ts-data-forge 14.6.4 → 14.7.0

package/src/functional/async-result/impl/async-result-map.mts

@@ -1,94 +0,0 @@
-import { Result } from '../../result/index.mjs';
-import { type AsyncResult } from '../async-result.mjs';
-
-/**
- * Maps an `AsyncResult<S, E>` to `AsyncResult<S2, E>` by applying a function
- * to the success value. The mapping function may be synchronous or return a
- * `Promise`; both are handled transparently. If the `AsyncResult` resolves to
- * `Err`, the original `Err` is passed through and the function is not called.
- *
- * If `mapFn` throws or returns a rejecting Promise, the rejection propagates
- * as-is — it is **not** caught and converted into an `Err`. `map` performs no
- * implicit error conversion; write a fallible step as
- * `AsyncResult.flatMap` combined with `AsyncResult.fromThrowable` instead, so
- * that the error type stays explicit.
- *
- * @example
- *
- * ```ts
- * const okValue = AsyncResult.fromPromise(
- *   Promise.resolve(5),
- *   () => 'failed',
- * );
- *
- * const doubled = await AsyncResult.map(okValue, (value) => value * 2);
- *
- * assert.deepStrictEqual(doubled, Result.ok(10));
- *
- * const double = AsyncResult.map((value: number) => value * 2);
- *
- * const curried = await double(
- *   AsyncResult.fromPromise(Promise.resolve(21), () => 'failed'),
- * );
- *
- * assert.deepStrictEqual(curried, Result.ok(42));
- * ```
- *
- * @template S The type of the success value of the input.
- * @template S2 The type of the success value returned by the mapping
- *   function.
- * @template E The type of the error value.
- * @param asyncResult The `AsyncResult` to map.
- * @param mapFn The function to apply to the success value if present.
- * @returns A new `AsyncResult<S2, E>`.
- */
-export function map<S, S2, E>(
-  asyncResult: AsyncResult<S, E>,
-  mapFn: (value: S) => Promise<S2> | S2,
-): AsyncResult<S2, E>;
-
-// Curried version
-//
-// Unlike `Result.map`, the returned function can simply be generic over `E`:
-// an `AsyncResult` is a `Promise`, not a discriminated union, so there is no
-// literal-narrowing problem that would require the whole-result generic
-// trick used by the synchronous combinators.
-export function map<S, S2>(
-  mapFn: (value: S) => Promise<S2> | S2,
-): <E>(asyncResult: AsyncResult<S, E>) => AsyncResult<S2, E>;
-
-export function map<S, S2, E>(
-  ...args:
-    | readonly [
-        asyncResult: AsyncResult<S, E>,
-        mapFn: (value: S) => Promise<S2> | S2,
-      ]
-    | readonly [mapFn: (value: S) => Promise<S2> | S2]
-):
-  | AsyncResult<S2, E>
-  | ((asyncResult: AsyncResult<S, E>) => AsyncResult<S2, E>) {
-  switch (args.length) {
-    case 2: {
-      // Direct version: first argument is asyncResult
-      const [asyncResult, mapFn] = args;
-
-      return mapImpl(asyncResult, mapFn);
-    }
-
-    case 1: {
-      // Curried version
-      const [mapFn] = args;
-
-      return (asyncResult: AsyncResult<S, E>) => mapImpl(asyncResult, mapFn);
-    }
-  }
-}
-
-const mapImpl = async <S, S2, E>(
-  asyncResult: AsyncResult<S, E>,
-  mapFn: (value: S) => Promise<S2> | S2,
-): AsyncResult<S2, E> => {
-  const result = await asyncResult;
-
-  return Result.isErr(result) ? result : Result.ok(await mapFn(result.value));
-};

package/src/functional/async-result/impl/async-result-unwrap-or.mts

@@ -1,42 +0,0 @@
-import { Result } from '../../result/index.mjs';
-import { type AsyncResult } from '../async-result.mjs';
-
-/**
- * Unwraps an `AsyncResult`, resolving to the success value or a default value
- * if it resolves to `Err`.
- *
- * @example
- *
- * ```ts
- * const okValue = AsyncResult.fromPromise(
- *   Promise.resolve(10),
- *   () => 'failed',
- * );
- *
- * const errValue = AsyncResult.fromPromise(
- *   Promise.reject(new Error('boom')),
- *   () => 'failed',
- * );
- *
- * assert.isTrue((await AsyncResult.unwrapOr(okValue, 0)) === 10);
- *
- * assert.isTrue((await AsyncResult.unwrapOr(errValue, 0)) === 0);
- * ```
- *
- * @template S The type of the success value.
- * @template E The type of the error value.
- * @template D The type of the default value.
- * @param asyncResult The `AsyncResult` to unwrap.
- * @param defaultValue The value to resolve to if `asyncResult` resolves to
- *   `Err`.
- * @returns A Promise of the success value if `Ok`, otherwise of
- *   `defaultValue`.
- */
-export const unwrapOr = async <S, E, D>(
-  asyncResult: AsyncResult<S, E>,
-  defaultValue: D,
-): Promise<D | S> => {
-  const result = await asyncResult;
-
-  return Result.isOk(result) ? result.value : defaultValue;
-};

package/src/functional/async-result/impl/index.mts

@@ -1,7 +0,0 @@
-export * from './async-result-flat-map.mjs';
-export * from './async-result-from-promise.mjs';
-export * from './async-result-from-throwable.mjs';
-export * from './async-result-map-err.mjs';
-export * from './async-result-map.mjs';
-export * from './async-result-unwrap-or.mjs';
-export * from './types.mjs';

package/src/functional/async-result/impl/types.mts

@@ -1,51 +0,0 @@
-import { type Err, type Ok } from '../../../types.mjs';
-import { type UnknownResult } from '../../result/index.mjs';
-import { type AsyncResult } from '../async-result.mjs';
-
-/**
- * Base type for any `AsyncResult`, used for generic constraints. Represents
- * an `AsyncResult` with unknown success and error types.
- */
-export type UnknownAsyncResult = AsyncResult<unknown, unknown>;
-
-/**
- * Extracts the success value type `S` from a `Result.Ok<S>`, or from an
- * `AsyncResult` resolving to one. Distributes over unions, so an
- * `Ok<S> | Err<E>` union resolves to `S`.
- *
- * @template R The `Result` or `AsyncResult` type to unwrap.
- */
-export type UnwrapOk<R extends UnknownAsyncResult | UnknownResult> =
-  UnwrapOkImpl<SyncResultOf<R>>;
-
-/**
- * Extracts the error value type `E` from a `Result.Err<E>`, or from an
- * `AsyncResult` resolving to one. Distributes over unions, so an
- * `Ok<S> | Err<E>` union resolves to `E`.
- *
- * @template R The `Result` or `AsyncResult` type to unwrap.
- */
-export type UnwrapErr<R extends UnknownAsyncResult | UnknownResult> =
-  UnwrapErrImpl<SyncResultOf<R>>;
-
-/**
- * @template R The `Result` or `AsyncResult` type.
- * @internal
- * Resolves an `AsyncResult` to its `Result`, leaving a plain `Result`
- * unchanged. Distributive.
- */
-type SyncResultOf<R> = R extends Promise<infer P> ? P : R;
-
-/**
- * @template R The `Result` type to unwrap.
- * @internal
- * Distributive extraction of the `Ok` value type.
- */
-type UnwrapOkImpl<R> = R extends Ok<infer S> ? S : never;
-
-/**
- * @template R The `Result` type to unwrap.
- * @internal
- * Distributive extraction of the `Err` value type.
- */
-type UnwrapErrImpl<R> = R extends Err<infer E> ? E : never;

package/src/functional/async-result/index.mts

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

package/src/functional/async-result.test.mts

@@ -1,291 +0,0 @@
-import { isError } from '@sindresorhus/is';
-import { AsyncResult as AsyncResultFromEntryPoint } from '../entry-point.mjs';
-import { expectType } from '../expect-type.mjs';
-import { unknownToString } from '../others/index.mjs';
-import { AsyncResult } from './async-result/index.mjs';
-import { Result } from './result/index.mjs';
-
-// Fixtures are created through functions so that the success/error types stay
-// unions instead of being narrowed to literal types by const inference.
-const okFixture = (value: number): AsyncResult<number, string> =>
-  Promise.resolve(Result.ok(value));
-
-const errFixture = (message: string): AsyncResult<number, string> =>
-  Promise.resolve(Result.err(message));
-
-describe('AsyncResult test', () => {
-  describe('fromPromise', () => {
-    test('resolved promise becomes Ok', async () => {
-      const result = await AsyncResult.fromPromise(
-        Promise.resolve(42),
-        (error) => `mapped: ${unknownToString(error)}`,
-      );
-
-      assert.isTrue(Result.isOk(result));
-
-      assert.deepStrictEqual(result, Result.ok(42));
-    });
-
-    test('rejected promise becomes Err with mapError applied', async () => {
-      const result = await AsyncResult.fromPromise(
-        Promise.reject(new Error('boom')),
-        (error) => (isError(error) ? error.message : 'unknown'),
-      );
-
-      assert.isTrue(Result.isErr(result));
-
-      assert.deepStrictEqual(result, Result.err('boom'));
-    });
-
-    test('resolved promise becomes Ok when mapError is omitted', async () => {
-      const result = await AsyncResult.fromPromise(Promise.resolve(42));
-
-      assert.deepStrictEqual(result, Result.ok(42));
-
-      expectType<typeof result, Result<number, unknown>>('=');
-    });
-
-    test('rejection reason is carried as-is when mapError is omitted', async () => {
-      const error = new Error('boom');
-
-      const result = await AsyncResult.fromPromise(
-        Promise.reject(error).then(() => 42),
-      );
-
-      assert.isTrue(Result.isErr(result));
-
-      assert.deepStrictEqual(result, Result.err(error));
-    });
-  });
-
-  describe('fromThrowable', () => {
-    test('resolved async function becomes Ok', async () => {
-      const result = await AsyncResult.fromThrowable(
-        () => Promise.resolve('data'),
-        (error) => `mapped: ${unknownToString(error)}`,
-      );
-
-      assert.isTrue(Result.isOk(result));
-
-      assert.deepStrictEqual(result, Result.ok('data'));
-    });
-
-    test('synchronous throw becomes Err with mapError applied', async () => {
-      const result = await AsyncResult.fromThrowable(
-        (): Promise<number> => {
-          throw new Error('sync failure');
-        },
-        (error) => (isError(error) ? error.message : 'unknown'),
-      );
-
-      assert.isTrue(Result.isErr(result));
-
-      assert.deepStrictEqual(result, Result.err('sync failure'));
-    });
-
-    test('async rejection becomes Err with mapError applied', async () => {
-      const result = await AsyncResult.fromThrowable(
-        () => Promise.reject(new Error('async failure')),
-        (error) => (isError(error) ? error.message : 'unknown'),
-      );
-
-      assert.isTrue(Result.isErr(result));
-
-      assert.deepStrictEqual(result, Result.err('async failure'));
-    });
-
-    test('synchronous throw is carried as-is when mapError is omitted', async () => {
-      const error = new Error('sync failure');
-
-      const result = await AsyncResult.fromThrowable((): Promise<number> => {
-        throw error;
-      });
-
-      assert.deepStrictEqual(result, Result.err(error));
-
-      expectType<typeof result, Result<number, unknown>>('=');
-    });
-
-    test('async rejection is carried as-is when mapError is omitted', async () => {
-      const error = new Error('async failure');
-
-      const result = await AsyncResult.fromThrowable(() =>
-        Promise.reject(error).then(() => 42),
-      );
-
-      assert.deepStrictEqual(result, Result.err(error));
-    });
-  });
-
-  describe('map', () => {
-    test('maps Ok value with a synchronous function', async () => {
-      const result = await AsyncResult.map(okFixture(5), (value) => value * 2);
-
-      assert.deepStrictEqual(result, Result.ok(10));
-    });
-
-    test('maps Ok value with an asynchronous function', async () => {
-      const result = await AsyncResult.map(okFixture(5), (value) =>
-        Promise.resolve(value * 3),
-      );
-
-      assert.deepStrictEqual(result, Result.ok(15));
-    });
-
-    test('passes Err through unchanged', async () => {
-      let mut_called = false;
-
-      const result = await AsyncResult.map(errFixture('failure'), (value) => {
-        mut_called = true;
-
-        return value * 2;
-      });
-
-      assert.deepStrictEqual(result, Result.err('failure'));
-
-      assert.isFalse(mut_called);
-    });
-
-    test('curried version maps Ok value', async () => {
-      const double = AsyncResult.map((value: number) => value * 2);
-
-      const result = await double(okFixture(21));
-
-      assert.deepStrictEqual(result, Result.ok(42));
-    });
-
-    test('curried version passes Err through unchanged', async () => {
-      const double = AsyncResult.map((value: number) => value * 2);
-
-      const result = await double(errFixture('failure'));
-
-      assert.deepStrictEqual(result, Result.err('failure'));
-    });
-  });
-
-  describe('mapErr', () => {
-    test('maps Err value with a synchronous function', async () => {
-      const result = await AsyncResult.mapErr(errFixture('failure'), (error) =>
-        error.toUpperCase(),
-      );
-
-      assert.deepStrictEqual(result, Result.err('FAILURE'));
-    });
-
-    test('maps Err value with an asynchronous function', async () => {
-      const result = await AsyncResult.mapErr(
-        errFixture('failure'),
-        (message) => Promise.resolve(message.length),
-      );
-
-      assert.deepStrictEqual(result, Result.err(7));
-    });
-
-    test('passes Ok through unchanged', async () => {
-      let mut_called = false;
-
-      const result = await AsyncResult.mapErr(okFixture(1), (error) => {
-        mut_called = true;
-
-        return error.toUpperCase();
-      });
-
-      assert.deepStrictEqual(result, Result.ok(1));
-
-      assert.isFalse(mut_called);
-    });
-
-    test('curried version maps Err value', async () => {
-      const upper = AsyncResult.mapErr((error: string) => error.toUpperCase());
-
-      const result = await upper(errFixture('failure'));
-
-      assert.deepStrictEqual(result, Result.err('FAILURE'));
-    });
-  });
-
-  describe('flatMap', () => {
-    test('chains with a function returning a Result', async () => {
-      const result = await AsyncResult.flatMap(okFixture(4), (value) =>
-        value > 0 ? Result.ok(value * 10) : Result.err('non-positive'),
-      );
-
-      assert.deepStrictEqual(result, Result.ok(40));
-    });
-
-    test('chains with a function returning an AsyncResult', async () => {
-      const result = await AsyncResult.flatMap(okFixture(4), (value) =>
-        AsyncResult.fromPromise(Promise.resolve(value + 1), () => 'failed'),
-      );
-
-      assert.deepStrictEqual(result, Result.ok(5));
-    });
-
-    test('chains into Err returned by the function', async () => {
-      const result = await AsyncResult.flatMap(
-        okFixture(-1),
-        (value): Result<number, string> =>
-          value > 0 ? Result.ok(value * 10) : Result.err('non-positive'),
-      );
-
-      assert.deepStrictEqual(result, Result.err('non-positive'));
-    });
-
-    test('short-circuits on Err without calling the function', async () => {
-      let mut_called = false;
-
-      const result = await AsyncResult.flatMap(
-        errFixture('failure'),
-        (value) => {
-          mut_called = true;
-
-          return Result.ok(value * 2);
-        },
-      );
-
-      assert.deepStrictEqual(result, Result.err('failure'));
-
-      assert.isFalse(mut_called);
-    });
-
-    test('curried version chains with a function returning a Result', async () => {
-      const validate = AsyncResult.flatMap(
-        (value: number): Result<number, string> =>
-          value > 0 ? Result.ok(value) : Result.err('non-positive'),
-      );
-
-      const passed = await validate(okFixture(7));
-
-      const failed = await validate(okFixture(-7));
-
-      assert.deepStrictEqual(passed, Result.ok(7));
-
-      assert.deepStrictEqual(failed, Result.err('non-positive'));
-    });
-  });
-
-  describe('unwrapOr', () => {
-    test('returns the success value for Ok', async () => {
-      const value = await AsyncResult.unwrapOr(okFixture(10), 0);
-
-      expect(value).toBe(10);
-    });
-
-    test('returns the default value for Err', async () => {
-      const value = await AsyncResult.unwrapOr(errFixture('failure'), 0);
-
-      expect(value).toBe(0);
-    });
-  });
-
-  describe('entry point', () => {
-    test('AsyncResult is exported from the package entry point', async () => {
-      const result = await AsyncResultFromEntryPoint.fromPromise(
-        Promise.resolve(1),
-        () => 'failed',
-      );
-
-      assert.deepStrictEqual(result, Result.ok(1));
-    });
-  });
-});

package/src/functional/match.mts

@@ -1,193 +0,0 @@
-import {
-  type ReadonlyRecord,
-  type RelaxedExclude,
-  type TypeEq,
-  type UnknownRecord,
-  type ValueOf,
-} from 'ts-type-forge';
-import { expectType } from '../expect-type.mjs';
-import { keyIsIn } from '../guard/index.mjs';
-
-/**
- * Type-safe pattern matching function for string-based discriminated unions.
- *
- * Provides compile-time guarantees for exhaustive case handling when working
- * with literal string unions. Automatically enforces completeness checking when
- * all cases are covered, and requires a default value when cases are
- * incomplete.
- *
- * ## Key Features:
- *
- * - **Exhaustive Matching**: When all cases of a literal union are handled, no
- *   default value is needed
- * - **Partial Matching**: When cases are incomplete or working with general
- *   string types, a default value is required
- * - **Type Safety**: Prevents extra cases and ensures only valid keys are used
- * - **Strict Property Checking**: Rejects objects with unexpected properties
- *
- * @example
- *
- * ```ts
- * type Status = 'draft' | 'review' | 'published';
- *
- * const status: Status = 'draft';
- *
- * const message = match<
- *   Status,
- *   Readonly<{ draft: string; review: string; published: string }>
- * >(status, {
- *   draft: 'Work in progress',
- *   review: 'Awaiting feedback',
- *   published: 'Complete',
- * });
- *
- * assert.isTrue(message === 'Work in progress');
- * ```
- *
- * @param target - The value to match against
- * @param cases - Object mapping possible values to their corresponding results
- * @param defaultValue - Fallback value (required when not all cases are
- *   covered)
- * @returns The matched result or default value
- */
-export function match<
-  const Case extends string,
-  const R extends ReadonlyRecord<Case, unknown>,
->(target: Case, cases: StrictPropertyCheck<R, Case>): R[Case];
-
-export function match<
-  const Case extends string,
-  const R extends UnknownRecord,
-  const D,
->(
-  target: Case,
-  cases: StrictPropertyCheck<R, Case>,
-  defaultValue: IsLiteralUnionFullyCovered<Case, R> extends true ? never : D,
-): ValueOf<R> | D;
-
-export function match<
-  const Case extends string,
-  const R extends UnknownRecord,
-  const D,
->(
-  ...args:
-    | readonly [target: Case, cases: R]
-    | readonly [target: Case, cases: R, defaultValue: D]
-): ValueOf<R> | D {
-  switch (args.length) {
-    case 2: {
-      const [target, cases] = args;
-
-      return cases[target];
-    }
-
-    case 3: {
-      const [target, cases, defaultValue] = args;
-
-      return keyIsIn(target, cases) ? cases[target] : defaultValue;
-    }
-  }
-}
-
-/**
- * @template T The object type to check.
- * @template ExpectedKeys The union of string literal types representing the
- *   allowed keys.
- * @internal
- * Helper type to ensure that an object `T` only contains keys specified in `ExpectedKeys`.
- * If `T` has any keys not in `ExpectedKeys`, this type resolves to `never`.
- */
-type StrictPropertyCheck<T, ExpectedKeys extends PropertyKey> =
-  RelaxedExclude<keyof T, ExpectedKeys> extends never ? T : never;
-
-/**
- * @template Case A union of string literal types representing the possible
- *   cases.
- * @template R A record type.
- * @internal
- * Helper type to check if all cases in `Case` union are fully covered by keys in `R`.
- * This checks bidirectional coverage: all Case members are in R, and no extra keys.
- */
-type AllCasesCovered<Case extends PropertyKey, R> =
-  TypeEq<Case, keyof R> extends true ? true : false;
-
-expectType<AllCasesCovered<'a' | 'b', Readonly<{ a: 1; b: 2 }>>, true>('=');
-
-expectType<AllCasesCovered<'a' | 'b' | 'c', Readonly<{ a: 1; b: 2 }>>, false>(
-  '=',
-);
-
-expectType<AllCasesCovered<'a' | 'b', Readonly<{ a: 1; b: 2; c: 3 }>>, false>(
-  '=',
-);
-
-expectType<AllCasesCovered<string, ReadonlyRecord<string, string>>, true>('=');
-
-/**
- * @template Case A union of string literal types.
- * @template R A record type.
- * @internal
- * Helper type to check if Case is a literal union type and all cases are covered.
- */
-type IsLiteralUnionFullyCovered<
-  Case extends PropertyKey,
-  R extends UnknownRecord,
-> =
-  TypeEq<IsLiteralType<Case>, true> extends true
-    ? AllCasesCovered<Case, R>
-    : false;
-
-expectType<
-  IsLiteralUnionFullyCovered<'a' | 'b', Readonly<{ a: 1; b: 2 }>>,
-  true
->('=');
-
-expectType<
-  IsLiteralUnionFullyCovered<'a' | 'b' | 'c', Readonly<{ a: 1; b: 2 }>>,
-  false
->('=');
-
-expectType<
-  IsLiteralUnionFullyCovered<'a' | 'b', Readonly<{ a: 1; b: 2; c: 3 }>>,
-  false
->('=');
-
-expectType<
-  IsLiteralUnionFullyCovered<string, ReadonlyRecord<string, string>>,
-  false
->('=');
-
-expectType<
-  // eslint-disable-next-line @typescript-eslint/no-redundant-type-constituents
-  IsLiteralUnionFullyCovered<'a' | 'b' | string, Readonly<{ a: 1; b: 2 }>>,
-  false
->('=');
-
-/**
- * @template T The PropertyKey type to check.
- * @returns `true` if `T` is a literal type, `false` otherwise.
- * @internal
- * Helper type to determine if a given PropertyKey `T` is a literal type (e.g., 'a', 1)
- * or a general type (e.g., string, number).
- */
-type IsLiteralType<T extends PropertyKey> = string extends T
-  ? false
-  : number extends T
-    ? false
-    : symbol extends T
-      ? false
-      : true;
-
-expectType<IsLiteralType<'a' | 'b'>, true>('=');
-
-expectType<IsLiteralType<'a'>, true>('=');
-
-expectType<IsLiteralType<string>, false>('=');
-
-expectType<IsLiteralType<number>, false>('=');
-
-expectType<IsLiteralType<1>, true>('=');
-
-expectType<IsLiteralType<number | 'aa'>, false>('=');
-
-expectType<IsLiteralType<'aa' | 32>, true>('=');