ts-data-forge 3.3.1 → 4.1.0

package/src/functional/ternary-result/impl/ternary-result-fold.mts

@@ -0,0 +1,93 @@
+import { err } from './ternary-result-err.mjs';
+import { isOk } from './ternary-result-is-ok.mjs';
+import { isWarn } from './ternary-result-is-warn.mjs';
+import { ok } from './ternary-result-ok.mjs';
+import { warn } from './ternary-result-warn.mjs';
+import { type UnwrapErr, type UnwrapOk, type UnwrapWarn } from './types.mjs';
+
+/**
+ * Applies the provided mapper based on the current variant.
+ *
+ * @example
+ *
+ * ```ts
+ * const okFold = TernaryResult.fold(
+ *   TernaryResult.ok(2),
+ *   (value) => value * 2,
+ *   (warn: string) => warn.length,
+ *   (error: string) => error.toUpperCase(),
+ * );
+ * const warnFold = TernaryResult.fold(
+ *   TernaryResult.warn(2, 'spike'),
+ *   (value: number) => value,
+ *   (warn: string) => warn.toUpperCase(),
+ *   (error: string) => error,
+ * );
+ *
+ * assert.deepStrictEqual(okFold, TernaryResult.ok(4));
+ * assert.deepStrictEqual(warnFold, TernaryResult.warn(2, 'SPIKE'));
+ * ```
+ */
+export function fold<R extends UnknownTernaryResult, S2, W2, E2>(
+  result: R,
+  mapOk: (value: UnwrapOk<R>) => S2,
+  mapWarn: (value: UnwrapWarn<R>) => W2,
+  mapErr: (error: UnwrapErr<R>) => E2,
+): TernaryResult<S2, E2, W2>;
+
+// Curried version
+export function fold<S, W, E, S2, W2, E2>(
+  mapOk: (value: S) => S2,
+  mapWarn: (value: W) => W2,
+  mapErr: (error: E) => E2,
+): (result: TernaryResult<S, E, W>) => TernaryResult<S2, E2, W2>;
+
+export function fold<R extends UnknownTernaryResult, S2, W2, E2>(
+  ...args:
+    | readonly [
+        result: R,
+        mapOk: (value: UnwrapOk<R>) => S2,
+        mapWarn: (value: UnwrapWarn<R>) => W2,
+        mapErr: (error: UnwrapErr<R>) => E2,
+      ]
+    | readonly [
+        mapOk: (value: UnwrapOk<R>) => S2,
+        mapWarn: (value: UnwrapWarn<R>) => W2,
+        mapErr: (error: UnwrapErr<R>) => E2,
+      ]
+): TernaryResult<S2, E2, W2> | ((result: R) => TernaryResult<S2, E2, W2>) {
+  switch (args.length) {
+    case 4: {
+      const [result, mapOk, mapWarn, mapErr] = args;
+      return foldImpl(result, mapOk, mapWarn, mapErr);
+    }
+    case 3: {
+      const [mapOk, mapWarn, mapErr] = args;
+      return (result: R) => foldImpl(result, mapOk, mapWarn, mapErr);
+    }
+  }
+}
+
+const foldImpl = <R extends UnknownTernaryResult, S2, W2, E2>(
+  result: R,
+  mapOk: (value: UnwrapOk<R>) => S2,
+  mapWarnFn: (warning: UnwrapWarn<R>) => W2,
+  mapErrFn: (error: UnwrapErr<R>) => E2,
+): TernaryResult<S2, E2, W2> => {
+  if (isOk(result)) {
+    // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+    return ok(mapOk(result.value as UnwrapOk<R>));
+  }
+
+  if (isWarn(result)) {
+    return warn(
+      // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+      mapOk(result.value as UnwrapOk<R>),
+      // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+      mapWarnFn(result.warning as UnwrapWarn<R>),
+    );
+  }
+
+  // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+  return err(mapErrFn(result.value as UnwrapErr<R>));
+};

package/src/functional/ternary-result/impl/ternary-result-from-promise.mts

@@ -0,0 +1,27 @@
+import { err } from './ternary-result-err.mjs';
+import { ok } from './ternary-result-ok.mjs';
+
+/** @internal Utility type extracting the resolved value 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 `TernaryResult`.
+ *
+ * @example
+ *
+ * ```ts
+ * const resolved = await TernaryResult.fromPromise(Promise.resolve('ok'));
+ * const rejected = await TernaryResult.fromPromise(
+ *   Promise.reject(new Error('fail')),
+ * );
+ *
+ * assert.deepStrictEqual(resolved, TernaryResult.ok('ok'));
+ * assert.ok(TernaryResult.isErr(rejected));
+ * ```
+ */
+export const fromPromise = <P extends Promise<unknown>>(
+  promise: P,
+): Promise<TernaryResult<UnwrapPromise<P>, unknown, never>> =>
+  // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+  promise.then((value) => ok(value) as TernaryOk<UnwrapPromise<P>>).catch(err);

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

@@ -0,0 +1,31 @@
+import { unknownToString } from '../../../others/index.mjs';
+import { err } from './ternary-result-err.mjs';
+import { ok } from './ternary-result-ok.mjs';
+
+/**
+ * Wraps a potentially-throwing function in a `TernaryResult`.
+ *
+ * @example
+ *
+ * ```ts
+ * const success = TernaryResult.fromThrowable(() => 1 + 1);
+ * const failure = TernaryResult.fromThrowable(() => {
+ *   throw new Error('boom');
+ * });
+ *
+ * assert.deepStrictEqual(success, TernaryResult.ok(2));
+ * assert.ok(TernaryResult.isErr(failure));
+ * ```
+ */
+export const fromThrowable = <T,>(
+  fn: () => T,
+): TernaryResult<T, Error, never> => {
+  try {
+    return ok(fn());
+  } catch (error) {
+    if (Error.isError(error)) {
+      return err(error);
+    }
+    return err(new Error(unknownToString(error)));
+  }
+};

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

@@ -0,0 +1,23 @@
+import { ErrTypeTagName } from './tag.mjs';
+import { type NarrowToErr } from './types.mjs';
+
+/**
+ * Type guard for the Err variant.
+ *
+ * @example
+ *
+ * ```ts
+ * const maybeErr = TernaryResult.err('boom') as TernaryResult<
+ *   number,
+ *   string,
+ *   string
+ * >;
+ *
+ * if (TernaryResult.isErr(maybeErr)) {
+ *   assert.strictEqual(maybeErr.value, 'boom');
+ * }
+ * ```
+ */
+export const isErr = <R extends UnknownTernaryResult>(
+  result: R,
+): result is NarrowToErr<R> => result.$$tag === ErrTypeTagName;

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

@@ -0,0 +1,24 @@
+import { OkTypeTagName } from './tag.mjs';
+import { type NarrowToOk } from './types.mjs';
+
+/**
+ * Type guard for the Ok variant.
+ *
+ * @example
+ *
+ * ```ts
+ * const maybeNumber = TernaryResult.ok(42) as TernaryResult<
+ *   number,
+ *   string,
+ *   string
+ * >;
+ *
+ * if (TernaryResult.isOk(maybeNumber)) {
+ *   const value: number = maybeNumber.value;
+ *   assert.strictEqual(value, 42);
+ * }
+ * ```
+ */
+export const isOk = <R extends UnknownTernaryResult>(
+  result: R,
+): result is NarrowToOk<R> => result.$$tag === OkTypeTagName;

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

@@ -0,0 +1,27 @@
+import { hasKey, isRecord } from '../../../guard/index.mjs';
+import { ErrTypeTagName, OkTypeTagName, WarnTypeTagName } from './tag.mjs';
+
+/**
+ * Checks whether the provided value is a {@link TernaryResult}.
+ *
+ * @example
+ *
+ * ```ts
+ * const okValue = TernaryResult.ok('done');
+ * const warnValue = TernaryResult.warn('done', 'retry later');
+ * const notResult = { $$tag: 'ts-data-forge::Result.ok' };
+ *
+ * assert.ok(TernaryResult.isTernaryResult(okValue));
+ * assert.ok(TernaryResult.isTernaryResult(warnValue));
+ * assert.ok(!TernaryResult.isTernaryResult(notResult));
+ * ```
+ */
+export const isTernaryResult = (
+  maybeResult: unknown,
+): maybeResult is UnknownTernaryResult =>
+  isRecord(maybeResult) &&
+  hasKey(maybeResult, '$$tag') &&
+  hasKey(maybeResult, 'value') &&
+  ((maybeResult.$$tag === WarnTypeTagName && hasKey(maybeResult, 'warning')) ||
+    maybeResult.$$tag === OkTypeTagName ||
+    maybeResult.$$tag === ErrTypeTagName);

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

@@ -0,0 +1,24 @@
+import { WarnTypeTagName } from './tag.mjs';
+import { type NarrowToWarn } from './types.mjs';
+
+/**
+ * Type guard for the Warn variant.
+ *
+ * @example
+ *
+ * ```ts
+ * const maybeWarn = TernaryResult.warn('value', 'check logs') as TernaryResult<
+ *   string,
+ *   string,
+ *   string
+ * >;
+ *
+ * if (TernaryResult.isWarn(maybeWarn)) {
+ *   assert.strictEqual(maybeWarn.value, 'value');
+ *   assert.strictEqual(maybeWarn.warning, 'check logs');
+ * }
+ * ```
+ */
+export const isWarn = <R extends UnknownTernaryResult>(
+  result: R,
+): result is NarrowToWarn<R> => result.$$tag === WarnTypeTagName;

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

@@ -0,0 +1,64 @@
+import { err } from './ternary-result-err.mjs';
+import { isErr } from './ternary-result-is-err.mjs';
+import { type UnwrapErr, type UnwrapOk, type UnwrapWarn } from './types.mjs';
+
+/**
+ * Maps the Err variant while leaving Ok/Warn untouched.
+ *
+ * @example
+ *
+ * ```ts
+ * const errValue = TernaryResult.err('boom');
+ * const mappedErr = TernaryResult.mapErr(errValue, (error) =>
+ *   error.toUpperCase(),
+ * );
+ * const warnPassthrough = TernaryResult.mapErr(
+ *   TernaryResult.warn(2, 'slow'),
+ *   (error: string) => `${error}!`,
+ * );
+ *
+ * assert.deepStrictEqual(mappedErr, TernaryResult.err('BOOM'));
+ * assert.deepStrictEqual(warnPassthrough, TernaryResult.warn(2, 'slow'));
+ * ```
+ */
+export function mapErr<R extends UnknownTernaryResult, E2>(
+  result: R,
+  mapFn: (error: UnwrapErr<R>) => E2,
+): TernaryResult<UnwrapOk<R>, E2, UnwrapWarn<R>>;
+
+// Curried version
+export function mapErr<E, E2>(
+  mapFn: (error: E) => E2,
+): <S, W>(result: TernaryResult<S, E, W>) => TernaryResult<S, E2, W>;
+
+export function mapErr<R extends UnknownTernaryResult, E2>(
+  ...args:
+    | readonly [result: R, mapFn: (error: UnwrapErr<R>) => E2]
+    | readonly [mapFn: (error: UnwrapErr<R>) => E2]
+):
+  | TernaryResult<UnwrapOk<R>, E2, UnwrapWarn<R>>
+  | ((result: R) => TernaryResult<UnwrapOk<R>, E2, UnwrapWarn<R>>) {
+  switch (args.length) {
+    case 2: {
+      const [result, mapFn] = args;
+      return mapErrImpl(result, mapFn);
+    }
+    case 1: {
+      const [mapFn] = args;
+      return (result: R) => mapErrImpl(result, mapFn);
+    }
+  }
+}
+
+const mapErrImpl = <R extends UnknownTernaryResult, E2>(
+  result: R,
+  mapFn: (error: UnwrapErr<R>) => E2,
+): TernaryResult<UnwrapOk<R>, E2, UnwrapWarn<R>> => {
+  if (isErr(result)) {
+    // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+    return err(mapFn(result.value as UnwrapErr<R>));
+  }
+
+  // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+  return result as TernaryResult<UnwrapOk<R>, E2, UnwrapWarn<R>>;
+};

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

@@ -0,0 +1,66 @@
+import { isWarn } from './ternary-result-is-warn.mjs';
+import { warn } from './ternary-result-warn.mjs';
+import { type UnwrapErr, type UnwrapOk, type UnwrapWarn } from './types.mjs';
+
+/**
+ * Maps the Warn variant while leaving Ok/Err untouched.
+ *
+ * @example
+ *
+ * ```ts
+ * const warnValue = TernaryResult.warn(2, 'slow');
+ * const mappedWarn = TernaryResult.mapWarn(warnValue, (warning) => `${warning}!`);
+ * const okPassthrough = TernaryResult.mapWarn(
+ *   TernaryResult.ok(3),
+ *   (value: number) => value * 2,
+ * );
+ *
+ * assert.deepStrictEqual(mappedWarn, TernaryResult.warn(2, 'slow!'));
+ * assert.deepStrictEqual(okPassthrough, TernaryResult.ok(3));
+ * ```
+ */
+export function mapWarn<R extends UnknownTernaryResult, W2>(
+  result: R,
+  mapFn: (warning: UnwrapWarn<R>) => W2,
+): TernaryResult<UnwrapOk<R>, UnwrapErr<R>, W2>;
+
+// Curried version
+export function mapWarn<W, W2>(
+  mapFn: (warning: W) => W2,
+): <S, E>(result: TernaryResult<S, E, W>) => TernaryResult<S, E, W2>;
+
+export function mapWarn<R extends UnknownTernaryResult, W2>(
+  ...args:
+    | readonly [result: R, mapFn: (warning: UnwrapWarn<R>) => W2]
+    | readonly [mapFn: (warning: UnwrapWarn<R>) => W2]
+):
+  | TernaryResult<UnwrapOk<R>, UnwrapErr<R>, W2>
+  | ((result: R) => TernaryResult<UnwrapOk<R>, UnwrapErr<R>, W2>) {
+  switch (args.length) {
+    case 2: {
+      const [result, mapFn] = args;
+      return mapWarnImpl(result, mapFn);
+    }
+    case 1: {
+      const [mapFn] = args;
+      return (result: R) => mapWarnImpl(result, mapFn);
+    }
+  }
+}
+
+const mapWarnImpl = <R extends UnknownTernaryResult, W2>(
+  result: R,
+  mapFn: (warning: UnwrapWarn<R>) => W2,
+): TernaryResult<UnwrapOk<R>, UnwrapErr<R>, W2> => {
+  if (isWarn(result)) {
+    return warn(
+      // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+      result.value as UnwrapOk<R>,
+      // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+      mapFn(result.warning as UnwrapWarn<R>),
+    );
+  }
+
+  // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+  return result as TernaryResult<UnwrapOk<R>, UnwrapErr<R>, W2>;
+};

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

@@ -0,0 +1,81 @@
+import { isOk } from './ternary-result-is-ok.mjs';
+import { isWarn } from './ternary-result-is-warn.mjs';
+import { ok } from './ternary-result-ok.mjs';
+import { warn } from './ternary-result-warn.mjs';
+import { type UnwrapErr, type UnwrapOk, type UnwrapWarn } from './types.mjs';
+
+/**
+ * Maps the Ok variant while leaving Warn/Err untouched.
+ *
+ * @example
+ *
+ * ```ts
+ * const okNumber = TernaryResult.ok(5);
+ * const warnValue = TernaryResult.warn(5, 'slow');
+ * const errValue = TernaryResult.err('bad');
+ *
+ * const doubled = TernaryResult.map(okNumber, (value) => value * 2);
+ * const warnPassthrough = TernaryResult.map(
+ *   warnValue,
+ *   (value: number) => value * 2,
+ * );
+ * const errPassthrough = TernaryResult.map(
+ *   errValue,
+ *   (value: number) => value * 2,
+ * );
+ *
+ * assert.deepStrictEqual(doubled, TernaryResult.ok(10));
+ * assert.deepStrictEqual(warnPassthrough, TernaryResult.warn(10, 'slow'));
+ * assert.deepStrictEqual(errPassthrough, errValue);
+ * ```
+ */
+export function map<R extends UnknownTernaryResult, S2>(
+  result: R,
+  mapFn: (value: UnwrapOk<R>) => S2,
+): TernaryResult<S2, UnwrapErr<R>, UnwrapWarn<R>>;
+
+// Curried version
+export function map<S, S2>(
+  mapFn: (value: S) => S2,
+): <W, E>(result: TernaryResult<S, E, W>) => TernaryResult<S2, E, W>;
+
+export function map<R extends UnknownTernaryResult, S2>(
+  ...args:
+    | readonly [result: R, mapFn: (value: UnwrapOk<R>) => S2]
+    | readonly [mapFn: (value: UnwrapOk<R>) => S2]
+):
+  | TernaryResult<S2, UnwrapErr<R>, UnwrapWarn<R>>
+  | ((result: R) => TernaryResult<S2, UnwrapErr<R>, UnwrapWarn<R>>) {
+  switch (args.length) {
+    case 2: {
+      const [result, mapFn] = args;
+      return mapImpl(result, mapFn);
+    }
+    case 1: {
+      const [mapFn] = args;
+      return (result: R) => mapImpl(result, mapFn);
+    }
+  }
+}
+
+const mapImpl = <R extends UnknownTernaryResult, S2>(
+  result: R,
+  mapFn: (value: UnwrapOk<R>) => S2,
+): TernaryResult<S2, UnwrapErr<R>, UnwrapWarn<R>> => {
+  if (isOk(result)) {
+    // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+    return ok(mapFn(result.value as UnwrapOk<R>));
+  }
+
+  if (isWarn(result)) {
+    return warn(
+      // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+      mapFn(result.value as UnwrapOk<R>),
+      // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+      result.warning as UnwrapWarn<R>,
+    );
+  }
+
+  // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+  return result as TernaryErr<UnwrapErr<R>>;
+};

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

@@ -0,0 +1,20 @@
+import { OkTypeTagName } from './tag.mjs';
+
+/**
+ * Creates a `TernaryResult.Ok` containing the provided value.
+ *
+ * @example
+ *
+ * ```ts
+ * const success = TernaryResult.ok({ id: 1 });
+ *
+ * assert.deepStrictEqual(success, {
+ *   $$tag: 'ts-data-forge::Result.ok',
+ *   value: { id: 1 },
+ * });
+ * ```
+ */
+export const ok = <S,>(value: S): TernaryOk<S> => ({
+  $$tag: OkTypeTagName,
+  value,
+});

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

@@ -0,0 +1,66 @@
+import { isOk } from './ternary-result-is-ok.mjs';
+import { isWarn } from './ternary-result-is-warn.mjs';
+import { type NarrowToOk, type NarrowToWarn } from './types.mjs';
+
+/**
+ * Returns the original result if it is Ok, otherwise the provided fallback.
+ *
+ * @example
+ *
+ * ```ts
+ * const fallback = TernaryResult.ok('fallback');
+ *
+ * assert.deepStrictEqual(
+ *   TernaryResult.orElse(TernaryResult.ok('value'), fallback),
+ *   TernaryResult.ok('value'),
+ * );
+ * assert.deepStrictEqual(
+ *   TernaryResult.orElse(TernaryResult.warn('value', 'warn'), fallback),
+ *   TernaryResult.warn('value', 'warn'),
+ * );
+ * assert.deepStrictEqual(
+ *   TernaryResult.orElse(TernaryResult.err('err'), fallback),
+ *   fallback,
+ * );
+ * ```
+ */
+export function orElse<
+  R extends UnknownTernaryResult,
+  R2 extends UnknownTernaryResult,
+>(result: R, alternative: R2): NarrowToOk<R> | NarrowToWarn<R> | R2;
+
+// Curried version
+export function orElse<S, W, E, S2, W2, E2>(
+  alternative: TernaryResult<S2, E2, W2>,
+): (
+  result: TernaryResult<S, E, W>,
+) => TernaryResult<S, E, W> | TernaryResult<S2, E2, W2>;
+
+export function orElse<
+  R extends UnknownTernaryResult,
+  R2 extends UnknownTernaryResult,
+>(
+  ...args: readonly [result: R, alternative: R2] | readonly [alternative: R2]
+):
+  | (NarrowToOk<R> | NarrowToWarn<R> | R2)
+  | ((result: R) => NarrowToOk<R> | NarrowToWarn<R> | R2) {
+  switch (args.length) {
+    case 2: {
+      const [result, alternative] = args;
+      return orElseImpl(result, alternative);
+    }
+    case 1: {
+      const [alternative] = args;
+      return (result: R) => orElseImpl(result, alternative);
+    }
+  }
+}
+
+const orElseImpl = <
+  R extends UnknownTernaryResult,
+  R2 extends UnknownTernaryResult,
+>(
+  result: R,
+  alternative: R2,
+): NarrowToOk<R> | NarrowToWarn<R> | R2 =>
+  isOk(result) || isWarn(result) ? result : alternative;

package/src/functional/ternary-result/impl/ternary-result-to-optional.mts

@@ -0,0 +1,25 @@
+import { Optional } from '../../optional/index.mjs';
+import { isOk } from './ternary-result-is-ok.mjs';
+import { isWarn } from './ternary-result-is-warn.mjs';
+import { type UnwrapOk } from './types.mjs';
+
+/**
+ * Converts a `TernaryResult` into an `Optional` by keeping only Ok values.
+ *
+ * @example
+ *
+ * ```ts
+ * const okValue = TernaryResult.ok(7);
+ * const warnValue = TernaryResult.warn(7, 'warn');
+ *
+ * assert.deepStrictEqual(TernaryResult.toOptional(okValue), Optional.some(7));
+ * assert.deepStrictEqual(TernaryResult.toOptional(warnValue), Optional.some(7));
+ * ```
+ */
+export const toOptional = <R extends UnknownTernaryResult>(
+  result: R,
+): Optional<UnwrapOk<R>> =>
+  isOk(result) || isWarn(result)
+    ? // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+      Optional.some(result.value as UnwrapOk<R>)
+    : Optional.none;

package/src/functional/ternary-result/impl/ternary-result-unwrap-err-or.mts

@@ -0,0 +1,45 @@
+import { unwrapErr } from './ternary-result-unwrap-err.mjs';
+import { type UnwrapErr } from './types.mjs';
+
+/**
+ * Returns the Err value or the provided default.
+ *
+ * @example
+ *
+ * ```ts
+ * const okValue = TernaryResult.ok('value');
+ *
+ * assert.strictEqual(TernaryResult.unwrapErrOr(okValue, 'default'), 'default');
+ * const unwrapErr = TernaryResult.unwrapErrOr('fallback error');
+ *
+ * assert.strictEqual(unwrapErr(TernaryResult.err('boom')), 'boom');
+ * assert.strictEqual(
+ *   unwrapErr(TernaryResult.warn('value', 'warn')),
+ *   'fallback error',
+ * );
+ * ```
+ */
+export function unwrapErrOr<R extends UnknownTernaryResult, D>(
+  result: R,
+  defaultValue: D,
+): D | UnwrapErr<R>;
+
+// Curried version
+export function unwrapErrOr<E, D>(
+  defaultValue: D,
+): <S, W>(result: TernaryResult<S, E, W>) => D | E;
+
+export function unwrapErrOr<R extends UnknownTernaryResult, D>(
+  ...args: readonly [result: R, defaultValue: D] | readonly [defaultValue: D]
+): D | UnwrapErr<R> | ((result: R) => D | UnwrapErr<R>) {
+  switch (args.length) {
+    case 2: {
+      const [result, defaultValue] = args;
+      return unwrapErr(result) ?? defaultValue;
+    }
+    case 1: {
+      const [defaultValue] = args;
+      return (result: R) => unwrapErr(result) ?? defaultValue;
+    }
+  }
+}

package/src/functional/ternary-result/impl/ternary-result-unwrap-err-throw.mts

@@ -0,0 +1,40 @@
+import { unknownToString } from '../../../others/index.mjs';
+import { isErr } from './ternary-result-is-err.mjs';
+import { isWarn } from './ternary-result-is-warn.mjs';
+import { type UnwrapErr, type UnwrapOk, type UnwrapWarn } from './types.mjs';
+import { variantName } from './variant-name.mjs';
+
+/**
+ * Returns the Err value or throws if the result is not Err.
+ *
+ * @example
+ *
+ * ```ts
+ * const errValue = TernaryResult.err('boom');
+ *
+ * assert.strictEqual(TernaryResult.unwrapErrThrow(errValue), 'boom');
+ * assert.throws(
+ *   () => TernaryResult.unwrapErrThrow(TernaryResult.ok('value')),
+ *   /Expected Err/u,
+ * );
+ * ```
+ */
+export const unwrapErrThrow = <R extends UnknownTernaryResult>(
+  result: R,
+  toStr: (value: UnwrapOk<R> | UnwrapWarn<R>) => string = unknownToString,
+): UnwrapErr<R> => {
+  if (isErr(result)) {
+    // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+    return result.value as UnwrapErr<R>;
+  }
+
+  const variant = variantName(result.$$tag);
+
+  const payload = isWarn(result)
+    ? // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+      (result.warning as UnwrapWarn<R> as UnwrapOk<R> | UnwrapWarn<R>)
+    : // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+      (result.value as UnwrapOk<R> as UnwrapOk<R> | UnwrapWarn<R>);
+
+  throw new Error(`Expected Err but got ${variant}: ${toStr(payload)}`);
+};