@dimensional-innovations/vue-toolkit
Version:
A comprehensive toolkit for Vue development including components, composables, and utilities
186 lines (137 loc) • 4.73 kB
Markdown
# Data Utilities
A collection of utility functions for manipulating and transforming data objects and arrays.
## Import
```js
import {
deepMerge,
groupBy,
sortByProperty,
pick,
omit
} from '@dimensional-innovations/vue-toolkit';
```
## Usage
```js
// Deep merge objects
deepMerge({ a: 1, b: { c: 2 } }, { b: { c: 3, d: 4 } }); // { a: 1, b: { c: 3, d: 4 } }
// Group array items by property
groupBy(
[
{ name: 'Alice', category: 'A' },
{ name: 'Bob', category: 'B' }
],
'category'
);
// { 'A': [{ name: 'Alice', category: 'A' }], 'B': [{ name: 'Bob', category: 'B' }] }
// Sort array by property
sortByProperty(
[
{ name: 'Alice', age: 30 },
{ name: 'Bob', age: 25 }
],
'age'
);
// [{ name: 'Bob', age: 25 }, { name: 'Alice', age: 30 }]
// Pick properties from object
pick({ name: 'Alice', email: 'alice@example.com', age: 30 }, ['name', 'email']);
// { name: 'Alice', email: 'alice@example.com' }
// Omit properties from object
omit({ name: 'Alice', email: 'alice@example.com', age: 30 }, ['email', 'age']);
// { name: 'Alice' }
```
## API Reference
### deepMerge(target, source)
Performs a deep merge of two objects.
**Parameters:**
| Parameter | Type | Description |
| --------- | ------ | --------------------------- |
| target | Object | Target object to merge into |
| source | Object | Source object to merge from |
**Returns:** Object - Merged object
**Examples:**
```js
// Returns { a: 1, b: { c: 3, d: 4 } }
deepMerge({ a: 1, b: { c: 2 } }, { b: { c: 3, d: 4 } });
```
### groupBy(array, key)
Groups an array of objects by a specified key.
**Parameters:**
| Parameter | Type | Description |
| --------- | ---------------- | ------------------------------------------------------------- |
| array | Array | Array of objects to group |
| key | string\|Function | Property name to group by or function returning the group key |
**Returns:** Object - Grouped object where keys are group values and values are arrays of items
**Examples:**
```js
// Returns { 'A': [{ name: 'Alice', category: 'A' }], 'B': [{ name: 'Bob', category: 'B' }] }
groupBy(
[
{ name: 'Alice', category: 'A' },
{ name: 'Bob', category: 'B' }
],
'category'
);
// Groups by the first letter of the name
groupBy([{ name: 'Alice' }, { name: 'Bob' }, { name: 'Amy' }], (item) => item.name[0]);
// Returns { 'A': [{ name: 'Alice' }, { name: 'Amy' }], 'B': [{ name: 'Bob' }] }
```
### sortByProperty(array, property, direction)
Sorts an array of objects by a property value.
**Parameters:**
| Parameter | Type | Default | Description |
| --------- | ---------------- | ------- | ----------------------------------------------- |
| array | Array | - | The array to sort |
| property | string\|Function | - | Property name or function to get the sort value |
| direction | string | 'asc' | Sort direction ('asc' or 'desc') |
**Returns:** Array - The sorted array
**Examples:**
```js
// Returns sorted by age ascending
sortByProperty(
[
{ name: 'Alice', age: 30 },
{ name: 'Bob', age: 25 }
],
'age'
);
// Returns sorted by age descending
sortByProperty(
[
{ name: 'Alice', age: 30 },
{ name: 'Bob', age: 25 }
],
'age',
'desc'
);
// Returns sorted by name length
sortByProperty(
[{ name: 'Alice' }, { name: 'Bob' }, { name: 'Christopher' }],
(item) => item.name.length
);
```
### pick(obj, keys)
Creates a new object picking only specified properties from the source object.
**Parameters:**
| Parameter | Type | Description |
| --------- | ------------- | --------------------- |
| obj | Object | Source object |
| keys | Array<string> | Array of keys to pick |
**Returns:** Object - New object with only picked properties
**Examples:**
```js
// Returns { name: 'Alice', email: 'alice@example.com' }
pick({ name: 'Alice', email: 'alice@example.com', age: 30 }, ['name', 'email']);
```
### omit(obj, keys)
Creates a new object omitting specified properties from the source object.
**Parameters:**
| Parameter | Type | Description |
| --------- | ------------- | --------------------- |
| obj | Object | Source object |
| keys | Array<string> | Array of keys to omit |
**Returns:** Object - New object without omitted properties
**Examples:**
```js
// Returns { name: 'Alice' }
omit({ name: 'Alice', email: 'alice@example.com', age: 30 }, ['email', 'age']);
```