iterflow 0.5.0 → 0.8.0

package/dist/index.js

@@ -97,6 +97,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) {
@@ -211,6 +235,7 @@ function validateIndex(index, size, operation) {
 // src/iter-flow.ts
 var iterflow = class _iterflow {
   source;
+  _sourceArray;
   /**
    * Creates a new iterflow instance from an iterable or iterator.
    *
@@ -222,7 +247,13 @@ var iterflow = class _iterflow {
    * ```
    */
   constructor(source) {
-    this.source = Symbol.iterator in source ? source[Symbol.iterator]() : source;
+    if (Array.isArray(source)) {
+      this._sourceArray = source;
+      this.source = source[Symbol.iterator]();
+    } else {
+      this._sourceArray = void 0;
+      this.source = Symbol.iterator in source ? source[Symbol.iterator]() : source;
+    }
   }
   // Iterator protocol
   /**
@@ -298,6 +329,9 @@ var iterflow = class _iterflow {
    * ```
    */
   take(limit) {
+    if (this._sourceArray) {
+      return new _iterflow(this._sourceArray.slice(0, limit));
+    }
     const self = this;
     return new _iterflow({
       *[Symbol.iterator]() {
@@ -310,6 +344,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.
    *
@@ -321,6 +405,9 @@ var iterflow = class _iterflow {
    * ```
    */
   drop(count) {
+    if (this._sourceArray) {
+      return new _iterflow(this._sourceArray.slice(count));
+    }
     const self = this;
     return new _iterflow({
       *[Symbol.iterator]() {
@@ -473,6 +560,9 @@ var iterflow = class _iterflow {
    * ```
    */
   reverse() {
+    if (this._sourceArray) {
+      return new _iterflow(this._sourceArray.slice().reverse());
+    }
     const self = this;
     return new _iterflow({
       *[Symbol.iterator]() {
@@ -500,6 +590,16 @@ var iterflow = class _iterflow {
    * ```
    */
   sort() {
+    if (this._sourceArray) {
+      return new _iterflow(
+        this._sourceArray.slice().sort((a, b) => {
+          if (typeof a === "number" && typeof b === "number") {
+            return a - b;
+          }
+          return String(a).localeCompare(String(b));
+        })
+      );
+    }
     const self = this;
     return new _iterflow({
       *[Symbol.iterator]() {
@@ -532,6 +632,9 @@ var iterflow = class _iterflow {
    * ```
    */
   sortBy(compareFn) {
+    if (this._sourceArray) {
+      return new _iterflow(this._sourceArray.slice().sort(compareFn));
+    }
     const self = this;
     return new _iterflow({
       *[Symbol.iterator]() {
@@ -546,14 +649,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() {
-    return Array.from(this);
+  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();
+    }
+    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.
@@ -566,6 +698,9 @@ var iterflow = class _iterflow {
    * ```
    */
   count() {
+    if (this._sourceArray) {
+      return this._sourceArray.length;
+    }
     let count = 0;
     for (const _ of this) {
       count++;
@@ -586,6 +721,13 @@ var iterflow = class _iterflow {
    * ```
    */
   sum() {
+    if (this._sourceArray) {
+      let total2 = 0;
+      for (let i = 0; i < this._sourceArray.length; i++) {
+        total2 += this._sourceArray[i];
+      }
+      return total2;
+    }
     let total = 0;
     for (const value of this) {
       total += value;
@@ -674,14 +816,14 @@ var iterflow = class _iterflow {
    * ```
    */
   median() {
-    const values = this.toArray();
+    const values = this._sourceArray || 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;
+    const sorted = values.slice().sort((a, b) => a - b);
+    const mid = Math.floor(sorted.length / 2);
+    if (sorted.length % 2 === 0) {
+      return (sorted[mid - 1] + sorted[mid]) / 2;
     } else {
-      return values[mid];
+      return sorted[mid];
     }
   }
   /**
@@ -699,7 +841,7 @@ var iterflow = class _iterflow {
    * ```
    */
   variance() {
-    const values = this.toArray();
+    const values = this._sourceArray || this.toArray();
     if (values.length === 0) return void 0;
     const mean = values.reduce((sum, val) => sum + val, 0) / values.length;
     let sumSquaredDiffs = 0;
@@ -747,19 +889,19 @@ var iterflow = class _iterflow {
    */
   percentile(p) {
     validateRange(p, 0, 100, "percentile", "percentile");
-    const values = this.toArray();
+    const values = this._sourceArray || 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 sorted = values.slice().sort((a, b) => a - b);
+    if (p === 0) return sorted[0];
+    if (p === 100) return sorted[sorted.length - 1];
+    const index = p / 100 * (sorted.length - 1);
     const lower = Math.floor(index);
     const upper = Math.ceil(index);
     if (lower === upper) {
-      return values[lower];
+      return sorted[lower];
     }
     const weight = index - lower;
-    return values[lower] * (1 - weight) + values[upper] * weight;
+    return sorted[lower] * (1 - weight) + sorted[upper] * weight;
   }
   /**
    * Finds the most frequent value(s) in the dataset.
@@ -777,7 +919,7 @@ var iterflow = class _iterflow {
    * ```
    */
   mode() {
-    const values = this.toArray();
+    const values = this._sourceArray || this.toArray();
     if (values.length === 0) return void 0;
     const frequency = /* @__PURE__ */ new Map();
     let maxFreq = 0;
@@ -810,20 +952,20 @@ var iterflow = class _iterflow {
    * ```
    */
   quartiles() {
-    const values = this.toArray();
+    const values = this._sourceArray || this.toArray();
     if (values.length === 0) return void 0;
-    values.sort((a, b) => a - b);
+    const sorted = values.slice().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);
+      if (p === 0) return sorted[0];
+      if (p === 100) return sorted[sorted.length - 1];
+      const index = p / 100 * (sorted.length - 1);
       const lower = Math.floor(index);
       const upper = Math.ceil(index);
       if (lower === upper) {
-        return values[lower];
+        return sorted[lower];
       }
       const weight = index - lower;
-      return values[lower] * (1 - weight) + values[upper] * weight;
+      return sorted[lower] * (1 - weight) + sorted[upper] * weight;
     };
     return {
       Q1: calculatePercentile(25),
@@ -895,7 +1037,7 @@ var iterflow = class _iterflow {
    * ```
    */
   covariance(other) {
-    const values1 = this.toArray();
+    const values1 = this._sourceArray || this.toArray();
     const values2 = Array.from(other);
     if (values1.length === 0 || values2.length === 0 || values1.length !== values2.length) {
       return void 0;
@@ -926,7 +1068,7 @@ var iterflow = class _iterflow {
    * ```
    */
   correlation(other) {
-    const values1 = this.toArray();
+    const values1 = this._sourceArray || this.toArray();
     const values2 = Array.from(other);
     if (values1.length === 0 || values2.length === 0 || values1.length !== values2.length) {
       return void 0;
@@ -1350,6 +1492,9 @@ var iterflow = class _iterflow {
    * ```
    */
   first(defaultValue) {
+    if (this._sourceArray) {
+      return this._sourceArray.length > 0 ? this._sourceArray[0] : defaultValue;
+    }
     const result = this.source.next();
     return result.done ? defaultValue : result.value;
   }
@@ -1367,6 +1512,9 @@ var iterflow = class _iterflow {
    * ```
    */
   last(defaultValue) {
+    if (this._sourceArray) {
+      return this._sourceArray.length > 0 ? this._sourceArray[this._sourceArray.length - 1] : defaultValue;
+    }
     let lastValue = defaultValue;
     let hasValue = false;
     for (const value of this) {
@@ -1389,6 +1537,9 @@ var iterflow = class _iterflow {
    * ```
    */
   nth(index) {
+    if (this._sourceArray) {
+      return index >= 0 && index < this._sourceArray.length ? this._sourceArray[index] : void 0;
+    }
     if (index < 0) {
       return void 0;
     }
@@ -1413,6 +1564,9 @@ var iterflow = class _iterflow {
    * ```
    */
   isEmpty() {
+    if (this._sourceArray) {
+      return this._sourceArray.length === 0;
+    }
     const result = this.source.next();
     return result.done === true;
   }
@@ -1431,6 +1585,9 @@ var iterflow = class _iterflow {
    * ```
    */
   includes(searchValue) {
+    if (this._sourceArray) {
+      return this._sourceArray.includes(searchValue);
+    }
     for (const value of this) {
       if (value === searchValue) {
         return true;
@@ -1887,15 +2044,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;
@@ -3147,6 +3317,111 @@ 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);
+        }
+      }
+    });
+  }
 };
 function asyncIter(source) {
   if (Symbol.asyncIterator in source) {
@@ -3373,12 +3648,12 @@ var DebugState = class {
   /**
    * Enable debug mode with optional configuration
    */
-  enable(config2) {
+  enable(config) {
     this.config = {
       ...this.config,
       enabled: true,
       traceOperations: true,
-      ...config2
+      ...config
     };
     if (this.config.logToConsole) {
       console.log("[iterflow Debug] Debug mode enabled", this.config);
@@ -3498,8 +3773,8 @@ var DebugState = class {
   }
 };
 var debugState = new DebugState();
-function enableDebug(config2) {
-  debugState.enable(config2);
+function enableDebug(config) {
+  debugState.enable(config);
 }
 function disableDebug() {
   debugState.disable();
@@ -3732,85 +4007,6 @@ function errorBoundary(fn, options = {}) {
   };
 }
 
-// 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);
@@ -3969,6 +4165,6 @@ function iter(source) {
   iter2.chain = chain;
 })(iter || (iter = {}));
 
-export { Asynciterflow, EmptySequenceError, IndexOutOfBoundsError, OperationError, TypeConversionError, ValidationError, addTrace, asyncIter, clearDeprecationWarnings, clearTraces, configureDeprecation, deprecate, deprecated, deprecatedFunction, disableDebug, enableDebug, errorBoundary, getDebugConfig, getDeprecationConfig, getTraceSummary, getTraces, getTracesForOperation, hasDeprecationWarning, isDebugEnabled, iter, iterflow, iterflowError, safeComparator, safePredicate, toInteger, toNumber, toResult, toResultAsync, traceOperation, traceOperationAsync, tryCatch, tryCatchAsync, tryOr, validateComparator, validateFiniteNumber, validateFunction, validateIndex, validateIterable, validateNonEmpty, validateNonNegativeInteger, validateNonZero, validatePositiveInteger, validateRange, withDefault, withErrorRecovery, withRetry, withRetryAsync };
+export { AbortError, Asynciterflow, EmptySequenceError, IndexOutOfBoundsError, OperationError, TimeoutError, 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 };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map