TypeScript Async Generator Method

An asynchronous generator method is a class or object literal member prefixed with both async and *. It combines the pause-and-resume execution model of generators with the non-blocking, promise-based resolution of asynchronous functions. When invoked, it does not execute its body immediately; instead, it returns an AsyncGenerator object. The generator yields values of type TYield, and it is the .next() method of the resulting iterator that returns a Promise<IteratorResult<TYield>>.

TypeScript Signatures and Typing

In TypeScript, the return type of an async generator method is strictly typed using the built-in AsyncGenerator<TYield, TReturn, TNext> interface:

TYield: The type of the values yielded by the method.
TReturn: The type of the value returned when the generator completes (defaults to void or any).
TNext: The type of the value accepted by the next() method (defaults to unknown).

Alternatively, you can type the return signature using AsyncIterable<TYield> or AsyncIterableIterator<TYield> if you do not need to strictly type the return or next values.

class StreamHandler {
    // Explicitly typing Yield, Return, and Next types
    public async *extractData(): AsyncGenerator<Uint8Array, number, string> {
        // 'command' is typed as 'string' based on TNext
        const command: string = yield new Uint8Array([1, 2, 3]);
        
        if (command === "STOP") {
            return 0; // Typed as 'number' based on TReturn
        }
        
        yield new Uint8Array([4, 5, 6]);
        return 1;
    }
}

// Object literal syntax
const asyncIterableObj = {
    async *generateSequence(): AsyncIterableIterator<number> {
        yield await Promise.resolve(10);
        yield await Promise.resolve(20);
    }
};

Execution Mechanics

Initialization: Calling the method instantiates the AsyncGenerator. No code inside the method executes until .next() is called.
Promise Resolution: Every yield expression pauses execution. The yielded value is automatically wrapped in a Promise if it is not already one.
IteratorResult: The .next() method returns a Promise that resolves to an IteratorResult object containing two properties:
- value: The yielded or returned value.
- done: A boolean indicating whether the generator has completed (true on return, false on yield).

const handler = new StreamHandler();
const generator = handler.extractData();

// Manual iteration mechanics
generator.next().then(result => {
    console.log(result); // { value: Uint8Array(3) [1, 2, 3], done: false }
    
    // Passing TNext back into the generator
    return generator.next("STOP"); 
}).then(result => {
    console.log(result); // { value: 0, done: true }
});

Delegation with `yield*`

An async generator method can delegate its execution to another AsyncIterable, Iterable, or generator using the yield* expression. TypeScript enforces that the delegated iterable’s yield type is compatible with the parent method’s TYield type.

class CompositeGenerator {
    private async *subRoutine(): AsyncGenerator<string, void, unknown> {
        yield "sub-yield-1";
        yield "sub-yield-2";
    }

    public async *mainRoutine(): AsyncGenerator<string, void, unknown> {
        yield "main-yield-1";
        // Delegates iteration to subRoutine
        yield* this.subRoutine(); 
        yield "main-yield-2";
    }
}

Consumption via `for await...of`

While manual .next() calls expose the underlying Promise mechanics, async generator methods are natively designed to be consumed by the for await...of statement. This construct implicitly awaits each Promise and extracts the value from the IteratorResult, automatically terminating when done: true is encountered.

async function consume(handler: CompositeGenerator) {
    // TypeScript infers 'item' as 'string' based on TYield
    for await (const item of handler.mainRoutine()) {
        console.log(item);
    }
}

Tired of Poor TypeScript Skills? Fix That With Deep Grasping!Learn More

Methods

Functions

Constructors

Classes

Generics

Type Definitions

Decorators

Accessors

Fields

Variables

Parameters

Modules

Namespaces

Enums

Destructuring

Error Handling

Control Flow

Loops

Built-In Object Types

Primitive & Special Types

Comments & Directives

Type Operators

Access Operators

Conditional & Sequence Operators

Logical Operators

Comparison Operators

Unary Operators

Assignment Operators

Arithmetic Operators

Bitwise Operators

TypeScript Async Generator Method

TypeScript Signatures and Typing

Execution Mechanics

Delegation with `yield*`

Consumption via `for await...of`

​TypeScript Signatures and Typing

​Execution Mechanics

​Delegation with yield*

​Consumption via for await...of

TypeScript Signatures and Typing

Execution Mechanics

Delegation with `yield*`

Consumption via `for await...of`