ts-data-forge 14.10.0 → 14.10.2

package/src/json/json.mts

@@ -3,8 +3,7 @@ import type {
   UintRangeInclusive,
   UnknownRecord,
 } from 'ts-type-forge';
-import { Arr } from '../array/index.mjs';
-import { pipe, Result } from '../functional/index.mjs';
+import { Result } from '../functional/index.mjs';
 import { isRecord } from '../guard/index.mjs';
 import { castMutable, unknownToString } from '../others/index.mjs';
 
@@ -323,63 +322,24 @@ export namespace Json {
     value: UnknownRecord,
     space?: UintRangeInclusive<1, 10> | string,
   ): Result<string | undefined, string> => {
-    const allKeys = pipe(keysDeep(value))
-      .map(Arr.uniq)
-      .map((ks) => ks.toSorted()).value;
+    // The keys are collected by a first pass with a function replacer, which
+    // `JSON.stringify` calls at every nesting level with the value after
+    // `toJSON`, so the allowlist of the second pass misses none of them. The
+    // allowlist also fixes the order, sorting integer-like keys as strings.
+    const mut_keys = new Set<string>();
 
-    return stringifySelected(value, allKeys, space);
-  };
-}
-
-/**
- * @param obj - The record to extract keys from. Must be a plain object.
- * @param mut_keys - A mutable array to accumulate the collected keys. This
- *   array will be modified in-place by the function for performance reasons.
- * @internal
- * Recursively collects all property keys from a nested object structure.
- *
- * This helper function traverses an object and its nested objects and arrays,
- * collecting all string keys found at any level of nesting. The function mutates
- * the provided keys array for performance reasons.
- */
-const keysDeepImpl = (
-  obj: UnknownRecord,
-  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
-  mut_keys: string[],
-): void => {
-  for (const [k, v] of Object.entries(obj)) {
-    mut_keys.push(k);
-
-    if (isRecord(v)) {
-      keysDeepImpl(v, mut_keys);
-    }
-
-    if (Array.isArray(v)) {
-      for (const li of v) {
-        if (isRecord(li)) {
-          keysDeepImpl(li, mut_keys);
+    const collected = stringify(value, (_key, v) => {
+      if (isRecord(v)) {
+        for (const k of Object.keys(v)) {
+          mut_keys.add(k);
         }
       }
-    }
-  }
-};
 
-/**
- * @param obj - The record to extract keys from. Must be a plain object.
- * @returns A readonly array of all string keys found in the object and its
- *   nested objects/arrays. May contain duplicates if the same key appears at
- *   multiple levels.
- * @internal
- * Extracts all property keys from a nested object structure into a flat array.
- *
- * This function serves as a safe wrapper around `keysDeepImpl`, creating a new
- * mutable array and passing it to the recursive implementation. The result
- * contains all keys found at any level of nesting within the input object.
- */
-const keysDeep = (obj: UnknownRecord): readonly string[] => {
-  const mut_keys: string[] = [];
+      return v;
+    });
 
-  keysDeepImpl(obj, mut_keys);
-
-  return mut_keys;
-};
+    return Result.isErr(collected)
+      ? collected
+      : stringifySelected(value, Array.from(mut_keys).toSorted(), space);
+  };
+}

package/src/json/json.test.mts

@@ -709,6 +709,38 @@ describe('stringifySortedKey', () => {
     }
   });
 
+  test('keeps the properties of an object nested in an array of arrays', () => {
+    const result = Json.stringifySortedKey({ a: [[{ c: 1, b: 2 }]] });
+
+    assert.isTrue(Result.isOk(result));
+
+    expect(result.value).toBe('{"a":[[{"b":2,"c":1}]]}');
+
+    const other = Json.stringifySortedKey({ a: [[{ c: 1, b: 3 }]] });
+
+    assert.isTrue(Result.isOk(other));
+
+    expect(other.value).not.toBe(result.value);
+  });
+
+  test('keeps the properties of what toJSON returns', () => {
+    const result = Json.stringifySortedKey({
+      x: { toJSON: () => ({ z: 1, y: 2 }) },
+    });
+
+    assert.isTrue(Result.isOk(result));
+
+    expect(result.value).toBe('{"x":{"y":2,"z":1}}');
+  });
+
+  test('sorts integer-like keys as strings', () => {
+    const result = Json.stringifySortedKey({ 2: 'b', 10: 'a', x: 'c' });
+
+    assert.isTrue(Result.isOk(result));
+
+    expect(result.value).toBe('{"10":"a","2":"b","x":"c"}');
+  });
+
   test('should handle empty object', () => {
     const result = Json.stringifySortedKey({});
 

package/src/number/num.mts

@@ -120,8 +120,8 @@ export namespace Num {
    *
    * assert.strictEqual(Result.unwrapOk(Num.safeParseInt('  ')), undefined);
    *
-   * // A value that overflows to Infinity is not an integer either, even
-   * // though native `parseInt` reads a 1 out of it.
+   * // A value that overflows to Infinity is not an integer either, even though
+   * // native `parseInt` reads a 1 out of it.
    *
    * assert.strictEqual(Number.parseInt('1e400', 10), 1);
    *
@@ -135,10 +135,10 @@ export namespace Num {
    */
   export const safeParseInt = (s: string): Result<Int, Error> =>
     // The parsing itself is `SafeNumber.parseInteger` (Sumi D-49 (c)): one
-    // implementation, in the package that owns the standard-library
-    // boundary. What stays here is this function's own contract — the `Int`
-    // brand on the success side, and an `Error` rather than a tagged record
-    // on the failure side.
+    // implementation, in the package that owns the standard-library boundary.
+    // What stays here is this function's own contract — the `Int` brand on the
+    // success side, and an `Error` rather than a tagged record on the failure
+    // side.
     Result.match(SafeNumber.parseInteger(s), {
       // eslint-disable-next-line total-functions/no-unsafe-type-assertion
       ok: (n) => Result.ok(n as Int),
@@ -213,10 +213,10 @@ export namespace Num {
    */
   export const safeParseFloat = (s: string): Result<FiniteNumber, Error> =>
     // The parsing itself is `SafeNumber.parse` (Sumi D-49 (c)): one
-    // implementation, in the package that owns the standard-library
-    // boundary. What stays here is this function's own contract — the
-    // `FiniteNumber` brand on the success side, and an `Error` rather than a
-    // tagged record on the failure side.
+    // implementation, in the package that owns the standard-library boundary.
+    // What stays here is this function's own contract — the `FiniteNumber`
+    // brand on the success side, and an `Error` rather than a tagged record on
+    // the failure side.
     Result.match(SafeNumber.parse(s), {
       // eslint-disable-next-line total-functions/no-unsafe-type-assertion
       ok: (n) => Result.ok(n as FiniteNumber),
@@ -603,15 +603,19 @@ export namespace Num {
   /**
    * Performs integer division using floor division.
    *
-   * Computes `⌊a / b⌋` by flooring both operands before division and then
-   * flooring the result. This ensures integer arithmetic semantics.
+   * Computes `⌊⌊a⌋ / b⌋`: the dividend is floored, the divisor is used as is,
+   * and the quotient is floored. For a positive integer divisor this is
+   * `⌊a / b⌋`. The divisor is not floored, since a divisor in `(-1, 1)` would
+   * floor to `0` or `-1`.
    *
-   * Note: Unlike `div`, this function does not enforce non-zero divisor at
-   * compile time. Division by zero returns `NaN`.
+   * Like `div`, the divisor must be typed as `NonZeroNumber` or a non-zero
+   * numeric literal. A divisor of magnitude below `1` makes the quotient larger
+   * than the dividend, so it overflows to `±Infinity` once `|a / b|` exceeds
+   * `Number.MAX_VALUE` (e.g. `1e300 / 1e-10`), as `mul` can.
    *
    * @param a - The dividend
-   * @param b - The divisor
-   * @returns The integer quotient, or `NaN` if b is zero
+   * @param b - The divisor (must be non-zero, enforced by types)
+   * @returns The integer quotient `⌊⌊a⌋ / b⌋`
    */
   export const divInt = <
     A extends number,
@@ -621,7 +625,7 @@ export namespace Num {
     b: B,
   ): DivIntResult<A, B> => {
     // eslint-disable-next-line total-functions/no-partial-division
-    const quotient = Math.floor(Math.floor(a) / Math.floor(b));
+    const quotient = Math.floor(Math.floor(a) / b);
 
     // eslint-disable-next-line total-functions/no-unsafe-type-assertion
     return quotient as DivIntResult<A, B>;

package/src/number/num.test.mts

@@ -354,7 +354,19 @@ describe('Num test', () => {
 
       expect(Num.divInt(-7, 2)).toBe(-4); // floor division
 
-      expect(Num.divInt(10.7, asNonZeroFiniteNumber(3.2))).toBe(3); // floors both operands
+      expect(Num.divInt(10.7, asNonZeroFiniteNumber(3.2))).toBe(3); // ⌊⌊10.7⌋ / 3.2⌋
+    });
+
+    test('a divisor in (-1, 1) is not floored to 0 or -1', () => {
+      expect(Num.divInt(5, asNonZeroFiniteNumber(0.5))).toBe(10);
+
+      expect(Num.divInt(0.3, asNonZeroFiniteNumber(0.5))).toBe(0);
+
+      expect(Num.divInt(-5, asNonZeroFiniteNumber(0.5))).toBe(-10);
+
+      expect(Num.divInt(5, asNonZeroFiniteNumber(-0.5))).toBe(-10);
+
+      expect(Num.divInt(7, asNonZeroFiniteNumber(-2.5))).toBe(-3);
     });
   });
 

package/src/object/object.mts

@@ -91,6 +91,10 @@ export namespace Obj {
    * **Type Safety**: Only keys that exist in the source record type are
    * allowed, preventing runtime errors from accessing non-existent properties.
    *
+   * **Key handling**: a numeric key `1` matches the property `'1'`, and
+   * symbol-keyed properties are picked like string-keyed ones. Only own
+   * enumerable properties are read.
+   *
    * @example
    *
    * ```ts
@@ -150,12 +154,12 @@ export namespace Obj {
       case 2: {
         const [record, keys] = args;
 
-        const keysSet = new Set<keyof R>(keys);
+        const keysSet = toOwnKeySet(keys);
 
         return (
           // eslint-disable-next-line total-functions/no-unsafe-type-assertion
           Object.fromEntries(
-            Object.entries(record).filter(([k, _v]) => keysSet.has(k)),
+            ownEnumerableEntries(record).filter(([k]) => keysSet.has(k)),
           ) as never
         );
       }
@@ -177,6 +181,10 @@ export namespace Obj {
    * allowed, and the return type precisely reflects which properties remain
    * after omission.
    *
+   * **Key handling**: a numeric key `1` matches the property `'1'`, and
+   * symbol-keyed properties are kept unless omitted, like string-keyed ones.
+   * Only own enumerable properties are copied.
+   *
    * @example
    *
    * ```ts
@@ -238,12 +246,12 @@ export namespace Obj {
       case 2: {
         const [record, keys] = args;
 
-        const keysSet = new Set<keyof R>(keys);
+        const keysSet = toOwnKeySet(keys);
 
         return (
           // eslint-disable-next-line total-functions/no-unsafe-type-assertion
           Object.fromEntries(
-            Object.entries(record).filter(([k, _v]) => !keysSet.has(k)),
+            ownEnumerableEntries(record).filter(([k]) => !keysSet.has(k)),
           ) as never
         );
       }
@@ -337,8 +345,8 @@ export namespace Obj {
    * This is what `Object.fromEntries(Object.entries(record).map(...))` cannot
    * express: an entries array carries no evidence that it still covers every
    * key of the record it came from, so its element type is all the return type
-   * can be built from. Going through a mapped type instead states the
-   * invariant that a value-only transform preserves the key set.
+   * can be built from. Going through a mapped type instead states the invariant
+   * that a value-only transform preserves the key set.
    *
    * **Key handling**: keys reach the callback the way `Object.entries` yields
    * them, so a numeric key `1` arrives as `'1'`. Symbol-keyed properties are
@@ -996,3 +1004,23 @@ declare namespace TsDataForgeInternals {
         ? MergeAll<Rest, MergeTwo<Acc, First>>
         : Acc;
 }
+
+/**
+ * The keys as `Reflect.ownKeys` reports them: a numeric key `1` becomes `'1'`,
+ * a symbol stays a symbol.
+ */
+const toOwnKeySet = (
+  keys: readonly PropertyKey[],
+): ReadonlySet<string | symbol> =>
+  new Set(keys.map((k) => (typeof k === 'number' ? k.toString() : k)));
+
+/**
+ * The own enumerable entries of `record`, string and symbol keys alike, in
+ * `Reflect.ownKeys` order. `Object.entries` would leave out the symbols.
+ */
+const ownEnumerableEntries = (
+  record: UnknownRecord,
+): readonly (readonly [string | symbol, unknown])[] =>
+  Reflect.ownKeys(record)
+    .filter((k) => Object.prototype.propertyIsEnumerable.call(record, k))
+    .map((k) => [k, Reflect.get(record, k)] as const);

package/src/object/object.test.mts

@@ -89,6 +89,32 @@ describe('pick', () => {
 
     assert.deepStrictEqual(result, { name: 'Alice' });
   });
+
+  test('pick matches a numeric key', () => {
+    const record = { 1: 'a', b: 2 } as const;
+
+    const result = Obj.pick(record, [1]);
+
+    expectType<typeof result, Readonly<{ 1: 'a' }>>('=');
+
+    assert.deepStrictEqual(result, { 1: 'a' });
+
+    assert.deepStrictEqual(Obj.pick([1])(record), { 1: 'a' });
+  });
+
+  test('pick matches a symbol key', () => {
+    const sym = Symbol('s');
+
+    const record = { [sym]: 'a', b: 2 } as const;
+
+    const result = Obj.pick(record, [sym]);
+
+    assert.deepStrictEqual(result, { [sym]: 'a' });
+
+    assert.deepStrictEqual(Obj.pick([sym])(record), { [sym]: 'a' });
+
+    assert.deepStrictEqual(Obj.pick(record, ['b']), { b: 2 });
+  });
 });
 
 describe('omit', () => {
@@ -132,6 +158,35 @@ describe('omit', () => {
     assert.deepStrictEqual(result, original);
   });
 
+  test('omit matches a numeric key', () => {
+    const record = { 1: 'a', b: 2 } as const;
+
+    const result = Obj.omit(record, [1]);
+
+    expectType<typeof result, Readonly<{ b: 2 }>>('=');
+
+    assert.deepStrictEqual(result, { b: 2 });
+
+    assert.deepStrictEqual(Obj.omit([1])(record), { b: 2 });
+  });
+
+  test('omit keeps the symbol keys it is not asked to omit', () => {
+    const sym = Symbol('s');
+
+    const other = Symbol('other');
+
+    const record = { [sym]: 'a', [other]: 'o', b: 2 } as const;
+
+    assert.deepStrictEqual(Obj.omit(record, [sym]), { [other]: 'o', b: 2 });
+
+    assert.deepStrictEqual(Obj.omit([sym])(record), { [other]: 'o', b: 2 });
+
+    assert.deepStrictEqual(Obj.omit(record, ['b']), {
+      [sym]: 'a',
+      [other]: 'o',
+    });
+  });
+
   test('should omit multiple keys in curried form', () => {
     const omitBAndD = Obj.omit(['b', 'd']);
 

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

@@ -67,12 +67,20 @@ export const fastDeepEqual = <T,>(a: T, b: T): boolean => {
       return isRegExp(b) && a.source === b.source && a.flags === b.flags;
     }
 
-    if (a.valueOf !== Object.prototype.valueOf) {
-      return a.valueOf() === b.valueOf();
+    // A null-prototype object (`Object.create(null)`, `Object.groupBy`) has
+    // neither method, so it falls through to the key comparison.
+    if (
+      typeof a.valueOf === 'function' &&
+      a.valueOf !== Object.prototype.valueOf
+    ) {
+      return typeof b.valueOf === 'function' && a.valueOf() === b.valueOf();
     }
 
-    if (a.toString !== Object.prototype.toString) {
-      return a.toString() === b.toString();
+    if (
+      typeof a.toString === 'function' &&
+      a.toString !== Object.prototype.toString
+    ) {
+      return typeof b.toString === 'function' && a.toString() === b.toString();
     }
 
     const aKeys: readonly string[] = Object.keys(a);
@@ -84,12 +92,11 @@ export const fastDeepEqual = <T,>(a: T, b: T): boolean => {
       aKeys.every(
         (key) =>
           hasKey(b, key) &&
-          // React-specific: avoid traversing React elements' _owner.
-          //  _owner contains circular references
-          // and is not needed when comparing the actual elements (and not their owners)
-          // eslint-disable-next-line @typescript-eslint/strict-boolean-expressions
-          !(key === '_owner' && a['$$typeof']) &&
-          fastDeepEqual(a[key], b[key]),
+          // React-specific: a React element (marked by a symbol `$$typeof`)
+          // has its _owner skipped, i.e. treated as equal. It holds circular
+          // references and is not part of what the element renders.
+          ((key === '_owner' && typeof a['$$typeof'] === 'symbol') ||
+            fastDeepEqual(a[key], b[key])),
       )
     );
   }