extra-iterator 0.10.3 → 0.11.1

package/dist/index.d.ts

@@ -46,12 +46,21 @@ export declare class ExtraIterator<T> extends Iterator<T, any, any> {
      *
      * @example
      * ExtraIterator.range(5, 10).toArray() // returns [5, 6, 7, 8, 9]
-     * ExtraIterator.range(5, 10).append(10).toArray() // returns [5, 6, 7, 8, 9, 10]
-     * ExtraIterator.range(1, 10, 2).toArray() // returns [1, 3, 5, 7, 9]
-     * ExtraIterator.range(0, 1, 0.25).toArray() // returns [0, 0.25, 0.5, 0.75]
-     * ExtraIterator.range(10, 0, -2).toArray() // returns [10, 8, 6, 4, 2]
+     * ExtraIterator.range(5, 10, { inclusive: true }).toArray() // returns [5, 6, 7, 8, 9, 10]
+     *
+     * // Counting down:
+     * ExtraIterator.range(10, 0).toArray() // return [10, 9, 8, 7, 6, 5, 4, 3, 2, 1]
+     * ExtraIterator.range(10, 0, { inclusive: true }).toArray() // return [10, 9, 8, 7, 6, 5, 4, 3, 2, 1, 0]
+     *
+     * // Custom stepping value:
+     * ExtraIterator.range(1, 10, { step: 2 }).toArray() // returns [1, 3, 5, 7, 9]
+     * ExtraIterator.range(0, 1, { step: 0.25 }).toArray() // returns [0, 0.25, 0.5, 0.75]
+     * ExtraIterator.range(10, 0, { step: 2 }).toArray() // returns [10, 8, 6, 4, 2]
      */
-    static range(start: number, end: number, step?: number): ExtraIterator<number>;
+    static range(start: number, end: number, { inclusive, step }?: {
+        inclusive?: boolean | undefined;
+        step?: number | undefined;
+    }): ExtraIterator<number>;
     /**
      * Creates an iterator that repeatedly yields the provided value.
      *
@@ -154,11 +163,11 @@ export declare class ExtraIterator<T> extends Iterator<T, any, any> {
      * @example
      *
      * ExtraIterator.from([4, 5, 6])
-     *     .prependMany([1, 2, 3])
+     *     .prependAll([1, 2, 3])
      *     .toArray()
      *     // returns [1, 2, 3, 4, 5, 6]
      */
-    prependMany<U>(items: Iterable<U>): ExtraIterator<T | U>;
+    prependAll<U>(items: Iterable<U>): ExtraIterator<T | U>;
     /**
      * Creates a new iterator that invokes the provided callback function over each element of this iterator and yields
      * the elements for which the callback returns `true`, only for as long as the callback returns `true`.
@@ -204,9 +213,9 @@ export declare class ExtraIterator<T> extends Iterator<T, any, any> {
     /**
      * Groups the elements in this iterator into groups of variable size.
      *
-     * This method calls the provided predicate function for each pair of adjacent elements in this iterator. It should
-     * return `true` if the elements should belong to the same group, or `false` if they should belong to different
-     * groups.
+     * This method calls the provided predicate function for each pair of adjacent elements in this iterator. The
+     * function should return `true` if the elements should belong to the same group, or `false` if they should belong
+     * to different groups.
      *
      * The resulting iterator yields arrays of elements that belong to the same group.
      *
@@ -283,7 +292,8 @@ export declare class ExtraIterator<T> extends Iterator<T, any, any> {
      */
     splice(startIndex: number, deleteCount: number, ...newItems: T[]): ExtraIterator<T>;
     /**
-     * Returns an iterator the provided element if this iterator is empty; otherwise, it returns this iterator.
+     * If this iterator is empty, returns an iterator with the provided element as its only element; otherwise, it
+     * returns a copy of this iterator.
      */
     defaultIfEmpty(provider: () => T): ExtraIterator<T>;
     /**
@@ -371,8 +381,8 @@ export declare class ExtraIterator<T> extends Iterator<T, any, any> {
      *
      * @example
      *
-     * ExtraIterator.from([1, 2, 3]).uniqueness() // returns true
-     * ExtraIterator.from([1, 2, 3, 1]).uniqueness() // returns false
+     * ExtraIterator.from([1, 2, 3]).testUnique() // returns true
+     * ExtraIterator.from([1, 2, 3, 1]).testUnique() // returns false
      */
     testUnique(mapper?: (value: T) => unknown): boolean;
     /**

package/dist/index.js

@@ -54,23 +54,30 @@ export class ExtraIterator extends Iterator {
      *
      * @example
      * ExtraIterator.range(5, 10).toArray() // returns [5, 6, 7, 8, 9]
-     * ExtraIterator.range(5, 10).append(10).toArray() // returns [5, 6, 7, 8, 9, 10]
-     * ExtraIterator.range(1, 10, 2).toArray() // returns [1, 3, 5, 7, 9]
-     * ExtraIterator.range(0, 1, 0.25).toArray() // returns [0, 0.25, 0.5, 0.75]
-     * ExtraIterator.range(10, 0, -2).toArray() // returns [10, 8, 6, 4, 2]
+     * ExtraIterator.range(5, 10, { inclusive: true }).toArray() // returns [5, 6, 7, 8, 9, 10]
+     *
+     * // Counting down:
+     * ExtraIterator.range(10, 0).toArray() // return [10, 9, 8, 7, 6, 5, 4, 3, 2, 1]
+     * ExtraIterator.range(10, 0, { inclusive: true }).toArray() // return [10, 9, 8, 7, 6, 5, 4, 3, 2, 1, 0]
+     *
+     * // Custom stepping value:
+     * ExtraIterator.range(1, 10, { step: 2 }).toArray() // returns [1, 3, 5, 7, 9]
+     * ExtraIterator.range(0, 1, { step: 0.25 }).toArray() // returns [0, 0.25, 0.5, 0.75]
+     * ExtraIterator.range(10, 0, { step: 2 }).toArray() // returns [10, 8, 6, 4, 2]
      */
-    static range(start, end, step = 1) {
+    static range(start, end, { inclusive = false, step = 1 } = {}) {
         return ExtraIterator.from(function* () {
-            if (Math.abs(step) < Number.EPSILON) {
+            step = Math.abs(step);
+            if (step < Number.EPSILON) {
                 throw new Error('Failed to create range. Cause: Range step cannot be 0.');
             }
-            else if (step > 0) {
-                for (let i = start; i < end; i += step) {
+            else if (end > start) {
+                for (let i = start; inclusive ? i <= end : i < end; i += step) {
                     yield i;
                 }
             }
             else {
-                for (let i = start; i > end; i += step) {
+                for (let i = start; inclusive ? i >= end : i > end; i -= step) {
                     yield i;
                 }
             }
@@ -264,11 +271,11 @@ export class ExtraIterator extends Iterator {
      * @example
      *
      * ExtraIterator.from([4, 5, 6])
-     *     .prependMany([1, 2, 3])
+     *     .prependAll([1, 2, 3])
      *     .toArray()
      *     // returns [1, 2, 3, 4, 5, 6]
      */
-    prependMany(items) {
+    prependAll(items) {
         return ExtraIterator.from(function* () {
             yield* items;
             yield* this;
@@ -344,9 +351,9 @@ export class ExtraIterator extends Iterator {
     /**
      * Groups the elements in this iterator into groups of variable size.
      *
-     * This method calls the provided predicate function for each pair of adjacent elements in this iterator. It should
-     * return `true` if the elements should belong to the same group, or `false` if they should belong to different
-     * groups.
+     * This method calls the provided predicate function for each pair of adjacent elements in this iterator. The
+     * function should return `true` if the elements should belong to the same group, or `false` if they should belong
+     * to different groups.
      *
      * The resulting iterator yields arrays of elements that belong to the same group.
      *
@@ -366,7 +373,7 @@ export class ExtraIterator extends Iterator {
             let chunk = [first.value];
             for (let left = first, right, index = 0; right = this.next(), !right.done; left = right, index++) {
                 if (predicate(left.value, right.value, index, chunk)) {
-                    chunk.push(left.value);
+                    chunk.push(right.value);
                 }
                 else {
                     yield chunk;
@@ -482,8 +489,7 @@ export class ExtraIterator extends Iterator {
      */
     splice(startIndex, deleteCount, ...newItems) {
         if (startIndex < 0) {
-            return ExtraIterator.from(this.toArray()
-                .toSpliced(startIndex, deleteCount, ...newItems));
+            return ExtraIterator.from(this.toArray().toSpliced(startIndex, deleteCount, ...newItems));
         }
         return ExtraIterator.from(function* () {
             for (let index = 0, next; next = this.next(), !next.done; index++) {
@@ -497,7 +503,8 @@ export class ExtraIterator extends Iterator {
         }.call(this));
     }
     /**
-     * Returns an iterator the provided element if this iterator is empty; otherwise, it returns this iterator.
+     * If this iterator is empty, returns an iterator with the provided element as its only element; otherwise, it
+     * returns a copy of this iterator.
      */
     defaultIfEmpty(provider) {
         return ExtraIterator.from(function* () {
@@ -521,9 +528,6 @@ export class ExtraIterator extends Iterator {
     loop(times = Infinity) {
         return ExtraIterator.from(function* () {
             const values = this.toArray();
-            if (values.length === 0) {
-                return;
-            }
             for (let i = 0; i < times; i++) {
                 yield* values;
             }
@@ -656,8 +660,8 @@ export class ExtraIterator extends Iterator {
      *
      * @example
      *
-     * ExtraIterator.from([1, 2, 3]).uniqueness() // returns true
-     * ExtraIterator.from([1, 2, 3, 1]).uniqueness() // returns false
+     * ExtraIterator.from([1, 2, 3]).testUnique() // returns true
+     * ExtraIterator.from([1, 2, 3, 1]).testUnique() // returns false
      */
     testUnique(mapper) {
         const seen = new Set();

package/dist/index.test.js

@@ -1,18 +1,30 @@
 import { ExtraIterator } from './index';
 import { describe, it } from 'node:test';
 import { expect } from 'expect';
-describe('ExtraIterator', () => {
+describe(ExtraIterator.name, () => {
     it('should create an ExtraIterator from an array', () => {
         const array = [1, 2, 3];
         const iterator = ExtraIterator.from(array);
         expect(iterator.toArray()).toEqual(array);
     });
+    it('should create an ExtraIterator from an "array-like" object', () => {
+        const arrayLike = { 0: 'a', 1: 'b', 2: 'c', length: 3 };
+        const iterator = ExtraIterator.from(arrayLike);
+        expect(iterator.toArray()).toEqual(['a', 'b', 'c']);
+    });
     it('should zip two iterators', () => {
         const a = ExtraIterator.from([1, 2, 3]);
         const b = ExtraIterator.from(['a', 'b', 'c']);
-        const zipped = ExtraIterator.zip(a, b);
+        const zipped = a.zip(b);
         expect(zipped.toArray()).toEqual([[1, 'a'], [2, 'b'], [3, 'c']]);
     });
+    it('should zip three iterators', () => {
+        const a = ExtraIterator.from([1, 2, 3]);
+        const b = ExtraIterator.from(['a', 'b', 'c']);
+        const c = ExtraIterator.from([true, false, true]);
+        const zipped = ExtraIterator.zip(a, b, c);
+        expect(zipped.toArray()).toEqual([[1, 'a', true], [2, 'b', false], [3, 'c', true]]);
+    });
     it('should count from 0 to a given number', () => {
         const iterator = ExtraIterator.count().take(5);
         expect(iterator.toArray()).toEqual([0, 1, 2, 3, 4]);
@@ -42,6 +54,10 @@ describe('ExtraIterator', () => {
         const iterator = ExtraIterator.from([1, 2, 3, 4]).take(2);
         expect(iterator.toArray()).toEqual([1, 2]);
     });
+    it('should take the last values of the sequence', () => {
+        const iterator = ExtraIterator.from([1, 2, 3, 4]).take(-2);
+        expect(iterator.toArray()).toEqual([3, 4]);
+    });
     it('should drop a given number of values', () => {
         const iterator = ExtraIterator.from([1, 2, 3, 4]).drop(2);
         expect(iterator.toArray()).toEqual([3, 4]);
@@ -54,9 +70,15 @@ describe('ExtraIterator', () => {
         const iterator = ExtraIterator.from([1, 2, 3]);
         expect(iterator.first()).toBe(1);
     });
-    it('should return the last value', () => {
-        const iterator = ExtraIterator.from([1, 2, 3]);
-        expect(iterator.last()).toBe(3);
+    describe(ExtraIterator.prototype.last.name, () => {
+        it('should return the last value if the iterator is not empty', () => {
+            const iterator = ExtraIterator.from([1, 2, 3]);
+            expect(iterator.last()).toBe(3);
+        });
+        it('should return undefined if the iterator is empty', () => {
+            const iterator = ExtraIterator.empty();
+            expect(iterator.last()).toBeUndefined();
+        });
     });
     it('should return a value at a specific index', () => {
         const iterator = ExtraIterator.from([1, 2, 3]);
@@ -92,6 +114,10 @@ describe('ExtraIterator', () => {
         const iterator = ExtraIterator.from([2, 3]).prepend(1);
         expect(iterator.toArray()).toEqual([1, 2, 3]);
     });
+    it('should prepend multiple values to the iterator', () => {
+        const iterator = ExtraIterator.from([4, 5, 6]).prependAll([1, 2, 3]);
+        expect(iterator.toArray()).toEqual([1, 2, 3, 4, 5, 6]);
+    });
     it('should append a value to the iterator', () => {
         const iterator = ExtraIterator.from([1, 2]).append(3);
         expect(iterator.toArray()).toEqual([1, 2, 3]);
@@ -114,9 +140,19 @@ describe('ExtraIterator', () => {
         const iterator = ExtraIterator.from([1, 2, 3, 4]).splice(1, 2, 5, 6);
         expect(iterator.toArray()).toEqual([1, 5, 6, 4]);
     });
-    it('should provide a default value if the iterator is empty', () => {
-        const iterator = ExtraIterator.empty().defaultIfEmpty(() => 42);
-        expect(iterator.toArray()).toEqual([42]);
+    it('should splice values from the end of the iterator', () => {
+        const iterator = ExtraIterator.from([1, 2, 3, 4]).splice(-3, 2, 5, 6);
+        expect(iterator.toArray()).toEqual([1, 5, 6, 4]);
+    });
+    describe('defaultIfEmpty', () => {
+        it('should provide a default value if the iterator is empty', () => {
+            const iterator = ExtraIterator.empty().defaultIfEmpty(() => 42);
+            expect(iterator.toArray()).toEqual([42]);
+        });
+        it('should relay the iterator itself if it is not empty', () => {
+            const iterator = ExtraIterator.from([1, 2, 3]).defaultIfEmpty(() => 42);
+            expect(iterator.toArray()).toEqual([1, 2, 3]);
+        });
     });
     it('should group values by a key', () => {
         const iterator = ExtraIterator.from(['apple', 'banana', 'apricot']);
@@ -171,6 +207,16 @@ describe('ExtraIterator', () => {
                 .toArray();
             expect(result).toEqual([[1, 1], [2], [3, 3, 3], [2, 2]]);
         });
+        it('should chunk using a key selector function', () => {
+            const result = ExtraIterator.from(['apple', 'apricot', 'banana', 'avocado'])
+                .chunkWith((lhs, rhs) => lhs[0] === rhs[0])
+                .toArray();
+            expect(result).toEqual([['apple', 'apricot'], ['banana'], ['avocado']]);
+        });
+        it('should build an empty iterator for an empty iterator', () => {
+            const result = ExtraIterator.from([]).chunkWith((lhs, rhs) => lhs === rhs).toArray();
+            expect(result).toEqual([]);
+        });
     });
     it('should create a chain of responsibility function', () => {
         const humanizeDuration = ExtraIterator.from([
@@ -191,15 +237,76 @@ describe('ExtraIterator', () => {
         const chain = handlers.toChainOfResponsibilityFunction(next => next());
         expect(() => chain()).toThrow();
     });
-    it('should repeat values', () => {
-        const iterator = ExtraIterator.from([1, 2, 3]).loop(3);
-        expect(iterator.toArray()).toEqual([1, 2, 3, 1, 2, 3, 1, 2, 3]);
+    describe(ExtraIterator.prototype.loop.name, () => {
+        it('should repeat values', () => {
+            const iterator = ExtraIterator.from([1, 2, 3]).loop(3);
+            expect(iterator.toArray()).toEqual([1, 2, 3, 1, 2, 3, 1, 2, 3]);
+        });
+        it('should yield an empty iterator if the count is equal to or lower than 0', () => {
+            expect(ExtraIterator.from([1, 2, 3]).loop(0).toArray()).toEqual([]);
+            expect(ExtraIterator.from([1, 2, 3]).loop(-1).toArray()).toEqual([]);
+            expect(ExtraIterator.from([1, 2, 3]).loop(-3).toArray()).toEqual([]);
+            expect(ExtraIterator.from([1, 2, 3]).loop(-4).toArray()).toEqual([]);
+            expect(ExtraIterator.from([1, 2, 3]).loop(-99999).toArray()).toEqual([]);
+        });
+    });
+    describe(ExtraIterator.range.name, () => {
+        it('should iterate over ranges', () => {
+            expect(ExtraIterator.range(5, 10).toArray()).toEqual([5, 6, 7, 8, 9]);
+            expect(ExtraIterator.range(5, 10).append(10).toArray()).toEqual([5, 6, 7, 8, 9, 10]);
+        });
+        it('should iterate over ranges with steps', () => {
+            expect(ExtraIterator.range(1, 10, { step: 2 }).toArray()).toEqual([1, 3, 5, 7, 9]);
+            expect(ExtraIterator.range(0, 1, { step: 0.25 }).toArray()).toEqual([0, 0.25, 0.5, 0.75]);
+            expect(ExtraIterator.range(10, 0, { step: 2 }).toArray()).toEqual([10, 8, 6, 4, 2]);
+            expect(ExtraIterator.range(10, 0, { step: -2 }).toArray()).toEqual([10, 8, 6, 4, 2]);
+        });
+        it('should iterate over inclusive ranges', () => {
+            expect(ExtraIterator.range(1, 10, { inclusive: true }).toArray()).toEqual([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
+            expect(ExtraIterator.range(1, 10, { inclusive: true, step: 2 }).toArray()).toEqual([1, 3, 5, 7, 9]);
+            expect(ExtraIterator.range(0, 1, { inclusive: true, step: 0.25 }).toArray()).toEqual([0, 0.25, 0.5, 0.75, 1]);
+            expect(ExtraIterator.range(10, 0, { inclusive: true, step: -2 }).toArray()).toEqual([10, 8, 6, 4, 2, 0]);
+        });
+        it('should throw an error if the step is 0', () => {
+            expect(() => ExtraIterator.range(0, 10, { step: 0 }).toArray()).toThrow();
+        });
+    });
+    it('should count the number of elements in the iterator', () => {
+        expect(ExtraIterator.from([1, 2, 3]).count()).toBe(3);
+        expect(ExtraIterator.empty().count()).toBe(0);
     });
-    it('should iterate over ranges', () => {
-        expect(ExtraIterator.range(5, 10).toArray()).toEqual([5, 6, 7, 8, 9]);
-        expect(ExtraIterator.range(5, 10).append(10).toArray()).toEqual([5, 6, 7, 8, 9, 10]);
-        expect(ExtraIterator.range(1, 10, 2).toArray()).toEqual([1, 3, 5, 7, 9]);
-        expect(ExtraIterator.range(0, 1, 0.25).toArray()).toEqual([0, 0.25, 0.5, 0.75]);
-        expect(ExtraIterator.range(10, 0, -2).toArray()).toEqual([10, 8, 6, 4, 2]);
+    describe(ExtraIterator.prototype.testUnique.name, () => {
+        it('should return true if all values are unique', () => {
+            expect(ExtraIterator.from([1, 2, 3]).testUnique()).toBe(true);
+        });
+        it('should return false if there are duplicate values', () => {
+            expect(ExtraIterator.from([1, 2, 2, 3]).testUnique()).toBe(false);
+        });
+        it('should return true for an empty iterator', () => {
+            expect(ExtraIterator.empty().testUnique()).toBe(true);
+        });
+    });
+    describe(ExtraIterator.prototype.withEach.name, () => {
+        it('should perform a side effect for each value', () => {
+            const sideEffects = [];
+            const iterator = ExtraIterator.from([1, 2, 3]).withEach(x => void sideEffects.push(x));
+            expect(iterator.toArray()).toEqual([1, 2, 3]);
+            expect(sideEffects).toEqual([1, 2, 3]);
+        });
+        it('should not perform side effects if the iterator is not consumed', () => {
+            const sideEffects = [];
+            ExtraIterator.from([1, 2, 3]).withEach(x => void sideEffects.push(x));
+            expect(sideEffects).toEqual([]);
+        });
+        it('should perform side effects even if the iterator is only partially consumed', () => {
+            const sideEffects = [];
+            const iterator = ExtraIterator.from([1, 2, 3]).withEach(x => void sideEffects.push(x));
+            iterator.next();
+            expect(sideEffects).toEqual([1]);
+        });
+        it('should perform side effects on objects', () => {
+            const iterator = ExtraIterator.from([{ value: 1 }, { value: 2 }, { value: 3 }]).withEach(obj => obj.value *= 2);
+            expect(iterator.toArray()).toEqual([{ value: 2 }, { value: 4 }, { value: 6 }]);
+        });
     });
 });

package/package.json

@@ -3,7 +3,7 @@
   "description": "An extension of the Iterator class with additional utility helper functions.",
   "author": "Leonardo Raele <leonardoraele@gmail.com>",
   "license": "MIT",
-  "version": "0.10.3",
+  "version": "0.11.1",
   "type": "module",
   "exports": {
     ".": "./dist/index.js",