extra-iterator 0.2.1 → 0.3.1

package/README.md

@@ -1,6 +1,6 @@
 # extra-iterator
 
-> ⚠ Still a work in progress; not ready for production — tests are missing and the documentation is lacking.
+> ⚠ Documentation is still a TODO
 
 ## Install
 

package/dist/index.d.ts

@@ -2,13 +2,20 @@ interface ArrayIsh<T> {
     [index: number]: T;
     length: number;
 }
+export type ExtraIteratorSource<T> = Iterator<T, any, any> | Iterable<T, any, any> | ArrayIsh<T>;
 export declare class ExtraIterator<T> extends Iterator<T, any, any> {
-    static from<T>(source: Iterator<T, any, any> | Iterable<T, any, any> | ArrayIsh<T>): ExtraIterator<T>;
-    static fromKeys<T extends {}>(subject: T): ExtraIterator<keyof T>;
-    static fromValues<T extends {}>(subject: T): ExtraIterator<T[keyof T]>;
-    static fromEntries<T extends {}>(subject: T): ExtraIterator<[keyof T, T[keyof T]]>;
+    static from<T>(source: ExtraIteratorSource<T>): ExtraIterator<T>;
+    static zip<A, B>(a: ExtraIteratorSource<A>, b: ExtraIteratorSource<B>): ExtraIterator<[A, B]>;
+    static zip<A, B, C>(a: ExtraIteratorSource<A>, b: ExtraIteratorSource<B>, c: ExtraIteratorSource<C>): ExtraIterator<[A, B, C]>;
+    static zip<A, B, C, D>(a: ExtraIteratorSource<A>, b: ExtraIteratorSource<B>, c: ExtraIteratorSource<C>, d: ExtraIteratorSource<D>): ExtraIterator<[A, B, C, D]>;
+    static zip<A, B, C, D, E>(a: ExtraIteratorSource<A>, b: ExtraIteratorSource<B>, c: ExtraIteratorSource<C>, d: ExtraIteratorSource<D>, e: ExtraIteratorSource<E>): ExtraIterator<[A, B, C, D, E]>;
+    static zip<A, B, C, D, E, F>(a: ExtraIteratorSource<A>, b: ExtraIteratorSource<B>, c: ExtraIteratorSource<C>, d: ExtraIteratorSource<D>, e: ExtraIteratorSource<E>, f: ExtraIteratorSource<F>): ExtraIterator<[A, B, C, D, E, F]>;
+    static zip<A, B, C, D, E, F, G>(a: ExtraIteratorSource<A>, b: ExtraIteratorSource<B>, c: ExtraIteratorSource<C>, d: ExtraIteratorSource<D>, e: ExtraIteratorSource<E>, f: ExtraIteratorSource<F>, g: ExtraIteratorSource<G>): ExtraIterator<[A, B, C, D, E, F, G]>;
+    static zip<A, B, C, D, E, F, G, H>(a: ExtraIteratorSource<A>, b: ExtraIteratorSource<B>, c: ExtraIteratorSource<C>, d: ExtraIteratorSource<D>, e: ExtraIteratorSource<E>, f: ExtraIteratorSource<F>, g: ExtraIteratorSource<G>, h: ExtraIteratorSource<H>): ExtraIterator<[A, B, C, D, E, F, G, H]>;
+    static zip<T>(...iterables: ExtraIteratorSource<T>[]): ExtraIterator<T[]>;
     static empty<T = any>(): ExtraIterator<T>;
-    static count(max: number): ExtraIterator<number>;
+    static count(): ExtraIterator<number>;
+    static count(end: number): ExtraIterator<number>;
     static count(start: number, end: number): ExtraIterator<number>;
     static count(start: number, end: number, interval: number): ExtraIterator<number>;
     static repeat<T>(count: number, value: T): ExtraIterator<T>;
@@ -30,26 +37,20 @@ export declare class ExtraIterator<T> extends Iterator<T, any, any> {
     first(): T | undefined;
     last(): T | undefined;
     at(index: number): T | undefined;
-    appendMany(items: Iterable<T>): ExtraIterator<T>;
-    appendOne(item: T): ExtraIterator<T>;
+    concat(items: Iterable<T>): ExtraIterator<T>;
+    append(item: T): ExtraIterator<T>;
     prependMany(items: Iterable<T>): ExtraIterator<T>;
-    prependOne(item: T): ExtraIterator<T>;
+    prepend(item: T): ExtraIterator<T>;
     takeWhile(predicate: (value: T, index: number) => boolean): ExtraIterator<T>;
     dropWhile(predicate: (value: T, index: number) => boolean): ExtraIterator<T>;
     chunk(size: number): ExtraIterator<T[]>;
-    /**
-     * Pairs with another iterable to form an iterator of pairs.
-     * // TODO Expand to support more than 2 iterables
-     */
     zip<U>(other: Iterable<U>): ExtraIterator<[T, U]>;
-    /**
-     * Transforms from an iterator of pairs into a pair of iterators.
-     * // TODO Expand to support more than 2 iterables
-     */
-    unzip(): T extends [infer U, infer V] ? [ExtraIterator<U>, ExtraIterator<V>] : never;
+    interpose<U>(separator: U): ExtraIterator<T | U>;
+    interleave<U>(other: ExtraIteratorSource<U>): ExtraIterator<T | U>;
     splice(startIndex: number, deleteCount: number, ...newItems: T[]): ExtraIterator<T>;
-    with(index: number, value: T): ExtraIterator<T>;
+    defaultIfEmpty(provider: () => T): ExtraIterator<T>;
     collect<U>(collectfn: ((iter: Iterable<T>) => U)): U;
     toSortedBy(...keys: (keyof T)[]): T[];
+    count(): number;
 }
 export {};

package/dist/index.js

@@ -10,24 +10,21 @@ export class ExtraIterator extends Iterator {
         }
         return new ExtraIterator(source);
     }
-    static fromKeys(subject) {
-        return new ExtraIterator(Object.keys(subject));
-    }
-    static fromValues(subject) {
-        return new ExtraIterator(Object.values(subject));
-    }
-    static fromEntries(subject) {
-        return new ExtraIterator(Object.entries(subject));
+    static zip(...iterables) {
+        return new ExtraIterator(function* () {
+            for (let iterators = iterables.map(iterable => ExtraIterator.from(iterable)), results; results = iterators.map(iterator => iterator.next()),
+                results.every(value => !value.done);) {
+                yield results.map(value => value.value);
+            }
+        }().toArray());
     }
     static empty() {
         return new ExtraIterator([]);
     }
-    static count(start, end, interval) {
-        if (typeof end === 'undefined') {
-            end = start;
-            start = 0;
-        }
-        interval ??= 1;
+    static count(...args) {
+        const [start, end, interval] = args.length === 0 ? [0, Infinity, 1]
+            : args.length === 1 ? [0, args[0], 1]
+                : [args[0], args[1], args[2] ?? 1];
         return new ExtraIterator(function* () {
             for (let counter = start; counter < end; counter += interval) {
                 yield counter;
@@ -140,13 +137,13 @@ export class ExtraIterator extends Iterator {
             : index < 0 ? this.take(index).at(0)
                 : this.drop(index).first();
     }
-    appendMany(items) {
+    concat(items) {
         return ExtraIterator.from(function* () {
             yield* this;
             yield* items;
         }.call(this));
     }
-    appendOne(item) {
+    append(item) {
         return ExtraIterator.from(function* () {
             yield* this;
             yield item;
@@ -158,7 +155,7 @@ export class ExtraIterator extends Iterator {
             yield* this;
         }.call(this));
     }
-    prependOne(item) {
+    prepend(item) {
         return ExtraIterator.from(function* () {
             yield item;
             yield* this;
@@ -192,10 +189,6 @@ export class ExtraIterator extends Iterator {
             }
         }.call(this));
     }
-    /**
-     * Pairs with another iterable to form an iterator of pairs.
-     * // TODO Expand to support more than 2 iterables
-     */
     zip(other) {
         return ExtraIterator.from(function* () {
             const otherIterator = Iterator.from(other);
@@ -204,15 +197,31 @@ export class ExtraIterator extends Iterator {
             }
         }.call(this));
     }
-    /**
-     * Transforms from an iterator of pairs into a pair of iterators.
-     * // TODO Expand to support more than 2 iterables
-     */
-    unzip() {
-        return [
-            this.map(value => value[0]),
-            this.map(value => value[1]),
-        ];
+    interpose(separator) {
+        return ExtraIterator.from(function* () {
+            for (let next = this.next(); !next.done;) {
+                yield next.value;
+                next = this.next();
+                if (!next.done) {
+                    yield separator;
+                }
+            }
+        }.call(this));
+    }
+    interleave(other) {
+        return ExtraIterator.from(function* () {
+            const otherIterator = ExtraIterator.from(other);
+            for (let next, otherNext; next = this.next(),
+                otherNext = otherIterator.next(),
+                !next.done || !otherNext.done;) {
+                if (!next.done) {
+                    yield next.value;
+                }
+                if (!otherNext.done) {
+                    yield otherNext.value;
+                }
+            }
+        }.call(this));
     }
     splice(startIndex, deleteCount, ...newItems) {
         if (startIndex < 0) {
@@ -230,8 +239,17 @@ export class ExtraIterator extends Iterator {
             }
         }.call(this));
     }
-    with(index, value) {
-        return this.splice(index, 1, value);
+    defaultIfEmpty(provider) {
+        return ExtraIterator.from(function* () {
+            const result = this.next();
+            if (result.done) {
+                yield provider();
+            }
+            else {
+                yield result.value;
+                yield* this;
+            }
+        }.call(this));
     }
     collect(collectfn) {
         return collectfn(this);
@@ -248,4 +266,11 @@ export class ExtraIterator extends Iterator {
             return 0;
         });
     }
+    count() {
+        let count = 0;
+        for (let next; next = this.next(), !next.done;) {
+            count++;
+        }
+        return count;
+    }
 }

package/dist/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.test.js

@@ -0,0 +1,121 @@
+import { ExtraIterator } from './index';
+import { describe, it } from 'node:test';
+import { expect } from 'expect';
+describe('ExtraIterator', () => {
+    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 zip two iterators', () => {
+        const a = ExtraIterator.from([1, 2, 3]);
+        const b = ExtraIterator.from(['a', 'b', 'c']);
+        const zipped = ExtraIterator.zip(a, b);
+        expect(zipped.toArray()).toEqual([[1, 'a'], [2, 'b'], [3, 'c']]);
+    });
+    it('should count from 0 to a given number', () => {
+        const iterator = ExtraIterator.count(5);
+        expect(iterator.toArray()).toEqual([0, 1, 2, 3, 4]);
+    });
+    it('should repeat a value a given number of times', () => {
+        const iterator = ExtraIterator.repeat(3, 'x');
+        expect(iterator.toArray()).toEqual(['x', 'x', 'x']);
+    });
+    it('should filter values based on a predicate', () => {
+        const iterator = ExtraIterator.from([1, 2, 3, 4]).filter(x => x % 2 === 0);
+        expect(iterator.toArray()).toEqual([2, 4]);
+    });
+    it('should map values using a callback function', () => {
+        const iterator = ExtraIterator.from([1, 2, 3]).map(x => x * 2);
+        expect(iterator.toArray()).toEqual([2, 4, 6]);
+    });
+    it('should take a limited number of values', () => {
+        const iterator = ExtraIterator.from([1, 2, 3, 4]).take(2);
+        expect(iterator.toArray()).toEqual([1, 2]);
+    });
+    it('should drop a given number of values', () => {
+        const iterator = ExtraIterator.from([1, 2, 3, 4]).drop(2);
+        expect(iterator.toArray()).toEqual([3, 4]);
+    });
+    it('should flatten nested iterables', () => {
+        const iterator = ExtraIterator.from([[1, 2], [3, 4]]).flatten();
+        expect(iterator.toArray()).toEqual([1, 2, 3, 4]);
+    });
+    it('should return the first value', () => {
+        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);
+    });
+    it('should return a value at a specific index', () => {
+        const iterator = ExtraIterator.from([1, 2, 3]);
+        expect(iterator.at(1)).toBe(2);
+    });
+    it('should interpose a separator between values', () => {
+        const iterator = ExtraIterator.from([1, 2, 3]).interpose(0);
+        expect(iterator.toArray()).toEqual([1, 0, 2, 0, 3]);
+    });
+    it('should chunk values into groups of a given size', () => {
+        const iterator = ExtraIterator.from([1, 2, 3, 4]).chunk(2);
+        expect(iterator.toArray()).toEqual([[1, 2], [3, 4]]);
+    });
+    it('should remove duplicate values', () => {
+        const iterator = ExtraIterator.from([1, 2, 2, 3]).uniq();
+        expect(iterator.toArray()).toEqual([1, 2, 3]);
+    });
+    it('should compact values by removing null and undefined', () => {
+        const iterator = ExtraIterator.from([1, null, 2, undefined, 3]).compact();
+        expect(iterator.toArray()).toEqual([1, 2, 3]);
+    });
+    it('should concatenate two iterators', () => {
+        const a = ExtraIterator.from([1, 2]);
+        const b = ExtraIterator.from([3, 4]);
+        const concatenated = a.concat(b);
+        expect(concatenated.toArray()).toEqual([1, 2, 3, 4]);
+    });
+    it('should prepend a value to the iterator', () => {
+        const iterator = ExtraIterator.from([2, 3]).prepend(1);
+        expect(iterator.toArray()).toEqual([1, 2, 3]);
+    });
+    it('should append a value to the iterator', () => {
+        const iterator = ExtraIterator.from([1, 2]).append(3);
+        expect(iterator.toArray()).toEqual([1, 2, 3]);
+    });
+    it('should take values while a predicate is true', () => {
+        const iterator = ExtraIterator.from([1, 2, 3, 4]).takeWhile(x => x < 3);
+        expect(iterator.toArray()).toEqual([1, 2]);
+    });
+    it('should drop values while a predicate is true', () => {
+        const iterator = ExtraIterator.from([1, 2, 3, 4]).dropWhile(x => x < 3);
+        expect(iterator.toArray()).toEqual([3, 4]);
+    });
+    it('should interleave two iterators', () => {
+        const a = ExtraIterator.from([1, 3]);
+        const b = ExtraIterator.from([2, 4]);
+        const interleaved = a.interleave(b);
+        expect(interleaved.toArray()).toEqual([1, 2, 3, 4]);
+    });
+    it('should splice values in the iterator', () => {
+        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 group values by a key', () => {
+        const iterator = ExtraIterator.from(['apple', 'banana', 'apricot']);
+        const grouped = iterator.groupBy(word => word[0]);
+        expect(grouped).toEqual({
+            a: ['apple', 'apricot'],
+            b: ['banana'],
+        });
+    });
+    it('should collect values using a custom collector', () => {
+        const iterator = ExtraIterator.from([1, 2, 3]);
+        const sum = iterator.collect(iter => Array.from(iter).reduce((a, b) => a + b, 0));
+        expect(sum).toBe(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.2.1",
+  "version": "0.3.1",
   "type": "module",
   "exports": {
     ".": "./dist/index.js",
@@ -13,13 +13,18 @@
     "dist"
   ],
   "scripts": {
-    "test": "node --test **/*.test.js",
+    "test": "run-s test:types test:unit",
+    "test:types": "tsc --noEmit",
+    "test:unit": "node --import=tsx --test **/*.test.ts",
     "build": "tsc",
     "prebuild": "rimraf dist",
-    "prepack": "npm run build"
+    "prepack": "run-s test build"
   },
   "devDependencies": {
+    "expect": "^29.7.0",
+    "npm-run-all": "^4.1.5",
     "rimraf": "^6.0.1",
+    "tsx": "^4.19.3",
     "typescript": "^5.8.3"
   },
   "keywords": [