iterflow 0.7.0 → 0.9.0

package/dist/index.cjs

@@ -99,6 +99,30 @@ var TypeConversionError = class extends iterflowError {
     this.expectedType = expectedType;
   }
 };
+var TimeoutError = class extends iterflowError {
+  timeoutMs;
+  constructor(timeoutMs, operation) {
+    super(
+      `Operation timed out after ${timeoutMs}ms`,
+      operation,
+      { timeoutMs }
+    );
+    this.name = "TimeoutError";
+    this.timeoutMs = timeoutMs;
+  }
+};
+var AbortError = class extends iterflowError {
+  reason;
+  constructor(operation, reason) {
+    super(
+      reason ? `Operation aborted: ${reason}` : "Operation aborted",
+      operation,
+      { reason }
+    );
+    this.name = "AbortError";
+    this.reason = reason;
+  }
+};
 
 // src/validation.ts
 function validatePositiveInteger(value, paramName, operation) {
@@ -322,6 +346,56 @@ var iterflow = class _iterflow {
       }
     });
   }
+  /**
+   * 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 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 iterator
+   * iter.range(Infinity).limit(1000).toArray(); // Throws after 1000 iterations
+   *
+   * // Regular finite iterator works normally
+   * iter([1, 2, 3]).limit(10).toArray(); // [1, 2, 3]
+   * ```
+   */
+  limit(maxIterations) {
+    validatePositiveInteger(maxIterations, "maxIterations", "limit");
+    if (this._sourceArray) {
+      if (this._sourceArray.length > maxIterations) {
+        throw new OperationError(
+          `Iterator exceeded limit of ${maxIterations} iterations`,
+          "limit",
+          void 0,
+          { maxIterations, actualCount: this._sourceArray.length }
+        );
+      }
+      return new _iterflow(this._sourceArray);
+    }
+    const self = this;
+    return new _iterflow({
+      *[Symbol.iterator]() {
+        let count = 0;
+        for (const value of self) {
+          if (count >= maxIterations) {
+            throw new OperationError(
+              `Iterator exceeded limit of ${maxIterations} iterations`,
+              "limit",
+              void 0,
+              { maxIterations }
+            );
+          }
+          yield value;
+          count++;
+        }
+      }
+    });
+  }
   /**
    * Skips the first `count` elements from the iterator.
    *
@@ -577,17 +651,43 @@ var iterflow = class _iterflow {
    * Collects all elements into an array.
    * This is a terminal operation that consumes the iterator.
    *
-   * @returns An array containing all elements
+   * @param maxSize - Optional maximum array size. If provided and the iterator produces
+   *                  more elements, collection stops at maxSize (no error thrown).
+   *                  This is useful for safely collecting from potentially large iterators.
+   * @returns Array containing all elements (up to maxSize if specified)
+   * @throws {ValidationError} If maxSize is provided but not a positive integer
    * @example
    * ```typescript
    * iter([1, 2, 3]).map(x => x * 2).toArray(); // [2, 4, 6]
+   *
+   * // Safely collect from large/infinite iterator
+   * iter.range(Infinity).toArray(1000); // [0, 1, 2, ..., 999]
+   *
+   * // Works with finite iterators too
+   * iter([1, 2, 3]).toArray(10); // [1, 2, 3] (stops early)
    * ```
    */
-  toArray() {
+  toArray(maxSize) {
+    if (maxSize !== void 0) {
+      validatePositiveInteger(maxSize, "maxSize", "toArray");
+    }
     if (this._sourceArray) {
+      if (maxSize !== void 0) {
+        return this._sourceArray.slice(0, maxSize);
+      }
       return this._sourceArray.slice();
     }
-    return Array.from(this);
+    if (maxSize === void 0) {
+      return Array.from(this);
+    }
+    const result = [];
+    for (const value of this) {
+      if (result.length >= maxSize) {
+        break;
+      }
+      result.push(value);
+    }
+    return result;
   }
   /**
    * Counts the total number of elements in the iterator.
@@ -1501,6 +1601,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();
@@ -1508,6 +1610,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);
@@ -1744,6 +1848,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.
    *
@@ -1946,15 +2089,28 @@ var Asynciterflow = class _Asynciterflow {
    * 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
+   * @param maxSize - Optional maximum array size. If provided and the iterator produces
+   *                  more elements, collection stops at maxSize (no error thrown).
+   *                  This is useful for safely collecting from potentially large iterators.
+   * @returns Promise of array containing all elements (up to maxSize if specified)
+   * @throws {ValidationError} If maxSize is provided but not a positive integer
    * @example
    * ```typescript
    * await asyncIter([1, 2, 3]).map(async x => x * 2).toArray(); // [2, 4, 6]
+   *
+   * // Safely collect from large async iterator
+   * await asyncIter(infiniteStream).toArray(1000); // First 1000 items
    * ```
    */
-  async toArray() {
+  async toArray(maxSize) {
+    if (maxSize !== void 0) {
+      validatePositiveInteger(maxSize, "maxSize", "toArray");
+    }
     const result = [];
     for await (const value of this) {
+      if (maxSize !== void 0 && result.length >= maxSize) {
+        break;
+      }
       result.push(value);
     }
     return result;
@@ -3206,6 +3362,221 @@ var Asynciterflow = class _Asynciterflow {
       }
     });
   }
+  /**
+   * Adds a timeout to async iteration operations.
+   * If any single iteration (next() call) takes longer than the specified timeout,
+   * a TimeoutError is thrown. Each iteration gets its own timeout window.
+   *
+   * @param ms - Timeout duration in milliseconds (must be positive)
+   * @returns A new async iterflow with timeout protection
+   * @throws {ValidationError} If ms is not a positive number
+   * @throws {TimeoutError} If any iteration exceeds the timeout
+   * @example
+   * ```typescript
+   * // Protect against slow async operations
+   * await asyncIter([1, 2, 3])
+   *   .map(async x => {
+   *     await slowOperation(x); // Each must complete within 5000ms
+   *     return x;
+   *   })
+   *   .timeout(5000)
+   *   .toArray();
+   * ```
+   */
+  timeout(ms) {
+    validatePositiveInteger(ms, "timeout", "timeout");
+    const self = this;
+    return new _Asynciterflow({
+      async *[Symbol.asyncIterator]() {
+        const iterator = self[Symbol.asyncIterator]();
+        while (true) {
+          const timeoutPromise = new Promise((_, reject) => {
+            setTimeout(() => {
+              reject(new TimeoutError(ms, "timeout"));
+            }, ms);
+          });
+          const result = await Promise.race([iterator.next(), timeoutPromise]);
+          if (result.done) break;
+          yield result.value;
+        }
+      }
+    });
+  }
+  /**
+   * Adds AbortSignal support to the async iteration.
+   * If the signal is aborted, iteration stops immediately with an AbortError.
+   * Checks the signal before each iteration and listens for abort events.
+   *
+   * @param signal - AbortSignal to control iteration cancellation
+   * @returns A new async iterflow with abort support
+   * @throws {AbortError} If the signal is aborted
+   * @example
+   * ```typescript
+   * const controller = new AbortController();
+   *
+   * // Cancel after 5 seconds
+   * setTimeout(() => controller.abort('Timeout reached'), 5000);
+   *
+   * try {
+   *   await asyncIter(largeDataset)
+   *     .withSignal(controller.signal)
+   *     .map(processItem)
+   *     .toArray();
+   * } catch (error) {
+   *   if (error instanceof AbortError) {
+   *     console.log('Operation cancelled:', error.reason);
+   *   }
+   * }
+   * ```
+   */
+  withSignal(signal) {
+    const self = this;
+    return new _Asynciterflow({
+      async *[Symbol.asyncIterator]() {
+        if (signal.aborted) {
+          throw new AbortError(
+            "withSignal",
+            typeof signal.reason === "string" ? signal.reason : void 0
+          );
+        }
+        const iterator = self[Symbol.asyncIterator]();
+        let abortReject;
+        const abortPromise = new Promise((_, reject) => {
+          abortReject = reject;
+        });
+        const abortHandler = () => {
+          if (abortReject) {
+            abortReject(
+              new AbortError(
+                "withSignal",
+                typeof signal.reason === "string" ? signal.reason : void 0
+              )
+            );
+          }
+        };
+        signal.addEventListener("abort", abortHandler);
+        try {
+          while (true) {
+            const result = await Promise.race([iterator.next(), abortPromise]);
+            if (result.done) break;
+            yield result.value;
+          }
+        } finally {
+          signal.removeEventListener("abort", abortHandler);
+        }
+      }
+    });
+  }
+  /**
+   * 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) {
@@ -3949,10 +4320,12 @@ function iter(source) {
   iter2.chain = chain;
 })(iter || (iter = {}));
 
+exports.AbortError = AbortError;
 exports.Asynciterflow = Asynciterflow;
 exports.EmptySequenceError = EmptySequenceError;
 exports.IndexOutOfBoundsError = IndexOutOfBoundsError;
 exports.OperationError = OperationError;
+exports.TimeoutError = TimeoutError;
 exports.TypeConversionError = TypeConversionError;
 exports.ValidationError = ValidationError;
 exports.addTrace = addTrace;