ts-data-forge 14.3.0 → 14.5.0

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';

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

@@ -0,0 +1,108 @@
+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.test.mts

@@ -800,4 +800,83 @@ describe('Optional test', () => {
       expect(Optional.unwrap(inner)).toBe(42);
     });
   });
+
+  describe('match', () => {
+    test('should apply the some case for Some', () => {
+      const result = Optional.match(Optional.some(21), {
+        some: (value) => value * 2,
+        none: () => 0,
+      });
+
+      expectType<typeof result, number>('=');
+
+      assert.deepStrictEqual(result, 42);
+    });
+
+    test('should apply the none case for None', () => {
+      const result = Optional.match(Optional.none, {
+        some: () => 'some',
+        none: () => 'none',
+      });
+
+      assert.deepStrictEqual(result, 'none');
+    });
+
+    test('should support Optional union inputs', () => {
+      const optional: Optional<number> = Optional.some(3);
+
+      const result = Optional.match(optional, {
+        some: (value) => `value: ${value}`,
+        none: () => 'none',
+      });
+
+      expectType<typeof result, string>('=');
+
+      assert.deepStrictEqual(result, 'value: 3');
+    });
+
+    test('curried version should work', () => {
+      const matcher = Optional.match({
+        some: (value: number) => `value: ${value}`,
+        none: () => 'none',
+      });
+
+      const result = matcher(Optional.some(3));
+
+      expectType<typeof result, string>('=');
+
+      assert.deepStrictEqual(result, 'value: 3');
+
+      assert.deepStrictEqual(matcher(Optional.none), 'none');
+    });
+
+    test('curried version should compose with Array.map and pipe', () => {
+      const matcher = Optional.match({
+        some: (value: number) => `some:${value}`,
+        none: () => 'none',
+      });
+
+      const optionals: readonly Optional<number>[] = [
+        Optional.some(1),
+        Optional.none,
+      ] as const;
+
+      assert.deepStrictEqual(optionals.map(matcher), ['some:1', 'none']);
+
+      const single: Optional<number> = Optional.some(3);
+
+      assert.deepStrictEqual(pipe(single).map(matcher).value, 'some:3');
+    });
+
+    test('should apply the some case for Some(undefined)', () => {
+      const makeOptional = (): Optional<undefined> => Optional.some(undefined);
+
+      const result = Optional.match(makeOptional(), {
+        some: (value) => `some: ${String(value)}`,
+        none: () => 'none',
+      });
+
+      assert.deepStrictEqual(result, 'some: undefined');
+    });
+  });
 });

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

@@ -2,6 +2,7 @@ export * from './result-err.mjs';
 export * from './result-expect-to-be.mjs';
 export * from './result-flat-map.mjs';
 export * from './result-fold.mjs';
+export * from './result-from-optional.mjs';
 export * from './result-from-promise.mjs';
 export * from './result-from-throwable.mjs';
 export * from './result-is-err.mjs';
@@ -9,8 +10,11 @@ export * from './result-is-ok.mjs';
 export * from './result-is-result.mjs';
 export * from './result-map-err.mjs';
 export * from './result-map.mjs';
+export * from './result-match.mjs';
 export * from './result-ok.mjs';
 export * from './result-or-else.mjs';
+export * from './result-safe-try.mjs';
+export * from './result-safe-unwrap.mjs';
 export * from './result-swap.mjs';
 export * from './result-to-optional.mjs';
 export * from './result-unwrap-err-or.mjs';

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

@@ -0,0 +1,80 @@
+import { Optional, type UnknownOptional } from '../../optional/index.mjs';
+import { type Result } from '../result.mjs';
+import { err } from './result-err.mjs';
+import { ok } from './result-ok.mjs';
+
+/**
+ * Converts an {@link Optional} to a `Result` (the inverse of
+ * {@link Result.toOptional}, and the equivalent of Rust's `Option::ok_or`).
+ *
+ * If the {@link Optional} is `Some`, returns `Ok` with the contained value.
+ * If it is `None`, returns `Err` with the provided error value.
+ *
+ * @example
+ *
+ * ```ts
+ * assert.deepStrictEqual(
+ *   Result.fromOptional(Optional.some(42), 'missing'),
+ *   Result.ok(42),
+ * );
+ *
+ * assert.deepStrictEqual(
+ *   Result.fromOptional(Optional.none, 'missing'),
+ *   Result.err('missing'),
+ * );
+ *
+ * const withMissingError = Result.fromOptional('missing');
+ *
+ * assert.deepStrictEqual(withMissingError(Optional.some(1)), Result.ok(1));
+ *
+ * assert.deepStrictEqual(
+ *   withMissingError(Optional.none),
+ *   Result.err('missing'),
+ * );
+ * ```
+ *
+ * @template O The input `UnknownOptional` type.
+ * @template E The type of the error value used for the `None` case.
+ * @param optional The `Optional` to convert.
+ * @param error The error value to use if the `Optional` is `None`.
+ * @returns `Ok` with the contained value, or `Err` with `error`.
+ */
+export function fromOptional<O extends UnknownOptional, const E>(
+  optional: O,
+  error: E,
+): Result<Optional.Unwrap<O>, E>;
+
+// Curried version
+export function fromOptional<const E>(
+  error: E,
+): <O extends UnknownOptional>(optional: O) => Result<Optional.Unwrap<O>, E>;
+
+export function fromOptional<O extends UnknownOptional, const E>(
+  ...args: readonly [optional: O, error: E] | readonly [error: E]
+):
+  | Result<Optional.Unwrap<O>, E>
+  | ((optional: O) => Result<Optional.Unwrap<O>, E>) {
+  switch (args.length) {
+    case 2: {
+      const [optional, error] = args;
+
+      return fromOptionalImpl(optional, error);
+    }
+
+    case 1: {
+      // Curried version: the only argument is the error value
+      const [error] = args;
+
+      return (optional: O) => fromOptionalImpl(optional, error);
+    }
+  }
+}
+
+const fromOptionalImpl = <O extends UnknownOptional, E>(
+  optional: O,
+  error: E,
+): Result<Optional.Unwrap<O>, E> =>
+  Optional.isSome(optional)
+    ? // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+      ok(Optional.unwrap(optional)!)
+    : err(error);

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

@@ -0,0 +1,108 @@
+import { type UnknownResult } from '../result.mjs';
+import { isOk } from './result-is-ok.mjs';
+import { type UnwrapErr, type UnwrapOk } from './types.mjs';
+
+/**
+ * Folds a `Result` into a plain value by applying one of two case handlers:
+ * `ok` if the `Result` is `Ok`, `err` otherwise. This is the function form of
+ * pattern matching on a `Result`.
+ *
+ * Unlike {@link Result.fold}, which maps both sides and returns another
+ * `Result`, `match` unwraps: both branches produce the final value directly.
+ *
+ * @example
+ *
+ * ```ts
+ * const doubledOrZero = Result.match(Result.ok(21), {
+ *   ok: (value) => value * 2,
+ *   err: () => 0,
+ * });
+ *
+ * assert.deepStrictEqual(doubledOrZero, 42);
+ *
+ * const matcher = Result.match({
+ *   ok: (value: number) => value + 1,
+ *   err: (error: string) => error.length,
+ * });
+ *
+ * assert.deepStrictEqual(matcher(Result.ok(1)), 2);
+ *
+ * assert.deepStrictEqual(matcher(Result.err('oops')), 4);
+ * ```
+ *
+ * @template R The input `UnknownResult` type.
+ * @template S2 The type returned by the `ok` case.
+ * @template E2 The type returned by the `err` case.
+ * @param result The `Result` to match on.
+ * @param cases An object with an `ok` handler receiving the success value and
+ *   an `err` handler receiving the error value.
+ * @returns The value produced by whichever case handler was applied.
+ */
+export function match<R extends UnknownResult, S2, E2>(
+  result: R,
+  cases: Readonly<{
+    ok: (value: UnwrapOk<R>) => S2;
+    err: (error: UnwrapErr<R>) => E2;
+  }>,
+): E2 | S2;
+
+// Curried version
+//
+// The returned function is generic over the *whole* result, mirroring the
+// direct overload above; see the comment on the curried overload of
+// `Result.map` for why the parameter is a conditional type instead of a plain
+// `Result<S, E>`. Both sides have to be checked here, hence the nested
+// conditional.
+export function match<S, E, S2, E2>(
+  cases: Readonly<{
+    ok: (value: S) => S2;
+    err: (error: E) => E2;
+  }>,
+): <R extends UnknownResult>(
+  result: UnwrapOk<R> extends S ? (UnwrapErr<R> extends E ? R : never) : never,
+) => E2 | S2;
+
+export function match<R extends UnknownResult, S2, E2>(
+  ...args:
+    | readonly [
+        result: R,
+        cases: Readonly<{
+          ok: (value: UnwrapOk<R>) => S2;
+          err: (error: UnwrapErr<R>) => E2;
+        }>,
+      ]
+    | readonly [
+        cases: Readonly<{
+          ok: (value: UnwrapOk<R>) => S2;
+          err: (error: UnwrapErr<R>) => E2;
+        }>,
+      ]
+): E2 | S2 | ((result: R) => E2 | S2) {
+  switch (args.length) {
+    case 2: {
+      const [result, cases] = args;
+
+      return matchImpl(result, cases);
+    }
+
+    case 1: {
+      // Curried version: the only argument is the case handlers
+      const [cases] = args;
+
+      return (result: R) => matchImpl(result, cases);
+    }
+  }
+}
+
+const matchImpl = <R extends UnknownResult, S2, E2>(
+  result: R,
+  cases: Readonly<{
+    ok: (value: UnwrapOk<R>) => S2;
+    err: (error: UnwrapErr<R>) => E2;
+  }>,
+): E2 | S2 =>
+  isOk(result)
+    ? // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+      cases.ok(result.value as UnwrapOk<R>)
+    : // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+      cases.err(result.value as UnwrapErr<R>);

package/src/functional/result/impl/result-safe-try.mts

@@ -0,0 +1,110 @@
+import { hasKey, isRecord } from '../../../guard/index.mjs';
+import { type Err } from '../../../types.mjs';
+import { type Result, type UnknownResult } from '../result.mjs';
+import { type UnwrapErr, type UnwrapOk } from './types.mjs';
+
+/**
+ * Runs a generator body in which `yield* Result.safeUnwrap(...)` unwraps `Ok`
+ * values and short-circuits on the first `Err`, emulating Rust's `?` operator
+ * (early-return error propagation).
+ *
+ * The body must return a `Result`. If every unwrapped `Result` is `Ok`, the
+ * returned value is the body's `Result`; otherwise it is the first `Err`
+ * encountered, and the rest of the body never runs — though the generator is
+ * closed rather than dropped, so `finally` blocks and `using` disposals
+ * pending in the body still run. An exception thrown by the body is not
+ * converted to an `Err`: it propagates out of `safeTry` (as a rejected
+ * `Promise` for an async body). Use {@link Result.fromThrowable} for that.
+ *
+ * Passing an async generator (`async function*`) returns a
+ * `Promise<Result<...>>` instead, so `await` can be used inside the body.
+ * Note that `yield*` inside an `async function*` awaits what it receives, so
+ * unwrapping an `Ok` whose value is itself a `Promise` yields the awaited
+ * value there while the static type still says `Promise<...>`; keep promises
+ * out of the `Ok` side of a `Result` unwrapped in an async body.
+ *
+ * @example
+ *
+ * ```ts
+ * const parseTwo = (a: string, b: string): Result<number, Error> =>
+ *   Result.safeTry(function* () {
+ *     const x = yield* Result.safeUnwrap(Num.safeParseInt(a));
+ *
+ *     const y = yield* Result.safeUnwrap(Num.safeParseInt(b));
+ *
+ *     return Result.ok(x + y);
+ *   });
+ *
+ * assert.deepStrictEqual(parseTwo('1', '2'), Result.ok(3));
+ *
+ * assert.isTrue(Result.isErr(parseTwo('1', 'not a number')));
+ * ```
+ *
+ * @template Y The union of `Err` types unwrapped via
+ *   {@link Result.safeUnwrap} (`never` if nothing is unwrapped).
+ * @template R2 The `Result` type returned by the body.
+ * @param body A generator function whose `yield*` expressions delegate to
+ *   {@link Result.safeUnwrap} and whose return value is a `Result`.
+ * @returns The body's `Result`, or the first `Err` short-circuited out of it
+ *   (wrapped in a `Promise` for an async generator body).
+ */
+export function safeTry<Y extends Err<unknown>, R2 extends UnknownResult>(
+  body: () => Generator<Y, R2>,
+): Result<UnwrapOk<R2>, UnwrapErr<R2> | UnwrapErr<Y>>;
+
+export function safeTry<Y extends Err<unknown>, R2 extends UnknownResult>(
+  body: () => AsyncGenerator<Y, R2>,
+): Promise<Result<UnwrapOk<R2>, UnwrapErr<R2> | UnwrapErr<Y>>>;
+
+export function safeTry(
+  body:
+    | (() => AsyncGenerator<UnknownResult, UnknownResult>)
+    | (() => Generator<UnknownResult, UnknownResult>),
+): Promise<UnknownResult> | UnknownResult {
+  const generator = body();
+
+  // A yielded `Err` and a returned `Result` are both already the final
+  // answer, so the first step's `value` is the result in either case: the
+  // generator is closed rather than resumed after yielding.
+  const step = generator.next();
+
+  if (isSyncStep(step)) {
+    // Dropping a suspended generator would skip the `finally` blocks and
+    // `using` disposals still pending in the body; closing it runs them
+    // before the short-circuited `Err` is handed back. `isSyncGenerator` is
+    // what makes `return()` here synchronous rather than a floating promise.
+    if (step.done !== true && isSyncGenerator(generator, step)) {
+      generator.return(step.value);
+    }
+
+    return step.value;
+  }
+
+  return step.then(async (asyncStep) => {
+    if (asyncStep.done !== true) {
+      await generator.return(asyncStep.value);
+    }
+
+    return asyncStep.value;
+  });
+}
+
+// A sync generator's `next()` returns a plain `{ value, done }` object with
+// own properties, while an async generator's returns a `Promise`, whose
+// `then` lives on the prototype — so an own-key check on `done` separates the
+// two.
+const isSyncStep = (
+  value: unknown,
+): value is IteratorResult<UnknownResult, UnknownResult> =>
+  isRecord(value) && hasKey(value, 'done');
+
+// The generator-side counterpart of `isSyncStep`: a step in the sync form can
+// only have come from a sync generator, so the step is what narrows the
+// generator that produced it — hence the predicate reads its second argument
+// and not its first.
+const isSyncGenerator = (
+  _generator:
+    | AsyncGenerator<UnknownResult, UnknownResult>
+    | Generator<UnknownResult, UnknownResult>,
+  step: unknown,
+): _generator is Generator<UnknownResult, UnknownResult> => isSyncStep(step);

package/src/functional/result/impl/result-safe-unwrap.mts

@@ -0,0 +1,50 @@
+import { type UnknownResult } from '../result.mjs';
+import { isErr } from './result-is-err.mjs';
+import { type NarrowToErr, type UnwrapOk } from './types.mjs';
+
+/**
+ * Unwraps a `Result` inside a {@link Result.safeTry} generator body via
+ * `yield*`, emulating Rust's `?` operator.
+ *
+ * If the `Result` is `Ok`, the `yield*` expression evaluates to the contained
+ * value and execution continues. If it is `Err`, the error is yielded to
+ * {@link Result.safeTry}, which returns it immediately — the rest of the
+ * generator body never runs.
+ *
+ * This generator must only be delegated to (`yield*`) inside a
+ * {@link Result.safeTry} body; resuming it after it has yielded an `Err`
+ * throws.
+ *
+ * @example
+ *
+ * ```ts
+ * const result = Result.safeTry(function* () {
+ *   const x = yield* Result.safeUnwrap(Result.ok(2));
+ *
+ *   const y = yield* Result.safeUnwrap(Result.ok(3));
+ *
+ *   return Result.ok(x + y);
+ * });
+ *
+ * assert.deepStrictEqual(result, Result.ok(5));
+ * ```
+ *
+ * @template R The input `UnknownResult` type.
+ * @param result The `Result` to unwrap.
+ * @returns A generator that yields the `Err` (if any) and returns the `Ok`
+ *   value.
+ */
+export function* safeUnwrap<R extends UnknownResult>(
+  result: R,
+): Generator<NarrowToErr<R>, UnwrapOk<R>, unknown> {
+  if (isErr(result)) {
+    yield result;
+
+    throw new Error(
+      '`safeUnwrap()` generator was resumed after yielding an `Err`; it must only be used via `yield*` inside `safeTry()`',
+    );
+  }
+
+  // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+  return result.value as UnwrapOk<R>;
+}