diff --git a/DATA-Utilities-%28Arrays%29.md b/DATA-Utilities-%28Arrays%29.md new file mode 100644 index 0000000..fe91298 --- /dev/null +++ b/DATA-Utilities-%28Arrays%29.md @@ -0,0 +1,560 @@ +* [`chunk`](#usage-chunk) | [`mergeArray` / `merge`](#usage-mergeArray) | [`add`](#usage-add) | [`clear` / `empty`](#usage-clear) +* [`pick`](#usage-pick) | [`omit`](#usage-omit) | [`get`](#usage-get) | [`set`](#usage-set) +* [`remove.at`](#usage-remove-at) | [`remove.first`](#usage-remove-first) | [`remove.last`](#usage-remove-last) | [`remove.byMatch`](#usage-remove-byMatch) | [`remove.byKey`](#usage-remove-byKey) | [`remove.byValue`](#usage-remove-byValue) | [`remove.all`](#usage-remove-all) +* [`find.at`](#usage-find-at) | [`find.first`](#usage-find-first) | [`find.last`](#usage-find-last) | [`find.all`](#usage-find-all) | [`find.key`](#usage-find-key) | [`find.value`](#usage-find-value) | [`find.byMatch`](#usage-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** + +```javascript +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** + +```javascript +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** + +```javascript +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** +```javascript +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** +```javascript +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** + +```javascript +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** +```javascript +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** + +```javascript +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** + +```javascript +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** + +```javascript +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** + +```javascript +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** + +```javascript +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** +```javascript +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** + +```javascript +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** + +```javascript +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** + +```javascript +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** + +```javascript +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** + +```javascript +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** + +```javascript +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** +```javascript +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** + +```javascript +const list = ['apple', 'banana', 'apricot']; +const matches = $.data.find.value(list, 'ap', 'startsWith'); +// Result: ['apple', 'apricot'] +``` \ No newline at end of file