ts-data-forge 3.3.0 → 3.3.1

package/dist/functional/optional.mjs

@@ -5,13 +5,25 @@ const SomeTypeTagName = 'ts-data-forge::Optional.some';
 /** @internal String literal tag to identify the 'None' variant of Optional. */
 const NoneTypeTagName = 'ts-data-forge::Optional.none';
 /**
- * Namespace for the {@link Optional} type and related functions.
- * Provides utilities to handle values that might be absent, similar to Option types in other languages.
+ * Namespace for the {@link Optional} type and related functions. Provides
+ * utilities to handle values that might be absent, similar to Option types in
+ * other languages.
  */
 var Optional;
 (function (Optional) {
     /**
      * Checks if the given value is an {@link Optional}.
+     *
+     * @example
+     *
+     * ```ts
+     * const maybeOptional = Optional.some('value');
+     * const notOptional = { $$tag: 'ts-data-forge::Optional.some' };
+     *
+     * assert.ok(Optional.isOptional(maybeOptional));
+     * assert.notOk(Optional.isOptional(notOptional));
+     * ```
+     *
      * @param maybeOptional The value to check.
      * @returns `true` if the value is an {@link Optional}, otherwise `false`.
      */
@@ -22,81 +34,116 @@ var Optional;
             maybeOptional['$$tag'] === NoneTypeTagName);
     /**
      * Creates an {@link Optional.Some} containing the given value.
+     *
+     * @example
+     *
+     * ```ts
+     * const someValue = Optional.some({ id: 1 });
+     * const noneValue = Optional.none;
+     *
+     * assert.ok(Optional.isSome(someValue));
+     * assert.ok(Optional.isNone(noneValue));
+     * ```
+     *
      * @template S The type of the value.
      * @param value The value to wrap in an {@link Optional.Some}.
      * @returns An {@link Optional.Some}<S> containing the value.
-     * @example
-     * ```typescript
-     * const someValue = Optional.some(42);
-     * console.log(Optional.isSome(someValue)); // true
-     * console.log(Optional.unwrap(someValue)); // 42
-     * ```
      */
     Optional.some = (value) => ({
         $$tag: SomeTypeTagName,
         value,
     });
     /**
-     * The singleton instance representing {@link Optional.None} (an empty Optional).
+     * The singleton instance representing {@link Optional.None} (an empty
+     * Optional).
+     *
      * @example
-     * ```typescript
-     * const emptyValue = Optional.none;
-     * console.log(Optional.isNone(emptyValue)); // true
-     * console.log(Optional.unwrapOr(emptyValue, "default")); // "default"
+     *
+     * ```ts
+     * const someValue = Optional.some({ id: 1 });
+     * const noneValue = Optional.none;
+     *
+     * assert.ok(Optional.isSome(someValue));
+     * assert.ok(Optional.isNone(noneValue));
      * ```
      */
     Optional.none = { $$tag: NoneTypeTagName };
     /**
-     * Checks if an {@link Optional} is {@link Optional.Some}.
-     * Acts as a type guard.
+     * Checks if an {@link Optional} is {@link Optional.Some}. Acts as a type guard.
+     *
+     * @example
+     *
+     * ```ts
+     * const optionalNumber = Optional.some(42);
+     *
+     * if (Optional.isSome(optionalNumber)) {
+     *   const value: number = optionalNumber.value;
+     *   assert(value === 42);
+     * }
+     * ```
+     *
      * @template O The {@link Optional.Base} type to check.
      * @param optional The {@link Optional} to check.
-     * @returns `true` if the {@link Optional} is {@link Optional.Some}, `false` otherwise.
+     * @returns `true` if the {@link Optional} is {@link Optional.Some}, `false`
+     *   otherwise.
      */
     Optional.isSome = (optional) => optional.$$tag === SomeTypeTagName;
     /**
-     * Checks if an {@link Optional} is {@link Optional.None}.
-     * Acts as a type guard.
+     * Checks if an {@link Optional} is {@link Optional.None}. Acts as a type guard.
+     *
+     * @example
+     *
+     * ```ts
+     * const optionalValue = Optional.none as Optional<number>;
+     *
+     * if (Optional.isNone(optionalValue)) {
+     *   // Type narrowed to None
+     *   assert.ok(true); // optionalValue is None
+     * }
+     * ```
+     *
      * @template O The {@link Optional.Base} type to check.
      * @param optional The {@link Optional} to check.
-     * @returns `true` if the {@link Optional} is {@link Optional.None}, `false` otherwise.
+     * @returns `true` if the {@link Optional} is {@link Optional.None}, `false`
+     *   otherwise.
      */
     Optional.isNone = (optional) => optional.$$tag === NoneTypeTagName;
     /**
-     * Unwraps an `Optional`, returning the contained value.
-     * Throws an error if the `Optional` is `Optional.None`.
+     * Unwraps an `Optional`, returning the contained value. Throws an error if
+     * the `Optional` is `Optional.None`.
      *
-     * This is a safer alternative to direct value access when you know the Optional
-     * should contain a value. Use this method when an empty Optional represents
-     * a programming error or unexpected condition.
+     * This is a safer alternative to direct value access when you know the
+     * Optional should contain a value. Use this method when an empty Optional
+     * represents a programming error or unexpected condition.
+     *
+     * @example
+     *
+     * ```ts
+     * const present = Optional.some('available');
+     *
+     * assert(Optional.unwrapThrow(present) === 'available');
+     * assert.throws(
+     *   () => Optional.unwrapThrow(Optional.none),
+     *   /has failed because it is `None`/u,
+     * );
+     * ```
      *
      * @template O The `Optional.Base` type to unwrap.
      * @param optional The `Optional` to unwrap.
      * @returns The contained value if `Optional.Some`.
-     * @throws {Error} Error with message "`unwrapThrow()` has failed because it is `None`" if the `Optional` is `Optional.None`.
-     * @example
-     * ```typescript
-     * const userInput = Optional.some(42);
-     * console.log(Optional.unwrapThrow(userInput)); // 42
-     *
-     * const empty = Optional.none;
-     * try {
-     *   Optional.unwrapThrow(empty); // throws Error
-     * } catch (error) {
-     *   console.log(error.message); // "`unwrapThrow()` has failed because it is `None`"
-     * }
-     * ```
+     * @throws {Error} Error with message "`unwrapThrow()` has failed because it
+     *   is `None`" if the `Optional` is `Optional.None`.
      */
     Optional.unwrapThrow = (optional) => {
         if (Optional.isSome(optional)) {
-            // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+            // eslint-disable-next-line total-functions/no-unsafe-type-assertion
             return optional.value;
         }
         throw new Error('`unwrapThrow()` has failed because it is `None`');
     };
     function unwrap(optional) {
         return Optional.isSome(optional)
-            ? // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+            ? // eslint-disable-next-line total-functions/no-unsafe-type-assertion
                 optional.value
             : undefined;
     }
@@ -106,7 +153,7 @@ var Optional;
             case 2: {
                 const [optional, defaultValue] = args;
                 return Optional.isSome(optional)
-                    ? // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+                    ? // eslint-disable-next-line total-functions/no-unsafe-type-assertion
                         optional.value
                     : defaultValue;
             }
@@ -198,21 +245,31 @@ var Optional;
     /**
      * Combines two `Optional` values into a single `Optional` containing a tuple.
      * If either `Optional` is `None`, returns `None`.
+     *
+     * @example
+     *
+     * ```ts
+     * const zipped = Optional.zip(Optional.some('left'), Optional.some(1));
+     *
+     * assert.ok(Optional.isSome(zipped));
+     * if (Optional.isSome(zipped)) {
+     *   const expected: readonly [string, number] = ['left', 1];
+     *   assert.deepStrictEqual(zipped.value, expected);
+     * }
+     *
+     * const missing = Optional.zip(
+     *   Optional.some('value'),
+     *   Optional.none as Optional<number>,
+     * );
+     *
+     * assert.deepStrictEqual(missing, Optional.none);
+     * ```
+     *
      * @template A The value type of the first `Optional`.
      * @template B The value type of the second `Optional`.
      * @param optionalA The first `Optional`.
      * @param optionalB The second `Optional`.
      * @returns An `Optional` containing a tuple of both values, or `None`.
-     * @example
-     * ```typescript
-     * const a = Optional.some(1);
-     * const b = Optional.some("hello");
-     * const zipped = Optional.zip(a, b);
-     * console.log(Optional.unwrap(zipped)); // [1, "hello"]
-     *
-     * const withNone = Optional.zip(a, Optional.none);
-     * console.log(Optional.isNone(withNone)); // true
-     * ```
      */
     Optional.zip = (optionalA, optionalB) => Optional.isSome(optionalA) && Optional.isSome(optionalB)
         ? Optional.some([optionalA.value, optionalB.value])
@@ -224,19 +281,20 @@ var Optional;
      * the Optional type system. The function treats both `null` and `undefined`
      * as empty values, converting them to `Optional.None`.
      *
-     * @template T The type of the nullable value.
-     * @param value The nullable value to convert.
-     * @returns `Optional.Some<NonNullable<T>>` if the value is not null or undefined, otherwise `Optional.None`.
      * @example
-     * ```typescript
-     * const value: string | null = "hello";
-     * const optional = Optional.fromNullable(value);
-     * console.log(Optional.unwrap(optional)); // "hello"
-     *
-     * const nullValue: string | null = null;
-     * const noneOptional = Optional.fromNullable(nullValue);
-     * console.log(Optional.isNone(noneOptional)); // true
+     *
+     * ```ts
+     * const present = Optional.fromNullable('hello');
+     * const absent = Optional.fromNullable<string | null>(null);
+     *
+     * assert.deepStrictEqual(present, Optional.some('hello'));
+     * assert.deepStrictEqual(absent, Optional.none);
      * ```
+     *
+     * @template T The type of the nullable value.
+     * @param value The nullable value to convert.
+     * @returns `Optional.Some<NonNullable<T>>` if the value is not null or
+     *   undefined, otherwise `Optional.None`.
      */
     Optional.fromNullable = (value) => (value == null ? Optional.none : Optional.some(value));
     /**
@@ -246,20 +304,22 @@ var Optional;
      * for empty Optionals. This is useful when interfacing with APIs or systems
      * that expect nullable values rather than Optional types.
      *
-     * Note: This returns `undefined` (not `null`) for consistency with JavaScript's
-     * undefined semantics and TypeScript's optional properties.
+     * Note: This returns `undefined` (not `null`) for consistency with
+     * JavaScript's undefined semantics and TypeScript's optional properties.
      *
-     * @template O The `Optional.Base` type to convert.
-     * @param optional The `Optional` to convert.
-     * @returns The contained value if `Some`, otherwise `undefined`.
      * @example
-     * ```typescript
-     * const some = Optional.some(42);
-     * console.log(Optional.toNullable(some)); // 42
      *
-     * const none = Optional.none;
-     * console.log(Optional.toNullable(none)); // undefined
+     * ```ts
+     * const someNumber = Optional.some(42);
+     * const noneNumber = Optional.none as Optional<number>;
+     *
+     * assert(Optional.toNullable(someNumber) === 42);
+     * assert(Optional.toNullable(noneNumber) === undefined);
      * ```
+     *
+     * @template O The `Optional.Base` type to convert.
+     * @param optional The `Optional` to convert.
+     * @returns The contained value if `Some`, otherwise `undefined`.
      */
     Optional.toNullable = (optional) => (Optional.isSome(optional) ? unwrap(optional) : undefined);
 })(Optional || (Optional = {}));

package/dist/functional/optional.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"optional.mjs","sources":["../../src/functional/optional.mts"],"sourcesContent":[null],"names":[],"mappings":"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"}
+{"version":3,"file":"optional.mjs","sources":["../../src/functional/optional.mts"],"sourcesContent":[null],"names":[],"mappings":";;AAEA;AACA,MAAM,eAAe,GAAG,8BAA8B;AAEtD;AACA,MAAM,eAAe,GAAG,8BAA8B;AAsCtD;;;;AAIG;AACG,IAAW;AAAjB,CAAA,UAAiB,QAAQ,EAAA;AACvB;;;;;;;;;;;;;;;AAeG;IACU,QAAA,CAAA,UAAU,GAAG,CACxB,aAAsB,KAEtB,QAAQ,CAAC,aAAa,CAAC;AACvB,QAAA,MAAM,CAAC,MAAM,CAAC,aAAa,EAAE,OAAO,CAAC;AACrC,SAAC,CAAC,aAAa,CAAC,OAAO,CAAC,KAAK,eAAe;AAC1C,YAAA,MAAM,CAAC,MAAM,CAAC,aAAa,EAAE,OAAO,CAAC;AACrC,YAAA,aAAa,CAAC,OAAO,CAAC,KAAK,eAAe,CAAC;AA4C/C;;;;;;;;;;;;;;;;AAgBG;AACU,IAAA,QAAA,CAAA,IAAI,GAAG,CAAK,KAAQ,MAAe;AAC9C,QAAA,KAAK,EAAE,eAAe;QACtB,KAAK;AACN,KAAA,CAAC;AAEF;;;;;;;;;;;;;AAaG;AACU,IAAA,QAAA,CAAA,IAAI,GAAS,EAAE,KAAK,EAAE,eAAe,EAAW;AAE7D;;;;;;;;;;;;;;;;;;AAkBG;IACU,QAAA,CAAA,MAAM,GAAG,CACpB,QAAW,KACqB,QAAQ,CAAC,KAAK,KAAK,eAAe;AAEpE;;;;;;;;;;;;;;;;;;AAkBG;IACU,QAAA,CAAA,MAAM,GAAG,CACpB,QAAW,KACqB,QAAQ,CAAC,KAAK,KAAK,eAAe;AAEpE;;;;;;;;;;;;;;;;;;;;;;;;;AAyBG;AACU,IAAA,QAAA,CAAA,WAAW,GAAG,CAAiB,QAAW,KAAe;AACpE,QAAA,IAAI,SAAA,MAAM,CAAC,QAAQ,CAAC,EAAE;;YAEpB,OAAO,QAAQ,CAAC,KAAkB;QACpC;AAEA,QAAA,MAAM,IAAI,KAAK,CAAC,iDAAiD,CAAC;AACpE,IAAA,CAAC;IA8BD,SAAgB,MAAM,CAAiB,QAAW,EAAA;AAChD,QAAA,OAAO,QAAA,CAAA,MAAM,CAAC,QAAQ;AACpB;AACG,gBAAA,QAAQ,CAAC;cACV,SAAS;IACf;AALgB,IAAA,QAAA,CAAA,MAAM,SAKrB;IAyCD,SAAgB,QAAQ,CACtB,GAAG,IAE2B,EAAA;AAE9B,QAAA,QAAQ,IAAI,CAAC,MAAM;YACjB,KAAK,CAAC,EAAE;AACN,gBAAA,MAAM,CAAC,QAAQ,EAAE,YAAY,CAAC,GAAG,IAAI;AACrC,gBAAA,OAAO,QAAA,CAAA,MAAM,CAAC,QAAQ;AACpB;AACG,wBAAA,QAAQ,CAAC;sBACV,YAAY;YAClB;YAEA,KAAK,CAAC,EAAE;;AAEN,gBAAA,MAAM,CAAC,YAAY,CAAC,GAAG,IAAI;gBAC3B,OAAO,CAAC,QAA6B,KACnC,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;YACpC;;IAEJ;AArBgB,IAAA,QAAA,CAAA,QAAQ,WAqBvB;IA4CD,SAAgB,MAAM,CACpB,GAAG,IAE2B,EAAA;AAE9B,QAAA,QAAQ,IAAI,CAAC,MAAM;YACjB,KAAK,CAAC,EAAE;AACN,gBAAA,MAAM,CAAC,QAAQ,EAAE,WAAW,CAAC,GAAG,IAAI;AACpC,gBAAA,OAAO,QAAA,CAAA,MAAM,CAAC,QAAQ,CAAC,GAAG,WAAW,GAAG,QAAQ;YAClD;YAEA,KAAK,CAAC,EAAE;AACN,gBAAA,MAAM,CAAC,WAAW,CAAC,GAAG,IAAI;gBAC1B,OAAO,CAAC,QAA6B,KAAK,MAAM,CAAC,QAAQ,EAAE,WAAW,CAAC;YACzE;;IAEJ;AAhBgB,IAAA,QAAA,CAAA,MAAM,SAgBrB;IAwCD,SAAgB,GAAG,CACjB,GAAG,IAE2C,EAAA;AAE9C,QAAA,QAAQ,IAAI,CAAC,MAAM;YACjB,KAAK,CAAC,EAAE;AACN,gBAAA,MAAM,CAAC,QAAQ,EAAE,KAAK,CAAC,GAAG,IAAI;;gBAE9B,OAAO,QAAA,CAAA,MAAM,CAAC,QAAQ,CAAC,GAAG,QAAA,CAAA,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAE,CAAC,CAAC,GAAG,QAAA,CAAA,IAAI;YACjE;YACA,KAAK,CAAC,EAAE;;AAEN,gBAAA,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI;gBACpB,OAAO,CAAC,QAAW,KAAK,GAAG,CAAC,QAAQ,EAAE,KAAK,CAAC;YAC9C;;IAEJ;AAjBgB,IAAA,QAAA,CAAA,GAAG,MAiBlB;IAyCD,SAAgB,OAAO,CACrB,GAAG,IAEyD,EAAA;AAE5D,QAAA,QAAQ,IAAI,CAAC,MAAM;YACjB,KAAK,CAAC,EAAE;AACN,gBAAA,MAAM,CAAC,QAAQ,EAAE,SAAS,CAAC,GAAG,IAAI;gBAClC,OAAO,QAAA,CAAA,MAAM,CAAC,QAAQ,CAAC,GAAG,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,GAAG,QAAA,CAAA,IAAI;YAC9D;YAEA,KAAK,CAAC,EAAE;AACN,gBAAA,MAAM,CAAC,SAAS,CAAC,GAAG,IAAI;gBACxB,OAAO,CAAC,QAAW,KAAK,OAAO,CAAC,QAAQ,EAAE,SAAS,CAAC;YACtD;;IAEJ;AAhBgB,IAAA,QAAA,CAAA,OAAO,UAgBtB;IAqCD,SAAgB,MAAM,CACpB,GAAG,IAEoD,EAAA;AAEvD,QAAA,QAAQ,IAAI,CAAC,MAAM;YACjB,KAAK,CAAC,EAAE;AACN,gBAAA,MAAM,CAAC,QAAQ,EAAE,SAAS,CAAC,GAAG,IAAI;AAClC,gBAAA,IAAI,SAAA,MAAM,CAAC,QAAQ,CAAC,EAAE;AACpB,oBAAA,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC;AAC9B,oBAAA,OAAO,SAAS,CAAC,KAAK,CAAC,GAAG,QAAA,CAAA,IAAI,CAAC,KAAK,CAAC,GAAG,QAAA,CAAA,IAAI;gBAC9C;;gBAEA,OAAO,QAAA,CAAA,IAAI;YACb;YAEA,KAAK,CAAC,EAAE;;AAEN,gBAAA,MAAM,CAAC,SAAS,CAAC,GAAG,IAAI;gBACxB,OAAO,CAAC,QAAW,KAAK,MAAM,CAAC,QAAQ,EAAE,SAAS,CAAC;YACrD;;IAEJ;AAtBgB,IAAA,QAAA,CAAA,MAAM,SAsBrB;IAmCD,SAAgB,UAAU,CACxB,GAAG,IAE2B,EAAA;AAE9B,QAAA,QAAQ,IAAI,CAAC,MAAM;YACjB,KAAK,CAAC,EAAE;AACN,gBAAA,MAAM,CAAC,QAAQ,EAAE,OAAO,CAAC,GAAG,IAAI;AAChC,gBAAA,IAAI,SAAA,MAAM,CAAC,QAAQ,CAAC,EAAE;AACpB,oBAAA,OAAO,MAAM,CAAC,QAAQ,CAAC;gBACzB;AACA,gBAAA,MAAM,IAAI,KAAK,CAAC,OAAO,CAAC;YAC1B;YAEA,KAAK,CAAC,EAAE;;AAEN,gBAAA,MAAM,CAAC,OAAO,CAAC,GAAG,IAAI;gBACtB,OAAO,CAAC,QAA6B,KACnC,UAAU,CAAC,QAAQ,EAAE,OAAO,CAAC;YACjC;;IAEJ;AArBgB,IAAA,QAAA,CAAA,UAAU,aAqBzB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4BG;AACU,IAAA,QAAA,CAAA,GAAG,GAAG,CACjB,SAAsB,EACtB,SAAsB,KAEtB,QAAA,CAAA,MAAM,CAAC,SAAS,CAAC,IAAI,SAAA,MAAM,CAAC,SAAS;AACnC,UAAE,QAAA,CAAA,IAAI,CAAC,CAAC,SAAS,CAAC,KAAK,EAAE,SAAS,CAAC,KAAK,CAAU;UAChD,QAAA,CAAA,IAAI;AAEV;;;;;;;;;;;;;;;;;;;;;AAqBG;IACU,QAAA,CAAA,YAAY,GAAG,CAC1B,KAA2B,MACG,KAAK,IAAI,IAAI,GAAG,QAAA,CAAA,IAAI,GAAG,QAAA,CAAA,IAAI,CAAC,KAAK,CAAC,CAAC;AAEnE;;;;;;;;;;;;;;;;;;;;;;;AAuBG;IACU,QAAA,CAAA,UAAU,GAAG,CACxB,QAAW,MACgB,QAAA,CAAA,MAAM,CAAC,QAAQ,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,SAAS,CAAC;AAC/E,CAAC,EAvpBgB,QAAQ,KAAR,QAAQ,GAAA,EAAA,CAAA,CAAA;;;;"}

package/dist/functional/pipe.d.mts

@@ -2,9 +2,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
  *
@@ -14,132 +16,58 @@ 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 declare function pipe<const A extends Optional.Base>(a: A): PipeWithMapOptional<A>;
 export declare function pipe<const A>(a: A): PipeBase<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.
      */
     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.
@@ -147,16 +75,34 @@ type PipeBase<A> = Readonly<{
     mapNullable: <B>(fn: (a: NonNullable<A>) => B) => Pipe<B | undefined>;
 }>;
 /**
+ * @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.

package/dist/functional/pipe.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"pipe.d.mts","sourceRoot":"","sources":["../../src/functional/pipe.mts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqHG;AACH,wBAAgB,IAAI,CAAC,KAAK,CAAC,CAAC,SAAS,QAAQ,CAAC,IAAI,EAChD,CAAC,EAAE,CAAC,GACH,mBAAmB,CAAC,CAAC,CAAC,CAAC;AAE1B,wBAAgB,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;AAkBjD,KAAK,IAAI,CAAC,CAAC,IAAI,CAAC,SAAS,QAAQ,CAAC,IAAI,GAAG,mBAAmB,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;AAE9E;;;;;GAKG;AACH,KAAK,QAAQ,CAAC,CAAC,IAAI,QAAQ,CAAC;IAC1B,qCAAqC;IACrC,KAAK,EAAE,CAAC,CAAC;IACT;;;;;OAKG;IACH,GAAG,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC;IAErC;;;;;;;OAOG;IACH,WAAW,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;CACvE,CAAC,CAAC;AAEH;;;;;GAKG;AACH,KAAK,mBAAmB,CAAC,CAAC,SAAS,QAAQ,CAAC,IAAI,IAAI,iBAAiB,CACnE,QAAQ,CAAC,CAAC,CAAC,GACT,QAAQ,CAAC;IACP;;;;;;;OAOG;IACH,WAAW,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;CACzE,CAAC,CACL,CAAC"}
+{"version":3,"file":"pipe.d.mts","sourceRoot":"","sources":["../../src/functional/pipe.mts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE1C;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,IAAI,CAAC,KAAK,CAAC,CAAC,SAAS,QAAQ,CAAC,IAAI,EAChD,CAAC,EAAE,CAAC,GACH,mBAAmB,CAAC,CAAC,CAAC,CAAC;AAE1B,wBAAgB,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;AAkBjD,KAAK,IAAI,CAAC,CAAC,IAAI,CAAC,SAAS,QAAQ,CAAC,IAAI,GAAG,mBAAmB,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;AAE9E;;;;;GAKG;AACH,KAAK,QAAQ,CAAC,CAAC,IAAI,QAAQ,CAAC;IAC1B,qCAAqC;IACrC,KAAK,EAAE,CAAC,CAAC;IAET;;;;;;;;;;;;;;;;OAgBG;IACH,GAAG,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC;IAErC;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,WAAW,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;CACvE,CAAC,CAAC;AAEH;;;;;GAKG;AACH,KAAK,mBAAmB,CAAC,CAAC,SAAS,QAAQ,CAAC,IAAI,IAAI,iBAAiB,CACnE,QAAQ,CAAC,CAAC,CAAC,GACT,QAAQ,CAAC;IACP;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,WAAW,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;CACzE,CAAC,CACL,CAAC"}

package/dist/functional/pipe.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"pipe.mjs","sources":["../../src/functional/pipe.mts"],"sourcesContent":[null],"names":[],"mappings":";;AA8HM,SAAU,IAAI,CAAU,CAAI,EAAA;AAChC,IAAA,IAAI,QAAQ,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE;QAC1B,OAAO;AACL,YAAA,KAAK,EAAE,CAAC;AACR,YAAA,GAAG,EAAE,CAAC,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;AACxB,YAAA,WAAW,EAAE,CAAC,EAAE,KAAK,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;SAC/C;IACH;SAAO;QACL,OAAO;AACL,YAAA,KAAK,EAAE,CAAC;AACR,YAAA,GAAG,EAAE,CAAC,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;YACxB,WAAW,EAAE,CAAC,EAAE,KAAK,IAAI,CAAC,CAAC,IAAI,IAAI,GAAG,SAAS,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC;SACzD;IACH;AACF;;;;"}
+{"version":3,"file":"pipe.mjs","sources":["../../src/functional/pipe.mts"],"sourcesContent":[null],"names":[],"mappings":";;AA0BM,SAAU,IAAI,CAAU,CAAI,EAAA;AAChC,IAAA,IAAI,QAAQ,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE;QAC1B,OAAO;AACL,YAAA,KAAK,EAAE,CAAC;AACR,YAAA,GAAG,EAAE,CAAC,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;AACxB,YAAA,WAAW,EAAE,CAAC,EAAE,KAAK,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;SAC/C;IACH;SAAO;QACL,OAAO;AACL,YAAA,KAAK,EAAE,CAAC;AACR,YAAA,GAAG,EAAE,CAAC,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;YACxB,WAAW,EAAE,CAAC,EAAE,KAAK,IAAI,CAAC,CAAC,IAAI,IAAI,GAAG,SAAS,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC;SACzD;IACH;AACF;;;;"}