Skip to content
Tutorials Center
My learning

Topics

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.

TypeScript
const it = new Set([1, 2]).values();
const first = it.next(); // IteratorResult<number, undefined>

Try it

TypeScript Checking done before using value

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.

TypeScript Using the value without a check

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

JSON
{ "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...of and spread are unaffected. They already ignore the return value, so only hand-written next() calls see a difference.
  • The typical fix is to test result.done first, or use a loop with for...of instead of calling next().
  • Do not use ! just to silence the error on iterator.next().value; an empty collection really produces undefined.
  • 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 skipLibCheck or an update if their .d.ts files assumed any.
  • Check inference on destructuring. const [k, v] = it.next().value is the pattern that most often starts failing after you turn the option on.