ts-data-forge 14.4.0 → 14.5.0

package/src/functional/result/impl/result-safe-try.mts

@@ -0,0 +1,110 @@
+import { hasKey, isRecord } from '../../../guard/index.mjs';
+import { type Err } from '../../../types.mjs';
+import { type Result, type UnknownResult } from '../result.mjs';
+import { type UnwrapErr, type UnwrapOk } from './types.mjs';
+
+/**
+ * Runs a generator body in which `yield* Result.safeUnwrap(...)` unwraps `Ok`
+ * values and short-circuits on the first `Err`, emulating Rust's `?` operator
+ * (early-return error propagation).
+ *
+ * The body must return a `Result`. If every unwrapped `Result` is `Ok`, the
+ * returned value is the body's `Result`; otherwise it is the first `Err`
+ * encountered, and the rest of the body never runs — though the generator is
+ * closed rather than dropped, so `finally` blocks and `using` disposals
+ * pending in the body still run. An exception thrown by the body is not
+ * converted to an `Err`: it propagates out of `safeTry` (as a rejected
+ * `Promise` for an async body). Use {@link Result.fromThrowable} for that.
+ *
+ * Passing an async generator (`async function*`) returns a
+ * `Promise<Result<...>>` instead, so `await` can be used inside the body.
+ * Note that `yield*` inside an `async function*` awaits what it receives, so
+ * unwrapping an `Ok` whose value is itself a `Promise` yields the awaited
+ * value there while the static type still says `Promise<...>`; keep promises
+ * out of the `Ok` side of a `Result` unwrapped in an async body.
+ *
+ * @example
+ *
+ * ```ts
+ * const parseTwo = (a: string, b: string): Result<number, Error> =>
+ *   Result.safeTry(function* () {
+ *     const x = yield* Result.safeUnwrap(Num.safeParseInt(a));
+ *
+ *     const y = yield* Result.safeUnwrap(Num.safeParseInt(b));
+ *
+ *     return Result.ok(x + y);
+ *   });
+ *
+ * assert.deepStrictEqual(parseTwo('1', '2'), Result.ok(3));
+ *
+ * assert.isTrue(Result.isErr(parseTwo('1', 'not a number')));
+ * ```
+ *
+ * @template Y The union of `Err` types unwrapped via
+ *   {@link Result.safeUnwrap} (`never` if nothing is unwrapped).
+ * @template R2 The `Result` type returned by the body.
+ * @param body A generator function whose `yield*` expressions delegate to
+ *   {@link Result.safeUnwrap} and whose return value is a `Result`.
+ * @returns The body's `Result`, or the first `Err` short-circuited out of it
+ *   (wrapped in a `Promise` for an async generator body).
+ */
+export function safeTry<Y extends Err<unknown>, R2 extends UnknownResult>(
+  body: () => Generator<Y, R2>,
+): Result<UnwrapOk<R2>, UnwrapErr<R2> | UnwrapErr<Y>>;
+
+export function safeTry<Y extends Err<unknown>, R2 extends UnknownResult>(
+  body: () => AsyncGenerator<Y, R2>,
+): Promise<Result<UnwrapOk<R2>, UnwrapErr<R2> | UnwrapErr<Y>>>;
+
+export function safeTry(
+  body:
+    | (() => AsyncGenerator<UnknownResult, UnknownResult>)
+    | (() => Generator<UnknownResult, UnknownResult>),
+): Promise<UnknownResult> | UnknownResult {
+  const generator = body();
+
+  // A yielded `Err` and a returned `Result` are both already the final
+  // answer, so the first step's `value` is the result in either case: the
+  // generator is closed rather than resumed after yielding.
+  const step = generator.next();
+
+  if (isSyncStep(step)) {
+    // Dropping a suspended generator would skip the `finally` blocks and
+    // `using` disposals still pending in the body; closing it runs them
+    // before the short-circuited `Err` is handed back. `isSyncGenerator` is
+    // what makes `return()` here synchronous rather than a floating promise.
+    if (step.done !== true && isSyncGenerator(generator, step)) {
+      generator.return(step.value);
+    }
+
+    return step.value;
+  }
+
+  return step.then(async (asyncStep) => {
+    if (asyncStep.done !== true) {
+      await generator.return(asyncStep.value);
+    }
+
+    return asyncStep.value;
+  });
+}
+
+// A sync generator's `next()` returns a plain `{ value, done }` object with
+// own properties, while an async generator's returns a `Promise`, whose
+// `then` lives on the prototype — so an own-key check on `done` separates the
+// two.
+const isSyncStep = (
+  value: unknown,
+): value is IteratorResult<UnknownResult, UnknownResult> =>
+  isRecord(value) && hasKey(value, 'done');
+
+// The generator-side counterpart of `isSyncStep`: a step in the sync form can
+// only have come from a sync generator, so the step is what narrows the
+// generator that produced it — hence the predicate reads its second argument
+// and not its first.
+const isSyncGenerator = (
+  _generator:
+    | AsyncGenerator<UnknownResult, UnknownResult>
+    | Generator<UnknownResult, UnknownResult>,
+  step: unknown,
+): _generator is Generator<UnknownResult, UnknownResult> => isSyncStep(step);

package/src/functional/result/impl/result-safe-unwrap.mts

@@ -0,0 +1,50 @@
+import { type UnknownResult } from '../result.mjs';
+import { isErr } from './result-is-err.mjs';
+import { type NarrowToErr, type UnwrapOk } from './types.mjs';
+
+/**
+ * Unwraps a `Result` inside a {@link Result.safeTry} generator body via
+ * `yield*`, emulating Rust's `?` operator.
+ *
+ * If the `Result` is `Ok`, the `yield*` expression evaluates to the contained
+ * value and execution continues. If it is `Err`, the error is yielded to
+ * {@link Result.safeTry}, which returns it immediately — the rest of the
+ * generator body never runs.
+ *
+ * This generator must only be delegated to (`yield*`) inside a
+ * {@link Result.safeTry} body; resuming it after it has yielded an `Err`
+ * throws.
+ *
+ * @example
+ *
+ * ```ts
+ * const result = Result.safeTry(function* () {
+ *   const x = yield* Result.safeUnwrap(Result.ok(2));
+ *
+ *   const y = yield* Result.safeUnwrap(Result.ok(3));
+ *
+ *   return Result.ok(x + y);
+ * });
+ *
+ * assert.deepStrictEqual(result, Result.ok(5));
+ * ```
+ *
+ * @template R The input `UnknownResult` type.
+ * @param result The `Result` to unwrap.
+ * @returns A generator that yields the `Err` (if any) and returns the `Ok`
+ *   value.
+ */
+export function* safeUnwrap<R extends UnknownResult>(
+  result: R,
+): Generator<NarrowToErr<R>, UnwrapOk<R>, unknown> {
+  if (isErr(result)) {
+    yield result;
+
+    throw new Error(
+      '`safeUnwrap()` generator was resumed after yielding an `Err`; it must only be used via `yield*` inside `safeTry()`',
+    );
+  }
+
+  // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+  return result.value as UnwrapOk<R>;
+}

package/src/functional/result.test.mts

@@ -1017,4 +1017,335 @@ describe('Result test', () => {
       >();
     });
   });
+
+  describe('match', () => {
+    test('should apply the ok case for Ok', () => {
+      const result = Result.match(Result.ok(21), {
+        ok: (value) => value * 2,
+        err: () => 0,
+      });
+
+      expectType<typeof result, number>('=');
+
+      assert.deepStrictEqual(result, 42);
+    });
+
+    test('should apply the err case for Err', () => {
+      const result = Result.match(Result.err('failure'), {
+        ok: () => 'ok',
+        err: (error) => `error: ${error}`,
+      });
+
+      assert.deepStrictEqual(result, 'error: failure');
+    });
+
+    test('should support Result union inputs', () => {
+      // Created through a function so that the const is not flow-narrowed to
+      // the Ok side.
+      const makeResult = (): Result<number, string> => Result.ok(2);
+
+      const result = makeResult();
+
+      const folded = Result.match(result, {
+        ok: (value) => value + 1,
+        err: (error) => error.length,
+      });
+
+      expectType<typeof folded, number>('=');
+
+      assert.deepStrictEqual(folded, 3);
+    });
+
+    test('curried version should work', () => {
+      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);
+    });
+
+    test('curried version should compose with Array.map and pipe', () => {
+      const matcher = Result.match({
+        ok: (value: number) => `ok:${value}`,
+        err: (error: string) => `err:${error}`,
+      });
+
+      const results: readonly Result<number, string>[] = [
+        Result.ok(1),
+        Result.err('bad'),
+      ] as const;
+
+      assert.deepStrictEqual(results.map(matcher), ['ok:1', 'err:bad']);
+
+      const single: Result<number, string> = Result.ok(3);
+
+      assert.deepStrictEqual(pipe(single).map(matcher).value, 'ok:3');
+    });
+  });
+
+  describe('fromOptional', () => {
+    test('should convert Some to Ok', () => {
+      const result = Result.fromOptional(Optional.some(42), 'missing');
+
+      expectType<typeof result, Result<42, 'missing'>>('=');
+
+      assert.deepStrictEqual(result, Result.ok(42));
+    });
+
+    test('should convert None to Err with the provided error', () => {
+      const result = Result.fromOptional(Optional.none, 'missing');
+
+      assert.isTrue(Result.isErr(result));
+
+      assert.deepStrictEqual(result.value, 'missing');
+    });
+
+    test('should convert Some(undefined) to Ok(undefined), not Err', () => {
+      const makeOptional = (): Optional<undefined> => Optional.some(undefined);
+
+      const result = Result.fromOptional(makeOptional(), 'missing');
+
+      assert.isTrue(Result.isOk(result));
+
+      assert.deepStrictEqual(result.value, undefined);
+    });
+
+    test('should support Optional union inputs', () => {
+      // Created through a function so that the const is not flow-narrowed to
+      // the Some side.
+      const makeOptional = (): Optional<number> => Optional.some(2);
+
+      const result = Result.fromOptional(makeOptional(), 'missing');
+
+      expectType<typeof result, Result<number, 'missing'>>('=');
+
+      assert.deepStrictEqual(result, Result.ok(2));
+    });
+
+    test('curried version should work', () => {
+      const withMissingError = Result.fromOptional('missing');
+
+      const result = withMissingError(Optional.some(1));
+
+      expectType<typeof result, Result<1, 'missing'>>('=');
+
+      assert.deepStrictEqual(result, Result.ok(1));
+
+      assert.deepStrictEqual(
+        withMissingError(Optional.none),
+        Result.err('missing'),
+      );
+    });
+  });
+
+  describe('safeTry', () => {
+    test('should return the body result when every yielded Result is Ok', () => {
+      const result = Result.safeTry(function* () {
+        const x = yield* Result.safeUnwrap(Result.ok(2));
+
+        const y = yield* Result.safeUnwrap(Result.ok(3));
+
+        return Result.ok(x + y);
+      });
+
+      expectType<typeof result, Result<number, never>>('=');
+
+      assert.deepStrictEqual(result, Result.ok(5));
+    });
+
+    test('should short-circuit on the first Err', () => {
+      const makeFailing = (): Result<number, string> =>
+        Result.err('first error');
+
+      const failing = makeFailing();
+
+      let mut_reached = false;
+
+      const result = Result.safeTry(function* () {
+        const x = yield* Result.safeUnwrap(failing);
+
+        mut_reached = true;
+
+        return Result.ok(x);
+      });
+
+      assert.isFalse(mut_reached);
+
+      assert.deepStrictEqual(result, Result.err('first error'));
+    });
+
+    test('should collect error types from yields and the return', () => {
+      const makeSource = (): Result<number, 'e1'> => Result.ok(1);
+
+      const source = makeSource();
+
+      const result = Result.safeTry(function* () {
+        const x = yield* Result.safeUnwrap(source);
+
+        if (x > 0) {
+          return Result.err('e2');
+        }
+
+        return Result.ok(x);
+      });
+
+      expectType<typeof result, Result<number, 'e1' | 'e2'>>('=');
+
+      assert.deepStrictEqual(result, Result.err('e2'));
+    });
+
+    test('async generator should return a Promise of the body result', async () => {
+      const result = await Result.safeTry(async function* () {
+        const x = yield* Result.safeUnwrap(
+          await Result.fromPromise(Promise.resolve(10)),
+        );
+
+        return Result.ok(x + 1);
+      });
+
+      assert.deepStrictEqual(result, Result.ok(11));
+    });
+
+    test('async generator should short-circuit on Err', async () => {
+      const makeFailing = (): Promise<Result<number, string>> =>
+        Promise.resolve(Result.err('async error'));
+
+      let mut_reached = false;
+
+      const promise = Result.safeTry(async function* () {
+        const x = yield* Result.safeUnwrap(await makeFailing());
+
+        mut_reached = true;
+
+        return Result.ok(x);
+      });
+
+      expectType<typeof promise, Promise<Result<number, string>>>('=');
+
+      const result = await promise;
+
+      assert.isFalse(mut_reached);
+
+      assert.deepStrictEqual(result, Result.err('async error'));
+    });
+
+    test('should run pending `finally` blocks when short-circuiting', () => {
+      // Created through a function so that the const is not flow-narrowed to
+      // the Err side.
+      const makeFailing = (): Result<number, string> => Result.err('boom');
+
+      let mut_cleanedUp = false;
+
+      const result = Result.safeTry(function* () {
+        try {
+          const x = yield* Result.safeUnwrap(makeFailing());
+
+          return Result.ok(x);
+        } finally {
+          mut_cleanedUp = true;
+        }
+      });
+
+      assert.isTrue(mut_cleanedUp);
+
+      assert.deepStrictEqual(result, Result.err('boom'));
+    });
+
+    test('should propagate an exception thrown by the body', () => {
+      expect(() =>
+        Result.safeTry(function* () {
+          const x = yield* Result.safeUnwrap(Result.ok(1));
+
+          throw new Error(`boom: ${x}`);
+        }),
+      ).toThrow('boom: 1');
+    });
+
+    test('async generator should reject on an exception thrown by the body', async () => {
+      await expect(
+        Result.safeTry(async function* () {
+          const x = yield* Result.safeUnwrap(
+            await Promise.resolve(Result.ok(1)),
+          );
+
+          throw new Error(`boom: ${x}`);
+        }),
+      ).rejects.toThrow('boom: 1');
+    });
+
+    test('should propagate through a delegating helper generator', () => {
+      const makeSource = (): Result<number, 'e1'> => Result.err('e1');
+
+      const doubled = function* (): Generator<Err<'e1'>, number, unknown> {
+        const x = yield* Result.safeUnwrap(makeSource());
+
+        return x * 2;
+      };
+
+      const result = Result.safeTry(function* () {
+        const y = yield* doubled();
+
+        return Result.ok(y);
+      });
+
+      expectType<typeof result, Result<number, 'e1'>>('=');
+
+      assert.deepStrictEqual(result, Result.err('e1'));
+    });
+
+    test('async generator should run pending `finally` blocks too', async () => {
+      const makeFailing = (): Promise<Result<number, string>> =>
+        Promise.resolve(Result.err('boom'));
+
+      let mut_cleanedUp = false;
+
+      const result = await Result.safeTry(async function* () {
+        try {
+          const x = yield* Result.safeUnwrap(await makeFailing());
+
+          return Result.ok(x);
+        } finally {
+          mut_cleanedUp = true;
+        }
+      });
+
+      assert.isTrue(mut_cleanedUp);
+
+      assert.deepStrictEqual(result, Result.err('boom'));
+    });
+  });
+
+  describe('safeUnwrap', () => {
+    test('should return the value without yielding for an Ok', () => {
+      const generator = Result.safeUnwrap(Result.ok(7));
+
+      assert.deepStrictEqual(generator.next(), { done: true, value: 7 });
+    });
+
+    test('should yield the Err itself for an Err', () => {
+      const makeFailing = (): Result<number, string> => Result.err('boom');
+
+      const generator = Result.safeUnwrap(makeFailing());
+
+      assert.deepStrictEqual(generator.next(), {
+        done: false,
+        value: Result.err('boom'),
+      });
+    });
+
+    test('should throw if resumed after yielding an Err', () => {
+      const makeFailing = (): Result<number, string> => Result.err('boom');
+
+      const generator = Result.safeUnwrap(makeFailing());
+
+      generator.next();
+
+      expect(() => generator.next()).toThrow(
+        'it must only be used via `yield*` inside `safeTry()`',
+      );
+    });
+  });
 });

package/src/guard/is-error.test.mts

@@ -1,4 +1,3 @@
-/* eslint-disable functional/immutable-data */
 /* eslint-disable functional/no-class-inheritance */
 /* eslint-disable unicorn/error-message */
 import { isError as isErrorBySindreSorhus } from '@sindresorhus/is';
@@ -129,14 +128,15 @@ describe('isError from @sindresorhus/is', () => {
   });
 
   test('should return false for errors created with Object.create', () => {
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
-    const protoError = Object.create(Error.prototype);
+    // Built and then re-pointed rather than `Object.create(Error.prototype)`,
+    // which the strict standard library types as `unknown` — correctly, since
+    // it knows nothing about the resulting shape. The object under test is the
+    // same: Error.prototype in its chain, never constructed as an Error.
+    const mut_protoError = { message: 'proto error', name: 'ProtoError' };
 
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
-    protoError.message = 'proto error';
+    Object.setPrototypeOf(mut_protoError, Error.prototype);
 
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
-    protoError.name = 'ProtoError';
+    const protoError = mut_protoError;
 
     assert.isFalse(isErrorBySindreSorhus(protoError));
   });

package/src/others/debounce-function.mts

@@ -11,7 +11,11 @@ export const debounce = <Args extends readonly unknown[]>(
   func: (...args: Args) => void,
   waitMilliseconds: number,
 ): ((...args: Args) => void) => {
-  let mut_timeoutId: ReturnType<typeof setTimeout> | undefined;
+  // Not `ReturnType<typeof setTimeout>`: with both the DOM and Node
+  // declarations in scope that resolves to `unknown`, which `clearTimeout`
+  // will not take. Naming what `clearTimeout` accepts says the same thing and
+  // stays true in either environment.
+  let mut_timeoutId: Parameters<typeof clearTimeout>[0];
 
   return (...args: Args): void => {
     clearTimeout(mut_timeoutId);

package/src/others/fast-deep-equal.mts

@@ -94,6 +94,13 @@ export const fastDeepEqual = <T,>(a: T, b: T): boolean => {
     );
   }
 
-  // true if both NaN, false otherwise
-  return Number.isNaN(a) && Number.isNaN(b);
+  // true if both NaN, false otherwise. `Number.isNaN` takes a number: called
+  // with anything else it is always false, so the check belongs behind a
+  // `typeof` guard rather than relying on that.
+  return (
+    typeof a === 'number' &&
+    typeof b === 'number' &&
+    Number.isNaN(a) &&
+    Number.isNaN(b)
+  );
 };