IteratorResult<T> definition conflicts with the JS spec

TypeScript Version: 3.8.3

Search Terms: iterator return type

Code

const list = ['v1', 'v2', 'v3']

const f: () => Iterator<string> = () => {
  let index = 0
  return {
    next: (): IteratorResult<string> => {
      console.log(list)
      if (index < list.length) {
        return { value: list[index++]}
      } else {
        return { done: true }
      }
    }
  }
}

Expected behavior: The code should compile without errors. Actual behavior: The code compiles with the error: “Type ‘{ done: true; }’ is not assignable to type ‘IteratorResult<string, any>’. Property ‘value’ is missing in type ‘{ done: true; }’ but required in type ‘IteratorReturnResult<any>’.(2322)”

The error can be bypassed by changing { done: true } to { value: undefined, done: true }. However, the specification allows omitting the value property. See Iteration Protocols

A suggested fix would be to change the definition of the type IteratorReturnResult to:

interface IteratorReturnResult<TReturn> {
    done: true;
    value?: TReturn;
}

Playground Link: https://www.typescriptlang.org/play?#code/MYewdgzgLgBANgS2jAvDA2gcgG4EZMA0MOATIcdgMyYC6AUHaJLAGYBcMAFAJSoB8MAJJQApgCcAhlBBiAPNDEIwAcwFoe-GAG86MeCNhKAJiIAeqGAAZdMMQYCuYsNpt6wZqBx4dh4qTIAlEQh7OCh5KEUVNQEdPXiYJggQOBEAOjgQZU5EaG5XeIQWLmMzGFl4JCgMkRUoAAteOIT4uyhHZy0YbAk4exEOXKh0UtMAajGaAF8CvSmYETgIERcW1ocnbRgjcAGYSP6YGbXj+NOZqaA

Related Issues: #29982

[zaach]

fwiw I ran into this in practice when attempting to use a ReadableStream as an async interator. E.g. this example from Jake Archibald’s article doesn’t type correctly:

function streamAsyncIterator(stream) {
  // Get a lock on the stream:
  const reader = stream.getReader();

  return {
    next() {
      // Stream reads already resolve with {done, value}, so
      // we can just call read:
      return reader.read();
    },
    return() {
      // Release the lock if the iterator terminates.
      reader.releaseLock();
      return {};
    },
    // for-await calls this on whatever it's passed, so
    // iterators tend to return themselves.
    [Symbol.asyncIterator]() {
      return this;
    }
  };
}

[rbuckton]

To reiterate, the problem is that, as written, IteratorReturnResult conflicts with the Iterator spec. @fatcerberus and I have suggested fixes. The argument against fixing it, so far, seems to be that it would make it less convenient to use, by requiring an undefined check. Two points:

1. The definition of the Iterator spec is what’s driving the need for an ‘undefined’ check. I understand that one may wish it didn’t, but that’s a complaint about the spec itself. It doesn’t work to have a type that reflects how we wish the spec to be and not how it actually is.

I agree that value should be allowed to be removed when done is true, but only when the iterator is typed as IteratorResult<T, void>, which is why I’m investigating treating a property of type void as optional. However if your result is typed IteratorResult<T, number>, then the only correct type for the return result is { done: true, value: number }. Making value optional for that case would remove type safety. However, if we allow properties of type void to be optional as we do for parameters, then { done: true } would be assignable to { done: true, value: void }.

1. The inconvenience of checking for undefined seems extremely minor, especially considering the optional chaining and non-null assertion operators. Moreover, and this bears repeating, the Iterator spec is defined in a way that makes the ‘undefined’ check unavoidable.

We made it such that calling generator.return() also requires a value if your generator is typed with a non-void return value, which ensures type safety. The only way I can see to accurately address this issue is to allow void properties to be considered optional.