543 lines
14 KiB
Markdown
543 lines
14 KiB
Markdown
|
* [`chunk`](#usage-chunk) | [`mergeObjects` / `merge`](#usage-mergeObjects) | [`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)
|
||
|
|
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## <a id="usage-chunk"></a>.chunk
|
||
|
|
|
||
|
|
**Description**
|
||
|
|
Splits an object into an array of smaller objects (chunks). Ideal for batched processing of object properties. Mirrors the array API.
|
||
|
|
|
||
|
|
**Parameters**
|
||
|
|
|
||
|
|
* `obj` (Object): The source object.
|
||
|
|
* `size` (Number): The maximum number of keys per chunk.
|
||
|
|
|
||
|
|
**Returns**
|
||
|
|
|
||
|
|
* (Object[]): An array of partial objects.
|
||
|
|
|
||
|
|
**Example**
|
||
|
|
```javascript
|
||
|
|
const data = { a: 1, b: 2, c: 3 };
|
||
|
|
const chunks = $.data.chunk(data, 2);
|
||
|
|
// Result: [{ a: 1, b: 2 }, { c: 3 }]
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## <a id="usage-add"></a>.add
|
||
|
|
|
||
|
|
**Description**
|
||
|
|
Safely adds a key-value pair at a specific index without mutating the original object (Immutable). Note: While modern browsers generally respect object insertion order, relying strictly on object key order is not always recommended.
|
||
|
|
|
||
|
|
**Parameters**
|
||
|
|
|
||
|
|
* `obj` (Object): The original object.
|
||
|
|
* `key` (String): The key to add.
|
||
|
|
* `value` (Any): The value to add.
|
||
|
|
* `index` (Number, optional): The position to insert at. Defaults to the end. Negative values count from the back.
|
||
|
|
|
||
|
|
**Returns**
|
||
|
|
|
||
|
|
* (Object): A new object including the added element.
|
||
|
|
|
||
|
|
**Example**
|
||
|
|
|
||
|
|
```javascript
|
||
|
|
const list = { a: 1, c: 3 };
|
||
|
|
const result = $.data.add(list, 'b', 2, 1);
|
||
|
|
// Result: { a: 1, b: 2, c: 3 }
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## <a id="usage-clear"></a>.clear (Alias: .empty)
|
||
|
|
|
||
|
|
**Description**
|
||
|
|
Clears the object and returns a new empty object. This method is strictly immutable; it does not mutate the original object, ensuring a safe functional approach when resetting state.
|
||
|
|
|
||
|
|
**Parameters**
|
||
|
|
|
||
|
|
* `obj` (Object): The object to clear.
|
||
|
|
|
||
|
|
**Returns**
|
||
|
|
|
||
|
|
* (Object): A new, empty object (`{}`).
|
||
|
|
|
||
|
|
**Example**
|
||
|
|
```javascript
|
||
|
|
const userProfile = { name: 'Sven', role: 'Admin' };
|
||
|
|
const resetProfile = $.data.clear(userProfile);
|
||
|
|
// Alternatively: $.data.empty(userProfile);
|
||
|
|
|
||
|
|
// Result: resetProfile is {}, userProfile remains unchanged
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## <a id="usage-mergeObjects"></a>.mergeObjects (Alias: .merge)
|
||
|
|
|
||
|
|
|
||
|
|
**Description**
|
||
|
|
Recursively merges one or more source objects into a target object (Deep Merge).
|
||
|
|
*Note: This modifies the `target` object in place.*
|
||
|
|
|
||
|
|
**Parameters**
|
||
|
|
|
||
|
|
* `target` (Object): The target object to receive properties.
|
||
|
|
* `...sources` (Object[]): One or more source objects to merge into the target.
|
||
|
|
|
||
|
|
**Returns**
|
||
|
|
|
||
|
|
* (Object): The modified target object.
|
||
|
|
|
||
|
|
**Example**
|
||
|
|
|
||
|
|
```javascript
|
||
|
|
const defaults = { app: { theme: 'light', debug: false } };
|
||
|
|
const config = { app: { debug: true } };
|
||
|
|
|
||
|
|
$.data.merge(defaults, config);
|
||
|
|
// Alternatively: $.data.mergeObjects(defaults, config);
|
||
|
|
|
||
|
|
// defaults is now: { app: { theme: 'light', debug: true } }
|
||
|
|
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## <a id="usage-pick"></a>.pick
|
||
|
|
|
||
|
|
**Description**
|
||
|
|
Creates a new object containing *only* the specified keys (Allowlist).
|
||
|
|
|
||
|
|
**Parameters**
|
||
|
|
|
||
|
|
* `obj` (Object): The source object.
|
||
|
|
* `keys` (String[]): An array of keys to keep.
|
||
|
|
|
||
|
|
**Returns**
|
||
|
|
|
||
|
|
* (Object): A new object with the selected keys.
|
||
|
|
|
||
|
|
**Example**
|
||
|
|
|
||
|
|
```javascript
|
||
|
|
const user = { id: 1, name: 'Alice', role: 'admin' };
|
||
|
|
const publicProfile = $.data.pick(user, ['name']);
|
||
|
|
// Result: { name: 'Alice' }
|
||
|
|
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## <a id="usage-omit"></a>.omit
|
||
|
|
|
||
|
|
**Description**
|
||
|
|
Creates a new object containing all keys *except* the specified ones (Blocklist).
|
||
|
|
|
||
|
|
**Parameters**
|
||
|
|
|
||
|
|
* `obj` (Object): The source object.
|
||
|
|
* `keys` (String[]): An array of keys to remove.
|
||
|
|
|
||
|
|
**Returns**
|
||
|
|
|
||
|
|
* (Object): A new object without the specified keys.
|
||
|
|
|
||
|
|
**Example**
|
||
|
|
|
||
|
|
```javascript
|
||
|
|
const user = { id: 1, name: 'Alice', password: '123' };
|
||
|
|
const safeUser = $.data.omit(user, ['password']);
|
||
|
|
// Result: { id: 1, name: 'Alice' }
|
||
|
|
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## <a id="usage-get"></a>.get
|
||
|
|
|
||
|
|
**Description**
|
||
|
|
Safely retrieves a value from a nested object using dot-notation. Returns `undefined` if the path does not exist, preventing runtime errors.
|
||
|
|
|
||
|
|
**Parameters**
|
||
|
|
|
||
|
|
* `obj` (Object): The object to query.
|
||
|
|
* `path` (String): The path as a dot-notation string (e.g., `'user.address.city'`).
|
||
|
|
|
||
|
|
**Returns**
|
||
|
|
|
||
|
|
* (Any): The found value or `undefined`.
|
||
|
|
|
||
|
|
**Example**
|
||
|
|
|
||
|
|
```javascript
|
||
|
|
const val = $.data.get(response, 'data.items.0.id');
|
||
|
|
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## <a id="usage-set"></a>.set
|
||
|
|
|
||
|
|
**Description**
|
||
|
|
Sets a value deeply within a nested object. It automatically creates missing intermediate objects if the path doesn't exist.
|
||
|
|
|
||
|
|
**Parameters**
|
||
|
|
|
||
|
|
* `obj` (Object): The object to modify.
|
||
|
|
* `path` (String): The path string (e.g., `'settings.theme.color'`).
|
||
|
|
* `value` (Any): The value to set.
|
||
|
|
|
||
|
|
**Returns**
|
||
|
|
|
||
|
|
* (Void): This function mutates the object and returns nothing.
|
||
|
|
|
||
|
|
**Example**
|
||
|
|
|
||
|
|
```javascript
|
||
|
|
const config = {};
|
||
|
|
$.data.set(config, 'database.connection.host', 'localhost');
|
||
|
|
// config is now: { database: { connection: { host: 'localhost' } } }
|
||
|
|
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## <a id="usage-remove-at"></a>.remove.at
|
||
|
|
|
||
|
|
**Description**
|
||
|
|
Removes an entry at a specific index and returns a new object (Immutable). Supports negative indices to count from the end.
|
||
|
|
|
||
|
|
**Parameters**
|
||
|
|
|
||
|
|
* `obj` (Object): The source object.
|
||
|
|
* `index` (Number): The index to remove.
|
||
|
|
|
||
|
|
**Returns**
|
||
|
|
|
||
|
|
* (Object): A new object without the entry at the specified index.
|
||
|
|
|
||
|
|
**Example**
|
||
|
|
```javascript
|
||
|
|
const data = { a: 1, b: 2, c: 3 };
|
||
|
|
const result = $.data.remove.at(data, -1);
|
||
|
|
// Result: { a: 1, b: 2 }
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## <a id="usage-remove-first"></a>.remove.first
|
||
|
|
|
||
|
|
**Description**
|
||
|
|
Removes the first entry of the object and returns the rest as a new object (Immutable).
|
||
|
|
|
||
|
|
**Parameters**
|
||
|
|
|
||
|
|
* `obj` (Object): The source object.
|
||
|
|
|
||
|
|
**Returns**
|
||
|
|
|
||
|
|
* (Object): A new object without the first entry.
|
||
|
|
|
||
|
|
**Example**
|
||
|
|
|
||
|
|
```javascript
|
||
|
|
const queue = { first: 'Task 1', second: 'Task 2' };
|
||
|
|
const nextQueue = $.data.remove.first(queue);
|
||
|
|
// Result: { second: 'Task 2' }
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## <a id="usage-remove-last"></a>.remove.last
|
||
|
|
|
||
|
|
**Description**
|
||
|
|
Removes the last entry of the object and returns the rest as a new object (Immutable).
|
||
|
|
|
||
|
|
**Parameters**
|
||
|
|
|
||
|
|
* `obj` (Object): The source object.
|
||
|
|
|
||
|
|
**Returns**
|
||
|
|
|
||
|
|
* (Object): A new object without the last entry.
|
||
|
|
|
||
|
|
**Example**
|
||
|
|
```javascript
|
||
|
|
const stack = { a: 1, b: 2, c: 3 };
|
||
|
|
const newStack = $.data.remove.last(stack);
|
||
|
|
// Result: { a: 1, b: 2 }
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## <a id="usage-remove-byMatch"></a>.remove.byMatch
|
||
|
|
|
||
|
|
**Description**
|
||
|
|
Removes **all** entries that match the search query condition (Immutable). Acts as an inverse filter.
|
||
|
|
|
||
|
|
**Parameters**
|
||
|
|
|
||
|
|
* `obj` (Object): The source object.
|
||
|
|
* `query` (String|Number): The search term.
|
||
|
|
* `mode` (String, optional): Comparison mode: `'exact'`, `'contains'`, `'startsWith'`, `'endsWith'`. Default is `'exact'`.
|
||
|
|
* `searchBy` (String, optional): Search by `'key'` or `'value'`. Default is `'key'`.
|
||
|
|
|
||
|
|
**Returns**
|
||
|
|
|
||
|
|
* (Object): A new object containing only the items that **did not** match.
|
||
|
|
|
||
|
|
**Example**
|
||
|
|
|
||
|
|
```javascript
|
||
|
|
const config = { api_key: '123', secret: 'abc', api_url: 'http' };
|
||
|
|
const safeConfig = $.data.remove.byMatch(config, 'api_', 'startsWith', 'key');
|
||
|
|
// Result: { secret: 'abc' }
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## <a id="usage-remove-byKey"></a>.remove.byKey
|
||
|
|
|
||
|
|
**Description**
|
||
|
|
Removes a specific key-value pair from the object based on its key (Immutable).
|
||
|
|
|
||
|
|
**Parameters**
|
||
|
|
|
||
|
|
* `obj` (Object): The source object.
|
||
|
|
* `key` (String): The exact key to remove.
|
||
|
|
|
||
|
|
**Returns**
|
||
|
|
|
||
|
|
* (Object): A new object without the specified key.
|
||
|
|
|
||
|
|
**Example**
|
||
|
|
```javascript
|
||
|
|
const user = { a: 1, b: 2, c: 3 };
|
||
|
|
const result = $.data.remove.byKey(user, 'b');
|
||
|
|
// Result: { a: 1, c: 3 }
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## <a id="usage-remove-byValue"></a>.remove.byValue
|
||
|
|
|
||
|
|
**Description**
|
||
|
|
Removes all entries that match a specific value exactly (using strict equality `!==`).
|
||
|
|
|
||
|
|
**Parameters**
|
||
|
|
|
||
|
|
* `obj` (Object): The source object.
|
||
|
|
* `value` (Any): The exact value to remove.
|
||
|
|
|
||
|
|
**Returns**
|
||
|
|
|
||
|
|
* (Object): A new object without the matching values.
|
||
|
|
|
||
|
|
**Example**
|
||
|
|
|
||
|
|
```javascript
|
||
|
|
const scores = { alice: 10, bob: 5, charlie: 10 };
|
||
|
|
const result = $.data.remove.byValue(scores, 10);
|
||
|
|
// Result: { bob: 5 }
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## <a id="usage-remove-all"></a>.remove.all
|
||
|
|
|
||
|
|
**Description**
|
||
|
|
Alias for `.clear()`. Empties the object immutably.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## <a id="usage-find-at"></a>.find.at
|
||
|
|
|
||
|
|
**Description**
|
||
|
|
Returns the n-th entry of an object as a `[key, value]` pair. Supports negative indices to count from the end.
|
||
|
|
|
||
|
|
**Parameters**
|
||
|
|
|
||
|
|
* `obj` (Object): The object to search.
|
||
|
|
* `index` (Number): The 0-based index. Negative numbers count from the back.
|
||
|
|
|
||
|
|
**Returns**
|
||
|
|
|
||
|
|
* ([String, Any] | undefined): A tuple containing the key and value, or undefined.
|
||
|
|
|
||
|
|
**Example**
|
||
|
|
|
||
|
|
```javascript
|
||
|
|
const data = { a: 1, b: 2, c: 3 };
|
||
|
|
const entry = $.data.find.at(data, -1);
|
||
|
|
// Result: ['c', 3]
|
||
|
|
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## <a id="usage-find-all"></a>.find.all
|
||
|
|
|
||
|
|
**Description**
|
||
|
|
Returns a NEW OBJECT containing ALL elements that match the condition. Similar to `filter()` but returns a partial object. Mirrors the array API.
|
||
|
|
|
||
|
|
**Parameters**
|
||
|
|
|
||
|
|
* `obj` (Object): The object to search.
|
||
|
|
* `query` (String|Number): The search term.
|
||
|
|
* `mode` (String, optional): `'exact'`, `'contains'`, `'startsWith'`, `'endsWith'`. Default is `'exact'`.
|
||
|
|
* `searchBy` (String, optional): Search by `'key'` or `'value'`. Default is `'key'`.
|
||
|
|
|
||
|
|
**Returns**
|
||
|
|
|
||
|
|
* (Object): A new object containing only the matching elements.
|
||
|
|
|
||
|
|
**Example**
|
||
|
|
```javascript
|
||
|
|
const config = { a: 1, b: 2, c: 1 };
|
||
|
|
// Find all entries where the value is exactly 1
|
||
|
|
const matches = $.data.find.all(config, 1, 'exact', 'value');
|
||
|
|
// Result: { a: 1, c: 1 }
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## <a id="usage-find-first"></a>.find.first
|
||
|
|
|
||
|
|
**Description**
|
||
|
|
Finds the **first** entry where the key or value matches the query.
|
||
|
|
|
||
|
|
**Parameters**
|
||
|
|
|
||
|
|
* `obj` (Object): The object to search.
|
||
|
|
* `query` (String|Number): The search term.
|
||
|
|
* `mode` (String, optional): Comparison mode: `'exact'`, `'contains'`, `'startsWith'`, `'endsWith'`. Default is `'exact'`.
|
||
|
|
* `searchBy` (String, optional): Search by `'key'` or `'value'`. Default is `'key'`.
|
||
|
|
|
||
|
|
**Returns**
|
||
|
|
|
||
|
|
* ([String, Any] | undefined): The first matching `[key, value]` pair.
|
||
|
|
|
||
|
|
**Example**
|
||
|
|
|
||
|
|
```javascript
|
||
|
|
const config = { admin_id: 10, user_id: 20 };
|
||
|
|
// Find first entry where key starts with 'user'
|
||
|
|
const match = $.data.find.first(config, 'user', 'startsWith', 'key');
|
||
|
|
// Result: ['user_id', 20]
|
||
|
|
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## <a id="usage-find-last"></a>.find.last
|
||
|
|
|
||
|
|
**Description**
|
||
|
|
Finds the **last** entry where the key or value matches the query. Useful for prioritized overrides or ordered objects.
|
||
|
|
|
||
|
|
**Parameters**
|
||
|
|
|
||
|
|
* `obj` (Object): The object to search.
|
||
|
|
* `query` (String|Number): The search term.
|
||
|
|
* `mode` (String, optional): `'exact'`, `'contains'`, `'startsWith'`, `'endsWith'`. Default is `'exact'`.
|
||
|
|
* `searchBy` (String, optional): `'key'` or `'value'`. Default is `'key'`.
|
||
|
|
|
||
|
|
**Returns**
|
||
|
|
|
||
|
|
* ([String, Any] | undefined): The last matching `[key, value]` pair.
|
||
|
|
|
||
|
|
**Example**
|
||
|
|
|
||
|
|
```javascript
|
||
|
|
const files = { 'script.js': 1, 'style.css': 2, 'main.css': 3 };
|
||
|
|
// Find last entry where key ends with '.css'
|
||
|
|
const match = $.data.find.last(files, '.css', 'endsWith', 'key');
|
||
|
|
// Result: ['main.css', 3]
|
||
|
|
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## <a id="usage-find-key"></a>.find.key
|
||
|
|
|
||
|
|
**Description**
|
||
|
|
Finds **all keys** in the object that match the query.
|
||
|
|
|
||
|
|
**Parameters**
|
||
|
|
|
||
|
|
* `obj` (Object): The object to search.
|
||
|
|
* `query` (String): The search term.
|
||
|
|
* `mode` (String, optional): `'exact'`, `'contains'`, `'startsWith'`, `'endsWith'`. Default is `'exact'`.
|
||
|
|
|
||
|
|
**Returns**
|
||
|
|
|
||
|
|
* (String[]): An array of matching keys.
|
||
|
|
|
||
|
|
**Example**
|
||
|
|
|
||
|
|
```javascript
|
||
|
|
const settings = { theme_dark: true, theme_light: false, lang: 'en' };
|
||
|
|
const themes = $.data.find.key(settings, 'theme_', 'startsWith');
|
||
|
|
// Result: ['theme_dark', 'theme_light']
|
||
|
|
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## <a id="usage-find-value"></a>.find.value
|
||
|
|
|
||
|
|
**Description**
|
||
|
|
Finds **all values** in the object that match the query.
|
||
|
|
|
||
|
|
**Parameters**
|
||
|
|
|
||
|
|
* `obj` (Object): The object to search.
|
||
|
|
* `query` (String): The search term.
|
||
|
|
* `mode` (String, optional): `'exact'`, `'contains'`, `'startsWith'`, `'endsWith'`. Default is `'exact'`.
|
||
|
|
|
||
|
|
**Returns**
|
||
|
|
|
||
|
|
* (Any[]): An array of matching values.
|
||
|
|
|
||
|
|
**Example**
|
||
|
|
|
||
|
|
```javascript
|
||
|
|
const roles = { bob: 'admin', alice: 'editor', john: 'admin' };
|
||
|
|
const admins = $.data.find.value(roles, 'admin', 'exact');
|
||
|
|
// Result: ['admin', 'admin']
|
||
|
|
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## <a id="usage-find-byMatch"></a>.find.byMatch
|
||
|
|
|
||
|
|
**Description**
|
||
|
|
Finds the **key** of the first match based on the query condition. This mirrors the array method (which returns a numeric index), but returns the string key for objects.
|
||
|
|
|
||
|
|
**Parameters**
|
||
|
|
|
||
|
|
* `obj` (Object): The object to search.
|
||
|
|
* `query` (String|Number): The search term.
|
||
|
|
* `mode` (String, optional): `'exact'`, `'contains'`, `'startsWith'`, `'endsWith'`. Default is `'exact'`.
|
||
|
|
* `searchBy` (String, optional): Search by `'key'` or `'value'`. Default is `'key'`.
|
||
|
|
|
||
|
|
**Returns**
|
||
|
|
|
||
|
|
* (String | undefined): The key of the first matching entry, or `undefined`.
|
||
|
|
|
||
|
|
**Example**
|
||
|
|
|
||
|
|
```javascript
|
||
|
|
const roles = { user: 'standard', alice: 'admin', bob: 'editor' };
|
||
|
|
|
||
|
|
// Find the key of the first entry where the value is 'admin'
|
||
|
|
const adminKey = $.data.find.byMatch(roles, 'admin', 'exact', 'value');
|
||
|
|
// Result: 'alice'
|
||
|
|
```
|