ts-data-forge 14.10.0 → 14.10.1

package/src/array/impl/array-utils-transformation.mts

@@ -48,8 +48,8 @@ export function map<const Ar extends readonly unknown[] & UnknownBrand, B>(
   mapFn: (a: Ar[number], index: ArrayIndex<Ar>) => B,
 ): ChangeArrayElement<Ar, B>;
 
-// A plain array or tuple carries no length brand, so the homomorphic mapping
-// is the whole answer. Stating it directly — rather than going through
+// A plain array or tuple carries no length brand, so the homomorphic mapping is
+// the whole answer. Stating it directly — rather than going through
 // `ChangeArrayElement`, whose `HasLengthConstraint` test a *generic* `Ar`
 // cannot decide — is what keeps `map` usable inside a function that is itself
 // generic over the tuple: a deferred conditional is not assignable to the
@@ -68,8 +68,8 @@ export function map<const Ar extends readonly unknown[], B>(
 //
 // Spelled as an intersection of two function types rather than one object type
 // carrying two call signatures — the `convert-to-readonly` codemod wraps an
-// inline object type in `Readonly<…>`, and a mapped type drops call
-// signatures, which would leave the curried form with none at all.
+// inline object type in `Readonly<…>`, and a mapped type drops call signatures,
+// which would leave the curried form with none at all.
 export function map<A, B>(
   mapFn: (a: A, index: SizeType.Arr) => B,
 ): (<const Ar extends readonly A[] & UnknownBrand>(
@@ -175,26 +175,6 @@ export function scan<E, S>(
   }
 }
 
-const scanImpl = <E, S>(
-  array: readonly E[],
-  reducer: (accumulator: S, currentValue: E, currentIndex: SizeType.Arr) => S,
-  init: S,
-): NonEmptyTuple<S> => {
-  const mut_result = castMutable<NonEmptyTuple<S>>(
-    newArray<PositiveUint32, S>(asPositiveUint32(array.length + 1), init),
-  );
-
-  let mut_acc = init;
-
-  for (const [index, value] of array.entries()) {
-    mut_acc = reducer(mut_acc, value, asUint32(index));
-
-    mut_result[index + 1] = mut_acc;
-  }
-
-  return mut_result;
-};
-
 /**
  * Reverses an array.
  *
@@ -277,16 +257,6 @@ export function toSorted(
   );
 }
 
-/** The result of sorting `Ar`: same elements, same length, same bounds. */
-type SortedResult<Ar extends readonly unknown[]> =
-  HasLengthConstraint<Ar> extends true
-    ? ChangeArrayElement<Ar, Ar[number]>
-    : IsFixedLengthList<Ar> extends true
-      ? FixedLengthTuple<Ar['length'], Ar[number]>
-      : Ar extends NonEmptyTuple<unknown>
-        ? NonEmptyArray<Ar[number]>
-        : readonly Ar[number][];
-
 /**
  * Sorts an array by a mapped value.
  *
@@ -426,11 +396,6 @@ export function filter<E>(
   }
 }
 
-const filterImpl = <E,>(
-  array: readonly E[],
-  predicate: (a: E, index: SizeType.Arr) => boolean,
-): readonly E[] => array.filter((a, i) => predicate(a, asUint32(i)));
-
 /**
  * Filters an array by excluding elements for which the predicate returns true.
  *
@@ -474,11 +439,6 @@ export function filterNot<E>(
   }
 }
 
-const filterNotImpl = <E,>(
-  array: readonly E[],
-  predicate: (a: E, index: SizeType.Arr) => boolean,
-): readonly E[] => array.filter((a, i) => !predicate(a, asUint32(i)));
-
 /**
  * Creates a new array with unique elements.
  *
@@ -615,11 +575,6 @@ export function flat<E, D extends SafeUintWithSmallInt = 1>(
   }
 }
 
-const flatImpl = (
-  array: readonly unknown[],
-  depth?: SafeUintWithSmallInt,
-): readonly unknown[] => array.flat(depth);
-
 /**
  * Maps each element and flattens the result.
  *
@@ -734,37 +689,6 @@ export function partition<
   }
 }
 
-/**
- * Element type of {@link partition}'s result: a chunk holds between 1 and `N`
- * elements. The lower bound is what makes this worth spelling out — `partition`
- * never emits an empty chunk, so indexed access into a chunk is not
- * `undefined` at position `0`, unlike with a plain `readonly E[]`.
- *
- * Falls back to {@link NonEmptyArray} when `N` is not a bound the brand can
- * express, which keeps that lower bound in every case.
- */
-type PartitionChunk<N, E> = N extends SupportedLength
-  ? BoundedLengthArray<1, N, E>
-  : NonEmptyArray<E>;
-
-const partitionImpl = <E, N extends WithSmallInt<PositiveInt & SizeType.Arr>>(
-  array: readonly E[],
-  chunkSize: N,
-): readonly (readonly E[])[] =>
-  chunkSize < 2
-    ? ([] as const)
-    : // eslint-disable-next-line total-functions/no-partial-division
-      seq(asUint32(Math.ceil(array.length / chunkSize))).map((i: Uint32) =>
-        array.slice(chunkSize * i, chunkSize * (i + 1)),
-      );
-
-/**
- * Alias for `partition`.
- *
- * @see {@link partition}
- */
-export const chunk = partition;
-
 /**
  * Concatenates two arrays.
  *
@@ -805,22 +729,6 @@ export const concat = <
   // eslint-disable-next-line total-functions/no-unsafe-type-assertion
   [...array1, ...array2] as never;
 
-/**
- * Return type of {@link concat}: the concatenated tuple `readonly [...Ar1,
- * ...Ar2]`, additionally branded as {@link NonEmptyArray} when either input is
- * a non-empty tuple (a plain non-empty tuple or a branded `NonEmptyArray`,
- * both of which extend `NonEmptyTuple<unknown>`).
- */
-type ConcatResult<
-  Ar1 extends readonly unknown[],
-  Ar2 extends readonly unknown[],
-> =
-  Ar1 extends NonEmptyTuple<unknown>
-    ? readonly [...Ar1, ...Ar2] & NonEmptyArray<Ar1[number] | Ar2[number]>
-    : Ar2 extends NonEmptyTuple<unknown>
-      ? readonly [...Ar1, ...Ar2] & NonEmptyArray<Ar1[number] | Ar2[number]>
-      : readonly [...Ar1, ...Ar2];
-
 /**
  * Groups elements by a key derived from each element.
  *
@@ -985,3 +893,95 @@ export const cartesianProduct = <T,>(
 
   return first.flatMap((item) => restProduct.map((prod) => [item, ...prod]));
 };
+
+const scanImpl = <E, S>(
+  array: readonly E[],
+  reducer: (accumulator: S, currentValue: E, currentIndex: SizeType.Arr) => S,
+  init: S,
+): NonEmptyTuple<S> => {
+  const mut_result = castMutable<NonEmptyTuple<S>>(
+    newArray<PositiveUint32, S>(asPositiveUint32(array.length + 1), init),
+  );
+
+  let mut_acc = init;
+
+  for (const [index, value] of array.entries()) {
+    mut_acc = reducer(mut_acc, value, asUint32(index));
+
+    mut_result[index + 1] = mut_acc;
+  }
+
+  return mut_result;
+};
+
+/** The result of sorting `Ar`: same elements, same length, same bounds. */
+type SortedResult<Ar extends readonly unknown[]> =
+  HasLengthConstraint<Ar> extends true
+    ? ChangeArrayElement<Ar, Ar[number]>
+    : IsFixedLengthList<Ar> extends true
+      ? FixedLengthTuple<Ar['length'], Ar[number]>
+      : Ar extends NonEmptyTuple<unknown>
+        ? NonEmptyArray<Ar[number]>
+        : readonly Ar[number][];
+
+const filterImpl = <E,>(
+  array: readonly E[],
+  predicate: (a: E, index: SizeType.Arr) => boolean,
+): readonly E[] => array.filter((a, i) => predicate(a, asUint32(i)));
+
+const filterNotImpl = <E,>(
+  array: readonly E[],
+  predicate: (a: E, index: SizeType.Arr) => boolean,
+): readonly E[] => array.filter((a, i) => !predicate(a, asUint32(i)));
+
+const flatImpl = (
+  array: readonly unknown[],
+  depth?: SafeUintWithSmallInt,
+): readonly unknown[] => array.flat(depth);
+
+/**
+ * Element type of {@link partition}'s result: a chunk holds between 1 and `N`
+ * elements. The lower bound is what makes this worth spelling out — `partition`
+ * never emits an empty chunk, so indexed access into a chunk is not `undefined`
+ * at position `0`, unlike with a plain `readonly E[]`.
+ *
+ * Falls back to {@link NonEmptyArray} when `N` is not a bound the brand can
+ * express, which keeps that lower bound in every case.
+ */
+type PartitionChunk<N, E> = N extends SupportedLength
+  ? BoundedLengthArray<1, N, E>
+  : NonEmptyArray<E>;
+
+const partitionImpl = <E, N extends WithSmallInt<PositiveInt & SizeType.Arr>>(
+  array: readonly E[],
+  chunkSize: N,
+): readonly (readonly E[])[] =>
+  chunkSize < 2
+    ? ([] as const)
+    : // eslint-disable-next-line total-functions/no-partial-division
+      seq(asUint32(Math.ceil(array.length / chunkSize))).map((i: Uint32) =>
+        array.slice(chunkSize * i, chunkSize * (i + 1)),
+      );
+
+/**
+ * Alias for `partition`.
+ *
+ * @see {@link partition}
+ */
+export const chunk = partition;
+
+/**
+ * Return type of {@link concat}: the concatenated tuple `readonly [...Ar1,
+ * ...Ar2]`, additionally branded as {@link NonEmptyArray} when either input is
+ * a non-empty tuple (a plain non-empty tuple or a branded `NonEmptyArray`, both
+ * of which extend `NonEmptyTuple<unknown>`).
+ */
+type ConcatResult<
+  Ar1 extends readonly unknown[],
+  Ar2 extends readonly unknown[],
+> =
+  Ar1 extends NonEmptyTuple<unknown>
+    ? readonly [...Ar1, ...Ar2] & NonEmptyArray<Ar1[number] | Ar2[number]>
+    : Ar2 extends NonEmptyTuple<unknown>
+      ? readonly [...Ar1, ...Ar2] & NonEmptyArray<Ar1[number] | Ar2[number]>
+      : readonly [...Ar1, ...Ar2];

package/src/array/impl/array-utils-transformation.test.mts

@@ -71,8 +71,8 @@ describe('Arr transformations', () => {
 
     test('should preserve the tuple shape under a generic parameter', () => {
       // A caller that is itself generic over the tuple cannot resolve a
-      // conditional return type, so `map` has to report the homomorphic
-      // mapping directly for a parameter that carries no length brand.
+      // conditional return type, so `map` has to report the homomorphic mapping
+      // directly for a parameter that carries no length brand.
       const mapValues = <const T extends readonly Readonly<{ v: unknown }>[]>(
         boxes: T,
       ): Readonly<{ [K in keyof T]: unknown }> => map(boxes, (b) => b.v);

package/src/array/impl/array-utils-validation.mts

@@ -63,11 +63,11 @@ type Cast<A, B> = A extends B ? A : never;
  */
 // Type guard overloads - narrow the entire array type.
 //
-// Both narrowed types are intersected with `Ar`: a type predicate's type has
-// to be assignable to the parameter's type, and neither the deferred
-// conditional `ChangeArrayElement<Ar, S>` nor the mapped type over a generic
-// `Ar` is (TS2677). The intersection also keeps whatever the caller already
-// knew about the array — a branded five-tuple stays a five-tuple.
+// Both narrowed types are intersected with `Ar`: a type predicate's type has to
+// be assignable to the parameter's type, and neither the deferred conditional
+// `ChangeArrayElement<Ar, S>` nor the mapped type over a generic `Ar` is
+// (TS2677). The intersection also keeps whatever the caller already knew about
+// the array — a branded five-tuple stays a five-tuple.
 export function every<
   const Ar extends readonly unknown[] & UnknownBrand,
   S extends Ar[number],
@@ -76,8 +76,8 @@ export function every<
   predicate: (a: Ar[number], index: ArrayIndex<Ar>) => a is S,
 ): array is ChangeArrayElement<Ar, S> & Ar;
 
-// A plain array or tuple carries no length brand, so the homomorphic mapping
-// is the whole answer — same reasoning as in `map`.
+// A plain array or tuple carries no length brand, so the homomorphic mapping is
+// the whole answer — same reasoning as in `map`.
 export function every<
   const Ar extends readonly unknown[],
   S extends Ar[number],
@@ -98,8 +98,8 @@ export function every<const Ar extends readonly unknown[]>(
 // returned function*, not two overloads of `every` itself: both curried
 // signatures take the same single predicate, so overload resolution would
 // always pick the first and the second would be dead — which is what left a
-// plain `readonly unknown[]` unable to satisfy the `UnknownBrand` constraint
-// at the call site of the returned guard.
+// plain `readonly unknown[]` unable to satisfy the `UnknownBrand` constraint at
+// the call site of the returned guard.
 //
 // The intersection is also what keeps the group compatible with the
 // implementation signature. A lone `<Ar extends readonly E[] & UnknownBrand>`
@@ -136,11 +136,6 @@ export function every<E>(
   }
 }
 
-const everyImpl = <E,>(
-  array: readonly E[],
-  predicate: (a: E, index: SizeType.Arr) => boolean,
-): boolean => array.every((a, i) => predicate(a, asUint32(i)));
-
 /**
  * Tests whether at least one element in an array passes a test implemented by a predicate.
  *
@@ -186,11 +181,6 @@ export function some<E>(
   }
 }
 
-const someImpl = <E,>(
-  array: readonly E[],
-  predicate: (a: E, index: SizeType.Arr) => boolean,
-): boolean => array.some((a, i) => predicate(a, asUint32(i)));
-
 /**
  * Checks if an index is within the valid range of an array.
  *
@@ -212,3 +202,13 @@ export const indexIsInRange = <E,>(
   array: readonly E[],
   index: SizeType.ArgArr,
 ): boolean => Num.isInRange(0, array.length)(index);
+
+const everyImpl = <E,>(
+  array: readonly E[],
+  predicate: (a: E, index: SizeType.Arr) => boolean,
+): boolean => array.every((a, i) => predicate(a, asUint32(i)));
+
+const someImpl = <E,>(
+  array: readonly E[],
+  predicate: (a: E, index: SizeType.Arr) => boolean,
+): boolean => array.some((a, i) => predicate(a, asUint32(i)));

package/src/array/impl/array-utils-validation.test.mts

@@ -39,7 +39,7 @@ describe('Arr validations', () => {
 
       assert.isFalse(isArray({}));
 
-      assert.isFalse(isArray(new Set()));
+      assert.isFalse(isArray(new Set<unknown>()));
     });
 
     test('should refine union types correctly', () => {

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