Description
Search Terms:
iterable return type
asynciterable return type
Related Issues:
#2983 - describes how the iterables types are not inferred correctly for generators. Fixing this current issue would be a step towards making that issue resolvable as well.
The Problem
The type definitions for iterable and asynciterable do not match the specification.
According to the specification, when IteratorResult
has done: true
, the value
is the return value of the iterator. This is not the same type as an element of the iterator. When implementing an iterator or async iterator "by hand", you get spurious type errors. For example:
const counter = (offset = 0, limit = 10) => {
let x = 0;
const a: AsyncIterator<number> = {
next: async () => {
if (x < 5) {
x++;
return { x, done: false };
}
return { done: true };
},
};
};
export default counter;
Gives errors:
src/testing/temp.ts:4:5 - error TS2322: Type '() => Promise<{ x: number; done: false; } | { done: true; x?: undefined; }>' is not assignable to type '(value?: any) => Promise<IteratorResult<number>>'.
Type 'Promise<{ x: number; done: false; } | { done: true; x?: undefined; }>' is not assignable to type 'Promise<IteratorResult<number>>'.
Type '{ x: number; done: false; } | { done: true; x?: undefined; }' is not assignable to type 'IteratorResult<number>'.
Property 'value' is missing in type '{ x: number; done: false; }' but required in type 'IteratorResult<number>'.
4 next: async () => {
~~~~
Thus, the types for iterables and async iterables should look more like this:
interface IteratorValueResult<T> {
done?: false;
value: T;
}
interface IteratorReturnResult<T = undefined> {
done: true;
value: T;
}
type IteratorResult<T, U = undefined> = IteratorValueResult<T> | IteratorReturnResult<U>;
interface Iterator<T, U = undefined> {
next(value?: any): IteratorResult<T, U>;
return?(value?: any): IteratorResult<T, U>;
throw?(e?: any): IteratorResult<T, U>;
}
interface Iterable<T, U = undefined> {
[Symbol.iterator](): Iterator<T, U>;
}
interface IterableIterator<T, U = undefined> extends Iterator<T, U> {
[Symbol.iterator](): IterableIterator<T, U>;
}
and
interface AsyncIterator<T, U = undefined, NextArg = undefined> {
// the type of the argument to next (if any) depends on the specific async iterator
next(value?: NextArg): Promise<IteratorResult<T, U>>;
// return should give an iterator result with done: true` and the passed value (if any) as the value
return?<R = undefined>(value: R): Promise<IteratorReturnResult<R>>;
// throw should return a rejected promise with the given argument as the error, or return an iterator result with done: true
throw?(e: any): Promise<IteratorReturnResult<undefined>>;
}
interface AsyncIterable<T, U = undefined, NextArg = undefined> {
[Symbol.asyncIterator](): AsyncIterator<T, U, NextArg>;
}
interface AsyncIterableIterator<T, U = undefined, NextArg = undefined> extends AsyncIterator<T, U> {
[Symbol.asyncIterator](): AsyncIterableIterator<T, U, NextArg>;
}
This should allow typescript to correctly infer that value
is not required when done: true
. For generators that do have a distinct return type from their yield type, they will be able to typecheck without spurious errors.
If the above definitions are acceptable to the maintainers I can prepare a PR to update the type definitions.
References
Activity
justjake commentedon Apr 12, 2019
I hit some runtime errors after following Typescript's iterable types.
At runtime, a call to
await iterable.next()
will return{ done: true, value: undefined }
for a complete
async * function
generator. However, the return type forasync * function
generator,AsyncIterableIterator<T>
, does not allow forvalue: undefined
.The return type of
await iterable.next()
should include| { done: true, value: undefined }
.Here's a demonstration of the issue:
https://github.com/justjake/ts-3.4.-async-iterable-issue
Here's a playground link, although this is less helpful because playground does not have the AsyncIterableIterator type (see also https://github.com/Microsoft/TypeScript/issues/23030#issuecomment-482692170)
https://www.typescriptlang.org/play/#src=async%20function*%20generate()%20%7B%0D%0A%20%20yield%201%0D%0A%20%20yield%202%0D%0A%20%20yield%203%0D%0A%7D%0D%0A%0D%0A%2F%2F%20AsyncIterableIterator%3C1%20%7C%202%20%7C%203%3E%0D%0Atype%20Out%20%3D%20ReturnType%3Ctypeof%20generate%3E%0D%0A%0D%0Aasync%20function%20consume()%20%7B%0D%0A%20%20const%20iterator%20%3D%20generate()%0D%0A%20%20const%20yield1%20%3D%20await%20iterator.next()%0D%0A%20%20const%20yield2%20%3D%20await%20iterator.next()%0D%0A%20%20const%20yield3%20%3D%20await%20iterator.next()%0D%0A%20%20const%20yield4%20%3D%20await%20iterator.next()%0D%0A%0D%0A%20%20%2F%2F%20IteratorResult%3C1%20%7C%202%20%7C%203%3E%0D%0A%20%20type%20ExpectedYield4Type%20%3D%20typeof%20yield4%0D%0A%20%20%2F%2F%20%201%20%7C%202%20%7C%203%0D%0A%20%20type%20ExpectedYield4ValueType%20%3D%20typeof%20yield4.value%0D%0A%0D%0A%20%20console.log('yield4'%2C%20yield4)%20%2F%2F%20%7B%20value%3A%20undefined%2C%20done%3A%20true%20%7D%0D%0A%20%20console.log('yiled4.value'%2C%20yield4.value)%20%2F%2F%20undefined%0D%0A%20%20if%20(yield4.value%20%3D%3D%3D%20undefined)%20%7B%0D%0A%20%20%20%20throw%20new%20Error('yield4.value%20type%20is%201%20%7C%202%20%7C%203%2C%20so%20value%20cannot%20be%20undefined')%0D%0A%20%20%7D%0D%0A%7D%0D%0A%0D%0Aconsume()
@RyanCavanaugh @rbuckton