ts-data-forge 4.0.0 → 4.1.0

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)}`);
+};

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

@@ -0,0 +1,22 @@
+import { isErr } from './ternary-result-is-err.mjs';
+import { type UnwrapErr } from './types.mjs';
+
+/**
+ * Safely unwraps the Err value.
+ *
+ * @example
+ *
+ * ```ts
+ * const errValue = TernaryResult.err('fail');
+ * const okValue = TernaryResult.ok('value');
+ *
+ * assert.strictEqual(TernaryResult.unwrapErr(errValue), 'fail');
+ * // eslint-disable-next-line @typescript-eslint/no-confusing-void-expression
+ * assert.strictEqual(TernaryResult.unwrapErr(okValue), undefined);
+ * ```
+ */
+export const unwrapErr = <R extends UnknownTernaryResult>(
+  result: R,
+): UnwrapErr<R> | undefined =>
+  // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+  isErr(result) ? (result.value as UnwrapErr<R>) : undefined;

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

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

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

@@ -0,0 +1,32 @@
+import { isOk } from './ternary-result-is-ok.mjs';
+import { isWarn } from './ternary-result-is-warn.mjs';
+import { type UnwrapOk } from './types.mjs';
+
+/**
+ * Safely unwraps the Ok value.
+ *
+ * @example
+ *
+ * ```ts
+ * const okValue = TernaryResult.ok(3);
+ * const warnValue = TernaryResult.warn(4, 'warn');
+ *
+ * assert.strictEqual(TernaryResult.unwrapOk(okValue), 3);
+ * assert.strictEqual(TernaryResult.unwrapOk(warnValue), 4);
+ * ```
+ */
+export function unwrapOk<R extends TernaryOk<unknown>>(result: R): UnwrapOk<R>;
+export function unwrapOk<R extends UnknownTernaryResult>(
+  result: R,
+): UnwrapOk<R> | undefined;
+
+export function unwrapOk<R extends UnknownTernaryResult>(
+  result: R,
+): UnwrapOk<R> | undefined {
+  if (isOk(result) || isWarn(result)) {
+    // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+    return result.value as UnwrapOk<R>;
+  }
+
+  return undefined;
+}

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

@@ -0,0 +1,45 @@
+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';
+
+/**
+ * Returns the Ok value or throws if the result is Warn or Err.
+ *
+ * @example
+ *
+ * ```ts
+ * const okValue = TernaryResult.ok('ready');
+ *
+ * assert.strictEqual(TernaryResult.unwrapThrow(okValue), 'ready');
+ * assert.throws(
+ *   () => TernaryResult.unwrapThrow(TernaryResult.warn('warn', 'warned')),
+ *   /Expected Ok/u,
+ * );
+ * ```
+ */
+export const unwrapThrow = <R extends UnknownTernaryResult>(
+  result: R,
+  toStr: (value: UnwrapWarn<R> | UnwrapErr<R>) => string = unknownToString,
+): UnwrapOk<R> => {
+  if (isErr(result)) {
+    throw new Error(
+      `Expected Ok but got Err: ${toStr(
+        // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+        result.value as UnwrapErr<R>,
+      )}`,
+    );
+  }
+
+  if (isWarn(result)) {
+    throw new Error(
+      `Expected Ok but got Warn: ${toStr(
+        // 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.value as UnwrapOk<R>;
+};

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

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

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

@@ -0,0 +1,38 @@
+import { unknownToString } from '../../../others/index.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 Warn value or throws if the result is not Warn.
+ *
+ * @example
+ *
+ * ```ts
+ * const warnValue = TernaryResult.warn('pending', 'check logs');
+ *
+ * assert.strictEqual(TernaryResult.unwrapWarnThrow(warnValue), 'check logs');
+ * assert.throws(
+ *   () => TernaryResult.unwrapWarnThrow(TernaryResult.err('err')),
+ *   /Expected Warn/u,
+ * );
+ * ```
+ */
+export const unwrapWarnThrow = <R extends UnknownTernaryResult>(
+  result: R,
+  toStr: (value: UnwrapOk<R> | UnwrapErr<R>) => string = unknownToString,
+): UnwrapWarn<R> => {
+  if (isWarn(result)) {
+    // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+    return result.warning as UnwrapWarn<R>;
+  }
+
+  const variant = variantName(result.$$tag);
+
+  throw new Error(
+    `Expected Warn but got ${variant}: ${toStr(
+      // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+      result.value as UnwrapOk<R> | UnwrapErr<R>,
+    )}`,
+  );
+};

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

@@ -0,0 +1,22 @@
+import { isWarn } from './ternary-result-is-warn.mjs';
+import { type UnwrapWarn } from './types.mjs';
+
+/**
+ * Safely unwraps the Warn value.
+ *
+ * @example
+ *
+ * ```ts
+ * const warnValue = TernaryResult.warn('ok', 'careful');
+ * const okValue = TernaryResult.ok('ok');
+ *
+ * assert.strictEqual(TernaryResult.unwrapWarn(warnValue), 'careful');
+ * // eslint-disable-next-line @typescript-eslint/no-confusing-void-expression
+ * assert.strictEqual(TernaryResult.unwrapWarn(okValue), undefined);
+ * ```
+ */
+export const unwrapWarn = <R extends UnknownTernaryResult>(
+  result: R,
+): UnwrapWarn<R> | undefined =>
+  // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+  isWarn(result) ? (result.warning as UnwrapWarn<R>) : undefined;

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

@@ -0,0 +1,23 @@
+import { WarnTypeTagName } from './tag.mjs';
+
+/**
+ * Creates a `TernaryResult.Warn` containing the provided success value and
+ * warning.
+ *
+ * @example
+ *
+ * ```ts
+ * const caution = TernaryResult.warn({ id: 1 }, 'Needs review');
+ *
+ * assert.deepStrictEqual(caution, {
+ *   $$tag: 'ts-data-forge::Result.warn',
+ *   value: { id: 1 },
+ *   warning: 'Needs review',
+ * });
+ * ```
+ */
+export const warn = <S, W>(value: S, warning: W): TernaryWarn<S, W> => ({
+  $$tag: WarnTypeTagName,
+  value,
+  warning,
+});

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

@@ -0,0 +1,53 @@
+import { isErr } from './ternary-result-is-err.mjs';
+import { isWarn } from './ternary-result-is-warn.mjs';
+import { ok } from './ternary-result-ok.mjs';
+import { warn } from './ternary-result-warn.mjs';
+
+/**
+ * Combines two `TernaryResult`s, prioritising Err over Warn over Ok.
+ *
+ * @example
+ *
+ * ```ts
+ * const okPair = TernaryResult.zip(TernaryResult.ok('left'), TernaryResult.ok(1));
+ * const warnPair = TernaryResult.zip(
+ *   TernaryResult.warn('left', 'warn'),
+ *   TernaryResult.ok(1),
+ * );
+ * const errPair = TernaryResult.zip(
+ *   TernaryResult.ok('left'),
+ *   TernaryResult.err('err'),
+ * );
+ *
+ * assert.deepStrictEqual(okPair, TernaryResult.ok(['left', 1] as const));
+ * assert.deepStrictEqual(
+ *   warnPair,
+ *   TernaryResult.warn(['left', 1] as const, 'warn'),
+ * );
+ * assert.deepStrictEqual(errPair, TernaryResult.err('err'));
+ * ```
+ */
+export const zip = <S1, W1, E1, S2, W2, E2>(
+  resultA: TernaryResult<S1, E1, W1>,
+  resultB: TernaryResult<S2, E2, W2>,
+): TernaryResult<readonly [S1, S2], E1 | E2, W1 | W2> => {
+  if (isErr(resultA)) {
+    return resultA;
+  }
+
+  if (isErr(resultB)) {
+    return resultB;
+  }
+
+  const pair = [resultA.value, resultB.value] as const;
+
+  if (isWarn(resultA)) {
+    return warn(pair, resultA.warning);
+  }
+
+  if (isWarn(resultB)) {
+    return warn(pair, resultB.warning);
+  }
+
+  return ok(pair);
+};

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

@@ -0,0 +1,39 @@
+/**
+ * Extracts the success value type `S` from a `TernaryResult.Ok<S>`.
+ */
+export type UnwrapOk<R extends UnknownTernaryResult> =
+  R extends TernaryOk<infer S>
+    ? S
+    : R extends TernaryWarn<infer S, unknown>
+      ? S
+      : never;
+
+/**
+ * Extracts the warning value type `W` from a `TernaryResult.Warn<W>`.
+ */
+export type UnwrapWarn<R extends UnknownTernaryResult> =
+  R extends TernaryWarn<unknown, infer E> ? E : never;
+
+/**
+ * Extracts the error value type `E` from a `TernaryResult.Err<E>`.
+ */
+export type UnwrapErr<R extends UnknownTernaryResult> =
+  R extends TernaryErr<infer E> ? E : never;
+
+/**
+ * Narrows the provided `UnknownTernaryResult` to its Ok variant.
+ */
+export type NarrowToOk<R extends UnknownTernaryResult> =
+  R extends TernaryOk<unknown> ? R : never;
+
+/**
+ * Narrows the provided `UnknownTernaryResult` to its Warn variant.
+ */
+export type NarrowToWarn<R extends UnknownTernaryResult> =
+  R extends TernaryWarn<unknown, unknown> ? R : never;
+
+/**
+ * Narrows the provided `UnknownTernaryResult` to its Err variant.
+ */
+export type NarrowToErr<R extends UnknownTernaryResult> =
+  R extends TernaryErr<unknown> ? R : never;

package/src/functional/ternary-result/impl/variant-name.mts

@@ -0,0 +1,17 @@
+import { ErrTypeTagName, OkTypeTagName, WarnTypeTagName } from './tag.mjs';
+
+/** @internal Returns the human readable variant label for the given tag. */
+export const variantName = (
+  tag: UnknownTernaryResult['$$tag'],
+): 'Ok' | 'Warn' | 'Err' => {
+  switch (tag) {
+    case OkTypeTagName:
+      return 'Ok';
+
+    case WarnTypeTagName:
+      return 'Warn';
+
+    case ErrTypeTagName:
+      return 'Err';
+  }
+};

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

@@ -0,0 +1 @@
+export * as TernaryResult from './impl/index.mjs';