TypeScript Reference ยท tsconfig: Type Checking Options
TypeScript strictBuiltinIteratorReturn option
Reference for strictBuiltinIteratorReturn: how built-in iterators such as Map.entries() type their return value as undefined instead of any, and how to handle done results.
An iterator's next() method returns either { done: false, value } or, when finished, { done: true, value: returnValue }. For iterators made by the language itself (arrays, Map, Set, strings, regular expression matches) the return value is always undefined. Before this option, the standard library typed that return value as any, which let you read a "finished" result as if it still held an element.
strictBuiltinIteratorReturn switches those built-in iterators to a precise return type of undefined. Calling next() by hand then gives you a union, IteratorResult<T, undefined>, and you must check done before using value. The option belongs to the strict family and was added in TypeScript 5.6.
const it = new Set([1, 2]).values(); const first = it.next(); // IteratorResult<number, undefined>
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.
Syntax
{ "compilerOptions": { "strictBuiltinIteratorReturn": true } }
| Part | Description |
|---|---|
| Value | true or false. Default: false, but true when strict is enabled. |
| Affected types | The built-in iterator types, such as ArrayIterator, MapIterator, SetIterator, StringIterator and RegExpStringIterator. They use the BuiltinIteratorReturn helper type. |
| With the option off | BuiltinIteratorReturn is any. |
| Typical error | The second example above stops with TS2488: Type '[string, number] | undefined' must have a '[Symbol.iterator]()' method that returns an iterator. because next().value might be the undefined return value. |
| With the option on | BuiltinIteratorReturn is undefined. |
Usage notes
for...ofand spread are unaffected. They already ignore the return value, so only hand-writtennext()calls see a difference.- The typical fix is to test
result.donefirst, or use a loop withfor...ofinstead of callingnext(). - Do not use
!just to silence the error oniterator.next().value; an empty collection really producesundefined. - Your own iterators and generators are not changed; their return type comes from your declaration, for example
Generator<number, string, void>. - Libraries that wrap iterators may need
skipLibCheckor an update if their.d.tsfiles assumedany. - Check inference on destructuring.
const [k, v] = it.next().valueis the pattern that most often starts failing after you turn the option on.
Related
strict,MapandSet,yield- Lessons: Iterators and generators, Strict mode