Add Iterator#chunk to allow splitting iterator values into Arrays

Author: lundibundi

CHANGELOG.md

@@ -14,6 +14,8 @@ and this project adheres to
 - `common.mkdirpPromise()` function.
 - `Iterator#apply()` and `Iterator#chainApply()` to improve iterator
   interaction with chained calls.
+- `Iterator#chunks()` to allow splitting iterator via custom condition into
+  Arrays of values.
 
 ### Changed
 

README.md

@@ -847,6 +847,16 @@ _Result:_
 '3, -1';
 ```
 
+#### Iterator.prototype.chunk(from)
+
+- `from`: [`<Function>`][function]|[`<number>`][number] split function or chunk
+  size
+  - `val`: `<any>` current iterator value
+
+Split iterator into chunks of size `from` or every time function
+
+`from` returns falsy value.
+
 #### Iterator.prototype.collectTo(CollectionClass)
 
 #### Iterator.prototype.collectWith(obj, collector)

lib/iterator.js

@@ -222,6 +222,19 @@ class Iterator {
     return iter(res && res[Symbol.iterator] ? res : [res]);
   }
 
+  // Split iterator into chunks of size `from` or every time function
+  // `from` returns falsy value.
+  //   from - <Function> | <number> split function or chunk size
+  //     val <any> current iterator value
+  chunk(from) {
+    if (typeof from === 'number') {
+      const num = from;
+      let counter = 0;
+      from = () => counter++ % num === 0;
+    }
+    return new ChunkIterator(this, from);
+  }
+
   // Create iterator iterating over the range
   // Signature: start, stop[, step]
   //   start <number>
@@ -490,6 +503,26 @@ class SkipWhileIterator extends Iterator {
   }
 }
 
+class ChunkIterator extends Iterator {
+  constructor(base, fn) {
+    super(base);
+    this.fn = fn;
+    this.value = [];
+  }
+
+  next() {
+    let next = this.base.next();
+    if (next.done) return next;
+    while (!next.done && (!this.fn(next.value) || this.value.length === 0)) {
+      this.value.push(next.value);
+      next = this.base.next();
+    }
+    const value = this.value;
+    this.value = [next.value];
+    return { done: false, value };
+  }
+}
+
 const iter = base => new Iterator(base);
 
 module.exports = {

test/iterator.js

@@ -643,6 +643,41 @@ metatests.testSync('Iterator.chainApply on string', test => {
   test.strictSame(actual, 'h e l l o');
 });
 
+metatests.testSync('Iterator.chunk', test => {
+  const actual = iter([1, 2, 3, 1, 4, 5, 1, 6, 7])
+    .chunk(v => v === 1)
+    .toArray();
+  test.strictSame(actual, [[1, 2, 3], [1, 4, 5], [1, 6, 7]]);
+});
+
+metatests.testSync('Iterator.chunk with number', test => {
+  const actual = iter([1, 2, 3, 1, 4, 5, 1, 6, 7])
+    .chunk(3)
+    .toArray();
+  test.strictSame(actual, [[1, 2, 3], [1, 4, 5], [1, 6, 7]]);
+});
+
+metatests.testSync('Iterator.chunk with empty iterator', test => {
+  const actual = iter([])
+    .chunk(3)
+    .toArray();
+  test.strictSame(actual, []);
+});
+
+metatests.testSync('Iterator.chunk with single chunk', test => {
+  const actual = iter([1, 2, 3, 1, 4, 5, 1, 6, 7])
+    .chunk(() => false)
+    .toArray();
+  test.strictSame(actual, [[1, 2, 3, 1, 4, 5, 1, 6, 7]]);
+});
+
+metatests.testSync('Iterator.chunk with empty chunks', test => {
+  const actual = iter([1, 1, 3, 3, 3, 5, 5])
+    .chunk(x => x === 3)
+    .toArray();
+  test.strictSame(actual, [[1, 1], [3], [3], [3, 5, 5]]);
+});
+
 metatests.testSync('iterEntries must iterate over object entries', test => {
   const source = { a: 13, b: 42, c: 'hello' };
   test.strictSame(iterEntries(source).toArray(), Object.entries(source));