ts-data-forge 14.9.0 → 14.10.1

package/dist/others/replace-equal-deep.d.mts

@@ -0,0 +1,95 @@
+/**
+ * Returns `next` with every part deeply equal to the same part of `current`
+ * replaced by that part of `current` (structural sharing). When the whole of
+ * `next` is deeply equal to `current`, `current` itself is returned, so an
+ * `Object.is` comparison of the result with `current` tells whether anything
+ * changed, and a reader that compares by reference sees a new object only where
+ * the value really changed.
+ *
+ * Only plain objects and arrays are walked into. Anything else — a `Map`, a
+ * `Set`, a `Date`, a class instance — is compared whole with
+ * {@link fastDeepEqual} and kept or replaced whole.
+ *
+ * Array items are matched by index. Give `key` to match them by key instead:
+ * an item for which it returns something other than `undefined` is matched with
+ * the item of `current` it returns the same key for, and an item it returns
+ * `undefined` for is still matched by index. The one `key` is used for the
+ * arrays at every depth.
+ *
+ * Neither argument is changed. The result shares objects with both, so it
+ * relies on neither being changed afterwards.
+ *
+ * Call it where the new value is written over the one held, so that nothing
+ * downstream has a new object it must compare again.
+ *
+ * @param current - The value held now
+ * @param next - The value to write over it
+ * @param options - {@link ReplaceEqualDeepOptions}
+ * @returns `current` when `next` is deeply equal to it; otherwise a value
+ *   deeply equal to `next` that reuses the equal parts of `current`
+ *
+ * @example
+ * ```ts
+ * type PullReport = DeepReadonly<{
+ *   summary: { open: number };
+ *   pulls: { number: number; title: string }[];
+ * }>;
+ *
+ * const held: PullReport = {
+ *   summary: { open: 2 },
+ *   pulls: [
+ *     { number: 1, title: 'one' },
+ *     { number: 2, title: 'two' },
+ *   ],
+ * } as const;
+ *
+ * // A server answers with the whole report every time.
+ * const answer: PullReport = {
+ *   summary: { open: 2 },
+ *   pulls: [
+ *     { number: 1, title: 'one' },
+ *     { number: 2, title: 'two (edited)' },
+ *   ],
+ * } as const;
+ *
+ * const written = replaceEqualDeep(held, answer);
+ *
+ * assert.deepStrictEqual(written, answer);
+ *
+ * // What did not change is the object already held,
+ * assert.strictEqual(written.summary, held.summary);
+ *
+ * assert.strictEqual(written.pulls[0], held.pulls[0]);
+ *
+ * // and what changed is new.
+ * assert.notStrictEqual(written.pulls[1], held.pulls[1]);
+ *
+ * // An answer that changes nothing gives back the value held.
+ * assert.strictEqual(replaceEqualDeep(held, structuredClone(held)), held);
+ *
+ * // Match array items by key rather than by index.
+ * const opened = replaceEqualDeep(
+ *   held.pulls,
+ *   [{ number: 0, title: 'zero' }, ...structuredClone(held.pulls)],
+ *   {
+ *     key: (item) =>
+ *       isRecord(item) && hasKey(item, 'number') ? item.number : undefined,
+ *   },
+ * );
+ *
+ * assert.strictEqual(opened[1], held.pulls[0]);
+ *
+ * assert.strictEqual(opened[2], held.pulls[1]);
+ * ```
+ */
+export declare const replaceEqualDeep: <T>(current: T, next: T, options?: ReplaceEqualDeepOptions) => T;
+/** Options of {@link replaceEqualDeep}. */
+export type ReplaceEqualDeepOptions = Readonly<{
+    /**
+     * The key an array item is matched by. Items it returns `undefined` for are
+     * matched by index. Keys are compared with `SameValueZero`, as `Map` compares
+     * them.
+     */
+    key?: (item: unknown) => unknown;
+}>;
+//# sourceMappingURL=replace-equal-deep.d.mts.map

package/dist/others/replace-equal-deep.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replace-equal-deep.d.mts","sourceRoot":"","sources":["../../src/others/replace-equal-deep.mts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmFG;AACH,eAAO,MAAM,gBAAgB,GAAI,CAAC,WACvB,CAAC,QACJ,CAAC,YACG,uBAAuB,KAChC,CAIwC,CAAC;AAE5C,2CAA2C;AAC3C,MAAM,MAAM,uBAAuB,GAAG,QAAQ,CAAC;IAC7C;;;;OAIG;IACH,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC;CAClC,CAAC,CAAC"}

package/dist/others/replace-equal-deep.mjs

@@ -0,0 +1,156 @@
+import { hasKey, isRecord } from '../guard/index.mjs';
+import { fastDeepEqual } from './fast-deep-equal.mjs';
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+export const replaceEqualDeep = (current, next, options) => 
+
+
+
+replace(current, next, options?.key);
+const isPlainArray = (value) => Array.isArray(value) && Object.getPrototypeOf(value) === Array.prototype;
+const isPlainObject = (value) => isRecord(value) && Object.getPrototypeOf(value) === Object.prototype;
+const replace = (current, next, key) => Object.is(current, next)
+    ? current
+    : isPlainArray(current) && isPlainArray(next)
+        ? replaceArray(current, next, key)
+        : isPlainObject(current) && isPlainObject(next)
+            ? replaceObject(current, next, key)
+            : fastDeepEqual(current, next)
+                ? current
+                : next;
+const indexByKey = (items, key) => {
+    const mut_byKey = new Map();
+    for (const item of items) {
+        const itemKey = key(item);
+        if (itemKey !== undefined && !mut_byKey.has(itemKey)) {
+            mut_byKey.set(itemKey, item);
+        }
+    }
+    return mut_byKey;
+};
+
+
+
+const replaceArray = (current, next, key) => {
+    const byKey = key === undefined ? undefined : indexByKey(current, key);
+    let mut_isCurrent = current.length === next.length;
+    let mut_isNext = true;
+    const mut_shared = [];
+    for (let mut_index = 0; mut_index < next.length; mut_index += 1) {
+        const index = mut_index;
+        const item = next[index];
+        const itemKey = key?.(item);
+        const before = itemKey === undefined || byKey === undefined
+            ? index < current.length
+                ? current[index]
+                : absent
+            : byKey.has(itemKey)
+                ? byKey.get(itemKey)
+                : absent;
+        const result = before === absent ? item : replace(before, item, key);
+        mut_isCurrent &&= Object.is(result, current[index]);
+        mut_isNext &&= Object.is(result, item);
+        mut_shared.push(result);
+    }
+    return mut_isCurrent ? current : mut_isNext ? next : mut_shared;
+};
+const replaceObject = (current, next, key) => {
+    const nextKeys = Object.keys(next);
+    let mut_isCurrent = Object.keys(current).length === nextKeys.length;
+    let mut_isNext = true;
+    const mut_shared = {};
+    for (const k of nextKeys) {
+        const value = next[k];
+        const has = hasKey(current, k);
+        const result = has ? replace(current[k], value, key) : value;
+        mut_isCurrent &&= has && Object.is(result, current[k]);
+        mut_isNext &&= Object.is(result, value);
+        mut_shared[k] = result;
+    }
+    return mut_isCurrent ? current : mut_isNext ? next : mut_shared;
+};
+
+const absent = Symbol('absent');
+//# sourceMappingURL=replace-equal-deep.mjs.map

package/dist/others/replace-equal-deep.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"replace-equal-deep.mjs","sourceRoot":"","sources":["../../src/others/replace-equal-deep.mts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAEtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmFG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAC9B,OAAU,EACV,IAAO,EACP,OAAiC,EAC9B,EAAE;AACL,8EAA8E;AAC9E,kEAAkE;AAClE,oEAAoE;AACpE,OAAO,CAAC,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,CAAM,CAAC;AAc5C,MAAM,YAAY,GAAG,CAAC,KAAc,EAA+B,EAAE,CACnE,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC,cAAc,CAAC,KAAK,CAAC,KAAK,KAAK,CAAC,SAAS,CAAC;AAE3E,MAAM,aAAa,GAAG,CAAC,KAAc,EAA0B,EAAE,CAC/D,QAAQ,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC,cAAc,CAAC,KAAK,CAAC,KAAK,MAAM,CAAC,SAAS,CAAC;AAEvE,MAAM,OAAO,GAAG,CACd,OAAgB,EAChB,IAAa,EACb,GAAoB,EACX,EAAE,CACX,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,IAAI,CAAC;IACtB,CAAC,CAAC,OAAO;IACT,CAAC,CAAC,YAAY,CAAC,OAAO,CAAC,IAAI,YAAY,CAAC,IAAI,CAAC;QAC3C,CAAC,CAAC,YAAY,CAAC,OAAO,EAAE,IAAI,EAAE,GAAG,CAAC;QAClC,CAAC,CAAC,aAAa,CAAC,OAAO,CAAC,IAAI,aAAa,CAAC,IAAI,CAAC;YAC7C,CAAC,CAAC,aAAa,CAAC,OAAO,EAAE,IAAI,EAAE,GAAG,CAAC;YACnC,CAAC,CAAC,aAAa,CAAC,OAAO,EAAE,IAAI,CAAC;gBAC5B,CAAC,CAAC,OAAO;gBACT,CAAC,CAAC,IAAI,CAAC;AAEjB,MAAM,UAAU,GAAG,CACjB,KAAyB,EACzB,GAAQ,EACuB,EAAE;IACjC,MAAM,SAAS,GAAG,IAAI,GAAG,EAAoB,CAAC;IAE9C,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,CAAC,CAAC;QAE1B,IAAI,OAAO,KAAK,SAAS,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;YACrD,SAAS,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QAC/B,CAAC;IACH,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC,CAAC;AAEF,gFAAgF;AAChF,4EAA4E;AAC5E,yDAAyD;AAEzD,MAAM,YAAY,GAAG,CACnB,OAA2B,EAC3B,IAAwB,EACxB,GAAoB,EACA,EAAE;IACtB,MAAM,KAAK,GAAG,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;IAEvE,IAAI,aAAa,GAAG,OAAO,CAAC,MAAM,KAAK,IAAI,CAAC,MAAM,CAAC;IAEnD,IAAI,UAAU,GAAG,IAAI,CAAC;IAEtB,MAAM,UAAU,GAAc,EAAE,CAAC;IAEjC,KAAK,IAAI,SAAS,GAAG,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC,MAAM,EAAE,SAAS,IAAI,CAAC,EAAE,CAAC;QAChE,MAAM,KAAK,GAAG,SAAS,CAAC;QAExB,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;QAEzB,MAAM,OAAO,GAAG,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;QAE5B,MAAM,MAAM,GACV,OAAO,KAAK,SAAS,IAAI,KAAK,KAAK,SAAS;YAC1C,CAAC,CAAC,KAAK,GAAG,OAAO,CAAC,MAAM;gBACtB,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC;gBAChB,CAAC,CAAC,MAAM;YACV,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC;gBAClB,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC;gBACpB,CAAC,CAAC,MAAM,CAAC;QAEf,MAAM,MAAM,GAAG,MAAM,KAAK,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC;QAErE,aAAa,KAAK,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;QAEpD,UAAU,KAAK,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QAEvC,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC1B,CAAC;IAED,OAAO,aAAa,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC;AAClE,CAAC,CAAC;AAEF,MAAM,aAAa,GAAG,CACpB,OAAsB,EACtB,IAAmB,EACnB,GAAoB,EACL,EAAE;IACjB,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAEnC,IAAI,aAAa,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,MAAM,KAAK,QAAQ,CAAC,MAAM,CAAC;IAEpE,IAAI,UAAU,GAAG,IAAI,CAAC;IAEtB,MAAM,UAAU,GAAmC,EAAE,CAAC;IAEtD,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;QACzB,MAAM,KAAK,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QAEtB,MAAM,GAAG,GAAG,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;QAE/B,MAAM,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;QAE7D,aAAa,KAAK,GAAG,IAAI,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;QAEvD,UAAU,KAAK,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;QAExC,UAAU,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC;IACzB,CAAC;IAED,OAAO,aAAa,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC;AAClE,CAAC,CAAC;AAEF,uEAAuE;AACvE,MAAM,MAAM,GAAkB,MAAM,CAAC,QAAQ,CAAC,CAAC"}

package/dist/string/str.d.mts

@@ -321,8 +321,8 @@ export declare namespace Str {
      * `NonEmptyString` is an alias of `MinLengthString<1>`, so this is the
      * length-1 specialization of {@link asMinLengthString}. Use this instead of
      * writing `s as unknown as NonEmptyString`: the length is verified at
-     * runtime, and the original string type (e.g. literal types) is preserved
-     * via intersection.
+     * runtime, and the original string type (e.g. literal types) is preserved via
+     * intersection.
      *
      * @example
      *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-data-forge",
-  "version": "14.9.0",
+  "version": "14.10.1",
   "private": false,
   "keywords": [
     "typescript",
@@ -43,28 +43,28 @@
   "devDependencies": {
     "@emotion/react": "11.14.0",
     "@emotion/styled": "11.14.1",
-    "@mui/material": "9.4.0",
+    "@mui/material": "9.5.0",
     "@types/react": "19.3.0",
-    "@vitest/browser-playwright": "5.0.3",
-    "eslint-config-typed": "5.19.0",
-    "eslint-plugin-ts-fortress": "1.3.5",
-    "eslint-plugin-ts-type-forge": "0.8.10",
-    "immer": "11.1.21",
-    "playwright": "1.64.0",
-    "prettier": "3.9.9",
+    "@vitest/browser-playwright": "5.0.5",
+    "eslint-config-typed": "7.3.0",
+    "eslint-plugin-ts-fortress": "1.3.12",
+    "eslint-plugin-ts-type-forge": "0.8.17",
+    "immer": "11.2.7",
+    "playwright": "1.64.1",
+    "prettier": "3.9.10",
     "prettier-plugin-organize-imports": "4.3.0",
     "prettier-plugin-packagejson": "3.0.2",
-    "react": "19.3.0",
+    "react": "19.3.1",
     "ts-repo-utils": "10.7.1",
     "typedoc": "0.28.20",
     "typedoc-github-theme": "0.4.0",
-    "vite": "8.3.3"
+    "vite": "8.3.5"
   },
   "peerDependencies": {
     "typescript": ">=4.8"
   },
   "engines": {
-    "node": ">=22.22.2",
+    "node": ">=22.23.4",
     "pnpm": ">=9.0.0"
   },
   "publishConfig": {

package/src/array/impl/array-utils-element-access.mts

@@ -53,17 +53,6 @@ export function at<E>(
   }
 }
 
-const atImpl = <E,>(
-  array: readonly E[],
-  index: SizeType.ArgArrWithNegative,
-): Optional<E> =>
-  pipe(index < 0 ? array.length + index : index).map((normalizedIndex) =>
-    normalizedIndex < 0 || array.length <= normalizedIndex
-      ? Optional.none
-      : // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-        Optional.some(array[normalizedIndex]!),
-  ).value;
-
 /**
  * Returns the first element of an array as an Optional.
  *
@@ -126,6 +115,17 @@ export const last = <const Ar extends readonly unknown[]>(
   // eslint-disable-next-line total-functions/no-unsafe-type-assertion
   (array.length === 0 ? Optional.none : Optional.some(array.at(-1))) as never;
 
+const atImpl = <E,>(
+  array: readonly E[],
+  index: SizeType.ArgArrWithNegative,
+): Optional<E> =>
+  pipe(index < 0 ? array.length + index : index).map((normalizedIndex) =>
+    normalizedIndex < 0 || array.length <= normalizedIndex
+      ? Optional.none
+      : // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        Optional.some(array[normalizedIndex]!),
+  ).value;
+
 /**
  * Alias for `head`.
  *

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>('=');