ts-data-forge 14.6.4 → 14.7.0

package/src/functional/match.test.mts

@@ -1,180 +0,0 @@
-import { expectType } from '../expect-type.mjs';
-import { match } from './match.mjs';
-
-describe(match, () => {
-  type Direction = 'E' | 'N' | 'S' | 'W';
-
-  // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion
-  const direction: Direction = 'N' as Direction;
-
-  test('literal union', () => {
-    const res = match(direction, {
-      E: 2,
-      N: 3,
-      S: 4,
-      W: 5,
-    });
-
-    expectType<typeof res, 2 | 3 | 4 | 5>('=');
-
-    expect(res).toBe(3);
-  });
-
-  test('Literal union with missing key - requires default', () => {
-    const res = match(
-      direction,
-      {
-        E: 2,
-        S: 4,
-        W: 5,
-      },
-      999,
-    );
-
-    expectType<typeof res, 2 | 4 | 5 | 999>('=');
-
-    expect(res).toBe(999);
-  });
-
-  test('Literal union with missing key - 2-arg form should cause type error', () => {
-    // @ts-expect-error Cannot use 2-argument form when not all cases are covered
-    const res = match(direction, {
-      E: 2,
-      S: 4,
-      W: 5,
-    });
-
-    expectType<typeof res, unknown>('=');
-
-    expect(res).toBeUndefined();
-  });
-
-  test('Missing key cases with string - requires default', () => {
-    const res = match(
-      direction as string,
-      {
-        E: 2,
-        S: 4,
-        W: 5,
-      },
-      'default',
-    );
-
-    expectType<typeof res, 2 | 4 | 5 | 'default'>('=');
-
-    expect(res).toBe('default');
-  });
-
-  test('String type always requires default even with all keys', () => {
-    const res = match(
-      direction as string,
-      {
-        E: 2,
-        N: 3,
-        S: 4,
-        W: 5,
-      },
-      'default',
-    );
-
-    expectType<typeof res, 2 | 3 | 4 | 5 | 'default'>('=');
-
-    expect(res).toBe(3);
-  });
-
-  test('A case with excess properties', () => {
-    // @ts-expect-error excess properties
-    const res = match(direction, {
-      E: 2,
-      N: 3,
-      S: 4,
-      W: 5,
-      X: 0,
-    });
-
-    expectType<typeof res, 2 | 3 | 4 | 5>('=');
-
-    expect(res).toBe(3);
-  });
-
-  test('with default case - all keys present should cause type error', () => {
-    const res = match(
-      direction,
-      {
-        E: 2,
-        N: 3,
-        S: 4,
-        W: 5,
-      },
-      // @ts-expect-error When all cases are covered, default value should not be allowed
-      999,
-    );
-
-    expect(res).toBe(3);
-  });
-
-  test('all keys present without default - should work correctly', () => {
-    const res = match(direction, {
-      E: 2,
-      N: 3,
-      S: 4,
-      W: 5,
-    });
-
-    expectType<typeof res, 2 | 3 | 4 | 5>('=');
-
-    expect(res).toBe(3);
-  });
-
-  test('with default case - missing key', () => {
-    const res = match(
-      direction,
-      {
-        E: 2,
-        S: 4,
-        W: 5,
-      },
-      999,
-    );
-
-    expectType<typeof res, 2 | 4 | 5 | 999>('=');
-
-    expect(res).toBe(999);
-  });
-
-  test('with default case - string key', () => {
-    const res = match(
-      direction as string,
-      {
-        E: 2,
-        N: 3,
-        S: 4,
-        W: 5,
-      },
-      'default',
-    );
-
-    expectType<typeof res, 2 | 3 | 4 | 5 | 'default'>('=');
-
-    expect(res).toBe(3);
-  });
-
-  test('with default case - string key missing', () => {
-    const unknownDirection = 'X' as string;
-
-    const res = match(
-      unknownDirection,
-      {
-        E: 2,
-        N: 3,
-        S: 4,
-        W: 5,
-      },
-      'default',
-    );
-
-    expectType<typeof res, 2 | 3 | 4 | 5 | 'default'>('=');
-
-    expect(res).toBe('default');
-  });
-});

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

@@ -1,18 +0,0 @@
-export * from './optional-expect-to-be.mjs';
-export * from './optional-filter.mjs';
-export * from './optional-flat-map.mjs';
-export * from './optional-from-nullable.mjs';
-export * from './optional-is-none.mjs';
-export * from './optional-is-optional.mjs';
-export * from './optional-is-some.mjs';
-export * from './optional-map.mjs';
-export * from './optional-match.mjs';
-export * from './optional-none.mjs';
-export * from './optional-or-else.mjs';
-export * from './optional-some.mjs';
-export * from './optional-to-nullable.mjs';
-export * from './optional-unwrap-or.mjs';
-export * from './optional-unwrap-throw.mjs';
-export * from './optional-unwrap.mjs';
-export * from './optional-zip.mjs';
-export * from './types.mjs';

package/src/functional/optional/impl/optional-expect-to-be.mts

@@ -1,75 +0,0 @@
-import { type Optional, type UnknownOptional } from '../optional.mjs';
-import { isSome } from './optional-is-some.mjs';
-import { unwrap } from './optional-unwrap.mjs';
-import { type Unwrap } from './types.mjs';
-
-/**
- * Unwraps an `Optional`, returning the contained value or throwing an error
- * with the provided message.
- *
- * @example
- *
- * ```ts
- * const optionalValue = Optional.some('data');
- *
- * assert.isTrue(
- *   Optional.expectToBe(optionalValue, 'value expected') === 'data',
- * );
- *
- * const expectValue = Optional.expectToBe('missing optional');
- *
- * const throwTest = (): void => {
- *   expectValue(Optional.none);
- * };
- *
- * assert.throws(throwTest, /missing optional/u);
- *
- * assert.isTrue(expectValue(Optional.some('present')) === 'present');
- * ```
- *
- * @template O The `UnknownOptional` type to unwrap.
- * @param optional The `Optional` to unwrap.
- * @param message The error message to throw if the `Optional` is
- *   `None`.
- * @returns The contained value if `Some`.
- * @throws Error with the provided message if the `Optional` is
- *   `None`.
- */
-export function expectToBe<O extends UnknownOptional>(
-  optional: O,
-  message: string,
-): Unwrap<O>;
-
-// Curried version
-export function expectToBe(message: string): <O>(optional: Optional<O>) => O;
-
-export function expectToBe<O extends UnknownOptional>(
-  ...args: readonly [optional: O, message: string] | readonly [message: string]
-): Unwrap<O> | ((optional: Optional<Unwrap<O>>) => Unwrap<O>) {
-  switch (args.length) {
-    case 2: {
-      const [optional, message] = args;
-
-      return expectToBeImpl(optional, message);
-    }
-
-    case 1: {
-      // Curried version: first argument is message
-      const [message] = args;
-
-      return (optional: Optional<Unwrap<O>>): Unwrap<O> =>
-        expectToBeImpl(optional, message);
-    }
-  }
-}
-
-const expectToBeImpl = <O extends UnknownOptional>(
-  optional: O,
-  message: string,
-): Unwrap<O> => {
-  if (isSome(optional)) {
-    return unwrap(optional);
-  }
-
-  throw new Error(message);
-};

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

@@ -1,78 +0,0 @@
-import { type Optional, type UnknownOptional } from '../optional.mjs';
-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';
-
-/**
- * Filters an `Optional` based on a predicate. If the `Optional` is `Some` and
- * the predicate returns true, returns the original `Optional`. Otherwise
- * returns `None`.
- *
- * @example
- *
- * ```ts
- * const even = Optional.filter(Optional.some(4), (value) => value % 2 === 0);
- *
- * const odd = Optional.filter(Optional.some(3), (value) => value % 2 === 0);
- *
- * assert.deepStrictEqual(even, Optional.some(4));
- *
- * assert.deepStrictEqual(odd, Optional.none);
- *
- * const filterEven = Optional.filter((value: number) => value % 2 === 0);
- *
- * assert.deepStrictEqual(filterEven(Optional.some(6)), Optional.some(6));
- *
- * assert.deepStrictEqual(filterEven(Optional.some(5)), Optional.none);
- * ```
- *
- * @template O The input `UnknownOptional` type.
- * @param optional The `Optional` to filter.
- * @param predicate The predicate function.
- * @returns The filtered `Optional`.
- */
-export function filter<O extends UnknownOptional>(
-  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 UnknownOptional>(
-  ...args:
-    | readonly [optional: O, predicate: (value: Unwrap<O>) => boolean]
-    | readonly [predicate: (value: Unwrap<O>) => boolean]
-): Optional<Unwrap<O>> | ((optional: O) => Optional<Unwrap<O>>) {
-  switch (args.length) {
-    case 2: {
-      const [optional, predicate] = args;
-
-      return filterImpl(optional, predicate);
-    }
-
-    case 1: {
-      // Curried version: first argument is predicate function
-      const [predicate] = args;
-
-      return (optional: O) => filterImpl(optional, predicate);
-    }
-  }
-}
-
-const filterImpl = <O extends UnknownOptional>(
-  optional: O,
-  predicate: (value: Unwrap<O>) => boolean,
-): Optional<Unwrap<O>> => {
-  if (isSome(optional)) {
-    const value = unwrap(optional);
-
-    return predicate(value) ? some(value) : none;
-  }
-
-  return none;
-};

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

@@ -1,75 +0,0 @@
-import { type Optional, type UnknownOptional } from '../optional.mjs';
-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 = Num.safeParseInt(input);
- *
- *   return Result.isErr(num) ? Optional.none : Optional.some(num.value);
- * };
- *
- * 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

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

@@ -1,26 +0,0 @@
-import { type UnknownOptional } from '../optional.mjs';
-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
- *   expectType<typeof optionalValue, 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

@@ -1,30 +0,0 @@
-import { hasKey, isRecord } from '../../../guard/index.mjs';
-import { type Optional } from '../optional.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' } as const;
- *
- * assert.isTrue(Optional.isOptional(maybeOptional));
- *
- * assert.isFalse(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) &&
-  hasKey(maybeOptional, '$$tag') &&
-  ((maybeOptional.$$tag === SomeTypeTagName &&
-    hasKey(maybeOptional, 'value')) ||
-    maybeOptional.$$tag === NoneTypeTagName);

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

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

@@ -1,90 +0,0 @@
-import { type Optional, type UnknownOptional } from '../optional.mjs';
-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
-//
-// The returned function is generic over the *whole* optional, mirroring the
-// direct overload above, rather than fixing its parameter to `Optional<S>`.
-// Fixing it makes the curried form unusable from a caller that is itself
-// generic over the optional: with `S` bound to `Unwrap<O>` at currying time
-// the parameter becomes `Optional<Unwrap<O>>`, and TypeScript cannot show a
-// bare `O extends UnknownOptional` is assignable to that — although every
-// concrete instantiation of `O` is.
-//
-// The conditional is what keeps the check: `O` is inferred from the argument
-// and its value type still has to satisfy `S`, so mapping a `(s: string) =>
-// …` over an `Optional<number>` stays an error. The cost is the message it
-// produces — "not assignable to `never`" rather than naming the two optionals.
-export function map<S, S2>(
-  mapFn: (value: S) => S2,
-): <O extends UnknownOptional>(
-  optional: Unwrap<O> extends S ? O : never,
-) => 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;