ts-data-forge 3.2.0 → 3.3.1

package/src/functional/pipe.mts

@@ -3,9 +3,11 @@ import { Optional } from './optional.mjs';
 /**
  * Creates a new pipe object that allows for chaining operations on a value.
  *
- * This function provides a fluent interface for applying transformations to values,
- * with intelligent method selection based on the input type:
- * - For `Optional` values: Provides `mapOptional` for safe Optional transformations
+ * This function provides a fluent interface for applying transformations to
+ * values, with intelligent method selection based on the input type:
+ *
+ * - For `Optional` values: Provides `mapOptional` for safe Optional
+ *   transformations
  * - For other values: Provides `mapNullable` for null-safe transformations
  * - All types get the basic `map` method for general transformations
  *
@@ -15,108 +17,6 @@ import { Optional } from './optional.mjs';
  * @template A The type of the initial value to wrap in a pipe.
  * @param a The initial value to wrap in a pipe.
  * @returns A pipe object with chaining methods appropriate for the value type.
- *
- * @example
- * Basic value transformation chaining:
- * ```ts
- * // Simple sequential transformations
- * const result = pipe(10)
- *   .map(x => x * 2)        // 20
- *   .map(x => x + 5)        // 25
- *   .map(x => x.toString()) // '25'
- *   .value;
- * assert(result === '25');
- *
- * // String processing pipeline
- * const processed = pipe("  Hello World  ")
- *   .map(s => s.trim())           // "Hello World"
- *   .map(s => s.toLowerCase())    // "hello world"
- *   .map(s => s.split(' '))       // ["hello", "world"]
- *   .map(arr => arr.join('-'))    // "hello-world"
- *   .value;
- * assert(processed === "hello-world");
- * ```
- *
- * @example
- * Nullable value handling with automatic null checking:
- * ```ts
- * // Safe operations on potentially nullish values
- * const maybeNumber: number | undefined = 10;
- * const result = pipe(maybeNumber)
- *   .mapNullable(x => x * 2)           // Only applies if not null
- *   .mapNullable(x => `Result: ${x}`)  // Only applies if previous step succeeded
- *   .value; // 'Result: 20' or undefined
- * assert(result === 'Result: 20');
- *
- * // Handling null values
- * const nullValue: number | null = null;
- * const nullResult = pipe(nullValue)
- *   .mapNullable(x => x * 2)
- *   .value;
- * assert(nullResult === undefined);
- * ```
- *
- * @example
- * Optional value handling with monadic operations:
- * ```ts
- * // Working with Optional types
- * const optional = Optional.some(42);
- * const result = pipe(optional)
- *   .mapOptional(x => x / 2)        // Optional.some(21)
- *   .mapOptional(x => Math.sqrt(x)) // Optional.some(~4.58)
- *   .value; // Optional.some(4.58...)
- * assert(Optional.isSome(result) === true);
- * assert(Math.abs(Optional.unwrap(result)! - Math.sqrt(21)) < 0.01);
- *
- * // Optional with None
- * const noneOptional = Optional.none;
- * const noneResult = pipe(noneOptional)
- *   .mapOptional(x => x * 2)
- *   .value;
- * assert(Optional.isNone(noneResult) === true);
- * ```
- *
- * @example
- * Mixed type transformations:
- * ```ts
- * // Starting with a string, transforming through different types
- * const complex = pipe('hello')
- *   .map(s => s.length)          // number: 5
- *   .map(n => n > 3 ? n : undefined)  // number | undefined: 5
- *   .mapNullable(n => n * 10)    // number: 50 (or undefined if undefined)
- *   .value; // 50 or undefined
- * assert(complex === 50);
- *
- * // Short string case
- * const shortString = pipe('hi')
- *   .map(s => s.length)          // number: 2
- *   .map(n => n > 3 ? n : undefined)  // number | undefined: undefined
- *   .mapNullable(n => n * 10)    // undefined
- *   .value;
- * assert(shortString === undefined);
- * ```
- *
- * @example
- * Error-safe computation chains:
- * ```ts
- * // Building complex computations safely
- * const maybeNumber: number | undefined = 25;
- * const result = pipe(maybeNumber)
- *   .mapNullable(n => n > 0 ? n : undefined)          // Positive numbers only
- *   .mapNullable(n => Math.sqrt(n))              // Safe square root
- *   .mapNullable(n => n < 100 ? n : undefined)        // Limit result
- *   .mapNullable(n => Math.round(n * 100) / 100) // Round to 2 decimals
- *   .value; // number | undefined
- *
- * assert(result === 5); // sqrt(25) = 5
- *
- * const negativeNumber: number | undefined = -5;
- * const negativeResult = pipe(negativeNumber)
- *   .mapNullable(n => n > 0 ? n : undefined)
- *   .value;
- * assert(negativeResult === undefined); // negative number
- * ```
- *
  */
 export function pipe<const A extends Optional.Base>(
   a: A,
@@ -143,16 +43,28 @@ export function pipe<const A>(a: A): PipeImpl<A> {
 type Pipe<A> = A extends Optional.Base ? PipeWithMapOptional<A> : PipeBase<A>;
 
 /**
+ * @template A The type of the current value in the pipe.
  * @internal
  * Base pipe interface providing core functionality.
  * All pipe types extend this interface.
- * @template A The type of the current value in the pipe.
  */
 type PipeBase<A> = Readonly<{
   /** The current value being piped. */
   value: A;
+
   /**
    * Maps the current value to a new value using the provided function.
+   *
+   * @example
+   *
+   * ```ts
+   * const result = pipe(2)
+   *   .map((value) => value * 3)
+   *   .map((value) => `value: ${value}`);
+   *
+   * assert.deepStrictEqual(result.value, 'value: 6');
+   * ```
+   *
    * @template B The type of the new value.
    * @param fn Function to transform the current value.
    * @returns A new pipe containing the transformed value.
@@ -160,9 +72,26 @@ type PipeBase<A> = Readonly<{
   map: <B>(fn: (a: A) => B) => Pipe<B>;
 
   /**
-   * Maps the current value only if it's not null or undefined.
-   * If the current value is null/undefined, the transformation is skipped
-   * and undefined is propagated through the pipe.
+   * Maps the current value only if it's not null or undefined. If the current
+   * value is null/undefined, the transformation is skipped and undefined is
+   * propagated through the pipe.
+   *
+   * @example
+   *
+   * ```ts
+   * const result = pipe<string | undefined>('hello')
+   *   .mapNullable((value) => value.toUpperCase())
+   *   .mapNullable((value) => value.slice(0, 2));
+   *
+   * assert.deepStrictEqual(result.value, 'HE');
+   *
+   * const empty = pipe<string | undefined>(undefined).mapNullable((value) =>
+   *   value.toUpperCase(),
+   * );
+   *
+   * assert(empty.value === undefined);
+   * ```
+   *
    * @template B The type of the transformed value.
    * @param fn Function to transform the non-null value.
    * @returns A new pipe containing the transformed value or undefined.
@@ -171,18 +100,36 @@ type PipeBase<A> = Readonly<{
 }>;
 
 /**
+ * @template A The Optional type currently in the pipe.
  * @internal
  * Pipe interface for Optional values, providing Optional-aware mapping.
  * Extends PipeBase with mapOptional functionality for monadic operations.
- * @template A The Optional type currently in the pipe.
  */
 type PipeWithMapOptional<A extends Optional.Base> = MergeIntersection<
   PipeBase<A> &
     Readonly<{
       /**
-       * Maps the value inside an Optional using Optional.map semantics.
-       * If the Optional is None, the transformation is skipped and None is propagated.
-       * If the Optional is Some, the transformation is applied to the inner value.
+       * Maps the value inside an Optional using Optional.map semantics. If the
+       * Optional is None, the transformation is skipped and None is propagated.
+       * If the Optional is Some, the transformation is applied to the inner
+       * value.
+       *
+       * @example
+       *
+       * ```ts
+       * const result = pipe(Optional.some(10))
+       *   .mapOptional((value) => value * 2)
+       *   .mapOptional((value) => value + 5);
+       *
+       * assert.deepStrictEqual(result.value, Optional.some(25));
+       *
+       * const empty = pipe(Optional.none as Optional<number>).mapOptional(
+       *   (value) => value * 2,
+       * );
+       *
+       * assert.ok(Optional.isNone(empty.value));
+       * ```
+       *
        * @template B The type of the transformed inner value.
        * @param fn Function to transform the inner value of the Optional.
        * @returns A new pipe containing an Optional with the transformed value.