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 copy
Or a server receiving network patch requests.
PATCH /pets/0
{
"toys" : { "1" : "updateSecondToy" , "-0" : "appendNewToy" }
} copy
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'] copy
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'] copy
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'] copy
Insert
// If the key ends with +, items are prepended, not replaced
set ([ 'a' , 'b' , 'c' ], { '1+' : 'X' }) // ['a', 'X', 'b', 'c'] copy
Append
set ([ 'a' , 'b' , 'c' ], { '-0' : 'X' }) // ['a', 'b', 'c', 'X']
set ([ 'a' , 'b' , 'c' ], { '-0' : [ 'X' , 'Y' ] }) // ['a', 'b', 'c', 'X', 'Y'] copy
Prepend
set ([ 'a' , 'b' , 'c' ], { '0+' : [ 'X' , 'Y' ] }) // ['X', 'Y', 'a', 'b', 'c'] copy
Delete
set ([ 'a' , 'b' , 'c' ], { 1 : [] }) // ['a', 'c'] copy
Set
set ([], { 0 : 'X' , 2 : 'Z' }) // ['X', undefined, 'Z'] copy
Install
npm install set-array copy
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
-0 appends 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 ([
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 copy
declarative-merge : merge
objects/arrays declaratively
wild-wild-utils : apply
set-array on multiple properties at once using this module's
merge() 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!