iterflow 0.9.0 → 0.12.0

package/dist/index.js

@@ -13,6 +13,26 @@ var iterflowError = class extends Error {
   }
   /**
    * Returns a detailed error message with context
+   *
+   * Formats the error as a multi-line string including operation name, context data,
+   * and stack trace for comprehensive debugging information.
+   *
+   * @returns A formatted string containing all error details
+   * @example
+   * ```typescript
+   * const error = new iterflowError(
+   *   "Processing failed",
+   *   "transform",
+   *   { index: 42, value: null }
+   * );
+   * console.log(error.toDetailedString());
+   * // iterflowError: Processing failed
+   * //   Operation: transform
+   * //   Context:
+   * //     index: 42
+   * //     value: null
+   * //   Stack: ...
+   * ```
    */
   toDetailedString() {
     let msg = `${this.name}: ${this.message}`;
@@ -47,6 +67,28 @@ var OperationError = class extends iterflowError {
     this.name = "OperationError";
     this.cause = cause;
   }
+  /**
+   * Returns a detailed error message including the original cause
+   *
+   * Extends the base toDetailedString() to include information about the
+   * underlying error that caused this operation to fail.
+   *
+   * @returns A formatted string with operation details and cause information
+   * @example
+   * ```typescript
+   * const originalError = new Error("Network timeout");
+   * const opError = new OperationError(
+   *   "Failed to fetch data",
+   *   "fetchAsync",
+   *   originalError
+   * );
+   * console.log(opError.toDetailedString());
+   * // OperationError: Failed to fetch data
+   * //   Operation: fetchAsync
+   * //   Caused by: Network timeout
+   * //   [stack traces...]
+   * ```
+   */
   toDetailedString() {
     let msg = super.toDetailedString();
     if (this.cause) {
@@ -806,13 +848,28 @@ var iterflow = class _iterflow {
    * This method is only available when T is number.
    * This is a terminal operation that consumes the iterator.
    *
+   * WARNING - Memory Intensive: This operation eagerly materializes the entire iterator into memory
+   * for sorting. For large datasets, consider using streaming alternatives or limiting data size.
+   *
    * @param this - iterflow instance constrained to numbers
    * @returns The median value, or undefined if the iterator is empty
    * @example
    * ```typescript
+   * // SAFE: Small dataset
    * iter([1, 2, 3, 4, 5]).median(); // 3
    * iter([1, 2, 3, 4]).median(); // 2.5
-   * iter([]).median(); // undefined
+   *
+   * // SAFE: Limit data before median
+   * iter(largeDataset).take(1000).median();
+   *
+   * // UNSAFE: Large dataset may cause memory issues
+   * iter(millionRecords).median(); // Materializes all records!
+   *
+   * // SAFE: Process in chunks
+   * iter(largeDataset)
+   *   .chunk(1000)
+   *   .map(chunk => iter(chunk).median())
+   *   .toArray();
    * ```
    */
   median() {
@@ -832,12 +889,28 @@ var iterflow = class _iterflow {
    * This method is only available when T is number.
    * This is a terminal operation that consumes the iterator.
    *
+   * WARNING - Memory Intensive: This operation eagerly materializes the entire iterator into memory
+   * to calculate variance. For large datasets, consider using streaming variance algorithms
+   * or limiting data size.
+   *
    * @param this - iterflow instance constrained to numbers
    * @returns The variance, or undefined if the iterator is empty
    * @example
    * ```typescript
+   * // SAFE: Small dataset
    * iter([1, 2, 3, 4, 5]).variance(); // 2
-   * iter([]).variance(); // undefined
+   *
+   * // SAFE: Limit data before variance
+   * iter(largeDataset).take(10000).variance();
+   *
+   * // UNSAFE: Large dataset may cause memory issues
+   * iter(millionRecords).variance(); // Materializes all records!
+   *
+   * // SAFE: Process in windows
+   * iter(largeDataset)
+   *   .window(1000)
+   *   .map(window => iter(window).variance())
+   *   .toArray();
    * ```
    */
   variance() {
@@ -858,12 +931,28 @@ var iterflow = class _iterflow {
    * This method is only available when T is number.
    * This is a terminal operation that consumes the iterator.
    *
+   * WARNING - Memory Intensive: This operation eagerly materializes the entire iterator into memory
+   * via variance calculation. For large datasets, consider using streaming algorithms
+   * or limiting data size.
+   *
    * @param this - iterflow instance constrained to numbers
    * @returns The standard deviation, or undefined if the iterator is empty
    * @example
    * ```typescript
+   * // SAFE: Small dataset
    * iter([2, 4, 4, 4, 5, 5, 7, 9]).stdDev(); // ~2
-   * iter([]).stdDev(); // undefined
+   *
+   * // SAFE: Limit data before stdDev
+   * iter(largeDataset).take(10000).stdDev();
+   *
+   * // UNSAFE: Large dataset may cause memory issues
+   * iter(millionRecords).stdDev(); // Materializes all records!
+   *
+   * // SAFE: Process in chunks
+   * iter(largeDataset)
+   *   .chunk(1000)
+   *   .map(chunk => iter(chunk).stdDev())
+   *   .toArray();
    * ```
    */
   stdDev() {
@@ -876,15 +965,30 @@ var iterflow = class _iterflow {
    * This method is only available when T is number.
    * This is a terminal operation that consumes the iterator.
    *
+   * WARNING - Memory Intensive: This operation eagerly materializes the entire iterator into memory
+   * for sorting. For large datasets, consider using approximate percentile algorithms
+   * or limiting data size.
+   *
    * @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
+   * // SAFE: Small dataset
    * iter([1, 2, 3, 4, 5]).percentile(50); // 3 (median)
    * iter([1, 2, 3, 4, 5]).percentile(75); // 4
-   * iter([]).percentile(50); // undefined
+   *
+   * // SAFE: Limit data before percentile
+   * iter(largeDataset).take(10000).percentile(95);
+   *
+   * // UNSAFE: Large dataset may cause memory issues
+   * iter(millionRecords).percentile(99); // Materializes all records!
+   *
+   * // SAFE: Sample for approximate percentile
+   * iter(largeDataset)
+   *   .filter(() => Math.random() < 0.01) // 1% sample
+   *   .percentile(95);
    * ```
    */
   percentile(p) {
@@ -909,13 +1013,28 @@ var iterflow = class _iterflow {
    * This method is only available when T is number.
    * This is a terminal operation that consumes the iterator.
    *
+   * WARNING - Memory Intensive: This operation eagerly materializes the entire iterator into memory
+   * to count frequencies. For large datasets with many unique values, memory usage can be significant.
+   *
    * @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
+   * // SAFE: Small dataset
    * iter([1, 2, 2, 3, 3, 3]).mode(); // [3]
    * iter([1, 1, 2, 2, 3]).mode(); // [1, 2] (bimodal)
-   * iter([]).mode(); // undefined
+   *
+   * // SAFE: Limit data before mode
+   * iter(largeDataset).take(10000).mode();
+   *
+   * // UNSAFE: Large dataset may cause memory issues
+   * iter(millionRecords).mode(); // Materializes all records!
+   *
+   * // SAFE: Process in chunks
+   * iter(largeDataset)
+   *   .chunk(1000)
+   *   .map(chunk => iter(chunk).mode())
+   *   .toArray();
    * ```
    */
   mode() {
@@ -942,13 +1061,28 @@ var iterflow = class _iterflow {
    * This method is only available when T is number.
    * This is a terminal operation that consumes the iterator.
    *
+   * WARNING - Memory Intensive: This operation eagerly materializes the entire iterator into memory
+   * for sorting and percentile calculation. For large datasets, consider using streaming
+   * quantile algorithms or limiting data size.
+   *
    * @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
+   * // SAFE: Small dataset
    * iter([1, 2, 3, 4, 5, 6, 7, 8, 9]).quartiles();
    * // { Q1: 3, Q2: 5, Q3: 7 }
-   * iter([]).quartiles(); // undefined
+   *
+   * // SAFE: Limit data before quartiles
+   * iter(largeDataset).take(10000).quartiles();
+   *
+   * // UNSAFE: Large dataset may cause memory issues
+   * iter(millionRecords).quartiles(); // Materializes all records!
+   *
+   * // SAFE: Sample for approximate quartiles
+   * iter(largeDataset)
+   *   .filter(() => Math.random() < 0.01) // 1% sample
+   *   .quartiles();
    * ```
    */
   quartiles() {
@@ -1027,13 +1161,34 @@ var iterflow = class _iterflow {
    * This method is only available when T is number.
    * This is a terminal operation that consumes the iterator.
    *
+   * WARNING - Memory Intensive: This operation eagerly materializes both iterators into memory
+   * to calculate covariance. For large datasets, this doubles memory usage.
+   *
    * @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
+   * // SAFE: Small datasets
    * iter([1, 2, 3, 4, 5]).covariance([2, 4, 6, 8, 10]); // 4
-   * iter([]).covariance([1, 2, 3]); // undefined
+   *
+   * // SAFE: Limit both sequences
+   * iter(largeDataset1).take(10000).covariance(
+   *   iter(largeDataset2).take(10000).toArray()
+   * );
+   *
+   * // UNSAFE: Large datasets may cause memory issues
+   * iter(millionRecords1).covariance(millionRecords2); // Materializes both!
+   *
+   * // SAFE: Process in windows
+   * iter(largeDataset1)
+   *   .window(1000)
+   *   .map((window, i) =>
+   *     iter(window).covariance(
+   *       iter(largeDataset2).drop(i * 1000).take(1000).toArray()
+   *     )
+   *   )
+   *   .toArray();
    * ```
    */
   covariance(other) {
@@ -1057,14 +1212,32 @@ var iterflow = class _iterflow {
    * This method is only available when T is number.
    * This is a terminal operation that consumes the iterator.
    *
+   * WARNING - Memory Intensive: This operation eagerly materializes both iterators into memory
+   * to calculate correlation. For large datasets, this doubles memory usage.
+   *
    * @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
+   * // SAFE: Small datasets
+   * iter([1, 2, 3, 4, 5]).correlation([2, 4, 6, 8, 10]); // 1 (perfect positive)
+   * iter([1, 2, 3]).correlation([3, 2, 1]); // -1 (perfect negative)
+   *
+   * // SAFE: Limit both sequences
+   * iter(largeDataset1).take(10000).correlation(
+   *   iter(largeDataset2).take(10000).toArray()
+   * );
+   *
+   * // UNSAFE: Large datasets may cause memory issues
+   * iter(millionRecords1).correlation(millionRecords2); // Materializes both!
+   *
+   * // SAFE: Sample for approximate correlation
+   * iter(largeDataset1)
+   *   .filter(() => Math.random() < 0.01)
+   *   .correlation(
+   *     iter(largeDataset2).filter(() => Math.random() < 0.01).toArray()
+   *   );
    * ```
    */
   correlation(other) {
@@ -2229,11 +2402,27 @@ var Asynciterflow = class _Asynciterflow {
    * Calculates the median value of all numeric elements.
    * This is a terminal operation that consumes the async iterator.
    *
+   * WARNING - Memory Intensive: This operation eagerly materializes the entire async iterator into memory
+   * for sorting. For large datasets, consider using streaming alternatives or limiting data size.
+   *
    * @param this - async iterflow instance constrained to numbers
    * @returns A promise of the median value, or undefined if empty
    * @example
    * ```typescript
+   * // SAFE: Small dataset
    * await asyncIter([1, 2, 3, 4, 5]).median(); // 3
+   *
+   * // SAFE: Limit data before median
+   * await asyncIter(largeAsyncDataset).take(1000).median();
+   *
+   * // UNSAFE: Large dataset may cause memory issues
+   * await asyncIter(millionRecords).median(); // Materializes all records!
+   *
+   * // SAFE: Process in chunks
+   * await asyncIter(largeAsyncDataset)
+   *   .chunk(1000)
+   *   .map(async chunk => await asyncIter(chunk).median())
+   *   .toArray();
    * ```
    */
   async median() {
@@ -2251,11 +2440,28 @@ var Asynciterflow = class _Asynciterflow {
    * Calculates the variance of all numeric elements.
    * This is a terminal operation that consumes the async iterator.
    *
+   * WARNING - Memory Intensive: This operation eagerly materializes the entire async iterator into memory
+   * to calculate variance. For large datasets, consider using streaming variance algorithms
+   * or limiting data size.
+   *
    * @param this - async iterflow instance constrained to numbers
    * @returns A promise of the variance, or undefined if empty
    * @example
    * ```typescript
+   * // SAFE: Small dataset
    * await asyncIter([1, 2, 3, 4, 5]).variance(); // 2
+   *
+   * // SAFE: Limit data before variance
+   * await asyncIter(largeAsyncDataset).take(10000).variance();
+   *
+   * // UNSAFE: Large dataset may cause memory issues
+   * await asyncIter(millionRecords).variance(); // Materializes all records!
+   *
+   * // SAFE: Process in windows
+   * await asyncIter(largeAsyncDataset)
+   *   .window(1000)
+   *   .map(async window => await asyncIter(window).variance())
+   *   .toArray();
    * ```
    */
   async variance() {
@@ -2273,11 +2479,28 @@ var Asynciterflow = class _Asynciterflow {
    * Calculates the standard deviation of all numeric elements.
    * This is a terminal operation that consumes the async iterator.
    *
+   * WARNING - Memory Intensive: This operation eagerly materializes the entire async iterator into memory
+   * via variance calculation. For large datasets, consider using streaming algorithms
+   * or limiting data size.
+   *
    * @param this - async iterflow instance constrained to numbers
    * @returns A promise of the standard deviation, or undefined if empty
    * @example
    * ```typescript
+   * // SAFE: Small dataset
    * await asyncIter([2, 4, 4, 4, 5, 5, 7, 9]).stdDev(); // ~2
+   *
+   * // SAFE: Limit data before stdDev
+   * await asyncIter(largeAsyncDataset).take(10000).stdDev();
+   *
+   * // UNSAFE: Large dataset may cause memory issues
+   * await asyncIter(millionRecords).stdDev(); // Materializes all records!
+   *
+   * // SAFE: Process in chunks
+   * await asyncIter(largeAsyncDataset)
+   *   .chunk(1000)
+   *   .map(async chunk => await asyncIter(chunk).stdDev())
+   *   .toArray();
    * ```
    */
   async stdDev() {
@@ -2288,13 +2511,29 @@ var Asynciterflow = class _Asynciterflow {
    * Calculates the specified percentile of all numeric elements.
    * This is a terminal operation that consumes the async iterator.
    *
+   * WARNING - Memory Intensive: This operation eagerly materializes the entire async iterator into memory
+   * for sorting. For large datasets, consider using approximate percentile algorithms
+   * or limiting data size.
+   *
    * @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
+   * // SAFE: Small dataset
    * await asyncIter([1, 2, 3, 4, 5]).percentile(50); // 3
+   *
+   * // SAFE: Limit data before percentile
+   * await asyncIter(largeAsyncDataset).take(10000).percentile(95);
+   *
+   * // UNSAFE: Large dataset may cause memory issues
+   * await asyncIter(millionRecords).percentile(99); // Materializes all records!
+   *
+   * // SAFE: Sample for approximate percentile
+   * await asyncIter(largeAsyncDataset)
+   *   .filter(async () => Math.random() < 0.01) // 1% sample
+   *   .percentile(95);
    * ```
    */
   async percentile(p) {
@@ -2317,11 +2556,27 @@ var Asynciterflow = class _Asynciterflow {
    * Finds the most frequent value(s) in the dataset.
    * This is a terminal operation that consumes the async iterator.
    *
+   * WARNING - Memory Intensive: This operation eagerly materializes the entire async iterator into memory
+   * to count frequencies. For large datasets with many unique values, memory usage can be significant.
+   *
    * @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
+   * // SAFE: Small dataset
    * await asyncIter([1, 2, 2, 3, 3, 3]).mode(); // [3]
+   *
+   * // SAFE: Limit data before mode
+   * await asyncIter(largeAsyncDataset).take(10000).mode();
+   *
+   * // UNSAFE: Large dataset may cause memory issues
+   * await asyncIter(millionRecords).mode(); // Materializes all records!
+   *
+   * // SAFE: Process in chunks
+   * await asyncIter(largeAsyncDataset)
+   *   .chunk(1000)
+   *   .map(async chunk => await asyncIter(chunk).mode())
+   *   .toArray();
    * ```
    */
   async mode() {
@@ -2346,12 +2601,28 @@ var Asynciterflow = class _Asynciterflow {
    * Calculates the quartiles (Q1, Q2, Q3) of all numeric elements.
    * This is a terminal operation that consumes the async iterator.
    *
+   * WARNING - Memory Intensive: This operation eagerly materializes the entire async iterator into memory
+   * for sorting and percentile calculation. For large datasets, consider using streaming
+   * quantile algorithms or limiting data size.
+   *
    * @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
+   * // SAFE: Small dataset
    * await asyncIter([1, 2, 3, 4, 5, 6, 7, 8, 9]).quartiles();
    * // { Q1: 3, Q2: 5, Q3: 7 }
+   *
+   * // SAFE: Limit data before quartiles
+   * await asyncIter(largeAsyncDataset).take(10000).quartiles();
+   *
+   * // UNSAFE: Large dataset may cause memory issues
+   * await asyncIter(millionRecords).quartiles(); // Materializes all records!
+   *
+   * // SAFE: Sample for approximate quartiles
+   * await asyncIter(largeAsyncDataset)
+   *   .filter(async () => Math.random() < 0.01) // 1% sample
+   *   .quartiles();
    * ```
    */
   async quartiles() {
@@ -2422,12 +2693,34 @@ var Asynciterflow = class _Asynciterflow {
    * Calculates the covariance between two numeric sequences.
    * This is a terminal operation that consumes the async iterator.
    *
+   * WARNING - Memory Intensive: This operation eagerly materializes both async iterators into memory
+   * to calculate covariance. For large datasets, this doubles memory usage.
+   *
    * @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
+   * // SAFE: Small datasets
    * await asyncIter([1, 2, 3, 4, 5]).covariance([2, 4, 6, 8, 10]); // 4
+   *
+   * // SAFE: Limit both sequences
+   * await asyncIter(largeAsyncDataset1).take(10000).covariance(
+   *   await asyncIter(largeAsyncDataset2).take(10000).toArray()
+   * );
+   *
+   * // UNSAFE: Large datasets may cause memory issues
+   * await asyncIter(millionRecords1).covariance(millionRecords2); // Materializes both!
+   *
+   * // SAFE: Process in windows
+   * await asyncIter(largeAsyncDataset1)
+   *   .window(1000)
+   *   .map(async (window, i) =>
+   *     await asyncIter(window).covariance(
+   *       await asyncIter(largeAsyncDataset2).drop(i * 1000).take(1000).toArray()
+   *     )
+   *   )
+   *   .toArray();
    * ```
    */
   async covariance(other) {
@@ -2457,12 +2750,33 @@ var Asynciterflow = class _Asynciterflow {
    * Calculates the Pearson correlation coefficient between two numeric sequences.
    * This is a terminal operation that consumes the async iterator.
    *
+   * WARNING - Memory Intensive: This operation eagerly materializes both async iterators into memory
+   * to calculate correlation. For large datasets, this doubles memory usage.
+   *
    * @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
+   * // SAFE: Small datasets
    * await asyncIter([1, 2, 3, 4, 5]).correlation([2, 4, 6, 8, 10]); // 1
+   *
+   * // SAFE: Limit both sequences
+   * await asyncIter(largeAsyncDataset1).take(10000).correlation(
+   *   await asyncIter(largeAsyncDataset2).take(10000).toArray()
+   * );
+   *
+   * // UNSAFE: Large datasets may cause memory issues
+   * await asyncIter(millionRecords1).correlation(millionRecords2); // Materializes both!
+   *
+   * // SAFE: Sample for approximate correlation
+   * await asyncIter(largeAsyncDataset1)
+   *   .filter(async () => Math.random() < 0.01)
+   *   .correlation(
+   *     await asyncIter(largeAsyncDataset2)
+   *       .filter(async () => Math.random() < 0.01)
+   *       .toArray()
+   *   );
    * ```
    */
   async correlation(other) {