Skip to content
Tutorials Center
My learning

Topics

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.

JavaScript
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

JS Pipelines over an infinite sequence

Press Run (or Ctrl + Enter) to see the console output here.

No output.

JS Laziness and Iterator.from()

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() or next() 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() or break); toArray() or reduce() on one never finishes.
  • Early exit cleans up. take() and short-circuiting methods call the source's return(), so finally blocks in generators run.
  • Arrays are not iterators. [1, 2, 3].map(...) is the array method. To use helpers on an array, write array.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.