Repository files navigation

A TC39 proposal to synchronise the advancement of multiple iterators, often calledzip.

Stage: 2.7. Further advancement is dependent onwriting test262 tests.

Demo:https://tc39.es/proposal-joint-iteration/demo/

Specification:https://tc39.es/proposal-joint-iteration/

Often you have 2 or more iterators that are positionally aligned (the firstvalue yielded by the first iterator corresponds to the first value yielded bythe other iterators, and so on), and you would like to operate on thecorresponding values together. A common solution to this iszip, whichproduces an iterator of the combined values.zipWith allows combination ofvalues in some way other than tupling. Some languages expresszipWith as avariadicmap.

• June 2024
• January 2024
• November 2023
• September 2023

This proposal adds two methods:Iterator.zip andIterator.zipKeyed.zip takes an iterable of iterables and produces an iterable of arrays where position corresponds to position in the passed iterable.zipKeyed takes an object whose values are iterables and produces an iterable of objects where keys correspond to keys in the passed object.

Iterator.zip([[0,1,2],[3,4,5],]).toArray()/*Produces:[  [0, 3],  [1, 4],  [2, 5],]*/

Iterator.zipKeyed({a:[0,1,2],b:[3,4,5,6],c:[7,8,9],}).toArray()/*Produces:[  { a: 0, b: 3, c: 7 },  { a: 1, b: 4, c: 8 },  { a: 2, b: 5, c: 9 },]*/

Both methods take an options bag as a second argument which allows specifying amode of"shortest" (the default),"longest", or"strict".

For"longest", the options bag can also define padding to be used for shorter inputs by providing an iterable or object (forzip andzipKeyed respectively):

Iterator.zipKeyed({a:[0,1,2],b:[3,4,5,6],c:[7,8,9],},{mode:'longest',padding:{c:10},}).toArray()/*Produces:[  { a: 0,         b: 3, c: 7  },  { a: 1,         b: 4, c: 8  },  { a: 2,         b: 5, c: 9  },  { a: undefined, b: 6, c: 10 },];*/

1. do we support just 2 iterators or something else? 2+? 1+? 0+?Decision: 0+.
   1. if 0 is allowed, is that considered never-ending or already completed?Decision: Already completed.
   2. should the iterators be passed positionally (combining to arrays) or named (combining to objects)?Decision: Both, as seperate APIs.
   3. do we take the iterators as varargs or as an iterable/object?Decision: Iterable/object.
      1. varargs eliminates design space for potentially passing an options bag or a combining function
2. do we support iterators and iterables likeIterator.from andflatMap?Decision: Just iterables.
   1. if so, which string handling do we match?Iterator.from iterates strings;flatMap rejects strings
3. if an iterator completes, do we still advance the other iterators?Decision: Depends on the mode.
   1. do wereturn them?Decision: Yes, except with mode: longest.
4. if an iterator fails to advance, do we still advance the other iterators?Decision: Yes.
   1. if so, do we return an AggregateError? Only if 2+ failures?Decision: No, first error swallows any subsequent.
5. do we want-With variants for combining the values in other ways than tupling?Decision: Not in this proposal.
   1. what about always requiring the combiner?
6. do we want azipLongest/zipFilled/zipAll?Decision: Yes, as an option.
   1. if so, do we want a filler element or to call a function to provide the filler?Decision: Per-iterable filler elements.
   2. what about a variant that matches the length of a privileged iterator (this)?Decision: No.
7. do we want azipEqual/zipStrict that throws if they do not complete after the same number of yields?Decision: Yes, as an option.