chunk|mergeObjects/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 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
const data = { a: 1, b: 2, c: 3 };
const chunks = $.data.chunk(data, 2);
// Result: [{ a: 1, b: 2 }, { c: 3 }]
.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
const list = { a: 1, c: 3 };
const result = $.data.add(list, 'b', 2, 1);
// Result: { a: 1, b: 2, c: 3 }
.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
const userProfile = { name: 'Sven', role: 'Admin' };
const resetProfile = $.data.clear(userProfile);
// Alternatively: $.data.empty(userProfile);
// Result: resetProfile is {}, userProfile remains unchanged
.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
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 } }
.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
const user = { id: 1, name: 'Alice', role: 'admin' };
const publicProfile = $.data.pick(user, ['name']);
// Result: { name: 'Alice' }
.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
const user = { id: 1, name: 'Alice', password: '123' };
const safeUser = $.data.omit(user, ['password']);
// Result: { id: 1, name: 'Alice' }
.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
const val = $.data.get(response, 'data.items.0.id');
.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
const config = {};
$.data.set(config, 'database.connection.host', 'localhost');
// config is now: { database: { connection: { host: 'localhost' } } }
.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
const data = { a: 1, b: 2, c: 3 };
const result = $.data.remove.at(data, -1);
// Result: { a: 1, b: 2 }
.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
const queue = { first: 'Task 1', second: 'Task 2' };
const nextQueue = $.data.remove.first(queue);
// Result: { second: 'Task 2' }
.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
const stack = { a: 1, b: 2, c: 3 };
const newStack = $.data.remove.last(stack);
// Result: { a: 1, b: 2 }
.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
const config = { api_key: '123', secret: 'abc', api_url: 'http' };
const safeConfig = $.data.remove.byMatch(config, 'api_', 'startsWith', 'key');
// Result: { secret: 'abc' }
.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
const user = { a: 1, b: 2, c: 3 };
const result = $.data.remove.byKey(user, 'b');
// Result: { a: 1, c: 3 }
.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
const scores = { alice: 10, bob: 5, charlie: 10 };
const result = $.data.remove.byValue(scores, 10);
// Result: { bob: 5 }
.remove.all
Description
Alias for .clear(). Empties the object immutably.
.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
const data = { a: 1, b: 2, c: 3 };
const entry = $.data.find.at(data, -1);
// Result: ['c', 3]
.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
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 }
.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
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]
.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
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]
.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
const settings = { theme_dark: true, theme_light: false, lang: 'en' };
const themes = $.data.find.key(settings, 'theme_', 'startsWith');
// Result: ['theme_dark', 'theme_light']
.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
const roles = { bob: 'admin', alice: 'editor', john: 'admin' };
const admins = $.data.find.value(roles, 'admin', 'exact');
// Result: ['admin', 'admin']
.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
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'