ts-data-forge 14.6.4 → 14.7.0

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

@@ -1,108 +0,0 @@
-import { type UnknownOptional } from '../optional.mjs';
-import { isSome } from './optional-is-some.mjs';
-import { unwrap } from './optional-unwrap.mjs';
-import { type Unwrap } from './types.mjs';
-
-/**
- * Folds an {@link Optional} into a plain value by applying one of two case
- * handlers: `some` if the {@link Optional} contains a value, `none`
- * otherwise. This is the function form of pattern matching on an
- * {@link Optional}.
- *
- * Unlike {@link Optional.map}, the result is not wrapped in an
- * {@link Optional} — both branches produce the final value directly.
- *
- * @example
- *
- * ```ts
- * const doubledOrZero = Optional.match(Optional.some(21), {
- *   some: (value) => value * 2,
- *   none: () => 0,
- * });
- *
- * assert.deepStrictEqual(doubledOrZero, 42);
- *
- * const matcher = Optional.match({
- *   some: (value: number) => `value: ${value}`,
- *   none: () => 'none',
- * });
- *
- * assert.deepStrictEqual(matcher(Optional.some(3)), 'value: 3');
- *
- * assert.deepStrictEqual(matcher(Optional.none), 'none');
- * ```
- *
- * @template O The input `UnknownOptional` type.
- * @template S2 The type returned by the `some` case.
- * @template N2 The type returned by the `none` case.
- * @param optional The `Optional` to match on.
- * @param cases An object with a `some` handler receiving the contained value
- *   and a `none` handler receiving nothing.
- * @returns The value produced by whichever case handler was applied.
- */
-export function match<O extends UnknownOptional, S2, N2>(
-  optional: O,
-  cases: Readonly<{
-    some: (value: Unwrap<O>) => S2;
-    none: () => N2;
-  }>,
-): N2 | S2;
-
-// Curried version
-//
-// The returned function is generic over the *whole* optional, mirroring the
-// direct overload above; see the comment on the curried overload of
-// `Optional.map` for why the parameter is a conditional type instead of a
-// plain `Optional<S>`.
-export function match<S, S2, N2>(
-  cases: Readonly<{
-    some: (value: S) => S2;
-    none: () => N2;
-  }>,
-): <O extends UnknownOptional>(
-  optional: Unwrap<O> extends S ? O : never,
-) => N2 | S2;
-
-export function match<O extends UnknownOptional, S2, N2>(
-  ...args:
-    | readonly [
-        optional: O,
-        cases: Readonly<{
-          some: (value: Unwrap<O>) => S2;
-          none: () => N2;
-        }>,
-      ]
-    | readonly [
-        cases: Readonly<{
-          some: (value: Unwrap<O>) => S2;
-          none: () => N2;
-        }>,
-      ]
-): N2 | S2 | ((optional: O) => N2 | S2) {
-  switch (args.length) {
-    case 2: {
-      const [optional, cases] = args;
-
-      return matchImpl(optional, cases);
-    }
-
-    case 1: {
-      // Curried version: the only argument is the case handlers
-      const [cases] = args;
-
-      return (optional: O) => matchImpl(optional, cases);
-    }
-  }
-}
-
-const matchImpl = <O extends UnknownOptional, S2, N2>(
-  optional: O,
-  cases: Readonly<{
-    some: (value: Unwrap<O>) => S2;
-    none: () => N2;
-  }>,
-): N2 | S2 =>
-  isSome(optional)
-    ? // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-      cases.some(unwrap(optional)!)
-    : cases.none();

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

@@ -1,20 +0,0 @@
-import { type None } from '../../../types.mjs';
-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.isTrue(Optional.isSome(someValue));
- *
- * assert.isTrue(Optional.isNone(noneValue));
- * ```
- */
-export const none: None = { $$tag: NoneTypeTagName } as const;

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

@@ -1,83 +0,0 @@
-import { type Optional, type UnknownOptional } from '../optional.mjs';
-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<O2>(
-  alternative: Optional<O2>,
-): <O>(optional: Optional<O>) => Optional<O> | Optional<O2>;
-
-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

@@ -1,27 +0,0 @@
-import { type Some } from '../../../types.mjs';
-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.isTrue(Optional.isSome(someValue));
- *
- * assert.isTrue(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 = <const S,>(value: S): Some<S> =>
-  ({
-    $$tag: SomeTypeTagName,
-    value,
-  }) as const;

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

@@ -1,34 +0,0 @@
-import { type UnknownOptional } from '../optional.mjs';
-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.isTrue(Optional.toNullable(someNumber) === 42);
- *
- * assert.isTrue(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

@@ -1,70 +0,0 @@
-import { type Optional, type UnknownOptional } from '../optional.mjs';
-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.isTrue(Optional.unwrapOr(withValue, 0) === 5);
- *
- * assert.isTrue(Optional.unwrapOr(withoutValue, 0) === 0);
- *
- * const unwrapWithDefault = Optional.unwrapOr(10);
- *
- * assert.isTrue(unwrapWithDefault(Optional.some(3)) === 3);
- *
- * assert.isTrue(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<D>(
-  defaultValue: D,
-): <O>(optional: Optional<O>) => D | O;
-
-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

@@ -1,41 +0,0 @@
-import { type UnknownOptional } from '../optional.mjs';
-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.isTrue(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

@@ -1,45 +0,0 @@
-import { type Some } from '../../../types.mjs';
-import { type UnknownOptional } from '../optional.mjs';
-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.isTrue(Optional.unwrap(someString) === 'text');
- *
- * assert.isTrue(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

@@ -1,44 +0,0 @@
-import { type Optional } from '../optional.mjs';
-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.isTrue(Optional.isSome(zipped));
- *
- * if (Optional.isSome(zipped)) {
- *   const expected: readonly [string, number] = ['left', 1] as const;
- *
- *   assert.deepStrictEqual(zipped.value, expected);
- * }
- *
- * const missing = Optional.zip(
- *   Optional.some('value'),
- *   // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion
- *   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

@@ -1,8 +0,0 @@
-/** @internal String literal tag to identify the 'Some' variant of Optional. */
-import { type None, type Some } from '../../../types.mjs';
-
-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

@@ -1,31 +0,0 @@
-import { type None, type Some } from '../../../types.mjs';
-import { type UnknownOptional } from '../optional.mjs';
-
-/**
- * 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

@@ -1 +0,0 @@
-export * from './optional.mjs';

package/src/functional/optional/optional.mts

@@ -1,19 +0,0 @@
-import { type None, type Some } from '../../types.mjs';
-
-/**
- * Represents an optional value that can either be `Some` (containing a value)
- * or `None` (empty).
- *
- * @template S The type of the value that might be present.
- */
-export type Optional<S> = None | Some<S>;
-
-/**
- * Base type for any {@link Optional}, used for generic constraints. Represents
- * an {@link Optional} with an unknown value type.
- */
-export type UnknownOptional = None | Some<unknown>;
-
-export type { None, Some } from '../../types.mjs';
-
-export * as Optional from './impl/index.mjs';