functional-examples 0.0.0-alpha.1

package/dist/types/extended-iterable.d.ts

@@ -0,0 +1,197 @@
+import { TypeGuard } from './guards.js';
+/**
+ * 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 declare class ExtendedIterable<T> implements Iterable<T> {
+    private _iterFn;
+    constructor(iterable: Iterable<T>);
+    private static _from;
+    /**
+     * 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(): ExtendedIterable<T extends Iterable<infer U> ? U : T>;
+    /**
+     * Maps each element through a transformation function.
+     * Evaluation is lazy - the function is called only when iterating.
+     */
+    map<T2>(fn: (val: T) => T2): ExtendedIterable<T2>;
+    filter(predicate: (val: T) => boolean): ExtendedIterable<T>;
+    filter<T2>(predicate: (val: T) => TypeGuard<T2>): ExtendedIterable<T2>;
+    /**
+     * Takes the first n elements.
+     */
+    take(n: number): ExtendedIterable<T>;
+    /**
+     * Tests whether at least one element passes the predicate.
+     * Short-circuits on first match.
+     * Supports both sync and async predicates - returns Promise if predicate is async.
+     */
+    some(predicate: (val: T) => boolean): boolean;
+    some(predicate: (val: T) => Promise<boolean>): Promise<boolean>;
+    /**
+     * Returns the first element that passes the predicate, or undefined.
+     * Short-circuits on first match.
+     * Supports both sync and async predicates - returns Promise if predicate is async.
+     */
+    find(predicate: (val: T) => boolean): T | undefined;
+    find(predicate: (val: T) => Promise<boolean>): Promise<T | undefined>;
+    /**
+     * Reduces the iterable to a single value by applying a function against
+     * an accumulator and each element.
+     *
+     * Without an initial value, the first element is used as the accumulator
+     * and reduction starts from the second element. Throws TypeError on empty iterables.
+     *
+     * @example
+     * ```typescript
+     * iter([1, 2, 3]).reduce((sum, n) => sum + n);        // 6
+     * iter([1, 2, 3]).reduce((sum, n) => sum + n, 10);    // 16
+     * ```
+     */
+    reduce(fn: (acc: T, val: T) => T): T;
+    reduce<U>(fn: (acc: U, val: T) => U, initialValue: U): U;
+    /**
+     * Collects all elements into an array.
+     */
+    collect(): T[];
+    /**
+     * Joins all elements into a string with a separator.
+     * Elements are converted to strings using toString().
+     */
+    join(separator: string): string;
+    /**
+     * Prepends an iterable to the start of this iterable.
+     */
+    prefix<U>(prefix: Iterable<U>): ExtendedIterable<T | U>;
+    /**
+     * 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: (val: T) => boolean, deleteCount: number, insertIterable: Iterable<T>): {
+        deleted: ExtendedIterable<T>;
+        sliced: ExtendedIterable<T>;
+    };
+    [Symbol.iterator](): Iterator<T>;
+}
+export declare class AsyncExtendedIterable<T> implements AsyncIterable<T> {
+    private asyncIterable;
+    constructor(iterable: AsyncIterable<T> | Iterable<T>);
+    /**
+     * 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<T2>(fn: (val: T) => T2 | Promise<T2>): AsyncExtendedIterable<T2>;
+    filter(predicate: (val: T) => boolean | Promise<boolean>): AsyncExtendedIterable<T>;
+    filter<T2 = unknown>(predicate: (val: T) => TypeGuard<T2>): AsyncExtendedIterable<T2>;
+    /**
+     * Reduces the async iterable to a single value.
+     * Without an initial value, the first element is used as the accumulator.
+     * Throws TypeError on empty iterables when no initial value is provided.
+     */
+    reduce(fn: (acc: T, val: T) => T | Promise<T>): Promise<T>;
+    reduce<U>(fn: (acc: U, val: T) => U | Promise<U>, initialValue: U): Promise<U>;
+    /**
+     * Collects all elements into an array.
+     */
+    collect(): Promise<T[]>;
+    /**
+     * Joins all elements into a string with a separator.
+     * Elements are converted to strings using String().
+     */
+    join(separator: string): Promise<string>;
+    /**
+     * Takes the first n elements.
+     */
+    take(n: number): AsyncExtendedIterable<T>;
+    /**
+     * Tests whether at least one element passes the predicate.
+     * Short-circuits on first match. Predicate can be sync or async.
+     */
+    some(predicate: (val: T) => boolean | Promise<boolean>): Promise<boolean>;
+    /**
+     * Returns the first element that passes the predicate, or undefined.
+     * Short-circuits on first match. Predicate can be sync or async.
+     */
+    find(predicate: (val: T) => boolean | Promise<boolean>): Promise<T | 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.
+     */
+    splice(matcher: (val: T) => boolean | Promise<boolean>, deleteCount: number, insertIterable: AsyncIterable<T> | Iterable<T>): Promise<{
+        deleted: AsyncExtendedIterable<T>;
+        sliced: AsyncExtendedIterable<T>;
+    }>;
+    [Symbol.asyncIterator](): AsyncIterator<T>;
+}
+/**
+ * Helper to create an AsyncExtendedIterable from any iterable.
+ */
+export declare function asyncIter<T>(iterable: AsyncIterable<T> | Iterable<T>): AsyncExtendedIterable<T>;
+/**
+ * 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 declare function asSettled<T>(promises: Iterable<Promise<T>>): AsyncExtendedIterable<PromiseSettledResult<T>>;
+/**
+ * Helper to create an ExtendedIterable from any iterable.
+ */
+export declare function iter<T>(iterable: Iterable<T>): ExtendedIterable<T>;
+//# sourceMappingURL=extended-iterable.d.ts.map

package/dist/types/extended-iterable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extended-iterable.d.ts","sourceRoot":"","sources":["../../src/types/extended-iterable.ts"],"names":[],"mappings":"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"}