ts-data-forge 14.10.0 → 14.10.2

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 < 1
+    ? ([] 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

@@ -12,6 +12,7 @@ import { SafeUint } from '../../number/index.mjs';
 import { asMinLengthArray } from './array-utils-length-bounded-array-cast.mjs';
 import {
   cartesianProduct,
+  chunk,
   concat,
   filter,
   filterNot,
@@ -71,8 +72,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);
@@ -759,13 +760,61 @@ describe('Arr transformations', () => {
       ]);
     });
 
-    test('should work with chunk size < 2 (returns empty)', () => {
+    test('returns singleton chunks for size one', () => {
       const numbers = [1, 2, 3] as const;
 
       const result = partition(numbers, 1);
 
-      // According to docs, returns empty array if chunkSize < 2
-      assert.deepStrictEqual(result, []);
+      expectType<typeof result, readonly BoundedLengthArray<1, 1, 1 | 2 | 3>[]>(
+        '~=',
+      );
+
+      assert.deepStrictEqual<readonly (readonly number[])[]>(result, [
+        [1],
+        [2],
+        [3],
+      ]);
+    });
+
+    test('preserves singleton chunks through the alias and curried overloads', () => {
+      const numbers = [1, 2, 3] as const;
+
+      const expected = [[1], [2], [3]] as const;
+
+      assert.deepStrictEqual<readonly (readonly number[])[]>(
+        partition(1)(numbers),
+        expected,
+      );
+
+      assert.deepStrictEqual<readonly (readonly number[])[]>(
+        chunk(numbers, 1),
+        expected,
+      );
+
+      assert.deepStrictEqual<readonly (readonly number[])[]>(
+        chunk(1)(numbers),
+        expected,
+      );
+    });
+
+    test('size one produces no chunk for an empty array', () => {
+      assert.deepStrictEqual(partition([], 1), []);
+
+      assert.deepStrictEqual(partition(1)([]), []);
+
+      assert.deepStrictEqual(chunk([], 1), []);
+
+      assert.deepStrictEqual(chunk(1)([]), []);
+    });
+
+    test('a size below one, which the types reject, produces no chunk', () => {
+      const numbers = [1, 2, 3] as const;
+
+      // @ts-expect-error - a chunk size of 0 is not a positive integer
+      assert.deepStrictEqual(partition(numbers, 0), []);
+
+      // @ts-expect-error - a negative chunk size is not a positive integer
+      assert.deepStrictEqual(partition(-1)(numbers), []);
     });
 
     test('should work with chunk size larger than array', () => {

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
@@ -1161,9 +1161,9 @@ class IMapMappedClass<K, V, KM extends MapSetKeyType>
           break;
 
         case 'update': {
-          const curr = mut_result.get(key);
-
-          if (curr === undefined || !mut_result.has(key)) {
+          // Presence is `has` alone, as in `update`: a stored value may itself
+          // be `undefined`.
+          if (!mut_result.has(key)) {
             if (this.#showNotFoundMessage) {
               console.warn(
                 `IMapMapped.withMutations::update: key not found: ${unknownToString(key)}`,
@@ -1173,7 +1173,9 @@ class IMapMappedClass<K, V, KM extends MapSetKeyType>
             break;
           }
 
-          mut_result.set(key, action.updater(curr));
+          // `has` held, so `get` returns the stored `V`, `undefined` included.
+          // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+          mut_result.set(key, action.updater(mut_result.get(key) as V));
 
           break;
         }

package/src/collections/imap-mapped.test.mts

@@ -705,6 +705,33 @@ describe('IMapMapped.withMutations', () => {
     expect(Optional.unwrap(updated.get({ id: 2, type: 'admin' }))).toBe('Bob');
   });
 
+  test('update calls the updater for a key whose value is undefined, as update() does', () => {
+    const map = IMapMapped.create<TestKey, string | undefined, string>(
+      [[{ id: 1, type: 'user' }, undefined]],
+      testKeyToString,
+      stringToTestKey,
+    );
+
+    const updater = (x: string | undefined): string | undefined =>
+      x ?? 'filled';
+
+    const batched = map.withMutations([
+      { type: 'update', key: { id: 1, type: 'user' }, updater },
+    ]);
+
+    expect(Optional.unwrap(batched.get({ id: 1, type: 'user' }))).toBe(
+      'filled',
+    );
+
+    expect(
+      Optional.unwrap(
+        map
+          .update({ id: 1, type: 'user' }, updater)
+          .get({ id: 1, type: 'user' }),
+      ),
+    ).toBe('filled');
+  });
+
   test('should handle empty mutations array', () => {
     const map = IMapMapped.create(
       [[{ id: 1, type: 'user' }, 'Alice']],

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.
    *
@@ -881,9 +880,9 @@ class IMapClass<K extends MapSetKeyType, V>
         case 'update': {
           const { key } = action;
 
-          const curr = mut_result.get(key);
-
-          if (curr === undefined || !mut_result.has(key)) {
+          // Presence is `has` alone, as in `update`: a stored value may itself
+          // be `undefined`.
+          if (!mut_result.has(key)) {
             if (this.#showNotFoundMessage) {
               const keyStr = unknownToString(key);
 
@@ -893,7 +892,9 @@ class IMapClass<K extends MapSetKeyType, V>
             break;
           }
 
-          mut_result.set(key, action.updater(curr));
+          // `has` held, so `get` returns the stored `V`, `undefined` included.
+          // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+          mut_result.set(key, action.updater(mut_result.get(key) as V));
 
           break;
         }

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],
     ]);
@@ -754,6 +754,19 @@ describe('IMap.withMutations', () => {
     assert.isTrue(Optional.isNone(updated.get('nonexistent')));
   });
 
+  test('update calls the updater for a key whose value is undefined, as update() does', () => {
+    const map = IMap.create<string, number | undefined>([['a', undefined]]);
+
+    const updater = (x: number | undefined): number | undefined =>
+      x === undefined ? 1 : x + 1;
+
+    const batched = map.withMutations([{ type: 'update', key: 'a', updater }]);
+
+    expect(Optional.unwrap(batched.get('a'))).toBe(1);
+
+    expect(Optional.unwrap(map.update('a', updater).get('a'))).toBe(1);
+  });
+
   test('should handle mixed operations', () => {
     const map = IMap.create([['a', 1]]);
 

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