TypeScript Generator Function

A generator function is a special class of function that can pause its execution context and yield multiple values over time, rather than computing and returning a single value synchronously. When invoked, it does not execute its body immediately; instead, it returns a Generator object that conforms to both the Iterable and Iterator protocols.

Syntax and Declaration

Generators are declared using the function* syntax. Inside the function body, the yield keyword is used to emit a value and suspend the function’s execution state.

function* simpleGenerator() {
    yield 1;
    yield 2;
}

TypeScript Typing

In TypeScript, the return type of a generator function is explicitly defined using the generic Generator<T, TReturn, TNext> interface.

T (Yield Type): The type of values emitted by the yield statements.
TReturn (Return Type): The type of the final value returned by the function when it completes (via the return statement). Defaults to void or any if omitted.
TNext (Next Type): The type of the value accepted by the next() method, which is injected back into the generator at the point of the suspended yield. Defaults to unknown.

function* typedGenerator(): Generator<string, number, boolean> {
    // Yields a string, expects a boolean to be passed into next()
    const injectedValue: boolean = yield "Step 1"; 
    
    // Yields another string
    yield `Step 2 received: ${injectedValue}`; 
    
    // Returns a number when done
    return 42; 
}

Execution Mechanics

Interacting with a generator involves calling the next() method on the instantiated Generator object. Each call to next() returns an IteratorResult object containing two properties:

value: The yielded or returned value.
done: A boolean indicating whether the generator has completed its execution.

const gen = typedGenerator();

// 1. Starts execution, pauses at the first yield.
// The argument to the first next() is always ignored.
const res1 = gen.next(); 
// res1: { value: "Step 1", done: false }

// 2. Resumes execution, injects `true` into `injectedValue`.
// Pauses at the second yield.
const res2 = gen.next(true); 
// res2: { value: "Step 2 received: true", done: false }

// 3. Resumes execution, hits the return statement.
const res3 = gen.next(false); 
// res3: { value: 42, done: true }

Delegation with `yield*`

A generator can delegate its yielding behavior to another generator or iterable object using the yield* expression. TypeScript infers the yielded types of the delegated iterable and merges them into the parent generator’s type signature.

function* subGenerator(): Generator<number, void, unknown> {
    yield 2;
    yield 3;
}

function* mainGenerator(): Generator<number, void, unknown> {
    yield 1;
    yield* subGenerator(); // Delegates execution to subGenerator
    yield 4;
}
// mainGenerator yields: 1, 2, 3, 4