TypeScript Reference ยท Primitive and Special Types
TypeScript Iterable and Iterator types
Reference for Iterable<T>, Iterator<T>, IterableIterator, Generator and AsyncIterable in TypeScript: typing for...of, spread, generators and custom iteration.
JavaScript has an iteration protocol: an object is iterable if it has a [Symbol.iterator]() method that returns an iterator, an object with a next() method that produces { value, done } results. for...of, spread ([...x]), destructuring, Array.from, new Map(entries) and Promise.all all consume iterables.
TypeScript models this with the interfaces Iterable<T>, Iterator<T> and IterableIterator<T>, plus Generator<T, TReturn, TNext> for generator functions and AsyncIterable<T> / AsyncIterator<T> for asynchronous iteration. Typing a parameter as Iterable<T> accepts arrays, sets, maps, strings and generators alike.
function count(items: Iterable<string>): number { let n = 0; for (const _ of items) n++; return n; }
Try it
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.
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
interface Iterable<T> { [Symbol.iterator](): Iterator<T>; } interface Iterator<T, TReturn = any, TNext = any> { next(...args: [] | [TNext]): IteratorResult<T, TReturn>; return?(value?: TReturn): IteratorResult<T, TReturn>; throw?(e?: any): IteratorResult<T, TReturn>; } interface IterableIterator<T> extends Iterator<T> { [Symbol.iterator](): IterableIterator<T>; }
| Type | Description |
|---|---|
Iterable<T> |
Has [Symbol.iterator](); usable in for...of and spread. |
Iterator<T> |
Has next() returning IteratorResult. |
IteratorResult<T, TReturn> |
{ done?: false; value: T } or { done: true; value: TReturn }. |
Generator<T, TReturn, TNext> |
What a function* returns: an iterator that is also iterable. |
AsyncIterable<T>, AsyncGenerator<T> |
Same ideas for for await...of and async function*. |
Edge cases:
- Iterating a non-array iterable with
for...ofneeds atargetof ES2015 or later (ordownlevelIterationfor older targets). - Newer lib typings add
IteratorObject<T>and iterator helper methods (map,filter,take,toArray) on iterators produced by arrays, sets, maps and generators in recent ES versions. Generator<T, TReturn, TNext>has three type parameters: values yielded, the final return value, and whatnext(x)can send in.- Plain objects are not iterable; use
Object.entries(obj).
Usage notes
- Prefer
Iterable<T>for parameters that only loop once; it accepts the widest set of inputs. UseArrayLike<T>for index access andreadonly T[]when you need random access. - Iterators are single use. A generator or
map.values()is exhausted after one pass; iterating twice gives nothing the second time. - Lazy evaluation. Generators compute on demand, which suits large or infinite sequences when combined with a
break. implements Iterable<T>makes the compiler check your[Symbol.iterator]method.- Symbol typing.
Symbol.iteratoris a well-knownunique symbol, which is how computed method names stay typed. - Async. Use
AsyncIterable<T>for streams of promises;for awaitalso accepts sync iterables of promises.