ts-data-forge 1.5.0 → 1.5.2

package/src/functional/optional.mts

@@ -106,9 +106,6 @@ export namespace Optional {
    * @example
    * ```typescript
    * const someValue = Optional.some(42);
-   * const someString = Optional.some("hello");
-   * const someObject = Optional.some({ name: "Alice", age: 30 });
-   *
    * console.log(Optional.isSome(someValue)); // true
    * console.log(Optional.unwrap(someValue)); // 42
    * ```
@@ -123,9 +120,7 @@ export namespace Optional {
    * @example
    * ```typescript
    * const emptyValue = Optional.none;
-   *
    * console.log(Optional.isNone(emptyValue)); // true
-   * console.log(Optional.unwrap(emptyValue)); // undefined
    * console.log(Optional.unwrapOr(emptyValue, "default")); // "default"
    * ```
    */
@@ -167,14 +162,6 @@ export namespace Optional {
    * @throws {Error} Error with message "`unwrapThrow()` has failed because it is `None`" if the `Optional` is `Optional.None`.
    * @example
    * ```typescript
-   * // Safe unwrapping when you know the value exists
-   * const config = loadConfig(); // returns Optional<Config>
-   * if (Optional.isSome(config)) {
-   *   const value = Optional.unwrapThrow(config); // Safe to unwrap
-   *   console.log(value); // Config object
-   * }
-   *
-   * // Unsafe unwrapping - will throw if empty
    * const userInput = Optional.some(42);
    * console.log(Optional.unwrapThrow(userInput)); // 42
    *
@@ -208,35 +195,23 @@ export namespace Optional {
    * @returns The contained value if `Optional.Some`, otherwise `undefined`.
    * @example
    * ```typescript
-   * // With Some - guaranteed to return value
    * const some = Optional.some(42);
-   * const value = Optional.unwrap(some); // Type: number, Value: 42
+   * const value = Optional.unwrap(some); // 42
    *
-   * // With general Optional - may return undefined
-   * const maybeValue: Optional<string> = getOptionalString();
-   * const result = Optional.unwrap(maybeValue); // Type: string | undefined
-   *
-   * // Safe pattern for handling both cases
-   * const optional = Optional.some("hello");
-   * const unwrapped = Optional.unwrap(optional);
-   * if (unwrapped !== undefined) {
-   *   console.log(unwrapped.toUpperCase()); // "HELLO"
-   * }
+   * const none = Optional.none;
+   * const result = Optional.unwrap(none); // undefined
    * ```
    */
-  export const unwrap: UnwrapFnOverload = (<O extends Base>(
-    optional: O,
-  ): Unwrap<O> | undefined =>
-    isNone(optional)
-      ? undefined
-      : // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
-        ((optional as NarrowToSome<O>).value as Unwrap<O>)) as UnwrapFnOverload;
+  export function unwrap<O extends Some<unknown>>(optional: O): Unwrap<O>;
 
-  type UnwrapFnOverload = {
-    <O extends Some<unknown>>(optional: O): Unwrap<O>;
+  export function unwrap<O extends Base>(optional: O): Unwrap<O> | undefined;
 
-    <O extends Base>(optional: O): Unwrap<O> | undefined;
-  };
+  export function unwrap<O extends Base>(optional: O): Unwrap<O> | undefined {
+    return isSome(optional)
+      ? // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+        (optional.value as Unwrap<O>)
+      : undefined;
+  }
 
   /**
    * Unwraps an `Optional`, returning the contained value or a default value if it's `Optional.None`.
@@ -252,11 +227,6 @@ export namespace Optional {
    * @example
    * ```typescript
    * // Direct usage - most common pattern
-   * const userAge = Optional.fromNullable(user.age);
-   * const displayAge = Optional.unwrapOr(userAge, "Unknown");
-   * console.log(`Age: ${displayAge}`); // "Age: 25" or "Age: Unknown"
-   *
-   * // With different Optional types
    * const some = Optional.some(42);
    * const value1 = Optional.unwrapOr(some, 0);
    * console.log(value1); // 42
@@ -265,33 +235,34 @@ export namespace Optional {
    * const value2 = Optional.unwrapOr(none, 0);
    * console.log(value2); // 0
    *
-   * // Curried usage for functional composition
+   * // Curried usage
    * const unwrapWithDefault = Optional.unwrapOr("default");
-   * const result = pipe(Optional.some("hello"))
-   *   .map(unwrapWithDefault)
-   *   .value;
+   * const result = unwrapWithDefault(Optional.some("hello"));
    * console.log(result); // "hello"
-   *
-   * // Chaining with other Optional operations
-   * const processValue = (input: string) =>
-   *   pipe(Optional.fromNullable(input))
-   *     .map(Optional.map(s => s.toUpperCase()))
-   *     .map(Optional.unwrapOr("NO INPUT"))
-   *     .value;
    * ```
    */
-  export const unwrapOr: UnwrapOrFnOverload = (<O extends Base, D>(
+  export function unwrapOr<O extends Base, D>(
+    optional: O,
+    defaultValue: D,
+  ): D | Unwrap<O>;
+
+  // Curried version
+  export function unwrapOr<S, D>(
+    defaultValue: D,
+  ): (optional: Optional<S>) => D | S;
+
+  export function unwrapOr<O extends Base, D>(
     ...args:
       | readonly [optional: O, defaultValue: D]
       | readonly [defaultValue: D]
-  ): (D | Unwrap<O>) | ((optional: Optional<Unwrap<O>>) => D | Unwrap<O>) => {
+  ): (D | Unwrap<O>) | ((optional: Optional<Unwrap<O>>) => D | Unwrap<O>) {
     switch (args.length) {
       case 2: {
         const [optional, defaultValue] = args;
-        return isNone(optional)
-          ? defaultValue
-          : // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
-            ((optional as NarrowToSome<O>).value as Unwrap<O>);
+        return isSome(optional)
+          ? // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+            (optional.value as Unwrap<O>)
+          : defaultValue;
       }
 
       case 1: {
@@ -301,14 +272,7 @@ export namespace Optional {
           unwrapOr(optional, defaultValue);
       }
     }
-  }) as UnwrapOrFnOverload;
-
-  type UnwrapOrFnOverload = {
-    <O extends Base, D>(optional: O, defaultValue: D): D | Unwrap<O>;
-
-    // Curried version
-    <S, D>(defaultValue: D): (optional: Optional<S>) => D | S;
-  };
+  }
 
   /**
    * Returns the `Optional` if it is `Some`, otherwise returns the alternative.
@@ -323,47 +287,27 @@ export namespace Optional {
    * @returns The first `Optional` if `Some`, otherwise the alternative.
    * @example
    * ```typescript
-   * // Direct usage - cascading lookups
-   * const primaryConfig = loadPrimaryConfig(); // Optional<Config>
-   * const fallbackConfig = loadFallbackConfig(); // Optional<Config>
-   * const config = Optional.orElse(primaryConfig, fallbackConfig);
-   *
-   * // Multiple fallbacks
-   * const userPreference = getUserPreference(); // Optional<string>
-   * const systemDefault = Optional.some("default-theme");
-   * const theme = Optional.orElse(userPreference, systemDefault);
-   * console.log(Optional.unwrap(theme)); // User's preference or "default-theme"
-   *
-   * // Regular usage example
    * const primary = Optional.none;
    * const fallback = Optional.some("default");
    * const result = Optional.orElse(primary, fallback);
    * console.log(Optional.unwrap(result)); // "default"
-   *
-   * // Curried usage for functional composition
-   * const withFallback = Optional.orElse(Optional.some("fallback"));
-   * const result2 = pipe(Optional.none)
-   *   .map(withFallback)
-   *   .value;
-   * console.log(Optional.unwrap(result2)); // "fallback"
-   *
-   * // Chaining multiple orElse operations
-   * const finalResult = pipe(Optional.none)
-   *   .map(Optional.orElse(Optional.none)) // Still none
-   *   .map(Optional.orElse(Optional.some("last resort")))
-   *   .value;
    * ```
    */
-  export const orElse: OrElseFnOverload = (<
-    O extends Base,
-    const O2 extends Base,
-  >(
+  export function orElse<O extends Base, const O2 extends Base>(
+    optional: O,
+    alternative: O2,
+  ): O | O2;
+
+  // Curried version
+  export function orElse<S, S2>(
+    alternative: Optional<S2>,
+  ): (optional: Optional<S>) => Optional<S> | Optional<S2>;
+
+  export function orElse<O extends Base, const O2 extends Base>(
     ...args:
       | readonly [optional: O, alternative: O2]
       | readonly [alternative: O2]
-  ):
-    | (O | O2)
-    | ((optional: Optional<Unwrap<O>>) => Optional<Unwrap<O>> | O2) => {
+  ): (O | O2) | ((optional: Optional<Unwrap<O>>) => Optional<Unwrap<O>> | O2) {
     switch (args.length) {
       case 2: {
         const [optional, alternative] = args;
@@ -375,19 +319,7 @@ export namespace Optional {
         return (optional: Optional<Unwrap<O>>) => orElse(optional, alternative);
       }
     }
-  }) as OrElseFnOverload;
-
-  type OrElseFnOverload = {
-    <O extends Base, const O2 extends Base>(
-      optional: O,
-      alternative: O2,
-    ): O | O2;
-
-    // Curried version
-    <S, S2>(
-      alternative: Optional<S2>,
-    ): (optional: Optional<S>) => Optional<S> | Optional<S2>;
-  };
+  }
 
   /**
    * Maps an {@link Optional}<S> to {@link Optional}<S2> by applying a function to a contained value.
@@ -407,26 +339,23 @@ export namespace Optional {
    * const noneValue = Optional.none;
    * const mappedNone = Optional.map(noneValue, x => x * 2);
    * console.log(Optional.isNone(mappedNone)); // true
-   *
-   * // Chaining maps
-   * const result = Optional.map(
-   *   Optional.map(Optional.some("hello"), s => s.toUpperCase()),
-   *   s => s.length
-   * );
-   * console.log(Optional.unwrap(result)); // 5
-   *
-   * // Curried version for use with pipe
-   * const doubler = Optional.map((x: number) => x * 2);
-   * const result2 = pipe(Optional.some(5)).map(doubler).value;
-   * console.log(Optional.unwrap(result2)); // 10
    * ```
    */
-  // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
-  export const map: MapFnOverload = (<O extends Base, S2>(
+  export function map<O extends Base, S2>(
+    optional: O,
+    mapFn: (value: Unwrap<O>) => S2,
+  ): Optional<S2>;
+
+  // Curried version
+  export function map<S, S2>(
+    mapFn: (value: S) => S2,
+  ): (optional: Optional<S>) => Optional<S2>;
+
+  export function map<O extends Base, S2>(
     ...args:
       | readonly [optional: O, mapFn: (value: Unwrap<O>) => S2]
       | readonly [mapFn: (value: Unwrap<O>) => S2]
-  ): Optional<S2> | ((optional: O) => Optional<S2>) => {
+  ): Optional<S2> | ((optional: O) => Optional<S2>) {
     switch (args.length) {
       case 2: {
         const [optional, mapFn] = args;
@@ -439,17 +368,7 @@ export namespace Optional {
         return (optional: O) => map(optional, mapFn);
       }
     }
-  }) as MapFnOverload;
-
-  type MapFnOverload = {
-    <O extends Base, S2>(
-      optional: O,
-      mapFn: (value: Unwrap<O>) => S2,
-    ): Optional<S2>;
-
-    // Curried version
-    <S, S2>(mapFn: (value: S) => S2): (optional: Optional<S>) => Optional<S2>;
-  };
+  }
 
   /**
    * Applies a function that returns an `Optional` to the value in an `Optional.Some`.
@@ -462,7 +381,6 @@ export namespace Optional {
    * @returns The result of applying the function, or `Optional.None`.
    * @example
    * ```typescript
-   * // Regular usage
    * const parseNumber = (s: string): Optional<number> => {
    *   const n = Number(s);
    *   return isNaN(n) ? Optional.none : Optional.some(n);
@@ -470,19 +388,23 @@ export namespace Optional {
    *
    * const result = Optional.flatMap(Optional.some("42"), parseNumber);
    * console.log(Optional.unwrap(result)); // 42
-   *
-   * // Curried usage for pipe composition
-   * const parser = Optional.flatMap(parseNumber);
-   * const result2 = pipe(Optional.some("42")).map(parser).value;
-   * console.log(Optional.unwrap(result2)); // 42
    * ```
    */
-  // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
-  export const flatMap: FlatMapFnOverload = (<O extends Base, S2>(
+  export function flatMap<O extends Base, S2>(
+    optional: O,
+    flatMapFn: (value: Unwrap<O>) => Optional<S2>,
+  ): Optional<S2>;
+
+  // Curried version
+  export function flatMap<S, S2>(
+    flatMapFn: (value: S) => Optional<S2>,
+  ): (optional: Optional<S>) => Optional<S2>;
+
+  export function flatMap<O extends Base, S2>(
     ...args:
       | readonly [optional: O, flatMapFn: (value: Unwrap<O>) => Optional<S2>]
       | readonly [flatMapFn: (value: Unwrap<O>) => Optional<S2>]
-  ): Optional<S2> | ((optional: O) => Optional<S2>) => {
+  ): Optional<S2> | ((optional: O) => Optional<S2>) {
     switch (args.length) {
       case 2: {
         const [optional, flatMapFn] = args;
@@ -494,19 +416,7 @@ export namespace Optional {
         return (optional: O) => flatMap(optional, flatMapFn);
       }
     }
-  }) as FlatMapFnOverload;
-
-  type FlatMapFnOverload = {
-    <O extends Base, S2>(
-      optional: O,
-      flatMapFn: (value: Unwrap<O>) => Optional<S2>,
-    ): Optional<S2>;
-
-    // Curried version
-    <S, S2>(
-      flatMapFn: (value: S) => Optional<S2>,
-    ): (optional: Optional<S>) => Optional<S2>;
-  };
+  }
 
   /**
    * Filters an `Optional` based on a predicate.
@@ -518,23 +428,26 @@ export namespace Optional {
    * @returns The filtered `Optional`.
    * @example
    * ```typescript
-   * // Regular usage
    * const someEven = Optional.some(4);
    * const filtered = Optional.filter(someEven, x => x % 2 === 0);
    * console.log(Optional.unwrap(filtered)); // 4
-   *
-   * // Curried usage for pipe composition
-   * const evenFilter = Optional.filter((x: number) => x % 2 === 0);
-   * const result = pipe(Optional.some(4)).map(evenFilter).value;
-   * console.log(Optional.unwrap(result)); // 4
    * ```
    */
-  // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
-  export const filter: FilterFnOverload = (<O extends Base>(
+  export function filter<O extends Base>(
+    optional: O,
+    predicate: (value: Unwrap<O>) => boolean,
+  ): Optional<Unwrap<O>>;
+
+  // Curried version
+  export function filter<S>(
+    predicate: (value: S) => boolean,
+  ): (optional: Optional<S>) => Optional<S>;
+
+  export function filter<O extends Base>(
     ...args:
       | readonly [optional: O, predicate: (value: Unwrap<O>) => boolean]
       | readonly [predicate: (value: Unwrap<O>) => boolean]
-  ): Optional<Unwrap<O>> | ((optional: O) => Optional<Unwrap<O>>) => {
+  ): Optional<Unwrap<O>> | ((optional: O) => Optional<Unwrap<O>>) {
     switch (args.length) {
       case 2: {
         const [optional, predicate] = args;
@@ -551,19 +464,7 @@ export namespace Optional {
         return (optional: O) => filter(optional, predicate);
       }
     }
-  }) as FilterFnOverload;
-
-  type FilterFnOverload = {
-    <O extends Base>(
-      optional: O,
-      predicate: (value: Unwrap<O>) => boolean,
-    ): Optional<Unwrap<O>>;
-
-    // Curried version
-    <S>(
-      predicate: (value: S) => boolean,
-    ): (optional: Optional<S>) => Optional<S>;
-  };
+  }
 
   /**
    * Unwraps an `Optional`, returning the contained value or throwing an error with the provided message.
@@ -574,23 +475,24 @@ export namespace Optional {
    * @throws Error with the provided message if the `Optional` is `Optional.None`.
    * @example
    * ```typescript
-   * // Regular usage
    * const some = Optional.some(42);
    * const value = Optional.expectToBe(some, "Value must exist");
    * console.log(value); // 42
-   *
-   * // Curried usage for pipe composition
-   * const getValue = Optional.expectToBe("Value must exist");
-   * const value2 = pipe(Optional.some(42)).map(getValue).value;
-   * console.log(value2); // 42
    * ```
    */
-  // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
-  export const expectToBe: ExpectToBeFnOverload = (<O extends Base>(
+  export function expectToBe<O extends Base>(
+    optional: O,
+    message: string,
+  ): Unwrap<O>;
+
+  // Curried version
+  export function expectToBe<S>(message: string): (optional: Optional<S>) => S;
+
+  export function expectToBe<O extends Base>(
     ...args:
       | readonly [optional: O, message: string]
       | readonly [message: string]
-  ): Unwrap<O> | ((optional: Optional<Unwrap<O>>) => Unwrap<O>) => {
+  ): Unwrap<O> | ((optional: Optional<Unwrap<O>>) => Unwrap<O>) {
     switch (args.length) {
       case 2: {
         const [optional, message] = args;
@@ -607,14 +509,7 @@ export namespace Optional {
           expectToBe(optional, message);
       }
     }
-  }) as ExpectToBeFnOverload;
-
-  type ExpectToBeFnOverload = {
-    <O extends Base>(optional: O, message: string): Unwrap<O>;
-
-    // Curried version
-    <S>(message: string): (optional: Optional<S>) => S;
-  };
+  }
 
   /**
    * Combines two `Optional` values into a single `Optional` containing a tuple.
@@ -655,39 +550,13 @@ export namespace Optional {
    * @returns `Optional.Some<NonNullable<T>>` if the value is not null or undefined, otherwise `Optional.None`.
    * @example
    * ```typescript
-   * // Basic nullable conversion
    * const value: string | null = "hello";
    * const optional = Optional.fromNullable(value);
    * console.log(Optional.unwrap(optional)); // "hello"
-   * console.log(Optional.isSome(optional)); // true
    *
-   * // Handling null values
    * const nullValue: string | null = null;
    * const noneOptional = Optional.fromNullable(nullValue);
    * console.log(Optional.isNone(noneOptional)); // true
-   *
-   * // Handling undefined values
-   * const undefinedValue: number | undefined = undefined;
-   * const alsoNone = Optional.fromNullable(undefinedValue);
-   * console.log(Optional.isNone(alsoNone)); // true
-   *
-   * // Common use case with API responses
-   * interface User {
-   *   name: string;
-   *   email?: string; // Optional field
-   * }
-   *
-   * const user: User = { name: "John" };
-   * const email = Optional.fromNullable(user.email);
-   * const emailDisplay = Optional.unwrapOr(email, "No email provided");
-   * console.log(emailDisplay); // "No email provided"
-   *
-   * // Chaining with other Optional operations
-   * const processNullableInput = (input: string | null) =>
-   *   Optional.fromNullable(input)
-   *     .map(Optional.map(s => s.trim()))
-   *     .map(Optional.filter(s => s.length > 0))
-   *     .map(Optional.unwrapOr("empty input"));
    * ```
    */
   export const fromNullable = <T,>(
@@ -709,35 +578,11 @@ export namespace Optional {
    * @returns The contained value if `Some`, otherwise `undefined`.
    * @example
    * ```typescript
-   * // Basic conversion
    * const some = Optional.some(42);
    * console.log(Optional.toNullable(some)); // 42
    *
    * const none = Optional.none;
    * console.log(Optional.toNullable(none)); // undefined
-   *
-   * // Interface with nullable APIs
-   * interface ApiResponse {
-   *   data?: string;
-   * }
-   *
-   * const optionalData: Optional<string> = processData();
-   * const response: ApiResponse = {
-   *   data: Optional.toNullable(optionalData)
-   * };
-   *
-   * // Converting back and forth
-   * const original: string | undefined = getValue();
-   * const optional = Optional.fromNullable(original);
-   * const processed = Optional.map(optional, s => s.toUpperCase());
-   * const result: string | undefined = Optional.toNullable(processed);
-   *
-   * // Useful in conditional logic
-   * const maybeUser = findUser(id);
-   * const userName = Optional.toNullable(maybeUser);
-   * if (userName !== undefined) {
-   *   console.log(`Found user: ${userName}`);
-   * }
    * ```
    */
   export const toNullable = <O extends Base>(

package/src/functional/pipe.mts

@@ -117,37 +117,27 @@ type MergeIntersection<T> = {
  *     .value; // number | undefined
  * ```
  */
-// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
-export const pipe: PipeFnOverload = (<const A,>(a: A) => {
+export function pipe<const A extends Optional.Base>(
+  a: A,
+): PipeWithMapOptional<A>;
+
+export function pipe<const A>(a: A): PipeWithMapNullable<A>;
+
+export function pipe<const A>(a: A): PipeImpl<A> {
   if (Optional.isOptional(a)) {
     return {
       value: a,
       map: (fn) => pipe(fn(a)),
       mapOptional: (fn) => pipe(Optional.map(a, fn)),
-    } satisfies PipeWithMapOptional<Optional.Base>;
+    };
   } else {
     return {
       value: a,
       map: (fn) => pipe(fn(a)),
       mapNullable: (fn) => pipe(a == null ? undefined : fn(a)),
-    } satisfies PipeWithMapNullable<A>;
+    };
   }
-}) as PipeFnOverload;
-
-/**
- * @internal
- * Overloaded function type for the pipe function.
- * Automatically selects the appropriate pipe type based on input:
- * - Optional types get PipeWithMapOptional
- * - All other types get PipeWithMapNullable
- * @template A The type of value being piped.
- */
-type PipeFnOverload = {
-  /** Creates a pipe for Optional values with mapOptional support. */
-  <const A extends Optional.Base>(a: A): PipeWithMapOptional<A>;
-  /** Creates a pipe for any other value type with mapNullable support. */
-  <const A>(a: A): PipeWithMapNullable<A>;
-};
+}
 
 /**
  * @internal
@@ -210,3 +200,18 @@ type PipeWithMapOptional<A extends Optional.Base> = MergeIntersection<
       ) => PipeBase<Optional<B>>;
     }>
 >;
+
+/** @internal */
+type Cast<T, U> = T & U;
+
+/** @internal */
+type PipeImpl<A> = Partial<
+  Readonly<{
+    value: A;
+    map: <B>(fn: (a: A) => B) => PipeBase<B>;
+    mapNullable: <B>(fn: (a: NonNullable<A>) => B) => PipeBase<B | undefined>;
+    mapOptional: <B>(
+      fn: (a: Optional.Unwrap<Cast<A, Optional.Base>>) => B,
+    ) => PipeBase<Optional<B>>;
+  }>
+>;