ts-data-forge 14.10.0 → 14.10.2

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

@@ -18,8 +18,8 @@ import {
  * exactly `length` elements.
  *
  * Use this instead of writing `xs as unknown as FixedLengthArray<N, E>`: the
- * length is verified at runtime, and the original array type (e.g. tuple
- * types) is preserved via intersection, so the result also benefits from the
+ * length is verified at runtime, and the original array type (e.g. tuple types)
+ * is preserved via intersection, so the result also benefits from the
  * structural tuple prefix (in-range indexed access without `undefined` under
  * `noUncheckedIndexedAccess`).
  *
@@ -83,28 +83,13 @@ export function asFixedLengthArray<E>(
   }
 }
 
-const asFixedLengthArrayImpl = <E,>(
-  length: SupportedLength,
-  xs: readonly E[],
-): readonly E[] => {
-  const actualLength = xs.length;
-
-  if (!isFixedLengthArray(length, xs)) {
-    throw new TypeError(
-      `Expected an array of length ${length}, got an array of length ${actualLength}`,
-    );
-  }
-
-  return xs;
-};
-
 /**
  * Casts an array to `MinLengthArray<MinLength, E>` after checking that it has
  * at least `minLength` elements.
  *
  * Use this instead of writing `xs as unknown as MinLengthArray<N, E>`: the
- * length is verified at runtime, and the original array type (e.g. tuple
- * types) is preserved via intersection, so the result also benefits from the
+ * length is verified at runtime, and the original array type (e.g. tuple types)
+ * is preserved via intersection, so the result also benefits from the
  * structural tuple prefix (indexed access below `min(N, 10)` without
  * `undefined` under `noUncheckedIndexedAccess`).
  *
@@ -168,28 +153,13 @@ export function asMinLengthArray<E>(
   }
 }
 
-const asMinLengthArrayImpl = <E,>(
-  minLength: SupportedLength,
-  xs: readonly E[],
-): readonly E[] => {
-  const actualLength = xs.length;
-
-  if (!isMinLengthArray(minLength, xs)) {
-    throw new TypeError(
-      `Expected an array of length >= ${minLength}, got an array of length ${actualLength}`,
-    );
-  }
-
-  return xs;
-};
-
 /**
  * Casts an array to `MaxLengthArray<MaxLength, E>` after checking that it has
  * at most `maxLength` elements.
  *
  * Use this instead of writing `xs as unknown as MaxLengthArray<N, E>`: the
- * length is verified at runtime, and the original array type (e.g. tuple
- * types) is preserved via intersection.
+ * length is verified at runtime, and the original array type (e.g. tuple types)
+ * is preserved via intersection.
  *
  * The length argument comes first, matching the type-parameter order of
  * `MaxLengthArray<MaxLength, Elm>`. Omitting the array returns a function that
@@ -247,29 +217,14 @@ export function asMaxLengthArray<E>(
   }
 }
 
-const asMaxLengthArrayImpl = <E,>(
-  maxLength: SupportedLength,
-  xs: readonly E[],
-): readonly E[] => {
-  const actualLength = xs.length;
-
-  if (!isMaxLengthArray(maxLength, xs)) {
-    throw new TypeError(
-      `Expected an array of length <= ${maxLength}, got an array of length ${actualLength}`,
-    );
-  }
-
-  return xs;
-};
-
 /**
  * Casts an array to `BoundedLengthArray<MinLength, MaxLength, E>` after
  * checking that its length is within the inclusive range
  * `[minLength, maxLength]`.
  *
  * Use this instead of writing
- * `xs as unknown as BoundedLengthArray<Min, Max, E>`: the length is verified
- * at runtime, and the original array type (e.g. tuple types) is preserved via
+ * `xs as unknown as BoundedLengthArray<Min, Max, E>`: the length is verified at
+ * runtime, and the original array type (e.g. tuple types) is preserved via
  * intersection.
  *
  * The length arguments come first, matching the type-parameter order of
@@ -344,22 +299,6 @@ export function asBoundedLengthArray<E>(
   }
 }
 
-const asBoundedLengthArrayImpl = <E,>(
-  minLength: SupportedLength,
-  maxLength: SupportedLength,
-  xs: readonly E[],
-): readonly E[] => {
-  const actualLength = xs.length;
-
-  if (!isBoundedLengthArray(minLength, maxLength, xs)) {
-    throw new TypeError(
-      `Expected an array of length in [${minLength}, ${maxLength}], got an array of length ${actualLength}`,
-    );
-  }
-
-  return xs;
-};
-
 /**
  * Casts an array to `FixedLengthArray<0, E>` after checking that it is empty.
  *
@@ -434,3 +373,64 @@ export const asNonEmptyArray = <Xs extends readonly unknown[]>(
 
   return xs;
 };
+
+const asFixedLengthArrayImpl = <E,>(
+  length: SupportedLength,
+  xs: readonly E[],
+): readonly E[] => {
+  const actualLength = xs.length;
+
+  if (!isFixedLengthArray(length, xs)) {
+    throw new TypeError(
+      `Expected an array of length ${length}, got an array of length ${actualLength}`,
+    );
+  }
+
+  return xs;
+};
+
+const asMinLengthArrayImpl = <E,>(
+  minLength: SupportedLength,
+  xs: readonly E[],
+): readonly E[] => {
+  const actualLength = xs.length;
+
+  if (!isMinLengthArray(minLength, xs)) {
+    throw new TypeError(
+      `Expected an array of length >= ${minLength}, got an array of length ${actualLength}`,
+    );
+  }
+
+  return xs;
+};
+
+const asMaxLengthArrayImpl = <E,>(
+  maxLength: SupportedLength,
+  xs: readonly E[],
+): readonly E[] => {
+  const actualLength = xs.length;
+
+  if (!isMaxLengthArray(maxLength, xs)) {
+    throw new TypeError(
+      `Expected an array of length <= ${maxLength}, got an array of length ${actualLength}`,
+    );
+  }
+
+  return xs;
+};
+
+const asBoundedLengthArrayImpl = <E,>(
+  minLength: SupportedLength,
+  maxLength: SupportedLength,
+  xs: readonly E[],
+): readonly E[] => {
+  const actualLength = xs.length;
+
+  if (!isBoundedLengthArray(minLength, maxLength, xs)) {
+    throw new TypeError(
+      `Expected an array of length in [${minLength}, ${maxLength}], got an array of length ${actualLength}`,
+    );
+  }
+
+  return xs;
+};

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

@@ -85,11 +85,6 @@ export function isMinLengthArray(
   }
 }
 
-const hasMinLength = (
-  minLength: SupportedLength,
-  xs: readonly unknown[],
-): boolean => xs.length >= minLength;
-
 /**
  * Type guard that checks if an array has at most `maxLength` elements.
  *
@@ -169,11 +164,6 @@ export function isMaxLengthArray(
   }
 }
 
-const hasMaxLength = (
-  maxLength: SupportedLength,
-  xs: readonly unknown[],
-): boolean => xs.length <= maxLength;
-
 /**
  * Type guard that checks if an array's length is within the inclusive range
  * `[minLength, maxLength]`.
@@ -267,12 +257,6 @@ export function isBoundedLengthArray(
   }
 }
 
-const hasBoundedLength = (
-  minLength: SupportedLength,
-  maxLength: SupportedLength,
-  xs: readonly unknown[],
-): boolean => minLength <= xs.length && xs.length <= maxLength;
-
 /**
  * Type guard that checks if an array has exactly `length` elements.
  *
@@ -350,11 +334,6 @@ export function isFixedLengthArray(
   }
 }
 
-const hasFixedLength = (
-  length: SupportedLength,
-  xs: readonly unknown[],
-): boolean => xs.length === length;
-
 /**
  * Type guard that checks if an array is empty.
  *
@@ -402,3 +381,24 @@ export const isEmpty = <Xs extends readonly unknown[]>(
 export const isNonEmpty = <Xs extends readonly unknown[]>(
   array: Xs,
 ): array is MinLengthArray<1, Xs[number]> & Xs => array.length > 0;
+
+const hasMinLength = (
+  minLength: SupportedLength,
+  xs: readonly unknown[],
+): boolean => xs.length >= minLength;
+
+const hasMaxLength = (
+  maxLength: SupportedLength,
+  xs: readonly unknown[],
+): boolean => xs.length <= maxLength;
+
+const hasBoundedLength = (
+  minLength: SupportedLength,
+  maxLength: SupportedLength,
+  xs: readonly unknown[],
+): boolean => minLength <= xs.length && xs.length <= maxLength;
+
+const hasFixedLength = (
+  length: SupportedLength,
+  xs: readonly unknown[],
+): boolean => xs.length === length;

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

@@ -166,8 +166,8 @@ describe(isFixedLengthArray, () => {
 
     expectType<typeof value, FixedLengthArray<4, number>>('!<=');
 
-    // `length` is narrowed to the literal and in-range indexed access does
-    // not include `undefined` (even under `noUncheckedIndexedAccess`)
+    // `length` is narrowed to the literal and in-range indexed access does not
+    // include `undefined` (even under `noUncheckedIndexedAccess`)
     const _len = value.length;
 
     expectType<typeof _len, 3>('=');

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,