ts-data-forge 3.3.0 → 4.0.0

package/src/functional/optional/impl/optional-flat-map.mts

@@ -0,0 +1,67 @@
+import { isSome } from './optional-is-some.mjs';
+import { none } from './optional-none.mjs';
+import { unwrap } from './optional-unwrap.mjs';
+import { type Unwrap } from './types.mjs';
+
+/**
+ * Applies a function that returns an `Optional` to the value in an
+ * `Some`. If the input is `None`, returns `None`.
+ * This is the monadic bind operation for `Optional`.
+ *
+ * @example
+ *
+ * ```ts
+ * const parseNumber = (input: string): Optional<number> => {
+ *   const num = Number.parseInt(input, 10);
+ *   return Number.isNaN(num) ? Optional.none : Optional.some(num);
+ * };
+ *
+ * const parsed = Optional.flatMap(Optional.some('10'), parseNumber);
+ *
+ * assert.deepStrictEqual(parsed, Optional.some(10));
+ *
+ * const flatMapParse = Optional.flatMap(parseNumber);
+ *
+ * assert.deepStrictEqual(flatMapParse(Optional.some('5')), Optional.some(5));
+ * assert.deepStrictEqual(flatMapParse(Optional.some('invalid')), Optional.none);
+ * ```
+ *
+ * @template O The input `UnknownOptional` type.
+ * @template S2 The value type of the `Optional` returned by the function.
+ * @param optional The `Optional` to flat map.
+ * @param flatMapFn The function to apply that returns an `Optional`.
+ * @returns The result of applying the function, or `None`.
+ */
+export function flatMap<O extends UnknownOptional, 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 UnknownOptional, S2>(
+  ...args:
+    | readonly [optional: O, flatMapFn: (value: Unwrap<O>) => Optional<S2>]
+    | readonly [flatMapFn: (value: Unwrap<O>) => Optional<S2>]
+): Optional<S2> | ((optional: O) => Optional<S2>) {
+  switch (args.length) {
+    case 2: {
+      const [optional, flatMapFn] = args;
+      return flatMapImpl(optional, flatMapFn);
+    }
+
+    case 1: {
+      // Curried version
+      const [flatMapFn] = args;
+      return (optional: O) => flatMapImpl(optional, flatMapFn);
+    }
+  }
+}
+
+const flatMapImpl = <O extends UnknownOptional, S2>(
+  optional: O,
+  flatMapFn: (value: Unwrap<O>) => Optional<S2>,
+): Optional<S2> => (isSome(optional) ? flatMapFn(unwrap(optional)) : none);

package/src/functional/optional/impl/optional-from-nullable.mts

@@ -0,0 +1,28 @@
+import { none } from './optional-none.mjs';
+import { some } from './optional-some.mjs';
+
+/**
+ * Converts a nullable value to an `Optional`.
+ *
+ * This is the primary way to lift nullable values (null or undefined) into
+ * the Optional type system. The function treats both `null` and `undefined`
+ * as empty values, converting them to `None`.
+ *
+ * @example
+ *
+ * ```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 `Some<NonNullable<T>>` if the value is not null or
+ *   undefined, otherwise `None`.
+ */
+export const fromNullable = <T,>(
+  value: T | null | undefined,
+): Optional<NonNullable<T>> => (value == null ? none : some(value));

package/src/functional/optional/impl/optional-is-none.mts

@@ -0,0 +1,25 @@
+import { NoneTypeTagName } from './tag.mjs';
+import { type NarrowToNone } from './types.mjs';
+
+/**
+ * Checks if an {@link Optional} is {@link 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 UnknownOptional} type to check.
+ * @param optional The {@link Optional} to check.
+ * @returns `true` if the {@link Optional} is {@link None}, `false`
+ *   otherwise.
+ */
+export const isNone = <O extends UnknownOptional>(
+  optional: O,
+): optional is NarrowToNone<O> => optional.$$tag === NoneTypeTagName;

package/src/functional/optional/impl/optional-is-optional.mts

@@ -0,0 +1,27 @@
+import { isRecord } from '../../../guard/index.mjs';
+import { NoneTypeTagName, SomeTypeTagName } from './tag.mjs';
+
+/**
+ * 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`.
+ */
+export const isOptional = (
+  maybeOptional: unknown,
+): maybeOptional is Optional<unknown> =>
+  isRecord(maybeOptional) &&
+  Object.hasOwn(maybeOptional, '$$tag') &&
+  ((maybeOptional['$$tag'] === SomeTypeTagName &&
+    Object.hasOwn(maybeOptional, 'value')) ||
+    maybeOptional['$$tag'] === NoneTypeTagName);

package/src/functional/optional/impl/optional-is-some.mts

@@ -0,0 +1,25 @@
+import { SomeTypeTagName } from './tag.mjs';
+import { type NarrowToSome } from './types.mjs';
+
+/**
+ * Checks if an {@link Optional} is {@link 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 UnknownOptional} type to check.
+ * @param optional The {@link Optional} to check.
+ * @returns `true` if the {@link Optional} is {@link Some}, `false`
+ *   otherwise.
+ */
+export const isSome = <O extends UnknownOptional>(
+  optional: O,
+): optional is NarrowToSome<O> => optional.$$tag === SomeTypeTagName;

package/src/functional/optional/impl/optional-map.mts

@@ -0,0 +1,69 @@
+import { isSome } from './optional-is-some.mjs';
+import { none } from './optional-none.mjs';
+import { some } from './optional-some.mjs';
+import { unwrap } from './optional-unwrap.mjs';
+import { type Unwrap } from './types.mjs';
+
+/**
+ * Maps an {@link Optional}<S> to {@link Optional}<S2> by applying a function to
+ * a contained value. If the {@link Optional} is {@link None}, it
+ * returns {@link Optional.none}. Otherwise, it applies the `mapFn` to the
+ * value in `Some` and returns a new `Some` with the result.
+ *
+ * @example
+ *
+ * ```ts
+ * const numberOptional = Optional.some(21);
+ * const mapped = Optional.map(numberOptional, (value) => value * 2);
+ *
+ * assert.deepStrictEqual(mapped, Optional.some(42));
+ *
+ * const mapToLength = Optional.map((text: string) => text.length);
+ *
+ * assert.deepStrictEqual(mapToLength(Optional.some('abc')), Optional.some(3));
+ * assert.deepStrictEqual(mapToLength(Optional.none), Optional.none);
+ * ```
+ *
+ * @template O The input `UnknownOptional` type.
+ * @template S2 The type of the value returned by the mapping function.
+ * @param optional The `Optional` to map.
+ * @param mapFn The function to apply to the value if it exists.
+ * @returns A new `Optional<S2>` resulting from the mapping, or
+ *   `None` if the input was `None`.
+ */
+export function map<O extends UnknownOptional, 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 UnknownOptional, S2>(
+  ...args:
+    | readonly [optional: O, mapFn: (value: Unwrap<O>) => S2]
+    | readonly [mapFn: (value: Unwrap<O>) => S2]
+): Optional<S2> | ((optional: O) => Optional<S2>) {
+  switch (args.length) {
+    case 2: {
+      const [optional, mapFn] = args;
+      return mapImpl(optional, mapFn);
+    }
+    case 1: {
+      // Curried version: first argument is mapping function
+      const [mapFn] = args;
+      return (optional: O) => mapImpl(optional, mapFn);
+    }
+  }
+}
+
+const mapImpl = <O extends UnknownOptional, S2>(
+  optional: O,
+  mapFn: (value: Unwrap<O>) => S2,
+): Optional<S2> =>
+  isSome(optional)
+    ? // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+      some(mapFn(unwrap(optional)!))
+    : none;

package/src/functional/optional/impl/optional-none.mts

@@ -0,0 +1,17 @@
+import { NoneTypeTagName } from './tag.mjs';
+
+/**
+ * The singleton instance representing {@link None} (an empty
+ * Optional).
+ *
+ * @example
+ *
+ * ```ts
+ * const someValue = Optional.some({ id: 1 });
+ * const noneValue = Optional.none;
+ *
+ * assert.ok(Optional.isSome(someValue));
+ * assert.ok(Optional.isNone(noneValue));
+ * ```
+ */
+export const none: None = { $$tag: NoneTypeTagName } as const;

package/src/functional/optional/impl/optional-or-else.mts

@@ -0,0 +1,73 @@
+import { isNone } from './optional-is-none.mjs';
+import { type Unwrap } from './types.mjs';
+
+/**
+ * Returns the `Optional` if it is `Some`, otherwise returns the alternative.
+ *
+ * Provides a way to chain Optional operations with fallback values. This is
+ * particularly useful for implementing default behavior or cascading lookups.
+ * Supports both direct usage and curried form for functional composition.
+ *
+ * @example
+ *
+ * ```ts
+ * const preferred = Optional.some('primary');
+ * const fallback = Optional.some('secondary');
+ * const noneValue = Optional.none as Optional<string>;
+ *
+ * assert.deepStrictEqual(Optional.orElse(preferred, fallback), preferred);
+ * assert.deepStrictEqual(Optional.orElse(noneValue, fallback), fallback);
+ *
+ * const orElseFallback = Optional.orElse(Optional.some('default'));
+ *
+ * assert.deepStrictEqual(orElseFallback(Optional.none), Optional.some('default'));
+ * assert.deepStrictEqual(
+ *   orElseFallback(Optional.some('value')),
+ *   Optional.some('value'),
+ * );
+ * ```
+ *
+ * @template O The input `UnknownOptional` type.
+ * @param optional The `Optional` to check.
+ * @param alternative The alternative `Optional` to return if the first is
+ *   `None`.
+ * @returns The first `Optional` if `Some`, otherwise the alternative.
+ */
+export function orElse<
+  O extends UnknownOptional,
+  const O2 extends UnknownOptional,
+>(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 UnknownOptional,
+  const O2 extends UnknownOptional,
+>(
+  ...args: readonly [optional: O, alternative: O2] | readonly [alternative: O2]
+): (O | O2) | ((optional: Optional<Unwrap<O>>) => Optional<Unwrap<O>> | O2) {
+  switch (args.length) {
+    case 2: {
+      const [optional, alternative] = args;
+      return orElseImpl(optional, alternative);
+    }
+
+    case 1: {
+      // Curried version
+      const [alternative] = args;
+      return (optional: Optional<Unwrap<O>>) =>
+        orElseImpl(optional, alternative);
+    }
+  }
+}
+
+const orElseImpl = <
+  O extends UnknownOptional,
+  const O2 extends UnknownOptional,
+>(
+  optional: O,
+  alternative: O2,
+): O | O2 => (isNone(optional) ? alternative : optional);

package/src/functional/optional/impl/optional-some.mts

@@ -0,0 +1,23 @@
+import { SomeTypeTagName } from './tag.mjs';
+
+/**
+ * Creates an {@link 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 Some}.
+ * @returns An {@link Some}<S> containing the value.
+ */
+export const some = <S,>(value: S): Some<S> => ({
+  $$tag: SomeTypeTagName,
+  value,
+});

package/src/functional/optional/impl/optional-to-nullable.mts

@@ -0,0 +1,31 @@
+import { isSome } from './optional-is-some.mjs';
+import { unwrap } from './optional-unwrap.mjs';
+import { type Unwrap } from './types.mjs';
+
+/**
+ * Converts an `Optional` to a nullable value.
+ *
+ * This function extracts the value from an Optional, returning `undefined`
+ * 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.
+ *
+ * @example
+ *
+ * ```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 `UnknownOptional` type to convert.
+ * @param optional The `Optional` to convert.
+ * @returns The contained value if `Some`, otherwise `undefined`.
+ */
+export const toNullable = <O extends UnknownOptional>(
+  optional: O,
+): Unwrap<O> | undefined => (isSome(optional) ? unwrap(optional) : undefined);

package/src/functional/optional/impl/optional-unwrap-or.mts

@@ -0,0 +1,64 @@
+import { unwrap } from './optional-unwrap.mjs';
+import { type Unwrap } from './types.mjs';
+
+/**
+ * Unwraps an `Optional`, returning the contained value or a default value if
+ * it's `None`.
+ *
+ * Supports both direct usage and curried form for functional composition.
+ * This is often preferred over `unwrap()` when you have a sensible fallback
+ * value.
+ *
+ * @example
+ *
+ * ```ts
+ * const withValue = Optional.some(5);
+ * const withoutValue = Optional.none as Optional<number>;
+ *
+ * assert(Optional.unwrapOr(withValue, 0) === 5);
+ * assert(Optional.unwrapOr(withoutValue, 0) === 0);
+ *
+ * const unwrapWithDefault = Optional.unwrapOr(10);
+ *
+ * assert(unwrapWithDefault(Optional.some(3)) === 3);
+ * assert(unwrapWithDefault(Optional.none) === 10);
+ * ```
+ *
+ * @template O The `UnknownOptional` type to unwrap.
+ * @template D The type of the default value.
+ * @param optional The `Optional` to unwrap.
+ * @param defaultValue The value to return if `optional` is `None`.
+ * @returns The contained value if `Some`, otherwise `defaultValue`.
+ */
+export function unwrapOr<O extends UnknownOptional, 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 UnknownOptional, D>(
+  ...args: readonly [optional: O, defaultValue: D] | readonly [defaultValue: D]
+): (D | Unwrap<O>) | ((optional: Optional<Unwrap<O>>) => D | Unwrap<O>) {
+  switch (args.length) {
+    case 2: {
+      const [optional, defaultValue] = args;
+      return unwrapOrImpl(optional, defaultValue);
+    }
+
+    case 1: {
+      // Curried version: first argument is default value
+      const [defaultValue] = args;
+      return (optional: Optional<Unwrap<O>>) =>
+        unwrapOrImpl(optional, defaultValue);
+    }
+  }
+}
+
+const unwrapOrImpl = <O extends UnknownOptional, D>(
+  optional: O,
+  defaultValue: D,
+): D | Unwrap<O> => unwrap(optional) ?? defaultValue;

package/src/functional/optional/impl/optional-unwrap-throw.mts

@@ -0,0 +1,39 @@
+import { isSome } from './optional-is-some.mjs';
+import { type Unwrap } from './types.mjs';
+
+/**
+ * Unwraps an `Optional`, returning the contained value. Throws an error if
+ * the `Optional` is `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.
+ *
+ * @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 `UnknownOptional` type to unwrap.
+ * @param optional The `Optional` to unwrap.
+ * @returns The contained value if `Some`.
+ * @throws {Error} Error with message "`unwrapThrow()` has failed because it
+ *   is `None`" if the `Optional` is `None`.
+ */
+export const unwrapThrow = <O extends UnknownOptional>(
+  optional: O,
+): Unwrap<O> => {
+  if (isSome(optional)) {
+    // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+    return optional.value as Unwrap<O>;
+  }
+
+  throw new Error('`unwrapThrow()` has failed because it is `None`');
+};

package/src/functional/optional/impl/optional-unwrap.mts

@@ -0,0 +1,41 @@
+import { isSome } from './optional-is-some.mjs';
+import { type Unwrap } from './types.mjs';
+
+/**
+ * Unwraps an `Optional`, returning the contained value or `undefined` if
+ * empty.
+ *
+ * This function provides a safe way to extract values from Optionals without
+ * throwing exceptions. It has overloaded behavior based on the type:
+ *
+ * - For `Some<T>`: Always returns `T` (guaranteed by type system)
+ * - For general `Optional<T>`: Returns `T | undefined`
+ *
+ * @example
+ *
+ * ```ts
+ * const someString = Optional.some('text');
+ * const noneString = Optional.none as Optional<string>;
+ *
+ * assert(Optional.unwrap(someString) === 'text');
+ * assert(Optional.unwrap(noneString) === undefined);
+ * ```
+ *
+ * @template O The `UnknownOptional` type to unwrap.
+ * @param optional The `Optional` to unwrap.
+ * @returns The contained value if `Some`, otherwise `undefined`.
+ */
+export function unwrap<O extends Some<unknown>>(optional: O): Unwrap<O>;
+
+export function unwrap<O extends UnknownOptional>(
+  optional: O,
+): Unwrap<O> | undefined;
+
+export function unwrap<O extends UnknownOptional>(
+  optional: O,
+): Unwrap<O> | undefined {
+  return isSome(optional)
+    ? // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+      (optional.value as Unwrap<O>)
+    : undefined;
+}

package/src/functional/optional/impl/optional-zip.mts

@@ -0,0 +1,40 @@
+import { isSome } from './optional-is-some.mjs';
+import { none } from './optional-none.mjs';
+import { some } from './optional-some.mjs';
+
+/**
+ * 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`.
+ */
+export const zip = <A, const B>(
+  optionalA: Optional<A>,
+  optionalB: Optional<B>,
+): Optional<readonly [A, B]> =>
+  isSome(optionalA) && isSome(optionalB)
+    ? some([optionalA.value, optionalB.value] as const)
+    : none;

package/src/functional/optional/impl/tag.mts

@@ -0,0 +1,6 @@
+/** @internal String literal tag to identify the 'Some' variant of Optional. */
+export const SomeTypeTagName: Some<unknown>['$$tag'] =
+  'ts-data-forge::Optional.some';
+
+/** @internal String literal tag to identify the 'None' variant of Optional. */
+export const NoneTypeTagName: None['$$tag'] = 'ts-data-forge::Optional.none';

package/src/functional/optional/impl/types.mts

@@ -0,0 +1,28 @@
+/**
+ * Extracts the value type `S` from an {@link Some}<S>. If the
+ * {@link Optional} is {@link None}, resolves to `never`.
+ *
+ * @template O The {@link UnknownOptional} type to unwrap.
+ */
+export type Unwrap<O extends UnknownOptional> =
+  O extends Some<infer S> ? S : never;
+
+/**
+ * Narrows an {@link UnknownOptional} type to {@link Some}<S> if it is a
+ * {@link Some}. If the {@link Optional} is {@link None}, resolves to `never`.
+ *
+ * @template O The {@link UnknownOptional} type to narrow.
+ */
+export type NarrowToSome<O extends UnknownOptional> = O extends None
+  ? never
+  : O;
+
+/**
+ * Narrows an {@link UnknownOptional} type to {@link None} if it is a
+ * {@link None}. If the {@link Optional} is {@link Some}<S>, resolves to never.
+ *
+ * @template O The {@link UnknownOptional} type to narrow.
+ */
+export type NarrowToNone<O extends UnknownOptional> = O extends None
+  ? O
+  : never;

package/src/functional/optional/index.mts

@@ -0,0 +1 @@
+export * as Optional from './impl/index.mjs';