[Web API type definition issue] Async `scroll...()` methods are non-async in fact

[turansky]

Summary

Scroll methods are non-async currently in latest browsers

Expected vs. Actual Behavior

Expected:

scroll(options?: ScrollToOptions): void;
scroll(x: number, y: number): void;
scrollBy(options?: ScrollToOptions): void;
scrollBy(x: number, y: number): void;
scrollIntoView(arg?: boolean | ScrollIntoViewOptions): void;
scrollTo(options?: ScrollToOptions): void;
scrollTo(x: number, y: number): void;

// or with optional async support

scroll(options?: ScrollToOptions): Promise<void> | void;
scroll(x: number, y: number): Promise<void> | void;
scrollBy(options?: ScrollToOptions): Promise<void> | void;
scrollBy(x: number, y: number): Promise<void> | void;
scrollIntoView(arg?: boolean | ScrollIntoViewOptions): Promise<void> | void;
scrollTo(options?: ScrollToOptions): Promise<void> | void;
scrollTo(x: number, y: number): Promise<void> | void;

Web Types 0.0.280

scroll(options?: ScrollToOptions): Promise<void>;
scroll(x: number, y: number): Promise<void>;
scrollBy(options?: ScrollToOptions): Promise<void>;
scrollBy(x: number, y: number): Promise<void>;
scrollIntoView(arg?: boolean | ScrollIntoViewOptions): Promise<void>;
scrollTo(options?: ScrollToOptions): Promise<void>;
scrollTo(x: number, y: number): Promise<void>;

Playground Link

No response

Browser Support

• This API is supported in at least two major browser engines (not two Chromium-based browsers).

Have Tried The Latest Releases

• This issue applies to the latest release of TypeScript.
• This issue applies to the latest release of @types/web.

Additional Context

Commit

MDN

https://developer.mozilla.org/en-US/docs/Web/API/Element/scroll
https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollBy
https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollIntoView
https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollTo

[jakebailey]

Yeah, I don't understand this. https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollTo

@saschanaz Do you know what happened here?

[saschanaz]

The spec is updated to be async, mdn update is not there yet.

[mmckenziedev]

@saschanaz Is this actually correct though? The actual implementation of scrollTo in a browser is that the method returns undefined and not a Promise. If someone were to treat the result of calling scrollTo as a Promise there would be a runtime error.

document.body instanceof Element; // true
document.body.scrollTo(1,1); // returns `undefined` not Promise

[saschanaz]

So, given the CSSWG agreement, I thought Blink would at least already have the implementation but CSSWG doesn't require implementations first before updating the spec, which causes the most frequent extra work here. At this point there's zero implementation that is actually shipped, even Blink is still experimenting in https://issues.chromium.org/issues/41406914, how come the spec is updated without any stable shipped implementation at all? 🙄

The second reason I accepted this change is that, in 2025 people should be using await that should automatically coerce non-promises too (await undefined does not cause a runtime error but is just no-op).

PR welcome though.