ts-data-forge 6.7.0 → 6.9.0

package/src/number/branded-types/uint16.test.mts

@@ -6,37 +6,37 @@ import { asUint16, isUint16, Uint16 } from './uint16.mjs';
 describe('Uint16 test', () => {
   describe(asUint16, () => {
     test('accepts valid uint16 values', () => {
-      expect(() => asUint16(0)).not.toThrowError();
+      expect(() => asUint16(0)).not.toThrow();
 
-      expect(() => asUint16(1)).not.toThrowError();
+      expect(() => asUint16(1)).not.toThrow();
 
-      expect(() => asUint16(65_535)).not.toThrowError(); // 2^16 - 1
+      expect(() => asUint16(65_535)).not.toThrow(); // 2^16 - 1
 
-      expect(() => asUint16(32_768)).not.toThrowError(); // 2^15
+      expect(() => asUint16(32_768)).not.toThrow(); // 2^15
     });
 
     test('rejects values outside uint16 range', () => {
-      expect(() => asUint16(65_536)).toThrowError(TypeError); // 2^16
+      expect(() => asUint16(65_536)).toThrow(TypeError); // 2^16
 
-      expect(() => asUint16(100_000)).toThrowError(TypeError);
+      expect(() => asUint16(100_000)).toThrow(TypeError);
     });
 
     test('rejects negative integers', () => {
-      expect(() => asUint16(-1)).toThrowError(TypeError);
+      expect(() => asUint16(-1)).toThrow(TypeError);
 
-      expect(() => asUint16(-42)).toThrowError(TypeError);
+      expect(() => asUint16(-42)).toThrow(TypeError);
     });
 
     test('rejects non-integers', () => {
-      expect(() => asUint16(Number.NaN)).toThrowError(TypeError);
+      expect(() => asUint16(Number.NaN)).toThrow(TypeError);
 
-      expect(() => asUint16(Number.POSITIVE_INFINITY)).toThrowError(TypeError);
+      expect(() => asUint16(Number.POSITIVE_INFINITY)).toThrow(TypeError);
 
-      expect(() => asUint16(Number.NEGATIVE_INFINITY)).toThrowError(TypeError);
+      expect(() => asUint16(Number.NEGATIVE_INFINITY)).toThrow(TypeError);
 
-      expect(() => asUint16(1.2)).toThrowError(TypeError);
+      expect(() => asUint16(1.2)).toThrow(TypeError);
 
-      expect(() => asUint16(-3.4)).toThrowError(TypeError);
+      expect(() => asUint16(-3.4)).toThrow(TypeError);
     });
 
     test('returns the same value for valid inputs', () => {
@@ -55,7 +55,7 @@ describe('Uint16 test', () => {
       { name: '-3.4', value: -3.4 },
       { name: '-1', value: -1 },
     ] as const)(`asUint16($name) should throw a TypeError`, ({ value }) => {
-      expect(() => asUint16(value)).toThrowError(
+      expect(() => asUint16(value)).toThrow(
         new TypeError(
           `Expected a non-negative integer less than 2^16, got: ${value}`,
         ),

package/src/number/branded-types/uint32.test.mts

@@ -6,37 +6,37 @@ import { asUint32, isUint32, Uint32 } from './uint32.mjs';
 describe('Uint32 test', () => {
   describe(asUint32, () => {
     test('accepts valid uint32 values', () => {
-      expect(() => asUint32(0)).not.toThrowError();
+      expect(() => asUint32(0)).not.toThrow();
 
-      expect(() => asUint32(1)).not.toThrowError();
+      expect(() => asUint32(1)).not.toThrow();
 
-      expect(() => asUint32(4_294_967_295)).not.toThrowError(); // 2^32 - 1
+      expect(() => asUint32(4_294_967_295)).not.toThrow(); // 2^32 - 1
 
-      expect(() => asUint32(2_147_483_648)).not.toThrowError(); // 2^31
+      expect(() => asUint32(2_147_483_648)).not.toThrow(); // 2^31
     });
 
     test('rejects values outside uint32 range', () => {
-      expect(() => asUint32(4_294_967_296)).toThrowError(TypeError); // 2^32
+      expect(() => asUint32(4_294_967_296)).toThrow(TypeError); // 2^32
 
-      expect(() => asUint32(10_000_000_000)).toThrowError(TypeError);
+      expect(() => asUint32(10_000_000_000)).toThrow(TypeError);
     });
 
     test('rejects negative integers', () => {
-      expect(() => asUint32(-1)).toThrowError(TypeError);
+      expect(() => asUint32(-1)).toThrow(TypeError);
 
-      expect(() => asUint32(-42)).toThrowError(TypeError);
+      expect(() => asUint32(-42)).toThrow(TypeError);
     });
 
     test('rejects non-integers', () => {
-      expect(() => asUint32(Number.NaN)).toThrowError(TypeError);
+      expect(() => asUint32(Number.NaN)).toThrow(TypeError);
 
-      expect(() => asUint32(Number.POSITIVE_INFINITY)).toThrowError(TypeError);
+      expect(() => asUint32(Number.POSITIVE_INFINITY)).toThrow(TypeError);
 
-      expect(() => asUint32(Number.NEGATIVE_INFINITY)).toThrowError(TypeError);
+      expect(() => asUint32(Number.NEGATIVE_INFINITY)).toThrow(TypeError);
 
-      expect(() => asUint32(1.2)).toThrowError(TypeError);
+      expect(() => asUint32(1.2)).toThrow(TypeError);
 
-      expect(() => asUint32(-3.4)).toThrowError(TypeError);
+      expect(() => asUint32(-3.4)).toThrow(TypeError);
     });
 
     test('returns the same value for valid inputs', () => {
@@ -55,7 +55,7 @@ describe('Uint32 test', () => {
       { name: '-3.4', value: -3.4 },
       { name: '-1', value: -1 },
     ] as const)(`asUint32($name) should throw a TypeError`, ({ value }) => {
-      expect(() => asUint32(value)).toThrowError(
+      expect(() => asUint32(value)).toThrow(
         new TypeError(
           `Expected a non-negative integer less than 2^32, got: ${value}`,
         ),

package/src/number/enum/int8.test.mts

@@ -35,7 +35,7 @@ describe('Int8 test', () => {
       { value: Number.POSITIVE_INFINITY, name: 'Infinity' },
       { value: Number.NEGATIVE_INFINITY, name: '-Infinity' },
     ])('asInt8($name) should throw TypeError', ({ value }) => {
-      expect(() => asInt8(value)).toThrowError(TypeError);
+      expect(() => asInt8(value)).toThrow(TypeError);
     });
   });
 

package/src/number/enum/uint8.test.mts

@@ -35,7 +35,7 @@ describe('Uint8 test', () => {
       { value: Number.POSITIVE_INFINITY, name: 'Infinity' },
       { value: Number.NEGATIVE_INFINITY, name: '-Infinity' },
     ])('asUint8($name) should throw TypeError', ({ value }) => {
-      expect(() => asUint8(value)).toThrowError(TypeError);
+      expect(() => asUint8(value)).toThrow(TypeError);
     });
   });
 

package/src/object/object.mts

@@ -1,3 +1,6 @@
+import { Arr } from '../array/index.mjs';
+import { hasKey, isRecord } from '../guard/index.mjs';
+
 /**
  * A collection of type-safe object utility functions providing functional
  * programming patterns for object manipulation, including pick, omit, shallow
@@ -58,7 +61,6 @@ export namespace Obj {
 
     const bEntries = Object.entries(b);
 
-    // eslint-disable-next-line ts-data-forge/prefer-arr-is-array-of-length
     if (aEntries.length !== bEntries.length) return false;
 
     return aEntries.every(([k, v]) => eq(b[k], v));
@@ -311,6 +313,8 @@ export namespace Obj {
    *
    * @example
    *
+   * <!-- doc:embed:jsdoc:example:./samples/src/object/merge-example.mts -->
+   *
    * ```ts
    * const a = { a: 0, b: 0 } as const;
    * const b = { b: 1, c: 0 } as const;
@@ -320,6 +324,8 @@ export namespace Obj {
    * assert.deepStrictEqual(result, { a: 0, b: 1, c: 0 });
    * ```
    *
+   * <!-- /doc:embed:jsdoc:example:./samples/src/object/merge-example.mts -->
+   *
    * @param records - The records to merge
    * @returns A new record with all properties merged
    */
@@ -328,8 +334,175 @@ export namespace Obj {
   ): TsDataForgeInternals.MergeAll<Records> =>
     // eslint-disable-next-line total-functions/no-unsafe-type-assertion
     Object.fromEntries(records.flatMap((r) => Object.entries(r))) as never;
+
+  /**
+   * Deeply picks a nested property from an object along the specified key path.
+   * Supports both direct and curried usage.
+   *
+   * @example
+   *
+   * ```ts
+   * const data = { a: { b: { c: 1, d: 2 }, e: 3 }, f: 4 } as const;
+   *
+   * // Direct usage
+   * const result = Obj.deepPick(data, ['a', 'b', 'c']);
+   * assert.deepStrictEqual(result, { a: { b: { c: 1 } } });
+   *
+   * // Curried usage with pipe
+   * const pickName = Obj.deepPick(['user', 'name']);
+   * const result2 = pipe(data).map(pickName).value;
+   * ```
+   *
+   * @template R - The type of the input record
+   * @template Path - The key path tuple
+   * @param record - The source record
+   * @param path - A readonly tuple of keys representing the nested path
+   * @returns A new record containing only the nested property at the path
+   */
+  export function deepPick<
+    const R extends UnknownRecord,
+    const Path extends readonly (string | number)[],
+  >(record: R, path: Path): DeepPick<R, Path>;
+
+  // Curried version
+  export function deepPick<const Path extends readonly (string | number)[]>(
+    path: Path,
+  ): <const R extends UnknownRecord>(record: R) => DeepPick<R, Path>;
+
+  export function deepPick<
+    const R extends UnknownRecord,
+    const Path extends readonly (string | number)[],
+  >(
+    ...args: readonly [record: R, path: Path] | readonly [path: Path]
+  ): DeepPick<R, Path> | ((record: R) => DeepPick<R, Path>) {
+    switch (args.length) {
+      case 2: {
+        const [record, path] = args;
+
+        return (
+          // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+          deepPickImpl(record, path) as never
+        );
+      }
+
+      case 1: {
+        const [path] = args;
+
+        return (record: R) => deepPick(record, path);
+      }
+    }
+  }
+
+  /**
+   * Deeply omits a nested property from an object along the specified key path.
+   * Supports both direct and curried usage.
+   *
+   * @example
+   *
+   * ```ts
+   * const data = { a: { b: { c: 1, d: 2 }, e: 3 }, f: 4 } as const;
+   *
+   * // Direct usage
+   * const result = Obj.deepOmit(data, ['a', 'b', 'c']);
+   * assert.deepStrictEqual(result, { a: { b: { d: 2 }, e: 3 }, f: 4 });
+   *
+   * // Curried usage with pipe
+   * const omitPassword = Obj.deepOmit(['user', 'password']);
+   * const result2 = pipe(data).map(omitPassword).value;
+   * ```
+   *
+   * @template R - The type of the input record
+   * @template Path - The key path tuple
+   * @param record - The source record
+   * @param path - A readonly tuple of keys representing the nested path to omit
+   * @returns A new record with the nested property at the path removed
+   */
+  export function deepOmit<
+    const R extends UnknownRecord,
+    const Path extends readonly (string | number)[],
+  >(record: R, path: Path): DeepOmit<R, Path>;
+
+  // Curried version
+  export function deepOmit<const Path extends readonly (string | number)[]>(
+    path: Path,
+  ): <const R extends UnknownRecord>(record: R) => DeepOmit<R, Path>;
+
+  export function deepOmit<
+    const R extends UnknownRecord,
+    const Path extends readonly (string | number)[],
+  >(
+    ...args: readonly [record: R, path: Path] | readonly [path: Path]
+  ): DeepOmit<R, Path> | ((record: R) => DeepOmit<R, Path>) {
+    switch (args.length) {
+      case 2: {
+        const [record, path] = args;
+
+        return (
+          // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+          deepOmitImpl(record, path) as never
+        );
+      }
+
+      case 1: {
+        const [path] = args;
+
+        return (record: R) => deepOmit(record, path);
+      }
+    }
+  }
 }
 
+const deepPickImpl = (
+  record: UnknownRecord,
+  path: readonly (string | number)[],
+): UnknownRecord => {
+  if (!Arr.isNonEmpty(path)) return record;
+
+  const head = path[0];
+
+  if (!hasKey(record, head)) return {};
+
+  const value = record[head];
+
+  const tail = path.slice(1);
+
+  if (!Arr.isNonEmpty(tail)) return { [head]: value };
+
+  if (!isRecord(value)) return { [head]: {} };
+
+  return {
+    [head]: deepPickImpl(value, tail),
+  };
+};
+
+const deepOmitImpl = (
+  record: UnknownRecord,
+  path: readonly (string | number)[],
+): UnknownRecord => {
+  if (!Arr.isNonEmpty(path)) return record;
+
+  const head = path[0];
+
+  const tail = path.slice(1);
+
+  if (!hasKey(record, head)) return record;
+
+  if (!Arr.isNonEmpty(tail)) {
+    return Object.fromEntries(
+      Object.entries(record).filter(([k]) => k !== head),
+    );
+  }
+
+  const value = record[head];
+
+  if (!isRecord(value)) return record;
+
+  return {
+    ...record,
+    [head]: deepOmitImpl(value, tail),
+  };
+};
+
 /**
  * @internal
  * Internal type utilities for the Obj module.

package/src/object/object.test.mts

@@ -472,3 +472,175 @@ describe('merge', () => {
     assert.deepStrictEqual(result, { a: 1, b: 'text', c: true, d: 42 });
   });
 });
+
+describe('deepPick', () => {
+  test('should deeply pick a nested property', () => {
+    const data = { a: { b: { c: 1, d: 2 }, e: 3 }, f: 4 } as const;
+
+    const result = Obj.deepPick(data, ['a', 'b', 'c']);
+
+    assert.deepStrictEqual(result, { a: { b: { c: 1 } } });
+
+    expectType<
+      typeof result,
+      Readonly<{ a: Readonly<{ b: Readonly<{ c: 1 }> }> }>
+    >('=');
+  });
+
+  test('should pick at depth 1', () => {
+    const data = { a: 1, b: 2, c: 3 } as const;
+
+    const result = Obj.deepPick(data, ['a']);
+
+    assert.deepStrictEqual(result, { a: 1 });
+
+    expectType<typeof result, Readonly<{ a: 1 }>>('=');
+  });
+
+  test('should pick at depth 2', () => {
+    const data = { a: { b: 10, c: 20 }, d: 30 } as const;
+
+    const result = Obj.deepPick(data, ['a', 'b']);
+
+    assert.deepStrictEqual(result, { a: { b: 10 } });
+
+    expectType<typeof result, Readonly<{ a: Readonly<{ b: 10 }> }>>('=');
+  });
+
+  test('should return empty object for non-existent key', () => {
+    const data = { a: 1 } as const;
+
+    const result = Obj.deepPick(data, ['x']);
+
+    assert.deepStrictEqual(result, {});
+  });
+
+  test('should return empty nested for non-existent nested key', () => {
+    const data = { a: { b: 1 } } as const;
+
+    const result = Obj.deepPick(data, ['a', 'x']);
+
+    assert.deepStrictEqual(result, { a: {} });
+  });
+
+  test('should support curried form with correct type inference', () => {
+    const pickABC = Obj.deepPick(['a', 'b', 'c']);
+
+    const data = { a: { b: { c: 42, d: 99 } } } as const;
+
+    const result = pickABC(data);
+
+    assert.deepStrictEqual(result, { a: { b: { c: 42 } } });
+
+    expectType<
+      typeof result,
+      Readonly<{ a: Readonly<{ b: Readonly<{ c: 42 }> }> }>
+    >('=');
+  });
+
+  test('should work with pipe when curried with correct type inference', () => {
+    const pickNested = Obj.deepPick(['a', 'b']);
+
+    const data = { a: { b: 1, c: 2 }, d: 3 } as const;
+
+    const result = pipe(data).map(pickNested).value;
+
+    assert.deepStrictEqual(result, { a: { b: 1 } });
+
+    expectType<typeof result, Readonly<{ a: Readonly<{ b: 1 }> }>>('=');
+  });
+
+  test('should return {} for path through primitive', () => {
+    const data = { a: 42 } as const;
+
+    const result = Obj.deepPick(data, ['a', 'b']);
+
+    assert.deepStrictEqual(result, { a: {} });
+  });
+});
+
+describe('deepOmit', () => {
+  test('should deeply omit a nested property', () => {
+    const data = { a: { b: { c: 1, d: 2 }, e: 3 }, f: 4 } as const;
+
+    const result = Obj.deepOmit(data, ['a', 'b', 'c']);
+
+    assert.deepStrictEqual(result, { a: { b: { d: 2 }, e: 3 }, f: 4 });
+
+    expectType<
+      typeof result,
+      Readonly<{ a: Readonly<{ b: Readonly<{ d: 2 }>; e: 3 }>; f: 4 }>
+    >('=');
+  });
+
+  test('should omit at depth 1', () => {
+    const data = { a: 1, b: 2, c: 3 } as const;
+
+    const result = Obj.deepOmit(data, ['a']);
+
+    assert.deepStrictEqual(result, { b: 2, c: 3 });
+
+    expectType<typeof result, Readonly<{ b: 2; c: 3 }>>('=');
+  });
+
+  test('should omit at depth 2', () => {
+    const data = { a: { b: 10, c: 20 }, d: 30 } as const;
+
+    const result = Obj.deepOmit(data, ['a', 'b']);
+
+    assert.deepStrictEqual(result, { a: { c: 20 }, d: 30 });
+
+    expectType<typeof result, Readonly<{ a: Readonly<{ c: 20 }>; d: 30 }>>('=');
+  });
+
+  test('should return unchanged for non-existent key', () => {
+    const data = { a: 1, b: 2 } as const;
+
+    const result = Obj.deepOmit(data, ['x']);
+
+    assert.deepStrictEqual(result, { a: 1, b: 2 });
+  });
+
+  test('should return unchanged for non-existent nested key', () => {
+    const data = { a: { b: 1 } } as const;
+
+    const result = Obj.deepOmit(data, ['a', 'x']);
+
+    assert.deepStrictEqual(result, { a: { b: 1 } });
+  });
+
+  test('should return unchanged for path through primitive', () => {
+    const data = { a: 42, b: 'hello' } as const;
+
+    const result = Obj.deepOmit(data, ['a', 'toString']);
+
+    assert.deepStrictEqual(result, { a: 42, b: 'hello' });
+  });
+
+  test('should support curried form with correct type inference', () => {
+    const omitABC = Obj.deepOmit(['a', 'b', 'c']);
+
+    const data = { a: { b: { c: 1, d: 2 } } } as const;
+
+    const result = omitABC(data);
+
+    assert.deepStrictEqual(result, { a: { b: { d: 2 } } });
+
+    expectType<
+      typeof result,
+      Readonly<{ a: Readonly<{ b: Readonly<{ d: 2 }> }> }>
+    >('=');
+  });
+
+  test('should work with pipe when curried with correct type inference', () => {
+    const omitNested = Obj.deepOmit(['a', 'b']);
+
+    const data = { a: { b: 1, c: 2 }, d: 3 } as const;
+
+    const result = pipe(data).map(omitNested).value;
+
+    assert.deepStrictEqual(result, { a: { c: 2 }, d: 3 });
+
+    expectType<typeof result, Readonly<{ a: Readonly<{ c: 2 }>; d: 3 }>>('=');
+  });
+});

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

@@ -1,4 +1,3 @@
-/* eslint-disable ts-data-forge/prefer-arr-is-array-of-length */
 /* eslint-disable ts-data-forge/prefer-arr-is-array */
 
 import { isMap, isRegExp, isSet, isTypedArray } from '@sindresorhus/is';

package/src/others/unknown-to-string.test.mts

@@ -21,7 +21,7 @@ describe(unknownToString, () => {
 
     expect(unknownToString(value)).toBe('123n');
 
-    expect(() => JSON.stringify(value)).toThrowError(
+    expect(() => JSON.stringify(value)).toThrow(
       'Do not know how to serialize a BigInt',
     );
   });