Typing Asynchronous Generator Functions and Iterators in TypeScript
Introduction
Asynchronous generator functions (async generators) combine the power of async/await with generator-based iteration to produce streams of values over time. They appear in scenarios such as paginated API clients, streaming parsers, real-time event processing, and more. But their hybrid nature—yielding values asynchronously and supporting next/send semantics—makes them trickier to type correctly in TypeScript than plain functions, Promises, or synchronous generators.
In this comprehensive guide for intermediate TypeScript developers you'll learn how to model async generator functions and their iterators precisely, improving type safety, developer experience (DX), and long-term maintainability. We'll start with the language primitives, show patterns for common use cases (streams of homogeneous types, mixed-type yields, error handling, early completion, and backpressure), and dive into advanced typing techniques such as conditional types, variadic tuples, and custom type guards.
Practical, copy-paste-ready examples will show real code you can adapt. You will also learn how async generators interact with other TypeScript patterns—like union returns, Promise resolving types, literal inference, and custom type predicates—and how to avoid common pitfalls. Along the way we'll link to deeper reads on related topics like typing generator functions, promises, and type predicates so you can go further where needed.
By the end of this article you will be able to author and consume typed async generator APIs confidently, design ergonomic factories and helpers, and leverage advanced TypeScript features to express intent precisely while avoiding common runtime surprises.
Background & Context
Async generators are defined with async function* and return AsyncGenerator<TYield, TReturn, TNext>. They let you yield values asynchronously (await inside the generator) and produce an async iterator compatible with for await...of and manual next()/return()/throw() calls. Proper typing matters because callers rely on yielded value types and final return shapes; incorrect types lead to subtle runtime bugs or fragile APIs.
This topic sits at the intersection of multiple TypeScript areas. If you haven't already, it's useful to read up on typing synchronous generator functions and iterators to understand the base patterns before layering on async behavior. For more on that foundation, see our guide on typing generator functions and iterators. Async generators also interact with Promises and union-return patterns, so related material on typing promises that resolve with different types and functions with multiple return types will be useful references.
Key Takeaways
- Learn the AsyncGenerator<TYield, TReturn, TNext> type and its behavior.
- Understand typing strategies for homogeneous and mixed-yield streams.
- Use conditional types and inference to build ergonomic factory functions.
- Combine async generators with type predicates and safe runtime guards.
- Avoid common pitfalls like widening yields, wrong next() types, and unhelpful overloads.
Prerequisites & Setup
You should know TypeScript basics (generics, union types, mapped types) and have TypeScript 4.x+ installed. A code editor with IntelliSense (VS Code) is strongly recommended. Create a new project or use an existing one:
- npm init -y
- npm i -D typescript@latest
- npx tsc --init
Set target to es2018+ or esnext if you want top-level async iteration support:
{ "compilerOptions": { "target": "ES2018", "lib": ["ES2019", "DOM"], "module": "commonjs" } }Also ensure you understand how to type Promises and unions; our article on promises that resolve with different types complements this guide.
Main Tutorial Sections
1. Anatomy of AsyncGenerator<TYield, TReturn, TNext>
TypeScript models async generators with the AsyncGenerator interface: AsyncGenerator<TYield, TReturn, TNext>. Each type parameter has a role:
- TYield: type produced by yield
- TReturn: type returned when the generator completes (via return or implicit finish)
- TNext: type accepted as the value of the next() call (the value you send into the generator)
Example:
async function* numbers(): AsyncGenerator<number, void, undefined> {
yield 1;
}Often TYield and TReturn are the most important to model. When next() will accept meaningful values, model TNext explicitly. For more on generative typing details for synchronous generators, see typing generator functions and iterators.
2. Typing a Simple Async Generator (Homogeneous Stream)
A common use-case: streaming JSON records from an API:
async function* fetchPages(urls: string[]): AsyncGenerator<Record<string, any>, void, void> {
for (const url of urls) {
const r = await fetch(url);
const data = await r.json();
for (const item of data.items) yield item;
}
}To be safer, replace Record<string, any> with a specific interface or generic type:
type Item = { id: string; value: number };
async function* fetchItems(urls: string[]): AsyncGenerator<Item, void, void> { /* ... */ }If you return a final summary on completion, the return type changes:
async function* fetchItems(urls: string[]): AsyncGenerator<Item, { total: number }, void> { /* ... */ }3. Mixed Yields: Union Types and Discriminated Structures
Sometimes a stream yields different kinds of messages: data, heartbeat, error markers. Use discriminated unions for clarity:
type DataMsg = { type: 'data'; payload: Item };
type Heartbeat = { type: 'hb'; ts: number };
type StreamMsg = DataMsg | Heartbeat;
async function* stream(): AsyncGenerator<StreamMsg, void, void> { /* ... */ }When consumers need to narrow the type, prefer type predicates (custom type guards) over inline condition checks. See our guide on using type predicates for custom type guards for patterns you can apply to your stream messages.
4. Accepting Values via next(): Modeling TNext
Generators accept values via next(value). For async generators this is the TNext parameter. Example where consumers can send a control message:
type Control = { reset?: boolean };
async function* controlledCounter(): AsyncGenerator<number, void, Control | undefined> {
let n = 0;
while (true) {
const ctrl = yield n++;
if (ctrl?.reset) n = 0;
}
}Note: callers must pass values when calling next(). Properly typing TNext helps the consumer know what to send and improves DX.
5. Factories with Generic Yield and Return Types
Often you want a reusable async generator factory:
function makeRange(start: number, end: number) {
return async function* (): AsyncGenerator<number, void, void> {
for (let i = start; i <= end; i++) yield i;
};
}Make factories generic to preserve type inference across usage:
function makeStream<T>(items: T[]) {
return async function* (): AsyncGenerator<T, number, void> {
let count = 0;
for (const it of items) {
yield it;
count++;
}
return count;
};
}Preserving inference avoids forcing callers to repeat generic parameters. If you return multiple shapes or want narrow literal types, consider using as const at creation time to preserve literal inference.
6. Combining Async Generators with Promises and Awaiting Yields
Inside an async generator you can await arbitrary Promises and yield their resolved values. But typing can become awkward when yields are Promise-wrapped or when a yield might be a Promise result or an immediate value.
Prefer normalizing values inside the generator before yielding. Example:
async function* readAll(urls: string[]): AsyncGenerator<string, void, void> {
for (const url of urls) {
const res = await fetch(url);
const text = await res.text(); // normalize before yield
yield text;
}
}If you need to yield Promises intentionally, reflect that in TYield (e.g., Promise
7. Backpressure and Async Iteration Control
Consumers control async generators by choosing when to await next(). This allows natural backpressure. However, when bridging to callback sources (event emitters, sockets) you must buffer or provide cancellation.
A typical buffer pattern:
function eventsToAsyncGen<T>(subscribe: (cb: (v: T) => void) => () => void): AsyncGenerator<T, void, void> {
const q: T[] = [];
let resolve: ((v?: unknown) => void) | null = null;
subscribe((v) => {
q.push(v);
if (resolve) { resolve(); resolve = null; }
});
return (async function* () {
while (true) {
if (q.length === 0) await new Promise(res => (resolve = res));
while (q.length) yield q.shift() as T;
}
})();
}When wiring to Node-style event emitters, our article on typing event emitters in TypeScript contains tips for strongly-typed subscribe/emit APIs.
8. Streams with Mixed-Length Batches (Arrays and Tuples)
Sometimes an async generator yields arrays of mixed types (e.g., [header, payload]). When the structure is fixed, prefer tuples and preserve literals with as const:
const batch = ['meta', { id: 1 }] as const;
async function* batched(): AsyncGenerator<readonly [string, { id: number }], void, void> {
yield batch;
}For variable-length mixed-type arrays, type unions apply: AsyncGenerator<(string | number)[], void, void>. When consumers need to discriminate elements, consider the article on typing arrays of mixed types for patterns like type guards and helpers.
9. Interop with Async Iteration Consumers
Consumers use for await...of, manual next(), or helpers that transform async iterables (map, take). When exposing async generator types from libraries, document the TYield/TReturn/TNext intention and provide helper overloads or wrapper types for common operations. For example a map helper:
async function* map<T, U>(src: AsyncIterable<T>, fn: (t: T) => U | Promise<U>): AsyncGenerator<U, void, void> {
for await (const it of src) yield await fn(it);
}If you build libraries that chain operations, see our guide on typing libraries that use method chaining in TypeScript for ideas about preserving fluent generics across transforms.
10. Debugging and Runtime Guards
Because TypeScript types are erased at runtime, you should validate or guard unsafe external data before yielding. Combine runtime checks with type predicates to get type narrowing for consumers:
function isItem(v: any): v is Item { return v && typeof v.id === 'string' && typeof v.value === 'number'; }
async function* safeFetch(urls: string[]): AsyncGenerator<Item, void, void> {
for (const url of urls) {
const data = await fetch(url).then(r => r.json());
for (const raw of data.items) {
if (!isItem(raw)) continue;
yield raw;
}
}
}For patterns and deeper examples of writing custom type guards, see using type predicates for custom type guards.
Advanced Techniques
Once you are comfortable with basics, use advanced TypeScript features to improve ergonomics and inference:
- Conditional and infer to extract generator element types: type UnwrapAsyncGen
= G extends AsyncGenerator<infer Y, any, any> ? Y : never. - Variadic tuples to type factories that accept heterogeneous inputs and preserve exact tuple yields; combine with as const for literal preservation. Our guide on as const for literal type inference helps preserve literalness in tuples.
- Overload or factory functions that infer TYield from input payloads to avoid redundant generic parameters.
- Use mapped and distributive conditional types to transform AsyncIterable-of-something into another typed async iterable while preserving narrow types.
These techniques let you build ergonomic helpers (map, combineLatest, merge) that keep strong typing.
Best Practices & Common Pitfalls
Dos:
- Explicitly annotate AsyncGenerator types on public surfaces. Keep internal helpers less verbose when inference is obvious.
- Use discriminated unions for mixed-value streams.
- Normalize Promises inside the generator before yielding.
- Provide clear semantics for next() accepted values; document TNext.
Don'ts:
- Don’t yield heterogeneous plain any values—use unions or discriminated unions.
- Don’t rely on TypeScript to enforce runtime invariants—validate external data.
- Avoid wide types like unknown without narrowing; they push burden to callers.
Common pitfalls and fixes:
- Widening literals: use as const or explicit tuple types.
- Returning a non-matching return type: ensure the return type parameter matches the value passed to return() or implied by the completion value.
- Mis-typed next argument: explicitly set TNext to avoid accidental any.
For larger examples of typing strategies and dealing with union returns, see typing functions with multiple return types.
Real-World Applications
Async generators shine in pagination, event streaming, and incremental processing. Examples:
- Paginated API clients that yield items across pages and return a summary object when done.
- Streaming log processors that yield parsed log lines as they arrive and accept control messages via next().
- File parsers that yield tokens or records incrementally to reduce memory use.
You can also compose async generators into higher-level utilities, e.g., an async data-fetching hook in front-end apps. If you're building hooks around fetch streams, check our case study on typing a data fetching hook for patterns on generics, caching, and error handling.
Conclusion & Next Steps
Typing async generators accurately reduces bugs, improves DX, and makes your streaming APIs easier to use. Start by modeling TYield, TReturn, and TNext precisely, favor discriminated unions and type predicates for mixed streams, and normalize Promise results before yielding. Move on to advanced inference techniques to make factories ergonomic.
Next steps: review the linked deeper guides—especially the generator functions primer and the promises article—to solidify your foundations, then convert a few of your untyped streams to typed async generators to internalize patterns.
Enhanced FAQ
Q: What is the difference between AsyncIterator and AsyncGenerator in TypeScript?
A: AsyncIterator
Q: How do I type the value sent to next()? A: Set the third generic parameter TNext on AsyncGenerator<TYield, TReturn, TNext>. For example AsyncGenerator<number, void, { reset: boolean } | undefined> tells callers what next accepts. If you don’t plan to use next(value) semantics, use undefined or void.
Q: Should the yield type ever be a Promise
Q: How do I extract the yield type from an async generator type?
A: Use conditional types: type YieldOf
Q: Can TypeScript infer generic parameters for async generator factories? A: Yes—if you design your factory correctly. Return a function expression that is generic or let inference flow from the input. Use overloads or default generics when inference needs help. Using as const can preserve literal types for tuple yields, avoiding manual generic annotations—see as const.
Q: How do I validate external data before yielding? A: Use runtime checks with type predicates: write a function that returns v is T and run it before yield. This both protects runtime behavior and gives consumers narrow types. For techniques and best practices, see using type predicates for custom type guards.
Q: What about performance overhead of async generators? A: Async generators add async/await and Promise allocations, so they are not zero-cost. For I/O-bound streaming (e.g., network, file), overhead is usually negligible. For CPU-critical tight loops, a synchronous solution or batch yields might be faster. Measure with realistic workloads before optimizing.
Q: How do I test async generators? A: Use async test helpers and consume the generator with for await...of or manual next() calls. Test both happy paths and error scenarios (throw into generator with iterator.throw). When testing streams that interact with external services, stub or mock the source and assert yields and final return values.
Q: How does error propagation work with async generators? A: Throwing inside the generator rejects the Promise returned by next() or for-await iteration. Consumers can call iterator.throw(err) to inject exceptions into the generator. Document error strategies so consumers know how to recover or abort.
Q: Are there higher-level libraries to transform async iterables? A: Yes—many libraries provide map/filter/take/reduce for async iterables. If you build such utilities, preserve typing across transforms to maintain DX. For guidance on building typed chaining APIs, explore typing libraries that use method chaining in TypeScript.
Q: How do I handle mixed arrays and tuples in streams? A: Use tuples (readonly [A, B]) when the structure is fixed; use unions and type guards for variable structures. For deep-dive techniques and type-guard approaches, check typing arrays of mixed types.
Q: Can async generators return a value on completion and how is that typed? A: Yes—the second generic parameter TReturn models the return value. You return it via return(value) inside the generator or simply let the generator finish with an implicit return. Consumers using for await...of cannot directly receive the returned value—only manual iterator.return() consumers can access it through the Promise result of next() when done. For scenarios with multiple return shapes or conditional returns, see typing functions with multiple return types.
Q: How do async generators relate to Promises that resolve to different types? A: Both deal with asynchronous values, but async generators produce a sequence of values asynchronously, while a Promise resolves once. When yields might be heterogeneous or represent different async outcomes, patterns from typing promises that resolve with different types help choose between union-based Promise returns vs streaming via AsyncGenerator.
Q: Where should I go next after this guide? A: Review the linked foundational articles in this guide—especially our in-depth piece on typing generator functions and iterators, and try converting a few untyped stream utilities to typed async generators. For end-to-end examples, consider reading the case study on typing a data fetching hook to see how typed async iteration improves real code.