iterflow 0.7.0 → 0.9.0

package/dist/index.d.cts

@@ -73,6 +73,25 @@ declare class iterflow<T> implements Iterable<T> {
      * ```
      */
     take(limit: number): iterflow<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 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: number): iterflow<T>;
     /**
      * Skips the first `count` elements from the iterator.
      *
@@ -205,13 +224,23 @@ declare class iterflow<T> implements Iterable<T> {
      * 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(): T[];
+    toArray(maxSize?: number): T[];
     /**
      * Counts the total number of elements in the iterator.
      * This is a terminal operation that consumes the iterator.
@@ -729,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>;
     /**
@@ -847,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.
      *
@@ -950,13 +1002,20 @@ declare class Asynciterflow<T> implements AsyncIterable<T> {
      * Collects all elements into an array.
      * This is a terminal operation that consumes the async iterator.
      *
-     * @returns A promise of an array containing all elements
+     * @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
      * ```
      */
-    toArray(): Promise<T[]>;
+    toArray(maxSize?: number): Promise<T[]>;
     /**
      * Counts the total number of elements in the async iterator.
      * This is a terminal operation that consumes the async iterator.
@@ -1545,6 +1604,80 @@ declare class Asynciterflow<T> implements AsyncIterable<T> {
      * ```
      */
     onError(handler: (error: unknown, value?: T) => void | Promise<void>): Asynciterflow<T>;
+    /**
+     * 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: number): Asynciterflow<T>;
+    /**
+     * 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: 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.
@@ -1761,6 +1894,20 @@ declare class TypeConversionError extends iterflowError {
     readonly expectedType: string;
     constructor(value: unknown, expectedType: string, operation?: string);
 }
+/**
+ * Error thrown when an operation exceeds its timeout duration
+ */
+declare class TimeoutError extends iterflowError {
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number, operation?: string);
+}
+/**
+ * Error thrown when an operation is aborted via AbortSignal
+ */
+declare class AbortError extends iterflowError {
+    readonly reason?: string;
+    constructor(operation?: string, reason?: string);
+}
 
 /**
  * Input validation utilities for iterflow operations
@@ -2127,4 +2274,4 @@ declare namespace iter {
     function chain<T>(...iterables: Iterable<T>[]): iterflow<T>;
 }
 
-export { Asynciterflow, type DebugConfig, EmptySequenceError, type ErrorHandler, IndexOutOfBoundsError, OperationError, type Result, type RetryOptions, type TraceEntry, TypeConversionError, ValidationError, addTrace, asyncIter, clearTraces, disableDebug, enableDebug, errorBoundary, getDebugConfig, getTraceSummary, getTraces, getTracesForOperation, isDebugEnabled, iter, iterflow, iterflowError, safeComparator, safePredicate, toInteger, toNumber, toResult, toResultAsync, traceOperation, traceOperationAsync, tryCatch, tryCatchAsync, tryOr, validateComparator, validateFiniteNumber, validateFunction, validateIndex, validateIterable, validateNonEmpty, validateNonNegativeInteger, validateNonZero, validatePositiveInteger, validateRange, withDefault, withErrorRecovery, withRetry, withRetryAsync };
+export { AbortError, Asynciterflow, type DebugConfig, EmptySequenceError, type ErrorHandler, IndexOutOfBoundsError, OperationError, type Result, type RetryOptions, TimeoutError, type TraceEntry, TypeConversionError, ValidationError, addTrace, asyncIter, clearTraces, disableDebug, enableDebug, errorBoundary, getDebugConfig, getTraceSummary, getTraces, getTracesForOperation, isDebugEnabled, iter, iterflow, iterflowError, safeComparator, safePredicate, toInteger, toNumber, toResult, toResultAsync, traceOperation, traceOperationAsync, tryCatch, tryCatchAsync, tryOr, validateComparator, validateFiniteNumber, validateFunction, validateIndex, validateIterable, validateNonEmpty, validateNonNegativeInteger, validateNonZero, validatePositiveInteger, validateRange, withDefault, withErrorRecovery, withRetry, withRetryAsync };

package/dist/index.d.ts

@@ -73,6 +73,25 @@ declare class iterflow<T> implements Iterable<T> {
      * ```
      */
     take(limit: number): iterflow<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 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: number): iterflow<T>;
     /**
      * Skips the first `count` elements from the iterator.
      *
@@ -205,13 +224,23 @@ declare class iterflow<T> implements Iterable<T> {
      * 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(): T[];
+    toArray(maxSize?: number): T[];
     /**
      * Counts the total number of elements in the iterator.
      * This is a terminal operation that consumes the iterator.
@@ -729,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>;
     /**
@@ -847,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.
      *
@@ -950,13 +1002,20 @@ declare class Asynciterflow<T> implements AsyncIterable<T> {
      * Collects all elements into an array.
      * This is a terminal operation that consumes the async iterator.
      *
-     * @returns A promise of an array containing all elements
+     * @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
      * ```
      */
-    toArray(): Promise<T[]>;
+    toArray(maxSize?: number): Promise<T[]>;
     /**
      * Counts the total number of elements in the async iterator.
      * This is a terminal operation that consumes the async iterator.
@@ -1545,6 +1604,80 @@ declare class Asynciterflow<T> implements AsyncIterable<T> {
      * ```
      */
     onError(handler: (error: unknown, value?: T) => void | Promise<void>): Asynciterflow<T>;
+    /**
+     * 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: number): Asynciterflow<T>;
+    /**
+     * 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: 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.
@@ -1761,6 +1894,20 @@ declare class TypeConversionError extends iterflowError {
     readonly expectedType: string;
     constructor(value: unknown, expectedType: string, operation?: string);
 }
+/**
+ * Error thrown when an operation exceeds its timeout duration
+ */
+declare class TimeoutError extends iterflowError {
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number, operation?: string);
+}
+/**
+ * Error thrown when an operation is aborted via AbortSignal
+ */
+declare class AbortError extends iterflowError {
+    readonly reason?: string;
+    constructor(operation?: string, reason?: string);
+}
 
 /**
  * Input validation utilities for iterflow operations
@@ -2127,4 +2274,4 @@ declare namespace iter {
     function chain<T>(...iterables: Iterable<T>[]): iterflow<T>;
 }
 
-export { Asynciterflow, type DebugConfig, EmptySequenceError, type ErrorHandler, IndexOutOfBoundsError, OperationError, type Result, type RetryOptions, type TraceEntry, TypeConversionError, ValidationError, addTrace, asyncIter, clearTraces, disableDebug, enableDebug, errorBoundary, getDebugConfig, getTraceSummary, getTraces, getTracesForOperation, isDebugEnabled, iter, iterflow, iterflowError, safeComparator, safePredicate, toInteger, toNumber, toResult, toResultAsync, traceOperation, traceOperationAsync, tryCatch, tryCatchAsync, tryOr, validateComparator, validateFiniteNumber, validateFunction, validateIndex, validateIterable, validateNonEmpty, validateNonNegativeInteger, validateNonZero, validatePositiveInteger, validateRange, withDefault, withErrorRecovery, withRetry, withRetryAsync };
+export { AbortError, Asynciterflow, type DebugConfig, EmptySequenceError, type ErrorHandler, IndexOutOfBoundsError, OperationError, type Result, type RetryOptions, TimeoutError, type TraceEntry, TypeConversionError, ValidationError, addTrace, asyncIter, clearTraces, disableDebug, enableDebug, errorBoundary, getDebugConfig, getTraceSummary, getTraces, getTracesForOperation, isDebugEnabled, iter, iterflow, iterflowError, safeComparator, safePredicate, toInteger, toNumber, toResult, toResultAsync, traceOperation, traceOperationAsync, tryCatch, tryCatchAsync, tryOr, validateComparator, validateFiniteNumber, validateFunction, validateIndex, validateIterable, validateNonEmpty, validateNonNegativeInteger, validateNonZero, validatePositiveInteger, validateRange, withDefault, withErrorRecovery, withRetry, withRetryAsync };