ehmicky
Set array items declaratively.
Array items can be updated, merged, added, inserted, appended, prepended, deleted or set.
Use cases
This is intended for cases where arrays manipulation in JavaScript is not available.
For example, a library where shared configuration files can be extended.
# The shared configuration exports a `rules` array of objects
extend: my-shared-config
rules:
# Update a rule
1:
level: silent
# Append a rule
'-0':
name: appendedRule
Or a server receiving network patch requests.
PATCH /pets/0
{
"toys": { "1": "updateSecondToy", "-0": "appendNewToy" }
}
Examples
Update
import { set } from 'set-array'
// Each element in the object argument updates array items.
// The object keys are the array indices (before any updates).
// The array is copied, not mutated.
set(['a', 'b', 'c'], { 1: 'X' }) // ['a', 'X', 'c']
set(['a', 'b', 'c'], { 1: 'X', 2: 'Y' }) // ['a', 'X', 'Y']
Indices
set(['a', 'b', 'c'], { '*': 'X' }) // ['X', 'X', 'X']
set(['a', 'b', 'c'], { '-1': 'X' }) // ['a', 'b', 'X']
set(['a', 'b', 'c'], { 4: 'X' }) // ['a', 'b', 'c', undefined, 'X']
Add
// Array of items can be used
set(['a', 'b', 'c'], { 1: ['X', 'Y'] }) // ['a', 'X', 'Y', 'c']
set(['a', 'b', 'c'], { 1: ['X'] }) // ['a', 'X', 'c']
set(['a', 'b', 'c'], { 1: [['X']] }) // ['a', ['X'], 'c']
Insert
// If the key ends with +, items are prepended, not replaced
set(['a', 'b', 'c'], { '1+': 'X' }) // ['a', 'X', 'b', 'c']
Append
set(['a', 'b', 'c'], { '-0': 'X' }) // ['a', 'b', 'c', 'X']
set(['a', 'b', 'c'], { '-0': ['X', 'Y'] }) // ['a', 'b', 'c', 'X', 'Y']
Prepend
set(['a', 'b', 'c'], { '0+': ['X', 'Y'] }) // ['X', 'Y', 'a', 'b', 'c']
Delete
set(['a', 'b', 'c'], { 1: [] }) // ['a', 'c']
Set
set([], { 0: 'X', 2: 'Z' }) // ['X', undefined, 'Z']
Install
npm install set-array
This package works in both Node.js >=18.18.0 and browsers.
This is an ES module. It must be loaded using
an import or import() statement,
not require(). If TypeScript is used, it must be configured to
output ES modules,
not CommonJS.
API
set(array, updates, options?)
array any[]\
updates object\
options object?\
Return value: any[]
Return a copy of array with each of the updates applied.
Updates
Values
updates values are the items to add.
- Array of values add multiple items
- Empty arrays remove items
Keys
updates keys are the array indices (before any updates).
- Negative indices match from the end
-0appends items- If the key ends with
+, items are prepended, not replaced *targets all items
Options
Options are an optional plain object.
merge(oldValue, newValue)
oldValue any\
newValue any\
Return value: any
By default, the updates items override the original array's
items. The merge option can be used to merge those instead.
If an array of items is being added, merge() is called once per item.
merge() is not called when the update's key ends with +, i.e. when items are
being prepended.
merge() is called even if the update's index is out-of-bound, with oldValue
being undefined.
const merge = (oldValue, newValue) => [oldValue, newValue]
set(['a', 'b', 'c'], { 1: 'X' }, { merge }) // ['a', ['b', 'X'], 'c']
set(['a', 'b', 'c'], { '*': 'X' }, { merge }) // [['a', 'X'], ['b', 'X'], ['c', 'X']]
set(['a', 'b', 'c'], { 1: ['X', 'Y'] }, { merge }) // ['a', ['b', 'X'], ['b', 'Y'], 'c']
set(['a', 'b', 'c'], { '1+': 'X' }, { merge }) // ['a', 'X', 'b', 'c']
set(['a', 'b', 'c'], { 4: 'X' }, { merge }) // ['a', 'b', 'c', undefined, [undefined, 'X']]
test(updates)
updates any\
Return value: boolean
Return whether the argument is an object that follows the shape
expected by set().
test({ 1: 'X' }) // true
test({ '1+': 'X' }) // true
test({ '-1': 'X' }) // true
test({ '*': 'X' }) // true
test({}) // true
test({ notAnIndex: 'X' }) // false
test('X') // false
Related projects
declarative-merge: merge objects/arrays declarativelywild-wild-utils: applyset-arrayon multiple properties at once using this module'smerge()method
Support
For any question, don't hesitate to submit an issue on GitHub.
Everyone is welcome regardless of personal background. We enforce a Code of conduct in order to promote a positive and inclusive environment.
Contributing
This project was made with ❤️. The simplest way to give back is by starring and sharing it online.
If the documentation is unclear or has a typo, please click on the page's Edit
button (pencil icon) and suggest a correction.
If you would like to help us fix a bug or add a new feature, please check our guidelines. Pull requests are welcome!