@nestia/e2e 14.0.1 → 14.0.2

package/lib/internal/json_equal_to.d.ts

@@ -1 +1,22 @@
+/**
+ * Compares two values through their JSON form and returns the accessors that
+ * differ.
+ *
+ * The comparison walks the keys of the first value, skipping keys whose value
+ * is `undefined` and keys the exception predicate accepts, so a key only the
+ * second value has is not a difference. Values with a `toJSON` are compared by
+ * it, functions are ignored, `null` differs from every object, and arrays must
+ * have the same length. An empty result means no difference.
+ *
+ * Processing cost: The walker traverses the first value and matching
+ * second-value positions, recording differing accessors. Object keys and
+ * recursion require space proportional to visited structure and depth; toJSON
+ * and exception callback costs belong to their implementations. Cyclic inputs
+ * are unsupported.
+ *
+ * @evidence contracts/common.md#principled-implementation Each pair is first read through `toJSON`, then separated by type, by `null`, by array against non-array, and by key walking, so the differences are the accessors where the JSON values differ over the keys of the first value; reading through `toJSON` compares a `Date` by its instant instead of treating every two dates as equal.
+ * @evidence contracts/common.md#clear-and-simple-design One curried function with three inner walkers (value, array, object) that append to one accessor list.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The exception predicate is the caller's, and no key or type name is special-cased.
+ * @evidence contracts/common.md#meaningful-documentation The comment states the comparison rules and what the result means.
+ */
 export declare const json_equal_to: (exception: (key: string) => boolean) => <T>(x: T) => (y: T | null | undefined) => string[];

package/lib/internal/json_equal_to.js

@@ -1,6 +1,27 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.json_equal_to = void 0;
+/**
+ * Compares two values through their JSON form and returns the accessors that
+ * differ.
+ *
+ * The comparison walks the keys of the first value, skipping keys whose value
+ * is `undefined` and keys the exception predicate accepts, so a key only the
+ * second value has is not a difference. Values with a `toJSON` are compared by
+ * it, functions are ignored, `null` differs from every object, and arrays must
+ * have the same length. An empty result means no difference.
+ *
+ * Processing cost: The walker traverses the first value and matching
+ * second-value positions, recording differing accessors. Object keys and
+ * recursion require space proportional to visited structure and depth; toJSON
+ * and exception callback costs belong to their implementations. Cyclic inputs
+ * are unsupported.
+ *
+ * @evidence contracts/common.md#principled-implementation Each pair is first read through `toJSON`, then separated by type, by `null`, by array against non-array, and by key walking, so the differences are the accessors where the JSON values differ over the keys of the first value; reading through `toJSON` compares a `Date` by its instant instead of treating every two dates as equal.
+ * @evidence contracts/common.md#clear-and-simple-design One curried function with three inner walkers (value, array, object) that append to one accessor list.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The exception predicate is the caller's, and no key or type name is special-cased.
+ * @evidence contracts/common.md#meaningful-documentation The comment states the comparison rules and what the result means.
+ */
 const json_equal_to = (exception) => (x) => (y) => {
     const container = [];
     const iterate = (accessor) => (x) => (y) => {
@@ -21,12 +42,11 @@ const json_equal_to = (exception) => (x) => (y) => {
             if (x !== y)
                 container.push(accessor);
         }
-        else if (x instanceof Array)
-            if (!(y instanceof Array))
-                container.push(accessor);
-            else
-                array(accessor)(x)(y);
-        else if (x instanceof Object)
+        else if (Array.isArray(x) !== Array.isArray(y))
+            container.push(accessor);
+        else if (Array.isArray(x))
+            array(accessor)(x)(y);
+        else if (typeof x === "object")
             object(accessor)(x)(y);
         else if (x !== y)
             container.push(accessor);

package/lib/internal/json_equal_to.js.map

@@ -1 +1 @@
-{"version":3,"file":"json_equal_to.js","sourceRoot":"","sources":["../../src/internal/json_equal_to.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"json_equal_to.js","sourceRoot":"","sources":["../../src/internal/json_equal_to.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nestia/e2e",
-  "version": "14.0.1",
+  "version": "14.0.2",
   "description": "E2E test utilify functions",
   "main": "lib/index.js",
   "exports": {
@@ -44,7 +44,8 @@
   },
   "scripts": {
     "build": "rimraf lib && ttsc",
-    "dev": "rimraf lib && ttsc --watch"
+    "dev": "rimraf lib && ttsc --watch",
+    "evidence": "evidence"
   },
   "types": "lib/index.d.ts"
 }

package/src/ArrayUtil.ts

@@ -6,16 +6,30 @@
  * in functional programming style. Functions use direct parameter passing for
  * simplicity while maintaining functional programming principles.
  *
+ * Processing cost: Sequential array operations visit each required position
+ * once; has short-circuits, and subsets materializes the exponential power-set
+ * output. Async helpers await one user callback per position and preserve its
+ * ordering rather than assuming callbacks are independent.
+ *
+ * Resource ownership: Async helpers await one callback at a time and keep their
+ * input and partial output until settlement; results transfer to the caller.
+ * Synchronous helpers retain only their local arrays and recursion state.
+ * Callback resources and cancellation belong to the caller.
+ *
  * @author Jeongho Nam - https://github.com/samchon
  * @example
- *   ```typescript
  *   // Asynchronous filtering example
  *   const numbers = [1, 2, 3, 4, 5];
- *   const evenNumbers = await ArrayUtil.asyncFilter(numbers,
- *     async (num) => num % 2 === 0
+ *   const evenNumbers = await ArrayUtil.asyncFilter(
+ *     numbers,
+ *     async (num) => num % 2 === 0,
  *   );
  *   console.log(evenNumbers); // [2, 4]
- *   ```;
+ *
+ * @evidence contracts/common.md#principled-implementation Asynchronous filtering and mapping share sequential `asyncForEach`; repetition awaits each index and collects its results. Synchronous helpers use loops and native methods, and `subsets` enumerates the include or exclude choice per position.
+ * @evidence contracts/common.md#clear-and-simple-design Filtering and mapping share iteration without allocating unused results; repetition separately collects its results, with one private count validator.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No function special-cases a value, a fixture, or a caller; ordering and short-circuiting follow from the loop and the native `some`.
+ * @evidence contracts/common.md#meaningful-documentation The namespace prose states the sequential, functional style, and each function documents its parameters, its result, and an example.
  */
 export namespace ArrayUtil {
   /**
@@ -26,28 +40,39 @@ export namespace ArrayUtil {
    * predicate function receives the element, index, and the full array as
    * parameters.
    *
+   * Processing cost: Each of N elements invokes its predicate once in sequence;
+   * array bookkeeping is O(N), with O(M) output for M accepted elements.
+   *
+   * Resource ownership: The invocation awaits one callback at a time and
+   * retains only its partial output and current call; success transfers the
+   * output to the caller and rejection releases local state. Callback-owned
+   * external resources remain the callback owner’s responsibility.
+   *
    * @example
-   *   ```typescript
    *   const users = [
-   *     { id: 1, name: 'Alice', active: true },
-   *     { id: 2, name: 'Bob', active: false },
-   *     { id: 3, name: 'Charlie', active: true }
+   *     { id: 1, name: "Alice", active: true },
+   *     { id: 2, name: "Bob", active: false },
+   *     { id: 3, name: "Charlie", active: true },
    *   ];
    *
-   *   const activeUsers = await ArrayUtil.asyncFilter(users,
+   *   const activeUsers = await ArrayUtil.asyncFilter(
+   *     users,
    *     async (user) => {
    *       // Async validation logic (e.g., API call)
-   *       await new Promise(resolve => setTimeout(resolve, 100));
+   *       await new Promise((resolve) => setTimeout(resolve, 100));
    *       return user.active;
-   *     }
+   *     },
    *   );
    *   console.log(activeUsers); // [{ id: 1, name: 'Alice', active: true }, { id: 3, name: 'Charlie', active: true }]
-   *   ```;
    *
    * @template Input - The type of elements in the input array
    * @param elements - The readonly array to filter
    * @param pred - The asynchronous predicate function to test each element
    * @returns A Promise resolving to the filtered array
+   * @evidence contracts/common.md#principled-implementation The predicate runs on each element in order and the next call starts after the previous promise settles; an element is kept only when the awaited result is exactly `true`, which the `Promise<boolean>` type guarantees for well-typed callers, and a rejection stops the iteration and rejects the result.
+   * @evidence contracts/common.md#clear-and-simple-design It composes `asyncForEach` with one push instead of reimplementing the loop.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The predicate alone decides inclusion; no element is skipped or retried.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the sequential order, the predicate arguments, and the result, with an example.
    */
   export const asyncFilter = async <Input>(
     elements: readonly Input[],
@@ -74,23 +99,33 @@ export namespace ArrayUtil {
    * performs sequential processing rather than parallel processing, making it
    * suitable for operations where order matters.
    *
+   * Processing cost: Each of N elements invokes its callback once in sequence:
+   * O(N) bookkeeping with no result array.
+   *
+   * Resource ownership: The invocation retains its input while awaiting one
+   * callback at a time, discards callback results and releases local state on
+   * completion or rejection. Callback-owned external resources remain the
+   * callback owner’s responsibility.
+   *
    * @example
-   *   ```typescript
-   *   const urls = ['url1', 'url2', 'url3'];
+   *   const urls = ["url1", "url2", "url3"];
    *
    *   await ArrayUtil.asyncForEach(urls, async (url, index) => {
-   *   console.log(`Processing ${index}: ${url}`);
-   *   const data = await fetch(url);
-   *   await processData(data);
-   *   console.log(`Completed ${index}: ${url}`);
+   *     console.log(`Processing ${index}: ${url}`);
+   *     const data = await fetch(url);
+   *     await processData(data);
+   *     console.log(`Completed ${index}: ${url}`);
    *   });
-   *   console.log('All URLs processed sequentially');
-   *   ```
+   *   console.log("All URLs processed sequentially");
    *
    * @template Input - The type of elements in the input array
    * @param elements - The readonly array to process
    * @param closure - The asynchronous function to execute for each element
    * @returns A Promise<void> that resolves when all operations complete
+   * @evidence contracts/common.md#principled-implementation The initial array length determines the visited indices, and each callback receives the current element, index and original array. Each call is awaited before advancing, so rejection ends iteration and propagates.
+   * @evidence contracts/common.md#clear-and-simple-design One sequential loop discards callback results without collecting an unused array.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The closure receives every element exactly once and no error is swallowed.
+   * @evidence contracts/common.md#meaningful-documentation The comment contrasts it with the native forEach, states the sequential semantics, and gives an example.
    */
   export const asyncForEach = async <Input>(
     elements: readonly Input[],
@@ -100,9 +135,9 @@ export namespace ArrayUtil {
       array: readonly Input[],
     ) => Promise<any>,
   ): Promise<void> => {
-    await asyncRepeat(elements.length, (index) =>
-      closure(elements[index]!, index, elements),
-    );
+    const length: number = elements.length;
+    for (let index: number = 0; index < length; ++index)
+      await closure(elements[index]!, index, elements);
   };
 
   /**
@@ -111,27 +146,40 @@ export namespace ArrayUtil {
    *
    * Similar to JavaScript's native map but processes asynchronous functions
    * sequentially. Each element's transformation is completed before proceeding
-   * to the next element, ensuring order is maintained. This function still
-   * maintains the currying pattern for composition.
+   * to the next element, ensuring order is maintained.
+   *
+   * Processing cost: Each of N elements invokes its mapper once in sequence and
+   * stores one result: O(N) bookkeeping and output space.
+   *
+   * Resource ownership: The invocation awaits one callback at a time and
+   * retains only its partial output and current call; success transfers the
+   * output to the caller and rejection releases local state. Callback-owned
+   * external resources remain the callback owner’s responsibility.
    *
    * @example
-   *   ```typescript
    *   const userIds = [1, 2, 3, 4, 5];
    *
-   *   const userDetails = await ArrayUtil.asyncMap(userIds)(
-   *   async (id, index) => {
-   *   console.log(`Fetching user ${id} (${index + 1}/${userIds.length})`);
-   *   const response = await fetch(`/api/users/${id}`);
-   *   return await response.json();
-   *   }
+   *   const userDetails = await ArrayUtil.asyncMap(
+   *     userIds,
+   *     async (id, index) => {
+   *       console.log(
+   *         `Fetching user ${id} (${index + 1}/${userIds.length})`,
+   *       );
+   *       const response = await fetch(`/api/users/${id}`);
+   *       return await response.json();
+   *     },
    *   );
-   *   console.log('All users fetched:', userDetails);
-   *   ```
+   *   console.log("All users fetched:", userDetails);
    *
    * @template Input - The type of elements in the input array
+   * @template Output - The type of elements in the resulting array
    * @param elements - The readonly array to transform
-   * @returns A function that takes a transformation function and returns a
-   *   Promise resolving to the transformed array
+   * @param closure - The asynchronous function that transforms each element
+   * @returns A Promise resolving to the transformed array
+   * @evidence contracts/common.md#principled-implementation The closure result of each element is pushed in iteration order, so the output order equals the input order, which holds because the calls are sequential.
+   * @evidence contracts/common.md#clear-and-simple-design It composes `asyncForEach` with one push.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Every element is transformed by the caller's closure, with no memoization or skipping.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the sequential order and the parameters, and the example calls the two-argument form the function has.
    */
   export const asyncMap = async <Input, Output>(
     elements: readonly Input[],
@@ -156,32 +204,43 @@ export namespace ArrayUtil {
    * execution is performed sequentially, and all results are collected into an
    * array.
    *
+   * Processing cost: The callback runs once for each of N indices, in sequence,
+   * with O(N) result storage.
+   *
+   * Resource ownership: The invocation awaits one callback at a time and
+   * retains only its partial output and current call; success transfers the
+   * output to the caller and rejection releases local state. Callback-owned
+   * external resources remain the callback owner’s responsibility.
+   *
    * @example
-   *   ```typescript
    *   // Generate random data 5 times
    *   const randomData = await ArrayUtil.asyncRepeat(5, async (index) => {
-   *     await new Promise(resolve => setTimeout(resolve, 100)); // Wait 0.1 seconds
+   *     await new Promise((resolve) => setTimeout(resolve, 100)); // Wait 0.1 seconds
    *     return {
    *       id: index,
    *       value: Math.random(),
-   *       timestamp: new Date().toISOString()
+   *       timestamp: new Date().toISOString(),
    *     };
    *   });
-   *   console.log('Generated data:', randomData);
-   *   ```;
+   *   console.log("Generated data:", randomData);
    *
    * @template T - The type of the result from each execution
-   * @param count - The number of times to repeat (non-negative integer)
+   * @param count - The number of times to repeat (integer from 0 to 2^32 - 1)
    * @param closure - The asynchronous function to execute repeatedly
    * @returns A Promise resolving to an array of results
+   * @evidence contracts/common.md#principled-implementation A count outside the integer range 0 through 2^32 - 1 is refused with a `RangeError` before any callback, because JavaScript arrays cannot represent a larger length; otherwise the closure is awaited for each index from 0 to count minus one and the results are collected in order, so the cost is linear in the count with no index array.
+   * @evidence contracts/common.md#clear-and-simple-design One validation and one loop; the validator is shared with `repeat`.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The loop is the direct implementation of the documented behavior, and an invalid count is an error, not a coerced number.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the index range, the sequential execution, and the result, and the count must be a non-negative integer as documented.
    */
   export const asyncRepeat = async <T>(
     count: number,
     closure: (index: number) => Promise<T>,
   ): Promise<T[]> => {
-    const indexes: number[] = new Array(count).fill(1).map((_, index) => index);
+    validate("asyncRepeat", count);
     const output: T[] = [];
-    for (const index of indexes) output.push(await closure(index));
+    for (let index: number = 0; index < count; ++index)
+      output.push(await closure(index));
     return output;
   };
 
@@ -191,29 +250,40 @@ export namespace ArrayUtil {
    * Similar to JavaScript's native some() method. Returns true immediately when
    * the first element satisfying the condition is found.
    *
+   * Processing cost: Native some stops at the first matching element:
+   * worst-case N predicate calls and constant auxiliary storage.
+   *
    * @example
-   *   ```typescript
    *   const numbers = [1, 3, 5, 7, 8, 9];
    *   const products = [
-   *     { name: 'Apple', price: 100, inStock: true },
-   *     { name: 'Banana', price: 50, inStock: false },
-   *     { name: 'Orange', price: 80, inStock: true }
+   *     { name: "Apple", price: 100, inStock: true },
+   *     { name: "Banana", price: 50, inStock: false },
+   *     { name: "Orange", price: 80, inStock: true },
    *   ];
    *
-   *   const hasEvenNumber = ArrayUtil.has(numbers, num => num % 2 === 0);
+   *   const hasEvenNumber = ArrayUtil.has(numbers, (num) => num % 2 === 0);
    *   console.log(hasEvenNumber); // true (8 exists)
    *
-   *   const hasExpensiveItem = ArrayUtil.has(products, product => product.price > 90);
+   *   const hasExpensiveItem = ArrayUtil.has(
+   *     products,
+   *     (product) => product.price > 90,
+   *   );
    *   console.log(hasExpensiveItem); // true (Apple costs 100)
    *
-   *   const hasOutOfStock = ArrayUtil.has(products, product => !product.inStock);
+   *   const hasOutOfStock = ArrayUtil.has(
+   *     products,
+   *     (product) => !product.inStock,
+   *   );
    *   console.log(hasOutOfStock); // true (Banana is out of stock)
-   *   ```;
    *
    * @template T - The type of elements in the array
    * @param elements - The readonly array to check
    * @param pred - The predicate function to test elements
    * @returns Boolean indicating if any element satisfies the condition
+   * @evidence contracts/common.md#principled-implementation The native `some` implements the existential search and returns at the first satisfying element, and the predicate receives only the element.
+   * @evidence contracts/common.md#clear-and-simple-design A one-expression delegation that keeps the native short-circuit visible.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The predicate alone decides membership.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the short-circuit and gives examples.
    */
   export const has = <T>(
     elements: readonly T[],
@@ -227,17 +297,19 @@ export namespace ArrayUtil {
    * A synchronous repetition function that executes the given function for each
    * index (from 0 to count-1) and collects the results into an array.
    *
+   * Processing cost: The callback runs once for each of N indices, with O(N)
+   * output storage.
+   *
    * @example
-   *   ```typescript
    *   // Generate an array of squares from 1 to 5
-   *   const squares = ArrayUtil.repeat(5, index => (index + 1) ** 2);
+   *   const squares = ArrayUtil.repeat(5, (index) => (index + 1) ** 2);
    *   console.log(squares); // [1, 4, 9, 16, 25]
    *
    *   // Generate an array of default user objects
-   *   const users = ArrayUtil.repeat(3, index => ({
-   *   id: index + 1,
-   *   name: `User${index + 1}`,
-   *   email: `user${index + 1}@example.com`
+   *   const users = ArrayUtil.repeat(3, (index) => ({
+   *     id: index + 1,
+   *     name: `User${index + 1}`,
+   *     email: `user${index + 1}@example.com`,
    *   }));
    *   console.log(users);
    *   // [
@@ -245,59 +317,76 @@ export namespace ArrayUtil {
    *   //   { id: 2, name: 'User2', email: 'user2@example.com' },
    *   //   { id: 3, name: 'User3', email: 'user3@example.com' }
    *   // ]
-   *   ```
    *
    * @template T - The type of the result from each execution
-   * @param count - The number of times to repeat (non-negative integer)
+   * @param count - The number of times to repeat (integer from 0 to 2^32 - 1)
    * @param closure - The function to execute repeatedly
    * @returns An array of results
+   * @evidence contracts/common.md#principled-implementation An invalid count is refused with a `RangeError`, and otherwise the closure is called for each index from 0 to count minus one and the results are collected in order, with cost linear in the count.
+   * @evidence contracts/common.md#clear-and-simple-design The synchronous counterpart of `asyncRepeat`, sharing its validator.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The loop implements the documented behavior directly.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the index range and the result, with examples.
    */
   export const repeat = <T>(
     count: number,
     closure: (index: number) => T,
-  ): T[] => new Array(count).fill("").map((_, index) => closure(index));
+  ): T[] => {
+    validate("repeat", count);
+    const output: T[] = [];
+    for (let index: number = 0; index < count; ++index)
+      output.push(closure(index));
+    return output;
+  };
 
   /**
    * Generates all possible subsets of a given array.
    *
    * Implements the mathematical concept of power set, generating 2^n subsets
    * from an array of n elements. Uses depth-first search (DFS) algorithm to
-   * calculate all possible combinations of including or excluding each
-   * element.
+   * calculate all possible combinations of including or excluding each element.
+   * Each element is included before it is excluded, so the first subset is the
+   * whole array and the last one is empty.
+   *
+   * Processing cost: The DFS visits the include/exclude tree and filters N
+   * input positions at each of 2^N leaves. This is O(N 2^N) time and
+   * materialized output space, the scale required by returning every subset,
+   * with O(N) recursion/mask state.
    *
    * @example
-   *   ```typescript
    *   const numbers = [1, 2, 3];
    *   const allSubsets = ArrayUtil.subsets(numbers);
    *   console.log(allSubsets);
    *   // [
-   *   //   [],           // empty set
-   *   //   [3],          // {3}
-   *   //   [2],          // {2}
-   *   //   [2, 3],       // {2, 3}
-   *   //   [1],          // {1}
-   *   //   [1, 3],       // {1, 3}
+   *   //   [1, 2, 3],    // {1, 2, 3}
    *   //   [1, 2],       // {1, 2}
-   *   //   [1, 2, 3]     // {1, 2, 3}
+   *   //   [1, 3],       // {1, 3}
+   *   //   [1],          // {1}
+   *   //   [2, 3],       // {2, 3}
+   *   //   [2],          // {2}
+   *   //   [3],          // {3}
+   *   //   []            // empty set
    *   // ]
    *
-   *   const colors = ['red', 'blue'];
+   *   const colors = ["red", "blue"];
    *   const colorSubsets = ArrayUtil.subsets(colors);
    *   console.log(colorSubsets);
    *   // [
-   *   //   [],
-   *   //   ['blue'],
+   *   //   ['red', 'blue'],
    *   //   ['red'],
-   *   //   ['red', 'blue']
+   *   //   ['blue'],
+   *   //   []
    *   // ]
    *
    *   // Warning: Result size grows exponentially with array size
    *   // Example: 10 elements → 1,024 subsets, 20 elements → 1,048,576 subsets
-   *   ```;
    *
    * @template T - The type of elements in the array
    * @param array - The array to generate subsets from
    * @returns An array containing all possible subsets
+   * @evidence contracts/common.md#principled-implementation A depth-first search decides for each position whether the element is in the subset, including it first, and each leaf materializes the chosen elements with `filter`, so the 2^n subsets appear in a fixed order, the whole array first and the empty array last; the recursion depth is the array length and the output size is exponential, which bounds the useful input size.
+   * @evidence contracts/common.md#clear-and-simple-design One recursive function over a mask, with no options.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It enumerates every subset without sampling or a size cap, and the array is not mutated.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the power-set meaning, the exact enumeration order, and the exponential growth warning, and the examples show that order.
    */
   export const subsets = <T>(array: T[]): T[][] => {
     const check: boolean[] = new Array(array.length).fill(false);
@@ -317,4 +406,11 @@ export namespace ArrayUtil {
     dfs(0);
     return output;
   };
+
+  const validate = (method: string, count: number): void => {
+    if (!Number.isSafeInteger(count) || count < 0 || count > 0xffffffff)
+      throw new RangeError(
+        `ArrayUtil.${method}(): count must be a non-negative integer.`,
+      );
+  };
 }