functional-examples 0.0.0-alpha.1

package/dist/types/extended-iterable.js

@@ -0,0 +1,769 @@
+// Shared done sentinel to reduce allocations
+const DONE = { done: true, value: undefined };
+// --- Sync iterator classes ---
+// Classes give V8 stable hidden classes and monomorphic inline caches on next(),
+// which outperforms plain object factories on chained operations.
+class MapIterator {
+    source;
+    fn;
+    r = { done: false, value: undefined };
+    constructor(source, fn) {
+        this.source = source;
+        this.fn = fn;
+    }
+    next() {
+        const result = this.source.next();
+        if (result.done)
+            return DONE;
+        this.r.value = this.fn(result.value);
+        return this.r;
+    }
+    [Symbol.iterator]() {
+        return this;
+    }
+}
+class FilterIterator {
+    source;
+    fn;
+    r = { done: false, value: undefined };
+    constructor(source, fn) {
+        this.source = source;
+        this.fn = fn;
+    }
+    next() {
+        while (true) {
+            const result = this.source.next();
+            if (result.done)
+                return DONE;
+            if (this.fn(result.value)) {
+                this.r.value = result.value;
+                return this.r;
+            }
+        }
+    }
+    [Symbol.iterator]() {
+        return this;
+    }
+}
+class TakeIterator {
+    source;
+    n;
+    r = { done: false, value: undefined };
+    count = 0;
+    constructor(source, n) {
+        this.source = source;
+        this.n = n;
+    }
+    next() {
+        if (this.count >= this.n)
+            return DONE;
+        const result = this.source.next();
+        if (result.done)
+            return DONE;
+        this.count++;
+        this.r.value = result.value;
+        return this.r;
+    }
+    [Symbol.iterator]() {
+        return this;
+    }
+}
+class FlatIterator {
+    source;
+    r = { done: false, value: undefined };
+    inner = null;
+    constructor(source) {
+        this.source = source;
+    }
+    next() {
+        while (true) {
+            if (this.inner) {
+                const result = this.inner.next();
+                if (!result.done) {
+                    this.r.value = result.value;
+                    return this.r;
+                }
+                this.inner = null;
+            }
+            const result = this.source.next();
+            if (result.done)
+                return DONE;
+            const value = result.value;
+            if (value != null &&
+                typeof value !== 'string' &&
+                typeof value[Symbol.iterator] === 'function') {
+                this.inner = value[Symbol.iterator]();
+            }
+            else {
+                this.r.value = value;
+                return this.r;
+            }
+        }
+    }
+    [Symbol.iterator]() {
+        return this;
+    }
+}
+class PrefixIterator {
+    source;
+    prefixIt;
+    constructor(prefix, source) {
+        this.source = source;
+        this.prefixIt = prefix[Symbol.iterator]();
+    }
+    next() {
+        if (this.prefixIt) {
+            const result = this.prefixIt.next();
+            if (!result.done)
+                return result;
+            this.prefixIt = null;
+        }
+        return this.source.next();
+    }
+    [Symbol.iterator]() {
+        return this;
+    }
+}
+// --- Async iterator classes ---
+class AsyncMapIterator {
+    source;
+    fn;
+    constructor(source, fn) {
+        this.source = source;
+        this.fn = fn;
+    }
+    async next() {
+        const result = await this.source.next();
+        if (result.done)
+            return DONE;
+        return { done: false, value: await this.fn(result.value) };
+    }
+    [Symbol.asyncIterator]() {
+        return this;
+    }
+}
+class AsyncFilterIterator {
+    source;
+    fn;
+    constructor(source, fn) {
+        this.source = source;
+        this.fn = fn;
+    }
+    async next() {
+        while (true) {
+            const result = await this.source.next();
+            if (result.done)
+                return DONE;
+            if (await this.fn(result.value))
+                return { done: false, value: result.value };
+        }
+    }
+    [Symbol.asyncIterator]() {
+        return this;
+    }
+}
+class AsyncTakeIterator {
+    source;
+    n;
+    count = 0;
+    constructor(source, n) {
+        this.source = source;
+        this.n = n;
+    }
+    async next() {
+        if (this.count >= this.n)
+            return DONE;
+        const result = await this.source.next();
+        if (result.done)
+            return DONE;
+        this.count++;
+        return result;
+    }
+    [Symbol.asyncIterator]() {
+        return this;
+    }
+}
+function createSpliceGenerators(source, matcher, deleteCount, insertIterable) {
+    const state = {
+        phase: 'seeking',
+        deletedCache: [],
+        slicedCache: [],
+        deletedPtr: 0,
+        slicedPtr: 0,
+        deleteRemaining: deleteCount,
+        insertIterator: null,
+        sourceIterator: source[Symbol.iterator](),
+    };
+    function* slicedGenerator() {
+        while (true) {
+            while (state.slicedPtr < state.slicedCache.length) {
+                yield state.slicedCache[state.slicedPtr++];
+            }
+            if (state.phase === 'seeking') {
+                const next = state.sourceIterator.next();
+                if (next.done) {
+                    state.phase = 'done';
+                    return;
+                }
+                const val = next.value;
+                if (matcher(val)) {
+                    state.phase = 'deleting';
+                    state.deletedCache.push(val);
+                    state.deleteRemaining--;
+                }
+                else {
+                    state.slicedCache.push(val);
+                    state.slicedPtr++;
+                    yield val;
+                }
+            }
+            else if (state.phase === 'deleting') {
+                if (state.deleteRemaining > 0) {
+                    const next = state.sourceIterator.next();
+                    if (next.done) {
+                        state.phase = 'done';
+                        return;
+                    }
+                    state.deletedCache.push(next.value);
+                    state.deleteRemaining--;
+                }
+                else {
+                    state.phase = 'inserting';
+                    state.insertIterator = insertIterable[Symbol.iterator]();
+                }
+            }
+            else if (state.phase === 'inserting') {
+                if (state.insertIterator === null) {
+                    state.insertIterator = insertIterable[Symbol.iterator]();
+                }
+                const next = state.insertIterator.next();
+                if (next.done) {
+                    state.phase = 'done';
+                }
+                else {
+                    state.slicedCache.push(next.value);
+                    state.slicedPtr++;
+                    yield next.value;
+                }
+            }
+            else if (state.phase === 'done') {
+                const next = state.sourceIterator.next();
+                if (next.done)
+                    return;
+                state.slicedCache.push(next.value);
+                state.slicedPtr++;
+                yield next.value;
+            }
+        }
+    }
+    function* deletedGenerator() {
+        while (true) {
+            while (state.deletedPtr < state.deletedCache.length) {
+                yield state.deletedCache[state.deletedPtr++];
+            }
+            if (state.phase === 'seeking' || state.phase === 'deleting') {
+                const slicedIter = slicedGenerator();
+                let result = slicedIter.next();
+                // slicedGenerator mutates state.phase as it iterates, so re-read
+                // through the full type to avoid TS narrowing from the outer `if`.
+                while (!result.done && state.phase !== 'done') {
+                    result = slicedIter.next();
+                }
+            }
+            if (state.deletedPtr >= state.deletedCache.length) {
+                if (state.phase === 'done' || state.phase === 'inserting')
+                    return;
+            }
+        }
+    }
+    return {
+        sliced: slicedGenerator(),
+        deleted: deletedGenerator(),
+    };
+}
+async function createAsyncSpliceGenerators(source, matcher, deleteCount, insertIterable) {
+    const state = {
+        phase: 'seeking',
+        deletedCache: [],
+        slicedCache: [],
+        deletedPtr: 0,
+        slicedPtr: 0,
+        deleteRemaining: deleteCount,
+        insertIterator: null,
+        sourceIterator: source[Symbol.asyncIterator](),
+    };
+    async function* slicedGenerator() {
+        while (true) {
+            while (state.slicedPtr < state.slicedCache.length) {
+                yield state.slicedCache[state.slicedPtr++];
+            }
+            if (state.phase === 'seeking') {
+                const next = await state.sourceIterator.next();
+                if (next.done) {
+                    state.phase = 'done';
+                    return;
+                }
+                const val = next.value;
+                if (await matcher(val)) {
+                    state.phase = 'deleting';
+                    state.deletedCache.push(val);
+                    state.deleteRemaining--;
+                }
+                else {
+                    state.slicedCache.push(val);
+                    state.slicedPtr++;
+                    yield val;
+                }
+            }
+            else if (state.phase === 'deleting') {
+                if (state.deleteRemaining > 0) {
+                    const next = await state.sourceIterator.next();
+                    if (next.done) {
+                        state.phase = 'done';
+                        return;
+                    }
+                    state.deletedCache.push(next.value);
+                    state.deleteRemaining--;
+                }
+                else {
+                    state.phase = 'inserting';
+                    state.insertIterator = insertIterable[Symbol.asyncIterator]();
+                }
+            }
+            else if (state.phase === 'inserting') {
+                if (state.insertIterator === null) {
+                    state.insertIterator = insertIterable[Symbol.asyncIterator]();
+                }
+                const next = await state.insertIterator.next();
+                if (next.done) {
+                    state.phase = 'done';
+                }
+                else {
+                    state.slicedCache.push(next.value);
+                    state.slicedPtr++;
+                    yield next.value;
+                }
+            }
+            else if (state.phase === 'done') {
+                const next = await state.sourceIterator.next();
+                if (next.done)
+                    return;
+                state.slicedCache.push(next.value);
+                state.slicedPtr++;
+                yield next.value;
+            }
+        }
+    }
+    async function* deletedGenerator() {
+        while (true) {
+            while (state.deletedPtr < state.deletedCache.length) {
+                yield state.deletedCache[state.deletedPtr++];
+            }
+            if (state.phase === 'seeking' || state.phase === 'deleting') {
+                const slicedIter = slicedGenerator();
+                let result = await slicedIter.next();
+                // slicedGenerator mutates state.phase as it iterates, so re-read
+                // through the full type to avoid TS narrowing from the outer `if`.
+                while (!result.done &&
+                    state.phase !== 'done') {
+                    result = await slicedIter.next();
+                }
+            }
+            if (state.deletedPtr >= state.deletedCache.length) {
+                if (state.phase === 'done' || state.phase === 'inserting')
+                    return;
+            }
+        }
+    }
+    return {
+        sliced: slicedGenerator(),
+        deleted: deletedGenerator(),
+    };
+}
+function asyncIterableFrom(factory) {
+    return { [Symbol.asyncIterator]: factory };
+}
+/**
+ * A wrapper around Iterable that provides chainable transformation methods.
+ * Each method returns a new ExtendedIterable wrapping the source,
+ * mirroring how Array methods work but with lazy evaluation.
+ *
+ * @example
+ * ```typescript
+ * const numbers = new ExtendedIterable([1, 2, 3]);
+ * const doubled = numbers.map(x => x * 2).collect(); // [2, 4, 6]
+ *
+ * // Works with any iterable, including generators
+ * const result = new ExtendedIterable(myGenerator())
+ *   .map(transform)
+ *   .join(', ');
+ * ```
+ */
+export class ExtendedIterable {
+    _iterFn;
+    constructor(iterable) {
+        // Store a factory so we can create fresh iterators on each iteration.
+        // For iterables that are already single-use (generators), this preserves
+        // the existing behavior — iterating twice just yields nothing the second time.
+        this._iterFn = () => iterable[Symbol.iterator]();
+    }
+    // Internal: create from a factory directly, skipping the iterable wrapper
+    static _from(factory) {
+        const inst = Object.create(ExtendedIterable.prototype);
+        inst._iterFn = factory;
+        return inst;
+    }
+    /**
+     * Flattens one level of nesting by yielding elements from nested iterables.
+     * Non-iterable values are yielded as-is. Strings are not split into characters.
+     */
+    flat() {
+        const parentIter = this._iterFn;
+        return ExtendedIterable._from(() => new FlatIterator(parentIter()));
+    }
+    /**
+     * Maps each element through a transformation function.
+     * Evaluation is lazy - the function is called only when iterating.
+     */
+    map(fn) {
+        const parentIter = this._iterFn;
+        return ExtendedIterable._from(() => new MapIterator(parentIter(), fn));
+    }
+    /**
+     * Filters elements using a predicate function.
+     * Supports type guards for narrowing.
+     */
+    filter(predicate) {
+        const parentIter = this._iterFn;
+        return ExtendedIterable._from(() => new FilterIterator(parentIter(), predicate));
+    }
+    /**
+     * Takes the first n elements.
+     */
+    take(n) {
+        const parentIter = this._iterFn;
+        return ExtendedIterable._from(() => new TakeIterator(parentIter(), n));
+    }
+    some(predicate) {
+        const iterator = this[Symbol.iterator]();
+        const processAsync = async (pending) => {
+            if (await pending)
+                return true;
+            for (let next = iterator.next(); !next.done; next = iterator.next()) {
+                if (await predicate(next.value))
+                    return true;
+            }
+            return false;
+        };
+        for (let next = iterator.next(); !next.done; next = iterator.next()) {
+            const result = predicate(next.value);
+            if (result instanceof Promise) {
+                return processAsync(result);
+            }
+            if (result)
+                return true;
+        }
+        return false;
+    }
+    find(predicate) {
+        const iterator = this[Symbol.iterator]();
+        const processAsync = async (currentVal, pending) => {
+            if (await pending)
+                return currentVal;
+            for (let next = iterator.next(); !next.done; next = iterator.next()) {
+                if (await predicate(next.value))
+                    return next.value;
+            }
+            return undefined;
+        };
+        for (let next = iterator.next(); !next.done; next = iterator.next()) {
+            const result = predicate(next.value);
+            if (result instanceof Promise) {
+                return processAsync(next.value, result);
+            }
+            if (result)
+                return next.value;
+        }
+        return undefined;
+    }
+    reduce(fn, ...rest) {
+        const it = this[Symbol.iterator]();
+        let acc;
+        if (rest.length > 0) {
+            acc = rest[0];
+        }
+        else {
+            const first = it.next();
+            if (first.done) {
+                throw new TypeError('Reduce of empty iterable with no initial value');
+            }
+            acc = first.value;
+        }
+        for (let r = it.next(); !r.done; r = it.next()) {
+            acc = fn(acc, r.value);
+        }
+        return acc;
+    }
+    /**
+     * Collects all elements into an array.
+     */
+    collect() {
+        const arr = [];
+        const it = this[Symbol.iterator]();
+        for (let r = it.next(); !r.done; r = it.next()) {
+            arr.push(r.value);
+        }
+        return arr;
+    }
+    /**
+     * Joins all elements into a string with a separator.
+     * Elements are converted to strings using toString().
+     */
+    join(separator) {
+        const it = this[Symbol.iterator]();
+        let r = it.next();
+        if (r.done)
+            return '';
+        let str = String(r.value);
+        for (r = it.next(); !r.done; r = it.next()) {
+            str += separator + String(r.value);
+        }
+        return str;
+    }
+    /**
+     * Prepends an iterable to the start of this iterable.
+     */
+    prefix(prefix) {
+        const parentIter = this._iterFn;
+        return ExtendedIterable._from(() => new PrefixIterator(prefix, parentIter()));
+    }
+    /**
+     * Removes elements from the iterable and optionally inserts new elements.
+     * Returns both the modified iterable and the deleted elements.
+     * Both iterables share state - iterating either will cache results for the other.
+     *
+     * @param matcher - Predicate to find the splice position
+     * @param deleteCount - Number of elements to remove after the match
+     * @param insertIterable - Elements to insert after removing
+     * @returns Object with `sliced` (modified iterable) and `deleted` (removed elements)
+     *
+     * @example
+     * ```typescript
+     * const { deleted, sliced } = iter([1, 2, 3, 4, 5])
+     *   .splice((el) => el === 3, 2, iter([10, 20]));
+     * sliced.collect();  // [1, 2, 10, 20, 5]
+     * deleted.collect(); // [3, 4]
+     * ```
+     */
+    splice(matcher, deleteCount, insertIterable) {
+        const { sliced, deleted } = createSpliceGenerators(this, matcher, deleteCount, insertIterable);
+        return {
+            sliced: new ExtendedIterable(sliced),
+            deleted: new ExtendedIterable(deleted),
+        };
+    }
+    [Symbol.iterator]() {
+        return this._iterFn();
+    }
+}
+export class AsyncExtendedIterable {
+    asyncIterable;
+    constructor(iterable) {
+        if (Symbol.asyncIterator in iterable) {
+            this.asyncIterable = iterable;
+        }
+        else {
+            const syncIterable = iterable;
+            this.asyncIterable = {
+                async *[Symbol.asyncIterator]() {
+                    for (const val of syncIterable) {
+                        yield val;
+                    }
+                },
+            };
+        }
+    }
+    /**
+     * Maps each element through a transformation function.
+     * The function can be sync or async.
+     * Evaluation is lazy - the function is called only when iterating.
+     */
+    map(fn) {
+        const source = this.asyncIterable;
+        return new AsyncExtendedIterable(asyncIterableFrom(() => new AsyncMapIterator(source[Symbol.asyncIterator](), fn)));
+    }
+    /**
+     * Filters elements using a predicate function.
+     * The predicate can be sync or async.
+     */
+    filter(predicate) {
+        const source = this.asyncIterable;
+        return new AsyncExtendedIterable(asyncIterableFrom(() => new AsyncFilterIterator(source[Symbol.asyncIterator](), predicate)));
+    }
+    async reduce(fn, ...rest) {
+        const it = this[Symbol.asyncIterator]();
+        let acc;
+        if (rest.length > 0) {
+            acc = rest[0];
+        }
+        else {
+            const first = await it.next();
+            if (first.done) {
+                throw new TypeError('Reduce of empty iterable with no initial value');
+            }
+            acc = first.value;
+        }
+        for (let r = await it.next(); !r.done; r = await it.next()) {
+            acc = await fn(acc, r.value);
+        }
+        return acc;
+    }
+    /**
+     * Collects all elements into an array.
+     */
+    async collect() {
+        const arr = [];
+        for await (const val of this) {
+            arr.push(val);
+        }
+        return arr;
+    }
+    /**
+     * Joins all elements into a string with a separator.
+     * Elements are converted to strings using String().
+     */
+    async join(separator) {
+        const arr = await this.collect();
+        return arr.map(String).join(separator);
+    }
+    /**
+     * Takes the first n elements.
+     */
+    take(n) {
+        const source = this.asyncIterable;
+        return new AsyncExtendedIterable(asyncIterableFrom(() => new AsyncTakeIterator(source[Symbol.asyncIterator](), n)));
+    }
+    /**
+     * Tests whether at least one element passes the predicate.
+     * Short-circuits on first match. Predicate can be sync or async.
+     */
+    async some(predicate) {
+        for await (const val of this) {
+            if (await predicate(val)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * Returns the first element that passes the predicate, or undefined.
+     * Short-circuits on first match. Predicate can be sync or async.
+     */
+    async find(predicate) {
+        for await (const val of this) {
+            if (await predicate(val)) {
+                return val;
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Removes elements from the async iterable and optionally inserts new elements.
+     * Returns both the modified iterable and the deleted elements.
+     * Both iterables share state - iterating either will cache results for the other.
+     */
+    async splice(matcher, deleteCount, insertIterable) {
+        const asyncInsert = Symbol.asyncIterator in insertIterable
+            ? insertIterable
+            : {
+                async *[Symbol.asyncIterator]() {
+                    for (const val of insertIterable) {
+                        yield val;
+                    }
+                },
+            };
+        const { sliced, deleted } = await createAsyncSpliceGenerators(this, matcher, deleteCount, asyncInsert);
+        return {
+            sliced: new AsyncExtendedIterable(sliced),
+            deleted: new AsyncExtendedIterable(deleted),
+        };
+    }
+    [Symbol.asyncIterator]() {
+        return this.asyncIterable[Symbol.asyncIterator]();
+    }
+}
+/**
+ * Helper to create an AsyncExtendedIterable from any iterable.
+ */
+export function asyncIter(iterable) {
+    return new AsyncExtendedIterable(iterable);
+}
+/**
+ * Returns an AsyncExtendedIterable that yields promise results as they settle,
+ * in completion order (not input order).
+ *
+ * Like Promise.allSettled, but streaming - you get results as soon as they're ready,
+ * with full chaining support.
+ *
+ * @example
+ * ```typescript
+ * const promises = [
+ *   fetch('/slow'),   // takes 3s
+ *   fetch('/fast'),   // takes 1s
+ *   fetch('/medium'), // takes 2s
+ * ];
+ *
+ * // Results arrive in order: fast, medium, slow
+ * for await (const result of asSettled(promises)) {
+ *   if (result.status === 'fulfilled') {
+ *     console.log('Got:', result.value);
+ *   } else {
+ *     console.log('Failed:', result.reason);
+ *   }
+ * }
+ *
+ * // Chain operations
+ * const firstThreeSuccesses = await asSettled(promises)
+ *   .filter(r => r.status === 'fulfilled')
+ *   .map(r => (r as PromiseFulfilledResult<Response>).value)
+ *   .take(3)
+ *   .collect();
+ * ```
+ */
+export function asSettled(promises) {
+    return new AsyncExtendedIterable(asSettledGen(promises));
+}
+async function* asSettledGen(promises) {
+    const queue = [];
+    let notifyReady = null;
+    let remaining = 0;
+    for (const p of promises) {
+        remaining++;
+        Promise.resolve(p).then((value) => {
+            queue.push({ status: 'fulfilled', value });
+            notifyReady?.();
+        }, (reason) => {
+            queue.push({ status: 'rejected', reason });
+            notifyReady?.();
+        });
+    }
+    while (remaining > 0) {
+        if (queue.length === 0) {
+            await new Promise((resolve) => {
+                notifyReady = resolve;
+            });
+            notifyReady = null;
+        }
+        while (queue.length > 0 && remaining > 0) {
+            yield queue.shift();
+            remaining--;
+        }
+    }
+}
+/**
+ * Helper to create an ExtendedIterable from any iterable.
+ */
+export function iter(iterable) {
+    return new ExtendedIterable(iterable);
+}
+//# sourceMappingURL=extended-iterable.js.map