[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.

[mmckenziedev]

Sure, people can use await or void which eliminates the return type problem, but it shouldn't be a requirement at this point given the lack of real-world implementations. This is basically a breaking change, which is surprising since most spec changes have tried very hard to not break existing interfaces. Oh well.

[saschanaz]

I don't see how it breaks existing code?

[saschanaz]

So it's technically true that the type doesn't reflect the reality, regardless of whether it's breaking or not.

@Bashamega would you like to try this one? Basically partially reverting the changes #2196 but with patches.

[jakebailey]

If the browsers are going to change this, and TS 6.0 is going to come out in a few months, and one nearly always would not have observed void, does anything even need to happen?

[saschanaz]

w3c/csswg-drafts#12355 had Mozilla support (from Emilio), but we don't know when the changes are going to actually happen.

[Bashamega]

So it's technically true that the type doesn't reflect the reality, regardless of whether it's breaking or not.

@Bashamega would you like to try this one? Basically partially reverting the changes #2196 but with patches.

Sure @saschanaz
Thank you for mentioning me