ts-data-forge 14.6.4 → 14.7.0

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

@@ -1,46 +0,0 @@
-import {
-  type TernaryErr,
-  type TernaryOk,
-  type TernaryWarn,
-  type UnknownTernaryResult,
-} from '../ternary-result.mjs';
-
-/**
- * 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

@@ -1,18 +0,0 @@
-import { type UnknownTernaryResult } from '../ternary-result.mjs';
-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

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

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

@@ -1,50 +0,0 @@
-/**
- * Represents a `TernaryResult` that is a success, containing a value.
- */
-export type TernaryOk<S> = Readonly<{
-  /** @internal Discriminant property for the 'Ok' type. */
-  $$tag: 'ts-data-forge::Result.ok';
-
-  /** The success value. */
-  value: S;
-}>;
-
-/**
- * Represents a `TernaryResult` that contains a success value and an attached
- * warning.
- */
-export type TernaryWarn<S, W> = Readonly<{
-  /** @internal Discriminant property for the 'Warn' type. */
-  $$tag: 'ts-data-forge::Result.warn';
-
-  /** The success value. */
-  value: S;
-
-  /** The warning value. */
-  warning: W;
-}>;
-
-/**
- * Represents a `TernaryResult` that is an error, containing an error value.
- */
-export type TernaryErr<E> = Readonly<{
-  /** @internal Discriminant property for the 'Err' type. */
-  $$tag: 'ts-data-forge::Result.err';
-
-  /** The error value. */
-  value: E;
-}>;
-
-/**
- * Represents a value that can be `Ok`, `Warn`, or `Err`.
- */
-export type TernaryResult<S, E, W = E> =
-  TernaryOk<S> | TernaryWarn<S, W> | TernaryErr<E>;
-
-/**
- * Base type for any `TernaryResult`, used for generic constraints.
- */
-export type UnknownTernaryResult =
-  TernaryOk<unknown> | TernaryWarn<unknown, unknown> | TernaryErr<unknown>;
-
-export * as TernaryResult from './impl/index.mjs';

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

@@ -1,310 +0,0 @@
-import { expectType } from '../expect-type.mjs';
-import { Num } from '../number/index.mjs';
-import { Optional } from './optional/index.mjs';
-import { pipe } from './pipe.mjs';
-import { Result } from './result/index.mjs';
-import { TernaryResult } from './ternary-result/index.mjs';
-
-describe('TernaryResult test', () => {
-  test('constructors and guards', () => {
-    const ok = TernaryResult.ok(1);
-
-    const warn = TernaryResult.warn(1, 'caution');
-
-    const err = TernaryResult.err(new Error('boom'));
-
-    assert.isTrue(TernaryResult.isOk(ok));
-
-    assert.isTrue(TernaryResult.isWarn(warn));
-
-    assert.isTrue(TernaryResult.isErr(err));
-
-    assert.isTrue(TernaryResult.isTernaryResult(ok));
-
-    assert.isFalse(TernaryResult.isTernaryResult({}));
-
-    expectType<typeof ok, TernaryResult<number, never, never>>('<=');
-
-    expectType<typeof warn, TernaryResult<number, never, string>>('<=');
-
-    expectType<typeof err, TernaryResult<never, Error, never>>('<=');
-  });
-
-  test('map transforms Ok and Warn success values', () => {
-    const ok = TernaryResult.ok(2);
-
-    const warn = TernaryResult.warn(2, 'check');
-
-    const err = TernaryResult.err('fail');
-
-    const double = TernaryResult.map((value: number) => value * 2);
-
-    expect(TernaryResult.unwrapOk(double(ok))).toBe(4);
-
-    expect(TernaryResult.unwrapOk(double(warn))).toBe(4);
-
-    expect(TernaryResult.unwrapWarn(double(warn))).toBe('check');
-
-    expect(TernaryResult.unwrapErr(double(err))).toBe('fail');
-  });
-
-  test('mapWarn and mapErr leave other variants untouched', () => {
-    const warn = TernaryResult.warn(2, 'slow');
-
-    const err = TernaryResult.err('err');
-
-    const warnMessage = TernaryResult.mapWarn(
-      (warning: string) => `${warning}!`,
-    );
-
-    const errUpper = TernaryResult.mapErr((value: string) =>
-      value.toUpperCase(),
-    );
-
-    expect(TernaryResult.unwrapWarn(warnMessage(warn))).toBe('slow!');
-
-    expect(TernaryResult.unwrapOk(warnMessage(warn))).toBe(2);
-
-    expect(TernaryResult.unwrapWarn(errUpper(warn))).toBe('slow');
-
-    expect(TernaryResult.unwrapErr(errUpper(err))).toBe('ERR');
-  });
-
-  test('flatMap propagates Warn and Err while keeping warnings', () => {
-    const parse = (value: string): TernaryResult<number, string, never> =>
-      pipe(Num.safeParseFloat(value)).map((result) =>
-        Result.isErr(result)
-          ? TernaryResult.err('NaN')
-          : TernaryResult.ok(result.value),
-      ).value;
-
-    const warn = TernaryResult.warn('3', 'slow');
-
-    const err = TernaryResult.err('bad');
-
-    const okResult = TernaryResult.flatMap(TernaryResult.ok('3'), parse);
-
-    const warnResult = TernaryResult.flatMap(warn, parse);
-
-    const errResult = TernaryResult.flatMap(err, parse);
-
-    expect(TernaryResult.unwrapOk(okResult)).toBe(3);
-
-    assert.isTrue(TernaryResult.isWarn(warnResult));
-
-    if (TernaryResult.isWarn(warnResult)) {
-      expect(warnResult.value).toBe(3);
-
-      expect(warnResult.warning).toBe('slow');
-    }
-
-    expect(TernaryResult.unwrapErr(errResult)).toBe('bad');
-  });
-
-  test('fold maps each variant independently', () => {
-    const value = TernaryResult.fold(
-      TernaryResult.ok(1),
-      (o: number) => o + 1,
-      (w: string) => ({ warning: w }),
-      (e: string) => ({ message: e }),
-    );
-
-    const warn = TernaryResult.fold(
-      TernaryResult.warn(2, 'heads up'),
-      (x) => x * 2,
-      (w: string) => ({ warning: w }),
-      (e: string) => ({ message: e }),
-    );
-
-    const err = TernaryResult.fold(
-      TernaryResult.err('boom'),
-      (x) => x,
-      (w: string) => ({ warning: w }),
-      (e: string) => ({ message: e }),
-    );
-
-    expect(TernaryResult.unwrapOk(value)).toBe(2);
-
-    expect(TernaryResult.unwrapOk(warn)).toBe(4);
-
-    assert.deepStrictEqual(TernaryResult.unwrapWarn(warn), {
-      warning: 'heads up',
-    });
-
-    assert.deepStrictEqual(TernaryResult.unwrapErr(err), { message: 'boom' });
-  });
-
-  test('orElse keeps Ok and Warn variants', () => {
-    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,
-    );
-  });
-
-  test('unwrap helpers', () => {
-    const warn = TernaryResult.warn('value', 'careful');
-
-    const err = TernaryResult.err('broken');
-
-    expect(TernaryResult.unwrapOk(TernaryResult.ok(3))).toBe(3);
-
-    expect(TernaryResult.unwrapOk(warn)).toBe('value');
-
-    expect(TernaryResult.unwrapWarn(warn)).toBe('careful');
-
-    expect(TernaryResult.unwrapErr(err)).toBe('broken');
-
-    expect(TernaryResult.unwrapOkOr(err, 0)).toBe(0);
-
-    expect(TernaryResult.unwrapWarnOr(err, 'default')).toBe('default');
-
-    expect(TernaryResult.unwrapErrOr(warn, 'default')).toBe('default');
-  });
-
-  test('throwing unwrap variants provide descriptive errors', () => {
-    expect(() =>
-      TernaryResult.unwrapThrow(TernaryResult.warn('notice', 'warned')),
-    ).toThrow(/Warn/u);
-
-    expect(() =>
-      TernaryResult.unwrapWarnThrow(TernaryResult.err('no warn')),
-    ).toThrow(/Err/u);
-
-    expect(() =>
-      TernaryResult.unwrapErrThrow(TernaryResult.ok('no err')),
-    ).toThrow(/Ok/u);
-  });
-
-  test('expectToBe unwraps Ok values', () => {
-    expect(TernaryResult.expectToBe(TernaryResult.ok('v'), 'msg')).toBe('v');
-
-    expect(() =>
-      TernaryResult.expectToBe(TernaryResult.err('x'), 'missing'),
-    ).toThrow(/missing/u);
-  });
-
-  test('zip prefers Err over Warn or Ok.', () => {
-    const ok = TernaryResult.ok('x');
-
-    const warn = TernaryResult.warn('warn', 'warned');
-
-    const err = TernaryResult.err('err');
-
-    assert.deepStrictEqual(
-      TernaryResult.zip(ok, TernaryResult.ok(1)),
-      TernaryResult.ok(['x', 1] as const),
-    );
-
-    assert.deepStrictEqual(
-      TernaryResult.zip(ok, warn),
-      TernaryResult.warn(['x', 'warn'] as const, 'warned'),
-    );
-
-    assert.deepStrictEqual(
-      TernaryResult.zip(warn, ok),
-      TernaryResult.warn(['warn', 'x'] as const, 'warned'),
-    );
-
-    assert.deepStrictEqual(TernaryResult.zip(ok, err), err);
-
-    assert.deepStrictEqual(TernaryResult.zip(err, warn), err);
-  });
-
-  test('toOptional keeps only Ok values', () => {
-    assert.deepStrictEqual(
-      TernaryResult.toOptional(TernaryResult.ok(1)),
-      Optional.some(1),
-    );
-
-    assert.deepStrictEqual(
-      TernaryResult.toOptional(TernaryResult.warn(1, 'warn')),
-      Optional.some(1),
-    );
-
-    expect(TernaryResult.toOptional(TernaryResult.err('err'))).toBe(
-      Optional.none,
-    );
-  });
-
-  test('fromPromise resolves into TernaryResult', async () => {
-    await expect(
-      TernaryResult.fromPromise(Promise.resolve('ok')),
-    ).resolves.toStrictEqual(TernaryResult.ok('ok'));
-
-    const rejected = await TernaryResult.fromPromise(
-      Promise.reject(new Error('bad')),
-    );
-
-    assert.isTrue(TernaryResult.isErr(rejected));
-  });
-
-  test('fromThrowable converts thrown values', () => {
-    assert.deepStrictEqual(
-      TernaryResult.fromThrowable(() => 5),
-      TernaryResult.ok(5),
-    );
-
-    const errorResult = TernaryResult.fromThrowable(() => {
-      throw new Error('boom');
-    });
-
-    assert.isTrue(TernaryResult.isErr(errorResult));
-  });
-
-  test('unwrapOkOr curried version', () => {
-    const unwrap = TernaryResult.unwrapOkOr(999);
-
-    expect(unwrap(TernaryResult.ok(42))).toBe(42);
-
-    expect(unwrap(TernaryResult.warn(10, 'notice'))).toBe(10);
-
-    expect(unwrap(TernaryResult.err('error'))).toBe(999);
-  });
-
-  test('unwrapWarnOr curried version', () => {
-    const unwrap = TernaryResult.unwrapWarnOr('default');
-
-    expect(unwrap(TernaryResult.warn(1, 'alert'))).toBe('alert');
-
-    expect(unwrap(TernaryResult.ok(5))).toBe('default');
-
-    expect(unwrap(TernaryResult.err('fail'))).toBe('default');
-  });
-
-  test('unwrapErrOr curried version', () => {
-    const unwrap = TernaryResult.unwrapErrOr('fallback');
-
-    expect(unwrap(TernaryResult.err('bad'))).toBe('bad');
-
-    expect(unwrap(TernaryResult.ok(3))).toBe('fallback');
-
-    expect(unwrap(TernaryResult.warn(1, 'note'))).toBe('fallback');
-  });
-
-  test('orElse curried version', () => {
-    const fallback = TernaryResult.ok('backup');
-
-    const useBackup = TernaryResult.orElse(fallback);
-
-    assert.deepStrictEqual(useBackup(TernaryResult.ok(1)), TernaryResult.ok(1));
-
-    assert.deepStrictEqual(
-      useBackup(TernaryResult.warn(2, 'w')),
-      TernaryResult.warn(2, 'w'),
-    );
-
-    assert.deepStrictEqual(useBackup(TernaryResult.err('e')), fallback);
-  });
-});

package/src/guard/has-key.test.mts

@@ -1,111 +0,0 @@
-import { type ReadonlyRecord } from 'ts-type-forge';
-import { expectType } from '../expect-type.mjs';
-import { hasKey, type HasKeyReturnType } from './has-key.mjs';
-
-test('hasKey type inferences', () => {
-  {
-    expectType<
-      HasKeyReturnType<Readonly<{ a: 0 } | { b: 1 }>, 'a'>,
-      Readonly<{ a: 0 }>
-    >('=');
-
-    expectType<
-      HasKeyReturnType<Readonly<{ a: 0 } | { b: 1 }>, 'b'>,
-      Readonly<{ b: 1 }>
-    >('=');
-
-    expectType<HasKeyReturnType<Readonly<{ a: 0 } | { b: 1 }>, 'd'>, never>(
-      '=',
-    );
-
-    expectType<
-      HasKeyReturnType<
-        Readonly<{ a: 0 } | { a: 1; b: 1 } | { b: 2 } | { c: 3 }>,
-        'a'
-      >,
-      Readonly<{ a: 0 } | { a: 1; b: 1 }>
-    >('=');
-
-    expectType<
-      HasKeyReturnType<
-        Readonly<{ a: 0 } | { a: 1; b: 1 } | { b: 2 } | { c: 3 }>,
-        'b'
-      >,
-      Readonly<{ a: 1; b: 1 } | { b: 2 }>
-    >('=');
-
-    expectType<
-      HasKeyReturnType<
-        | ReadonlyRecord<string, number>
-        | Readonly<{ a: 0 } | { a: 1; b: 1 } | { b: 2 }>,
-        'a'
-      >,
-      | Readonly<{ a: 0 } | { a: 1; b: 1 }>
-      | (ReadonlyRecord<'a', number> & ReadonlyRecord<string, number>)
-    >('=');
-
-    expectType<
-      HasKeyReturnType<ReadonlyRecord<string, unknown>, 'a'>,
-      ReadonlyRecord<'a', unknown> & ReadonlyRecord<string, unknown>
-    >('=');
-  }
-
-  {
-    type R = Readonly<{ a: 0 } | { b: 1 }>;
-
-    // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion
-    const obj: R = { a: 0 } as R;
-
-    if (hasKey(obj, 'a')) {
-      expectType<typeof obj.a, 0>('=');
-
-      expectType<typeof obj, Readonly<{ a: 0 }>>('=');
-    }
-
-    if (hasKey(obj, 'c')) {
-      expectType<typeof obj, never>('=');
-    }
-  }
-
-  {
-    type R = Readonly<{ a: 0 } | { a: 1; b: 1 } | { b: 2 } | { c: 3 }>;
-
-    // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion
-    const obj: R = { a: 0 } as R;
-
-    if (hasKey(obj, 'a') && hasKey(obj, 'b')) {
-      expectType<typeof obj.a, 1>('=');
-
-      expectType<typeof obj.b, 1>('=');
-
-      expectType<typeof obj, Readonly<{ a: 1; b: 1 }>>('=');
-    }
-  }
-
-  {
-    type R =
-      | ReadonlyRecord<string, number>
-      | Readonly<{ a: 0 } | { a: 1; b: 1 } | { b: 2 }>;
-
-    // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion
-    const obj: R = { a: 0 } as R;
-
-    expectType<
-      R,
-      | ReadonlyRecord<string, number>
-      | Readonly<{ a: 0 } | { a: 1; b: 1 } | { b: 2 }>
-    >('=');
-
-    if (hasKey(obj, 'a')) {
-      expectType<typeof obj.a, number>('=');
-
-      expectType<
-        typeof obj,
-        | Readonly<{ a: 0 } | { a: 1; b: 1 }>
-        | (ReadonlyRecord<'a', number> & ReadonlyRecord<string, number>)
-      >('=');
-    }
-  }
-
-  assert.strictEqual(true, true);
-});

package/src/guard/is-non-null-object.test.mts

@@ -1,109 +0,0 @@
-import { type UnknownRecord } from 'ts-type-forge';
-import { expectType } from '../expect-type.mjs';
-import { isNonNullObject } from './is-non-null-object.mjs';
-
-describe(isNonNullObject, () => {
-  test('should return true for plain objects', () => {
-    assert.isTrue(isNonNullObject({}));
-
-    assert.isTrue(isNonNullObject({ a: 1, b: 'test' }));
-
-    assert.isTrue(isNonNullObject({ nested: { value: true } }));
-  });
-
-  test('should return true for arrays', () => {
-    assert.isTrue(isNonNullObject([]));
-
-    assert.isTrue(isNonNullObject([1, 2, 3]));
-
-    assert.isTrue(isNonNullObject(['a', 'b', 'c']));
-  });
-
-  test('should return true for functions', () => {
-    assert.isFalse(isNonNullObject(() => {}));
-
-    assert.isFalse(isNonNullObject(async () => {}));
-
-    // eslint-disable-next-line @typescript-eslint/no-extraneous-class
-    assert.isFalse(isNonNullObject(class MyClass {}));
-  });
-
-  test('should return true for built-in objects', () => {
-    assert.isTrue(isNonNullObject(new Date()));
-
-    assert.isTrue(isNonNullObject(/test/u));
-
-    assert.isTrue(isNonNullObject(/regex/u));
-
-    assert.isTrue(isNonNullObject(new Map()));
-
-    assert.isTrue(isNonNullObject(new Set()));
-
-    assert.isTrue(isNonNullObject(new Error('test')));
-  });
-
-  test('should return true for boxed primitives', () => {
-    // eslint-disable-next-line unicorn/new-for-builtins, @typescript-eslint/no-deprecated
-    assert.isTrue(isNonNullObject(new String('hello')));
-
-    // eslint-disable-next-line unicorn/new-for-builtins, @typescript-eslint/no-deprecated
-    assert.isTrue(isNonNullObject(new Number(42)));
-
-    // eslint-disable-next-line unicorn/new-for-builtins, @typescript-eslint/no-deprecated
-    assert.isTrue(isNonNullObject(new Boolean(true)));
-  });
-
-  test('should return false for null', () => {
-    assert.isFalse(isNonNullObject(null));
-  });
-
-  test('should return false for primitive values', () => {
-    assert.isFalse(isNonNullObject(undefined));
-
-    assert.isFalse(isNonNullObject('string'));
-
-    assert.isFalse(isNonNullObject(42));
-
-    assert.isFalse(isNonNullObject(true));
-
-    assert.isFalse(isNonNullObject(false));
-
-    assert.isFalse(isNonNullObject(Symbol('test')));
-
-    assert.isFalse(isNonNullObject(123n));
-  });
-
-  test('should act as a type guard', () => {
-    const value: unknown = { test: true } as const;
-
-    if (isNonNullObject(value)) {
-      expectType<typeof value, object>('=');
-    }
-  });
-
-  test('should narrow nullable object types', () => {
-    const nullable: UnknownRecord | null =
-      Math.random() > 0.5 ? ({} as const) : null;
-
-    if (isNonNullObject(nullable)) {
-      expectType<typeof nullable, UnknownRecord>('=');
-    }
-  });
-
-  test('should work in filter operations', () => {
-    const mixed: readonly unknown[] = [
-      'string',
-      42,
-      { a: 1 },
-      null,
-      undefined,
-      [],
-      () => {},
-      true,
-    ] as const;
-
-    const objects = mixed.filter(isNonNullObject);
-
-    assert.deepStrictEqual(objects, [{ a: 1 }, []]);
-  });
-});