ts-data-forge 14.4.0 → 14.6.0

package/src/functional/async-result/impl/async-result-from-throwable.mts

@@ -0,0 +1,78 @@
+import { Result } from '../../result/index.mjs';
+import { type AsyncResult } from '../async-result.mjs';
+
+/**
+ * Wraps a function returning a `Promise` in an `AsyncResult`. Both a
+ * synchronous `throw` while calling `fn` and an asynchronous rejection of the
+ * returned Promise are caught, passed through `mapError`, and carried as
+ * `Err`.
+ *
+ * Passing `mapError` is what gives the error channel a concrete type `E`.
+ * Omitting it carries the thrown value through untouched, leaving the error
+ * channel as `unknown`.
+ *
+ * @example
+ *
+ * ```ts
+ * const success = await AsyncResult.fromThrowable(
+ *   () => Promise.resolve(2),
+ *   (error) => `failed: ${String(error)}`,
+ * );
+ *
+ * const failure = await AsyncResult.fromThrowable(
+ *   (): Promise<number> => {
+ *     throw new Error('boom');
+ *   },
+ *   (error) => (isError(error) ? error.message : 'unknown'),
+ * );
+ *
+ * assert.deepStrictEqual(success, Result.ok(2));
+ *
+ * assert.deepStrictEqual(failure, Result.err('boom'));
+ *
+ * // Without `mapError`, the thrown value is carried as-is.
+ * const untyped = await AsyncResult.fromThrowable(
+ *   (): Promise<number> => {
+ *     throw new Error('boom');
+ *   },
+ * );
+ *
+ * assert.isTrue(Result.isErr(untyped));
+ * ```
+ *
+ * @template S The type of the success value.
+ * @template E The type of the error value.
+ * @param fn The function to execute; it may throw synchronously or return a
+ *   rejecting Promise.
+ * @param mapError The function applied to the thrown value or rejection
+ *   reason to produce the error value. Omit it to carry the thrown value as
+ *   `unknown`.
+ * @returns An `AsyncResult<S, E>` containing either the resolved value or the
+ *   mapped error.
+ */
+export function fromThrowable<S>(fn: () => Promise<S>): AsyncResult<S, unknown>;
+
+export function fromThrowable<S, E>(
+  fn: () => Promise<S>,
+  mapError: (error: unknown) => E,
+): AsyncResult<S, E>;
+
+export function fromThrowable<S, E>(
+  fn: () => Promise<S>,
+  mapError?: (error: unknown) => E,
+): AsyncResult<S, E> | AsyncResult<S, unknown> {
+  return mapError === undefined
+    ? fromThrowableImpl(fn, (error: unknown) => error)
+    : fromThrowableImpl(fn, mapError);
+}
+
+const fromThrowableImpl = async <S, E>(
+  fn: () => Promise<S>,
+  mapError: (error: unknown) => E,
+): AsyncResult<S, E> => {
+  try {
+    return Result.ok(await fn());
+  } catch (error) {
+    return Result.err(mapError(error));
+  }
+};

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

@@ -0,0 +1,84 @@
+import { Result } from '../../result/index.mjs';
+import { type AsyncResult } from '../async-result.mjs';
+
+/**
+ * Maps an `AsyncResult<S, E>` to `AsyncResult<S, E2>` by applying a function
+ * to the error value. The mapping function may be synchronous or return a
+ * `Promise`; both are handled transparently. If the `AsyncResult` resolves to
+ * `Ok`, the original `Ok` 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`.
+ *
+ * @example
+ *
+ * ```ts
+ * const errValue = AsyncResult.fromPromise(
+ *   Promise.reject(new Error('boom')),
+ *   () => 'failure',
+ * );
+ *
+ * const uppercased = await AsyncResult.mapErr(errValue, (error) =>
+ *   error.toUpperCase(),
+ * );
+ *
+ * assert.deepStrictEqual(uppercased, Result.err('FAILURE'));
+ * ```
+ *
+ * @template S The type of the success value.
+ * @template E The type of the error value of the input.
+ * @template E2 The type of the error value returned by the mapping function.
+ * @param asyncResult The `AsyncResult` to map.
+ * @param mapFn The function to apply to the error value if present.
+ * @returns A new `AsyncResult<S, E2>`.
+ */
+export function mapErr<S, E, E2>(
+  asyncResult: AsyncResult<S, E>,
+  mapFn: (error: E) => E2 | Promise<E2>,
+): AsyncResult<S, E2>;
+
+// Curried version
+//
+// Unlike `Result.mapErr`, the returned function can simply be generic over
+// `S`: 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 mapErr<E, E2>(
+  mapFn: (error: E) => E2 | Promise<E2>,
+): <S>(asyncResult: AsyncResult<S, E>) => AsyncResult<S, E2>;
+
+export function mapErr<S, E, E2>(
+  ...args:
+    | readonly [
+        asyncResult: AsyncResult<S, E>,
+        mapFn: (error: E) => E2 | Promise<E2>,
+      ]
+    | readonly [mapFn: (error: E) => E2 | Promise<E2>]
+):
+  | AsyncResult<S, E2>
+  | ((asyncResult: AsyncResult<S, E>) => AsyncResult<S, E2>) {
+  switch (args.length) {
+    case 2: {
+      // Direct version: first argument is asyncResult
+      const [asyncResult, mapFn] = args;
+
+      return mapErrImpl(asyncResult, mapFn);
+    }
+
+    case 1: {
+      // Curried version: first argument is mapping function
+      const [mapFn] = args;
+
+      return (asyncResult: AsyncResult<S, E>) => mapErrImpl(asyncResult, mapFn);
+    }
+  }
+}
+
+const mapErrImpl = async <S, E, E2>(
+  asyncResult: AsyncResult<S, E>,
+  mapFn: (error: E) => E2 | Promise<E2>,
+): AsyncResult<S, E2> => {
+  const result = await asyncResult;
+
+  return Result.isOk(result) ? result : Result.err(await mapFn(result.value));
+};

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

@@ -0,0 +1,94 @@
+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

@@ -0,0 +1,42 @@
+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

@@ -0,0 +1,7 @@
+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

@@ -0,0 +1,51 @@
+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

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

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

@@ -0,0 +1,290 @@
+import { isError } from '@sindresorhus/is';
+import { AsyncResult as AsyncResultFromEntryPoint } from '../entry-point.mjs';
+import { expectType } from '../expect-type.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: ${String(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: ${String(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/index.mts

@@ -1,3 +1,4 @@
+export * from './async-result/index.mjs';
 export * from './match.mjs';
 export * from './optional/index.mjs';
 export * from './pipe.mjs';

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

@@ -6,6 +6,7 @@ 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';