feat(array): add new array helpers and array-like detection

.size-limit.json

@@ -2,42 +2,42 @@
   {
     "name": "es5-full",
     "path": "lib/dist/es5/mod/ts-utils.js",
-    "limit": "24.5 kb",
+    "limit": "27.5 kb",
     "brotli": false,
     "running": false
   },
   {
     "name": "es6-full",
     "path": "lib/dist/es6/mod/ts-utils.js",
-    "limit": "23.5 kb",
+    "limit": "26.5 kb",
     "brotli": false,
     "running": false
   },
   {
     "name": "es5-full-brotli",
     "path": "lib/dist/es5/mod/ts-utils.js",
-    "limit": "9 kb",
+    "limit": "10 kb",
     "brotli": true,
     "running": false
   },
   {
     "name": "es6-full-brotli",
     "path": "lib/dist/es6/mod/ts-utils.js",
-    "limit": "9 kb",
+    "limit": "9.75 kb",
     "brotli": true,
     "running": false
   },
   {
     "name": "es5-zip",
     "path": "lib/dist/es5/mod/ts-utils.js",
-    "limit": "9.5 Kb",
+    "limit": "11 Kb",
     "gzip": true,
     "running": false
   },
   {
     "name": "es6-zip",
     "path": "lib/dist/es6/mod/ts-utils.js",
-    "limit": "9.5 Kb",
+    "limit": "10.5 Kb",
     "gzip": true,
     "running": false
   },
@@ -68,7 +68,7 @@
   {
     "name": "es5-poly",
     "path": "lib/bundle/es5/ts-polyfills-utils.js",
-    "limit": "9 kb",
+    "limit": "10 kb",
     "brotli": false,
     "running": false
   },

lib/src/array/at.ts

@@ -0,0 +1,71 @@
+/*
+ * @nevware21/ts-utils
+ * https://github.com/nevware21/ts-utils
+ *
+ * Copyright (c) 2026 NevWare21 Solutions LLC
+ * Licensed under the MIT license.
+ */
+
+import { ArrProto } from "../internal/constants";
+import { _unwrapFunctionWithPoly } from "../internal/unwrapFunction";
+import { isArrayLike } from "../helpers/base";
+
+/**
+ * The arrAt() method takes an integer value and returns the item at that index, allowing for
+ * positive and negative integers. Negative integers count back from the last item in the array.
+ * This is an ES2022 feature with polyfill support for older environments.
+ * @function
+ * @since 0.14.0
+ * @group Array
+ * @group ArrayLike
+ * @typeParam T - Identifies the type of array elements
+ * @param theArray - The array or array-like object to get element from
+ * @param index - The index of the element to return. Negative index counts from the end
+ * @returns The element at the specified index, or undefined if index is out of range
+ * @example
+ * ```ts
+ * arrAt([1, 2, 3, 4, 5], 0);      // 1
+ * arrAt([1, 2, 3, 4, 5], 2);      // 3
+ * arrAt([1, 2, 3, 4, 5], -1);     // 5
+ * arrAt([1, 2, 3, 4, 5], -2);     // 4
+ * arrAt([1, 2, 3], 10);           // undefined
+ * arrAt([1, 2, 3], -10);          // undefined
+ *
+ * // Array-like objects
+ * arrAt({ length: 3, 0: "a", 1: "b", 2: "c" }, -1);  // "c"
+ * ```
+ */
+export const arrAt = (/*#__PURE__*/_unwrapFunctionWithPoly("at", ArrProto as any, polyArrAt) as <T>(theArray: ArrayLike<T>, index: number) => T | undefined);
+
+/**
+ * Polyfill implementation of Array.at() for environments that don't support it.
+ * @since 0.14.0
+ * @group Array
+ * @group ArrayLike
+ * @group Polyfill
+ * @typeParam T - Identifies the type of array elements
+ * @param theArray - The array or array-like object to get element from
+ * @param index - The index of the element to return
+ * @returns The element at the specified index, or undefined if out of range
+ */
+/*#__NO_SIDE_EFFECTS__*/
+export function polyArrAt<T>(theArray: ArrayLike<T>, index: number): T | undefined {
+    let result: T | undefined;
+
+    if (isArrayLike(theArray)) {
+        const len = theArray.length;
+        let idx = index;
+
+        // Convert negative index to positive
+        if (idx < 0) {
+            idx = len + idx;
+        }
+
+        // Check bounds and get value
+        if (idx >= 0 && idx < len) {
+            result = theArray[idx];
+        }
+    }
+
+    return result;
+}

lib/src/array/callbacks.ts

@@ -14,8 +14,8 @@
  * @group ArrayLike
  * @typeParam T - Identifies the type of array elements
  * @typeParam E - Identifies the type of the return array elements (defaults to T)
- * @param value - The cuirrent element of the array being processed.
- * @param index - The index of the current elemety of the array being processed.
+ * @param value - The current element of the array being processed.
+ * @param index - The index of the current element of the array being processed.
  * @param array - The array being processed.
  * @returns A boolean value indicating that the value is of the type expected (the test is true)
  */
@@ -29,8 +29,8 @@ export type ArrPredicateCallbackFn<T, E extends T> = (value: T, index: number, a
  * @group ArrayLike
  * @typeParam T - Identifies the type of array elements
  * @typeParam E - Identifies the type of the return array elements (defaults to T)
- * @param value - The cuirrent element of the array being processed.
- * @param index - The index of the current elemety of the array being processed.
+ * @param value - The current element of the array being processed.
+ * @param index - The index of the current element of the array being processed.
  * @param array - The array being processed.
  */
 export type ArrPredicateCallbackFn2<T> = (value: T, index: number, array: T[]) => unknown;

lib/src/array/chunk.ts

@@ -0,0 +1,56 @@
+/*
+ * @nevware21/ts-utils
+ * https://github.com/nevware21/ts-utils
+ *
+ * Copyright (c) 2026 NevWare21 Solutions LLC
+ * Licensed under the MIT license.
+ */
+
+import { isArrayLike } from "../helpers/base";
+import { arrForEach } from "./forEach";
+
+/**
+ * The arrChunk() method returns a new array with elements divided into groups of a specified size.
+ * The last group may have fewer elements if the array length is not divisible by the chunk size.
+ * @function
+ * @since 0.14.0
+ * @group Array
+ * @group ArrayLike
+ * @typeParam T - Identifies the base type of array elements
+ * @param theArray - The array or array-like object to chunk
+ * @param size - The size of each chunk. Must be a positive integer
+ * @returns A new array of chunks, where each chunk is an array of the specified size
+ * @example
+ * ```ts
+ * arrChunk([1, 2, 3, 4, 5, 6, 7], 2);     // [[1, 2], [3, 4], [5, 6], [7]]
+ * arrChunk([1, 2, 3, 4, 5], 3);          // [[1, 2, 3], [4, 5]]
+ * arrChunk([1, 2, 3], 1);                // [[1], [2], [3]]
+ * arrChunk([1, 2, 3], 5);                // [[1, 2, 3]]
+ * arrChunk([], 2);                       // []
+ *
+ * // Array-like objects
+ * arrChunk({ length: 5, 0: "a", 1: "b", 2: "c", 3: "d", 4: "e" }, 2);
+ * // [["a", "b"], ["c", "d"], ["e"]]
+ * ```
+ */
+/*#__NO_SIDE_EFFECTS__*/
+export function arrChunk<T>(theArray: ArrayLike<T> | null | undefined, size: number): T[][] {
+    const result: T[][] = [];
+
+    if (isArrayLike(theArray) && size > 0) {
+        let idx = 0;
+        let chunkIdx = -1;
+
+        arrForEach(theArray, (item) => {
+            if (idx % size === 0) {
+                result.push([]);
+                chunkIdx++;
+            }
+
+            result[chunkIdx].push(item);
+            idx++;
+        });
+    }
+
+    return result;
+}

lib/src/array/compact.ts

@@ -0,0 +1,46 @@
+/*
+ * @nevware21/ts-utils
+ * https://github.com/nevware21/ts-utils
+ *
+ * Copyright (c) 2026 NevWare21 Solutions LLC
+ * Licensed under the MIT license.
+ */
+
+import { isArrayLike } from "../helpers/base";
+import { arrForEach } from "./forEach";
+
+/**
+ * The arrCompact() method returns a new array with all falsy values removed.
+ * Falsy values include: false, 0, -0, 0n, "", null, undefined, and NaN.
+ * @function
+ * @since 0.14.0
+ * @group Array
+ * @group ArrayLike
+ * @typeParam T - Identifies the base type of array elements
+ * @param theArray - The array or array-like object to compact
+ * @returns A new array with all falsy values filtered out
+ * @example
+ * ```ts
+ * arrCompact([0, 1, false, 2, "", 3, null, undefined, 4]);  // [1, 2, 3, 4]
+ * arrCompact([false, 0, "", null, undefined]);              // []
+ * arrCompact([1, 2, 3]);                                    // [1, 2, 3]
+ * arrCompact([]);                                           // []
+ *
+ * // Array-like objects
+ * arrCompact({ length: 5, 0: 0, 1: 1, 2: false, 3: 2, 4: null });  // [1, 2]
+ * ```
+ */
+/*#__NO_SIDE_EFFECTS__*/
+export function arrCompact<T>(theArray: ArrayLike<T | null | undefined | false | 0 | ""> | null | undefined): T[] {
+    const result: T[] = [];
+
+    if (isArrayLike(theArray)) {
+        arrForEach(theArray, (item) => {
+            if (item) {
+                result.push(item);
+            }
+        });
+    }
+
+    return result;
+}

lib/src/array/difference.ts

@@ -0,0 +1,58 @@
+/*
+ * @nevware21/ts-utils
+ * https://github.com/nevware21/ts-utils
+ *
+ * Copyright (c) 2026 NevWare21 Solutions LLC
+ * Licensed under the MIT license.
+ */
+
+import { isArrayLike } from "../helpers/base";
+import { arrForEach } from "./forEach";
+import { arrIncludes } from "./includes";
+
+/**
+ * The arrDifference() method returns a new array containing elements from the first array
+ * that do not exist in any of the other provided arrays. Uses strict equality (===) for comparison.
+ * @since 0.14.0
+ * @group Array
+ * @group ArrayLike
+ * @typeParam T - Identifies the base type of array elements
+ * @param theArray - The source array to compare from
+ * @param excludeArrays - One or more arrays whose values should be excluded
+ * @returns A new array containing elements only in the source array
+ * @example
+ * ```ts
+ * arrDifference([1, 2, 3, 4], [2, 4]);           // [1, 3]
+ * arrDifference([1, 2, 3], [2], [3]);            // [1]
+ * arrDifference(["a", "b", "c"], ["b"]);         // ["a", "c"]
+ * arrDifference([1, 2, 3], []);                  // [1, 2, 3]
+ * arrDifference([], [1, 2]);                     // []
+ *
+ * // Array-like objects
+ * arrDifference({ length: 3, 0: 1, 1: 2, 2: 3 }, [2]);  // [1, 3]
+ * ```
+ */
+/*#__NO_SIDE_EFFECTS__*/
+export function arrDifference<T>(theArray: ArrayLike<T> | null | undefined, ...excludeArrays: ArrayLike<T>[]): T[] {
+    let result: T[] = [];
+
+    if (isArrayLike(theArray)) {
+        arrForEach(theArray, (item) => {
+            let excluded = false;
+            for (let lp = 0; lp < excludeArrays.length; lp++) {
+                let exclValue = excludeArrays[lp];
+                // Check if excludeArray is valid before using arrIncludes
+                if (isArrayLike(exclValue) && arrIncludes(exclValue, item)) {
+                    excluded = true;
+                    break;
+                }
+            }
+
+            if (!excluded) {
+                result.push(item);
+            }
+        });
+    }
+
+    return result;
+}

lib/src/array/drop.ts

@@ -0,0 +1,37 @@
+/*
+ * @nevware21/ts-utils
+ * https://github.com/nevware21/ts-utils
+ *
+ * Copyright (c) 2026 NevWare21 Solutions LLC
+ * Licensed under the MIT license.
+ */
+
+import { arrSlice } from "./slice";
+import { mathMax } from "../math/min_max";
+
+/**
+ * The arrDrop() method returns a new array with the first n elements removed from the source array.
+ * If n is greater than the array length, returns empty array. If n is negative or 0, returns all elements.
+ * @since 0.14.0
+ * @group Array
+ * @group ArrayLike
+ * @typeParam T - Identifies the base type of array elements
+ * @param theArray - The array or array-like object to drop from
+ * @param count - The number of elements to drop from the beginning
+ * @returns A new array with the first n elements removed
+ * @example
+ * ```ts
+ * arrDrop([1, 2, 3, 4, 5], 2);    // [3, 4, 5]
+ * arrDrop(["a", "b", "c"], 1);    // ["b", "c"]
+ * arrDrop([1, 2], 5);             // []
+ * arrDrop([1, 2, 3], 0);          // [1, 2, 3]
+ * arrDrop([1, 2, 3], -1);         // [1, 2, 3]
+ *
+ * // Array-like objects
+ * arrDrop({ length: 4, 0: 1, 1: 2, 2: 3, 3: 4 }, 2);  // [3, 4]
+ * ```
+ */
+/*#__NO_SIDE_EFFECTS__*/
+export function arrDrop<T>(theArray: ArrayLike<T> | null | undefined, count: number): T[] {
+    return arrSlice(theArray, mathMax(0, count));
+}