Regression of disposable async iterators (#59633)

[james-pre]

⚙ Compilation target

N/A

⚙ Library

ESNext, Typescript 5.7.2

Missing / Incorrect Definition

AsyncIterator is missing a [Symbol.asyncDispose] property. I found this after investigating a type error I got while creating a polyfill of node:fs's ReadStream. You can follow the rabbit hole here: DefinitelyTyped/DefinitelyTyped#71307.

At the end, I discovered that AsyncIteratorObject has the [Symbol.asyncDispose] property (from #59633) and since AsyncIterator doesn't extend AsyncIteratorObject, it is missing the property. In fact, AsyncIteratorObject extends AsyncIterator.

Sample Code

declare const it: AsyncIterator<any>;

it[Symbol.asyncDispose](); // <-- error!

Error:

Element implicitly has an 'any' type because expression of type 'unique symbol' can't be used to index type 'AsyncIterator<any, any, any>'.
  Property '[SymbolConstructor.asyncDispose]' does not exist on type 'AsyncIterator<any, any, any>'.ts(7053)

Documentation Link

I wasn't able to independently find anything in the ECMAScript specification or on MDN, so the only reference I have is #59633

Fix

This can be fixed by having AsyncIterator extend AsyncDisposable.

[Jamesernator]

At the end, I discovered that AsyncIteratorObject has the [Symbol.asyncDispose] property (from #59633) and since AsyncIterator doesn't extend AsyncIteratorObject, it is missing the property. In fact, AsyncIteratorObject extends AsyncIterator.

The AsyncIterator type doesn't refer to the builtin object of the same name because TypeScript already used it for the async iterator protocol where it already perfectly legal to have an async iterator that doesn't have [Symbol.asyncDispose].

The new AsyncIteratorObject is the builtin AsyncIterator object (i.e. the one on the prototype of async generators). That is what you should use in your example:

declare const it: AsyncIteratorObject<any>;

it[Symbol.asyncDispose](); 

---

declare class Broken implements AsyncItWithNode {
  it: AsyncIterableIterator<any>; // <-- error!
}

The error you are getting in the linked discussion is expected, an arbitrary async iterator doesn't have [Symbol.asyncDispose]. Only those that actually extend the builtin AsyncIterator object, or those that implement it themselves, do.

---

Also general warning, currently v8/Node doesn't actually implement Symbol.asyncDispose on the builtin AsyncIterator object yet anyway, if you need this functionality you should polyfill it.

[james-pre]

Great, thanks. I'll look into resolving the issue on @types/node.