#Iterator Sequencing S4

#Iterator Sequencing

A TC39 proposal to create iterators by sequencing existing iterators.

Stage: 4

Specification: https://tc39.es/proposal-iterator-sequencing/

#presentations to committee

• November 2025
• July 2025
• May 2025
• October 2024
• June 2024
• January 2024
• November 2023
• September 2023

#motivation

Often you have 2 or more iterators, the values of which you would like to consume in sequence, as if they were a single iterator. Iterator libraries (and standard libraries of other languages) often have a function called concat or chain to do this. In JavaScript today, one can accomplish this with generators:

let lows = Iterator.from([0, 1, 2, 3]);
let highs = Iterator.from([6, 7, 8, 9]);

let lowsAndHighs = function* () {
  yield* lows;
  yield* highs;
}();

Array.from(lowsAndHighs); // [0, 1, 2, 3, 6, 7, 8, 9]

It is also useful to be able to sequence immediate values among the iterators, as one would do with yield using the generator approach.

let digits = function* () {
  yield* lows;
  yield 4;
  yield 5;
  yield* highs;
}();

Array.from(digits); // [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]

We should explore how to make this more ergonomic and functional.

#chosen solution

let digits = Iterator.concat(lows, [4, 5], highs);

For the (rare) case of infinite iterators of iterators, use Iterator.prototype.flatMap with the identity function.

function* selfCountingSequenceHelper() {
  for (let n = 1;; ++n) {
    yield Array(n).fill(n);
  }
}
let selfCountingSequence = selfCountingSequenceHelper().flatMap(x => x)

#prior art

#other languages

#JS libraries