Skip to content
Tutorials Center
My learning

Topics

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.

TypeScript
function count(items: Iterable<string>): number {
  let n = 0;
  for (const _ of items) n++;
  return n;
}

Try it

TypeScript Accepting any iterable

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 A custom iterable class

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
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...of needs a target of ES2015 or later (or downlevelIteration for 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 what next(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. Use ArrayLike<T> for index access and readonly 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.iterator is a well-known unique symbol, which is how computed method names stay typed.
  • Async. Use AsyncIterable<T> for streams of promises; for await also accepts sync iterables of promises.