ts-data-forge 14.3.0 → 14.5.0

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/object/object.mts

@@ -17,6 +17,7 @@ import {
   type UnknownRecord,
 } from 'ts-type-forge';
 import { Arr } from '../array/index.mjs';
+import { Optional } from '../functional/index.mjs';
 import { hasKey, isRecord } from '../guard/index.mjs';
 
 /**
@@ -397,6 +398,171 @@ export namespace Obj {
     );
   };
 
+  /**
+   * Keeps the entries whose value the predicate accepts, leaving the values
+   * themselves untouched.
+   *
+   * **Type Behavior**: the surviving keys are the keys of the source record,
+   * made optional — the predicate may reject any of them. A record keyed by an
+   * index signature stays total instead, because it names no specific key that
+   * could go missing.
+   *
+   * Passing a type guard narrows the value type of the result, which is what
+   * `Object.fromEntries(Object.entries(record).filter(guard))` loses.
+   *
+   * **Key handling**: keys reach the callback the way `Object.entries` yields
+   * them, so a numeric key `1` arrives as `'1'`. Symbol-keyed properties are
+   * not enumerated by `Object.entries`; they are dropped from both the result
+   * and its type.
+   *
+   * @example
+   *
+   * <!-- doc:embed:jsdoc:example:./samples/src/object/filter-example.mts -->
+   *
+   * ```ts
+   * const scores = { alice: 1, bob: 2 } as const;
+   *
+   * const passing = Obj.filter(scores, (value) => value > 1);
+   *
+   * assert.deepStrictEqual(passing, { bob: 2 });
+   *
+   * // The key is available as the second argument.
+   * const notAlice = Obj.filter(scores, (_value, key) => key !== 'alice');
+   *
+   * assert.deepStrictEqual(notAlice, { bob: 2 });
+   *
+   * // A type guard narrows the value type of the result.
+   * const mixed: UnknownRecord = { a: 1, b: 'x' } as const;
+   *
+   * const strings = Obj.filter(mixed, isString);
+   *
+   * assert.deepStrictEqual(strings, { b: 'x' });
+   * ```
+   *
+   * <!-- /doc:embed:jsdoc:example:./samples/src/object/filter-example.mts -->
+   *
+   * @template R - The type of the source record
+   * @template V2 - The type the guard narrows values to
+   * @param record - The record whose entries are filtered
+   * @param predicate - Called once per own enumerable string key, with the
+   *   value and the key
+   * @returns A new record holding only the accepted entries
+   */
+  export function filter<const R extends UnknownRecord, V2 extends R[keyof R]>(
+    record: R,
+    predicate: (
+      value: R[keyof R],
+      key: TsDataForgeInternals.MappedRecordKey<R>,
+    ) => value is V2,
+  ): TsDataForgeInternals.FilteredRecord<
+    TsDataForgeInternals.MappedRecord<R, V2>
+  >;
+
+  export function filter<const R extends UnknownRecord>(
+    record: R,
+    predicate: (
+      value: R[keyof R],
+      key: TsDataForgeInternals.MappedRecordKey<R>,
+    ) => boolean,
+  ): TsDataForgeInternals.FilteredRecord<R>;
+
+  export function filter<const R extends UnknownRecord>(
+    record: R,
+    predicate: (
+      value: R[keyof R],
+      key: TsDataForgeInternals.MappedRecordKey<R>,
+    ) => boolean,
+  ): TsDataForgeInternals.FilteredRecord<R> {
+    // `Object.entries` erases both the key and the value type of `R`, so the
+    // callback is widened once here instead of asserting on every entry.
+    // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+    const predicateWidened = predicate as (
+      value: unknown,
+      key: string,
+    ) => boolean;
+
+    return (
+      // `Object.entries` enumerates exactly the own enumerable string keys of
+      // `record`, and filtering only ever removes entries, so the result has a
+      // subset of those keys — which is what `FilteredRecord` claims.
+      // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+      Object.fromEntries(
+        Object.entries(record).filter(([k, v]) => predicateWidened(v, k)),
+      ) as never
+    );
+  }
+
+  /**
+   * Transforms and drops entries in one pass: the callback returns
+   * `Optional.some(value)` to keep an entry with a new value, or
+   * `Optional.none` to drop it.
+   *
+   * **Type Behavior**: as with {@link filter}, the surviving keys are the keys
+   * of the source record made optional, and a record keyed by an index
+   * signature stays total. Unlike {@link filter}, every kept value takes the
+   * type the callback returns.
+   *
+   * `Optional` rather than `undefined` marks the dropped entries, so a record
+   * whose values are legitimately `undefined` stays expressible.
+   *
+   * **Key handling**: keys reach the callback the way `Object.entries` yields
+   * them, so a numeric key `1` arrives as `'1'`. Symbol-keyed properties are
+   * not enumerated by `Object.entries`; they are dropped from both the result
+   * and its type.
+   *
+   * @example
+   *
+   * <!-- doc:embed:jsdoc:example:./samples/src/object/filter-map-example.mts -->
+   *
+   * ```ts
+   * const scores = { alice: 1, bob: 2 } as const;
+   *
+   * // `Optional.some` keeps an entry with a new value, `Optional.none` drops it.
+   * const labelled = Obj.filterMap(scores, (value, key) =>
+   *   value > 1 ? Optional.some(`${key}=${value}`) : Optional.none,
+   * );
+   *
+   * assert.deepStrictEqual(labelled, { bob: 'bob=2' });
+   * ```
+   *
+   * <!-- /doc:embed:jsdoc:example:./samples/src/object/filter-map-example.mts -->
+   *
+   * @template R - The type of the source record
+   * @template V2 - The type the callback returns for the entries it keeps
+   * @param record - The record whose entries are transformed and filtered
+   * @param mapFn - Called once per own enumerable string key, with the value
+   *   and the key
+   * @returns A new record holding only the kept entries, with mapped values
+   */
+  export const filterMap = <const R extends UnknownRecord, V2>(
+    record: R,
+    mapFn: (
+      value: R[keyof R],
+      key: TsDataForgeInternals.MappedRecordKey<R>,
+    ) => Optional<V2>,
+  ): TsDataForgeInternals.FilteredRecord<
+    TsDataForgeInternals.MappedRecord<R, V2>
+  > => {
+    // `Object.entries` erases both the key and the value type of `R`, so the
+    // callback is widened once here instead of asserting on every entry.
+    // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+    const mapFnWidened = mapFn as (value: unknown, key: string) => Optional<V2>;
+
+    return (
+      // `Object.entries` enumerates exactly the own enumerable string keys of
+      // `record`, and this only ever drops entries or replaces their values, so
+      // the result has a subset of those keys with `V2` values.
+      // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+      Object.fromEntries(
+        Object.entries(record).flatMap(([k, v]) => {
+          const mapped = mapFnWidened(v, k);
+
+          return Optional.isSome(mapped) ? [[k, mapped.value] as const] : [];
+        }),
+      ) as never
+    );
+  };
+
   /**
    * Merges multiple records into a single record using `Object.assign`.
    * Later records override properties from earlier records with the same key.
@@ -691,6 +857,27 @@ declare namespace TsDataForgeInternals {
     [K in keyof R as K extends symbol ? never : K]: V2;
   }>;
 
+  /** `R` without the symbol keys `Object.entries` never visits. */
+  type StringKeyedRecord<R> = Readonly<{
+    [K in keyof R as K extends symbol ? never : K]: R[K];
+  }>;
+
+  /**
+   * The result of dropping entries from `R`: symbol keys go away, and the
+   * remaining keys become optional because a predicate may reject any of them.
+   *
+   * A record keyed by an index signature stays total instead. It names no
+   * specific key that could go missing, and `noUncheckedIndexedAccess` already
+   * adds `| undefined` on access, so making it `Partial` would add nothing and
+   * would only stop the result from being assignable back to the record type it
+   * came from.
+   */
+  export type FilteredRecord<R> = string extends keyof R
+    ? StringKeyedRecord<R>
+    : number extends keyof R
+      ? StringKeyedRecord<R>
+      : Readonly<{ [K in keyof R as K extends symbol ? never : K]?: R[K] }>;
+
   /**
    * Merges two object types where keys in B override keys in A, preserving optional modifiers.
    *

package/src/object/object.test.mts

@@ -5,7 +5,8 @@ import {
   type UnknownRecord,
 } from 'ts-type-forge';
 import { expectType } from '../expect-type.mjs';
-import { pipe } from '../functional/index.mjs';
+import { Optional, pipe } from '../functional/index.mjs';
+import { isString } from '../guard/index.mjs';
 import { Obj } from './object.mjs';
 
 describe('shallowEq', () => {
@@ -285,6 +286,124 @@ describe('map', () => {
   });
 });
 
+describe('filter', () => {
+  test('should keep the entries the predicate accepts', () => {
+    const result = Obj.filter({ a: 1, b: 2 }, (value) => value > 1);
+
+    expectType<typeof result, Readonly<{ a?: 1; b?: 2 }>>('=');
+
+    assert.deepStrictEqual(result, { b: 2 });
+  });
+
+  test('should keep a record with an index signature total', () => {
+    const scores: ReadonlyRecord<string, number> = {
+      alice: 1,
+      bob: 2,
+    } as const;
+
+    const result = Obj.filter(scores, (value) => value > 1);
+
+    expectType<typeof result, ReadonlyRecord<string, number>>('=');
+
+    assert.deepStrictEqual(result, { bob: 2 });
+  });
+
+  test('should pass the key as the second argument', () => {
+    const result = Obj.filter({ a: 1, b: 2 }, (_value, key) => {
+      expectType<typeof key, 'a' | 'b'>('=');
+
+      return key === 'a';
+    });
+
+    assert.deepStrictEqual(result, { a: 1 });
+  });
+
+  test('should narrow the value type through a type guard', () => {
+    const mixed: UnknownRecord = { a: 1, b: 'x' } as const;
+
+    const result = Obj.filter(mixed, isString);
+
+    expectType<typeof result, ReadonlyRecord<string, string>>('=');
+
+    assert.deepStrictEqual(result, { b: 'x' });
+  });
+
+  test('should drop symbol keys, as Object.entries does', () => {
+    const sym = Symbol('s');
+
+    const result = Obj.filter({ a: 1, [sym]: 2 }, () => true);
+
+    expectType<typeof result, Readonly<{ a?: 1 }>>('=');
+
+    assert.deepStrictEqual(result, { a: 1 });
+  });
+
+  test('should handle an empty record', () => {
+    const result = Obj.filter({}, () => true);
+
+    assert.deepStrictEqual(result, {});
+  });
+
+  test('should not mutate the source record', () => {
+    const source = { a: 1, b: 2 } as const;
+
+    Obj.filter(source, (value) => value > 1);
+
+    assert.deepStrictEqual(source, { a: 1, b: 2 });
+  });
+});
+
+describe('filterMap', () => {
+  test('should keep Optional.some and drop Optional.none', () => {
+    const result = Obj.filterMap({ a: 1, b: 2 }, (value) =>
+      value > 1 ? Optional.some(value * 10) : Optional.none,
+    );
+
+    expectType<typeof result, Readonly<{ a?: number; b?: number }>>('=');
+
+    assert.deepStrictEqual(result, { b: 20 });
+  });
+
+  test('should keep a record with an index signature total', () => {
+    const scores: ReadonlyRecord<string, number> = {
+      alice: 1,
+      bob: 2,
+    } as const;
+
+    const result = Obj.filterMap(scores, (value) =>
+      value > 1 ? Optional.some(value * 10) : Optional.none,
+    );
+
+    expectType<typeof result, ReadonlyRecord<string, number>>('=');
+
+    assert.deepStrictEqual(result, { bob: 20 });
+  });
+
+  test('should pass the key as the second argument', () => {
+    const result = Obj.filterMap({ a: 1, b: 2 }, (value, key) => {
+      expectType<typeof key, 'a' | 'b'>('=');
+
+      return key === 'a' ? Optional.some(value) : Optional.none;
+    });
+
+    assert.deepStrictEqual(result, { a: 1 });
+  });
+
+  test('should handle an empty record', () => {
+    const result = Obj.filterMap({}, () => Optional.none);
+
+    assert.deepStrictEqual(result, {});
+  });
+
+  test('should not mutate the source record', () => {
+    const source = { a: 1, b: 2 } as const;
+
+    Obj.filterMap(source, (value) => Optional.some(value * 2));
+
+    assert.deepStrictEqual(source, { a: 1, b: 2 });
+  });
+});
+
 describe('merge', () => {
   test('should merge two objects, later overriding earlier', () => {
     const a = { a: 0, b: 0 } as const;