iterflow 0.2.2

package/dist/index.cjs

@@ -0,0 +1,4030 @@
+'use strict';
+
+// src/errors.ts
+var iterflowError = class extends Error {
+  operation;
+  context;
+  constructor(message, operation, context) {
+    super(message);
+    this.name = "iterflowError";
+    this.operation = operation;
+    this.context = context;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+  /**
+   * Returns a detailed error message with context
+   */
+  toDetailedString() {
+    let msg = `${this.name}: ${this.message}`;
+    if (this.operation) {
+      msg += `
+  Operation: ${this.operation}`;
+    }
+    if (this.context && Object.keys(this.context).length > 0) {
+      msg += "\n  Context:";
+      for (const [key, value] of Object.entries(this.context)) {
+        msg += `
+    ${key}: ${JSON.stringify(value)}`;
+      }
+    }
+    if (this.stack) {
+      msg += `
+  Stack: ${this.stack.split("\n").slice(1).join("\n")}`;
+    }
+    return msg;
+  }
+};
+var ValidationError = class extends iterflowError {
+  constructor(message, operation, context) {
+    super(message, operation, context);
+    this.name = "ValidationError";
+  }
+};
+var OperationError = class extends iterflowError {
+  cause;
+  constructor(message, operation, cause, context) {
+    super(message, operation, context);
+    this.name = "OperationError";
+    this.cause = cause;
+  }
+  toDetailedString() {
+    let msg = super.toDetailedString();
+    if (this.cause) {
+      msg += `
+  Caused by: ${this.cause.message}`;
+      if (this.cause.stack) {
+        msg += `
+  ${this.cause.stack}`;
+      }
+    }
+    return msg;
+  }
+};
+var EmptySequenceError = class extends iterflowError {
+  constructor(operation, message) {
+    super(
+      message || `Operation '${operation}' requires a non-empty sequence`,
+      operation
+    );
+    this.name = "EmptySequenceError";
+  }
+};
+var IndexOutOfBoundsError = class extends iterflowError {
+  index;
+  size;
+  constructor(index, size, operation) {
+    const sizeInfo = size !== void 0 ? ` (size: ${size})` : "";
+    super(`Index ${index} is out of bounds${sizeInfo}`, operation, {
+      index,
+      size
+    });
+    this.name = "IndexOutOfBoundsError";
+    this.index = index;
+    this.size = size;
+  }
+};
+var TypeConversionError = class extends iterflowError {
+  value;
+  expectedType;
+  constructor(value, expectedType, operation) {
+    super(
+      `Cannot convert value ${JSON.stringify(value)} to type ${expectedType}`,
+      operation,
+      { value, expectedType }
+    );
+    this.name = "TypeConversionError";
+    this.value = value;
+    this.expectedType = expectedType;
+  }
+};
+
+// src/validation.ts
+function validatePositiveInteger(value, paramName, operation) {
+  if (!Number.isInteger(value)) {
+    throw new ValidationError(
+      `${paramName} must be an integer, got ${value}`,
+      operation,
+      { paramName, value }
+    );
+  }
+  if (value < 1) {
+    throw new ValidationError(
+      `${paramName} must be at least 1, got ${value}`,
+      operation,
+      { paramName, value }
+    );
+  }
+}
+function validateNonNegativeInteger(value, paramName, operation) {
+  if (!Number.isInteger(value)) {
+    throw new ValidationError(
+      `${paramName} must be an integer, got ${value}`,
+      operation,
+      { paramName, value }
+    );
+  }
+  if (value < 0) {
+    throw new ValidationError(
+      `${paramName} must be non-negative, got ${value}`,
+      operation,
+      { paramName, value }
+    );
+  }
+}
+function validateRange(value, min, max, paramName, operation) {
+  if (value < min || value > max) {
+    throw new ValidationError(
+      `${paramName} must be between ${min} and ${max}, got ${value}`,
+      operation,
+      { paramName, value, min, max }
+    );
+  }
+}
+function validateFiniteNumber(value, paramName, operation) {
+  if (!Number.isFinite(value)) {
+    throw new ValidationError(
+      `${paramName} must be a finite number, got ${value}`,
+      operation,
+      { paramName, value }
+    );
+  }
+}
+function validateNonZero(value, paramName, operation) {
+  if (value === 0) {
+    throw new ValidationError(`${paramName} cannot be zero`, operation, {
+      paramName,
+      value
+    });
+  }
+}
+function validateFunction(value, paramName, operation) {
+  if (typeof value !== "function") {
+    throw new ValidationError(
+      `${paramName} must be a function, got ${typeof value}`,
+      operation,
+      { paramName, type: typeof value }
+    );
+  }
+}
+function validateIterable(value, paramName, operation) {
+  if (value == null || typeof value[Symbol.iterator] !== "function") {
+    throw new ValidationError(`${paramName} must be iterable`, operation, {
+      paramName,
+      type: typeof value
+    });
+  }
+}
+function validateComparator(fn, operation) {
+  validateFunction(fn, "comparator", operation);
+}
+function validateNonEmpty(arr, operation) {
+  if (arr.length === 0) {
+    throw new ValidationError("Sequence cannot be empty", operation);
+  }
+}
+function toNumber(value, operation) {
+  const num = Number(value);
+  if (Number.isNaN(num)) {
+    throw new TypeConversionError(value, "number", operation);
+  }
+  return num;
+}
+function toInteger(value, operation) {
+  const num = toNumber(value, operation);
+  const int = Math.trunc(num);
+  if (num !== int) {
+    throw new TypeConversionError(value, "integer", operation);
+  }
+  return int;
+}
+function validateIndex(index, size, operation) {
+  validateNonNegativeInteger(index, "index", operation);
+  if (index >= size) {
+    throw new ValidationError(
+      `Index ${index} is out of bounds for size ${size}`,
+      operation,
+      { index, size }
+    );
+  }
+}
+
+// src/iter-flow.ts
+var iterflow = class _iterflow {
+  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) {
+    this.source = Symbol.iterator in source ? source[Symbol.iterator]() : source;
+  }
+  // Iterator protocol
+  /**
+   * Returns the iterator for this iterflow instance.
+   * This allows iterflow to be used in for...of loops.
+   *
+   * @returns The underlying iterator
+   */
+  [Symbol.iterator]() {
+    return this.source;
+  }
+  /**
+   * Retrieves the next value from the iterator.
+   *
+   * @returns An IteratorResult containing the next value or indicating completion
+   */
+  next() {
+    return this.source.next();
+  }
+  // ES2025 native passthrough methods (would normally delegate to native implementations)
+  /**
+   * 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(fn) {
+    const self = this;
+    return new _iterflow({
+      *[Symbol.iterator]() {
+        for (const value of self) {
+          yield fn(value);
+        }
+      }
+    });
+  }
+  /**
+   * 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) {
+    const self = this;
+    return new _iterflow({
+      *[Symbol.iterator]() {
+        for (const value of self) {
+          if (predicate(value)) {
+            yield value;
+          }
+        }
+      }
+    });
+  }
+  /**
+   * 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) {
+    const self = this;
+    return new _iterflow({
+      *[Symbol.iterator]() {
+        let count = 0;
+        for (const value of self) {
+          if (count >= limit) break;
+          yield value;
+          count++;
+        }
+      }
+    });
+  }
+  /**
+   * 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) {
+    const self = this;
+    return new _iterflow({
+      *[Symbol.iterator]() {
+        let dropped = 0;
+        for (const value of self) {
+          if (dropped < count) {
+            dropped++;
+            continue;
+          }
+          yield value;
+        }
+      }
+    });
+  }
+  /**
+   * 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(fn) {
+    const self = this;
+    return new _iterflow({
+      *[Symbol.iterator]() {
+        for (const value of self) {
+          yield* fn(value);
+        }
+      }
+    });
+  }
+  /**
+   * 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) {
+    const self = this;
+    return new _iterflow({
+      *[Symbol.iterator]() {
+        yield* self;
+        for (const iterable of iterables) {
+          yield* iterable;
+        }
+      }
+    });
+  }
+  /**
+   * 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) {
+    const self = this;
+    return new _iterflow({
+      *[Symbol.iterator]() {
+        let isFirst = true;
+        for (const value of self) {
+          if (!isFirst) {
+            yield separator;
+          }
+          yield value;
+          isFirst = false;
+        }
+      }
+    });
+  }
+  /**
+   * 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(fn, initial) {
+    const self = this;
+    return new _iterflow({
+      *[Symbol.iterator]() {
+        let accumulator = initial;
+        yield accumulator;
+        for (const value of self) {
+          accumulator = fn(accumulator, value);
+          yield accumulator;
+        }
+      }
+    });
+  }
+  /**
+   * 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() {
+    const self = this;
+    return new _iterflow({
+      *[Symbol.iterator]() {
+        let index = 0;
+        for (const value of self) {
+          yield [index, value];
+          index++;
+        }
+      }
+    });
+  }
+  /**
+   * 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() {
+    const self = this;
+    return new _iterflow({
+      *[Symbol.iterator]() {
+        const buffer = Array.from(self);
+        for (let i = buffer.length - 1; i >= 0; i--) {
+          yield buffer[i];
+        }
+      }
+    });
+  }
+  /**
+   * 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() {
+    const self = this;
+    return new _iterflow({
+      *[Symbol.iterator]() {
+        const buffer = Array.from(self);
+        buffer.sort((a, b) => {
+          if (typeof a === "number" && typeof b === "number") {
+            return a - b;
+          }
+          return String(a).localeCompare(String(b));
+        });
+        yield* buffer;
+      }
+    });
+  }
+  /**
+   * 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) {
+    const self = this;
+    return new _iterflow({
+      *[Symbol.iterator]() {
+        const buffer = Array.from(self);
+        buffer.sort(compareFn);
+        yield* buffer;
+      }
+    });
+  }
+  // Terminal operations (consume the iterator)
+  /**
+   * 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() {
+    return Array.from(this);
+  }
+  /**
+   * 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() {
+    let count = 0;
+    for (const _ of this) {
+      count++;
+    }
+    return count;
+  }
+  // Statistical operations - type-constrained to numbers
+  /**
+   * 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() {
+    let total = 0;
+    for (const value of this) {
+      total += value;
+    }
+    return total;
+  }
+  /**
+   * 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() {
+    let total = 0;
+    let count = 0;
+    for (const value of this) {
+      total += value;
+      count++;
+    }
+    return count === 0 ? void 0 : total / count;
+  }
+  /**
+   * 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() {
+    let minimum = void 0;
+    for (const value of this) {
+      if (minimum === void 0 || value < minimum) {
+        minimum = value;
+      }
+    }
+    return minimum;
+  }
+  /**
+   * 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() {
+    let maximum = void 0;
+    for (const value of this) {
+      if (maximum === void 0 || value > maximum) {
+        maximum = value;
+      }
+    }
+    return maximum;
+  }
+  /**
+   * 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() {
+    const values = this.toArray();
+    if (values.length === 0) return void 0;
+    values.sort((a, b) => a - b);
+    const mid = Math.floor(values.length / 2);
+    if (values.length % 2 === 0) {
+      return (values[mid - 1] + values[mid]) / 2;
+    } else {
+      return values[mid];
+    }
+  }
+  /**
+   * 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() {
+    const values = this.toArray();
+    if (values.length === 0) return void 0;
+    const mean = values.reduce((sum, val) => sum + val, 0) / values.length;
+    let sumSquaredDiffs = 0;
+    for (let i = 0; i < values.length; i++) {
+      const value = values[i];
+      const diff = value - mean;
+      sumSquaredDiffs += diff * diff;
+    }
+    return sumSquaredDiffs / values.length;
+  }
+  /**
+   * 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() {
+    const variance = this.variance();
+    return variance === void 0 ? void 0 : Math.sqrt(variance);
+  }
+  /**
+   * 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(p) {
+    validateRange(p, 0, 100, "percentile", "percentile");
+    const values = this.toArray();
+    if (values.length === 0) return void 0;
+    values.sort((a, b) => a - b);
+    if (p === 0) return values[0];
+    if (p === 100) return values[values.length - 1];
+    const index = p / 100 * (values.length - 1);
+    const lower = Math.floor(index);
+    const upper = Math.ceil(index);
+    if (lower === upper) {
+      return values[lower];
+    }
+    const weight = index - lower;
+    return values[lower] * (1 - weight) + values[upper] * weight;
+  }
+  /**
+   * 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() {
+    const values = this.toArray();
+    if (values.length === 0) return void 0;
+    const frequency = /* @__PURE__ */ new Map();
+    let maxFreq = 0;
+    for (const value of values) {
+      const count = (frequency.get(value) || 0) + 1;
+      frequency.set(value, count);
+      maxFreq = Math.max(maxFreq, count);
+    }
+    const modes = [];
+    for (const [value, freq] of frequency) {
+      if (freq === maxFreq) {
+        modes.push(value);
+      }
+    }
+    return modes.sort((a, b) => a - b);
+  }
+  /**
+   * 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() {
+    const values = this.toArray();
+    if (values.length === 0) return void 0;
+    values.sort((a, b) => a - b);
+    const calculatePercentile = (p) => {
+      if (p === 0) return values[0];
+      if (p === 100) return values[values.length - 1];
+      const index = p / 100 * (values.length - 1);
+      const lower = Math.floor(index);
+      const upper = Math.ceil(index);
+      if (lower === upper) {
+        return values[lower];
+      }
+      const weight = index - lower;
+      return values[lower] * (1 - weight) + values[upper] * weight;
+    };
+    return {
+      Q1: calculatePercentile(25),
+      Q2: calculatePercentile(50),
+      Q3: calculatePercentile(75)
+    };
+  }
+  /**
+   * 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() {
+    let minimum = void 0;
+    let maximum = void 0;
+    for (const value of this) {
+      if (minimum === void 0 || value < minimum) {
+        minimum = value;
+      }
+      if (maximum === void 0 || value > maximum) {
+        maximum = value;
+      }
+    }
+    return minimum === void 0 || maximum === void 0 ? void 0 : maximum - minimum;
+  }
+  /**
+   * 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() {
+    let result = 1;
+    for (const value of this) {
+      result *= value;
+    }
+    return result;
+  }
+  /**
+   * 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(other) {
+    const values1 = this.toArray();
+    const values2 = Array.from(other);
+    if (values1.length === 0 || values2.length === 0 || values1.length !== values2.length) {
+      return void 0;
+    }
+    const mean1 = values1.reduce((sum, val) => sum + val, 0) / values1.length;
+    const mean2 = values2.reduce((sum, val) => sum + val, 0) / values2.length;
+    let covariance = 0;
+    for (let i = 0; i < values1.length; i++) {
+      covariance += (values1[i] - mean1) * (values2[i] - mean2);
+    }
+    return covariance / values1.length;
+  }
+  /**
+   * 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(other) {
+    const values1 = this.toArray();
+    const values2 = Array.from(other);
+    if (values1.length === 0 || values2.length === 0 || values1.length !== values2.length) {
+      return void 0;
+    }
+    const mean1 = values1.reduce((sum, val) => sum + val, 0) / values1.length;
+    const mean2 = values2.reduce((sum, val) => sum + val, 0) / values2.length;
+    let covariance = 0;
+    let variance1 = 0;
+    let variance2 = 0;
+    for (let i = 0; i < values1.length; i++) {
+      const diff1 = values1[i] - mean1;
+      const diff2 = values2[i] - mean2;
+      covariance += diff1 * diff2;
+      variance1 += diff1 * diff1;
+      variance2 += diff2 * diff2;
+    }
+    const stdDev1 = Math.sqrt(variance1 / values1.length);
+    const stdDev2 = Math.sqrt(variance2 / values2.length);
+    if (stdDev1 === 0 || stdDev2 === 0) {
+      return void 0;
+    }
+    return covariance / (values1.length * stdDev1 * stdDev2);
+  }
+  // Windowing operations
+  /**
+   * 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) {
+    validatePositiveInteger(size, "size", "window");
+    const self = this;
+    return new _iterflow({
+      *[Symbol.iterator]() {
+        const buffer = new Array(size);
+        let count = 0;
+        let index = 0;
+        for (const value of self) {
+          buffer[index] = value;
+          count++;
+          index = (index + 1) % size;
+          if (count >= size) {
+            const window = new Array(size);
+            for (let i = 0; i < size; i++) {
+              window[i] = buffer[(index + i) % size];
+            }
+            yield window;
+          }
+        }
+      }
+    });
+  }
+  /**
+   * 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) {
+    validatePositiveInteger(size, "size", "chunk");
+    const self = this;
+    return new _iterflow({
+      *[Symbol.iterator]() {
+        let buffer = new Array(size);
+        let bufferIndex = 0;
+        for (const value of self) {
+          buffer[bufferIndex++] = value;
+          if (bufferIndex === size) {
+            yield buffer;
+            buffer = new Array(size);
+            bufferIndex = 0;
+          }
+        }
+        if (bufferIndex > 0) {
+          yield buffer.slice(0, bufferIndex);
+        }
+      }
+    });
+  }
+  /**
+   * 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() {
+    return this.window(2).map((arr) => [arr[0], arr[1]]);
+  }
+  // Set operations
+  /**
+   * 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() {
+    const self = this;
+    return new _iterflow({
+      *[Symbol.iterator]() {
+        const seen = /* @__PURE__ */ new Set();
+        for (const value of self) {
+          if (!seen.has(value)) {
+            seen.add(value);
+            yield value;
+          }
+        }
+      }
+    });
+  }
+  /**
+   * 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(keyFn) {
+    const self = this;
+    return new _iterflow({
+      *[Symbol.iterator]() {
+        const seenKeys = /* @__PURE__ */ new Set();
+        for (const value of self) {
+          const key = keyFn(value);
+          if (!seenKeys.has(key)) {
+            seenKeys.add(key);
+            yield value;
+          }
+        }
+      }
+    });
+  }
+  // Utility operations
+  /**
+   * 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) {
+    const self = this;
+    return new _iterflow({
+      *[Symbol.iterator]() {
+        for (const value of self) {
+          fn(value);
+          yield value;
+        }
+      }
+    });
+  }
+  /**
+   * 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) {
+    const self = this;
+    return new _iterflow({
+      *[Symbol.iterator]() {
+        for (const value of self) {
+          if (!predicate(value)) break;
+          yield value;
+        }
+      }
+    });
+  }
+  /**
+   * 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) {
+    const self = this;
+    return new _iterflow({
+      *[Symbol.iterator]() {
+        let dropping = true;
+        for (const value of self) {
+          if (dropping && predicate(value)) {
+            continue;
+          }
+          dropping = false;
+          yield value;
+        }
+      }
+    });
+  }
+  // Grouping operations (terminal)
+  /**
+   * 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) {
+    const truthy = [];
+    const falsy = [];
+    for (const value of this) {
+      if (predicate(value)) {
+        truthy.push(value);
+      } else {
+        falsy.push(value);
+      }
+    }
+    return [truthy, falsy];
+  }
+  /**
+   * 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(keyFn) {
+    const groups = /* @__PURE__ */ new Map();
+    for (const value of this) {
+      const key = keyFn(value);
+      if (!groups.has(key)) {
+        groups.set(key, []);
+      }
+      groups.get(key).push(value);
+    }
+    return groups;
+  }
+  // Additional terminal operations
+  /**
+   * 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(fn, initial) {
+    let accumulator = initial;
+    for (const value of this) {
+      accumulator = fn(accumulator, value);
+    }
+    return accumulator;
+  }
+  /**
+   * 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) {
+    for (const value of this) {
+      if (predicate(value)) {
+        return value;
+      }
+    }
+    return void 0;
+  }
+  /**
+   * 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) {
+    let index = 0;
+    for (const value of this) {
+      if (predicate(value)) {
+        return index;
+      }
+      index++;
+    }
+    return -1;
+  }
+  /**
+   * 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) {
+    for (const value of this) {
+      if (predicate(value)) {
+        return true;
+      }
+    }
+    return false;
+  }
+  /**
+   * 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) {
+    for (const value of this) {
+      if (!predicate(value)) {
+        return false;
+      }
+    }
+    return true;
+  }
+  /**
+   * 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) {
+    for (const value of this) {
+      fn(value);
+    }
+  }
+  /**
+   * 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) {
+    const result = this.source.next();
+    return result.done ? defaultValue : result.value;
+  }
+  /**
+   * 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) {
+    let lastValue = defaultValue;
+    let hasValue = false;
+    for (const value of this) {
+      lastValue = value;
+      hasValue = true;
+    }
+    return hasValue ? lastValue : defaultValue;
+  }
+  /**
+   * 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) {
+    if (index < 0) {
+      return void 0;
+    }
+    let currentIndex = 0;
+    for (const value of this) {
+      if (currentIndex === index) {
+        return value;
+      }
+      currentIndex++;
+    }
+    return void 0;
+  }
+  /**
+   * 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() {
+    const result = this.source.next();
+    return result.done === true;
+  }
+  /**
+   * 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) {
+    for (const value of this) {
+      if (value === searchValue) {
+        return true;
+      }
+    }
+    return false;
+  }
+  // Alias methods for compatibility
+  /**
+   * Alias for stdDev() method for compatibility.
+   * Calculates the standard deviation of all numeric elements.
+   */
+  stddev() {
+    return this.stdDev();
+  }
+  /**
+   * Alias for drop() method for compatibility.
+   * Skips the first `count` elements from the iterator.
+   */
+  skip(count) {
+    return this.drop(count);
+  }
+  /**
+   * 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) {
+    const self = this;
+    return new _iterflow({
+      *[Symbol.iterator]() {
+        const allIterables = [self, ...others];
+        if (allIterables.length === 0) return;
+        const iterators = allIterables.map((it) => it[Symbol.iterator]());
+        const active = new Set(iterators);
+        while (active.size > 0) {
+          for (const iterator of iterators) {
+            if (!active.has(iterator)) continue;
+            const result = iterator.next();
+            if (result.done) {
+              active.delete(iterator);
+            } else {
+              yield result.value;
+            }
+          }
+        }
+      }
+    });
+  }
+  /**
+   * 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) {
+    const self = this;
+    return new _iterflow({
+      *[Symbol.iterator]() {
+        const allIterables = [self, ...others];
+        if (allIterables.length === 0) return;
+        const compareFn = (a, b) => {
+          if (a < b) return -1;
+          if (a > b) return 1;
+          return 0;
+        };
+        const heap = [];
+        for (let i = 0; i < allIterables.length; i++) {
+          const iterator = allIterables[i][Symbol.iterator]();
+          const result = iterator.next();
+          if (!result.done) {
+            heap.push({ value: result.value, iterator, index: i });
+          }
+        }
+        const bubbleDown = (index) => {
+          const length = heap.length;
+          while (true) {
+            let smallest = index;
+            const leftChild = 2 * index + 1;
+            const rightChild = 2 * index + 2;
+            if (leftChild < length && compareFn(heap[leftChild].value, heap[smallest].value) < 0) {
+              smallest = leftChild;
+            }
+            if (rightChild < length && compareFn(heap[rightChild].value, heap[smallest].value) < 0) {
+              smallest = rightChild;
+            }
+            if (smallest === index) break;
+            const temp = heap[index];
+            heap[index] = heap[smallest];
+            heap[smallest] = temp;
+            index = smallest;
+          }
+        };
+        for (let i = Math.floor(heap.length / 2) - 1; i >= 0; i--) {
+          bubbleDown(i);
+        }
+        while (heap.length > 0) {
+          const min = heap[0];
+          yield min.value;
+          const nextResult = min.iterator.next();
+          if (nextResult.done) {
+            heap[0] = heap[heap.length - 1];
+            heap.pop();
+            if (heap.length > 0) {
+              bubbleDown(0);
+            }
+          } else {
+            heap[0].value = nextResult.value;
+            bubbleDown(0);
+          }
+        }
+      }
+    });
+  }
+};
+
+// src/async-iter-flow.ts
+var Asynciterflow = class _Asynciterflow {
+  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) {
+    this.source = Symbol.asyncIterator in source ? source[Symbol.asyncIterator]() : source;
+  }
+  // Async Iterator protocol
+  /**
+   * 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]() {
+    return this.source;
+  }
+  /**
+   * Retrieves the next value from the async iterator.
+   *
+   * @returns A promise of an IteratorResult containing the next value or indicating completion
+   */
+  next() {
+    return this.source.next();
+  }
+  // Transformation operations
+  /**
+   * 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(fn) {
+    const self = this;
+    return new _Asynciterflow({
+      async *[Symbol.asyncIterator]() {
+        for await (const value of self) {
+          yield await fn(value);
+        }
+      }
+    });
+  }
+  /**
+   * 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) {
+    const self = this;
+    return new _Asynciterflow({
+      async *[Symbol.asyncIterator]() {
+        for await (const value of self) {
+          if (await predicate(value)) {
+            yield value;
+          }
+        }
+      }
+    });
+  }
+  /**
+   * 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) {
+    const self = this;
+    return new _Asynciterflow({
+      async *[Symbol.asyncIterator]() {
+        let count = 0;
+        for await (const value of self) {
+          if (count >= limit) break;
+          yield value;
+          count++;
+        }
+      }
+    });
+  }
+  /**
+   * 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) {
+    const self = this;
+    return new _Asynciterflow({
+      async *[Symbol.asyncIterator]() {
+        let dropped = 0;
+        for await (const value of self) {
+          if (dropped < count) {
+            dropped++;
+            continue;
+          }
+          yield value;
+        }
+      }
+    });
+  }
+  /**
+   * 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(fn) {
+    const self = this;
+    return new _Asynciterflow({
+      async *[Symbol.asyncIterator]() {
+        for await (const value of self) {
+          const result = await fn(value);
+          if (Symbol.asyncIterator in result) {
+            yield* result;
+          } else {
+            yield* result;
+          }
+        }
+      }
+    });
+  }
+  /**
+   * 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) {
+    const self = this;
+    return new _Asynciterflow({
+      async *[Symbol.asyncIterator]() {
+        yield* self;
+        for (const iterable of iterables) {
+          if (Symbol.asyncIterator in iterable) {
+            yield* iterable;
+          } else {
+            yield* iterable;
+          }
+        }
+      }
+    });
+  }
+  /**
+   * 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) {
+    const self = this;
+    return new _Asynciterflow({
+      async *[Symbol.asyncIterator]() {
+        let isFirst = true;
+        for await (const value of self) {
+          if (!isFirst) {
+            yield separator;
+          }
+          yield value;
+          isFirst = false;
+        }
+      }
+    });
+  }
+  /**
+   * 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(fn, initial) {
+    const self = this;
+    return new _Asynciterflow({
+      async *[Symbol.asyncIterator]() {
+        let accumulator = initial;
+        yield accumulator;
+        for await (const value of self) {
+          accumulator = await fn(accumulator, value);
+          yield accumulator;
+        }
+      }
+    });
+  }
+  /**
+   * 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() {
+    const self = this;
+    return new _Asynciterflow({
+      async *[Symbol.asyncIterator]() {
+        let index = 0;
+        for await (const value of self) {
+          yield [index, value];
+          index++;
+        }
+      }
+    });
+  }
+  /**
+   * 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() {
+    const self = this;
+    return new _Asynciterflow({
+      async *[Symbol.asyncIterator]() {
+        const buffer = await self.toArray();
+        for (let i = buffer.length - 1; i >= 0; i--) {
+          yield buffer[i];
+        }
+      }
+    });
+  }
+  /**
+   * 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() {
+    const self = this;
+    return new _Asynciterflow({
+      async *[Symbol.asyncIterator]() {
+        const buffer = await self.toArray();
+        buffer.sort((a, b) => {
+          if (typeof a === "number" && typeof b === "number") {
+            return a - b;
+          }
+          return String(a).localeCompare(String(b));
+        });
+        yield* buffer;
+      }
+    });
+  }
+  /**
+   * 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) {
+    const self = this;
+    return new _Asynciterflow({
+      async *[Symbol.asyncIterator]() {
+        const buffer = await self.toArray();
+        buffer.sort(compareFn);
+        yield* buffer;
+      }
+    });
+  }
+  // Terminal operations
+  /**
+   * 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]
+   * ```
+   */
+  async toArray() {
+    const result = [];
+    for await (const value of this) {
+      result.push(value);
+    }
+    return result;
+  }
+  /**
+   * 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
+   * ```
+   */
+  async count() {
+    let count = 0;
+    for await (const _ of this) {
+      count++;
+    }
+    return count;
+  }
+  /**
+   * 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));
+   * ```
+   */
+  async forEach(fn) {
+    for await (const value of this) {
+      await fn(value);
+    }
+  }
+  // Statistical operations
+  /**
+   * 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
+   * ```
+   */
+  async sum() {
+    let total = 0;
+    for await (const value of this) {
+      total += value;
+    }
+    return total;
+  }
+  /**
+   * 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
+   * ```
+   */
+  async mean() {
+    let total = 0;
+    let count = 0;
+    for await (const value of this) {
+      total += value;
+      count++;
+    }
+    return count === 0 ? void 0 : total / count;
+  }
+  /**
+   * 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
+   * ```
+   */
+  async min() {
+    let minimum = void 0;
+    for await (const value of this) {
+      if (minimum === void 0 || value < minimum) {
+        minimum = value;
+      }
+    }
+    return minimum;
+  }
+  /**
+   * 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
+   * ```
+   */
+  async max() {
+    let maximum = void 0;
+    for await (const value of this) {
+      if (maximum === void 0 || value > maximum) {
+        maximum = value;
+      }
+    }
+    return maximum;
+  }
+  /**
+   * 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
+   * ```
+   */
+  async median() {
+    const values = await this.toArray();
+    if (values.length === 0) return void 0;
+    values.sort((a, b) => a - b);
+    const mid = Math.floor(values.length / 2);
+    if (values.length % 2 === 0) {
+      return (values[mid - 1] + values[mid]) / 2;
+    } else {
+      return values[mid];
+    }
+  }
+  /**
+   * 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
+   * ```
+   */
+  async variance() {
+    const values = await this.toArray();
+    if (values.length === 0) return void 0;
+    const mean = values.reduce((sum, val) => sum + val, 0) / values.length;
+    let sumSquaredDiffs = 0;
+    for (let i = 0; i < values.length; i++) {
+      const diff = values[i] - mean;
+      sumSquaredDiffs += diff * diff;
+    }
+    return sumSquaredDiffs / values.length;
+  }
+  /**
+   * 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
+   * ```
+   */
+  async stdDev() {
+    const variance = await this.variance();
+    return variance === void 0 ? void 0 : Math.sqrt(variance);
+  }
+  /**
+   * 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
+   * ```
+   */
+  async percentile(p) {
+    validateRange(p, 0, 100, "percentile", "percentile");
+    const values = await this.toArray();
+    if (values.length === 0) return void 0;
+    values.sort((a, b) => a - b);
+    if (p === 0) return values[0];
+    if (p === 100) return values[values.length - 1];
+    const index = p / 100 * (values.length - 1);
+    const lower = Math.floor(index);
+    const upper = Math.ceil(index);
+    if (lower === upper) {
+      return values[lower];
+    }
+    const weight = index - lower;
+    return values[lower] * (1 - weight) + values[upper] * weight;
+  }
+  /**
+   * 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]
+   * ```
+   */
+  async mode() {
+    const values = await this.toArray();
+    if (values.length === 0) return void 0;
+    const frequency = /* @__PURE__ */ new Map();
+    let maxFreq = 0;
+    for (const value of values) {
+      const count = (frequency.get(value) || 0) + 1;
+      frequency.set(value, count);
+      maxFreq = Math.max(maxFreq, count);
+    }
+    const modes = [];
+    for (const [value, freq] of frequency) {
+      if (freq === maxFreq) {
+        modes.push(value);
+      }
+    }
+    return modes.sort((a, b) => a - b);
+  }
+  /**
+   * 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 }
+   * ```
+   */
+  async quartiles() {
+    const values = await this.toArray();
+    if (values.length === 0) return void 0;
+    values.sort((a, b) => a - b);
+    const calculatePercentile = (p) => {
+      if (p === 0) return values[0];
+      if (p === 100) return values[values.length - 1];
+      const index = p / 100 * (values.length - 1);
+      const lower = Math.floor(index);
+      const upper = Math.ceil(index);
+      if (lower === upper) {
+        return values[lower];
+      }
+      const weight = index - lower;
+      return values[lower] * (1 - weight) + values[upper] * weight;
+    };
+    return {
+      Q1: calculatePercentile(25),
+      Q2: calculatePercentile(50),
+      Q3: calculatePercentile(75)
+    };
+  }
+  /**
+   * 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
+   * ```
+   */
+  async span() {
+    let minimum = void 0;
+    let maximum = void 0;
+    for await (const value of this) {
+      if (minimum === void 0 || value < minimum) {
+        minimum = value;
+      }
+      if (maximum === void 0 || value > maximum) {
+        maximum = value;
+      }
+    }
+    return minimum === void 0 || maximum === void 0 ? void 0 : maximum - minimum;
+  }
+  /**
+   * 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
+   * ```
+   */
+  async product() {
+    let result = 1;
+    for await (const value of this) {
+      result *= value;
+    }
+    return result;
+  }
+  /**
+   * 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
+   * ```
+   */
+  async covariance(other) {
+    const values1 = await this.toArray();
+    const values2 = [];
+    if (Symbol.asyncIterator in other) {
+      for await (const value of other) {
+        values2.push(value);
+      }
+    } else {
+      for (const value of other) {
+        values2.push(value);
+      }
+    }
+    if (values1.length === 0 || values2.length === 0 || values1.length !== values2.length) {
+      return void 0;
+    }
+    const mean1 = values1.reduce((sum, val) => sum + val, 0) / values1.length;
+    const mean2 = values2.reduce((sum, val) => sum + val, 0) / values2.length;
+    let covariance = 0;
+    for (let i = 0; i < values1.length; i++) {
+      covariance += (values1[i] - mean1) * (values2[i] - mean2);
+    }
+    return covariance / values1.length;
+  }
+  /**
+   * 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
+   * ```
+   */
+  async correlation(other) {
+    const values1 = await this.toArray();
+    const values2 = [];
+    if (Symbol.asyncIterator in other) {
+      for await (const value of other) {
+        values2.push(value);
+      }
+    } else {
+      for (const value of other) {
+        values2.push(value);
+      }
+    }
+    if (values1.length === 0 || values2.length === 0 || values1.length !== values2.length) {
+      return void 0;
+    }
+    const mean1 = values1.reduce((sum, val) => sum + val, 0) / values1.length;
+    const mean2 = values2.reduce((sum, val) => sum + val, 0) / values2.length;
+    let covariance = 0;
+    let variance1 = 0;
+    let variance2 = 0;
+    for (let i = 0; i < values1.length; i++) {
+      const diff1 = values1[i] - mean1;
+      const diff2 = values2[i] - mean2;
+      covariance += diff1 * diff2;
+      variance1 += diff1 * diff1;
+      variance2 += diff2 * diff2;
+    }
+    const stdDev1 = Math.sqrt(variance1 / values1.length);
+    const stdDev2 = Math.sqrt(variance2 / values2.length);
+    if (stdDev1 === 0 || stdDev2 === 0) {
+      return void 0;
+    }
+    return covariance / (values1.length * stdDev1 * stdDev2);
+  }
+  // Windowing operations
+  /**
+   * 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) {
+    validatePositiveInteger(size, "size", "window");
+    const self = this;
+    return new _Asynciterflow({
+      async *[Symbol.asyncIterator]() {
+        const buffer = new Array(size);
+        let count = 0;
+        let index = 0;
+        for await (const value of self) {
+          buffer[index] = value;
+          count++;
+          index = (index + 1) % size;
+          if (count >= size) {
+            const window = new Array(size);
+            for (let i = 0; i < size; i++) {
+              window[i] = buffer[(index + i) % size];
+            }
+            yield window;
+          }
+        }
+      }
+    });
+  }
+  /**
+   * 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) {
+    validatePositiveInteger(size, "size", "chunk");
+    const self = this;
+    return new _Asynciterflow({
+      async *[Symbol.asyncIterator]() {
+        let buffer = new Array(size);
+        let bufferIndex = 0;
+        for await (const value of self) {
+          buffer[bufferIndex++] = value;
+          if (bufferIndex === size) {
+            yield buffer;
+            buffer = new Array(size);
+            bufferIndex = 0;
+          }
+        }
+        if (bufferIndex > 0) {
+          yield buffer.slice(0, bufferIndex);
+        }
+      }
+    });
+  }
+  /**
+   * 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() {
+    return this.window(2).map((arr) => [arr[0], arr[1]]);
+  }
+  // Set operations
+  /**
+   * 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() {
+    const self = this;
+    return new _Asynciterflow({
+      async *[Symbol.asyncIterator]() {
+        const seen = /* @__PURE__ */ new Set();
+        for await (const value of self) {
+          if (!seen.has(value)) {
+            seen.add(value);
+            yield value;
+          }
+        }
+      }
+    });
+  }
+  /**
+   * 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(keyFn) {
+    const self = this;
+    return new _Asynciterflow({
+      async *[Symbol.asyncIterator]() {
+        const seenKeys = /* @__PURE__ */ new Set();
+        for await (const value of self) {
+          const key = await keyFn(value);
+          if (!seenKeys.has(key)) {
+            seenKeys.add(key);
+            yield value;
+          }
+        }
+      }
+    });
+  }
+  // Utility operations
+  /**
+   * 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) {
+    const self = this;
+    return new _Asynciterflow({
+      async *[Symbol.asyncIterator]() {
+        for await (const value of self) {
+          await fn(value);
+          yield value;
+        }
+      }
+    });
+  }
+  /**
+   * 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) {
+    const self = this;
+    return new _Asynciterflow({
+      async *[Symbol.asyncIterator]() {
+        for await (const value of self) {
+          if (!await predicate(value)) break;
+          yield value;
+        }
+      }
+    });
+  }
+  /**
+   * 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) {
+    const self = this;
+    return new _Asynciterflow({
+      async *[Symbol.asyncIterator]() {
+        let dropping = true;
+        for await (const value of self) {
+          if (dropping && await predicate(value)) {
+            continue;
+          }
+          dropping = false;
+          yield value;
+        }
+      }
+    });
+  }
+  // Grouping operations (terminal)
+  /**
+   * 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]]
+   * ```
+   */
+  async partition(predicate) {
+    const truthy = [];
+    const falsy = [];
+    for await (const value of this) {
+      if (await predicate(value)) {
+        truthy.push(value);
+      } else {
+        falsy.push(value);
+      }
+    }
+    return [truthy, falsy];
+  }
+  /**
+   * 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'] }
+   * ```
+   */
+  async groupBy(keyFn) {
+    const groups = /* @__PURE__ */ new Map();
+    for await (const value of this) {
+      const key = await keyFn(value);
+      if (!groups.has(key)) {
+        groups.set(key, []);
+      }
+      groups.get(key).push(value);
+    }
+    return groups;
+  }
+  // Additional terminal operations
+  /**
+   * 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
+   * ```
+   */
+  async reduce(fn, initial) {
+    let accumulator = initial;
+    for await (const value of this) {
+      accumulator = await fn(accumulator, value);
+    }
+    return accumulator;
+  }
+  /**
+   * 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
+   * ```
+   */
+  async find(predicate) {
+    for await (const value of this) {
+      if (await predicate(value)) {
+        return value;
+      }
+    }
+    return void 0;
+  }
+  /**
+   * 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
+   * ```
+   */
+  async findIndex(predicate) {
+    let index = 0;
+    for await (const value of this) {
+      if (await predicate(value)) {
+        return index;
+      }
+      index++;
+    }
+    return -1;
+  }
+  /**
+   * 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
+   * ```
+   */
+  async some(predicate) {
+    for await (const value of this) {
+      if (await predicate(value)) {
+        return true;
+      }
+    }
+    return false;
+  }
+  /**
+   * 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
+   * ```
+   */
+  async every(predicate) {
+    for await (const value of this) {
+      if (!await predicate(value)) {
+        return false;
+      }
+    }
+    return true;
+  }
+  /**
+   * 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
+   * ```
+   */
+  async first(defaultValue) {
+    const result = await this.source.next();
+    return result.done ? defaultValue : result.value;
+  }
+  /**
+   * 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
+   * ```
+   */
+  async last(defaultValue) {
+    let lastValue = defaultValue;
+    let hasValue = false;
+    for await (const value of this) {
+      lastValue = value;
+      hasValue = true;
+    }
+    return hasValue ? lastValue : defaultValue;
+  }
+  /**
+   * 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
+   * ```
+   */
+  async nth(index) {
+    if (index < 0) {
+      return void 0;
+    }
+    let currentIndex = 0;
+    for await (const value of this) {
+      if (currentIndex === index) {
+        return value;
+      }
+      currentIndex++;
+    }
+    return void 0;
+  }
+  /**
+   * 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
+   * ```
+   */
+  async isEmpty() {
+    const result = await this.source.next();
+    return result.done === true;
+  }
+  /**
+   * 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
+   * ```
+   */
+  async includes(searchValue) {
+    for await (const value of this) {
+      if (value === searchValue) {
+        return true;
+      }
+    }
+    return false;
+  }
+  // Concurrent/Parallel processing operations
+  /**
+   * 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(fn, concurrency = 10) {
+    const self = this;
+    return new _Asynciterflow({
+      async *[Symbol.asyncIterator]() {
+        const promises = [];
+        const results = /* @__PURE__ */ new Map();
+        let nextIndex = 0;
+        let completedIndex = 0;
+        for await (const value of self) {
+          const currentIndex = nextIndex++;
+          const promise = fn(value).then((result) => ({
+            index: currentIndex,
+            value: result
+          }));
+          promises.push(promise);
+          if (promises.length >= concurrency) {
+            const completed = await Promise.race(promises);
+            results.set(completed.index, completed.value);
+            promises.splice(
+              promises.findIndex(
+                (p) => p.then((r) => r.index === completed.index)
+              ),
+              1
+            );
+            while (results.has(completedIndex)) {
+              yield results.get(completedIndex);
+              results.delete(completedIndex);
+              completedIndex++;
+            }
+          }
+        }
+        while (promises.length > 0) {
+          const completed = await Promise.race(promises);
+          results.set(completed.index, completed.value);
+          promises.splice(
+            promises.findIndex(
+              (p) => p.then((r) => r.index === completed.index)
+            ),
+            1
+          );
+          while (results.has(completedIndex)) {
+            yield results.get(completedIndex);
+            results.delete(completedIndex);
+            completedIndex++;
+          }
+        }
+      }
+    });
+  }
+  /**
+   * 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, concurrency = 10) {
+    const self = this;
+    return new _Asynciterflow({
+      async *[Symbol.asyncIterator]() {
+        const promises = [];
+        const results = /* @__PURE__ */ new Map();
+        let nextIndex = 0;
+        let completedIndex = 0;
+        for await (const value of self) {
+          const currentIndex = nextIndex++;
+          const promise = predicate(value).then((keep) => ({
+            index: currentIndex,
+            value,
+            keep
+          }));
+          promises.push(promise);
+          if (promises.length >= concurrency) {
+            const completed = await Promise.race(promises);
+            results.set(completed.index, {
+              value: completed.value,
+              keep: completed.keep
+            });
+            promises.splice(
+              promises.findIndex(
+                (p) => p.then((r) => r.index === completed.index)
+              ),
+              1
+            );
+            while (results.has(completedIndex)) {
+              const result = results.get(completedIndex);
+              if (result.keep) {
+                yield result.value;
+              }
+              results.delete(completedIndex);
+              completedIndex++;
+            }
+          }
+        }
+        while (promises.length > 0) {
+          const completed = await Promise.race(promises);
+          results.set(completed.index, {
+            value: completed.value,
+            keep: completed.keep
+          });
+          promises.splice(
+            promises.findIndex(
+              (p) => p.then((r) => r.index === completed.index)
+            ),
+            1
+          );
+          while (results.has(completedIndex)) {
+            const result = results.get(completedIndex);
+            if (result.keep) {
+              yield result.value;
+            }
+            results.delete(completedIndex);
+            completedIndex++;
+          }
+        }
+      }
+    });
+  }
+  /**
+   * 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(fn, concurrency = 10) {
+    const self = this;
+    return new _Asynciterflow({
+      async *[Symbol.asyncIterator]() {
+        const promises = [];
+        const results = /* @__PURE__ */ new Map();
+        let nextIndex = 0;
+        let completedIndex = 0;
+        for await (const value of self) {
+          const currentIndex = nextIndex++;
+          const promise = fn(value).then((values) => ({
+            index: currentIndex,
+            values
+          }));
+          promises.push(promise);
+          if (promises.length >= concurrency) {
+            const completed = await Promise.race(promises);
+            results.set(completed.index, completed.values);
+            promises.splice(
+              promises.findIndex(
+                (p) => p.then((r) => r.index === completed.index)
+              ),
+              1
+            );
+            while (results.has(completedIndex)) {
+              const result = results.get(completedIndex);
+              if (Symbol.asyncIterator in result) {
+                yield* result;
+              } else {
+                yield* result;
+              }
+              results.delete(completedIndex);
+              completedIndex++;
+            }
+          }
+        }
+        while (promises.length > 0) {
+          const completed = await Promise.race(promises);
+          results.set(completed.index, completed.values);
+          promises.splice(
+            promises.findIndex(
+              (p) => p.then((r) => r.index === completed.index)
+            ),
+            1
+          );
+          while (results.has(completedIndex)) {
+            const result = results.get(completedIndex);
+            if (Symbol.asyncIterator in result) {
+              yield* result;
+            } else {
+              yield* result;
+            }
+            results.delete(completedIndex);
+            completedIndex++;
+          }
+        }
+      }
+    });
+  }
+  // Backpressure handling
+  /**
+   * 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) {
+    return this.chunk(size);
+  }
+  /**
+   * 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) {
+    const self = this;
+    return new _Asynciterflow({
+      async *[Symbol.asyncIterator]() {
+        let lastEmitTime = 0;
+        for await (const value of self) {
+          const now = Date.now();
+          if (now - lastEmitTime >= intervalMs) {
+            lastEmitTime = now;
+            yield value;
+          } else {
+            const delay = intervalMs - (now - lastEmitTime);
+            await new Promise((resolve) => setTimeout(resolve, delay));
+            lastEmitTime = Date.now();
+            yield value;
+          }
+        }
+      }
+    });
+  }
+  /**
+   * 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) {
+    const self = this;
+    return new _Asynciterflow({
+      async *[Symbol.asyncIterator]() {
+        const buffer = [];
+        let lastValue;
+        let hasValue = false;
+        for await (const value of self) {
+          hasValue = true;
+          lastValue = value;
+          buffer.push(value);
+          await new Promise((resolve) => setTimeout(resolve, waitMs));
+          if (lastValue === value && buffer[buffer.length - 1] === value) {
+            yield value;
+            buffer.length = 0;
+          }
+        }
+        if (hasValue && buffer.length > 0 && lastValue !== void 0) {
+          yield lastValue;
+        }
+      }
+    });
+  }
+  // Error handling
+  /**
+   * 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) {
+    const self = this;
+    return new _Asynciterflow({
+      async *[Symbol.asyncIterator]() {
+        try {
+          for await (const value of self) {
+            yield value;
+          }
+        } catch (error) {
+          const fallback = await handler(error);
+          if (typeof fallback === "object" && fallback !== null && (Symbol.asyncIterator in fallback || Symbol.iterator in fallback)) {
+            if (Symbol.asyncIterator in fallback) {
+              yield* fallback;
+            } else {
+              yield* fallback;
+            }
+          } else {
+            yield fallback;
+          }
+        }
+      }
+    });
+  }
+  /**
+   * 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, delayMs = 0) {
+    const self = this;
+    return new _Asynciterflow({
+      async *[Symbol.asyncIterator]() {
+        const iterator = self[Symbol.asyncIterator]();
+        let retryCount = 0;
+        while (true) {
+          try {
+            const result = await iterator.next();
+            if (result.done) break;
+            yield result.value;
+            retryCount = 0;
+          } catch (error) {
+            if (retryCount < maxRetries) {
+              retryCount++;
+              if (delayMs > 0) {
+                await new Promise((resolve) => setTimeout(resolve, delayMs));
+              }
+            } else {
+              throw error;
+            }
+          }
+        }
+      }
+    });
+  }
+  /**
+   * 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) {
+    const self = this;
+    return new _Asynciterflow({
+      async *[Symbol.asyncIterator]() {
+        for await (const value of self) {
+          try {
+            yield value;
+          } catch (error) {
+            await handler(error, value);
+          }
+        }
+      }
+    });
+  }
+};
+function asyncIter(source) {
+  if (Symbol.asyncIterator in source) {
+    return new Asynciterflow(source);
+  }
+  return new Asynciterflow({
+    async *[Symbol.asyncIterator]() {
+      yield* source;
+    }
+  });
+}
+((asyncIter2) => {
+  function zip(iter1, iter2) {
+    return new Asynciterflow({
+      async *[Symbol.asyncIterator]() {
+        const it1 = Symbol.asyncIterator in iter1 ? iter1[Symbol.asyncIterator]() : (async function* () {
+          yield* iter1;
+        })();
+        const it2 = Symbol.asyncIterator in iter2 ? iter2[Symbol.asyncIterator]() : (async function* () {
+          yield* iter2;
+        })();
+        while (true) {
+          const result1 = await it1.next();
+          const result2 = await it2.next();
+          if (result1.done || result2.done) {
+            break;
+          }
+          yield [result1.value, result2.value];
+        }
+      }
+    });
+  }
+  asyncIter2.zip = zip;
+  function zipWith(iter1, iter2, fn) {
+    return zip(iter1, iter2).map(async ([a, b]) => await fn(a, b));
+  }
+  asyncIter2.zipWith = zipWith;
+  function range(startOrStop, stop, step = 1) {
+    const actualStart = stop === void 0 ? 0 : startOrStop;
+    const actualStop = stop === void 0 ? startOrStop : stop;
+    return new Asynciterflow({
+      async *[Symbol.asyncIterator]() {
+        if (step === 0) {
+          validateNonZero(step, "step", "range");
+        }
+        if (step > 0) {
+          for (let i = actualStart; i < actualStop; i += step) {
+            yield i;
+          }
+        } else {
+          for (let i = actualStart; i > actualStop; i += step) {
+            yield i;
+          }
+        }
+      }
+    });
+  }
+  asyncIter2.range = range;
+  function repeat(value, times) {
+    return new Asynciterflow({
+      async *[Symbol.asyncIterator]() {
+        if (times === void 0) {
+          while (true) {
+            yield value;
+          }
+        } else {
+          for (let i = 0; i < times; i++) {
+            yield value;
+          }
+        }
+      }
+    });
+  }
+  asyncIter2.repeat = repeat;
+  function interleave(...iterables) {
+    return new Asynciterflow({
+      async *[Symbol.asyncIterator]() {
+        if (iterables.length === 0) return;
+        const iterators = iterables.map(
+          (it) => Symbol.asyncIterator in it ? it[Symbol.asyncIterator]() : (async function* () {
+            yield* it;
+          })()
+        );
+        const active = new Set(iterators);
+        while (active.size > 0) {
+          for (const iterator of iterators) {
+            if (!active.has(iterator)) continue;
+            const result = await iterator.next();
+            if (result.done) {
+              active.delete(iterator);
+            } else {
+              yield result.value;
+            }
+          }
+        }
+      }
+    });
+  }
+  asyncIter2.interleave = interleave;
+  function merge(...args) {
+    let compareFn;
+    let iterables;
+    if (typeof args[0] === "function") {
+      compareFn = args[0];
+      iterables = args.slice(1);
+    } else {
+      compareFn = (a, b) => {
+        if (a < b) return -1;
+        if (a > b) return 1;
+        return 0;
+      };
+      iterables = args;
+    }
+    return new Asynciterflow({
+      async *[Symbol.asyncIterator]() {
+        if (iterables.length === 0) return;
+        const heap = [];
+        for (let i = 0; i < iterables.length; i++) {
+          const iterable = iterables[i];
+          const iterator = Symbol.asyncIterator in iterable ? iterable[Symbol.asyncIterator]() : (async function* () {
+            yield* iterable;
+          })();
+          const result = await iterator.next();
+          if (!result.done) {
+            heap.push({ value: result.value, iterator, index: i });
+          }
+        }
+        const bubbleDown = (index) => {
+          const length = heap.length;
+          while (true) {
+            let smallest = index;
+            const leftChild = 2 * index + 1;
+            const rightChild = 2 * index + 2;
+            if (leftChild < length && compareFn(heap[leftChild].value, heap[smallest].value) < 0) {
+              smallest = leftChild;
+            }
+            if (rightChild < length && compareFn(heap[rightChild].value, heap[smallest].value) < 0) {
+              smallest = rightChild;
+            }
+            if (smallest === index) break;
+            [heap[index], heap[smallest]] = [heap[smallest], heap[index]];
+            index = smallest;
+          }
+        };
+        for (let i = Math.floor(heap.length / 2) - 1; i >= 0; i--) {
+          bubbleDown(i);
+        }
+        while (heap.length > 0) {
+          const { value, iterator } = heap[0];
+          yield value;
+          const result = await iterator.next();
+          if (result.done) {
+            heap[0] = heap[heap.length - 1];
+            heap.pop();
+            if (heap.length > 0) {
+              bubbleDown(0);
+            }
+          } else {
+            heap[0].value = result.value;
+            bubbleDown(0);
+          }
+        }
+      }
+    });
+  }
+  asyncIter2.merge = merge;
+  function chain(...iterables) {
+    return new Asynciterflow({
+      async *[Symbol.asyncIterator]() {
+        for (const iterable of iterables) {
+          if (Symbol.asyncIterator in iterable) {
+            yield* iterable;
+          } else {
+            yield* iterable;
+          }
+        }
+      }
+    });
+  }
+  asyncIter2.chain = chain;
+  function fromGenerator(fn) {
+    return new Asynciterflow(fn());
+  }
+  asyncIter2.fromGenerator = fromGenerator;
+  function fromPromise(promise) {
+    return new Asynciterflow({
+      async *[Symbol.asyncIterator]() {
+        yield await promise;
+      }
+    });
+  }
+  asyncIter2.fromPromise = fromPromise;
+  function fromPromises(promises) {
+    return new Asynciterflow({
+      async *[Symbol.asyncIterator]() {
+        const pending = new Set(promises);
+        const results = /* @__PURE__ */ new Map();
+        const indexed = promises.map((p, i) => p.then((v) => ({ i, v })));
+        while (pending.size > 0) {
+          const result = await Promise.race(indexed);
+          results.set(result.i, result.v);
+          pending.delete(promises[result.i]);
+          let nextIndex = promises.length - pending.size - 1;
+          while (results.has(nextIndex)) {
+            yield results.get(nextIndex);
+            results.delete(nextIndex);
+            nextIndex++;
+          }
+        }
+      }
+    });
+  }
+  asyncIter2.fromPromises = fromPromises;
+})(asyncIter || (asyncIter = {}));
+
+// src/debug.ts
+var DebugState = class {
+  config = {
+    enabled: false,
+    traceOperations: false,
+    traceInput: false,
+    traceOutput: false,
+    logToConsole: false,
+    maxTraceEntries: 1e3
+  };
+  traces = [];
+  /**
+   * Enable debug mode with optional configuration
+   */
+  enable(config2) {
+    this.config = {
+      ...this.config,
+      enabled: true,
+      traceOperations: true,
+      ...config2
+    };
+    if (this.config.logToConsole) {
+      console.log("[iterflow Debug] Debug mode enabled", this.config);
+    }
+  }
+  /**
+   * Disable debug mode
+   */
+  disable() {
+    this.config.enabled = false;
+    this.config.traceOperations = false;
+    if (this.config.logToConsole) {
+      console.log("[iterflow Debug] Debug mode disabled");
+    }
+  }
+  /**
+   * Check if debug mode is enabled
+   */
+  isEnabled() {
+    return this.config.enabled;
+  }
+  /**
+   * Get current configuration
+   */
+  getConfig() {
+    return { ...this.config };
+  }
+  /**
+   * Add a trace entry
+   */
+  trace(entry) {
+    if (!this.config.traceOperations) {
+      return;
+    }
+    if (this.traces.length >= (this.config.maxTraceEntries || 1e3)) {
+      this.traces.shift();
+    }
+    this.traces.push(entry);
+    if (this.config.logToConsole) {
+      this.logTrace(entry);
+    }
+  }
+  /**
+   * Get all trace entries
+   */
+  getTraces() {
+    return [...this.traces];
+  }
+  /**
+   * Clear all traces
+   */
+  clearTraces() {
+    this.traces = [];
+    if (this.config.logToConsole) {
+      console.log("[iterflow Debug] Traces cleared");
+    }
+  }
+  /**
+   * Get traces for a specific operation
+   */
+  getTracesForOperation(operation) {
+    return this.traces.filter((t) => t.operation === operation);
+  }
+  /**
+   * Get summary statistics for traces
+   */
+  getTraceSummary() {
+    const summary = {};
+    for (const trace of this.traces) {
+      if (!summary[trace.operation]) {
+        summary[trace.operation] = { count: 0, totalDuration: 0, errors: 0 };
+      }
+      const operationSummary = summary[trace.operation];
+      operationSummary.count++;
+      if (trace.duration !== void 0) {
+        operationSummary.totalDuration += trace.duration;
+      }
+      if (trace.error) {
+        operationSummary.errors++;
+      }
+    }
+    const result = {};
+    for (const [op, stats] of Object.entries(summary)) {
+      result[op] = {
+        count: stats.count,
+        avgDuration: stats.count > 0 ? stats.totalDuration / stats.count : 0,
+        errors: stats.errors
+      };
+    }
+    return result;
+  }
+  /**
+   * Log a trace entry to console
+   */
+  logTrace(entry) {
+    const timestamp = new Date(entry.timestamp).toISOString();
+    const duration = entry.duration !== void 0 ? `${entry.duration.toFixed(2)}ms` : "N/A";
+    if (entry.error) {
+      console.error(
+        `[iterflow Debug] ${timestamp} | ${entry.operation} | ERROR | ${duration}`,
+        entry.error
+      );
+    } else {
+      console.log(
+        `[iterflow Debug] ${timestamp} | ${entry.operation} | ${duration}`
+      );
+      if (this.config.traceInput && entry.input !== void 0) {
+        console.log("  Input:", entry.input);
+      }
+      if (this.config.traceOutput && entry.output !== void 0) {
+        console.log("  Output:", entry.output);
+      }
+      if (entry.metadata) {
+        console.log("  Metadata:", entry.metadata);
+      }
+    }
+  }
+};
+var debugState = new DebugState();
+function enableDebug(config2) {
+  debugState.enable(config2);
+}
+function disableDebug() {
+  debugState.disable();
+}
+function isDebugEnabled() {
+  return debugState.isEnabled();
+}
+function getDebugConfig() {
+  return debugState.getConfig();
+}
+function addTrace(entry) {
+  debugState.trace(entry);
+}
+function getTraces() {
+  return debugState.getTraces();
+}
+function clearTraces() {
+  debugState.clearTraces();
+}
+function getTracesForOperation(operation) {
+  return debugState.getTracesForOperation(operation);
+}
+function getTraceSummary() {
+  return debugState.getTraceSummary();
+}
+function traceOperation(operation, fn, metadata) {
+  if (!debugState.isEnabled()) {
+    return fn();
+  }
+  const startTime = performance.now();
+  const timestamp = Date.now();
+  try {
+    const result = fn();
+    const duration = performance.now() - startTime;
+    debugState.trace({
+      operation,
+      timestamp,
+      duration,
+      output: debugState.getConfig().traceOutput ? result : void 0,
+      metadata
+    });
+    return result;
+  } catch (error) {
+    const duration = performance.now() - startTime;
+    debugState.trace({
+      operation,
+      timestamp,
+      duration,
+      error,
+      metadata
+    });
+    throw error;
+  }
+}
+async function traceOperationAsync(operation, fn, metadata) {
+  if (!debugState.isEnabled()) {
+    return fn();
+  }
+  const startTime = performance.now();
+  const timestamp = Date.now();
+  try {
+    const result = await fn();
+    const duration = performance.now() - startTime;
+    debugState.trace({
+      operation,
+      timestamp,
+      duration,
+      output: debugState.getConfig().traceOutput ? result : void 0,
+      metadata
+    });
+    return result;
+  } catch (error) {
+    const duration = performance.now() - startTime;
+    debugState.trace({
+      operation,
+      timestamp,
+      duration,
+      error,
+      metadata
+    });
+    throw error;
+  }
+}
+
+// src/recovery.ts
+function withErrorRecovery(fn, errorHandler) {
+  return (value, index) => {
+    try {
+      return fn(value, index);
+    } catch (error) {
+      return errorHandler(error, value, index);
+    }
+  };
+}
+function withRetry(fn, options = {}) {
+  const { maxAttempts = 3, delay = 0, backoff = false, onRetry } = options;
+  return (...args) => {
+    let lastError;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      try {
+        return fn(...args);
+      } catch (error) {
+        lastError = error;
+        if (attempt < maxAttempts) {
+          if (onRetry) {
+            onRetry(attempt, lastError);
+          }
+        }
+      }
+    }
+    throw new OperationError(
+      `Operation failed after ${maxAttempts} attempts`,
+      "retry",
+      lastError
+    );
+  };
+}
+function withRetryAsync(fn, options = {}) {
+  const { maxAttempts = 3, delay = 0, backoff = false, onRetry } = options;
+  return async (...args) => {
+    let lastError;
+    let currentDelay = delay;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      try {
+        return await fn(...args);
+      } catch (error) {
+        lastError = error;
+        if (attempt < maxAttempts) {
+          if (onRetry) {
+            onRetry(attempt, lastError);
+          }
+          if (currentDelay > 0) {
+            await new Promise((resolve) => setTimeout(resolve, currentDelay));
+          }
+          if (backoff) {
+            currentDelay *= 2;
+          }
+        }
+      }
+    }
+    throw new OperationError(
+      `Operation failed after ${maxAttempts} attempts`,
+      "retry",
+      lastError
+    );
+  };
+}
+function withDefault(fn, defaultValue) {
+  return (value) => {
+    try {
+      return fn(value);
+    } catch {
+      return defaultValue;
+    }
+  };
+}
+function tryOr(fn, fallback) {
+  return (value) => {
+    try {
+      return fn(value);
+    } catch {
+      return fallback;
+    }
+  };
+}
+function tryCatch(fn, value) {
+  try {
+    return [fn(value), void 0];
+  } catch (error) {
+    return [void 0, error];
+  }
+}
+async function tryCatchAsync(fn, value) {
+  try {
+    return [await fn(value), void 0];
+  } catch (error) {
+    return [void 0, error];
+  }
+}
+function toResult(fn) {
+  return (value) => {
+    try {
+      return { success: true, value: fn(value) };
+    } catch (error) {
+      return { success: false, error };
+    }
+  };
+}
+function toResultAsync(fn) {
+  return async (value) => {
+    try {
+      return { success: true, value: await fn(value) };
+    } catch (error) {
+      return { success: false, error };
+    }
+  };
+}
+function safePredicate(predicate, defaultValue = false) {
+  return (value, index) => {
+    try {
+      return predicate(value, index);
+    } catch {
+      return defaultValue;
+    }
+  };
+}
+function safeComparator(comparator, defaultComparison = 0) {
+  return (a, b) => {
+    try {
+      return comparator(a, b);
+    } catch {
+      return defaultComparison;
+    }
+  };
+}
+function errorBoundary(fn, options = {}) {
+  const { onError, rethrow = true, defaultValue } = options;
+  return (...args) => {
+    try {
+      return fn(...args);
+    } catch (error) {
+      if (onError) {
+        onError(error, args);
+      }
+      if (rethrow) {
+        throw error;
+      }
+      return defaultValue;
+    }
+  };
+}
+
+// src/deprecation.ts
+var config = {
+  enabled: typeof process !== "undefined" && process.env.NODE_ENV !== "production",
+  showStackTrace: false
+};
+var warnedFeatures = /* @__PURE__ */ new Set();
+function configureDeprecation(options) {
+  config = { ...config, ...options };
+}
+function getDeprecationConfig() {
+  return { ...config };
+}
+function clearDeprecationWarnings() {
+  warnedFeatures.clear();
+}
+function emitWarning(warning) {
+  if (!config.enabled) return;
+  if (warnedFeatures.has(warning.feature)) return;
+  warnedFeatures.add(warning.feature);
+  if (config.handler) {
+    config.handler(warning);
+    return;
+  }
+  let message = `[iterflow] DEPRECATED: ${warning.feature} has been deprecated since v${warning.since}`;
+  if (warning.removeIn) {
+    message += ` and will be removed in v${warning.removeIn}`;
+  }
+  if (warning.alternative) {
+    message += `
+Please use ${warning.alternative} instead.`;
+  }
+  if (warning.message) {
+    message += `
+${warning.message}`;
+  }
+  if (typeof process !== "undefined" && process.emitWarning) {
+    const options = {
+      type: "DeprecationWarning",
+      code: "ITERFLOW_DEPRECATION",
+      detail: warning.message
+    };
+    process.emitWarning(message, options);
+  } else {
+    console.warn(message);
+  }
+  if (config.showStackTrace && warning.stack) {
+    console.warn("Stack trace:", warning.stack);
+  }
+}
+function deprecate(options) {
+  const warning = {
+    ...options,
+    stack: config.showStackTrace ? new Error().stack : void 0
+  };
+  emitWarning(warning);
+}
+function deprecated(options) {
+  return function(target, propertyKey, descriptor) {
+    const originalMethod = descriptor.value;
+    if (!originalMethod) return;
+    const className = target.constructor?.name || "Object";
+    const feature = `${className}.${propertyKey}`;
+    descriptor.value = function(...args) {
+      deprecate({ ...options, feature });
+      return originalMethod.apply(this, args);
+    };
+    return descriptor;
+  };
+}
+function deprecatedFunction(fn, options) {
+  return function(...args) {
+    deprecate(options);
+    return fn.apply(this, args);
+  };
+}
+function hasDeprecationWarning(feature) {
+  return warnedFeatures.has(feature);
+}
+
+// src/index.ts
+function iter(source) {
+  return new iterflow(source);
+}
+((iter2) => {
+  function zip(iter1, iter22) {
+    return new iterflow({
+      *[Symbol.iterator]() {
+        const it1 = iter1[Symbol.iterator]();
+        const it2 = iter22[Symbol.iterator]();
+        while (true) {
+          const result1 = it1.next();
+          const result2 = it2.next();
+          if (result1.done || result2.done) {
+            break;
+          }
+          yield [result1.value, result2.value];
+        }
+      }
+    });
+  }
+  iter2.zip = zip;
+  function zipWith(iter1, iter22, fn) {
+    return zip(iter1, iter22).map(([a, b]) => fn(a, b));
+  }
+  iter2.zipWith = zipWith;
+  function range(startOrStop, stop, step = 1) {
+    const actualStart = stop === void 0 ? 0 : startOrStop;
+    const actualStop = stop === void 0 ? startOrStop : stop;
+    return new iterflow({
+      *[Symbol.iterator]() {
+        validateNonZero(step, "step", "range");
+        if (step > 0) {
+          for (let i = actualStart; i < actualStop; i += step) {
+            yield i;
+          }
+        } else {
+          for (let i = actualStart; i > actualStop; i += step) {
+            yield i;
+          }
+        }
+      }
+    });
+  }
+  iter2.range = range;
+  function repeat(value, times) {
+    return new iterflow({
+      *[Symbol.iterator]() {
+        if (times === void 0) {
+          while (true) {
+            yield value;
+          }
+        } else {
+          for (let i = 0; i < times; i++) {
+            yield value;
+          }
+        }
+      }
+    });
+  }
+  iter2.repeat = repeat;
+  function interleave(...iterables) {
+    return new iterflow({
+      *[Symbol.iterator]() {
+        if (iterables.length === 0) return;
+        const iterators = iterables.map((it) => it[Symbol.iterator]());
+        const active = new Set(iterators);
+        while (active.size > 0) {
+          for (const iterator of iterators) {
+            if (!active.has(iterator)) continue;
+            const result = iterator.next();
+            if (result.done) {
+              active.delete(iterator);
+            } else {
+              yield result.value;
+            }
+          }
+        }
+      }
+    });
+  }
+  iter2.interleave = interleave;
+  function merge(...args) {
+    let compareFn;
+    let iterables;
+    if (typeof args[0] === "function") {
+      compareFn = args[0];
+      iterables = args.slice(1);
+    } else {
+      compareFn = (a, b) => {
+        if (a < b) return -1;
+        if (a > b) return 1;
+        return 0;
+      };
+      iterables = args;
+    }
+    return new iterflow({
+      *[Symbol.iterator]() {
+        if (iterables.length === 0) return;
+        const heap = [];
+        for (let i = 0; i < iterables.length; i++) {
+          const iterator = iterables[i][Symbol.iterator]();
+          const result = iterator.next();
+          if (!result.done) {
+            heap.push({ value: result.value, iterator, index: i });
+          }
+        }
+        const bubbleDown = (index) => {
+          const length = heap.length;
+          while (true) {
+            let smallest = index;
+            const leftChild = 2 * index + 1;
+            const rightChild = 2 * index + 2;
+            if (leftChild < length && compareFn(heap[leftChild].value, heap[smallest].value) < 0) {
+              smallest = leftChild;
+            }
+            if (rightChild < length && compareFn(heap[rightChild].value, heap[smallest].value) < 0) {
+              smallest = rightChild;
+            }
+            if (smallest === index) break;
+            [heap[index], heap[smallest]] = [heap[smallest], heap[index]];
+            index = smallest;
+          }
+        };
+        for (let i = Math.floor(heap.length / 2) - 1; i >= 0; i--) {
+          bubbleDown(i);
+        }
+        while (heap.length > 0) {
+          const { value, iterator } = heap[0];
+          yield value;
+          const result = iterator.next();
+          if (result.done) {
+            heap[0] = heap[heap.length - 1];
+            heap.pop();
+            if (heap.length > 0) {
+              bubbleDown(0);
+            }
+          } else {
+            heap[0].value = result.value;
+            bubbleDown(0);
+          }
+        }
+      }
+    });
+  }
+  iter2.merge = merge;
+  function chain(...iterables) {
+    return new iterflow({
+      *[Symbol.iterator]() {
+        for (const iterable of iterables) {
+          yield* iterable;
+        }
+      }
+    });
+  }
+  iter2.chain = chain;
+})(iter || (iter = {}));
+
+exports.Asynciterflow = Asynciterflow;
+exports.EmptySequenceError = EmptySequenceError;
+exports.IndexOutOfBoundsError = IndexOutOfBoundsError;
+exports.OperationError = OperationError;
+exports.TypeConversionError = TypeConversionError;
+exports.ValidationError = ValidationError;
+exports.addTrace = addTrace;
+exports.asyncIter = asyncIter;
+exports.clearDeprecationWarnings = clearDeprecationWarnings;
+exports.clearTraces = clearTraces;
+exports.configureDeprecation = configureDeprecation;
+exports.deprecate = deprecate;
+exports.deprecated = deprecated;
+exports.deprecatedFunction = deprecatedFunction;
+exports.disableDebug = disableDebug;
+exports.enableDebug = enableDebug;
+exports.errorBoundary = errorBoundary;
+exports.getDebugConfig = getDebugConfig;
+exports.getDeprecationConfig = getDeprecationConfig;
+exports.getTraceSummary = getTraceSummary;
+exports.getTraces = getTraces;
+exports.getTracesForOperation = getTracesForOperation;
+exports.hasDeprecationWarning = hasDeprecationWarning;
+exports.isDebugEnabled = isDebugEnabled;
+exports.iter = iter;
+exports.iterflow = iterflow;
+exports.iterflowError = iterflowError;
+exports.safeComparator = safeComparator;
+exports.safePredicate = safePredicate;
+exports.toInteger = toInteger;
+exports.toNumber = toNumber;
+exports.toResult = toResult;
+exports.toResultAsync = toResultAsync;
+exports.traceOperation = traceOperation;
+exports.traceOperationAsync = traceOperationAsync;
+exports.tryCatch = tryCatch;
+exports.tryCatchAsync = tryCatchAsync;
+exports.tryOr = tryOr;
+exports.validateComparator = validateComparator;
+exports.validateFiniteNumber = validateFiniteNumber;
+exports.validateFunction = validateFunction;
+exports.validateIndex = validateIndex;
+exports.validateIterable = validateIterable;
+exports.validateNonEmpty = validateNonEmpty;
+exports.validateNonNegativeInteger = validateNonNegativeInteger;
+exports.validateNonZero = validateNonZero;
+exports.validatePositiveInteger = validatePositiveInteger;
+exports.validateRange = validateRange;
+exports.withDefault = withDefault;
+exports.withErrorRecovery = withErrorRecovery;
+exports.withRetry = withRetry;
+exports.withRetryAsync = withRetryAsync;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map