iterflow 0.2.2

package/dist/index.d.ts

@@ -0,0 +1,2264 @@
+/**
+ * A fluent interface wrapper for working with iterators and iterables.
+ * Provides chainable methods for transforming, filtering, and analyzing data streams.
+ *
+ * @template T The type of elements in the iterator
+ * @example
+ * ```typescript
+ * const result = new iterflow([1, 2, 3, 4, 5])
+ *   .filter(x => x % 2 === 0)
+ *   .map(x => x * 2)
+ *   .toArray(); // [4, 8]
+ * ```
+ */
+declare class iterflow<T> implements Iterable<T> {
+    private source;
+    /**
+     * Creates a new iterflow instance from an iterable or iterator.
+     *
+     * @param source - The source iterable or iterator to wrap
+     * @example
+     * ```typescript
+     * const flow1 = new iterflow([1, 2, 3]);
+     * const flow2 = new iterflow(someIterator);
+     * ```
+     */
+    constructor(source: Iterable<T> | Iterator<T>);
+    /**
+     * Returns the iterator for this iterflow instance.
+     * This allows iterflow to be used in for...of loops.
+     *
+     * @returns The underlying iterator
+     */
+    [Symbol.iterator](): Iterator<T>;
+    /**
+     * Retrieves the next value from the iterator.
+     *
+     * @returns An IteratorResult containing the next value or indicating completion
+     */
+    next(): IteratorResult<T>;
+    /**
+     * Transforms each element using the provided function.
+     *
+     * @template U The type of the transformed elements
+     * @param fn - Function to transform each element
+     * @returns A new iterflow with transformed elements
+     * @example
+     * ```typescript
+     * iter([1, 2, 3]).map(x => x * 2).toArray(); // [2, 4, 6]
+     * ```
+     */
+    map<U>(fn: (value: T) => U): iterflow<U>;
+    /**
+     * Filters elements based on a predicate function.
+     * Only elements for which the predicate returns true are included.
+     *
+     * @param predicate - Function to test each element
+     * @returns A new iterflow with only elements that pass the predicate
+     * @example
+     * ```typescript
+     * iter([1, 2, 3, 4]).filter(x => x % 2 === 0).toArray(); // [2, 4]
+     * ```
+     */
+    filter(predicate: (value: T) => boolean): iterflow<T>;
+    /**
+     * Takes only the first `limit` elements from the iterator.
+     *
+     * @param limit - Maximum number of elements to take
+     * @returns A new iterflow with at most `limit` elements
+     * @example
+     * ```typescript
+     * iter([1, 2, 3, 4, 5]).take(3).toArray(); // [1, 2, 3]
+     * ```
+     */
+    take(limit: number): iterflow<T>;
+    /**
+     * Skips the first `count` elements from the iterator.
+     *
+     * @param count - Number of elements to skip
+     * @returns A new iterflow without the first `count` elements
+     * @example
+     * ```typescript
+     * iter([1, 2, 3, 4, 5]).drop(2).toArray(); // [3, 4, 5]
+     * ```
+     */
+    drop(count: number): iterflow<T>;
+    /**
+     * Maps each element to an iterable and flattens the results into a single iterator.
+     *
+     * @template U The type of elements in the resulting iterator
+     * @param fn - Function that maps each element to an iterable
+     * @returns A new iterflow with all mapped iterables flattened
+     * @example
+     * ```typescript
+     * iter([1, 2, 3]).flatMap(x => [x, x * 2]).toArray(); // [1, 2, 2, 4, 3, 6]
+     * ```
+     */
+    flatMap<U>(fn: (value: T) => Iterable<U>): iterflow<U>;
+    /**
+     * Concatenates multiple iterators sequentially.
+     * Yields all elements from this iterator, then from each provided iterator.
+     *
+     * @param iterables - Additional iterables to concatenate
+     * @returns A new iterflow with all elements from all iterables
+     * @example
+     * ```typescript
+     * iter([1, 2]).concat([3, 4], [5, 6]).toArray();
+     * // [1, 2, 3, 4, 5, 6]
+     * ```
+     */
+    concat(...iterables: Iterable<T>[]): iterflow<T>;
+    /**
+     * Inserts a separator element between each item.
+     * The separator is not added before the first element or after the last.
+     *
+     * @param separator - The element to insert between items
+     * @returns A new iterflow with separators interspersed
+     * @example
+     * ```typescript
+     * iter([1, 2, 3]).intersperse(0).toArray();
+     * // [1, 0, 2, 0, 3]
+     * iter(['a', 'b', 'c']).intersperse('-').toArray();
+     * // ['a', '-', 'b', '-', 'c']
+     * ```
+     */
+    intersperse(separator: T): iterflow<T>;
+    /**
+     * Like reduce, but emits all intermediate accumulator values.
+     * Similar to reduce but returns an iterator of partial results.
+     *
+     * @template U The type of the accumulated value
+     * @param fn - Function to combine the accumulator with each element
+     * @param initial - The initial value for the accumulator
+     * @returns A new iterflow of intermediate accumulator values
+     * @example
+     * ```typescript
+     * iter([1, 2, 3, 4]).scan((acc, x) => acc + x, 0).toArray();
+     * // [0, 1, 3, 6, 10]
+     * iter([1, 2, 3]).scan((acc, x) => acc * x, 1).toArray();
+     * // [1, 1, 2, 6]
+     * ```
+     */
+    scan<U>(fn: (accumulator: U, value: T) => U, initial: U): iterflow<U>;
+    /**
+     * Adds index as tuple with each element [index, value].
+     * Creates tuples pairing each element with its zero-based index.
+     *
+     * @returns A new iterflow of tuples containing [index, value]
+     * @example
+     * ```typescript
+     * iter(['a', 'b', 'c']).enumerate().toArray();
+     * // [[0, 'a'], [1, 'b'], [2, 'c']]
+     * ```
+     */
+    enumerate(): iterflow<[number, T]>;
+    /**
+     * Reverses the iterator order.
+     * Warning: This operation buffers all elements in memory and may cause
+     * performance issues with large iterables. Consider using only when necessary.
+     *
+     * @returns A new iterflow with elements in reverse order
+     * @example
+     * ```typescript
+     * iter([1, 2, 3, 4, 5]).reverse().toArray();
+     * // [5, 4, 3, 2, 1]
+     * ```
+     */
+    reverse(): iterflow<T>;
+    /**
+     * Sorts elements using default comparison.
+     * Numbers are sorted numerically, strings lexicographically.
+     * Warning: This operation buffers all elements in memory. Avoid chaining
+     * with other buffering operations (reverse, sort, sortBy) for better performance.
+     *
+     * @param this - iterflow instance constrained to numbers or strings
+     * @returns A new iterflow with elements sorted
+     * @example
+     * ```typescript
+     * iter([3, 1, 4, 1, 5]).sort().toArray();
+     * // [1, 1, 3, 4, 5]
+     * iter(['c', 'a', 'b']).sort().toArray();
+     * // ['a', 'b', 'c']
+     * ```
+     */
+    sort(this: iterflow<number | string>): iterflow<number | string>;
+    /**
+     * Sorts elements using a custom comparison function.
+     * Warning: This operation buffers all elements in memory. Avoid chaining
+     * with other buffering operations (reverse, sort, sortBy) for better performance.
+     *
+     * @param compareFn - Function that compares two elements (returns negative if a < b, 0 if equal, positive if a > b)
+     * @returns A new iterflow with elements sorted
+     * @example
+     * ```typescript
+     * iter([3, 1, 4, 1, 5]).sortBy((a, b) => a - b).toArray();
+     * // [1, 1, 3, 4, 5]
+     * iter([3, 1, 4, 1, 5]).sortBy((a, b) => b - a).toArray();
+     * // [5, 4, 3, 1, 1]
+     * iter(['alice', 'bob', 'charlie']).sortBy((a, b) => a.length - b.length).toArray();
+     * // ['bob', 'alice', 'charlie']
+     * ```
+     */
+    sortBy(compareFn: (a: T, b: T) => number): iterflow<T>;
+    /**
+     * Collects all elements into an array.
+     * This is a terminal operation that consumes the iterator.
+     *
+     * @returns An array containing all elements
+     * @example
+     * ```typescript
+     * iter([1, 2, 3]).map(x => x * 2).toArray(); // [2, 4, 6]
+     * ```
+     */
+    toArray(): T[];
+    /**
+     * Counts the total number of elements in the iterator.
+     * This is a terminal operation that consumes the iterator.
+     *
+     * @returns The total count of elements
+     * @example
+     * ```typescript
+     * iter([1, 2, 3, 4, 5]).count(); // 5
+     * ```
+     */
+    count(): number;
+    /**
+     * Calculates the sum of all numeric elements.
+     * This method is only available when T is number.
+     * This is a terminal operation that consumes the iterator.
+     *
+     * @param this - iterflow instance constrained to numbers
+     * @returns The sum of all elements
+     * @example
+     * ```typescript
+     * iter([1, 2, 3, 4, 5]).sum(); // 15
+     * ```
+     */
+    sum(this: iterflow<number>): number;
+    /**
+     * Calculates the arithmetic mean (average) of all numeric elements.
+     * This method is only available when T is number.
+     * This is a terminal operation that consumes the iterator.
+     *
+     * @param this - iterflow instance constrained to numbers
+     * @returns The mean value, or undefined if the iterator is empty
+     * @example
+     * ```typescript
+     * iter([1, 2, 3, 4, 5]).mean(); // 3
+     * iter([]).mean(); // undefined
+     * ```
+     */
+    mean(this: iterflow<number>): number | undefined;
+    /**
+     * Finds the minimum value among all numeric elements.
+     * This method is only available when T is number.
+     * This is a terminal operation that consumes the iterator.
+     *
+     * @param this - iterflow instance constrained to numbers
+     * @returns The minimum value, or undefined if the iterator is empty
+     * @example
+     * ```typescript
+     * iter([3, 1, 4, 1, 5]).min(); // 1
+     * iter([]).min(); // undefined
+     * ```
+     */
+    min(this: iterflow<number>): number | undefined;
+    /**
+     * Finds the maximum value among all numeric elements.
+     * This method is only available when T is number.
+     * This is a terminal operation that consumes the iterator.
+     *
+     * @param this - iterflow instance constrained to numbers
+     * @returns The maximum value, or undefined if the iterator is empty
+     * @example
+     * ```typescript
+     * iter([3, 1, 4, 1, 5]).max(); // 5
+     * iter([]).max(); // undefined
+     * ```
+     */
+    max(this: iterflow<number>): number | undefined;
+    /**
+     * Calculates the median value of all numeric elements.
+     * The median is the middle value when elements are sorted.
+     * This method is only available when T is number.
+     * This is a terminal operation that consumes the iterator.
+     *
+     * @param this - iterflow instance constrained to numbers
+     * @returns The median value, or undefined if the iterator is empty
+     * @example
+     * ```typescript
+     * iter([1, 2, 3, 4, 5]).median(); // 3
+     * iter([1, 2, 3, 4]).median(); // 2.5
+     * iter([]).median(); // undefined
+     * ```
+     */
+    median(this: iterflow<number>): number | undefined;
+    /**
+     * Calculates the variance of all numeric elements.
+     * Variance measures how far each number in the set is from the mean.
+     * This method is only available when T is number.
+     * This is a terminal operation that consumes the iterator.
+     *
+     * @param this - iterflow instance constrained to numbers
+     * @returns The variance, or undefined if the iterator is empty
+     * @example
+     * ```typescript
+     * iter([1, 2, 3, 4, 5]).variance(); // 2
+     * iter([]).variance(); // undefined
+     * ```
+     */
+    variance(this: iterflow<number>): number | undefined;
+    /**
+     * Calculates the standard deviation of all numeric elements.
+     * Standard deviation is the square root of variance and measures dispersion.
+     * This method is only available when T is number.
+     * This is a terminal operation that consumes the iterator.
+     *
+     * @param this - iterflow instance constrained to numbers
+     * @returns The standard deviation, or undefined if the iterator is empty
+     * @example
+     * ```typescript
+     * iter([2, 4, 4, 4, 5, 5, 7, 9]).stdDev(); // ~2
+     * iter([]).stdDev(); // undefined
+     * ```
+     */
+    stdDev(this: iterflow<number>): number | undefined;
+    /**
+     * Calculates the specified percentile of all numeric elements.
+     * Uses linear interpolation between closest ranks.
+     * This method is only available when T is number.
+     * This is a terminal operation that consumes the iterator.
+     *
+     * @param this - iterflow instance constrained to numbers
+     * @param p - The percentile to calculate (0-100)
+     * @returns The percentile value, or undefined if the iterator is empty
+     * @throws {Error} If p is not between 0 and 100
+     * @example
+     * ```typescript
+     * iter([1, 2, 3, 4, 5]).percentile(50); // 3 (median)
+     * iter([1, 2, 3, 4, 5]).percentile(75); // 4
+     * iter([]).percentile(50); // undefined
+     * ```
+     */
+    percentile(this: iterflow<number>, p: number): number | undefined;
+    /**
+     * Finds the most frequent value(s) in the dataset.
+     * Returns an array of all values that appear most frequently.
+     * This method is only available when T is number.
+     * This is a terminal operation that consumes the iterator.
+     *
+     * @param this - iterflow instance constrained to numbers
+     * @returns An array of the most frequent value(s), or undefined if the iterator is empty
+     * @example
+     * ```typescript
+     * iter([1, 2, 2, 3, 3, 3]).mode(); // [3]
+     * iter([1, 1, 2, 2, 3]).mode(); // [1, 2] (bimodal)
+     * iter([]).mode(); // undefined
+     * ```
+     */
+    mode(this: iterflow<number>): number[] | undefined;
+    /**
+     * Calculates the quartiles (Q1, Q2, Q3) of all numeric elements.
+     * Q1 is the 25th percentile, Q2 is the median (50th percentile), Q3 is the 75th percentile.
+     * This method is only available when T is number.
+     * This is a terminal operation that consumes the iterator.
+     *
+     * @param this - iterflow instance constrained to numbers
+     * @returns An object with Q1, Q2, and Q3 values, or undefined if the iterator is empty
+     * @example
+     * ```typescript
+     * iter([1, 2, 3, 4, 5, 6, 7, 8, 9]).quartiles();
+     * // { Q1: 3, Q2: 5, Q3: 7 }
+     * iter([]).quartiles(); // undefined
+     * ```
+     */
+    quartiles(this: iterflow<number>): {
+        Q1: number;
+        Q2: number;
+        Q3: number;
+    } | undefined;
+    /**
+     * Calculates the span (range from minimum to maximum value) of all numeric elements.
+     * This method is only available when T is number.
+     * This is a terminal operation that consumes the iterator.
+     *
+     * @param this - iterflow instance constrained to numbers
+     * @returns The span (max - min), or undefined if the iterator is empty
+     * @example
+     * ```typescript
+     * iter([1, 2, 3, 4, 5]).span(); // 4
+     * iter([10]).span(); // 0
+     * iter([]).span(); // undefined
+     * ```
+     */
+    span(this: iterflow<number>): number | undefined;
+    /**
+     * Calculates the product of all numeric elements.
+     * This method is only available when T is number.
+     * This is a terminal operation that consumes the iterator.
+     *
+     * @param this - iterflow instance constrained to numbers
+     * @returns The product of all elements, or 1 if the iterator is empty
+     * @example
+     * ```typescript
+     * iter([1, 2, 3, 4, 5]).product(); // 120
+     * iter([2, 3, 4]).product(); // 24
+     * iter([]).product(); // 1
+     * ```
+     */
+    product(this: iterflow<number>): number;
+    /**
+     * Calculates the covariance between two numeric sequences.
+     * Covariance measures the joint variability of two random variables.
+     * This method is only available when T is number.
+     * This is a terminal operation that consumes the iterator.
+     *
+     * @param this - iterflow instance constrained to numbers
+     * @param other - An iterable of numbers to compare with
+     * @returns The covariance, or undefined if either sequence is empty or sequences have different lengths
+     * @example
+     * ```typescript
+     * iter([1, 2, 3, 4, 5]).covariance([2, 4, 6, 8, 10]); // 4
+     * iter([]).covariance([1, 2, 3]); // undefined
+     * ```
+     */
+    covariance(this: iterflow<number>, other: Iterable<number>): number | undefined;
+    /**
+     * Calculates the Pearson correlation coefficient between two numeric sequences.
+     * Correlation measures the strength and direction of the linear relationship between two variables.
+     * Values range from -1 (perfect negative correlation) to 1 (perfect positive correlation).
+     * This method is only available when T is number.
+     * This is a terminal operation that consumes the iterator.
+     *
+     * @param this - iterflow instance constrained to numbers
+     * @param other - An iterable of numbers to compare with
+     * @returns The correlation coefficient, or undefined if either sequence is empty or sequences have different lengths
+     * @example
+     * ```typescript
+     * iter([1, 2, 3, 4, 5]).correlation([2, 4, 6, 8, 10]); // 1 (perfect positive correlation)
+     * iter([1, 2, 3]).correlation([3, 2, 1]); // -1 (perfect negative correlation)
+     * iter([]).correlation([1, 2, 3]); // undefined
+     * ```
+     */
+    correlation(this: iterflow<number>, other: Iterable<number>): number | undefined;
+    /**
+     * Creates a sliding window of the specified size over the elements.
+     * Each window contains `size` consecutive elements.
+     *
+     * @param size - The size of each window (must be at least 1)
+     * @returns A new iterflow of arrays, each containing `size` consecutive elements
+     * @throws {Error} If size is less than 1
+     * @example
+     * ```typescript
+     * iter([1, 2, 3, 4, 5]).window(3).toArray();
+     * // [[1, 2, 3], [2, 3, 4], [3, 4, 5]]
+     * ```
+     */
+    window(size: number): iterflow<T[]>;
+    /**
+     * Splits elements into chunks of the specified size.
+     * Unlike window, chunks don't overlap. The last chunk may be smaller.
+     *
+     * @param size - The size of each chunk (must be at least 1)
+     * @returns A new iterflow of arrays, each containing up to `size` elements
+     * @throws {Error} If size is less than 1
+     * @example
+     * ```typescript
+     * iter([1, 2, 3, 4, 5]).chunk(2).toArray();
+     * // [[1, 2], [3, 4], [5]]
+     * ```
+     */
+    chunk(size: number): iterflow<T[]>;
+    /**
+     * Creates pairs of consecutive elements.
+     * Equivalent to window(2) but returns tuples instead of arrays.
+     *
+     * @returns A new iterflow of tuples, each containing two consecutive elements
+     * @example
+     * ```typescript
+     * iter([1, 2, 3, 4]).pairwise().toArray();
+     * // [[1, 2], [2, 3], [3, 4]]
+     * ```
+     */
+    pairwise(): iterflow<[T, T]>;
+    /**
+     * Removes duplicate elements, keeping only the first occurrence of each.
+     * Uses strict equality (===) to compare elements.
+     *
+     * @returns A new iterflow with duplicate elements removed
+     * @example
+     * ```typescript
+     * iter([1, 2, 2, 3, 1, 4]).distinct().toArray();
+     * // [1, 2, 3, 4]
+     * ```
+     */
+    distinct(): iterflow<T>;
+    /**
+     * Removes duplicate elements based on a key function.
+     * Keeps only the first occurrence of each unique key.
+     *
+     * @template K The type of the key used for comparison
+     * @param keyFn - Function to extract the comparison key from each element
+     * @returns A new iterflow with duplicate elements (by key) removed
+     * @example
+     * ```typescript
+     * const users = [{id: 1, name: 'Alice'}, {id: 2, name: 'Bob'}, {id: 1, name: 'Charlie'}];
+     * iter(users).distinctBy(u => u.id).toArray();
+     * // [{id: 1, name: 'Alice'}, {id: 2, name: 'Bob'}]
+     * ```
+     */
+    distinctBy<K>(keyFn: (value: T) => K): iterflow<T>;
+    /**
+     * Executes a side-effect function on each element without modifying the stream.
+     * Useful for debugging or performing operations like logging.
+     *
+     * @param fn - Function to execute for each element
+     * @returns A new iterflow with the same elements
+     * @example
+     * ```typescript
+     * iter([1, 2, 3])
+     *   .tap(x => console.log('Processing:', x))
+     *   .map(x => x * 2)
+     *   .toArray(); // logs each value, returns [2, 4, 6]
+     * ```
+     */
+    tap(fn: (value: T) => void): iterflow<T>;
+    /**
+     * Takes elements while the predicate returns true, then stops.
+     * Stops at the first element that fails the predicate.
+     *
+     * @param predicate - Function to test each element
+     * @returns A new iterflow with elements up to the first failing predicate
+     * @example
+     * ```typescript
+     * iter([1, 2, 3, 4, 1, 2]).takeWhile(x => x < 4).toArray();
+     * // [1, 2, 3]
+     * ```
+     */
+    takeWhile(predicate: (value: T) => boolean): iterflow<T>;
+    /**
+     * Skips elements while the predicate returns true, then yields all remaining elements.
+     * Starts yielding from the first element that fails the predicate.
+     *
+     * @param predicate - Function to test each element
+     * @returns A new iterflow starting from the first element that fails the predicate
+     * @example
+     * ```typescript
+     * iter([1, 2, 3, 4, 1, 2]).dropWhile(x => x < 3).toArray();
+     * // [3, 4, 1, 2]
+     * ```
+     */
+    dropWhile(predicate: (value: T) => boolean): iterflow<T>;
+    /**
+     * Splits elements into two arrays based on a predicate.
+     * This is a terminal operation that consumes the iterator.
+     *
+     * @param predicate - Function to test each element
+     * @returns A tuple of two arrays: [elements passing predicate, elements failing predicate]
+     * @example
+     * ```typescript
+     * iter([1, 2, 3, 4, 5]).partition(x => x % 2 === 0);
+     * // [[2, 4], [1, 3, 5]]
+     * ```
+     */
+    partition(predicate: (value: T) => boolean): [T[], T[]];
+    /**
+     * Groups elements by a key function into a Map.
+     * This is a terminal operation that consumes the iterator.
+     *
+     * @template K The type of the grouping key
+     * @param keyFn - Function to extract the grouping key from each element
+     * @returns A Map where keys are the result of keyFn and values are arrays of elements
+     * @example
+     * ```typescript
+     * iter(['alice', 'bob', 'charlie', 'dave'])
+     *   .groupBy(name => name.length);
+     * // Map { 3 => ['bob'], 5 => ['alice'], 7 => ['charlie'], 4 => ['dave'] }
+     * ```
+     */
+    groupBy<K>(keyFn: (value: T) => K): Map<K, T[]>;
+    /**
+     * Reduces the iterator to a single value using an accumulator function.
+     * This is a terminal operation that consumes the iterator.
+     *
+     * @template U The type of the accumulated value
+     * @param fn - Function to combine the accumulator with each element
+     * @param initial - The initial value for the accumulator
+     * @returns The final accumulated value
+     * @example
+     * ```typescript
+     * iter([1, 2, 3, 4]).reduce((acc, x) => acc + x, 0); // 10
+     * iter(['a', 'b', 'c']).reduce((acc, x) => acc + x, ''); // 'abc'
+     * ```
+     */
+    reduce<U>(fn: (accumulator: U, value: T) => U, initial: U): U;
+    /**
+     * Finds the first element that matches the predicate.
+     * This is a terminal operation that may consume part of the iterator.
+     *
+     * @param predicate - Function to test each element
+     * @returns The first matching element, or undefined if none found
+     * @example
+     * ```typescript
+     * iter([1, 2, 3, 4, 5]).find(x => x > 3); // 4
+     * iter([1, 2, 3]).find(x => x > 10); // undefined
+     * ```
+     */
+    find(predicate: (value: T) => boolean): T | undefined;
+    /**
+     * Finds the index of the first element that matches the predicate.
+     * This is a terminal operation that may consume part of the iterator.
+     *
+     * @param predicate - Function to test each element
+     * @returns The index of the first matching element, or -1 if none found
+     * @example
+     * ```typescript
+     * iter([1, 2, 3, 4, 5]).findIndex(x => x > 3); // 3
+     * iter([1, 2, 3]).findIndex(x => x > 10); // -1
+     * ```
+     */
+    findIndex(predicate: (value: T) => boolean): number;
+    /**
+     * Tests whether at least one element matches the predicate.
+     * This is a terminal operation that may consume part of the iterator.
+     *
+     * @param predicate - Function to test each element
+     * @returns true if any element matches, false otherwise
+     * @example
+     * ```typescript
+     * iter([1, 2, 3, 4, 5]).some(x => x > 3); // true
+     * iter([1, 2, 3]).some(x => x > 10); // false
+     * ```
+     */
+    some(predicate: (value: T) => boolean): boolean;
+    /**
+     * Tests whether all elements match the predicate.
+     * This is a terminal operation that may consume part or all of the iterator.
+     *
+     * @param predicate - Function to test each element
+     * @returns true if all elements match, false otherwise
+     * @example
+     * ```typescript
+     * iter([2, 4, 6]).every(x => x % 2 === 0); // true
+     * iter([1, 2, 3]).every(x => x % 2 === 0); // false
+     * ```
+     */
+    every(predicate: (value: T) => boolean): boolean;
+    /**
+     * Executes a function for each element in the iterator.
+     * This is a terminal operation that consumes the entire iterator.
+     *
+     * @param fn - Function to execute for each element
+     * @example
+     * ```typescript
+     * iter([1, 2, 3]).forEach(x => console.log(x));
+     * // Logs: 1, 2, 3
+     * ```
+     */
+    forEach(fn: (value: T) => void): void;
+    /**
+     * Gets the first element from the iterator.
+     * This is a terminal operation that consumes the first element.
+     *
+     * @param defaultValue - Optional default value to return if iterator is empty
+     * @returns The first element, the default value, or undefined if empty and no default
+     * @example
+     * ```typescript
+     * iter([1, 2, 3]).first(); // 1
+     * iter([]).first(); // undefined
+     * iter([]).first(0); // 0
+     * ```
+     */
+    first(defaultValue?: T): T | undefined;
+    /**
+     * Gets the last element from the iterator.
+     * This is a terminal operation that consumes the entire iterator.
+     *
+     * @param defaultValue - Optional default value to return if iterator is empty
+     * @returns The last element, the default value, or undefined if empty and no default
+     * @example
+     * ```typescript
+     * iter([1, 2, 3]).last(); // 3
+     * iter([]).last(); // undefined
+     * iter([]).last(0); // 0
+     * ```
+     */
+    last(defaultValue?: T): T | undefined;
+    /**
+     * Gets the element at the specified index.
+     * This is a terminal operation that may consume part of the iterator.
+     *
+     * @param index - Zero-based index of the element to retrieve
+     * @returns The element at the index, or undefined if index is out of bounds
+     * @example
+     * ```typescript
+     * iter([1, 2, 3, 4, 5]).nth(2); // 3
+     * iter([1, 2, 3]).nth(10); // undefined
+     * iter([1, 2, 3]).nth(-1); // undefined
+     * ```
+     */
+    nth(index: number): T | undefined;
+    /**
+     * Checks if the iterator is empty.
+     * This is a terminal operation that may consume the first element.
+     *
+     * @returns true if the iterator has no elements, false otherwise
+     * @example
+     * ```typescript
+     * iter([]).isEmpty(); // true
+     * iter([1, 2, 3]).isEmpty(); // false
+     * ```
+     */
+    isEmpty(): boolean;
+    /**
+     * Checks if the iterator includes a specific value.
+     * Uses strict equality (===) for comparison.
+     * This is a terminal operation that may consume part or all of the iterator.
+     *
+     * @param searchValue - The value to search for
+     * @returns true if the value is found, false otherwise
+     * @example
+     * ```typescript
+     * iter([1, 2, 3, 4, 5]).includes(3); // true
+     * iter([1, 2, 3]).includes(10); // false
+     * iter(['a', 'b', 'c']).includes('b'); // true
+     * ```
+     */
+    includes(searchValue: T): boolean;
+    /**
+     * Alias for stdDev() method for compatibility.
+     * Calculates the standard deviation of all numeric elements.
+     */
+    stddev(this: iterflow<number>): number | undefined;
+    /**
+     * Alias for drop() method for compatibility.
+     * Skips the first `count` elements from the iterator.
+     */
+    skip(count: number): iterflow<T>;
+    /**
+     * Interleaves elements from this iterator with elements from other iterables.
+     * Takes one element from each iterable in round-robin fashion.
+     *
+     * @param others - Variable number of iterables to interleave with
+     * @returns A new iterflow with elements from all iterables interleaved
+     * @example
+     * ```typescript
+     * iter([1, 2, 3]).interleave([4, 5, 6]).toArray(); // [1, 4, 2, 5, 3, 6]
+     * ```
+     */
+    interleave(...others: Iterable<T>[]): iterflow<T>;
+    /**
+     * Merges this iterator with other sorted iterables into a single sorted iterator.
+     * Assumes all input iterables are already sorted in ascending order.
+     *
+     * @param others - Variable number of sorted iterables to merge with
+     * @returns A new iterflow with all elements merged in sorted order
+     * @example
+     * ```typescript
+     * iter([1, 3, 5]).merge([2, 4, 6]).toArray(); // [1, 2, 3, 4, 5, 6]
+     * ```
+     */
+    merge(...others: Iterable<T>[]): iterflow<T>;
+}
+
+/**
+ * A fluent interface wrapper for working with async iterators and async iterables.
+ * Provides chainable methods for transforming, filtering, and analyzing async data streams.
+ *
+ * @template T The type of elements in the async iterator
+ * @example
+ * ```typescript
+ * const result = await new Asynciterflow(asyncIterable)
+ *   .filter(async x => x % 2 === 0)
+ *   .map(async x => x * 2)
+ *   .toArray(); // [4, 8]
+ * ```
+ */
+declare class Asynciterflow<T> implements AsyncIterable<T> {
+    private source;
+    /**
+     * Creates a new async iterflow instance from an async iterable or async iterator.
+     *
+     * @param source - The source async iterable or async iterator to wrap
+     * @example
+     * ```typescript
+     * const flow1 = new Asynciterflow(asyncIterable);
+     * const flow2 = new Asynciterflow(asyncIterator);
+     * ```
+     */
+    constructor(source: AsyncIterable<T> | AsyncIterator<T>);
+    /**
+     * Returns the async iterator for this iterflow instance.
+     * This allows iterflow to be used in for await...of loops.
+     *
+     * @returns The underlying async iterator
+     */
+    [Symbol.asyncIterator](): AsyncIterator<T>;
+    /**
+     * Retrieves the next value from the async iterator.
+     *
+     * @returns A promise of an IteratorResult containing the next value or indicating completion
+     */
+    next(): Promise<IteratorResult<T>>;
+    /**
+     * Transforms each element using the provided async or sync function.
+     *
+     * @template U The type of the transformed elements
+     * @param fn - Async or sync function to transform each element
+     * @returns A new async iterflow with transformed elements
+     * @example
+     * ```typescript
+     * await asyncIter([1, 2, 3]).map(async x => x * 2).toArray(); // [2, 4, 6]
+     * ```
+     */
+    map<U>(fn: (value: T) => U | Promise<U>): Asynciterflow<U>;
+    /**
+     * Filters elements based on an async or sync predicate function.
+     * Only elements for which the predicate returns true are included.
+     *
+     * @param predicate - Async or sync function to test each element
+     * @returns A new async iterflow with only elements that pass the predicate
+     * @example
+     * ```typescript
+     * await asyncIter([1, 2, 3, 4]).filter(async x => x % 2 === 0).toArray(); // [2, 4]
+     * ```
+     */
+    filter(predicate: (value: T) => boolean | Promise<boolean>): Asynciterflow<T>;
+    /**
+     * Takes only the first `limit` elements from the async iterator.
+     *
+     * @param limit - Maximum number of elements to take
+     * @returns A new async iterflow with at most `limit` elements
+     * @example
+     * ```typescript
+     * await asyncIter([1, 2, 3, 4, 5]).take(3).toArray(); // [1, 2, 3]
+     * ```
+     */
+    take(limit: number): Asynciterflow<T>;
+    /**
+     * Skips the first `count` elements from the async iterator.
+     *
+     * @param count - Number of elements to skip
+     * @returns A new async iterflow without the first `count` elements
+     * @example
+     * ```typescript
+     * await asyncIter([1, 2, 3, 4, 5]).drop(2).toArray(); // [3, 4, 5]
+     * ```
+     */
+    drop(count: number): Asynciterflow<T>;
+    /**
+     * Maps each element to an async iterable and flattens the results.
+     *
+     * @template U The type of elements in the resulting iterator
+     * @param fn - Async or sync function that maps each element to an async iterable
+     * @returns A new async iterflow with all mapped iterables flattened
+     * @example
+     * ```typescript
+     * await asyncIter([1, 2, 3]).flatMap(async x => [x, x * 2]).toArray(); // [1, 2, 2, 4, 3, 6]
+     * ```
+     */
+    flatMap<U>(fn: (value: T) => AsyncIterable<U> | Iterable<U> | Promise<AsyncIterable<U> | Iterable<U>>): Asynciterflow<U>;
+    /**
+     * Concatenates multiple async iterators sequentially.
+     *
+     * @param iterables - Additional async iterables to concatenate
+     * @returns A new async iterflow with all elements from all iterables
+     * @example
+     * ```typescript
+     * await asyncIter([1, 2]).concat([3, 4], [5, 6]).toArray();
+     * // [1, 2, 3, 4, 5, 6]
+     * ```
+     */
+    concat(...iterables: Array<AsyncIterable<T> | Iterable<T>>): Asynciterflow<T>;
+    /**
+     * Inserts a separator element between each item.
+     *
+     * @param separator - The element to insert between items
+     * @returns A new async iterflow with separators interspersed
+     * @example
+     * ```typescript
+     * await asyncIter([1, 2, 3]).intersperse(0).toArray();
+     * // [1, 0, 2, 0, 3]
+     * ```
+     */
+    intersperse(separator: T): Asynciterflow<T>;
+    /**
+     * Like reduce, but emits all intermediate accumulator values.
+     *
+     * @template U The type of the accumulated value
+     * @param fn - Async or sync function to combine the accumulator with each element
+     * @param initial - The initial value for the accumulator
+     * @returns A new async iterflow of intermediate accumulator values
+     * @example
+     * ```typescript
+     * await asyncIter([1, 2, 3, 4]).scan((acc, x) => acc + x, 0).toArray();
+     * // [0, 1, 3, 6, 10]
+     * ```
+     */
+    scan<U>(fn: (accumulator: U, value: T) => U | Promise<U>, initial: U): Asynciterflow<U>;
+    /**
+     * Adds index as tuple with each element [index, value].
+     *
+     * @returns A new async iterflow of tuples containing [index, value]
+     * @example
+     * ```typescript
+     * await asyncIter(['a', 'b', 'c']).enumerate().toArray();
+     * // [[0, 'a'], [1, 'b'], [2, 'c']]
+     * ```
+     */
+    enumerate(): Asynciterflow<[number, T]>;
+    /**
+     * Reverses the async iterator order.
+     * Warning: This operation buffers all elements in memory.
+     *
+     * @returns A new async iterflow with elements in reverse order
+     * @example
+     * ```typescript
+     * await asyncIter([1, 2, 3, 4, 5]).reverse().toArray();
+     * // [5, 4, 3, 2, 1]
+     * ```
+     */
+    reverse(): Asynciterflow<T>;
+    /**
+     * Sorts elements using default comparison.
+     * Warning: This operation buffers all elements in memory.
+     *
+     * @param this - async iterflow instance constrained to numbers or strings
+     * @returns A new async iterflow with elements sorted
+     * @example
+     * ```typescript
+     * await asyncIter([3, 1, 4, 1, 5]).sort().toArray();
+     * // [1, 1, 3, 4, 5]
+     * ```
+     */
+    sort(this: Asynciterflow<number | string>): Asynciterflow<number | string>;
+    /**
+     * Sorts elements using a custom comparison function.
+     * Warning: This operation buffers all elements in memory.
+     *
+     * @param compareFn - Function that compares two elements
+     * @returns A new async iterflow with elements sorted
+     * @example
+     * ```typescript
+     * await asyncIter([3, 1, 4, 1, 5]).sortBy((a, b) => a - b).toArray();
+     * // [1, 1, 3, 4, 5]
+     * ```
+     */
+    sortBy(compareFn: (a: T, b: T) => number): Asynciterflow<T>;
+    /**
+     * Collects all elements into an array.
+     * This is a terminal operation that consumes the async iterator.
+     *
+     * @returns A promise of an array containing all elements
+     * @example
+     * ```typescript
+     * await asyncIter([1, 2, 3]).map(async x => x * 2).toArray(); // [2, 4, 6]
+     * ```
+     */
+    toArray(): Promise<T[]>;
+    /**
+     * Counts the total number of elements in the async iterator.
+     * This is a terminal operation that consumes the async iterator.
+     *
+     * @returns A promise of the total count of elements
+     * @example
+     * ```typescript
+     * await asyncIter([1, 2, 3, 4, 5]).count(); // 5
+     * ```
+     */
+    count(): Promise<number>;
+    /**
+     * Executes a function for each element.
+     * This is a terminal operation that consumes the async iterator.
+     *
+     * @param fn - Async or sync function to execute for each element
+     * @returns A promise that resolves when all elements have been processed
+     * @example
+     * ```typescript
+     * await asyncIter([1, 2, 3]).forEach(async x => console.log(x));
+     * ```
+     */
+    forEach(fn: (value: T) => void | Promise<void>): Promise<void>;
+    /**
+     * Calculates the sum of all numeric elements.
+     * This is a terminal operation that consumes the async iterator.
+     *
+     * @param this - async iterflow instance constrained to numbers
+     * @returns A promise of the sum of all elements
+     * @example
+     * ```typescript
+     * await asyncIter([1, 2, 3, 4, 5]).sum(); // 15
+     * ```
+     */
+    sum(this: Asynciterflow<number>): Promise<number>;
+    /**
+     * Calculates the arithmetic mean (average) of all numeric elements.
+     * This is a terminal operation that consumes the async iterator.
+     *
+     * @param this - async iterflow instance constrained to numbers
+     * @returns A promise of the mean value, or undefined if empty
+     * @example
+     * ```typescript
+     * await asyncIter([1, 2, 3, 4, 5]).mean(); // 3
+     * ```
+     */
+    mean(this: Asynciterflow<number>): Promise<number | undefined>;
+    /**
+     * Finds the minimum value among all numeric elements.
+     * This is a terminal operation that consumes the async iterator.
+     *
+     * @param this - async iterflow instance constrained to numbers
+     * @returns A promise of the minimum value, or undefined if empty
+     * @example
+     * ```typescript
+     * await asyncIter([3, 1, 4, 1, 5]).min(); // 1
+     * ```
+     */
+    min(this: Asynciterflow<number>): Promise<number | undefined>;
+    /**
+     * Finds the maximum value among all numeric elements.
+     * This is a terminal operation that consumes the async iterator.
+     *
+     * @param this - async iterflow instance constrained to numbers
+     * @returns A promise of the maximum value, or undefined if empty
+     * @example
+     * ```typescript
+     * await asyncIter([3, 1, 4, 1, 5]).max(); // 5
+     * ```
+     */
+    max(this: Asynciterflow<number>): Promise<number | undefined>;
+    /**
+     * Calculates the median value of all numeric elements.
+     * This is a terminal operation that consumes the async iterator.
+     *
+     * @param this - async iterflow instance constrained to numbers
+     * @returns A promise of the median value, or undefined if empty
+     * @example
+     * ```typescript
+     * await asyncIter([1, 2, 3, 4, 5]).median(); // 3
+     * ```
+     */
+    median(this: Asynciterflow<number>): Promise<number | undefined>;
+    /**
+     * Calculates the variance of all numeric elements.
+     * This is a terminal operation that consumes the async iterator.
+     *
+     * @param this - async iterflow instance constrained to numbers
+     * @returns A promise of the variance, or undefined if empty
+     * @example
+     * ```typescript
+     * await asyncIter([1, 2, 3, 4, 5]).variance(); // 2
+     * ```
+     */
+    variance(this: Asynciterflow<number>): Promise<number | undefined>;
+    /**
+     * Calculates the standard deviation of all numeric elements.
+     * This is a terminal operation that consumes the async iterator.
+     *
+     * @param this - async iterflow instance constrained to numbers
+     * @returns A promise of the standard deviation, or undefined if empty
+     * @example
+     * ```typescript
+     * await asyncIter([2, 4, 4, 4, 5, 5, 7, 9]).stdDev(); // ~2
+     * ```
+     */
+    stdDev(this: Asynciterflow<number>): Promise<number | undefined>;
+    /**
+     * Calculates the specified percentile of all numeric elements.
+     * This is a terminal operation that consumes the async iterator.
+     *
+     * @param this - async iterflow instance constrained to numbers
+     * @param p - The percentile to calculate (0-100)
+     * @returns A promise of the percentile value, or undefined if empty
+     * @throws {Error} If p is not between 0 and 100
+     * @example
+     * ```typescript
+     * await asyncIter([1, 2, 3, 4, 5]).percentile(50); // 3
+     * ```
+     */
+    percentile(this: Asynciterflow<number>, p: number): Promise<number | undefined>;
+    /**
+     * Finds the most frequent value(s) in the dataset.
+     * This is a terminal operation that consumes the async iterator.
+     *
+     * @param this - async iterflow instance constrained to numbers
+     * @returns A promise of an array of the most frequent value(s), or undefined if empty
+     * @example
+     * ```typescript
+     * await asyncIter([1, 2, 2, 3, 3, 3]).mode(); // [3]
+     * ```
+     */
+    mode(this: Asynciterflow<number>): Promise<number[] | undefined>;
+    /**
+     * Calculates the quartiles (Q1, Q2, Q3) of all numeric elements.
+     * This is a terminal operation that consumes the async iterator.
+     *
+     * @param this - async iterflow instance constrained to numbers
+     * @returns A promise of an object with Q1, Q2, and Q3 values, or undefined if empty
+     * @example
+     * ```typescript
+     * await asyncIter([1, 2, 3, 4, 5, 6, 7, 8, 9]).quartiles();
+     * // { Q1: 3, Q2: 5, Q3: 7 }
+     * ```
+     */
+    quartiles(this: Asynciterflow<number>): Promise<{
+        Q1: number;
+        Q2: number;
+        Q3: number;
+    } | undefined>;
+    /**
+     * Calculates the span (range from minimum to maximum value).
+     * This is a terminal operation that consumes the async iterator.
+     *
+     * @param this - async iterflow instance constrained to numbers
+     * @returns A promise of the span (max - min), or undefined if empty
+     * @example
+     * ```typescript
+     * await asyncIter([1, 2, 3, 4, 5]).span(); // 4
+     * ```
+     */
+    span(this: Asynciterflow<number>): Promise<number | undefined>;
+    /**
+     * Calculates the product of all numeric elements.
+     * This is a terminal operation that consumes the async iterator.
+     *
+     * @param this - async iterflow instance constrained to numbers
+     * @returns A promise of the product of all elements
+     * @example
+     * ```typescript
+     * await asyncIter([1, 2, 3, 4, 5]).product(); // 120
+     * ```
+     */
+    product(this: Asynciterflow<number>): Promise<number>;
+    /**
+     * Calculates the covariance between two numeric sequences.
+     * This is a terminal operation that consumes the async iterator.
+     *
+     * @param this - async iterflow instance constrained to numbers
+     * @param other - An async iterable of numbers to compare with
+     * @returns A promise of the covariance, or undefined if sequences are empty or have different lengths
+     * @example
+     * ```typescript
+     * await asyncIter([1, 2, 3, 4, 5]).covariance([2, 4, 6, 8, 10]); // 4
+     * ```
+     */
+    covariance(this: Asynciterflow<number>, other: AsyncIterable<number> | Iterable<number>): Promise<number | undefined>;
+    /**
+     * Calculates the Pearson correlation coefficient between two numeric sequences.
+     * This is a terminal operation that consumes the async iterator.
+     *
+     * @param this - async iterflow instance constrained to numbers
+     * @param other - An async iterable of numbers to compare with
+     * @returns A promise of the correlation coefficient, or undefined if sequences are empty or have different lengths
+     * @example
+     * ```typescript
+     * await asyncIter([1, 2, 3, 4, 5]).correlation([2, 4, 6, 8, 10]); // 1
+     * ```
+     */
+    correlation(this: Asynciterflow<number>, other: AsyncIterable<number> | Iterable<number>): Promise<number | undefined>;
+    /**
+     * Creates a sliding window of the specified size over the elements.
+     *
+     * @param size - The size of each window
+     * @returns A new async iterflow of arrays, each containing `size` consecutive elements
+     * @throws {Error} If size is less than 1
+     * @example
+     * ```typescript
+     * await asyncIter([1, 2, 3, 4, 5]).window(3).toArray();
+     * // [[1, 2, 3], [2, 3, 4], [3, 4, 5]]
+     * ```
+     */
+    window(size: number): Asynciterflow<T[]>;
+    /**
+     * Splits elements into chunks of the specified size.
+     *
+     * @param size - The size of each chunk
+     * @returns A new async iterflow of arrays, each containing up to `size` elements
+     * @throws {Error} If size is less than 1
+     * @example
+     * ```typescript
+     * await asyncIter([1, 2, 3, 4, 5]).chunk(2).toArray();
+     * // [[1, 2], [3, 4], [5]]
+     * ```
+     */
+    chunk(size: number): Asynciterflow<T[]>;
+    /**
+     * Creates pairs of consecutive elements.
+     *
+     * @returns A new async iterflow of tuples, each containing two consecutive elements
+     * @example
+     * ```typescript
+     * await asyncIter([1, 2, 3, 4]).pairwise().toArray();
+     * // [[1, 2], [2, 3], [3, 4]]
+     * ```
+     */
+    pairwise(): Asynciterflow<[T, T]>;
+    /**
+     * Removes duplicate elements, keeping only the first occurrence.
+     *
+     * @returns A new async iterflow with duplicate elements removed
+     * @example
+     * ```typescript
+     * await asyncIter([1, 2, 2, 3, 1, 4]).distinct().toArray();
+     * // [1, 2, 3, 4]
+     * ```
+     */
+    distinct(): Asynciterflow<T>;
+    /**
+     * Removes duplicate elements based on a key function.
+     *
+     * @template K The type of the key used for comparison
+     * @param keyFn - Async or sync function to extract the comparison key
+     * @returns A new async iterflow with duplicate elements (by key) removed
+     * @example
+     * ```typescript
+     * const users = [{id: 1, name: 'Alice'}, {id: 2, name: 'Bob'}, {id: 1, name: 'Charlie'}];
+     * await asyncIter(users).distinctBy(async u => u.id).toArray();
+     * // [{id: 1, name: 'Alice'}, {id: 2, name: 'Bob'}]
+     * ```
+     */
+    distinctBy<K>(keyFn: (value: T) => K | Promise<K>): Asynciterflow<T>;
+    /**
+     * Executes a side-effect function on each element without modifying the stream.
+     *
+     * @param fn - Async or sync function to execute for each element
+     * @returns A new async iterflow with the same elements
+     * @example
+     * ```typescript
+     * await asyncIter([1, 2, 3])
+     *   .tap(async x => console.log('Processing:', x))
+     *   .map(async x => x * 2)
+     *   .toArray(); // logs each value, returns [2, 4, 6]
+     * ```
+     */
+    tap(fn: (value: T) => void | Promise<void>): Asynciterflow<T>;
+    /**
+     * Takes elements while the predicate returns true, then stops.
+     *
+     * @param predicate - Async or sync function to test each element
+     * @returns A new async iterflow with elements up to the first failing predicate
+     * @example
+     * ```typescript
+     * await asyncIter([1, 2, 3, 4, 1, 2]).takeWhile(async x => x < 4).toArray();
+     * // [1, 2, 3]
+     * ```
+     */
+    takeWhile(predicate: (value: T) => boolean | Promise<boolean>): Asynciterflow<T>;
+    /**
+     * Skips elements while the predicate returns true, then yields all remaining.
+     *
+     * @param predicate - Async or sync function to test each element
+     * @returns A new async iterflow starting from the first element that fails the predicate
+     * @example
+     * ```typescript
+     * await asyncIter([1, 2, 3, 4, 1, 2]).dropWhile(async x => x < 3).toArray();
+     * // [3, 4, 1, 2]
+     * ```
+     */
+    dropWhile(predicate: (value: T) => boolean | Promise<boolean>): Asynciterflow<T>;
+    /**
+     * Splits elements into two arrays based on a predicate.
+     * This is a terminal operation that consumes the async iterator.
+     *
+     * @param predicate - Async or sync function to test each element
+     * @returns A promise of a tuple of two arrays
+     * @example
+     * ```typescript
+     * await asyncIter([1, 2, 3, 4, 5]).partition(async x => x % 2 === 0);
+     * // [[2, 4], [1, 3, 5]]
+     * ```
+     */
+    partition(predicate: (value: T) => boolean | Promise<boolean>): Promise<[T[], T[]]>;
+    /**
+     * Groups elements by a key function into a Map.
+     * This is a terminal operation that consumes the async iterator.
+     *
+     * @template K The type of the grouping key
+     * @param keyFn - Async or sync function to extract the grouping key
+     * @returns A promise of a Map where keys are the result of keyFn and values are arrays of elements
+     * @example
+     * ```typescript
+     * await asyncIter(['alice', 'bob', 'charlie', 'dave'])
+     *   .groupBy(async name => name.length);
+     * // Map { 3 => ['bob'], 5 => ['alice'], 7 => ['charlie'], 4 => ['dave'] }
+     * ```
+     */
+    groupBy<K>(keyFn: (value: T) => K | Promise<K>): Promise<Map<K, T[]>>;
+    /**
+     * Reduces the async iterator to a single value using an accumulator function.
+     * This is a terminal operation that consumes the async iterator.
+     *
+     * @template U The type of the accumulated value
+     * @param fn - Async or sync function to combine the accumulator with each element
+     * @param initial - The initial value for the accumulator
+     * @returns A promise of the final accumulated value
+     * @example
+     * ```typescript
+     * await asyncIter([1, 2, 3, 4]).reduce(async (acc, x) => acc + x, 0); // 10
+     * ```
+     */
+    reduce<U>(fn: (accumulator: U, value: T) => U | Promise<U>, initial: U): Promise<U>;
+    /**
+     * Finds the first element that matches the predicate.
+     * This is a terminal operation that may consume part of the async iterator.
+     *
+     * @param predicate - Async or sync function to test each element
+     * @returns A promise of the first matching element, or undefined if none found
+     * @example
+     * ```typescript
+     * await asyncIter([1, 2, 3, 4, 5]).find(async x => x > 3); // 4
+     * ```
+     */
+    find(predicate: (value: T) => boolean | Promise<boolean>): Promise<T | undefined>;
+    /**
+     * Finds the index of the first element that matches the predicate.
+     * This is a terminal operation that may consume part of the async iterator.
+     *
+     * @param predicate - Async or sync function to test each element
+     * @returns A promise of the index of the first matching element, or -1 if none found
+     * @example
+     * ```typescript
+     * await asyncIter([1, 2, 3, 4, 5]).findIndex(async x => x > 3); // 3
+     * ```
+     */
+    findIndex(predicate: (value: T) => boolean | Promise<boolean>): Promise<number>;
+    /**
+     * Tests whether at least one element matches the predicate.
+     * This is a terminal operation that may consume part of the async iterator.
+     *
+     * @param predicate - Async or sync function to test each element
+     * @returns A promise of true if any element matches, false otherwise
+     * @example
+     * ```typescript
+     * await asyncIter([1, 2, 3, 4, 5]).some(async x => x > 3); // true
+     * ```
+     */
+    some(predicate: (value: T) => boolean | Promise<boolean>): Promise<boolean>;
+    /**
+     * Tests whether all elements match the predicate.
+     * This is a terminal operation that may consume part or all of the async iterator.
+     *
+     * @param predicate - Async or sync function to test each element
+     * @returns A promise of true if all elements match, false otherwise
+     * @example
+     * ```typescript
+     * await asyncIter([2, 4, 6]).every(async x => x % 2 === 0); // true
+     * ```
+     */
+    every(predicate: (value: T) => boolean | Promise<boolean>): Promise<boolean>;
+    /**
+     * Gets the first element from the async iterator.
+     * This is a terminal operation that consumes the first element.
+     *
+     * @param defaultValue - Optional default value to return if iterator is empty
+     * @returns A promise of the first element, the default value, or undefined if empty and no default
+     * @example
+     * ```typescript
+     * await asyncIter([1, 2, 3]).first(); // 1
+     * ```
+     */
+    first(defaultValue?: T): Promise<T | undefined>;
+    /**
+     * Gets the last element from the async iterator.
+     * This is a terminal operation that consumes the entire async iterator.
+     *
+     * @param defaultValue - Optional default value to return if iterator is empty
+     * @returns A promise of the last element, the default value, or undefined if empty and no default
+     * @example
+     * ```typescript
+     * await asyncIter([1, 2, 3]).last(); // 3
+     * ```
+     */
+    last(defaultValue?: T): Promise<T | undefined>;
+    /**
+     * Gets the element at the specified index.
+     * This is a terminal operation that may consume part of the async iterator.
+     *
+     * @param index - Zero-based index of the element to retrieve
+     * @returns A promise of the element at the index, or undefined if index is out of bounds
+     * @example
+     * ```typescript
+     * await asyncIter([1, 2, 3, 4, 5]).nth(2); // 3
+     * ```
+     */
+    nth(index: number): Promise<T | undefined>;
+    /**
+     * Checks if the async iterator is empty.
+     * This is a terminal operation that may consume the first element.
+     *
+     * @returns A promise of true if the iterator has no elements, false otherwise
+     * @example
+     * ```typescript
+     * await asyncIter([]).isEmpty(); // true
+     * ```
+     */
+    isEmpty(): Promise<boolean>;
+    /**
+     * Checks if the async iterator includes a specific value.
+     * This is a terminal operation that may consume part or all of the async iterator.
+     *
+     * @param searchValue - The value to search for
+     * @returns A promise of true if the value is found, false otherwise
+     * @example
+     * ```typescript
+     * await asyncIter([1, 2, 3, 4, 5]).includes(3); // true
+     * ```
+     */
+    includes(searchValue: T): Promise<boolean>;
+    /**
+     * Maps elements in parallel with a concurrency limit.
+     * Processes multiple elements simultaneously while respecting the concurrency limit.
+     *
+     * @template U The type of the transformed elements
+     * @param fn - Async function to transform each element
+     * @param concurrency - Maximum number of concurrent operations (default: 10)
+     * @returns A new async iterflow with transformed elements
+     * @example
+     * ```typescript
+     * await asyncIter([1, 2, 3, 4, 5])
+     *   .mapParallel(async x => {
+     *     await sleep(100);
+     *     return x * 2;
+     *   }, 3)
+     *   .toArray(); // Processes 3 items at a time
+     * ```
+     */
+    mapParallel<U>(fn: (value: T) => Promise<U>, concurrency?: number): Asynciterflow<U>;
+    /**
+     * Filters elements in parallel with a concurrency limit.
+     *
+     * @param predicate - Async function to test each element
+     * @param concurrency - Maximum number of concurrent operations (default: 10)
+     * @returns A new async iterflow with only elements that pass the predicate
+     * @example
+     * ```typescript
+     * await asyncIter([1, 2, 3, 4, 5])
+     *   .filterParallel(async x => {
+     *     await sleep(100);
+     *     return x % 2 === 0;
+     *   }, 3)
+     *   .toArray(); // [2, 4]
+     * ```
+     */
+    filterParallel(predicate: (value: T) => Promise<boolean>, concurrency?: number): Asynciterflow<T>;
+    /**
+     * FlatMaps elements in parallel with a concurrency limit.
+     *
+     * @template U The type of elements in the resulting iterator
+     * @param fn - Async function that maps each element to an async iterable
+     * @param concurrency - Maximum number of concurrent operations (default: 10)
+     * @returns A new async iterflow with all mapped iterables flattened
+     * @example
+     * ```typescript
+     * await asyncIter([1, 2, 3])
+     *   .flatMapParallel(async x => [x, x * 2], 2)
+     *   .toArray(); // [1, 2, 2, 4, 3, 6]
+     * ```
+     */
+    flatMapParallel<U>(fn: (value: T) => Promise<AsyncIterable<U> | Iterable<U>>, concurrency?: number): Asynciterflow<U>;
+    /**
+     * Buffers elements up to a specified size.
+     *
+     * @param size - Maximum buffer size
+     * @returns A new async iterflow with buffered elements
+     * @example
+     * ```typescript
+     * await asyncIter([1, 2, 3, 4, 5]).buffer(2).toArray();
+     * // [[1, 2], [3, 4], [5]]
+     * ```
+     */
+    buffer(size: number): Asynciterflow<T[]>;
+    /**
+     * Throttles the stream to emit at most one value per time interval.
+     *
+     * @param intervalMs - Minimum time between emissions in milliseconds
+     * @returns A new async iterflow with throttled elements
+     * @example
+     * ```typescript
+     * await asyncIter([1, 2, 3, 4, 5]).throttle(100).toArray();
+     * // Emits one value every 100ms
+     * ```
+     */
+    throttle(intervalMs: number): Asynciterflow<T>;
+    /**
+     * Debounces the stream, only emitting values after a period of silence.
+     *
+     * @param waitMs - Time to wait for silence in milliseconds
+     * @returns A new async iterflow with debounced elements
+     * @example
+     * ```typescript
+     * await asyncIter([1, 2, 3, 4, 5]).debounce(100).toArray();
+     * // Only emits values after 100ms of no new values
+     * ```
+     */
+    debounce(waitMs: number): Asynciterflow<T>;
+    /**
+     * Catches errors and continues with a fallback value or stream.
+     *
+     * @param handler - Function to handle errors and return a fallback value or async iterable
+     * @returns A new async iterflow with error handling
+     * @example
+     * ```typescript
+     * await asyncIter([1, 2, 3])
+     *   .map(async x => {
+     *     if (x === 2) throw new Error('Error!');
+     *     return x;
+     *   })
+     *   .catchError(async (error) => [-1])
+     *   .toArray(); // [1, -1, 3]
+     * ```
+     */
+    catchError(handler: (error: unknown) => T | AsyncIterable<T> | Iterable<T> | Promise<T | AsyncIterable<T> | Iterable<T>>): Asynciterflow<T>;
+    /**
+     * Retries failed operations a specified number of times.
+     *
+     * @param maxRetries - Maximum number of retry attempts
+     * @param delayMs - Optional delay between retries in milliseconds
+     * @returns A new async iterflow with retry logic
+     * @example
+     * ```typescript
+     * await asyncIter([1, 2, 3])
+     *   .map(async x => {
+     *     if (Math.random() > 0.5) throw new Error('Random error');
+     *     return x;
+     *   })
+     *   .retry(3, 100)
+     *   .toArray(); // Retries up to 3 times with 100ms delay
+     * ```
+     */
+    retry(maxRetries: number, delayMs?: number): Asynciterflow<T>;
+    /**
+     * Handles errors for each element individually.
+     *
+     * @param handler - Async or sync function to handle errors for each element
+     * @returns A new async iterflow with error handling
+     * @example
+     * ```typescript
+     * await asyncIter([1, 2, 3])
+     *   .map(async x => {
+     *     if (x === 2) throw new Error('Error!');
+     *     return x;
+     *   })
+     *   .onError(async (error, value) => console.error('Error:', error))
+     *   .toArray(); // [1, 3] (2 is skipped)
+     * ```
+     */
+    onError(handler: (error: unknown, value?: T) => void | Promise<void>): Asynciterflow<T>;
+}
+/**
+ * Creates an async iterflow instance from an async iterable or iterable.
+ * This is the main entry point for working with async iterables in a fluent API style.
+ *
+ * @template T The type of elements in the iterable
+ * @param source - The async iterable or iterable to wrap
+ * @returns A new async iterflow instance
+ * @example
+ * ```typescript
+ * await asyncIter(asyncIterable)
+ *   .filter(async x => x % 2 === 0)
+ *   .map(async x => x * 2)
+ *   .toArray(); // [4, 8]
+ * ```
+ */
+declare function asyncIter<T>(source: AsyncIterable<T> | Iterable<T>): Asynciterflow<T>;
+declare namespace asyncIter {
+    /**
+     * Combines two async iterables into an async iterator of tuples.
+     * Stops when the shorter iterable is exhausted.
+     *
+     * @template T The type of elements in the first iterable
+     * @template U The type of elements in the second iterable
+     * @param iter1 - The first async iterable
+     * @param iter2 - The second async iterable
+     * @returns A new async iterflow of tuples pairing elements from both iterables
+     * @example
+     * ```typescript
+     * await asyncIter.zip(asyncIter1, asyncIter2).toArray();
+     * // [[1, 'a'], [2, 'b'], [3, 'c']]
+     * ```
+     */
+    function zip<T, U>(iter1: AsyncIterable<T> | Iterable<T>, iter2: AsyncIterable<U> | Iterable<U>): Asynciterflow<[T, U]>;
+    /**
+     * Combines two async iterables using a combining function.
+     * Stops when the shorter iterable is exhausted.
+     *
+     * @template T The type of elements in the first iterable
+     * @template U The type of elements in the second iterable
+     * @template R The type of the result
+     * @param iter1 - The first async iterable
+     * @param iter2 - The second async iterable
+     * @param fn - Async or sync function to combine elements
+     * @returns A new async iterflow with combined results
+     * @example
+     * ```typescript
+     * await asyncIter.zipWith(asyncIter1, asyncIter2, async (a, b) => a + b).toArray();
+     * // [11, 22, 33]
+     * ```
+     */
+    function zipWith<T, U, R>(iter1: AsyncIterable<T> | Iterable<T>, iter2: AsyncIterable<U> | Iterable<U>, fn: (a: T, b: U) => R | Promise<R>): Asynciterflow<R>;
+    /**
+     * Generates an async sequence of numbers.
+     *
+     * @param stop - The end value (exclusive)
+     * @returns A new async iterflow of numbers
+     * @example
+     * ```typescript
+     * await asyncIter.range(5).toArray(); // [0, 1, 2, 3, 4]
+     * ```
+     */
+    function range(stop: number): Asynciterflow<number>;
+    function range(start: number, stop: number): Asynciterflow<number>;
+    function range(start: number, stop: number, step: number): Asynciterflow<number>;
+    /**
+     * Repeats a value a specified number of times, or infinitely.
+     *
+     * @template T The type of the value to repeat
+     * @param value - The value to repeat
+     * @param times - Optional number of times to repeat (infinite if omitted)
+     * @returns A new async iterflow repeating the value
+     * @example
+     * ```typescript
+     * await asyncIter.repeat('x', 3).toArray(); // ['x', 'x', 'x']
+     * ```
+     */
+    function repeat<T>(value: T, times?: number): Asynciterflow<T>;
+    /**
+     * Alternates elements from multiple async iterables in a round-robin fashion.
+     *
+     * @template T The type of elements in all iterables
+     * @param iterables - Variable number of async iterables to interleave
+     * @returns A new async iterflow with elements from all iterables interleaved
+     * @example
+     * ```typescript
+     * await asyncIter.interleave(asyncIter1, asyncIter2).toArray();
+     * // [1, 4, 2, 5, 3, 6]
+     * ```
+     */
+    function interleave<T>(...iterables: Array<AsyncIterable<T> | Iterable<T>>): Asynciterflow<T>;
+    /**
+     * Merges multiple sorted async iterables into a single sorted async iterator.
+     *
+     * @template T The type of elements in all iterables
+     * @param iterables - Variable number of sorted async iterables to merge
+     * @returns A new async iterflow with all elements merged in sorted order
+     * @example
+     * ```typescript
+     * await asyncIter.merge(asyncIter1, asyncIter2).toArray();
+     * // [1, 2, 3, 4, 5, 6]
+     * ```
+     */
+    function merge<T>(...iterables: Array<AsyncIterable<T> | Iterable<T>>): Asynciterflow<T>;
+    function merge<T>(compareFn: (a: T, b: T) => number, ...iterables: Array<AsyncIterable<T> | Iterable<T>>): Asynciterflow<T>;
+    /**
+     * Chains multiple async iterables sequentially, one after another.
+     *
+     * @template T The type of elements in all iterables
+     * @param iterables - Variable number of async iterables to chain
+     * @returns A new async iterflow with all elements chained sequentially
+     * @example
+     * ```typescript
+     * await asyncIter.chain(asyncIter1, asyncIter2).toArray();
+     * // [1, 2, 3, 4, 5, 6]
+     * ```
+     */
+    function chain<T>(...iterables: Array<AsyncIterable<T> | Iterable<T>>): Asynciterflow<T>;
+    /**
+     * Creates an async iterator from a generator function.
+     *
+     * @template T The type of elements to generate
+     * @param fn - Async generator function
+     * @returns A new async iterflow
+     * @example
+     * ```typescript
+     * const fibonacci = asyncIter.fromGenerator(async function* () {
+     *   let [a, b] = [0, 1];
+     *   while (true) {
+     *     yield a;
+     *     [a, b] = [b, a + b];
+     *   }
+     * });
+     * await fibonacci.take(10).toArray(); // [0, 1, 1, 2, 3, 5, 8, 13, 21, 34]
+     * ```
+     */
+    function fromGenerator<T>(fn: () => AsyncGenerator<T>): Asynciterflow<T>;
+    /**
+     * Creates an async iterator from a promise.
+     *
+     * @template T The type of the resolved value
+     * @param promise - Promise to convert to async iterator
+     * @returns A new async iterflow
+     * @example
+     * ```typescript
+     * await asyncIter.fromPromise(fetch('/api/data').then(r => r.json())).toArray();
+     * ```
+     */
+    function fromPromise<T>(promise: Promise<T>): Asynciterflow<T>;
+    /**
+     * Creates an async iterator from an array of promises, yielding results as they resolve.
+     *
+     * @template T The type of the resolved values
+     * @param promises - Array of promises
+     * @returns A new async iterflow
+     * @example
+     * ```typescript
+     * const promises = [fetch('/api/1'), fetch('/api/2'), fetch('/api/3')];
+     * await asyncIter.fromPromises(promises).map(r => r.json()).toArray();
+     * ```
+     */
+    function fromPromises<T>(promises: Promise<T>[]): Asynciterflow<T>;
+}
+
+/**
+ * Error handling utilities and custom error classes for iterflow
+ * @module errors
+ */
+/**
+ * Base error class for all iterflow errors
+ */
+declare class iterflowError extends Error {
+    readonly operation?: string;
+    readonly context?: Record<string, unknown>;
+    constructor(message: string, operation?: string, context?: Record<string, unknown>);
+    /**
+     * Returns a detailed error message with context
+     */
+    toDetailedString(): string;
+}
+/**
+ * Error thrown when operation parameters are invalid
+ */
+declare class ValidationError extends iterflowError {
+    constructor(message: string, operation?: string, context?: Record<string, unknown>);
+}
+/**
+ * Error thrown when an operation fails during execution
+ */
+declare class OperationError extends iterflowError {
+    readonly cause?: Error;
+    constructor(message: string, operation?: string, cause?: Error, context?: Record<string, unknown>);
+    toDetailedString(): string;
+}
+/**
+ * Error thrown when an operation requires a non-empty sequence
+ */
+declare class EmptySequenceError extends iterflowError {
+    constructor(operation: string, message?: string);
+}
+/**
+ * Error thrown when accessing an invalid index
+ */
+declare class IndexOutOfBoundsError extends iterflowError {
+    readonly index: number;
+    readonly size?: number;
+    constructor(index: number, size?: number, operation?: string);
+}
+/**
+ * Error thrown when a type conversion or coercion fails
+ */
+declare class TypeConversionError extends iterflowError {
+    readonly value: unknown;
+    readonly expectedType: string;
+    constructor(value: unknown, expectedType: string, operation?: string);
+}
+
+/**
+ * Input validation utilities for iterflow operations
+ * @module validation
+ */
+/**
+ * Validates that a value is a positive integer
+ */
+declare function validatePositiveInteger(value: number, paramName: string, operation?: string): void;
+/**
+ * Validates that a value is a non-negative integer
+ */
+declare function validateNonNegativeInteger(value: number, paramName: string, operation?: string): void;
+/**
+ * Validates that a value is within a specific range
+ */
+declare function validateRange(value: number, min: number, max: number, paramName: string, operation?: string): void;
+/**
+ * Validates that a value is a finite number (not NaN or Infinity)
+ */
+declare function validateFiniteNumber(value: number, paramName: string, operation?: string): void;
+/**
+ * Validates that a value is not zero
+ */
+declare function validateNonZero(value: number, paramName: string, operation?: string): void;
+/**
+ * Validates that a value is a function
+ */
+declare function validateFunction(value: unknown, paramName: string, operation?: string): asserts value is Function;
+/**
+ * Validates that a value is iterable
+ */
+declare function validateIterable<T>(value: unknown, paramName: string, operation?: string): asserts value is Iterable<T>;
+/**
+ * Validates that a value is a valid comparator function
+ */
+declare function validateComparator<T>(fn: unknown, operation?: string): asserts fn is (a: T, b: T) => number;
+/**
+ * Validates that an array is not empty
+ */
+declare function validateNonEmpty<T>(arr: T[], operation?: string): void;
+/**
+ * Safely converts a value to a number
+ */
+declare function toNumber(value: unknown, operation?: string): number;
+/**
+ * Safely converts a value to an integer
+ */
+declare function toInteger(value: unknown, operation?: string): number;
+/**
+ * Validates array index
+ */
+declare function validateIndex(index: number, size: number, operation?: string): void;
+
+/**
+ * Debug mode and operation tracing utilities for iterflow
+ * @module debug
+ */
+/**
+ * Trace entry representing a single operation execution
+ */
+interface TraceEntry {
+    operation: string;
+    timestamp: number;
+    input?: unknown;
+    output?: unknown;
+    error?: Error;
+    duration?: number;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Debug configuration options
+ */
+interface DebugConfig {
+    enabled: boolean;
+    traceOperations: boolean;
+    traceInput: boolean;
+    traceOutput: boolean;
+    logToConsole: boolean;
+    maxTraceEntries?: number;
+}
+/**
+ * Enable debug mode
+ */
+declare function enableDebug(config?: Partial<DebugConfig>): void;
+/**
+ * Disable debug mode
+ */
+declare function disableDebug(): void;
+/**
+ * Check if debug mode is enabled
+ */
+declare function isDebugEnabled(): boolean;
+/**
+ * Get debug configuration
+ */
+declare function getDebugConfig(): Readonly<DebugConfig>;
+/**
+ * Add a trace entry
+ */
+declare function addTrace(entry: TraceEntry): void;
+/**
+ * Get all trace entries
+ */
+declare function getTraces(): readonly TraceEntry[];
+/**
+ * Clear all traces
+ */
+declare function clearTraces(): void;
+/**
+ * Get traces for a specific operation
+ */
+declare function getTracesForOperation(operation: string): TraceEntry[];
+/**
+ * Get trace summary statistics
+ */
+declare function getTraceSummary(): Record<string, {
+    count: number;
+    avgDuration: number;
+    errors: number;
+}>;
+/**
+ * Wrapper function to trace operation execution
+ */
+declare function traceOperation<T>(operation: string, fn: () => T, metadata?: Record<string, unknown>): T;
+/**
+ * Async version of traceOperation
+ */
+declare function traceOperationAsync<T>(operation: string, fn: () => Promise<T>, metadata?: Record<string, unknown>): Promise<T>;
+
+/**
+ * Error recovery utilities for iterflow
+ * @module recovery
+ */
+/**
+ * Error handler function type
+ */
+type ErrorHandler<T, R = T> = (error: Error, element?: T, index?: number) => R;
+/**
+ * Options for retry behavior
+ */
+interface RetryOptions {
+    maxAttempts?: number;
+    delay?: number;
+    backoff?: boolean;
+    onRetry?: (attempt: number, error: Error) => void;
+}
+/**
+ * Wraps a function with error recovery
+ */
+declare function withErrorRecovery<T, R>(fn: (value: T, index?: number) => R, errorHandler: ErrorHandler<T, R>): (value: T, index?: number) => R;
+/**
+ * Wraps a function with retry logic
+ */
+declare function withRetry<T extends any[], R>(fn: (...args: T) => R, options?: RetryOptions): (...args: T) => R;
+/**
+ * Async version of withRetry
+ */
+declare function withRetryAsync<T extends any[], R>(fn: (...args: T) => Promise<R>, options?: RetryOptions): (...args: T) => Promise<R>;
+/**
+ * Returns a default value if an error occurs
+ */
+declare function withDefault<T, R>(fn: (value: T) => R, defaultValue: R): (value: T) => R;
+/**
+ * Returns undefined if an error occurs (swallows errors)
+ */
+declare function tryOr<T, R>(fn: (value: T) => R, fallback: R): (value: T) => R;
+/**
+ * Executes a function and returns [result, error] tuple
+ */
+declare function tryCatch<T, R>(fn: (value: T) => R, value: T): [R | undefined, Error | undefined];
+/**
+ * Async version of tryCatch
+ */
+declare function tryCatchAsync<T, R>(fn: (value: T) => Promise<R>, value: T): Promise<[R | undefined, Error | undefined]>;
+/**
+ * Result type for safe operations
+ */
+type Result<T, E = Error> = {
+    success: true;
+    value: T;
+} | {
+    success: false;
+    error: E;
+};
+/**
+ * Wraps a function to return a Result type
+ */
+declare function toResult<T, R>(fn: (value: T) => R): (value: T) => Result<R>;
+/**
+ * Async version of toResult
+ */
+declare function toResultAsync<T, R>(fn: (value: T) => Promise<R>): (value: T) => Promise<Result<R>>;
+/**
+ * Guards a predicate function to return false on error instead of throwing
+ */
+declare function safePredicate<T>(predicate: (value: T, index?: number) => boolean, defaultValue?: boolean): (value: T, index?: number) => boolean;
+/**
+ * Guards a comparator function to handle errors gracefully
+ */
+declare function safeComparator<T>(comparator: (a: T, b: T) => number, defaultComparison?: number): (a: T, b: T) => number;
+/**
+ * Creates an error boundary that catches and logs errors
+ */
+declare function errorBoundary<T extends any[], R>(fn: (...args: T) => R, options?: {
+    onError?: (error: Error, args: T) => void;
+    rethrow?: boolean;
+    defaultValue?: R;
+}): (...args: T) => R | undefined;
+
+/**
+ * Deprecation warnings system for iterflow
+ *
+ * This module provides utilities for marking APIs as deprecated and emitting
+ * warnings to help users migrate away from deprecated functionality.
+ *
+ * @module deprecation
+ */
+/**
+ * Configuration options for deprecation warnings
+ */
+interface DeprecationConfig {
+    /** Whether to show deprecation warnings (default: true in development, false in production) */
+    enabled: boolean;
+    /** Whether to show stack traces with warnings (default: false) */
+    showStackTrace: boolean;
+    /** Custom handler for deprecation warnings */
+    handler?: (warning: DeprecationWarning) => void;
+}
+/**
+ * Information about a deprecated API
+ */
+interface DeprecationWarning {
+    /** The deprecated feature name */
+    feature: string;
+    /** Version when it was deprecated */
+    since: string;
+    /** Version when it will be removed (if known) */
+    removeIn?: string;
+    /** Alternative to use instead */
+    alternative?: string;
+    /** Additional message with migration guidance */
+    message?: string;
+    /** Stack trace (if enabled) */
+    stack?: string;
+}
+/**
+ * Configure the deprecation warning system
+ *
+ * @param options - Configuration options to update
+ * @example
+ * ```typescript
+ * // Disable all deprecation warnings
+ * configureDeprecation({ enabled: false });
+ *
+ * // Enable stack traces
+ * configureDeprecation({ showStackTrace: true });
+ *
+ * // Use custom handler
+ * configureDeprecation({
+ *   handler: (warning) => {
+ *     logger.warn(`Deprecated: ${warning.feature}`, warning);
+ *   }
+ * });
+ * ```
+ */
+declare function configureDeprecation(options: Partial<DeprecationConfig>): void;
+/**
+ * Get current deprecation configuration
+ *
+ * @returns Current deprecation configuration
+ */
+declare function getDeprecationConfig(): Readonly<DeprecationConfig>;
+/**
+ * Clear the set of warned features (mainly for testing)
+ */
+declare function clearDeprecationWarnings(): void;
+/**
+ * Mark a feature as deprecated and emit a warning when called
+ *
+ * @param options - Deprecation warning details
+ * @example
+ * ```typescript
+ * // In your code
+ * function oldMethod() {
+ *   deprecate({
+ *     feature: 'oldMethod()',
+ *     since: '0.9.0',
+ *     removeIn: '2.0.0',
+ *     alternative: 'newMethod()',
+ *     message: 'See migration guide: https://...'
+ *   });
+ *
+ *   // ... implementation
+ * }
+ * ```
+ */
+declare function deprecate(options: Omit<DeprecationWarning, "stack">): void;
+/**
+ * Decorator to mark a method or function as deprecated
+ *
+ * @param options - Deprecation warning details
+ * @returns Decorator function
+ * @example
+ * ```typescript
+ * class MyClass {
+ *   @deprecated({
+ *     feature: 'MyClass.oldMethod',
+ *     since: '0.9.0',
+ *     alternative: 'MyClass.newMethod'
+ *   })
+ *   oldMethod() {
+ *     // implementation
+ *   }
+ * }
+ * ```
+ */
+declare function deprecated(options: Omit<DeprecationWarning, "stack" | "feature">): <T extends Function>(target: any, propertyKey: string, descriptor: TypedPropertyDescriptor<T>) => TypedPropertyDescriptor<T> | void;
+/**
+ * Create a wrapper function that marks the original function as deprecated
+ *
+ * @param fn - The function to wrap
+ * @param options - Deprecation warning details
+ * @returns Wrapped function that emits deprecation warning
+ * @example
+ * ```typescript
+ * const oldFunction = deprecatedFunction(
+ *   (x: number) => x * 2,
+ *   {
+ *     feature: 'oldFunction',
+ *     since: '0.9.0',
+ *     alternative: 'newFunction'
+ *   }
+ * );
+ * ```
+ */
+declare function deprecatedFunction<T extends (...args: any[]) => any>(fn: T, options: Omit<DeprecationWarning, "stack">): T;
+/**
+ * Check if a feature has been marked as deprecated (for testing)
+ *
+ * @param feature - The feature name to check
+ * @returns True if the feature has been warned about
+ */
+declare function hasDeprecationWarning(feature: string): boolean;
+
+/**
+ * Creates an iterflow instance from an iterable.
+ * This is the main entry point for working with iterables in a fluent API style.
+ *
+ * @template T The type of elements in the iterable
+ * @param source - The iterable to wrap
+ * @returns A new iterflow instance
+ * @example
+ * ```typescript
+ * iter([1, 2, 3, 4, 5])
+ *   .filter(x => x % 2 === 0)
+ *   .map(x => x * 2)
+ *   .toArray(); // [4, 8]
+ * ```
+ */
+declare function iter<T>(source: Iterable<T>): iterflow<T>;
+declare namespace iter {
+    /**
+     * Combines two iterables into an iterator of tuples.
+     * Stops when the shorter iterable is exhausted.
+     *
+     * @template T The type of elements in the first iterable
+     * @template U The type of elements in the second iterable
+     * @param iter1 - The first iterable
+     * @param iter2 - The second iterable
+     * @returns A new iterflow of tuples pairing elements from both iterables
+     * @example
+     * ```typescript
+     * iter.zip([1, 2, 3], ['a', 'b', 'c']).toArray();
+     * // [[1, 'a'], [2, 'b'], [3, 'c']]
+     * ```
+     */
+    function zip<T, U>(iter1: Iterable<T>, iter2: Iterable<U>): iterflow<[T, U]>;
+    /**
+     * Combines two iterables using a combining function.
+     * Stops when the shorter iterable is exhausted.
+     *
+     * @template T The type of elements in the first iterable
+     * @template U The type of elements in the second iterable
+     * @template R The type of the result
+     * @param iter1 - The first iterable
+     * @param iter2 - The second iterable
+     * @param fn - Function to combine elements from both iterables
+     * @returns A new iterflow with combined results
+     * @example
+     * ```typescript
+     * iter.zipWith([1, 2, 3], [10, 20, 30], (a, b) => a + b).toArray();
+     * // [11, 22, 33]
+     * ```
+     */
+    function zipWith<T, U, R>(iter1: Iterable<T>, iter2: Iterable<U>, fn: (a: T, b: U) => R): iterflow<R>;
+    /**
+     * Generates a sequence of numbers.
+     * Supports three call signatures:
+     * - range(stop): generates [0, stop) with step 1
+     * - range(start, stop): generates [start, stop) with step 1
+     * - range(start, stop, step): generates [start, stop) with custom step
+     *
+     * @param stop - The end value (exclusive) when called with one argument
+     * @returns A new iterflow of numbers
+     * @throws {Error} If step is zero
+     * @example
+     * ```typescript
+     * iter.range(5).toArray(); // [0, 1, 2, 3, 4]
+     * iter.range(2, 5).toArray(); // [2, 3, 4]
+     * iter.range(0, 10, 2).toArray(); // [0, 2, 4, 6, 8]
+     * iter.range(5, 0, -1).toArray(); // [5, 4, 3, 2, 1]
+     * ```
+     */
+    function range(stop: number): iterflow<number>;
+    /**
+     * Generates a sequence of numbers from start to stop (exclusive).
+     *
+     * @param start - The starting value (inclusive)
+     * @param stop - The end value (exclusive)
+     * @returns A new iterflow of numbers
+     */
+    function range(start: number, stop: number): iterflow<number>;
+    /**
+     * Generates a sequence of numbers from start to stop (exclusive) with a custom step.
+     *
+     * @param start - The starting value (inclusive)
+     * @param stop - The end value (exclusive)
+     * @param step - The increment between values
+     * @returns A new iterflow of numbers
+     */
+    function range(start: number, stop: number, step: number): iterflow<number>;
+    /**
+     * Repeats a value a specified number of times, or infinitely.
+     * If times is not specified, creates an infinite iterator.
+     *
+     * @template T The type of the value to repeat
+     * @param value - The value to repeat
+     * @param times - Optional number of times to repeat (infinite if omitted)
+     * @returns A new iterflow repeating the value
+     * @example
+     * ```typescript
+     * iter.repeat('x', 3).toArray(); // ['x', 'x', 'x']
+     * iter.repeat(0, 5).toArray(); // [0, 0, 0, 0, 0]
+     * iter.repeat(1).take(3).toArray(); // [1, 1, 1] (infinite, limited by take)
+     * ```
+     */
+    function repeat<T>(value: T, times?: number): iterflow<T>;
+    /**
+     * Alternates elements from multiple iterables in a round-robin fashion.
+     * Continues until all iterables are exhausted.
+     *
+     * @template T The type of elements in all iterables
+     * @param iterables - Variable number of iterables to interleave
+     * @returns A new iterflow with elements from all iterables interleaved
+     * @example
+     * ```typescript
+     * iter.interleave([1, 2, 3], [4, 5, 6]).toArray();
+     * // [1, 4, 2, 5, 3, 6]
+     * iter.interleave([1, 2], [3, 4, 5], [6]).toArray();
+     * // [1, 3, 6, 2, 4, 5]
+     * ```
+     */
+    function interleave<T>(...iterables: Iterable<T>[]): iterflow<T>;
+    /**
+     * Merges multiple sorted iterables into a single sorted iterator.
+     * Assumes input iterables are already sorted in ascending order.
+     * Uses a custom comparator if provided, otherwise uses default < comparison.
+     *
+     * @template T The type of elements in all iterables
+     * @param iterables - Variable number of sorted iterables to merge
+     * @param compareFn - Optional comparison function (returns negative if a < b, positive if a > b, 0 if equal)
+     * @returns A new iterflow with all elements merged in sorted order
+     * @example
+     * ```typescript
+     * iter.merge([1, 3, 5], [2, 4, 6]).toArray();
+     * // [1, 2, 3, 4, 5, 6]
+     * iter.merge([1, 5, 9], [2, 6, 10], [3, 7, 11]).toArray();
+     * // [1, 2, 3, 5, 6, 7, 9, 10, 11]
+     * ```
+     */
+    function merge<T>(...iterables: Iterable<T>[]): iterflow<T>;
+    function merge<T>(compareFn: (a: T, b: T) => number, ...iterables: Iterable<T>[]): iterflow<T>;
+    /**
+     * Chains multiple iterables sequentially, one after another.
+     * Yields all elements from the first iterable, then all from the second, etc.
+     *
+     * @template T The type of elements in all iterables
+     * @param iterables - Variable number of iterables to chain
+     * @returns A new iterflow with all elements chained sequentially
+     * @example
+     * ```typescript
+     * iter.chain([1, 2], [3, 4], [5, 6]).toArray();
+     * // [1, 2, 3, 4, 5, 6]
+     * iter.chain([1], [2, 3], [], [4, 5, 6]).toArray();
+     * // [1, 2, 3, 4, 5, 6]
+     * ```
+     */
+    function chain<T>(...iterables: Iterable<T>[]): iterflow<T>;
+}
+
+export { Asynciterflow, type DebugConfig, type DeprecationConfig, type DeprecationWarning, EmptySequenceError, type ErrorHandler, IndexOutOfBoundsError, OperationError, type Result, type RetryOptions, type TraceEntry, TypeConversionError, ValidationError, addTrace, asyncIter, clearDeprecationWarnings, clearTraces, configureDeprecation, deprecate, deprecated, deprecatedFunction, disableDebug, enableDebug, errorBoundary, getDebugConfig, getDeprecationConfig, getTraceSummary, getTraces, getTracesForOperation, hasDeprecationWarning, isDebugEnabled, iter, iterflow, iterflowError, safeComparator, safePredicate, toInteger, toNumber, toResult, toResultAsync, traceOperation, traceOperationAsync, tryCatch, tryCatchAsync, tryOr, validateComparator, validateFiniteNumber, validateFunction, validateIndex, validateIterable, validateNonEmpty, validateNonNegativeInteger, validateNonZero, validatePositiveInteger, validateRange, withDefault, withErrorRecovery, withRetry, withRetryAsync };