Skip to content
Tutorials Center
My learning

Topics

TypeScript Reference ยท Keywords and Declarations

TypeScript yield and function* generators

Reference for typing generator functions in TypeScript: Generator<Y, R, N>, yield, yield*, async generators, iterator protocols and common mistakes.

A generator function, written function*, produces values lazily with yield. Calling it does not run the body; it returns a generator object that you step through with next() or loop over with for...of. TypeScript describes that object with the built-in type Generator<Yield, Return, Next>.

The three type arguments are: the type of values you yield, the type of the final return value, and the type of values passed back in through next(value). Inference fills them in for you in most code. Async generators (async function*) work the same way but produce AsyncGenerator objects that you consume with for await.

TypeScript
function* count(): Generator<number, string, undefined> {
  yield 1;
  yield 2;
  return "done";
}

Try it

TypeScript Inferred generator types

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 Two-way communication and delegation

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

TypeScript
function* name(params): Generator<Y, R, N> { yield expr; return value; }
async function* name(params): AsyncGenerator<Y, R, N> { /* ... */ }
const received: N = yield value;   // value goes out, next(arg) comes in
yield* iterable;                   // delegate; its return value is the result
Parameter Description
Y (yield type) Union of all yield operands.
R (return type) Type of the return operand; void if none.
N (next type) Type of the argument accepted by next(). Unannotated generators infer unknown when the yield results are never used; annotate it when you pass values in.

Edge cases

  • next() returns IteratorResult<Y, R>: { done: false, value: Y } or { done: true, value: R }. Check done to narrow value.
  • The value passed to the first next() call is always discarded.
  • for...of and spread ignore the return value, so it never appears there.
  • Generators cannot be arrow functions; the * goes after function (or before a method name: *items() {}).

Usage notes

  • Return type annotations may also be Iterable<Y>, IterableIterator<Y> or Iterator<Y> when you do not care about the return or next types. The generator stays assignable to them.
  • Iterating requires a target of es2015 or newer, or downlevelIteration for older targets.
  • Typing yield results. If you read the result of a yield, annotate it (const x: number = yield ...) or give the function an explicit Generator<..., ..., number> return type. Under noImplicitAny, an unconstrained result can trigger error TS7057.
  • Lazy and finite. Generators are good for sequences you do not want in memory. Infinite ones need a consumer that stops.
  • yield* delegates to another generator or any iterable and evaluates to that generator's return value.
  • strictBuiltinIteratorReturn (part of strict since 5.6) makes built-in iterators report undefined as their return type instead of any.