Support async iterable DOM types

[MattiasBuelens]

Search Terms

asynciterator asynciterable async iterable iterator

Suggestion

Add a dom.asynciterable option to --lib to support DOM types that define a Symbol.asyncIterator method.

Use Cases

The streams spec has recently been updated to add a Symbol.asyncIterator method to ReadableStream, making it the first DOM type to implement the ES2018 AsyncIterable interface.

I would like to update the type definitions for streams in TSJS-lib-generator to include this new async iterator method. However, this requires Symbol.asyncIterator, which is not available before ES2018 and thus cannot be readily used in the DOM type definitions.

Previously, a dom.iterable option was added to support DOM types that define a Symbol.iterator method. I think it would make sense to use this same strategy to support Symbol.asyncIterator.

Examples

TypeScript would have (generated) type definitions in lib/lib.dom.asynciterable.d.ts:

interface ReadableStream<R = any> {
  [Symbol.asyncIterator](): AsyncIterator<R>;
}

Users could then use a ReadableStream in a for await..of loop by compiling with --target es2018:

const readable = new ReadableStream<Uint8Array>();
for await (const chunk of readable) {
  console.log(chunk);
}

Checklist

My suggestion meets these guidelines:

• This wouldn't be a breaking change in existing TypeScript/JavaScript code
• This wouldn't change the runtime behavior of existing JavaScript code
• This could be implemented without emitting different JS based on the types of the expressions
• This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, etc.)
• This feature would agree with the rest of TypeScript's Design Goals.

[espindola]

Hi, I just stumbled upon this. I noticed forEach was removed from ReadableStream in src/lib/dom.generated.d.ts in 4e237ed, but async iteration was not added. The ReadableStream in lib/lib.dom.d.ts still has a forEach and no async iteration.

Is there anything I can do to help?

[MattiasBuelens]

The forEach method was mistakenly added to the ReadableStream type definition. It never existed in the specification nor in any implementation. This was fixed in microsoft/TypeScript-DOM-lib-generator#1134, and should no longer be in lib.dom.d.ts. (Maybe double-check that you're on the latest version of TypeScript?)

At the moment, ReadableStream is not yet marked as an async iterable in TypeScript because it is not implemented by any browser, and thus it does not meet the criteria for being added to the DOM type definitions.

Is there anything I can do to help?

Not a whole lot. You can try to convince Chromium (#929585), Gecko (#1496770) and/or WebKit (#194379) to implement async iteration on ReadableStream, because we need at least two of them to implement it before we can add an official TypeScript type definition. 😅

[espindola]

The forEach method was mistakenly added to the ReadableStream type definition. It never existed in the specification nor in any implementation. This was fixed in microsoft/TypeScript-DOM-lib-generator#1134, and should no longer be in lib.dom.d.ts. (Maybe double-check that you're on the latest version of TypeScript?)

I have a current clone, but the last commit to change that file is from Jul 1, 2021 and forEach is still there:

https://github.com/microsoft/TypeScript/blob/main/lib/lib.dom.d.ts#L11924

At the moment, ReadableStream is not yet marked as an async iterable because it is not implemented by any browser, and thus it does not meet the criteria for being added to the DOM type definitions.

I guess that explains why deno has its own .d.ts :-)

Is there anything I can do to help?

Not a whole lot. You can try to convince Chromium (#929585), Gecko (#1496770) and/or WebKit (#194379) to implement async iteration on ReadableStream, because we need at least two of them to implement it before we can add an official TypeScript type definition. sweat_smile

I would be more likely to try to convince "TSC" of the value of having a deno mode :-)

Thanks for the explanation, the situation makes a lot more sense now.

[MattiasBuelens]

I have a current clone, but the last commit to change that file is from Jul 1, 2021 and forEach is still there:

https://github.com/microsoft/TypeScript/blob/main/lib/lib.dom.d.ts#L11924

Huh, strange. It looks like TypeScript's main branch is behind the latest v4.5.5 tag (committed on 12 November 2021). Not sure what's going on with that, you'd have to ask the TypeScript team. 😛

[dglazkov]

Yup, this just bit me. Have to do a weird thing like:

const stream = response.body as unknown as AsyncIterable<ConcreteType>;

Because fetch is already implemented in Node v18+, people stumbling over this will likely be more common.

[nickserv]

This is now supported in 4 runtimes (Firefox, Node, Deno, and Bun): https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream#browser_compatibility

Can we implement this please?

[saschanaz]

dom.asynciterable generation from the lib side is done in Sept 2022 (thanks Mattias!), we need to add a corresponding option from TypeScript side.

[jedwards1211]

@saschanaz @sandersn lib.dom.asynciterable.d.ts doesn't seem to many of the intended type defs. I'm confused how this would have been overlooked but in Mattias' PR it lacks the example he mentioned in OP and only contains:

interface FileSystemDirectoryHandle {
    [Symbol.asyncIterator](): AsyncIterableIterator<[string, FileSystemHandle]>;
    entries(): AsyncIterableIterator<[string, FileSystemHandle]>;
    keys(): AsyncIterableIterator<string>;
    values(): AsyncIterableIterator<FileSystemHandle>;
}

I can't find ReadableStream[Symbol.asyncIterator]() etc anywhere in TS 5.4.5. Can we reopen?

[saschanaz]

That's added later because of browser support state and should be added in a future TS version.

[jedwards1211]

@saschanaz as people have mentioned, this has been supported in many runtimes for over a year, so shouldn't we have a way to opt into these type defs already?

Adding ReadableStream[Symbol.asyncIterator]() in userland isn't hard, but AFAICT it's impossible to declaration merge ReadableStream.from into the type defs, which is painful

[saschanaz]

I mean asyncIterable support is already there, what we need is just a new TS release.

ReadableStream.from problem is real and it's still Firefox only. Opting in is not available as we don't have conditional types in TS 😞 and declaration merge is also blocked by web-interface-decls-not-being-class-decls 😭.

[MattiasBuelens]

As @saschanaz said, it's already in TypeScript Nightly. You can try it in the Playground.

[jedwards1211]

Okay my apologies, since parts of this had been done over a year ago I assumed it was being delayed past the next planned release to wait for more environments to catch up, glad to see it will be released soon.