iterflow 0.9.0 → 0.12.0

package/dist/index.d.ts

@@ -313,13 +313,28 @@ declare class iterflow<T> implements Iterable<T> {
      * 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(this: iterflow<number>): number | undefined;
@@ -329,12 +344,28 @@ declare class iterflow<T> implements Iterable<T> {
      * 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(this: iterflow<number>): number | undefined;
@@ -344,12 +375,28 @@ declare class iterflow<T> implements Iterable<T> {
      * 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(this: iterflow<number>): number | undefined;
@@ -359,15 +406,30 @@ declare class iterflow<T> implements Iterable<T> {
      * 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(this: iterflow<number>, p: number): number | undefined;
@@ -377,13 +439,28 @@ declare class iterflow<T> implements Iterable<T> {
      * 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(this: iterflow<number>): number[] | undefined;
@@ -393,13 +470,28 @@ declare class iterflow<T> implements Iterable<T> {
      * 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(this: iterflow<number>): {
@@ -443,13 +535,34 @@ declare class iterflow<T> implements Iterable<T> {
      * 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(this: iterflow<number>, other: Iterable<number>): number | undefined;
@@ -460,14 +573,32 @@ declare class iterflow<T> implements Iterable<T> {
      * 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(this: iterflow<number>, other: Iterable<number>): number | undefined;
@@ -1091,11 +1222,27 @@ declare class Asynciterflow<T> implements AsyncIterable<T> {
      * 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();
      * ```
      */
     median(this: Asynciterflow<number>): Promise<number | undefined>;
@@ -1103,11 +1250,28 @@ declare class Asynciterflow<T> implements AsyncIterable<T> {
      * 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();
      * ```
      */
     variance(this: Asynciterflow<number>): Promise<number | undefined>;
@@ -1115,11 +1279,28 @@ declare class Asynciterflow<T> implements AsyncIterable<T> {
      * 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();
      * ```
      */
     stdDev(this: Asynciterflow<number>): Promise<number | undefined>;
@@ -1127,13 +1308,29 @@ declare class Asynciterflow<T> implements AsyncIterable<T> {
      * 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);
      * ```
      */
     percentile(this: Asynciterflow<number>, p: number): Promise<number | undefined>;
@@ -1141,11 +1338,27 @@ declare class Asynciterflow<T> implements AsyncIterable<T> {
      * 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();
      * ```
      */
     mode(this: Asynciterflow<number>): Promise<number[] | undefined>;
@@ -1153,12 +1366,28 @@ declare class Asynciterflow<T> implements AsyncIterable<T> {
      * 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();
      * ```
      */
     quartiles(this: Asynciterflow<number>): Promise<{
@@ -1194,12 +1423,34 @@ declare class Asynciterflow<T> implements AsyncIterable<T> {
      * 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();
      * ```
      */
     covariance(this: Asynciterflow<number>, other: AsyncIterable<number> | Iterable<number>): Promise<number | undefined>;
@@ -1207,12 +1458,33 @@ declare class Asynciterflow<T> implements AsyncIterable<T> {
      * 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()
+     *   );
      * ```
      */
     correlation(this: Asynciterflow<number>, other: AsyncIterable<number> | Iterable<number>): Promise<number | undefined>;
@@ -1848,6 +2120,18 @@ declare namespace asyncIter {
  */
 /**
  * Base error class for all iterflow errors
+ *
+ * Provides a foundation for all library-specific errors with additional context
+ * including the operation name and custom metadata for debugging.
+ *
+ * @example
+ * ```typescript
+ * throw new iterflowError(
+ *   "Invalid configuration",
+ *   "setupStream",
+ *   { config: { timeout: -1 } }
+ * );
+ * ```
  */
 declare class iterflowError extends Error {
     readonly operation?: string;
@@ -1855,31 +2139,135 @@ declare class iterflowError extends Error {
     constructor(message: string, operation?: string, context?: Record<string, unknown>);
     /**
      * 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(): string;
 }
 /**
  * Error thrown when operation parameters are invalid
+ *
+ * Indicates that input validation failed due to incorrect parameter types,
+ * out-of-range values, or other constraint violations.
+ *
+ * @example
+ * ```typescript
+ * // Thrown when validating a negative value that must be positive
+ * throw new ValidationError(
+ *   "count must be positive, got -5",
+ *   "take",
+ *   { paramName: "count", value: -5 }
+ * );
+ * ```
  */
 declare class ValidationError extends iterflowError {
     constructor(message: string, operation?: string, context?: Record<string, unknown>);
 }
 /**
  * Error thrown when an operation fails during execution
+ *
+ * Wraps underlying errors that occur during stream processing or transformations,
+ * preserving the original error as the cause while adding operation context.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await processItem(item);
+ * } catch (error) {
+ *   throw new OperationError(
+ *     "Failed to process item",
+ *     "map",
+ *     error as Error,
+ *     { item, index: 5 }
+ *   );
+ * }
+ * ```
  */
 declare class OperationError extends iterflowError {
     readonly cause?: Error;
     constructor(message: string, operation?: string, cause?: Error, context?: Record<string, unknown>);
+    /**
+     * 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(): string;
 }
 /**
  * Error thrown when an operation requires a non-empty sequence
+ *
+ * Indicates that an operation like first(), last(), or min() was called on an
+ * empty iterable where at least one element is required to produce a result.
+ *
+ * @example
+ * ```typescript
+ * import { from } from 'iterflow';
+ *
+ * const empty = from([]);
+ * try {
+ *   empty.first(); // Throws EmptySequenceError
+ * } catch (error) {
+ *   console.error(error.message);
+ *   // "Operation 'first' requires a non-empty sequence"
+ * }
+ * ```
  */
 declare class EmptySequenceError extends iterflowError {
     constructor(operation: string, message?: string);
 }
 /**
  * Error thrown when accessing an invalid index
+ *
+ * Indicates that an index-based operation attempted to access an element
+ * outside the valid range of the collection (negative index or index >= size).
+ *
+ * @example
+ * ```typescript
+ * import { from } from 'iterflow';
+ *
+ * const items = from([1, 2, 3]);
+ * try {
+ *   items.elementAt(10); // Only 3 elements, index 10 is out of bounds
+ * } catch (error) {
+ *   console.error(error.message);
+ *   // "Index 10 is out of bounds (size: 3)"
+ * }
+ * ```
  */
 declare class IndexOutOfBoundsError extends iterflowError {
     readonly index: number;
@@ -1888,6 +2276,21 @@ declare class IndexOutOfBoundsError extends iterflowError {
 }
 /**
  * Error thrown when a type conversion or coercion fails
+ *
+ * Indicates that an attempt to convert a value to a specific type failed,
+ * such as converting a non-numeric string to a number or a decimal to an integer.
+ *
+ * @example
+ * ```typescript
+ * import { toNumber } from 'iterflow';
+ *
+ * try {
+ *   const num = toNumber("not-a-number");
+ * } catch (error) {
+ *   console.error(error.message);
+ *   // 'Cannot convert value "not-a-number" to type number'
+ * }
+ * ```
  */
 declare class TypeConversionError extends iterflowError {
     readonly value: unknown;
@@ -1896,6 +2299,28 @@ declare class TypeConversionError extends iterflowError {
 }
 /**
  * Error thrown when an operation exceeds its timeout duration
+ *
+ * Indicates that an async operation took longer than the specified timeout
+ * and was terminated to prevent indefinite waiting.
+ *
+ * @example
+ * ```typescript
+ * import { fromAsync } from 'iterflow';
+ *
+ * async function* slowGenerator() {
+ *   yield await new Promise(resolve => setTimeout(() => resolve(1), 5000));
+ * }
+ *
+ * try {
+ *   // Timeout after 1 second
+ *   await fromAsync(slowGenerator())
+ *     .withTimeout(1000)
+ *     .toArray();
+ * } catch (error) {
+ *   console.error(error.message);
+ *   // "Operation timed out after 1000ms"
+ * }
+ * ```
  */
 declare class TimeoutError extends iterflowError {
     readonly timeoutMs: number;
@@ -1903,6 +2328,27 @@ declare class TimeoutError extends iterflowError {
 }
 /**
  * Error thrown when an operation is aborted via AbortSignal
+ *
+ * Indicates that an async operation was cancelled using an AbortController,
+ * typically for user-initiated cancellation or cleanup during component unmounting.
+ *
+ * @example
+ * ```typescript
+ * import { fromAsync } from 'iterflow';
+ *
+ * const controller = new AbortController();
+ *
+ * setTimeout(() => controller.abort("User cancelled"), 1000);
+ *
+ * try {
+ *   await fromAsync(longRunningGenerator())
+ *     .withAbortSignal(controller.signal)
+ *     .toArray();
+ * } catch (error) {
+ *   console.error(error.message);
+ *   // "Operation aborted: User cancelled"
+ * }
+ * ```
  */
 declare class AbortError extends iterflowError {
     readonly reason?: string;
@@ -1918,47 +2364,246 @@ declare class AbortError extends iterflowError {
  */
 declare function validatePositiveInteger(value: number, paramName: string, operation?: string): void;
 /**
- * Validates that a value is a non-negative integer
+ * Validates that a value is a non-negative integer (zero or greater)
+ *
+ * This function ensures the value is both an integer and non-negative, making it
+ * suitable for array indices, counts, and offsets that can start from zero.
+ *
+ * @param value - The value to validate
+ * @param paramName - The parameter name for error messages
+ * @param operation - The operation name for error context
+ * @throws {ValidationError} When value is not an integer
+ * @throws {ValidationError} When value is negative
+ * @example
+ * ```typescript
+ * validateNonNegativeInteger(0, "index");      // OK - zero is allowed
+ * validateNonNegativeInteger(5, "offset");     // OK
+ * validateNonNegativeInteger(-1, "index");     // throws ValidationError
+ * validateNonNegativeInteger(1.5, "count");    // throws ValidationError
+ * ```
  */
 declare function validateNonNegativeInteger(value: number, paramName: string, operation?: string): void;
 /**
- * Validates that a value is within a specific range
+ * Validates that a value is within a specific range (inclusive)
+ *
+ * Checks that a numeric value falls within the specified bounds, including
+ * both minimum and maximum values. Useful for percentages, bounded parameters,
+ * and range-constrained inputs.
+ *
+ * @param value - The value to validate
+ * @param min - The minimum allowed value (inclusive)
+ * @param max - The maximum allowed value (inclusive)
+ * @param paramName - The parameter name for error messages
+ * @param operation - The operation name for error context
+ * @throws {ValidationError} When value is less than min or greater than max
+ * @example
+ * ```typescript
+ * validateRange(50, 0, 100, "percent");     // OK
+ * validateRange(0, 0, 100, "percent");      // OK - min boundary
+ * validateRange(100, 0, 100, "percent");    // OK - max boundary
+ * validateRange(150, 0, 100, "percent");    // throws ValidationError
+ * validateRange(-10, 0, 100, "percent");    // throws ValidationError
+ * ```
  */
 declare function validateRange(value: number, min: number, max: number, paramName: string, operation?: string): void;
 /**
  * Validates that a value is a finite number (not NaN or Infinity)
+ *
+ * Ensures the value is a real, finite number that can be used in mathematical
+ * operations. Rejects NaN, Infinity, and -Infinity which could cause undefined
+ * behavior in calculations.
+ *
+ * @param value - The value to validate
+ * @param paramName - The parameter name for error messages
+ * @param operation - The operation name for error context
+ * @throws {ValidationError} When value is NaN, Infinity, or -Infinity
+ * @example
+ * ```typescript
+ * validateFiniteNumber(42, "weight");           // OK
+ * validateFiniteNumber(-3.14, "temperature");   // OK
+ * validateFiniteNumber(0, "value");             // OK
+ * validateFiniteNumber(NaN, "result");          // throws ValidationError
+ * validateFiniteNumber(Infinity, "max");        // throws ValidationError
+ * ```
  */
 declare function validateFiniteNumber(value: number, paramName: string, operation?: string): void;
 /**
  * Validates that a value is not zero
+ *
+ * Prevents division by zero errors and other operations where zero is invalid.
+ * Detects both positive and negative zero.
+ *
+ * @param value - The value to validate
+ * @param paramName - The parameter name for error messages
+ * @param operation - The operation name for error context
+ * @throws {ValidationError} When value equals zero (including -0)
+ * @example
+ * ```typescript
+ * validateNonZero(1, "divisor");       // OK
+ * validateNonZero(-5, "denominator");  // OK
+ * validateNonZero(0.1, "scale");       // OK
+ * validateNonZero(0, "divisor");       // throws ValidationError
+ * validateNonZero(-0, "divisor");      // throws ValidationError
+ * ```
  */
 declare function validateNonZero(value: number, paramName: string, operation?: string): void;
 /**
  * Validates that a value is a function
+ *
+ * Type guard that ensures the value is callable. Accepts arrow functions, regular
+ * functions, async functions, generator functions, and class constructors.
+ * Uses TypeScript assertion to narrow the type.
+ *
+ * @param value - The value to validate
+ * @param paramName - The parameter name for error messages
+ * @param operation - The operation name for error context
+ * @throws {ValidationError} When value is not a function
+ * @example
+ * ```typescript
+ * validateFunction((x) => x * 2, "mapper");           // OK
+ * validateFunction(Math.max, "comparator");           // OK
+ * async function fetch() {}
+ * validateFunction(fetch, "loader");                  // OK
+ * validateFunction(null, "callback");                 // throws ValidationError
+ * validateFunction("not a function", "fn");           // throws ValidationError
+ * ```
  */
-declare function validateFunction(value: unknown, paramName: string, operation?: string): asserts value is Function;
+declare function validateFunction(value: unknown, paramName: string, operation?: string): asserts value is (...args: unknown[]) => unknown;
 /**
  * Validates that a value is iterable
+ *
+ * Type guard ensuring the value implements the iterable protocol (has Symbol.iterator).
+ * Accepts arrays, strings, Maps, Sets, generators, and custom iterables.
+ * Uses TypeScript assertion to narrow the type.
+ *
+ * @param value - The value to validate
+ * @param paramName - The parameter name for error messages
+ * @param operation - The operation name for error context
+ * @throws {ValidationError} When value is null, undefined, or lacks Symbol.iterator
+ * @example
+ * ```typescript
+ * validateIterable([1, 2, 3], "items");                // OK
+ * validateIterable("hello", "text");                   // OK
+ * validateIterable(new Set([1, 2]), "uniqueIds");      // OK
+ * function* gen() { yield 1; }
+ * validateIterable(gen(), "sequence");                 // OK
+ * validateIterable(null, "items");                     // throws ValidationError
+ * validateIterable({ a: 1 }, "obj");                   // throws ValidationError
+ * ```
  */
 declare function validateIterable<T>(value: unknown, paramName: string, operation?: string): asserts value is Iterable<T>;
 /**
  * Validates that a value is a valid comparator function
+ *
+ * Type guard ensuring the value is a function suitable for sorting and comparison
+ * operations. A comparator should return a negative number if a < b, zero if a === b,
+ * and a positive number if a > b. Uses TypeScript assertion to narrow the type.
+ *
+ * @param fn - The value to validate as a comparator
+ * @param operation - The operation name for error context
+ * @throws {ValidationError} When fn is not a function
+ * @example
+ * ```typescript
+ * const numCompare = (a: number, b: number) => a - b;
+ * validateComparator(numCompare);                      // OK
+ *
+ * const strCompare = (a: string, b: string) => a.localeCompare(b);
+ * validateComparator(strCompare, "sortBy");            // OK
+ *
+ * validateComparator(null, "sort");                    // throws ValidationError
+ * validateComparator("not a function", "sort");        // throws ValidationError
+ * ```
  */
 declare function validateComparator<T>(fn: unknown, operation?: string): asserts fn is (a: T, b: T) => number;
 /**
  * Validates that an array is not empty
+ *
+ * Ensures an array has at least one element. Useful for operations that require
+ * at least one item to function properly (e.g., finding min/max, first/last).
+ *
+ * @param arr - The array to validate
+ * @param operation - The operation name for error context
+ * @throws {ValidationError} When the array is empty (length === 0)
+ * @example
+ * ```typescript
+ * validateNonEmpty([1, 2, 3]);         // OK
+ * validateNonEmpty(["a"]);             // OK
+ * validateNonEmpty([]);                // throws ValidationError
+ *
+ * // Usage in operations requiring elements
+ * function findMax(arr: number[]): number {
+ *   validateNonEmpty(arr, "findMax");
+ *   return Math.max(...arr);
+ * }
+ * ```
  */
 declare function validateNonEmpty<T>(arr: T[], operation?: string): void;
 /**
  * Safely converts a value to a number
+ *
+ * Attempts to convert any value to a number using JavaScript's Number() constructor.
+ * Throws a specific error if the conversion results in NaN, providing clear feedback
+ * about type conversion failures.
+ *
+ * @param value - The value to convert to a number
+ * @param operation - The operation name for error context
+ * @returns The numeric representation of the value
+ * @throws {TypeConversionError} When conversion results in NaN
+ * @example
+ * ```typescript
+ * toNumber("123");              // returns 123
+ * toNumber("45.6");             // returns 45.6
+ * toNumber(100);                // returns 100
+ * toNumber(true);               // returns 1
+ * toNumber("not a number");     // throws TypeConversionError
+ * toNumber(undefined);          // throws TypeConversionError
+ * ```
  */
 declare function toNumber(value: unknown, operation?: string): number;
 /**
  * Safely converts a value to an integer
+ *
+ * Converts a value to a number and ensures it's an integer (no decimal part).
+ * Uses Math.trunc to identify the integer portion and validates that no precision
+ * is lost during conversion.
+ *
+ * @param value - The value to convert to an integer
+ * @param operation - The operation name for error context
+ * @returns The integer representation of the value
+ * @throws {TypeConversionError} When conversion to number fails (NaN)
+ * @throws {TypeConversionError} When the number has a fractional part
+ * @example
+ * ```typescript
+ * toInteger("123");             // returns 123
+ * toInteger(456);               // returns 456
+ * toInteger("0");               // returns 0
+ * toInteger("-50");             // returns -50
+ * toInteger("123.45");          // throws TypeConversionError
+ * toInteger(789.12);            // throws TypeConversionError
+ * toInteger("abc");             // throws TypeConversionError
+ * ```
  */
 declare function toInteger(value: unknown, operation?: string): number;
 /**
- * Validates array index
+ * Validates an array index is within bounds
+ *
+ * Ensures an index is a non-negative integer and falls within the valid range
+ * for an array or collection of the given size. Valid indices are 0 to size-1.
+ *
+ * @param index - The index to validate
+ * @param size - The size of the array or collection
+ * @param operation - The operation name for error context
+ * @throws {ValidationError} When index is not a non-negative integer
+ * @throws {ValidationError} When index is greater than or equal to size
+ * @example
+ * ```typescript
+ * validateIndex(0, 10);         // OK
+ * validateIndex(5, 10);         // OK
+ * validateIndex(9, 10);         // OK - last valid index
+ * validateIndex(10, 10);        // throws ValidationError - out of bounds
+ * validateIndex(-1, 10);        // throws ValidationError - negative
+ * validateIndex(1.5, 10);       // throws ValidationError - not integer
+ * ```
  */
 declare function validateIndex(index: number, size: number, operation?: string): void;
 
@@ -2007,22 +2652,120 @@ declare function isDebugEnabled(): boolean;
 declare function getDebugConfig(): Readonly<DebugConfig>;
 /**
  * Add a trace entry
+ *
+ * Manually records an operation trace entry for debugging purposes.
+ * Traces are only recorded when debug mode is enabled with traceOperations: true.
+ *
+ * @param entry - The trace entry to add
+ * @example
+ * ```typescript
+ * import { enableDebug, addTrace } from 'iterflow';
+ *
+ * enableDebug({ traceOperations: true });
+ *
+ * addTrace({
+ *   operation: 'customOp',
+ *   timestamp: Date.now(),
+ *   duration: 42.5,
+ *   metadata: { itemsProcessed: 100 }
+ * });
+ * ```
  */
 declare function addTrace(entry: TraceEntry): void;
 /**
  * Get all trace entries
+ *
+ * Retrieves all recorded trace entries for analysis. Each trace entry contains
+ * operation name, timestamp, duration, and optional input/output/error data.
+ *
+ * @returns An immutable array of all trace entries
+ * @example
+ * ```typescript
+ * import { from, enableDebug, getTraces } from 'iterflow';
+ *
+ * enableDebug({ traceOperations: true, traceInput: true, traceOutput: true });
+ *
+ * from([1, 2, 3]).map(x => x * 2).toArray();
+ *
+ * const traces = getTraces();
+ * traces.forEach(trace => {
+ *   console.log(`${trace.operation} took ${trace.duration}ms`);
+ * });
+ * ```
  */
 declare function getTraces(): readonly TraceEntry[];
 /**
  * Clear all traces
+ *
+ * Removes all recorded trace entries from memory. Useful for resetting debug state
+ * between test runs or freeing memory after analyzing traces.
+ *
+ * @example
+ * ```typescript
+ * import { enableDebug, getTraces, clearTraces } from 'iterflow';
+ *
+ * enableDebug({ traceOperations: true });
+ *
+ * // ... run some operations ...
+ *
+ * const traces = getTraces();
+ * analyzePerformance(traces);
+ *
+ * clearTraces(); // Reset for next benchmark
+ * ```
  */
 declare function clearTraces(): void;
 /**
  * Get traces for a specific operation
+ *
+ * Filters trace entries to return only those for the specified operation name.
+ * Useful for analyzing performance of a specific method or transformation.
+ *
+ * @param operation - The operation name to filter by (e.g., "map", "filter")
+ * @returns An array of trace entries for the specified operation
+ * @example
+ * ```typescript
+ * import { from, enableDebug, getTracesForOperation } from 'iterflow';
+ *
+ * enableDebug({ traceOperations: true });
+ *
+ * from([1, 2, 3])
+ *   .map(x => x * 2)
+ *   .filter(x => x > 3)
+ *   .toArray();
+ *
+ * const mapTraces = getTracesForOperation('map');
+ * console.log(`map was called ${mapTraces.length} times`);
+ * ```
  */
 declare function getTracesForOperation(operation: string): TraceEntry[];
 /**
  * Get trace summary statistics
+ *
+ * Computes aggregated statistics for each operation including call count,
+ * average duration, and error count. Useful for identifying performance
+ * bottlenecks and error-prone operations.
+ *
+ * @returns An object mapping operation names to their statistics
+ * @example
+ * ```typescript
+ * import { from, enableDebug, getTraceSummary } from 'iterflow';
+ *
+ * enableDebug({ traceOperations: true });
+ *
+ * from([1, 2, 3, 4, 5])
+ *   .map(x => x * 2)
+ *   .filter(x => x > 5)
+ *   .toArray();
+ *
+ * const summary = getTraceSummary();
+ * Object.entries(summary).forEach(([op, stats]) => {
+ *   console.log(`${op}: ${stats.count} calls, avg ${stats.avgDuration.toFixed(2)}ms`);
+ * });
+ * // Output:
+ * // map: 5 calls, avg 0.02ms
+ * // filter: 5 calls, avg 0.01ms
+ * ```
  */
 declare function getTraceSummary(): Record<string, {
     count: number;
@@ -2031,10 +2774,59 @@ declare function getTraceSummary(): Record<string, {
 }>;
 /**
  * Wrapper function to trace operation execution
+ *
+ * Wraps a synchronous function to automatically record execution timing and errors.
+ * Only records traces when debug mode is enabled.
+ *
+ * @template T - The function's return type
+ * @param operation - The operation name for the trace entry
+ * @param fn - The function to execute and trace
+ * @param metadata - Optional metadata to include in the trace entry
+ * @returns The result of executing fn
+ * @example
+ * ```typescript
+ * import { enableDebug, traceOperation } from 'iterflow';
+ *
+ * enableDebug({ traceOperations: true });
+ *
+ * const result = traceOperation(
+ *   'computeExpensive',
+ *   () => {
+ *     let sum = 0;
+ *     for (let i = 0; i < 1000000; i++) sum += i;
+ *     return sum;
+ *   },
+ *   { iterations: 1000000 }
+ * );
+ * ```
  */
 declare function traceOperation<T>(operation: string, fn: () => T, metadata?: Record<string, unknown>): T;
 /**
  * Async version of traceOperation
+ *
+ * Wraps an async function to automatically record execution timing and errors.
+ * Only records traces when debug mode is enabled.
+ *
+ * @template T - The function's return type
+ * @param operation - The operation name for the trace entry
+ * @param fn - The async function to execute and trace
+ * @param metadata - Optional metadata to include in the trace entry
+ * @returns A promise resolving to the result of executing fn
+ * @example
+ * ```typescript
+ * import { enableDebug, traceOperationAsync } from 'iterflow';
+ *
+ * enableDebug({ traceOperations: true });
+ *
+ * const data = await traceOperationAsync(
+ *   'fetchUserData',
+ *   async () => {
+ *     const response = await fetch('/api/users');
+ *     return response.json();
+ *   },
+ *   { endpoint: '/api/users' }
+ * );
+ * ```
  */
 declare function traceOperationAsync<T>(operation: string, fn: () => Promise<T>, metadata?: Record<string, unknown>): Promise<T>;
 
@@ -2061,26 +2853,168 @@ interface RetryOptions {
 declare function withErrorRecovery<T, R>(fn: (value: T, index?: number) => R, errorHandler: ErrorHandler<T, R>): (value: T, index?: number) => R;
 /**
  * Wraps a function with retry logic
+ *
+ * Automatically retries a function on failure with configurable attempts, delays,
+ * and exponential backoff. Useful for handling transient failures in operations
+ * that may succeed on subsequent attempts.
+ *
+ * @template T - The function's argument types as a tuple
+ * @template R - The function's return type
+ * @param fn - The function to wrap with retry logic
+ * @param options - Configuration object with maxAttempts (default: 3), delay in ms (default: 0), backoff flag (default: false), and optional onRetry callback
+ * @returns A wrapped function that retries on failure
+ * @throws {OperationError} When all retry attempts are exhausted
+ * @example
+ * ```typescript
+ * const fetchWithRetry = withRetry(
+ *   () => fetch('/api/data').then(r => r.json()),
+ *   {
+ *     maxAttempts: 3,
+ *     delay: 1000,
+ *     backoff: true,
+ *     onRetry: (attempt, error) => console.log(`Retry ${attempt}: ${error.message}`)
+ *   }
+ * );
+ *
+ * const data = fetchWithRetry();
+ * ```
  */
 declare function withRetry<T extends any[], R>(fn: (...args: T) => R, options?: RetryOptions): (...args: T) => R;
 /**
  * Async version of withRetry
+ *
+ * Wraps an async function with retry logic, using proper async delays instead of
+ * busy-waiting. Ideal for network requests, database operations, or other async
+ * operations that may fail transiently.
+ *
+ * @template T - The function's argument types as a tuple
+ * @template R - The function's return type
+ * @param fn - The async function to wrap with retry logic
+ * @param options - Configuration object with maxAttempts (default: 3), delay in ms (default: 0), backoff flag (default: false), and optional onRetry callback
+ * @returns A wrapped async function that retries on failure
+ * @throws {OperationError} When all retry attempts are exhausted
+ * @example
+ * ```typescript
+ * const fetchDataWithRetry = withRetryAsync(
+ *   async (id: string) => {
+ *     const response = await fetch(`/api/items/${id}`);
+ *     return response.json();
+ *   },
+ *   {
+ *     maxAttempts: 5,
+ *     delay: 500,
+ *     backoff: true
+ *   }
+ * );
+ *
+ * const item = await fetchDataWithRetry('123');
+ * ```
  */
 declare function withRetryAsync<T extends any[], R>(fn: (...args: T) => Promise<R>, options?: RetryOptions): (...args: T) => Promise<R>;
 /**
  * Returns a default value if an error occurs
+ *
+ * Wraps a function to catch any errors and return a fallback value instead,
+ * preventing exceptions from propagating. Useful for providing safe defaults
+ * in transformations or mappings.
+ *
+ * @template T - The input value type
+ * @template R - The return/default value type
+ * @param fn - The function that may throw
+ * @param defaultValue - The value to return if fn throws
+ * @returns A wrapped function that returns defaultValue on error
+ * @example
+ * ```typescript
+ * const parseIntSafe = withDefault(
+ *   (str: string) => {
+ *     const num = parseInt(str, 10);
+ *     if (isNaN(num)) throw new Error("Not a number");
+ *     return num;
+ *   },
+ *   0
+ * );
+ *
+ * parseIntSafe("123");  // returns 123
+ * parseIntSafe("abc");  // returns 0 (default)
+ * ```
  */
 declare function withDefault<T, R>(fn: (value: T) => R, defaultValue: R): (value: T) => R;
 /**
- * Returns undefined if an error occurs (swallows errors)
+ * Returns a fallback value if an error occurs (swallows errors)
+ *
+ * Similar to withDefault, this function wraps another function and returns a fallback
+ * value on error. Provides error-safe execution for operations that should never throw.
+ *
+ * @template T - The input value type
+ * @template R - The return/fallback value type
+ * @param fn - The function that may throw
+ * @param fallback - The value to return if fn throws
+ * @returns A wrapped function that returns fallback on error
+ * @example
+ * ```typescript
+ * const safeDivide = tryOr(
+ *   (x: number) => 100 / x,
+ *   Infinity
+ * );
+ *
+ * safeDivide(10);  // returns 10
+ * safeDivide(0);   // returns Infinity (fallback)
+ * ```
  */
 declare function tryOr<T, R>(fn: (value: T) => R, fallback: R): (value: T) => R;
 /**
  * Executes a function and returns [result, error] tuple
+ *
+ * Provides Go-style error handling by returning both the result and error as a tuple.
+ * Allows explicit error handling without try-catch blocks.
+ *
+ * @template T - The input value type
+ * @template R - The function's return type
+ * @param fn - The function to execute
+ * @param value - The value to pass to fn
+ * @returns A tuple of [result, undefined] on success or [undefined, error] on failure
+ * @example
+ * ```typescript
+ * const [result, error] = tryCatch(
+ *   (str: string) => JSON.parse(str),
+ *   '{"name": "Alice"}'
+ * );
+ *
+ * if (error) {
+ *   console.error("Parse failed:", error);
+ * } else {
+ *   console.log("Parsed:", result);
+ * }
+ * ```
  */
 declare function tryCatch<T, R>(fn: (value: T) => R, value: T): [R | undefined, Error | undefined];
 /**
  * Async version of tryCatch
+ *
+ * Executes an async function and returns [result, error] tuple, providing
+ * Go-style error handling for async operations.
+ *
+ * @template T - The input value type
+ * @template R - The function's return type
+ * @param fn - The async function to execute
+ * @param value - The value to pass to fn
+ * @returns A promise resolving to [result, undefined] on success or [undefined, error] on failure
+ * @example
+ * ```typescript
+ * const [data, error] = await tryCatchAsync(
+ *   async (url: string) => {
+ *     const response = await fetch(url);
+ *     return response.json();
+ *   },
+ *   '/api/users'
+ * );
+ *
+ * if (error) {
+ *   console.error("Request failed:", error);
+ * } else {
+ *   console.log("Data:", data);
+ * }
+ * ```
  */
 declare function tryCatchAsync<T, R>(fn: (value: T) => Promise<R>, value: T): Promise<[R | undefined, Error | undefined]>;
 /**
@@ -2095,22 +3029,131 @@ type Result<T, E = Error> = {
 };
 /**
  * Wraps a function to return a Result type
+ *
+ * Transforms a throwing function into one that returns a discriminated union
+ * Result type ({ success: true, value } | { success: false, error }).
+ * Enables type-safe error handling with exhaustive checking.
+ *
+ * @template T - The input value type
+ * @template R - The function's return type
+ * @param fn - The function that may throw
+ * @returns A wrapped function that returns a Result type
+ * @example
+ * ```typescript
+ * const parseJson = toResult((str: string) => JSON.parse(str));
+ *
+ * const result = parseJson('{"name": "Alice"}');
+ * if (result.success) {
+ *   console.log(result.value.name); // Type-safe access
+ * } else {
+ *   console.error(result.error.message); // Type-safe error handling
+ * }
+ * ```
  */
 declare function toResult<T, R>(fn: (value: T) => R): (value: T) => Result<R>;
 /**
  * Async version of toResult
+ *
+ * Wraps an async function to return a Result type instead of throwing.
+ * Provides type-safe error handling for async operations.
+ *
+ * @template T - The input value type
+ * @template R - The function's return type
+ * @param fn - The async function that may throw
+ * @returns A wrapped async function that returns a Result type
+ * @example
+ * ```typescript
+ * const fetchUser = toResultAsync(async (id: string) => {
+ *   const response = await fetch(`/api/users/${id}`);
+ *   return response.json();
+ * });
+ *
+ * const result = await fetchUser('123');
+ * if (result.success) {
+ *   console.log(result.value.name);
+ * } else {
+ *   console.error("Fetch failed:", result.error);
+ * }
+ * ```
  */
 declare function toResultAsync<T, R>(fn: (value: T) => Promise<R>): (value: T) => Promise<Result<R>>;
 /**
  * Guards a predicate function to return false on error instead of throwing
+ *
+ * Wraps a predicate to prevent errors from breaking filter/find operations.
+ * Returns the default value (false by default) when the predicate throws.
+ *
+ * @template T - The value type being tested
+ * @param predicate - The predicate function that may throw
+ * @param defaultValue - The value to return on error (default: false)
+ * @returns A safe predicate that never throws
+ * @example
+ * ```typescript
+ * const hasValidId = safePredicate(
+ *   (user: any) => user.id > 0,
+ *   false
+ * );
+ *
+ * [{ id: 1 }, { id: null }, { id: 3 }].filter(hasValidId);
+ * // Returns [{ id: 1 }, { id: 3 }] - null.id doesn't throw
+ * ```
  */
 declare function safePredicate<T>(predicate: (value: T, index?: number) => boolean, defaultValue?: boolean): (value: T, index?: number) => boolean;
 /**
  * Guards a comparator function to handle errors gracefully
+ *
+ * Wraps a comparator to prevent errors from breaking sort operations.
+ * Returns the default comparison value (0 by default) when the comparator throws.
+ *
+ * @template T - The value type being compared
+ * @param comparator - The comparator function that may throw
+ * @param defaultComparison - The value to return on error (default: 0, meaning equal)
+ * @returns A safe comparator that never throws
+ * @example
+ * ```typescript
+ * const byAge = safeComparator(
+ *   (a: any, b: any) => a.age - b.age,
+ *   0
+ * );
+ *
+ * [{ age: 30 }, { age: null }, { age: 25 }].sort(byAge);
+ * // Doesn't throw when comparing with null
+ * ```
  */
 declare function safeComparator<T>(comparator: (a: T, b: T) => number, defaultComparison?: number): (a: T, b: T) => number;
 /**
  * Creates an error boundary that catches and logs errors
+ *
+ * Wraps a function with configurable error handling, allowing custom error logging,
+ * optional re-throwing, and default value fallbacks. Ideal for top-level error
+ * boundaries or instrumentation.
+ *
+ * @template T - The function's argument types as a tuple
+ * @template R - The function's return type
+ * @param fn - The function to wrap with error boundary
+ * @param options - Error handling configuration
+ * @param options.onError - Callback invoked when an error occurs, before rethrowing or returning default
+ * @param options.rethrow - Whether to rethrow the error after logging (default: true)
+ * @param options.defaultValue - Value to return instead of rethrowing (only used if rethrow is false)
+ * @returns A wrapped function with error boundary
+ * @throws The original error if rethrow is true (default behavior)
+ * @example
+ * ```typescript
+ * const processWithLogging = errorBoundary(
+ *   (data: unknown) => JSON.parse(data as string),
+ *   {
+ *     onError: (error, [data]) => {
+ *       console.error("Parse failed for:", data, error);
+ *       sendToErrorTracking(error);
+ *     },
+ *     rethrow: false,
+ *     defaultValue: {}
+ *   }
+ * );
+ *
+ * const result = processWithLogging('invalid json');
+ * // Logs error but returns {} instead of throwing
+ * ```
  */
 declare function errorBoundary<T extends any[], R>(fn: (...args: T) => R, options?: {
     onError?: (error: Error, args: T) => void;
@@ -2243,8 +3286,6 @@ declare namespace iter {
      * Uses a custom comparator if provided, otherwise uses default < comparison.
      *
      * @template T The type of elements in all iterables
-     * @param iterables - Variable number of sorted iterables to merge
-     * @param compareFn - Optional comparison function (returns negative if a < b, positive if a > b, 0 if equal)
      * @returns A new iterflow with all elements merged in sorted order
      * @example
      * ```typescript