ts-data-forge 6.4.0 → 6.6.0

package/src/json/json.test.mts

@@ -54,7 +54,7 @@ describe('parse', () => {
           array: [1, 2, { level3: 'deep' }],
         },
       },
-    };
+    } as const;
 
     assert.deepStrictEqual(Json.parse(json), Result.ok(expected));
   });
@@ -227,7 +227,7 @@ describe('stringify', () => {
           array: [1, 2, { level3: 'deep' }],
         },
       },
-    };
+    } as const;
 
     assert.deepStrictEqual(
       Json.stringify(nested),
@@ -301,7 +301,7 @@ describe('stringify', () => {
   test('should handle objects with toJSON method', () => {
     const obj = {
       toJSON: () => ({ custom: 'value' }),
-    };
+    } as const;
 
     assert.deepStrictEqual(
       Json.stringify(obj),
@@ -333,7 +333,7 @@ describe('stringify', () => {
       name: 'John',
       password: 'secret123',
       email: 'john@example.com',
-    };
+    } as const;
 
     const secureReplacer = (key: string, value: unknown): unknown => {
       if (key === 'password') return '[REDACTED]';
@@ -351,7 +351,7 @@ describe('stringify', () => {
   });
 
   test('should format output with space parameter (number)', () => {
-    const data = { a: 1, b: 2 };
+    const data = { a: 1, b: 2 } as const;
 
     const result = Json.stringify(data, undefined, 2);
 
@@ -363,7 +363,7 @@ describe('stringify', () => {
   });
 
   test('should format output with space parameter (string)', () => {
-    const data = { a: 1, b: 2 };
+    const data = { a: 1, b: 2 } as const;
 
     const result = Json.stringify(data, undefined, '\t');
 
@@ -383,7 +383,7 @@ describe('stringifySelected', () => {
       email: 'alice@example.com',
       password: 'secret123',
       lastLogin: '2023-12-01',
-    };
+    } as const;
 
     const result = Json.stringifySelected(user, ['id', 'name', 'email']);
 
@@ -411,7 +411,7 @@ describe('stringifySelected', () => {
         { id: 2, name: 'Bob', secret: 'hidden2' },
       ],
       metadata: { total: 2, page: 1, internal: 'secret' },
-    };
+    } as const;
 
     const result = Json.stringifySelected(data, [
       'users',
@@ -453,7 +453,7 @@ describe('stringifySelected', () => {
       [1, 2, 3, 4],
       [5, 6, 7, 8],
       [9, 10, 11, 12],
-    ];
+    ] as const;
 
     const result = Json.stringifySelected(matrix, [0, 1]);
 
@@ -465,13 +465,14 @@ describe('stringifySelected', () => {
 
     // Note: stringifySelected works with JSON.stringify's replacer parameter
     // which may not work as expected with arrays
+    // eslint-disable-next-line ts-data-forge/prefer-arr-is-array
     assert.isTrue(Array.isArray(parsed));
 
     expect(parsed).toHaveLength(3);
   });
 
   test('should handle formatting with space parameter', () => {
-    const data = { a: 1, b: { c: 2 } };
+    const data = { a: 1, b: { c: 2 } } as const;
 
     const result = Json.stringifySelected(data, ['a', 'b', 'c'], 2);
 
@@ -483,7 +484,7 @@ describe('stringifySelected', () => {
   });
 
   test('should handle empty selection array', () => {
-    const data = { a: 1, b: 2, c: 3 };
+    const data = { a: 1, b: 2, c: 3 } as const;
 
     const result = Json.stringifySelected(data, []);
 
@@ -493,7 +494,7 @@ describe('stringifySelected', () => {
   });
 
   test('should handle undefined properties parameter', () => {
-    const data = { a: 1, b: 2 };
+    const data = { a: 1, b: 2 } as const;
 
     const result = Json.stringifySelected(data, undefined);
 
@@ -532,7 +533,7 @@ describe('stringifySortedKey', () => {
       apple: 'fruit',
       banana: 'fruit',
       aardvark: 'animal',
-    };
+    } as const;
 
     const result = Json.stringifySortedKey(unsortedObj);
 
@@ -558,7 +559,7 @@ describe('stringifySortedKey', () => {
         theme: 'dark',
         language: 'en',
       },
-    };
+    } as const;
 
     const result = Json.stringifySortedKey(nestedObj);
 
@@ -598,7 +599,7 @@ describe('stringifySortedKey', () => {
         created: '2023-12-01',
         author: 'system',
       },
-    };
+    } as const;
 
     const result = Json.stringifySortedKey(dataWithArrays);
 
@@ -639,7 +640,7 @@ describe('stringifySortedKey', () => {
   });
 
   test('should handle formatting with space parameter', () => {
-    const obj = { b: 2, a: 1 };
+    const obj = { b: 2, a: 1 } as const;
 
     const result = Json.stringifySortedKey(obj, 2);
 
@@ -653,9 +654,9 @@ describe('stringifySortedKey', () => {
   });
 
   test('should produce deterministic output', () => {
-    const obj1 = { c: 3, a: 1, b: 2 };
+    const obj1 = { c: 3, a: 1, b: 2 } as const;
 
-    const obj2 = { b: 2, a: 1, c: 3 };
+    const obj2 = { b: 2, a: 1, c: 3 } as const;
 
     const result1 = Json.stringifySortedKey(obj1);
 
@@ -716,7 +717,7 @@ describe('stringifySortedKey', () => {
           },
         },
       },
-    };
+    } as const;
 
     const result = Json.stringifySortedKey(deep);
 

package/src/number/branded-types/non-zero-safe-int.mts

@@ -27,9 +27,9 @@ const {
 >({
   integerOrSafeInteger: 'SafeInteger',
   nonZero: true,
-  // eslint-disable-next-line total-functions/no-unsafe-type-assertion, math/prefer-number-min-safe-integer
+  // eslint-disable-next-line total-functions/no-unsafe-type-assertion, math/prefer-number-min-safe-integer, ts-data-forge/prefer-as-int
   MIN_VALUE: Number.MIN_SAFE_INTEGER as SafeInt,
-  // eslint-disable-next-line total-functions/no-unsafe-type-assertion, math/prefer-number-max-safe-integer
+  // eslint-disable-next-line total-functions/no-unsafe-type-assertion, math/prefer-number-max-safe-integer, ts-data-forge/prefer-as-int
   MAX_VALUE: Number.MAX_SAFE_INTEGER as SafeUint,
   typeNameInMessage,
 } as const);

package/src/number/branded-types/positive-safe-int.mts

@@ -26,7 +26,7 @@ const {
 >({
   integerOrSafeInteger: 'SafeInteger',
   MIN_VALUE: 1,
-  // eslint-disable-next-line total-functions/no-unsafe-type-assertion, math/prefer-number-max-safe-integer
+  // eslint-disable-next-line total-functions/no-unsafe-type-assertion, math/prefer-number-max-safe-integer, ts-data-forge/prefer-as-int
   MAX_VALUE: Number.MAX_SAFE_INTEGER as SafeUint,
   typeNameInMessage,
 } as const);

package/src/number/branded-types/safe-int.mts

@@ -26,9 +26,9 @@ const {
   SafeUint
 >({
   integerOrSafeInteger: 'SafeInteger',
-  // eslint-disable-next-line total-functions/no-unsafe-type-assertion, math/prefer-number-min-safe-integer
+  // eslint-disable-next-line total-functions/no-unsafe-type-assertion, math/prefer-number-min-safe-integer, ts-data-forge/prefer-as-int
   MIN_VALUE: Number.MIN_SAFE_INTEGER as SafeInt,
-  // eslint-disable-next-line total-functions/no-unsafe-type-assertion, math/prefer-number-max-safe-integer
+  // eslint-disable-next-line total-functions/no-unsafe-type-assertion, math/prefer-number-max-safe-integer, ts-data-forge/prefer-as-int
   MAX_VALUE: Number.MAX_SAFE_INTEGER as SafeUint,
   typeNameInMessage,
 } as const);

package/src/number/branded-types/safe-uint.mts

@@ -26,7 +26,7 @@ const {
 >({
   integerOrSafeInteger: 'SafeInteger',
   MIN_VALUE: 0,
-  // eslint-disable-next-line total-functions/no-unsafe-type-assertion, math/prefer-number-max-safe-integer
+  // eslint-disable-next-line total-functions/no-unsafe-type-assertion, math/prefer-number-max-safe-integer, ts-data-forge/prefer-as-int
   MAX_VALUE: Number.MAX_SAFE_INTEGER as SafeUint,
   typeNameInMessage,
 } as const);

package/src/number/num.mts

@@ -391,7 +391,7 @@ export namespace Num {
    * @param num - The number to round
    * @returns The rounded integer as an Int branded type
    */
-  // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+  // eslint-disable-next-line total-functions/no-unsafe-type-assertion, ts-data-forge/prefer-as-int
   export const roundToInt = (num: number): Int => Math.trunc(num + 0.5) as Int;
 
   /**

package/src/object/object.mts

@@ -16,20 +16,20 @@ export namespace Obj {
    * @example
    *
    * ```ts
-   * const obj1 = { name: 'Alice', age: 30 };
+   * const obj1 = { name: 'Alice', age: 30 } as const;
    *
-   * const obj2 = { name: 'Alice', age: 30 };
+   * const obj2 = { name: 'Alice', age: 30 } as const;
    *
-   * const obj3 = { name: 'Alice', age: 31 };
+   * const obj3 = { name: 'Alice', age: 31 } as const;
    *
    * assert.isTrue(Obj.shallowEq(obj1, obj2));
    *
    * assert.isFalse(Obj.shallowEq(obj1, obj3));
    *
    * // Custom equality function
-   * const obj4 = { value: 1 };
+   * const obj4 = { value: 1 } as const;
    *
-   * const obj5 = { value: 1.00001 };
+   * const obj5 = { value: 1.00001 } as const;
    *
    * const closeEnough = (a: unknown, b: unknown): boolean => {
    *   if (typeof a === 'number' && typeof b === 'number') {
@@ -58,6 +58,7 @@ 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));
@@ -80,7 +81,7 @@ export namespace Obj {
    *   email: 'bob@example.com',
    *   password: 'secret',
    *   role: 'admin',
-   * };
+   * } as const;
    *
    * // Direct usage
    * const publicInfo = Obj.pick(user, ['id', 'name', 'role']);
@@ -166,7 +167,7 @@ export namespace Obj {
    *   email: 'charlie@example.com',
    *   password: 'secret123',
    *   internalNote: 'VIP customer',
-   * };
+   * } as const;
    *
    * // Direct usage - remove sensitive fields
    * const safeUser = Obj.omit(user, ['password', 'internalNote']);
@@ -277,7 +278,7 @@ export namespace Obj {
    * const dynamicEntries: readonly (readonly ['x' | 'y', number])[] = [
    *   ['x', 10],
    *   ['y', 20],
-   * ];
+   * ] as const;
    *
    * const obj2 = Obj.fromEntries(dynamicEntries);
    *
@@ -377,5 +378,50 @@ export namespace Obj {
 
     export type PartialIfKeyIsUnion<K, T> =
       IsUnion<K> extends true ? Partial<T> : T;
+
+    /** Merges two object types where keys in B override keys in A. */
+    type MergeTwo<A extends UnknownRecord, B extends UnknownRecord> = Readonly<{
+      [K in keyof A | keyof B]: K extends keyof B
+        ? B[K]
+        : K extends keyof A
+          ? A[K]
+          : never;
+    }>;
+
+    /** Sequentially merges a tuple of object types from left to right. */
+    export type MergeAll<
+      Records extends readonly UnknownRecord[],
+      // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+      Acc extends UnknownRecord = {},
+    > = Records extends readonly [
+      infer First extends UnknownRecord,
+      ...infer Rest extends readonly UnknownRecord[],
+    ]
+      ? MergeAll<Rest, MergeTwo<Acc, First>>
+      : Acc;
   }
+
+  /**
+   * Merges multiple records into a single record using `Object.assign`.
+   * Later records override properties from earlier records with the same key.
+   *
+   * @example
+   *
+   * ```ts
+   * const a = { a: 0, b: 0 } as const;
+   * const b = { b: 1, c: 0 } as const;
+   *
+   * const result = Obj.merge(a, b);
+   *
+   * assert.deepStrictEqual(result, { a: 0, b: 1, c: 0 });
+   * ```
+   *
+   * @param records - The records to merge
+   * @returns A new record with all properties merged
+   */
+  export const merge = <const Records extends readonly UnknownRecord[]>(
+    ...records: Records
+  ): TsDataForgeInternals.MergeAll<Records> =>
+    // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+    Object.fromEntries(records.flatMap((r) => Object.entries(r))) as never;
 }

package/src/object/object.test.mts

@@ -47,7 +47,12 @@ describe('pick', () => {
   test('pick should work with pipe when curried', () => {
     const pickIdAndName = Obj.pick(['id', 'name']);
 
-    const user = { id: 1, name: 'Alice', email: 'alice@example.com', age: 30 };
+    const user = {
+      id: 1,
+      name: 'Alice',
+      email: 'alice@example.com',
+      age: 30,
+    } as const;
 
     const result = pipe(user).map(pickIdAndName).value;
 
@@ -103,7 +108,7 @@ describe('omit', () => {
       name: 'Alice',
       email: 'alice@example.com',
       password: 'secret123',
-    };
+    } as const;
 
     const result = pipe(user).map(omitSensitive).value;
 
@@ -113,7 +118,7 @@ describe('omit', () => {
   test('omit should handle empty keys in curried form', () => {
     const omitNone = Obj.omit([]);
 
-    const original = { a: 1, b: 2, c: 3 };
+    const original = { a: 1, b: 2, c: 3 } as const;
 
     const result = omitNone(original);
 
@@ -149,9 +154,9 @@ describe('omit', () => {
 describe('fromEntries', () => {
   test('should build readonly object from fixed entries', () => {
     const entries = [
-      ['name', 'Alice'] as const,
-      ['age', 30 as const],
-      ['active', true as const],
+      ['name', 'Alice'],
+      ['age', 30],
+      ['active', true],
     ] as const;
 
     const result = Obj.fromEntries(entries);
@@ -167,7 +172,7 @@ describe('fromEntries', () => {
   test('should produce partial record when keys are unions', () => {
     const dynamicEntries: readonly (readonly ['name' | 'email', string])[] = [
       ['name', 'Alice'],
-    ];
+    ] as const;
 
     const result = Obj.fromEntries(dynamicEntries) satisfies Partial<
       Readonly<Record<'name' | 'email', string>>
@@ -176,3 +181,61 @@ describe('fromEntries', () => {
     assert.deepStrictEqual(result, { name: 'Alice' });
   });
 });
+
+describe('merge', () => {
+  test('should merge two objects, later overriding earlier', () => {
+    const a = { a: 0, b: 0 } as const;
+
+    const b = { b: 1, c: 0 } as const;
+
+    const result = Obj.merge(a, b);
+
+    expectType<typeof result, Readonly<{ a: 0; b: 1; c: 0 }>>('=');
+
+    assert.deepStrictEqual(result, { a: 0, b: 1, c: 0 });
+  });
+
+  test('should merge three objects', () => {
+    const a = { x: 1, y: 2 } as const;
+
+    const b = { y: 3, z: 4 } as const;
+
+    const c = { z: 5, w: 6 } as const;
+
+    const result = Obj.merge(a, b, c);
+
+    expectType<typeof result, Readonly<{ x: 1; y: 3; z: 5; w: 6 }>>('=');
+
+    assert.deepStrictEqual(result, { x: 1, y: 3, z: 5, w: 6 });
+  });
+
+  test('should return empty object when called with no arguments', () => {
+    const result = Obj.merge();
+
+    expectType<typeof result, {}>('=');
+
+    assert.deepStrictEqual(result, {});
+  });
+
+  test('should return the same shape for a single argument', () => {
+    const a = { a: 1, b: 2 } as const;
+
+    const result = Obj.merge(a);
+
+    expectType<typeof result, Readonly<{ a: 1; b: 2 }>>('=');
+
+    assert.deepStrictEqual(result, { a: 1, b: 2 });
+  });
+
+  test('type: later key completely overrides earlier key type', () => {
+    const a = { key: 'hello' } as const;
+
+    const b = { key: 42 } as const;
+
+    const result = Obj.merge(a, b);
+
+    expectType<typeof result, Readonly<{ key: 42 }>>('=');
+
+    assert.deepStrictEqual(result, { key: 42 });
+  });
+});

package/src/others/cast-mutable.test.mts

@@ -3,7 +3,7 @@ import { castDeepMutable, castMutable } from './cast-mutable.mjs';
 
 describe(castMutable, () => {
   test('should allow mutating arrays that were readonly', () => {
-    const readonlyArray: readonly number[] = [1, 2, 3];
+    const readonlyArray: readonly number[] = [1, 2, 3] as const;
 
     const mut_array = castMutable(readonlyArray);
 
@@ -21,7 +21,7 @@ describe(castMutable, () => {
     const readonlyUser: Readonly<{ name: string; age: number }> = {
       name: 'Alice',
       age: 30,
-    };
+    } as const;
 
     const mut_user = castMutable(readonlyUser);
 
@@ -56,7 +56,7 @@ describe(castDeepMutable, () => {
           tags: ['admin', 'owner'],
         },
       },
-    };
+    } as const;
 
     const mut_state = castDeepMutable(readonlyState);
 

package/src/others/cast-readonly.test.mts

@@ -2,7 +2,7 @@ import { castDeepReadonly, castReadonly } from './cast-readonly.mjs';
 
 describe(castReadonly, () => {
   test('should cast mutable array to readonly', () => {
-    const mutableArr = [1, 2, 3];
+    const mutableArr = [1, 2, 3] as const;
 
     const readonlyArr = castReadonly(mutableArr);
 
@@ -12,7 +12,7 @@ describe(castReadonly, () => {
   });
 
   test('should cast mutable object to readonly', () => {
-    const mutableObj = { x: 1, y: 2 };
+    const mutableObj = { x: 1, y: 2 } as const;
 
     const readonlyObj = castReadonly(mutableObj);
 
@@ -22,7 +22,7 @@ describe(castReadonly, () => {
   });
 
   test('should preserve the runtime value', () => {
-    const original = { value: 42 };
+    const original = { value: 42 } as const;
 
     const readonly = castReadonly(original);
 
@@ -52,7 +52,7 @@ describe(castDeepReadonly, () => {
     const mutableNested = {
       a: { b: [1, 2, 3] },
       c: { d: { e: 'value' } },
-    };
+    } as const;
 
     const readonlyNested = castDeepReadonly(mutableNested);
 
@@ -64,9 +64,13 @@ describe(castDeepReadonly, () => {
   });
 
   test('should preserve runtime value for complex structures', () => {
+    // transformer-ignore-next-line convert-to-readonly
     const complex = {
       users: [{ id: 1, profile: { name: 'Alice' } }],
       settings: { theme: 'dark', options: { debug: true } },
+    } as {
+      users: { id: number; profile: { name: string } }[];
+      settings: { theme: string; options: { debug: boolean } };
     };
 
     const readonly = castDeepReadonly(complex);
@@ -79,10 +83,11 @@ describe(castDeepReadonly, () => {
   });
 
   test('should work with arrays of objects', () => {
+    // transformer-ignore-next-line convert-to-readonly
     const data = [
       { id: 1, meta: { active: true } },
       { id: 2, meta: { active: false } },
-    ];
+    ] as { id: number; meta: { active: boolean } }[];
 
     const readonly = castDeepReadonly(data);
 

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

@@ -0,0 +1,98 @@
+/* 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';
+import { hasKey, isRecord } from '../guard/index.mjs';
+
+/**
+ * The fastest deep equal with ES6 Map, Set and Typed arrays support.
+ * Checks equality of Date and RegExp objects by value.
+ *
+ * Forked from https://github.com/epoberezkin/fast-deep-equal/blob/v3.1.3/src/index.jst
+ */
+export const fastDeepEqual = <T,>(a: T, b: T): boolean => {
+  if (a === b) {
+    return true;
+  }
+
+  if (typeof a !== typeof b) {
+    return false;
+  }
+
+  if (isRecord(a)) {
+    if (!isRecord(b)) {
+      return false;
+    }
+
+    if (a.constructor !== b.constructor) {
+      return false;
+    }
+
+    if (Array.isArray(a)) {
+      return (
+        Array.isArray(b) &&
+        a.length === b.length &&
+        a.every((ai, index) => fastDeepEqual(ai, b[index]))
+      );
+    }
+
+    if (isMap(a)) {
+      return (
+        isMap(b) &&
+        a.size === b.size &&
+        Array.from(a.entries()).every(
+          ([key, value]) => b.has(key) && fastDeepEqual(value, b.get(key)),
+        )
+      );
+    }
+
+    if (isSet(a)) {
+      return (
+        isSet(b) &&
+        a.size === b.size &&
+        Array.from(a.entries()).every(([value]) => b.has(value))
+      );
+    }
+
+    if (isTypedArray(a)) {
+      return (
+        isTypedArray(b) &&
+        a.length === b.length &&
+        a.every((value, index) => value === b[index])
+      );
+    }
+
+    if (isRegExp(a)) {
+      return isRegExp(b) && a.source === b.source && a.flags === b.flags;
+    }
+
+    if (a.valueOf !== Object.prototype.valueOf) {
+      return a.valueOf() === b.valueOf();
+    }
+
+    if (a.toString !== Object.prototype.toString) {
+      return a.toString() === b.toString();
+    }
+
+    const aKeys: readonly string[] = Object.keys(a);
+
+    const bKeys: readonly string[] = Object.keys(b);
+
+    return (
+      aKeys.length === bKeys.length &&
+      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]),
+      )
+    );
+  }
+
+  // true if both NaN, false otherwise
+  return Number.isNaN(a) && Number.isNaN(b);
+};