Iterator helpers

Array-style helpers for iterators

An iterator is an object that gives you values one at a time. Each time you call its next() method, you get the next value. Generators give you iterators, and so do methods such as entries() on a Map or a Set.

Iterator helpers are methods you can call on an iterator. Many have the same names as array methods, such as map and filter. If you know map, filter, and reduce on arrays, the names will look familiar.

The big difference is when the work happens. An array method is eager: it does its work right away, on every item. Most iterator helpers are lazy: they do no work until someone asks for the next value. Asking an iterator for its next value is called pulling a value.

These are the standard helpers this lesson covers:

• Iterator.from gives you an iterator that has the helpers.
• map, filter, take, drop, and flatMap give back a new iterator. They wait.
• toArray, reduce, forEach, some, every, and find pull the values out and give back a result.

They work in current browsers and in Node 22. Older browsers may not have them, so code for those browsers should check first.

An iterator is any object with a next() method. Each call to next() returns a small object shaped like { value, done }. The value part is the next value. The done part is true when there are no more values.

An object you write by hand with only a next() method does not get the helpers. It has no map and no toArray. The fix is Iterator.from(value). It gives back an iterator that pulls from your object and also has every helper.

1const handRolled = {2  current: 0,3  next() {4    this.current += 1;5    return this.current <= 36      ? { value: this.current, done: false }7      : { value: undefined, done: true };8  },9};10 11const result = Iterator.from(handRolled)12  .map(n => n * 10)13  .toArray();14 15console.log(result);

It prints [10, 20, 30]. Line by line:

1. Lines 1–9 make handRolled. It gives 1, 2, 3, then says done: true. It has only next().
2. Line 11 passes it to Iterator.from, which gives back an iterator with the helpers.
3. Line 12 multiplies each value by 10.
4. Line 13 calls toArray(), which pulls every value and puts them in an array.

You can do the same with any object that gives values through next(), such as a reader you wrote for your own data.

1const prices = new Map([2  ["tea", 3],3  ["bread", 4],4  ["rice", 8],5]);6 7const labels = Iterator.from(prices.entries())8  .map(([name, price]) => name + ":" + price)9  .toArray();10 11console.log(labels.join(", "));

prices.entries() already returns an iterator. Each value it gives is a [name, price] pair. Built-in iterators like this one already have the helpers, so Iterator.from just hands the same iterator back.

1. Line 8 turns one pair at a time into text like "tea:3".
2. Line 9 calls toArray() to collect the results.
3. Line 11 prints tea:3, bread:4, rice:8.

No extra array of pairs is made along the way.

A generator is a function that makes values one at a time, only when asked. Calling a generator gives you an iterator, so you can use the helpers on it straight away. The generator below counts up forever and gives out only the even numbers.

1function* evenNumbers() {2  let value = 0;3  while (true) {4    if (value % 2 === 0) yield value;5    value += 1;6  }7}8 9const firstThree = evenNumbers().take(3).toArray();10console.log(firstThree);

Line 9 asks for only three values, so it gets [0, 2, 4]. After the third value, take(3) stops pulling, and the endless loop is never asked again. Without take(3), toArray() would wait forever, because this generator never says done: true.

The tool below runs a longer chain. A function you pass to a helper, like n => n * 2, is called a callback. Each part of the chain logs a line when it runs:

• pull means the source gave one value.
• map means the map callback ran on that value.
• filter means the filter callback checked the result.

1function* numbers() {2  for (const value of [1, 2, 3, 4, 5, 6]) {3    console.log("pull " + value);4    yield value;5  }6}7 8const result = numbers()9  .map(n => { console.log("map " + n); return n * 2; })10  .filter(n => { console.log("filter " + n); return n % 3 !== 0; })11  .take(3)12  .toArray();13 14console.log(result.join(", "));

Switch to the array version. The result is still 2, 4, 8, but the log changes:

• The array chain runs map on all six numbers. Only then does filter start.
• The iterator chain pulls one value, maps it, and filters it. Then it pulls the next one.
• The iterator chain stops after the fourth value, because three values have passed the filter by then.

1function* numbers() {2  for (const value of [1, 2, 3, 4, 5, 6]) {3    console.log("pull " + value);4    yield value;5  }6}7 8const result = numbers()Run9  .map(n => { console.log("map " + n); return n * 2; })10  .filter(n => { console.log("filter " + n); return n % 3 !== 0; })11  .take(3)12  .toArray();13 14console.log(result.join(", "));

map, filter, take, drop and flatMap

These five helpers each give back a new iterator. Nothing happens until something pulls from it. The table also lists the consuming helpers from the next section, so you can compare them. Read each row as: the helper, whether it waits to be asked, what it gives back, and what it is for.

• map(callback) changes each value it pulls.
• filter(callback) keeps a value when the callback returns a truthy value, which is a value that counts as true.
• take(n) lets the first n values through, then stops.
• drop(n) skips the first n values and lets the rest through.

take and drop check their number. A negative number or NaN throws a RangeError, which is an error for a number outside the allowed range. They do not quietly guess what you meant.

flatMap is for when one value should become several values, or none. Its callback returns something you can loop over, like an array. The helper then gives out each item inside it, one by one.

1const baskets = [["tea", "bread"], ["rice"]];2const items = Iterator.from(baskets)3  .flatMap(basket => basket)4  .toArray();5 6console.log(items.join(", "));

Each basket is an array, so flatMap can loop over it. It gives out tea, then bread, then rice, and line 6 prints tea, bread, rice. If the callback returned a number instead, flatMap would throw a TypeError, because you can't loop over a number.

You can use flatMap to split lines into words, to turn one calendar day into its events, or to turn one page of results into single rows.

An iterator remembers where it is. Once it gives out a value, it never gives that value again. An iterator that can be used only once like this is called one-shot.

1const iterator = Iterator.from([1, 2, 3]);2console.log(iterator.take(2).toArray());3console.log(iterator.toArray());

Line 2 prints [1, 2]. Line 3 prints [3], because line 2 already pulled 1 and 2 from the same iterator. To go through the values again, keep the original array, or make a fresh iterator.

Some sources keep something open, such as a file or a database connection. They can have a return() method that cleans up. When a helper stops early, it calls that method on the source.

1function makeReader(log) {2  let value = 1;3  return {4    next() {5      return { value: value++, done: false };6    },7    return() {8      log.push("closed");9      return { value: undefined, done: true };10    },11    [Symbol.iterator]() { return this; },12  };13}14 15const log = [];16const values = Iterator.from(makeReader(log)).take(2).toArray();17console.log(values);18console.log(log);

The reader on lines 1–13 counts 1, 2, 3, and so on forever. Its return() method on lines 7–10 adds "closed" to the log. When take(2) has its two values, it calls return() before the chain finishes. So line 17 prints [1, 2] and line 18 prints ["closed"]. A real source can close its file or connection at that moment.

some, every, find, reduce, forEach and toArray

Consuming helpers pull values out of the chain. They give back a final result, not another iterator.

• toArray() puts every remaining value into an array.
• reduce(callback, initial) combines every remaining value into one value, starting from initial.
• forEach(callback) calls the callback for each value, for example to log it. It returns undefined.
• some, every, and find stop as soon as they know the answer.

1let checks = 0;2const firstOdd = Iterator.from([2, 4, 7, 8]).find(value => {3  checks += 1;4  return value % 2 === 1;5});6 7console.log(firstOdd + ":" + checks);

find checks 2, then 4, then 7. 7 is odd, so it stops there. Line 7 prints 7:3: the value found, then the number of checks. The callback never sees 8.

Stopping early helps most with long or endless sources:

• find stops at the first value that matches.
• some stops at the first value where the callback returns a truthy value.
• every stops at the first value where the callback returns a falsy value, one that counts as false.

On an endless source, use these only when the answer will come at some point. Otherwise they keep checking forever.

Pick a source, turn helpers on or off, then pick a consuming helper. The infinite counter counts 1, 2, 3, and so on forever. The playground refuses any chain that would pull from it forever. Real code needs the same care with endless sources.

1function* counter() {2  let value = 1;3  while (true) yield value++;4}5 6const result = Iterator.from(source)7  .drop(1)8  .map(n => n * 2)9  .filter(n => n % 3 !== 0)10  .take(6)11  .toArray();

An array, a Set, a generator, and the endless counter all use the same helpers. Each of them gives an iterator, and the helpers work on any iterator.

New JavaScript features are planned by a group called TC39. Each planned feature is called a proposal. A proposal moves through numbered stages, and stage 4 means finished. At the time of writing, TC39 lists these as finished:

• Iterator helpers: the standard helpers in this lesson.
• Joint Iteration: Iterator.zip and Iterator.zipKeyed, which pair up values from several iterators by position.
• Iterator Sequencing: Iterator.concat, which joins several iterators one after another.

Finished does not mean every browser or Node version has it yet. Node 22 has the standard helpers, but not Iterator.concat, Iterator.zip, or Iterator.zipKeyed. So check that a newer helper exists before you use it. This check is called feature detection.

1// At the time of writing, Node 22 does not expose these yet.2// Feature-detect before using them in production code.3const canConcat = typeof Iterator.concat === "function";4const canZip = typeof Iterator.zip === "function";5const canZipKeyed = typeof Iterator.zipKeyed === "function";6 7console.log({ canConcat, canZip, canZipKeyed });

Lines 3–5 use typeof, which gives the type of a value as text. A method that exists gives "function". In Node 22, all three checks are false.

TC39 also lists three ideas at stage 3, one step before finished:

• Iterator chunking: splitting values into groups, called chunks, or into sliding windows.
• Iterator Includes: checking whether an iterator gives a certain value.
• Iterator Join: joining the values into one string.

Until the places your code runs have these, write a small generator yourself or use a library. Make it clear that it is your own code, not standard JavaScript.

1function* chunks(iterable, size) {2  let chunk = [];3  for (const value of iterable) {4    chunk.push(value);5    if (chunk.length === size) {6      yield chunk;7      chunk = [];8    }9  }10  if (chunk.length) yield chunk;11}

1. Line 1 starts a generator that takes anything you can loop over, plus a group size.
2. Lines 3–4 add each value to the current group, called chunk.
3. When the group reaches size items, line 6 gives it out and line 7 starts a new one.
4. Line 10 gives out the last, shorter group, if there is one.

1// At the time of writing, Node 22 does not expose these yet.2// Feature-detect before using them in production code.3const canConcat = typeof Iterator.concat === "function";4const canZip = typeof Iterator.zip === "function";5const canZipKeyed = typeof Iterator.zipKeyed === "function";6 7console.log({ canConcat, canZip, canZipKeyed });

1function* chunks(iterable, size) {2  let chunk = [];3  for (const value of iterable) {4    chunk.push(value);5    if (chunk.length === size) {6      yield chunk;7      chunk = [];8    }9  }10  if (chunk.length) yield chunk;11}

Where you'll use this

Iterator helpers help when the source is not a small array, or when stopping early saves work. For example:

• reading lines from a big log file,
• making IDs one at a time,
• loading results one page at a time,
• reading rows from a local database.

They also keep a chain easy to read without making a new array at every step.

Eager is not bad. If you already have a small array and need every value, array methods are often clearer. Use lazy helpers when you want to stop early, save memory, or work with an endless source.

Common misconceptions

• “map runs right away.” Iterator map gives back a new iterator and waits. A consuming helper pulls the values.
• “Iterators go back to the start, like arrays.” Most iterators are one-shot. A value that was pulled is gone.
• “take(-1) means take none.” A negative count throws a RangeError.
• “toArray is always safe.” On an endless source, it never finishes. Add take first, or use find or some.
• “A finished proposal works everywhere today.” Some places don't have it yet. Check for newer names such as Iterator.zip first.
• “Lazy is always faster.” Sorting, grouping, and adding up every value still need all the values.

The table compares the two styles. Read each row as a question, then the answer for iterator helpers and for array methods.

Key takeaways

• Iterator.from gives the helpers to an object that only has next().
• map, filter, take, drop, and flatMap are lazy. They give back a new iterator and wait.
• toArray, reduce, forEach, some, every, and find pull the remaining values and give back a result.
• An iterator does not go back to the start. Make a fresh one if you need the values again.
• Check that newer helpers, such as Iterator.zip, exist before you use them.

Iterator helpers are methods for iterators. Most of them wait, and work on one value at a time, only when a value is pulled.

Up next: Async iteration & async generators.