JavaScript Reference ยท Iterators, Generators and Symbols
Iterator helpers
Reference for JavaScript iterator helpers: Iterator.from(), map, filter, take, drop, flatMap, toArray and more, evaluated lazily over any iterator.
Iterator helpers add array-style methods to iterators: map(), filter(), take(), drop(), flatMap(), reduce(), toArray() and others. Unlike array methods, the lazy ones (map, filter, take, drop, flatMap) do not build intermediate arrays. They return a new iterator that pulls one value at a time from the source, so they work on infinite sequences and stop as soon as the answer is known.
The methods live on Iterator.prototype, which every built-in iterator and generator object inherits from. Use Iterator.from() to wrap any iterable or iterator-like object.
function* naturals() { let n = 1; while (true) yield n++; } naturals().filter((n) => n % 2 === 0).map((n) => n * n).take(3).toArray(); // [4, 16, 36]
Try it
Press Run (or Ctrl + Enter) to see the console output here.
No output.
Press Run (or Ctrl + Enter) to see the console output here.
No output.
Methods
| Method | Lazy? | Description |
|---|---|---|
map(fn) |
yes | Transforms each value. fn(value, index). |
filter(fn) |
yes | Keeps values for which fn(value, index) is truthy. |
take(n) |
yes | Yields at most the first n values, then closes the source. |
drop(n) |
yes | Skips the first n values. |
flatMap(fn) |
yes | Maps each value to an iterable (not a plain string) and flattens one level. |
reduce(fn, initial) |
no | Folds the values into one result. |
toArray() |
no | Collects every value into an array. |
forEach(fn) |
no | Calls fn(value, index) for each value; returns undefined. |
some(fn), every(fn), find(fn) |
no | Short-circuit as soon as the answer is known. |
Iterator.from(x) |
n/a | Static method that turns an iterable or iterator into one that inherits these methods. |
Return value: lazy methods return a new iterator helper object; the others return an array, a single value or undefined.
Exceptions: passing a non-function callback, or a negative or NaN count to take() or drop(), throws a TypeError or RangeError.
Usage notes
- Order of work. With a pipeline, each value goes through every stage before the next value is pulled, as the "pulling" log shows.
- Nothing runs until you consume it. Creating a pipeline pulls nothing;
toArray(),for...of,reduce()ornext()starts the work. - One-shot. An iterator is consumed as you read it. Calling
toArray()twice on the same iterator gives a second empty result. - Infinite sources need a limit (
take(),find(),some()orbreak);toArray()orreduce()on one never finishes. - Early exit cleans up.
take()and short-circuiting methods call the source'sreturn(), sofinallyblocks in generators run. - Arrays are not iterators.
[1, 2, 3].map(...)is the array method. To use helpers on an array, writearray.values().map(...). flatMap()rejects strings returned from the callback; split them into an iterable first.- Versus array methods: helpers avoid temporary arrays and allow infinite or huge sequences, but arrays remain simpler for small, finite data.
- Not related to async iteration. Async iterator helpers are a separate, later proposal.
Browser support
Iterator helpers are recent. Current versions of the major browsers and recent Node.js releases support them, but older environments do not, so check a compatibility table and consider a fallback before using them in production.