Improve Iterator Helper Type Signatures

⚙ Compilation target

ESNext

⚙ Library

esnext.iterator.d.ts

Missing / Incorrect Definition

• Iterator.from(value: Iterator) - PR #59927
  • value iterator argument with TNext other than undefined should be accepted; this is a bad idea; my mistake
  • Since IteratorObject instances (objects whose prototype is Iterator.prototype) are not wrapped by Iterator.from, we could add an Iterator.from overload to represent those cases and pass through all generic type parameters: from<T, TReturn = any, TNext = any>(value: IteratorObject<T, TReturn, TNext>): IteratorObject<T, TReturn, TNext>;
  • TReturn type should be passed through from the argument to the return type
• Iterator helper intermediate operators (filter, map etc) do not propagate the return value of their source iterator and should have TReturn set to undefined
  • This is already the case in the current declarations
• Iterator objects returned from Iterator.from and the other built-in iterators returned from Array.values etc always have a return method (built-in iterators returned from Array.values etc also always have a throw method) thanks to @bakkot for the clarification
  • There is no way that I am aware of to express this behavior in TypeScript with the current definition of IteratorObject without also forcing user-defined classes extending from the javascript Iterator class to also implement the return method, which would be wrong. The impact on client code is minimal as the Iterator object's return method can always be called safely using the return!() notation.

Sample Code

https://github.com/nikolaybotev/iteratorhelpersdemo

Documentation Link

https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Iterator

and

https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols