ts-data-forge 14.9.0 → 14.10.1

package/src/array/impl/array-utils-length-bounded-tuple-cast.mts

@@ -18,8 +18,8 @@ import {
  * exactly `length` elements.
  *
  * This is the structural counterpart of `asFixedLengthArray`: it produces a
- * tuple type rather than the branded `FixedLengthArray`. Prefer the branded
- * one unless you specifically need the structural type — the brand keeps
+ * tuple type rather than the branded `FixedLengthArray`. Prefer the branded one
+ * unless you specifically need the structural type — the brand keeps
  * type-checking cost independent of the element type and of the bound.
  *
  * The length argument comes first, matching the type-parameter order of
@@ -76,21 +76,6 @@ export function asFixedLengthTuple(
   }
 }
 
-const asFixedLengthTupleImpl = (
-  length: SizeType.ArgArr,
-  xs: readonly unknown[],
-): readonly unknown[] => {
-  const actualLength = xs.length;
-
-  if (!isFixedLengthTuple(length, xs)) {
-    throw new TypeError(
-      `Expected an array of length ${length}, got an array of length ${actualLength}`,
-    );
-  }
-
-  return xs;
-};
-
 /**
  * Casts an array to `MinLengthTuple<MinLength, E>` after checking that it has
  * at least `minLength` elements.
@@ -148,21 +133,6 @@ export function asMinLengthTuple(
   }
 }
 
-const asMinLengthTupleImpl = (
-  minLength: SizeType.ArgArr,
-  xs: readonly unknown[],
-): readonly unknown[] => {
-  const actualLength = xs.length;
-
-  if (!isMinLengthTuple(minLength, xs)) {
-    throw new TypeError(
-      `Expected an array of length >= ${minLength}, got an array of length ${actualLength}`,
-    );
-  }
-
-  return xs;
-};
-
 /**
  * Casts an array to `MaxLengthTuple<MaxLength, E>` after checking that it has
  * at most `maxLength` elements.
@@ -218,21 +188,6 @@ export function asMaxLengthTuple(
   }
 }
 
-const asMaxLengthTupleImpl = (
-  maxLength: SizeType.ArgArr,
-  xs: readonly unknown[],
-): readonly unknown[] => {
-  const actualLength = xs.length;
-
-  if (!isMaxLengthTuple(maxLength, xs)) {
-    throw new TypeError(
-      `Expected an array of length <= ${maxLength}, got an array of length ${actualLength}`,
-    );
-  }
-
-  return xs;
-};
-
 /**
  * Casts an array to `BoundedLengthTuple<Min, Max, E>` after checking that its
  * length is within the inclusive range `[min, max]`.
@@ -299,25 +254,8 @@ export function asBoundedLengthTuple(
   }
 }
 
-const asBoundedLengthTupleImpl = (
-  min: SizeType.ArgArr,
-  max: SizeType.ArgArr,
-  xs: readonly unknown[],
-): readonly unknown[] => {
-  const actualLength = xs.length;
-
-  if (!isBoundedLengthTuple(min, max, xs)) {
-    throw new TypeError(
-      `Expected an array of length in [${min}, ${max}], got an array of length ${actualLength}`,
-    );
-  }
-
-  return xs;
-};
-
 /**
- * Casts an array to the structural empty tuple after checking that it is
- * empty.
+ * Casts an array to the structural empty tuple after checking that it is empty.
  *
  * This is the structural counterpart of `asEmptyArray`, and the length-0
  * specialization of {@link asFixedLengthTuple}.
@@ -382,3 +320,64 @@ export const asNonEmptyTuple = <Xs extends readonly unknown[]>(
 
   return xs;
 };
+
+const asFixedLengthTupleImpl = (
+  length: SizeType.ArgArr,
+  xs: readonly unknown[],
+): readonly unknown[] => {
+  const actualLength = xs.length;
+
+  if (!isFixedLengthTuple(length, xs)) {
+    throw new TypeError(
+      `Expected an array of length ${length}, got an array of length ${actualLength}`,
+    );
+  }
+
+  return xs;
+};
+
+const asMinLengthTupleImpl = (
+  minLength: SizeType.ArgArr,
+  xs: readonly unknown[],
+): readonly unknown[] => {
+  const actualLength = xs.length;
+
+  if (!isMinLengthTuple(minLength, xs)) {
+    throw new TypeError(
+      `Expected an array of length >= ${minLength}, got an array of length ${actualLength}`,
+    );
+  }
+
+  return xs;
+};
+
+const asMaxLengthTupleImpl = (
+  maxLength: SizeType.ArgArr,
+  xs: readonly unknown[],
+): readonly unknown[] => {
+  const actualLength = xs.length;
+
+  if (!isMaxLengthTuple(maxLength, xs)) {
+    throw new TypeError(
+      `Expected an array of length <= ${maxLength}, got an array of length ${actualLength}`,
+    );
+  }
+
+  return xs;
+};
+
+const asBoundedLengthTupleImpl = (
+  min: SizeType.ArgArr,
+  max: SizeType.ArgArr,
+  xs: readonly unknown[],
+): readonly unknown[] => {
+  const actualLength = xs.length;
+
+  if (!isBoundedLengthTuple(min, max, xs)) {
+    throw new TypeError(
+      `Expected an array of length in [${min}, ${max}], got an array of length ${actualLength}`,
+    );
+  }
+
+  return xs;
+};

package/src/array/impl/array-utils-length-bounded-tuple-guard.mts

@@ -102,11 +102,6 @@ export function isFixedLengthTuple(
   }
 }
 
-const hasFixedLength = (
-  len: SizeType.ArgArr,
-  array: readonly unknown[],
-): boolean => array.length === len;
-
 /**
  * Checks if an array has at least a specific length.
  *
@@ -150,11 +145,6 @@ export function isMinLengthTuple(
   }
 }
 
-const hasMinLength = (
-  len: SizeType.ArgArr,
-  array: readonly unknown[],
-): boolean => array.length >= len;
-
 /**
  * Checks if an array has at most a specific length.
  *
@@ -198,11 +188,6 @@ export function isMaxLengthTuple(
   }
 }
 
-const hasMaxLength = (
-  len: SizeType.ArgArr,
-  array: readonly unknown[],
-): boolean => array.length <= len;
-
 /**
  * Checks if an array's length is within a specific inclusive range.
  *
@@ -259,6 +244,21 @@ export function isBoundedLengthTuple(
   }
 }
 
+const hasFixedLength = (
+  len: SizeType.ArgArr,
+  array: readonly unknown[],
+): boolean => array.length === len;
+
+const hasMinLength = (
+  len: SizeType.ArgArr,
+  array: readonly unknown[],
+): boolean => array.length >= len;
+
+const hasMaxLength = (
+  len: SizeType.ArgArr,
+  array: readonly unknown[],
+): boolean => array.length <= len;
+
 const isWithinBounds = (
   min: SizeType.ArgArr,
   max: SizeType.ArgArr,

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

@@ -55,12 +55,6 @@ export function set<E, const V = E>(
   }
 }
 
-const setImpl = <E, const V = E>(
-  array: readonly E[],
-  index: SizeType.ArgArr,
-  newValue: V,
-): readonly (E | V)[] => (array as readonly (E | V)[]).with(index, newValue);
-
 /**
  * Returns a new array with an element at the specified index updated by applying a function.
  *
@@ -111,14 +105,6 @@ export function toUpdated<E, V = E>(
   }
 }
 
-const toUpdatedImpl = <E, V = E>(
-  array: readonly E[],
-  index: SizeType.ArgArr,
-  updater: (prev: E) => V,
-): readonly (E | V)[] =>
-  // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-  (array as readonly (E | V)[]).with(index, updater(array[index]!));
-
 /**
  * Returns a new array with a value inserted at the specified index.
  *
@@ -175,20 +161,6 @@ export function toInserted<E, const V = E>(
   }
 }
 
-const toInsertedImpl = <E, const V = E>(
-  array: readonly E[],
-  index: SizeType.ArgArrWithNegative,
-  newValue: V,
-): NonEmptyArray<E | V> =>
-  // eslint-disable-next-line total-functions/no-unsafe-type-assertion
-  (array as readonly (E | V)[]).toSpliced(
-    index,
-    0,
-    newValue,
-  ) as unknown as NonEmptyArray<E | V>;
-
-type CastToNumber<T> = T extends number ? T : never;
-
 /**
  * Returns a new array with the element at the specified index removed.
  *
@@ -229,11 +201,6 @@ export function toRemoved<E>(
   }
 }
 
-const toRemovedImpl = <E,>(
-  array: readonly E[],
-  index: SizeType.ArgArrWithNegative,
-): readonly E[] => array.toSpliced(index, 1);
-
 /**
  * Returns a new array with a value appended to the end.
  *
@@ -279,13 +246,6 @@ export function toPushed<const Ar extends readonly unknown[], const V>(
   }
 }
 
-const toPushedImpl = <const Ar extends readonly unknown[], const V>(
-  array: Ar,
-  newValue: V,
-): readonly [...Ar, V] =>
-  // eslint-disable-next-line total-functions/no-unsafe-type-assertion
-  array.toSpliced(array.length, 0, newValue) as unknown as readonly [...Ar, V];
-
 /**
  * Returns a new array with a value prepended to the beginning.
  *
@@ -331,13 +291,6 @@ export function toUnshifted<Ar extends readonly unknown[], const V>(
   }
 }
 
-const toUnshiftedImpl = <Ar extends readonly unknown[], const V>(
-  array: Ar,
-  newValue: V,
-): readonly [V, ...Ar] =>
-  // eslint-disable-next-line total-functions/no-unsafe-type-assertion
-  array.toSpliced(0, 0, newValue) as unknown as readonly [V, ...Ar];
-
 /**
  * Returns a new array with all elements replaced by the specified value.
  *
@@ -363,10 +316,10 @@ export function toFilled<
 // For an array or tuple that carries no length brand the homomorphic mapping
 // already covers every case the conditional spelled out — a fixed-length tuple
 // keeps its length, `readonly [A, ...A[]]` stays non-empty, and `readonly A[]`
-// stays unbounded. Stating it directly is what keeps this usable from a
-// caller that is itself generic over the array: a conditional a *generic* `Ar`
-// cannot decide stays deferred, and its branded branch is then not assignable
-// to the caller's own mapping.
+// stays unbounded. Stating it directly is what keeps this usable from a caller
+// that is itself generic over the array: a conditional a *generic* `Ar` cannot
+// decide stays deferred, and its branded branch is then not assignable to the
+// caller's own mapping.
 export function toFilled<const Ar extends readonly unknown[], const V>(
   array: Ar,
   value: V,
@@ -395,9 +348,6 @@ export function toFilled<E>(
   }
 }
 
-const toFilledImpl = <E,>(array: readonly E[], value: E): readonly E[] =>
-  create(asPositiveUint32(array.length), value);
-
 /**
  * Returns a new array with elements in the specified range replaced by the specified value.
  *
@@ -479,6 +429,56 @@ export function toRangeFilled<E, const V>(
   }
 }
 
+const setImpl = <E, const V = E>(
+  array: readonly E[],
+  index: SizeType.ArgArr,
+  newValue: V,
+): readonly (E | V)[] => (array as readonly (E | V)[]).with(index, newValue);
+
+const toUpdatedImpl = <E, V = E>(
+  array: readonly E[],
+  index: SizeType.ArgArr,
+  updater: (prev: E) => V,
+): readonly (E | V)[] =>
+  // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+  (array as readonly (E | V)[]).with(index, updater(array[index]!));
+
+const toInsertedImpl = <E, const V = E>(
+  array: readonly E[],
+  index: SizeType.ArgArrWithNegative,
+  newValue: V,
+): NonEmptyArray<E | V> =>
+  // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+  (array as readonly (E | V)[]).toSpliced(
+    index,
+    0,
+    newValue,
+  ) as unknown as NonEmptyArray<E | V>;
+
+type CastToNumber<T> = T extends number ? T : never;
+
+const toRemovedImpl = <E,>(
+  array: readonly E[],
+  index: SizeType.ArgArrWithNegative,
+): readonly E[] => array.toSpliced(index, 1);
+
+const toPushedImpl = <const Ar extends readonly unknown[], const V>(
+  array: Ar,
+  newValue: V,
+): readonly [...Ar, V] =>
+  // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+  array.toSpliced(array.length, 0, newValue) as unknown as readonly [...Ar, V];
+
+const toUnshiftedImpl = <Ar extends readonly unknown[], const V>(
+  array: Ar,
+  newValue: V,
+): readonly [V, ...Ar] =>
+  // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+  array.toSpliced(0, 0, newValue) as unknown as readonly [V, ...Ar];
+
+const toFilledImpl = <E,>(array: readonly E[], value: E): readonly E[] =>
+  create(asPositiveUint32(array.length), value);
+
 const toRangeFilledImpl = <E, const V>(
   array: readonly E[],
   value: V,

package/src/array/impl/array-utils-reducing-value.mts

@@ -247,16 +247,6 @@ export function count<E>(
   }
 }
 
-const countImpl = <E,>(
-  array: readonly E[],
-  predicate: (value: E, index: SizeType.Arr) => boolean,
-): SizeType.Arr =>
-  array.reduce<Uint32>(
-    (acc, curr, index) =>
-      predicate(curr, asUint32(index)) ? Uint32.add(acc, 1) : acc,
-    asUint32(0),
-  );
-
 /**
  * Groups elements by a key and counts the elements in each group.
  *
@@ -303,23 +293,6 @@ export function countBy<E, G extends MapSetKeyType>(
   }
 }
 
-const countByImpl = <E, G extends MapSetKeyType>(
-  array: readonly E[],
-  grouper: (value: E, index: SizeType.Arr) => G,
-): IMap<G, SizeType.Arr> => {
-  const mut_groups = new Map<G, SizeType.Arr>();
-
-  for (const [index, e] of array.entries()) {
-    const key = grouper(e, asUint32(index));
-
-    const curr = mut_groups.get(key) ?? 0;
-
-    mut_groups.set(key, asUint32(curr + 1));
-  }
-
-  return IMap.create(mut_groups);
-};
-
 /**
  * Reduces an array to a single value from left to right.
  *
@@ -388,20 +361,6 @@ export function foldl<E, P>(
   }
 }
 
-const foldlImpl = <E, P>(
-  array: readonly E[],
-  callbackfn: (
-    previousValue: P,
-    currentValue: E,
-    currentIndex: SizeType.Arr,
-  ) => P,
-  initialValue: P,
-): P =>
-  array.reduce(
-    (prev, curr, index) => callbackfn(prev, curr, asUint32(index)),
-    initialValue,
-  );
-
 /**
  * Reduces an array to a single value from right to left.
  *
@@ -470,20 +429,6 @@ export function foldr<E, P>(
   }
 }
 
-const foldrImpl = <E, P>(
-  array: readonly E[],
-  callbackfn: (
-    previousValue: P,
-    currentValue: E,
-    currentIndex: SizeType.Arr,
-  ) => P,
-  initialValue: P,
-): P =>
-  array.reduceRight(
-    (prev, curr, index) => callbackfn(prev, curr, asUint32(index)),
-    initialValue,
-  );
-
 /**
  * Calculates the sum of numbers in an array.
  *
@@ -618,6 +563,61 @@ export function join(
   }
 }
 
+const countImpl = <E,>(
+  array: readonly E[],
+  predicate: (value: E, index: SizeType.Arr) => boolean,
+): SizeType.Arr =>
+  array.reduce<Uint32>(
+    (acc, curr, index) =>
+      predicate(curr, asUint32(index)) ? Uint32.add(acc, 1) : acc,
+    asUint32(0),
+  );
+
+const countByImpl = <E, G extends MapSetKeyType>(
+  array: readonly E[],
+  grouper: (value: E, index: SizeType.Arr) => G,
+): IMap<G, SizeType.Arr> => {
+  const mut_groups = new Map<G, SizeType.Arr>();
+
+  for (const [index, e] of array.entries()) {
+    const key = grouper(e, asUint32(index));
+
+    const curr = mut_groups.get(key) ?? 0;
+
+    mut_groups.set(key, asUint32(curr + 1));
+  }
+
+  return IMap.create(mut_groups);
+};
+
+const foldlImpl = <E, P>(
+  array: readonly E[],
+  callbackfn: (
+    previousValue: P,
+    currentValue: E,
+    currentIndex: SizeType.Arr,
+  ) => P,
+  initialValue: P,
+): P =>
+  array.reduce(
+    (prev, curr, index) => callbackfn(prev, curr, asUint32(index)),
+    initialValue,
+  );
+
+const foldrImpl = <E, P>(
+  array: readonly E[],
+  callbackfn: (
+    previousValue: P,
+    currentValue: E,
+    currentIndex: SizeType.Arr,
+  ) => P,
+  initialValue: P,
+): P =>
+  array.reduceRight(
+    (prev, curr, index) => callbackfn(prev, curr, asUint32(index)),
+    initialValue,
+  );
+
 const joinImpl = (
   array: readonly unknown[],
   separator: string | undefined,