ts-data-forge 14.6.3 → 14.7.0

package/src/functional/pipe.mts

@@ -1,180 +0,0 @@
-import { expectType } from '../expect-type.mjs';
-import { Optional, type UnknownOptional } from './optional/index.mjs';
-
-/**
- * Creates a new pipe object that allows for chaining operations on a value.
- *
- * This function provides a fluent interface for applying transformations to
- * values, with intelligent method selection based on the input type:
- *
- * - For `Optional` values: Provides `mapOptional` for safe Optional
- *   transformations
- * - For other values: Provides `mapNullable` for null-safe transformations
- * - All types get the basic `map` method for general transformations
- *
- * The pipe maintains type safety throughout the chain, automatically selecting
- * the appropriate overload based on the current value type.
- *
- * @template A The type of the initial value to wrap in a pipe.
- * @param a The initial value to wrap in a pipe.
- * @returns A pipe object with chaining methods appropriate for the value type.
- */
-export const pipe = <const A,>(a: A): Pipe<A> =>
-  // eslint-disable-next-line total-functions/no-unsafe-type-assertion
-  ({
-    value: a,
-    map: (fn) => pipe(fn(a)),
-    mapNullable: (fn) => pipe(a == null ? undefined : fn(a)),
-
-    ...(Optional.isOptional(a)
-      ? {
-          mapOptional: (fn) => pipe(Optional.map(a, fn)),
-        }
-      : {}),
-  }) satisfies PipeImpl<A> as unknown as Pipe<A>;
-
-// `PipeBase<A>` is always present; the conditional only *adds* `mapOptional`
-// for Optional values. Two subtleties motivate this shape:
-//
-//   1. The check is `[A] extends [UnknownOptional]` (a 1-tuple), not the bare
-//      `A extends UnknownOptional`. A bare check distributes over unions, so a
-//      piped union value such as `Result<D, E> | undefined` would expand into
-//      `Pipe<Ok<D>> | Pipe<Err<E>> | Pipe<undefined>`. Calling a chained method
-//      on that union of pipe objects forces TypeScript to synthesize a merged
-//      call signature, during which a branded member like `Ok<D>` is widened to
-//      its constraint (`Ok<number>`) — losing the brand `D`.
-//
-//   2. `value: A` lives on `PipeBase<A>`, *outside* the conditional. If `value`
-//      flowed through the conditional, then for a not-yet-resolved generic `A`
-//      the deferred true branch narrows `A` to `A & UnknownOptional`, so
-//      `.value` would surface as the noisy `(A & UnknownOptional) | A`. Keeping
-//      it on the unconditional base yields a clean `A`.
-export type Pipe<A> = PipeBase<A> &
-  PipeMapNullable<A> &
-  ([A] extends [UnknownOptional] ? PipeMapOptional<A> : unknown);
-
-// NOTE: 以下では 'typing when used with generics' test で型エラーが出る。
-// 詳細は documents/reports/pipe-typing.md の 「mapNullable を条件付きで含めるのがうまくいかない理由」を参照。
-// export type Pipe<A> = PipeBase<A> &
-//   ([A] extends [UnknownOptional] ? PipeMapOptional<A> : unknown) &
-//   ([undefined] extends [A] ? PipeMapNullable<A> : unknown) &
-//   ([null] extends [A] ? PipeMapNullable<A> : unknown);
-
-expectType<Optional<number>, UnknownOptional>('<=');
-
-expectType<number | undefined, undefined>('>=');
-
-expectType<keyof Pipe<number | undefined>, 'value' | 'map' | 'mapNullable'>(
-  '=',
-);
-
-expectType<
-  keyof Pipe<Optional<number>>,
-  'value' | 'map' | 'mapNullable' | 'mapOptional'
->('=');
-
-expectType<
-  keyof Pipe<Optional<number | undefined>>,
-  'value' | 'map' | 'mapNullable' | 'mapOptional'
->('=');
-
-expectType<
-  keyof Pipe<Optional<number> | undefined>,
-  'value' | 'map' | 'mapNullable'
->('=');
-
-type PipeBase<A> = Readonly<{
-  /** The current value being piped. */
-  value: A;
-
-  /**
-   * Maps the current value to a new value using the provided function.
-   *
-   * @example
-   *
-   * ```ts
-   * const result = pipe(2)
-   *   .map((value) => value * 3)
-   *   .map((value) => `value: ${value}`);
-   *
-   * assert.deepStrictEqual(result.value, 'value: 6');
-   * ```
-   *
-   * @template B The type of the new value.
-   * @param fn Function to transform the current value.
-   * @returns A new pipe containing the transformed value.
-   */
-  map: <B>(fn: (a: A) => B) => Pipe<B>;
-}>;
-
-type PipeMapNullable<A> = Readonly<{
-  /**
-   * Maps the current value only if it's not null or undefined. If the current
-   * value is null/undefined, the transformation is skipped and undefined is
-   * propagated through the pipe.
-   *
-   * @example
-   *
-   * ```ts
-   * const result = pipe<string | undefined>('hello')
-   *   .mapNullable((value) => value.toUpperCase())
-   *   .mapNullable((value) => value.slice(0, 2));
-   *
-   * assert.deepStrictEqual(result.value, 'HE');
-   *
-   * const empty = pipe<string | undefined>(undefined).mapNullable((value) =>
-   *   value.toUpperCase(),
-   * );
-   *
-   * assert.isTrue(empty.value === undefined);
-   * ```
-   *
-   * @template B The type of the transformed value.
-   * @param fn Function to transform the non-null value.
-   * @returns A new pipe containing the transformed value or undefined.
-   */
-  mapNullable: <B>(fn: (a: NonNullable<A>) => B) => Pipe<B | undefined>;
-}>;
-
-type PipeMapOptional<A extends UnknownOptional> = Readonly<{
-  /**
-   * Maps the value inside an Optional using Optional.map semantics. If the
-   * Optional is None, the transformation is skipped and None is propagated.
-   * If the Optional is Some, the transformation is applied to the inner
-   * value.
-   *
-   * @example
-   *
-   * ```ts
-   * const result = pipe(Optional.some(10))
-   *   .mapOptional((value) => value * 2)
-   *   .mapOptional((value) => value + 5);
-   *
-   * assert.deepStrictEqual(result.value, Optional.some(25));
-   *
-   * const empty = pipe(Optional.none as Optional<number>).mapOptional(
-   *   (value) => value * 2,
-   * );
-   *
-   * assert.isTrue(Optional.isNone(empty.value));
-   * ```
-   *
-   * @template B The type of the transformed inner value.
-   * @param fn Function to transform the inner value of the Optional.
-   * @returns A new pipe containing an Optional with the transformed value.
-   */
-  mapOptional: <B>(fn: (a: Optional.Unwrap<A>) => B) => Pipe<Optional<B>>;
-}>;
-
-/** @internal */
-type Cast<T, U> = T & U;
-
-/** @internal */
-type PipeImpl<A> = Readonly<{
-  value: A;
-  map: <B>(fn: (a: A) => B) => PipeImpl<B>;
-  mapNullable?: <B>(fn: (a: NonNullable<A>) => B) => PipeImpl<B | undefined>;
-  mapOptional?: <B>(
-    fn: (a: Optional.Unwrap<Cast<A, UnknownOptional>>) => B,
-  ) => PipeImpl<Optional<B>>;
-}>;

package/src/functional/pipe.test.mts

@@ -1,155 +0,0 @@
-import { expectType } from '../expect-type.mjs';
-import { Num } from '../number/index.mjs';
-import { type None, type Some } from '../types.mjs';
-import { Optional } from './optional/index.mjs';
-import { pipe } from './pipe.mjs';
-import { Result } from './result/index.mjs';
-
-describe(pipe, () => {
-  test('basic pipe operations', () => {
-    const result = pipe(5)
-      .map((x) => x * 2)
-      .map((x) => x + 1).value;
-
-    expect(result).toBe(11);
-
-    expectType<typeof result, number>('=');
-  });
-
-  test('pipe with string operations', () => {
-    const result = pipe('hello')
-      .map((s) => s.toUpperCase())
-      .map((s) => `${s}!`).value;
-
-    expect(result).toBe('HELLO!');
-
-    expectType<typeof result, string>('=');
-  });
-
-  test('pipe with array operations', () => {
-    const result = pipe([1, 2, 3])
-      .map((arr) => arr.map((x) => x * 2))
-      .map((arr) => arr.length).value;
-
-    expect(result).toBe(3);
-
-    expectType<typeof result, number>('=');
-  });
-
-  test('mapNullable with non-null value', () => {
-    const s = 5 as number | null;
-
-    const result = pipe(s).mapNullable((x) => x * 2).value;
-
-    expect(result).toBe(10);
-
-    expectType<typeof result, number | undefined>('=');
-  });
-
-  test('mapNullable with null value', () => {
-    const result = pipe(null as number | null).mapNullable((x) => x * 2).value;
-
-    expect(result).toBeUndefined();
-
-    expectType<typeof result, number | undefined>('=');
-  });
-
-  test('mapNullable with undefined value', () => {
-    const result = pipe(undefined as number | undefined).mapNullable(
-      (x) => x * 2,
-    ).value;
-
-    expect(result).toBeUndefined();
-
-    expectType<typeof result, number | undefined>('=');
-  });
-
-  test('mapOptional with Some value', () => {
-    const optional = Optional.some(42);
-
-    const result = pipe(optional).mapOptional((x) => x * 2).value;
-
-    assert.isTrue(Optional.isSome(result));
-
-    if (Optional.isSome(result)) {
-      expect(result.value).toBe(84);
-    }
-
-    expectType<typeof result, Some<number>>('=');
-  });
-
-  test('mapOptional with None value', () => {
-    const optional: Optional<number> = Optional.none;
-
-    const result = pipe(optional).mapOptional((x) => x * 2).value;
-
-    assert.isTrue(Optional.isNone(result));
-
-    expectType<typeof result, None>('=');
-  });
-
-  test('chaining multiple operations', () => {
-    const result = pipe('5')
-      .map((s) => Result.unwrapOkOr(Num.safeParseInt(s), Number.NaN))
-      .map((n) => n * 3)
-      .map((n) => n.toString())
-      .map((s) => `${s} items`).value;
-
-    expect(result).toBe('15 items');
-
-    expectType<typeof result, string>('=');
-  });
-
-  test('typing when used with Result', () => {
-    const validate = <D,>(_u: unknown): Result<D, unknown> =>
-      Result.err(undefined);
-
-    const decodeBranded = (
-      input: string,
-      parse: (s: string) => number | undefined,
-    ): number | undefined => {
-      const v = pipe(input)
-        .map(parse)
-        .mapNullable(validate<number>)
-        .mapNullable((res) => Result.unwrapOk(res)).value;
-
-      expectType<typeof v, number | undefined>('=');
-
-      return v;
-    };
-
-    expect(decodeBranded('', () => undefined)).toBeUndefined();
-  });
-
-  test('typing when used with generics', () => {
-    const validate = <D,>(_u: unknown): Result<D, unknown> =>
-      Result.err(undefined);
-
-    // Regression: a generic brand `D` must survive the whole chain.
-    //
-    // The trigger is a `.map` whose result is a branded *union* such as
-    // `D | undefined`. If `Pipe<A>` distributes over unions, that step expands
-    // into `Pipe<D> | Pipe<undefined>`; calling the next method on the union of
-    // pipe objects then widens `D` to its constraint `number`, so `.value`
-    // collapses to `number | undefined` instead of `D | undefined`.
-    //
-    // The explicit `D | undefined` return annotation is itself the assertion:
-    // were the brand lost, `.value` would be `number | undefined` and the
-    // body would fail to compile.
-    const decodeBranded = <D extends number>(
-      input: string,
-      parse: (s: string) => D | undefined,
-    ): D | undefined => {
-      const v = pipe(input)
-        .map(parse)
-        .mapNullable(validate<D>)
-        .mapNullable((res) => Result.unwrapOk(res)).value;
-
-      expectType<typeof v, D | undefined>('=');
-
-      return v;
-    };
-
-    expect(decodeBranded('', () => undefined)).toBeUndefined();
-  });
-});

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

@@ -1,27 +0,0 @@
-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';
-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';
-export * from './result-unwrap-err-throw.mjs';
-export * from './result-unwrap-err.mjs';
-export * from './result-unwrap-ok-or.mjs';
-export * from './result-unwrap-ok.mjs';
-export * from './result-unwrap-throw.mjs';
-export * from './result-zip.mjs';
-export * from './types.mjs';

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

@@ -1,33 +0,0 @@
-import { type Err } from '../../../types.mjs';
-import { ErrTypeTagName } from './tag.mjs';
-
-/**
- * Creates a `Result.Err` containing the given error value.
- *
- * Use this constructor when an operation fails and you want to wrap the error
- * information 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 E The type of the error value.
- * @param value The error value.
- * @returns A `Result.Err<E>` containing the value.
- */
-export const err = <const E,>(value: E): Err<E> =>
-  ({
-    $$tag: ErrTypeTagName,
-    value,
-  }) as const;

package/src/functional/result/impl/result-expect-to-be.mts

@@ -1,73 +0,0 @@
-import { type UnknownResult } from '../result.mjs';
-import { isOk } from './result-is-ok.mjs';
-import { unwrapOk } from './result-unwrap-ok.mjs';
-import { type UnwrapOk } from './types.mjs';
-
-/**
- * Unwraps a `Result`, returning the success value or throwing an error with
- * the provided message.
- *
- * @example
- *
- * ```ts
- * const okValue = Result.ok('data');
- *
- * assert.isTrue(Result.expectToBe(okValue, 'should have value') === 'data');
- *
- * const expectResult = Result.expectToBe('missing result');
- *
- * const throwTest = (): void => {
- *   expectResult(Result.err('boom'));
- * };
- *
- * assert.throws(throwTest, /missing result/u);
- *
- * assert.isTrue(expectResult(Result.ok('value')) === 'value');
- * ```
- *
- * @template R The `UnknownResult` type to unwrap.
- * @param result The `Result` to unwrap.
- * @param message The error message to throw if the `Result` is `Result.Err`.
- * @returns The success value if `Result.Ok`.
- * @throws Error with the provided message if the `Result` is `Result.Err`.
- */
-export function expectToBe<R extends UnknownResult>(
-  result: R,
-  message: string,
-): UnwrapOk<R>;
-
-// Curried version
-export function expectToBe(
-  message: string,
-): <R extends UnknownResult>(result: R) => UnwrapOk<R>;
-
-export function expectToBe<R extends UnknownResult>(
-  ...args: readonly [result: R, message: string] | readonly [message: string]
-): UnwrapOk<R> | ((result: R) => UnwrapOk<R>) {
-  switch (args.length) {
-    case 2: {
-      // Direct version: first argument is result
-      const [result, message] = args;
-
-      return expectToBeImpl(result, message);
-    }
-
-    case 1: {
-      // Curried version: first argument is message
-      const [message] = args;
-
-      return (result: R): UnwrapOk<R> => expectToBeImpl(result, message);
-    }
-  }
-}
-
-const expectToBeImpl = <R extends UnknownResult>(
-  result: R,
-  message: string,
-): UnwrapOk<R> => {
-  if (isOk(result)) {
-    return unwrapOk(result);
-  }
-
-  throw new Error(message);
-};

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

@@ -1,88 +0,0 @@
-import { type Err } from '../../../types.mjs';
-import { type Result, type UnknownResult } from '../result.mjs';
-import { isErr } from './result-is-err.mjs';
-import { type UnwrapErr, type UnwrapOk } from './types.mjs';
-
-/**
- * Applies a function that returns a `Result` to the success value of a
- * `Result`. If the input is `Err`, returns the original `Err`. This is the
- * monadic bind operation for `Result`.
- *
- * @example
- *
- * ```ts
- * const parseNumber = (input: string): Result<number, string> => {
- *   const num = Num.safeParseInt(input);
- *
- *   return Result.mapErr(num, () => 'not a number');
- * };
- *
- * const parsed = Result.flatMap(Result.ok('42'), parseNumber);
- *
- * const failure = Result.flatMap(Result.ok('abc'), parseNumber);
- *
- * const passthrough = Result.flatMap(Result.err('fail'), parseNumber);
- *
- * assert.deepStrictEqual(parsed, Result.ok(42));
- *
- * assert.deepStrictEqual(failure, Result.err('not a number'));
- *
- * assert.deepStrictEqual(passthrough, Result.err('fail'));
- *
- * const parseThenDouble = Result.flatMap((input: string) =>
- *   Result.map(parseNumber(input), (value) => value * 2),
- * );
- *
- * assert.deepStrictEqual(parseThenDouble(Result.ok('10')), Result.ok(20));
- * ```
- *
- * @template R The input `UnknownResult` type.
- * @template S2 The success type of the `Result` returned by the function.
- * @template E2 The error type of the `Result` returned by the function.
- * @param result The `Result` to flat map.
- * @param flatMapFn The function to apply that returns a `Result`.
- * @returns The result of applying the function, or the original `Err`.
- */
-export function flatMap<R extends UnknownResult, S2, E2>(
-  result: R,
-  flatMapFn: (value: UnwrapOk<R>) => Result<S2, E2>,
-): Result<S2, E2 | UnwrapErr<R>>;
-
-// Curried version
-export function flatMap<S, S2, E2>(
-  flatMapFn: (value: S) => Result<S2, E2>,
-): <E>(result: Result<S, E>) => Result<S2, E | E2>;
-
-export function flatMap<R extends UnknownResult, S2, E2>(
-  ...args:
-    | readonly [result: R, flatMapFn: (value: UnwrapOk<R>) => Result<S2, E2>]
-    | readonly [flatMapFn: (value: UnwrapOk<R>) => Result<S2, E2>]
-):
-  | Result<S2, E2 | UnwrapErr<R>>
-  | ((result: R) => Result<S2, UnwrapErr<R> | E2>) {
-  switch (args.length) {
-    case 2: {
-      // Direct version: first argument is result
-      const [result, flatMapFn] = args;
-
-      return flatMapImpl(result, flatMapFn);
-    }
-
-    case 1: {
-      // Curried version
-      const [flatMapFn] = args;
-
-      return (result: R) => flatMapImpl(result, flatMapFn);
-    }
-  }
-}
-
-const flatMapImpl = <R extends UnknownResult, S2, E2>(
-  result: R,
-  flatMapFn: (value: UnwrapOk<R>) => Result<S2, E2>,
-): Result<S2, E2 | 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
-      flatMapFn(result.value as UnwrapOk<R>);

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

@@ -1,102 +0,0 @@
-import { type Result, type UnknownResult } from '../result.mjs';
-import { err } from './result-err.mjs';
-import { isOk } from './result-is-ok.mjs';
-import { ok } from './result-ok.mjs';
-import { type UnwrapErr, type UnwrapOk } from './types.mjs';
-
-/**
- * Applies one of two functions depending on whether the `Result` is `Ok` or
- * `Err`.
- *
- * @example
- *
- * ```ts
- * const okValue = Result.ok(2);
- *
- * const errValue = Result.err('bad');
- *
- * const foldedOk = Result.fold(
- *   okValue,
- *   (value) => value * 2,
- *   (error) => error,
- * );
- *
- * const foldedErr = Result.fold(
- *   errValue,
- *   (value: number) => value * 2,
- *   (error) => error.toUpperCase(),
- * );
- *
- * assert.deepStrictEqual(foldedOk, Result.ok(4));
- *
- * assert.deepStrictEqual(foldedErr, Result.err('BAD'));
- *
- * const foldNumbers = Result.fold(
- *   (value: number) => value * 3,
- *   (error: string) => error.length,
- * );
- *
- * assert.deepStrictEqual(foldNumbers(Result.ok(3)), Result.ok(9));
- *
- * assert.deepStrictEqual(foldNumbers(Result.err('oops')), Result.err(4));
- * ```
- *
- * @template R The input `UnknownResult` type.
- * @template S2 The type of the success value returned by `mapFn`.
- * @template E2 The type of the error value returned by `mapErrFn`.
- * @param result The `Result` to fold.
- * @param mapFn The function to apply if `result` is `Ok`.
- * @param mapErrFn The function to apply if `result` is `Err`.
- * @returns A new `Result<S2, E2>` based on the applied function.
- */
-export function fold<R extends UnknownResult, S2, E2>(
-  result: R,
-  mapFn: (value: UnwrapOk<R>) => S2,
-  mapErrFn: (error: UnwrapErr<R>) => E2,
-): Result<S2, E2>;
-
-// Curried version
-export function fold<S, E, S2, E2>(
-  mapFn: (value: S) => S2,
-  mapErrFn: (error: E) => E2,
-): (result: Result<S, E>) => Result<S2, E2>;
-
-export function fold<R extends UnknownResult, S2, E2>(
-  ...args:
-    | readonly [
-        result: R,
-        mapFn: (value: UnwrapOk<R>) => S2,
-        mapErrFn: (error: UnwrapErr<R>) => E2,
-      ]
-    | readonly [
-        mapFn: (value: UnwrapOk<R>) => S2,
-        mapErrFn: (error: UnwrapErr<R>) => E2,
-      ]
-): Result<S2, E2> | ((result: R) => Result<S2, E2>) {
-  switch (args.length) {
-    case 3: {
-      // Direct version: first argument is result
-      const [result, mapFn, mapErrFn] = args;
-
-      return foldImpl(result, mapFn, mapErrFn);
-    }
-
-    case 2: {
-      // Curried version
-      const [mapFn, mapErrFn] = args;
-
-      return (result: R) => foldImpl(result, mapFn, mapErrFn);
-    }
-  }
-}
-
-const foldImpl = <R extends UnknownResult, S2, E2>(
-  result: R,
-  mapFn: (value: UnwrapOk<R>) => S2,
-  mapErrFn: (error: UnwrapErr<R>) => E2,
-): Result<S2, E2> =>
-  isOk(result)
-    ? // eslint-disable-next-line total-functions/no-unsafe-type-assertion
-      ok(mapFn(result.value as UnwrapOk<R>))
-    : // eslint-disable-next-line total-functions/no-unsafe-type-assertion
-      err(mapErrFn(result.value as UnwrapErr<R>));