ts-data-forge 14.9.0 → 14.10.1

package/src/collections/imap-mapped.mts

@@ -125,8 +125,8 @@ type IMapMappedInterface<K, V, KM extends MapSetKeyType> = Readonly<{
   // Reducing a value
 
   /**
-   * Checks if all elements in the map satisfy a predicate. Also supports a
-   * type predicate overload that narrows the type of values in the map if the
+   * Checks if all elements in the map satisfy a predicate. Also supports a type
+   * predicate overload that narrows the type of values in the map if the
    * predicate returns true for all elements.
    *
    * @example

package/src/collections/imap.mts

@@ -96,8 +96,8 @@ type IMapInterface<K extends MapSetKeyType, V> = Readonly<{
   // Reducing a value
 
   /**
-   * Checks if all elements in the map satisfy a predicate. Also supports a
-   * type predicate overload that narrows the type of values in the map if the
+   * Checks if all elements in the map satisfy a predicate. Also supports a type
+   * predicate overload that narrows the type of values in the map if the
    * predicate returns true for all elements.
    *
    * @example
@@ -656,8 +656,7 @@ export namespace IMap {
    *
    * Two IMaps are considered equal if they have the same size and contain
    * exactly the same key-value pairs. The order of entries does not matter for
-   * equality comparison. Values are compared using JavaScript's `===`
-   * operator.
+   * equality comparison. Values are compared using JavaScript's `===` operator.
    *
    * **Performance:** O(n) where n is the size of the smaller map.
    *

package/src/collections/imap.test.mts

@@ -81,7 +81,7 @@ describe('IMap.create', () => {
   });
 
   test('should create map from JavaScript Map', () => {
-    const jsMap = new Map([
+    const jsMap = new Map<string, number>([
       ['a', 1],
       ['b', 2],
     ]);

package/src/collections/iset-mapped.mts

@@ -138,8 +138,7 @@ type ISetMappedInterface<K, KM extends MapSetKeyType> = Readonly<{
 
   /**
    * Checks if all elements in the set satisfy a type predicate. Narrows the
-   * type of elements in the set if the predicate returns true for all
-   * elements.
+   * type of elements in the set if the predicate returns true for all elements.
    *
    *
    * @example

package/src/collections/iset.mts

@@ -89,9 +89,9 @@ type ISetInterface<K extends MapSetKeyType> = Readonly<{
   // Reducing a value
 
   /**
-   * Checks if all elements in the set satisfy a predicate. Also supports a
-   * type predicate overload that narrows the type of elements in the set if
-   * the predicate returns true for all elements.
+   * Checks if all elements in the set satisfy a predicate. Also supports a type
+   * predicate overload that narrows the type of elements in the set if the
+   * predicate returns true for all elements.
    *
    * @example
    *
@@ -539,8 +539,7 @@ export namespace ISet {
    *
    * This factory function accepts any iterable of elements, including arrays,
    * JavaScript Sets, other ISets, or custom iterables. Duplicate elements in
-   * the input iterable will be automatically deduplicated in the resulting
-   * set.
+   * the input iterable will be automatically deduplicated in the resulting set.
    *
    * **Performance:** O(n) where n is the number of elements in the iterable.
    *

package/src/collections/iset.test.mts

@@ -39,7 +39,7 @@ describe('ISet.create', () => {
   });
 
   test('should create set from JavaScript Set', () => {
-    const jsSet = new Set(['a', 'b', 'c']);
+    const jsSet = new Set<string>(['a', 'b', 'c']);
 
     const set = ISet.create(jsSet);
 

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),

package/src/object/object.mts

@@ -337,8 +337,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

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])),
       )
     );
   }

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

@@ -203,6 +203,18 @@ describe(fastDeepEqual, () => {
         y: { toString: () => 'Hello world!' } as any,
         expected: '=',
       },
+      {
+        name: 'objects whose own `valueOf` and `toString` are not functions are compared by key',
+        x: { valueOf: 1, toString: 'a' } as any,
+        y: { valueOf: 1, toString: 'a' } as any,
+        expected: '=',
+      },
+      {
+        name: 'objects whose own `valueOf` that is not a function differs are not equal',
+        x: { valueOf: 1 } as any,
+        y: { valueOf: 2 } as any,
+        expected: '!=',
+      },
       {
         name: 'objects with `toString` functions returning different values are not equal',
         x: { toString: () => 'Hello world!' } as any,
@@ -212,6 +224,54 @@ describe(fastDeepEqual, () => {
     ] as const satisfies readonly TestCase[])('$name', testFn);
   });
 
+  describe('null-prototype objects', () => {
+    const withNullPrototype = (
+      entries: ReadonlyRecord<string, unknown>,
+    ): unknown => Object.setPrototypeOf({ ...entries }, null);
+
+    const groupByParity = (xs: readonly number[]): unknown =>
+      Object.groupBy(xs, (x) => (x % 2 === 0 ? 'even' : 'odd'));
+
+    test.each([
+      {
+        name: 'empty null-prototype objects are equal',
+        x: Object.create(null),
+        y: Object.create(null),
+        expected: '=',
+      },
+      {
+        name: 'null-prototype objects with the same entries are equal',
+        x: withNullPrototype({ a: 1, b: [2] }),
+        y: withNullPrototype({ a: 1, b: [2] }),
+        expected: '=',
+      },
+      {
+        name: 'null-prototype objects with different entries are not equal',
+        x: withNullPrototype({ a: 1 }),
+        y: withNullPrototype({ a: 2 }),
+        expected: '!=',
+      },
+      {
+        name: 'a null-prototype object and a plain object are not equal',
+        x: Object.create(null),
+        y: {},
+        expected: '!=',
+      },
+      {
+        name: 'Object.groupBy results with the same groups are equal',
+        x: groupByParity([1, 2, 3]),
+        y: groupByParity([1, 2, 3]),
+        expected: '=',
+      },
+      {
+        name: 'Object.groupBy results with different groups are not equal',
+        x: groupByParity([1, 2, 3]),
+        y: groupByParity([1, 2, 4]),
+        expected: '!=',
+      },
+    ] as const satisfies readonly TestCase[])('$name', testFn);
+  });
+
   describe('arrays', () => {
     test.each([
       { name: 'two empty arrays are equal', x: [], y: [], expected: '=' },
@@ -382,13 +442,13 @@ describe(fastDeepEqual, () => {
     test.each([
       {
         name: 'empty maps are equal',
-        x: new Map(),
-        y: new Map(),
+        x: new Map<unknown, unknown>(),
+        y: new Map<unknown, unknown>(),
         expected: '=',
       },
       {
         name: 'empty maps of different class are not equal',
-        x: new Map(),
+        x: new Map<unknown, unknown>(),
         y: new MyMap(),
         expected: '!=',
       },
@@ -436,32 +496,44 @@ describe(fastDeepEqual, () => {
       },
       {
         name: 'equal maps (same sub-keys)',
-        x: new Map([['a', [createMap({ b: 'c' })]]]),
-        y: new Map([['a', [createMap({ b: 'c' })]]]),
+        x: new Map<string, readonly ReadonlyMap<unknown, string>[]>([
+          ['a', [createMap({ b: 'c' })]],
+        ]),
+        y: new Map<string, readonly ReadonlyMap<unknown, string>[]>([
+          ['a', [createMap({ b: 'c' })]],
+        ]),
         expected: '=',
       },
       {
         name: 'not equal maps (different sub-key value)',
-        x: new Map([['a', [createMap({ b: 'c' })]]]),
-        y: new Map([['a', [createMap({ b: 'd' })]]]),
+        x: new Map<string, readonly ReadonlyMap<unknown, string>[]>([
+          ['a', [createMap({ b: 'c' })]],
+        ]),
+        y: new Map<string, readonly ReadonlyMap<unknown, string>[]>([
+          ['a', [createMap({ b: 'd' })]],
+        ]),
         expected: '!=',
       },
       {
         name: 'not equal maps (different sub-key)',
-        x: new Map([['a', [createMap({ b: 'c' })]]]),
-        y: new Map([['a', [createMap({ c: 'c' })]]]),
+        x: new Map<string, readonly ReadonlyMap<unknown, string>[]>([
+          ['a', [createMap({ b: 'c' })]],
+        ]),
+        y: new Map<string, readonly ReadonlyMap<unknown, string>[]>([
+          ['a', [createMap({ c: 'c' })]],
+        ]),
         expected: '!=',
       },
       {
         name: 'empty map and empty object are equal',
         x: {},
-        y: new Map(),
+        y: new Map<unknown, unknown>(),
         expected: '!=',
       },
       {
         name: 'empty map and empty array are not equal',
         x: [],
-        y: new Map(),
+        y: new Map<unknown, unknown>(),
         expected: '!=',
       },
       {
@@ -514,13 +586,13 @@ describe(fastDeepEqual, () => {
     test.each([
       {
         name: 'empty sets are equal',
-        x: new Set(),
-        y: new Set(),
+        x: new Set<unknown>(),
+        y: new Set<unknown>(),
         expected: '=',
       },
       {
         name: 'empty sets of different class are not equal',
-        x: new Set(),
+        x: new Set<unknown>(),
         y: new MySet(),
         expected: '!=',
       },
@@ -575,13 +647,13 @@ describe(fastDeepEqual, () => {
       {
         name: 'empty set and empty object are not equal',
         x: {},
-        y: new Set(),
+        y: new Set<unknown>(),
         expected: '!=',
       },
       {
         name: 'empty set and empty array are not equal',
         x: [],
-        y: new Set(),
+        y: new Set<unknown>(),
         expected: '!=',
       },
       {
@@ -598,7 +670,7 @@ describe(fastDeepEqual, () => {
       },
       {
         name: 'set and pseudo set are not equal',
-        x: new Set(),
+        x: new Set<unknown>(),
         y: {
           constructor: Set,
           size: 0,
@@ -702,15 +774,58 @@ describe(fastDeepEqual, () => {
           'content',
         );
 
-        // These elements have the same structure but different _owner references
-        // fastDeepEqual should skip _owner comparison and not cause infinite loop
-        // The result depends on whether other properties are equal
-        const result = fastDeepEqualUntyped(element1, element2);
-
-        // The important thing is that it doesn't throw or hang
-        assert.isBoolean(result);
+        assert.isTrue(fastDeepEqualUntyped(element1, element2));
       });
 
+      test.each([
+        {
+          name: 'element-shaped objects with different _owner are equal',
+          x: {
+            $$typeof: Symbol.for('react.element'),
+            type: 'div',
+            key: null,
+            props: { className: 'x' },
+            _owner: { name: 'A' },
+          },
+          y: {
+            $$typeof: Symbol.for('react.element'),
+            type: 'div',
+            key: null,
+            props: { className: 'x' },
+            _owner: { name: 'B' },
+          },
+          expected: '=',
+        },
+        {
+          name: 'element-shaped objects with different props are not equal',
+          x: {
+            $$typeof: Symbol.for('react.element'),
+            type: 'div',
+            props: { className: 'x' },
+            _owner: null,
+          },
+          y: {
+            $$typeof: Symbol.for('react.element'),
+            type: 'div',
+            props: { className: 'y' },
+            _owner: null,
+          },
+          expected: '!=',
+        },
+        {
+          name: '_owner is compared on an object without $$typeof',
+          x: { _owner: { name: 'A' } },
+          y: { _owner: { name: 'B' } },
+          expected: '!=',
+        },
+        {
+          name: '_owner is compared when $$typeof is falsy',
+          x: { $$typeof: null, _owner: { name: 'A' } },
+          y: { $$typeof: null, _owner: { name: 'B' } },
+          expected: '!=',
+        },
+      ] as const satisfies readonly TestCase[])('$name', testFn);
+
       test('React elements with different props are not equal', () => {
         const element1 = React.createElement('div', { className: 'test1' });
 
@@ -747,9 +862,7 @@ describe(fastDeepEqual, () => {
           child.render();
         }
 
-        // Should still be 1 or 2 depending on React element comparison
-        // The important thing is it doesn't throw or hang
-        assert.isTrue(mut_renderCount >= 1);
+        assert.strictEqual(mut_renderCount, 1);
 
         // Update with different props - should re-render
         const differentProps = {
@@ -763,8 +876,7 @@ describe(fastDeepEqual, () => {
           child.render();
         }
 
-        // Should have rendered at least once more
-        assert.isTrue(mut_renderCount >= 2);
+        assert.strictEqual(mut_renderCount, 2);
       });
     });
   });

package/src/others/index.mts

@@ -6,5 +6,6 @@ export * from './if-then.mjs';
 export * from './map-nullable.mjs';
 export * from './memoize-function.mjs';
 export * from './panic-error.mjs';
+export * from './replace-equal-deep.mjs';
 export * from './tuple.mjs';
 export * from './unknown-to-string.mjs';