ts-data-forge 14.6.3 → 14.7.0

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

@@ -1,80 +0,0 @@
-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-from-promise.mts

@@ -1,51 +0,0 @@
-import { type Ok } from '../../../types.mjs';
-import { type Result } from '../result.mjs';
-import { err } from './result-err.mjs';
-import { ok } from './result-ok.mjs';
-
-/**
- * @template P The Promise type.
- * @internal
- * Utility type to extract the resolved value type from a Promise.
- */
-type UnwrapPromise<P extends Promise<unknown>> =
-  P extends Promise<infer V> ? V : never;
-
-/**
- * Converts a Promise into a Promise that resolves to a `Result`. If the input
- * Promise resolves, the `Result` will be `Ok` with the resolved value. If the
- * input Promise rejects, the `Result` will be `Err` with the rejection
- * reason.
- *
- * The error channel is `unknown`, since the rejection reason is carried
- * through untouched. For a concrete error type, use `AsyncResult.fromPromise`
- * with a `mapError` function; called without one it behaves exactly as this
- * function does.
- *
- * @example
- *
- * ```ts
- * const successPromise = Result.fromPromise(Promise.resolve('ok'));
- *
- * const failurePromise = Result.fromPromise(
- *   Promise.reject(new Error('fail')),
- * );
- *
- * const resolved = await successPromise;
- *
- * const rejected = await failurePromise;
- *
- * assert.deepStrictEqual(resolved, Result.ok('ok'));
- *
- * assert.isTrue(Result.isErr(rejected));
- * ```
- *
- * @template P The type of the input Promise.
- * @param promise The Promise to convert.
- * @returns A Promise that resolves to `Result<UnwrapPromise<P>, unknown>`.
- */
-export const fromPromise = <P extends Promise<unknown>>(
-  promise: P,
-): Promise<Result<UnwrapPromise<P>, unknown>> =>
-  // eslint-disable-next-line total-functions/no-unsafe-type-assertion
-  promise.then((v) => ok(v) as Ok<UnwrapPromise<P>>).catch(err);

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

@@ -1,48 +0,0 @@
-import { isError } from '@sindresorhus/is';
-import { unknownToString } from '../../../others/index.mjs';
-import { type Result } from '../result.mjs';
-import { err } from './result-err.mjs';
-import { ok } from './result-ok.mjs';
-
-/**
- * Wraps a function that may throw an exception in a `Result`.
- *
- * This is a fundamental utility for converting traditional exception-based
- * error handling into Result-based error handling. Any thrown value is
- * converted to an Error object for consistent error handling.
- *
- * If the function executes successfully, returns `Result.Ok` with the result.
- * If the function throws, returns `Result.Err` with the caught error.
- *
- * @example
- *
- * ```ts
- * const success = Result.fromThrowable(() => 1 + 1);
- *
- * const failure = Result.fromThrowable(() => {
- *   throw new Error('boom');
- * });
- *
- * assert.deepStrictEqual(success, Result.ok(2));
- *
- * assert.isTrue(Result.isErr(failure));
- * ```
- *
- * @template T The return type of the function.
- * @param fn The function to execute that may throw.
- * @returns A `Result<T, Error>` containing either the successful result or
- *   the caught error.
- */
-export const fromThrowable = <T,>(fn: () => T): Result<T, Error> => {
-  try {
-    return ok(fn());
-  } catch (error) {
-    if (isError(error)) {
-      return err(error);
-    }
-
-    const msg = unknownToString(error);
-
-    return err(new Error(msg));
-  }
-};

package/src/functional/result/impl/result-is-err.mts

@@ -1,26 +0,0 @@
-import { type UnknownResult } from '../result.mjs';
-import { ErrTypeTagName } from './tag.mjs';
-import { type NarrowToErr } from './types.mjs';
-
-/**
- * Type guard for the error variant.
- *
- * @example
- *
- * ```ts
- * const operation = Result.ok(3);
- *
- * const failure = Result.err('error');
- *
- * if (Result.isOk(operation)) {
- *   const value: number = operation.value;
- *
- *   assert.isTrue(value === 3);
- * }
- *
- * assert.isTrue(Result.isErr(failure));
- * ```
- */
-export const isErr = <R extends UnknownResult>(
-  result: R,
-): result is NarrowToErr<R> => result.$$tag === ErrTypeTagName;

package/src/functional/result/impl/result-is-ok.mts

@@ -1,26 +0,0 @@
-import { type UnknownResult } from '../result.mjs';
-import { OkTypeTagName } from './tag.mjs';
-import { type NarrowToOk } from './types.mjs';
-
-/**
- * Type guard for the ok variant.
- *
- * @example
- *
- * ```ts
- * const operation = Result.ok(3);
- *
- * const failure = Result.err('error');
- *
- * if (Result.isOk(operation)) {
- *   const value: number = operation.value;
- *
- *   assert.isTrue(value === 3);
- * }
- *
- * assert.isTrue(Result.isErr(failure));
- * ```
- */
-export const isOk = <R extends UnknownResult>(
-  result: R,
-): result is NarrowToOk<R> => result.$$tag === OkTypeTagName;

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

@@ -1,28 +0,0 @@
-import { hasKey, isRecord } from '../../../guard/index.mjs';
-import { type UnknownResult } from '../result.mjs';
-import { ErrTypeTagName, OkTypeTagName } from './tag.mjs';
-
-/**
- * Checks whether the provided value is a {@link Result<S, E>}.
- *
- * @example
- *
- * ```ts
- * const okValue = Result.ok('success');
- *
- * const errValue = Result.err(new Error('failure'));
- *
- * const notResult = { $$tag: 'ts-data-forge::Result.ok' } as const;
- *
- * assert.isTrue(Result.isResult(okValue));
- *
- * assert.isTrue(Result.isResult(errValue));
- *
- * assert.isFalse(Result.isResult(notResult));
- * ```
- */
-export const isResult = (maybeResult: unknown): maybeResult is UnknownResult =>
-  isRecord(maybeResult) &&
-  hasKey(maybeResult, '$$tag') &&
-  hasKey(maybeResult, 'value') &&
-  (maybeResult.$$tag === ErrTypeTagName || maybeResult.$$tag === OkTypeTagName);

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

@@ -1,96 +0,0 @@
-import { type Ok } from '../../../types.mjs';
-import { type Result, type UnknownResult } from '../result.mjs';
-import { err } from './result-err.mjs';
-import { isOk } from './result-is-ok.mjs';
-import { type UnwrapErr, type UnwrapOk } from './types.mjs';
-
-/**
- * Maps a `Result<S, E>` to `Result<S, E2>` by applying a function to the
- * error value. If the `Result` is `Result.Ok`, returns the original `Ok`.
- *
- * @example
- *
- * ```ts
- * const okValue = Result.ok(3) as Result<number, string>;
- *
- * const errValue = Result.err('missing');
- *
- * const untouchedOk = Result.mapErr(okValue, (error) => error.toUpperCase());
- *
- * const uppercasedErr = Result.mapErr(errValue, (error) =>
- *   error.toUpperCase(),
- * );
- *
- * assert.deepStrictEqual(untouchedOk, Result.ok(3));
- *
- * assert.deepStrictEqual(uppercasedErr, Result.err('MISSING'));
- *
- * const mapError = Result.mapErr((error: Readonly<Error>) => error.message);
- *
- * const wrapped = mapError(Result.err(new Error('boom')));
- *
- * assert.deepStrictEqual(wrapped, Result.err('boom'));
- * ```
- *
- * @template R The input `UnknownResult` type.
- * @template E2 The type of the error value returned by the mapping function.
- * @param result The `Result` to map.
- * @param mapFn The function to apply to the error value if present.
- * @returns A new `Result<UnwrapOk<R>, E2>`.
- */
-export function mapErr<R extends UnknownResult, E2>(
-  result: R,
-  mapFn: (error: UnwrapErr<R>) => E2,
-): Result<UnwrapOk<R>, E2>;
-
-// Curried version
-//
-// The returned function is generic over the *whole* result, mirroring the
-// direct overload above, rather than fixing its parameter to `Result<S, E>`.
-// Fixing it makes the curried form unusable from a caller that is itself
-// generic over the result: with `E` bound to `UnwrapErr<R>` at currying time the
-// parameter becomes `Result<...>` in terms of `R`, and TypeScript cannot show
-// a bare `R extends UnknownResult` is assignable to that — although every
-// concrete instantiation of `R` is.
-//
-// The conditional is what keeps the check: `R` is inferred from the argument
-// and its error type still has to satisfy `E`, so the mismatched case stays an
-// error. The cost is the message it produces — "not assignable to `never`"
-// rather than naming the two results.
-export function mapErr<E, E2>(
-  mapFn: (error: E) => E2,
-): <R extends UnknownResult>(
-  result: UnwrapErr<R> extends E ? R : never,
-) => Result<UnwrapOk<R>, E2>;
-
-export function mapErr<R extends UnknownResult, E2>(
-  ...args:
-    | readonly [result: R, mapFn: (error: UnwrapErr<R>) => E2]
-    | readonly [mapFn: (error: UnwrapErr<R>) => E2]
-): Result<UnwrapOk<R>, E2> | ((result: R) => Result<UnwrapOk<R>, E2>) {
-  switch (args.length) {
-    case 2: {
-      // Direct version: first argument is result
-      const [result, mapFn] = args;
-
-      return mapErrImpl(result, mapFn);
-    }
-
-    case 1: {
-      // Curried version: first argument is mapping function
-      const [mapFn] = args;
-
-      return (result: R) => mapErrImpl(result, mapFn);
-    }
-  }
-}
-
-const mapErrImpl = <R extends UnknownResult, E2>(
-  result: R,
-  mapFn: (error: UnwrapErr<R>) => E2,
-): Result<UnwrapOk<R>, E2> =>
-  isOk(result)
-    ? // eslint-disable-next-line total-functions/no-unsafe-type-assertion
-      (result as Ok<UnwrapOk<R>>)
-    : // eslint-disable-next-line total-functions/no-unsafe-type-assertion
-      err(mapFn(result.value as UnwrapErr<R>));

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

@@ -1,96 +0,0 @@
-import { type Err } from '../../../types.mjs';
-import { type Result, type UnknownResult } from '../result.mjs';
-import { isErr } from './result-is-err.mjs';
-import { ok } from './result-ok.mjs';
-import { type UnwrapErr, type UnwrapOk } from './types.mjs';
-
-/**
- * Maps a `Result<S, E>` to `Result<S2, E>` by applying a function to the
- * success value. If the `Result` is `Result.Err`, returns the original
- * `Err`.
- *
- * @example
- *
- * ```ts
- * const okNumber = Result.ok(5);
- *
- * const errMessage = Result.err('error');
- *
- * const doubled = Result.map(okNumber, (value) => value * 2);
- *
- * const untouchedError = Result.map(errMessage, (value: number) => value * 2);
- *
- * assert.deepStrictEqual(doubled, Result.ok(10));
- *
- * assert.deepStrictEqual(untouchedError, errMessage);
- *
- * const mapToLength = Result.map((text: string) => text.length);
- *
- * assert.deepStrictEqual(mapToLength(Result.ok('abc')), Result.ok(3));
- *
- * assert.deepStrictEqual(mapToLength(Result.err('bad')), Result.err('bad'));
- * ```
- *
- * @template R The input `UnknownResult` type.
- * @template S2 The type of the success value returned by the mapping
- *   function.
- * @param result The `Result` to map.
- * @param mapFn The function to apply to the success value if present.
- * @returns A new `Result<S2, UnwrapErr<R>>`.
- */
-export function map<R extends UnknownResult, S2>(
-  result: R,
-  mapFn: (value: UnwrapOk<R>) => S2,
-): Result<S2, UnwrapErr<R>>;
-
-// Curried version
-//
-// The returned function is generic over the *whole* result, mirroring the
-// direct overload above, rather than fixing its parameter to `Result<S, E>`.
-// Fixing it makes the curried form unusable from a caller that is itself
-// generic over the result: with `S` bound to `UnwrapOk<R>` at currying time the
-// parameter becomes `Result<...>` in terms of `R`, and TypeScript cannot show
-// a bare `R extends UnknownResult` is assignable to that — although every
-// concrete instantiation of `R` is.
-//
-// The conditional is what keeps the check: `R` is inferred from the argument
-// and its success type still has to satisfy `S`, so the mismatched case stays an
-// error. The cost is the message it produces — "not assignable to `never`"
-// rather than naming the two results.
-export function map<S, S2>(
-  mapFn: (value: S) => S2,
-): <R extends UnknownResult>(
-  result: UnwrapOk<R> extends S ? R : never,
-) => Result<S2, UnwrapErr<R>>;
-
-export function map<R extends UnknownResult, S2>(
-  ...args:
-    | readonly [result: R, mapFn: (value: UnwrapOk<R>) => S2]
-    | readonly [mapFn: (value: UnwrapOk<R>) => S2]
-): Result<S2, UnwrapErr<R>> | ((result: R) => Result<S2, UnwrapErr<R>>) {
-  switch (args.length) {
-    case 2: {
-      // Direct version: first argument is result
-      const [result, mapFn] = args;
-
-      return mapImpl(result, mapFn);
-    }
-
-    case 1: {
-      // Curried version
-      const [mapFn] = args;
-
-      return (result: R) => mapImpl(result, mapFn);
-    }
-  }
-}
-
-const mapImpl = <R extends UnknownResult, S2>(
-  result: R,
-  mapFn: (value: UnwrapOk<R>) => S2,
-): Result<S2, UnwrapErr<R>> =>
-  isErr(result)
-    ? // eslint-disable-next-line total-functions/no-unsafe-type-assertion
-      (result as Err<UnwrapErr<R>>)
-    : // eslint-disable-next-line total-functions/no-unsafe-type-assertion
-      ok(mapFn(result.value as UnwrapOk<R>));

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

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

@@ -1,33 +0,0 @@
-import { type Ok } from '../../../types.mjs';
-import { OkTypeTagName } from './tag.mjs';
-
-/**
- * Creates a `Result.Ok` containing the given success value.
- *
- * Use this constructor when an operation succeeds and you want to wrap the
- * successful result in a Result type for consistent error handling.
- *
- * @example
- *
- * ```ts
- * const success = Result.ok({ id: 1 });
- *
- * const failure = Result.err(new Error('missing data'));
- *
- * assert.deepStrictEqual(success, {
- *   $$tag: 'ts-data-forge::Result.ok',
- *   value: { id: 1 },
- * });
- *
- * assert.isTrue(Result.isErr(failure));
- * ```
- *
- * @template S The type of the success value.
- * @param value The success value.
- * @returns A `Result.Ok<S>` containing the value.
- */
-export const ok = <const S,>(value: S): Ok<S> =>
-  ({
-    $$tag: OkTypeTagName,
-    value,
-  }) as const;

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

@@ -1,73 +0,0 @@
-import { type UnknownResult } from '../result.mjs';
-import { isOk } from './result-is-ok.mjs';
-import { type NarrowToOk } from './types.mjs';
-
-/**
- * Returns the `Result` if it is `Ok`, otherwise returns the alternative.
- *
- * @example
- *
- * ```ts
- * const primary = Result.ok('primary');
- *
- * const fallback = Result.ok('fallback');
- *
- * const failure = Result.err('failure');
- *
- * assert.deepStrictEqual(Result.orElse(primary, fallback), primary);
- *
- * assert.deepStrictEqual(Result.orElse(failure, fallback), fallback);
- *
- * const orElseFallback = Result.orElse(Result.ok('default'));
- *
- * assert.deepStrictEqual(
- *   orElseFallback(Result.err('missing')),
- *   Result.ok('default'),
- * );
- *
- * assert.deepStrictEqual(
- *   orElseFallback(Result.ok('value')),
- *   Result.ok('value'),
- * );
- * ```
- *
- * @template R The input `UnknownResult` type.
- * @param result The `Result` to check.
- * @param alternative The alternative `Result` to return if the first is
- *   `Err`.
- * @returns The first `Result` if `Ok`, otherwise the alternative.
- */
-export function orElse<R extends UnknownResult, R2 extends UnknownResult>(
-  result: R,
-  alternative: R2,
-): NarrowToOk<R> | R2;
-
-// Curried version
-export function orElse<R2 extends UnknownResult>(
-  alternative: R2,
-): <R extends UnknownResult>(result: R) => NarrowToOk<R> | R2;
-
-export function orElse<R extends UnknownResult, R2 extends UnknownResult>(
-  ...args: readonly [result: R, alternative: R2] | readonly [alternative: R2]
-): (NarrowToOk<R> | R2) | ((result: R) => R | R2) {
-  switch (args.length) {
-    case 2: {
-      // Direct version: first argument is result
-      const [result, alternative] = args;
-
-      return orElseImpl(result, alternative);
-    }
-
-    case 1: {
-      // Curried version
-      const [alternative] = args;
-
-      return (result: R) => orElseImpl(result, alternative);
-    }
-  }
-}
-
-const orElseImpl = <R extends UnknownResult, R2 extends UnknownResult>(
-  result: R,
-  alternative: R2,
-): NarrowToOk<R> | R2 => (isOk(result) ? result : alternative);