iterflow 0.8.0 → 0.10.0

package/dist/index.d.cts

@@ -758,11 +758,15 @@ declare class iterflow<T> implements Iterable<T> {
     /**
      * Alias for stdDev() method for compatibility.
      * Calculates the standard deviation of all numeric elements.
+     *
+     * @deprecated Use stdDev() instead. This alias will be removed in v1.0.0.
      */
     stddev(this: iterflow<number>): number | undefined;
     /**
      * Alias for drop() method for compatibility.
      * Skips the first `count` elements from the iterator.
+     *
+     * @deprecated Use drop() instead. This alias will be removed in v1.0.0.
      */
     skip(count: number): iterflow<T>;
     /**
@@ -876,6 +880,25 @@ declare class Asynciterflow<T> implements AsyncIterable<T> {
      * ```
      */
     drop(count: number): Asynciterflow<T>;
+    /**
+     * Limits the maximum number of iterations to prevent infinite loops.
+     * Unlike `take()` which silently stops at the limit, this method throws
+     * an OperationError if the limit is exceeded, making infinite loops explicit.
+     *
+     * @param maxIterations - Maximum number of iterations allowed (must be at least 1)
+     * @returns A new async iterflow that will throw if limit is exceeded
+     * @throws {ValidationError} If maxIterations is not a positive integer
+     * @throws {OperationError} If iteration count exceeds maxIterations
+     * @example
+     * ```typescript
+     * // Safely process potentially infinite async iterator
+     * await asyncIter.range(Infinity).limit(1000).toArray(); // Throws after 1000 iterations
+     *
+     * // Regular finite iterator works normally
+     * await asyncIter([1, 2, 3]).limit(10).toArray(); // [1, 2, 3]
+     * ```
+     */
+    limit(maxIterations: number): Asynciterflow<T>;
     /**
      * Maps each element to an async iterable and flattens the results.
      *
@@ -1631,6 +1654,30 @@ declare class Asynciterflow<T> implements AsyncIterable<T> {
      * ```
      */
     withSignal(signal: AbortSignal): Asynciterflow<T>;
+    /**
+     * Interleaves elements from this async iterator with elements from other async/sync iterables.
+     * Takes one element from each iterable in round-robin fashion.
+     *
+     * @param others - Variable number of async/sync iterables to interleave with
+     * @returns A new async iterflow with elements from all iterables interleaved
+     * @example
+     * ```typescript
+     * await asyncIter([1, 2, 3]).interleave([4, 5, 6]).toArray(); // [1, 4, 2, 5, 3, 6]
+     * ```
+     */
+    interleave(...others: Array<AsyncIterable<T> | Iterable<T>>): Asynciterflow<T>;
+    /**
+     * Merges this async iterator with other sorted async/sync iterables into a single sorted async iterator.
+     * Assumes all input iterables are already sorted in ascending order.
+     *
+     * @param others - Variable number of sorted async/sync iterables to merge with
+     * @returns A new async iterflow with all elements merged in sorted order
+     * @example
+     * ```typescript
+     * await asyncIter([1, 3, 5]).merge([2, 4, 6]).toArray(); // [1, 2, 3, 4, 5, 6]
+     * ```
+     */
+    merge(...others: Array<AsyncIterable<T> | Iterable<T>>): Asynciterflow<T>;
 }
 /**
  * Creates an async iterflow instance from an async iterable or iterable.

package/dist/index.d.ts

@@ -758,11 +758,15 @@ declare class iterflow<T> implements Iterable<T> {
     /**
      * Alias for stdDev() method for compatibility.
      * Calculates the standard deviation of all numeric elements.
+     *
+     * @deprecated Use stdDev() instead. This alias will be removed in v1.0.0.
      */
     stddev(this: iterflow<number>): number | undefined;
     /**
      * Alias for drop() method for compatibility.
      * Skips the first `count` elements from the iterator.
+     *
+     * @deprecated Use drop() instead. This alias will be removed in v1.0.0.
      */
     skip(count: number): iterflow<T>;
     /**
@@ -876,6 +880,25 @@ declare class Asynciterflow<T> implements AsyncIterable<T> {
      * ```
      */
     drop(count: number): Asynciterflow<T>;
+    /**
+     * Limits the maximum number of iterations to prevent infinite loops.
+     * Unlike `take()` which silently stops at the limit, this method throws
+     * an OperationError if the limit is exceeded, making infinite loops explicit.
+     *
+     * @param maxIterations - Maximum number of iterations allowed (must be at least 1)
+     * @returns A new async iterflow that will throw if limit is exceeded
+     * @throws {ValidationError} If maxIterations is not a positive integer
+     * @throws {OperationError} If iteration count exceeds maxIterations
+     * @example
+     * ```typescript
+     * // Safely process potentially infinite async iterator
+     * await asyncIter.range(Infinity).limit(1000).toArray(); // Throws after 1000 iterations
+     *
+     * // Regular finite iterator works normally
+     * await asyncIter([1, 2, 3]).limit(10).toArray(); // [1, 2, 3]
+     * ```
+     */
+    limit(maxIterations: number): Asynciterflow<T>;
     /**
      * Maps each element to an async iterable and flattens the results.
      *
@@ -1631,6 +1654,30 @@ declare class Asynciterflow<T> implements AsyncIterable<T> {
      * ```
      */
     withSignal(signal: AbortSignal): Asynciterflow<T>;
+    /**
+     * Interleaves elements from this async iterator with elements from other async/sync iterables.
+     * Takes one element from each iterable in round-robin fashion.
+     *
+     * @param others - Variable number of async/sync iterables to interleave with
+     * @returns A new async iterflow with elements from all iterables interleaved
+     * @example
+     * ```typescript
+     * await asyncIter([1, 2, 3]).interleave([4, 5, 6]).toArray(); // [1, 4, 2, 5, 3, 6]
+     * ```
+     */
+    interleave(...others: Array<AsyncIterable<T> | Iterable<T>>): Asynciterflow<T>;
+    /**
+     * Merges this async iterator with other sorted async/sync iterables into a single sorted async iterator.
+     * Assumes all input iterables are already sorted in ascending order.
+     *
+     * @param others - Variable number of sorted async/sync iterables to merge with
+     * @returns A new async iterflow with all elements merged in sorted order
+     * @example
+     * ```typescript
+     * await asyncIter([1, 3, 5]).merge([2, 4, 6]).toArray(); // [1, 2, 3, 4, 5, 6]
+     * ```
+     */
+    merge(...others: Array<AsyncIterable<T> | Iterable<T>>): Asynciterflow<T>;
 }
 /**
  * Creates an async iterflow instance from an async iterable or iterable.

package/dist/index.js

@@ -1599,6 +1599,8 @@ var iterflow = class _iterflow {
   /**
    * Alias for stdDev() method for compatibility.
    * Calculates the standard deviation of all numeric elements.
+   *
+   * @deprecated Use stdDev() instead. This alias will be removed in v1.0.0.
    */
   stddev() {
     return this.stdDev();
@@ -1606,6 +1608,8 @@ var iterflow = class _iterflow {
   /**
    * Alias for drop() method for compatibility.
    * Skips the first `count` elements from the iterator.
+   *
+   * @deprecated Use drop() instead. This alias will be removed in v1.0.0.
    */
   skip(count) {
     return this.drop(count);
@@ -1842,6 +1846,45 @@ var Asynciterflow = class _Asynciterflow {
       }
     });
   }
+  /**
+   * Limits the maximum number of iterations to prevent infinite loops.
+   * Unlike `take()` which silently stops at the limit, this method throws
+   * an OperationError if the limit is exceeded, making infinite loops explicit.
+   *
+   * @param maxIterations - Maximum number of iterations allowed (must be at least 1)
+   * @returns A new async iterflow that will throw if limit is exceeded
+   * @throws {ValidationError} If maxIterations is not a positive integer
+   * @throws {OperationError} If iteration count exceeds maxIterations
+   * @example
+   * ```typescript
+   * // Safely process potentially infinite async iterator
+   * await asyncIter.range(Infinity).limit(1000).toArray(); // Throws after 1000 iterations
+   *
+   * // Regular finite iterator works normally
+   * await asyncIter([1, 2, 3]).limit(10).toArray(); // [1, 2, 3]
+   * ```
+   */
+  limit(maxIterations) {
+    validatePositiveInteger(maxIterations, "maxIterations", "limit");
+    const self = this;
+    return new _Asynciterflow({
+      async *[Symbol.asyncIterator]() {
+        let count = 0;
+        for await (const value of self) {
+          if (count >= maxIterations) {
+            throw new OperationError(
+              `Iterator exceeded limit of ${maxIterations} iterations`,
+              "limit",
+              void 0,
+              { maxIterations }
+            );
+          }
+          yield value;
+          count++;
+        }
+      }
+    });
+  }
   /**
    * Maps each element to an async iterable and flattens the results.
    *
@@ -3422,6 +3465,116 @@ var Asynciterflow = class _Asynciterflow {
       }
     });
   }
+  /**
+   * Interleaves elements from this async iterator with elements from other async/sync iterables.
+   * Takes one element from each iterable in round-robin fashion.
+   *
+   * @param others - Variable number of async/sync iterables to interleave with
+   * @returns A new async iterflow with elements from all iterables interleaved
+   * @example
+   * ```typescript
+   * await asyncIter([1, 2, 3]).interleave([4, 5, 6]).toArray(); // [1, 4, 2, 5, 3, 6]
+   * ```
+   */
+  interleave(...others) {
+    const self = this;
+    return new _Asynciterflow({
+      async *[Symbol.asyncIterator]() {
+        const allIterables = [self, ...others];
+        if (allIterables.length === 0) return;
+        const iterators = allIterables.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;
+            }
+          }
+        }
+      }
+    });
+  }
+  /**
+   * Merges this async iterator with other sorted async/sync iterables into a single sorted async iterator.
+   * Assumes all input iterables are already sorted in ascending order.
+   *
+   * @param others - Variable number of sorted async/sync iterables to merge with
+   * @returns A new async iterflow with all elements merged in sorted order
+   * @example
+   * ```typescript
+   * await asyncIter([1, 3, 5]).merge([2, 4, 6]).toArray(); // [1, 2, 3, 4, 5, 6]
+   * ```
+   */
+  merge(...others) {
+    const self = this;
+    return new _Asynciterflow({
+      async *[Symbol.asyncIterator]() {
+        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 iterable = allIterables[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;
+            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 = await 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, iterator: min.iterator, index: min.index };
+            bubbleDown(0);
+          }
+        }
+      }
+    });
+  }
 };
 function asyncIter(source) {
   if (Symbol.asyncIterator in source) {