Implement Iterator#zipLongest and improve zip description

CHANGELOG.md

@@ -8,6 +8,14 @@ and this project adheres to
 
 ## [Unreleased][unreleased]
 
+### Added
+
+- `Iterator#zipLongest()` and `Iterator.zipLongest()`,
+  `Iterator#zipLongestWith()` and `Iterator.zipLongestWith()` similar to
+  `Iterator#zip` but instead of stopping when shortest iterator is exhausted
+  continues until the longest iterable is exhausted filling-in missing values
+  with `undefined` or provided `defaultValue`.
+
 ## [2.2.0][] - 2020-07-10
 
 ### Added

README.md

@@ -139,6 +139,8 @@ $ npm install @metarhia/common
 - [Iterator](#class-iterator)
   - [Iterator.range](#iteratorrangestart-stop-step)
   - [Iterator.zip](#iteratorzipiterators)
+  - [Iterator.zipLongest](#iteratorziplongestiterators)
+  - [Iterator.zipLongestWith](#iteratorziplongestwithdefaultvalue-iterators)
   - [Iterator.prototype.constructor](#iteratorprototypeconstructorbase)
   - [Iterator.prototype.apply](#iteratorprototypeapplyfn)
   - [Iterator.prototype.chain](#iteratorprototypechainiterators)
@@ -174,6 +176,8 @@ $ npm install @metarhia/common
   - [Iterator.prototype.toArray](#iteratorprototypetoarray)
   - [Iterator.prototype.toObject](#iteratorprototypetoobject)
   - [Iterator.prototype.zip](#iteratorprototypezipiterators)
+  - [Iterator.prototype.zipLongest](#iteratorprototypeziplongestiterators)
+  - [Iterator.prototype.zipLongestWith](#iteratorprototypeziplongestwithdefaultvalue-iterators)
 - [iter](#iterbase)
 - [iterEntries](#iterentriesobj)
 - [iterKeys](#iterkeysobj)
@@ -1062,11 +1066,39 @@ Create iterator iterating over the range
 
 #### Iterator.zip(...iterators)
 
-- `iterators`: [`<Array>`][array]
+- `...iterators`: [`<Array>`][array] iterators to be aggregated
 
 _Returns:_ `<Iterator>`
 
-Create iterator by zipping multiple provided iterators into one
+Creates an iterator that aggregates elements from each of the iterators.
+
+Returns an iterator of Arrays where the i-th tuple contains the i-th element
+from each of the passed iterators. The iterator stops when the shortest input
+iterable is exhausted.
+
+#### Iterator.zipLongest(...iterators)
+
+- `...iterators`: [`<Array>`][array] iterators to be aggregated
+
+_Returns:_ `<Iterator>`
+
+Creates an iterator that aggregates elements from each of the iterators.
+
+If the iterables are of uneven length, missing values are filled-in with
+[`<undefined>`][undefined]. Iteration continues until the longest iterable is
+exhausted.
+
+#### Iterator.zipLongestWith(defaultValue, ...iterators)
+
+- `defaultValue`: `<any>` value to fill-in missing values with
+- `...iterators`: [`<Array>`][array] iterators to be aggregated
+
+_Returns:_ `<Iterator>`
+
+Creates an iterator that aggregates elements from each of the iterators.
+
+If the iterables are of uneven length, missing values are filled-in with
+`<defaultValue>`. Iteration continues until the longest iterable is exhausted.
 
 #### Iterator.prototype.constructor(base)
 
@@ -1245,6 +1277,40 @@ offer.
 
 #### Iterator.prototype.zip(...iterators)
 
+- `...iterators`: [`<Array>`][array] iterators to be aggregated
+
+_Returns:_ `<Iterator>`
+
+Creates an iterator that aggregates elements from each of the iterators.
+
+Returns an iterator of Arrays where the i-th tuple contains the i-th element
+from each of the passed iterators. The iterator stops when the shortest input
+iterable is exhausted.
+
+#### Iterator.prototype.zipLongest(...iterators)
+
+- `...iterators`: [`<Array>`][array] iterators to be aggregated
+
+_Returns:_ `<Iterator>`
+
+Creates an iterator that aggregates elements from each of the iterators.
+
+If the iterables are of uneven length, missing values are filled-in with
+[`<undefined>`][undefined]. Iteration continues until the longest iterable is
+exhausted.
+
+#### Iterator.prototype.zipLongestWith(defaultValue, ...iterators)
+
+- `defaultValue`: `<any>` value to fill-in missing values with
+- `...iterators`: [`<Array>`][array] iterators to be aggregated
+
+_Returns:_ `<Iterator>`
+
+Creates an iterator that aggregates elements from each of the iterators.
+
+If the iterables are of uneven length, missing values are filled-in with
+`<defaultValue>`. Iteration continues until the longest iterable is exhausted.
+
 ### iter(base)
 
 ### iterEntries(obj)

lib/iterator.js

@@ -156,10 +156,40 @@ class Iterator {
     return new FlatMapIterator(this, mapper, thisArg);
   }
 
+  // Creates an iterator that aggregates elements from each of the iterators.
+  //
+  // Returns an iterator of Arrays where the i-th tuple contains
+  // the i-th element from each of the passed iterators.
+  // The iterator stops when the shortest input iterable is exhausted.
+  //   ...iterators <Array> iterators to be aggregated
+  // Returns: <Iterator>
   zip(...iterators) {
     return new ZipIterator(this, iterators);
   }
 
+  // Creates an iterator that aggregates elements from each of the iterators.
+  //
+  // If the iterables are of uneven length, missing values are filled-in
+  // with <undefined>. Iteration continues until the longest iterable
+  // is exhausted.
+  //   ...iterators <Array> iterators to be aggregated
+  // Returns: <Iterator>
+  zipLongest(...iterators) {
+    return new ZipIteratorLongest(this, iterators);
+  }
+
+  // Creates an iterator that aggregates elements from each of the iterators.
+  //
+  // If the iterables are of uneven length, missing values are filled-in
+  // with <defaultValue>. Iteration continues until the longest iterable
+  // is exhausted.
+  //   defaultValue <any> value to fill-in missing values with
+  //   ...iterators <Array> iterators to be aggregated
+  // Returns: <Iterator>
+  zipLongestWith(defaultValue, ...iterators) {
+    return new ZipIteratorLongest(this, iterators, defaultValue);
+  }
+
   chain(...iterators) {
     return new ChainIterator(this, iterators);
   }
@@ -328,14 +358,40 @@ class Iterator {
     return iter(res && res[Symbol.iterator] ? res : [res]);
   }
 
-  // Create iterator by zipping multiple provided iterators into one
-  // Signature: ...iterators
-  //   iterators <Array>
+  // Creates an iterator that aggregates elements from each of the iterators.
+  //
+  // Returns an iterator of Arrays where the i-th tuple contains
+  // the i-th element from each of the passed iterators.
+  // The iterator stops when the shortest input iterable is exhausted.
+  //   ...iterators <Array> iterators to be aggregated
   // Returns: <Iterator>
   static zip(base, ...iterators) {
     return new ZipIterator(toIterator(base), iterators);
   }
 
+  // Creates an iterator that aggregates elements from each of the iterators.
+  //
+  // If the iterables are of uneven length, missing values are filled-in
+  // with <undefined>. Iteration continues until the longest iterable
+  // is exhausted.
+  //   ...iterators <Array> iterators to be aggregated
+  // Returns: <Iterator>
+  static zipLongest(base, ...iterators) {
+    return new ZipIteratorLongest(toIterator(base), iterators);
+  }
+
+  // Creates an iterator that aggregates elements from each of the iterators.
+  //
+  // If the iterables are of uneven length, missing values are filled-in
+  // with <defaultValue>. Iteration continues until the longest iterable
+  // is exhausted.
+  //   defaultValue <any> value to fill-in missing values with
+  //   ...iterators <Array> iterators to be aggregated
+  // Returns: <Iterator>
+  static zipLongestWith(defaultValue, base, ...iterators) {
+    return new ZipIteratorLongest(toIterator(base), iterators, defaultValue);
+  }
+
   // Create iterator iterating over the range
   // Signature: start, stop[, step]
   //   start <number>
@@ -545,6 +601,38 @@ class ZipIterator extends Iterator {
       }
       result.push(next.value);
     }
+
+    return { done: false, value: result };
+  }
+}
+
+class ZipIteratorLongest extends Iterator {
+  constructor(base, iterators, defaultValue) {
+    super(base);
+    this.done = false;
+    this.iterators = iterators.map(toIterator);
+    this.defaultValue = defaultValue;
+  }
+
+  next() {
+    if (this.done) return { done: true, value: undefined };
+
+    const result = [];
+
+    const next = this.base.next();
+    result.push(!next.done ? next.value : this.defaultValue);
+
+    let allDone = next.done;
+    for (const iterator of this.iterators) {
+      const next = iterator.next();
+      result.push(!next.done ? next.value : this.defaultValue);
+      allDone = allDone && next.done;
+    }
+
+    if (allDone) {
+      this.done = true;
+      return { done: true, value: undefined };
+    }
     return { done: false, value: result };
   }
 }