• chunk | mergeArray / merge | add | clear / empty
• pick | omit | get | set
• remove.at | remove.first | remove.last | remove.byMatch | remove.byKey | remove.byValue | remove.all
• find.at | find.first | find.last | find.all | find.key | find.value | find.byMatch

---

.chunk

Description Creates an array of elements split into groups the length of size.

Parameters

• array (Array): The array to process.
• size (Number): The length of each chunk.

Returns

• (Array[]): An array containing the chunked arrays.

Example

const data = [1, 2, 3, 4, 5];
const chunks = $.data.chunk(data, 2);
// Result: [[1, 2], [3, 4], [5]]

---

.mergeArray (Alias: .merge)

Description Merges multiple arrays into a single, flat array. (Note: This creates a new array and does not modify the inputs).

Parameters

• ...arrays (Array[]): A list of arrays to merge (e.g. arr1, arr2, arr3).

Returns

• (Array): A new, single merged array.

Example

const a = [1, 2];
const b = [3, 4];
const c = [5, 6];
const result = $.data.merge(a, b, c);
//Alternative: $.data.mergeArray(a, b, c);

// Result: [1, 2, 3, 4, 5, 6]

---

.add

Description Safely adds an element to the array at a specific position without mutating the original array (Immutable).

Parameters

• array (Array): The original array.
• item (Any): The item to add.
• index (Number, optional): The position to insert at. Defaults to the end (array.length). Negative values count from the back.

Returns

• (Array): A new array including the added element.

Example

const list = ['a', 'c'];
// Insert 'b' at index 1
const result = $.data.add(list, 'b', 1);
// Result: ['a', 'b', 'c']

---

.clear (Alias: .empty)

Description Clears the array and returns a new empty array. This method is strictly immutable; it does not mutate the original array, but instead provides a clean, predictable way to reset data states.

Parameters

• array (Array): The array to clear.

Returns

• (Array): A new, empty array ([]).

Example

const myData = [1, 2, 3, 4, 5];
const resetData = $.data.clear(myData);
// Alternatively: $.data.empty(myData);

// Result: resetData is [], myData remains [1, 2, 3, 4, 5]

---

.pick

Description Creates a new array containing only the elements at the specified indices (Allowlist). Mirrors the object API.

Parameters

• array (Array): The source array.
• indices (Number[]): Array of indices to keep.

Returns

• (Array): A new array with selected elements.

Example

const list = ['a', 'b', 'c', 'd'];
const result = $.data.pick(list, [0, 2]);
// Result: ['a', 'c']

---

.omit

Description Creates a new array containing all elements EXCEPT those at the specified indices (Blocklist). Mirrors the object API.

Parameters

• array (Array): The source array.
• indices (Number[]): Array of indices to remove.

Returns

• (Array): A new array without the specified elements.

Example

const list = ['a', 'b', 'c', 'd'];
const result = $.data.omit(list, [1, 3]);
// Result: ['a', 'c']

---

.get

Description Safely retrieves a value from a nested array/object structure (Safe Navigation) using dot-notation. Mirrors the object API.

Parameters

• array (Array): The source array.
• path (String): The path as a dot-notation string.

Returns

• (Any | undefined): The found value or undefined if any part is missing.

Example

const users = [{ profile: { name: 'Sven' } }];
const name = $.data.get(users, '0.profile.name');
// Result: 'Sven'

---

.set

Description Sets a value deeply within a nested array/object structure. Automatically creates missing intermediate objects or arrays based on the path. Mirrors the object API.

Parameters

• array (Array): The array to modify.
• path (String): The path as a string (e.g., '0.profile.name').
• value (Any): The value to set.

Returns

• (void): Modifies the array in place.

Example

const users = [];
$.data.set(users, '0.profile.role', 'admin');
// Result: [{ profile: { role: 'admin' } }]

---

.remove.at

Description Removes an element at a specific index and returns a new array. Supports negative indices to count from the end.

Parameters

• array (Array): The source array.
• index (Number): The index to remove. Negative values count from the back (e.g., -1 is the last item).

Returns

• (Array): A new array without the item at the specified index.

Example

const numbers = [10, 20, 30, 40];
const result = $.data.remove.at(numbers, -2); // Removes 30
// Result: [10, 20, 40]
// Original 'numbers' array remains [10, 20, 30, 40]

---

.remove.first

Description Removes the first element of the array and returns the rest as a new array.

Parameters

• array (Array): The source array.

Returns

• (Array): A new array without the first element.

Example

const queue = ['Task 1', 'Task 2', 'Task 3'];
const nextQueue = $.data.remove.first(queue);
// Result: ['Task 2', 'Task 3']

---

.remove.last

Description Removes the last element of the array and returns the rest as a new array.

Parameters

• array (Array): The source array.

Returns

• (Array): A new array without the last element.

Example

const stack = ['A', 'B', 'C'];
const newStack = $.data.remove.last(stack);
// Result: ['A', 'B']

---

.remove.byMatch

Description Removes all elements that match the search query condition. (This effectively acts as an inverse filter).

Parameters

• array (Array): The source array.
• query (String|Number): The search term to match against.
• mode (String, optional): Comparison mode: 'exact', 'contains', 'startsWith', 'endsWith'. Default is 'exact'.
• key (String, optional): If the array contains objects, specify the property key to check.

Returns

• (Array): A new array containing only the items that did not match.

Example

const users = [
    { id: 1, role: 'admin' },
    { id: 2, role: 'user' },
    { id: 3, role: 'admin' }
];

// Remove all admins
const nonAdmins = $.data.remove.byMatch(users, 'admin', 'exact', 'role');
// Result: [{ id: 2, role: 'user' }]

---

.remove.byKey

Description Removes the element at a specific index. Mirrors object.remove.byKey. Functionally identical to remove.at for arrays.

Parameters

• array (Array): The source array.
• index (Number): The index (key) to remove.

Returns

• (Array): A new array without the specified index.

Example

const list = ['a', 'b', 'c'];
const result = $.data.remove.byKey(list, 1); 
// Result: ['a', 'c']

---

.remove.byValue

Description Removes all elements that match a specific value exactly (using strict equality !==).

Parameters

• array (Array): The source array.
• value (Any): The exact value to remove.

Returns

• (Array): A new array without the specified values.

Example

const nums = [1, 2, 1, 3];
const result = $.data.remove.byValue(nums, 1); 
// Result: [2, 3]

---

.remove.all

Description Alias for .clear(). Empties the array immutably.

---

.find.at

Description Finds the index of the first element that matches the query.

Parameters

• array (Array): The array to search.
• query (String|Number): The search term.
• mode (String, optional): Comparison mode: 'exact', 'contains', 'startsWith', 'endsWith'. Default is 'exact'.
• key (String, optional): If the array contains objects, specify the property key to search in.

Returns

• (Number): The index of the match, or -1 if not found.

Example

const users = [{id: 1, name: 'Alice'}, {id: 2, name: 'Bob'}];
// Find index of user with name starting with 'Bo'
const index = $.data.find.at(users, 'Bo', 'startsWith', 'name');
// Result: 1

---

.find.all

Description Returns all elements (as a new array) that match the condition. Similar to filter().

Parameters

• array (Array): The array to search.
• query (String|Number): The search term.
• mode (String, optional): 'exact', 'contains', 'startsWith', 'endsWith'. Default is 'exact'.
• key (String, optional): The object property key to check (if array of objects).

Returns

• (Array): An array containing all matching elements.

Example

const files = ['image.png', 'script.js', 'logo.png', 'style.css'];
// Find all .png files
const images = $.data.find.all(files, '.png', 'endsWith');
// Result: ['image.png', 'logo.png']

---

.find.first

Description Returns the first element (the actual item, not the index) that matches the query.

Parameters

• array (Array): The array to search.
• query (String|Number): The search term.
• mode (String, optional): 'exact', 'contains', 'startsWith', 'endsWith'. Default is 'exact'.
• key (String, optional): The object property key to check.

Returns

• (Any | undefined): The found element, or undefined.

Example

const fruits = ['apple', 'banana', 'cherry'];
const match = $.data.find.first(fruits, 'nana', 'contains');
// Result: 'banana'

---

.find.last

Description Returns the last element that matches the query. Searches the array in reverse order.

Parameters

• array (Array): The array to search.
• query (String|Number): The search term.
• mode (String, optional): 'exact', 'contains', 'startsWith', 'endsWith'. Default is 'exact'.
• key (String, optional): The object property key to check.

Returns

• (Any | undefined): The last matching element, or undefined.

Example

const log = [
    { level: 'info', msg: 'Start' },
    { level: 'error', msg: 'Fail' },
    { level: 'info', msg: 'End' }
];
// Find last info message
const lastInfo = $.data.find.last(log, 'info', 'exact', 'level');
// Result: { level: 'info', msg: 'End' }

---

.find.byMatch

Description Finds the index of the first match based on the query condition. (Note: Functionally similar to find.at in the current implementation).

Parameters

• array (Array): The array to search.
• query (String|Number): The search term.
• mode (String, optional): 'exact', 'contains', 'startsWith', 'endsWith'. Default is 'exact'.
• key (String, optional): The object property key to check.

Returns

• (Number): The index of the match, or -1.

Example

const nums = [10, 20, 30, 40];
const idx = $.data.find.byMatch(nums, 30);
// Result: 2

---

.find.key

Description Finds all indices (keys) matching the query. For arrays, keys are the indices (represented as strings). Mirrors the object API.

Parameters

• array (Array): The array to search.
• query (String|Number): The search query.
• mode (String, optional): Comparison mode: 'exact', 'contains', 'startsWith', 'endsWith'. Default is 'exact'.

Returns

• (String[]): An array of matching indices as strings.

Example

const list = ['apple', 'banana', 'apricot'];
// Find indices containing '0'
const indices = $.data.find.key(list, '0', 'exact');
// Result: ['0']

---

.find.value

Description Finds all values matching the query. Identical to find.all() for flat arrays, provided for strict API symmetry with objects.

Parameters

• array (Array): The array to search.
• query (String|Number): The search term.
• mode (String, optional): Comparison mode. Default is 'exact'.

Returns

• (Array): An array of matching values.

Example

const list = ['apple', 'banana', 'apricot'];
const matches = $.data.find.value(list, 'ap', 'startsWith');
// Result: ['apple', 'apricot']