13 KiB
chunk|mergeArray/merge|add|clear/emptypick|omit|get|setremove.at|remove.first|remove.last|remove.byMatch|remove.byKey|remove.byValue|remove.allfind.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
undefinedif 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.,-1is 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
-1if 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']