Set array items declaratively.

Array items can be updated, merged, added, inserted, appended, prepended, deleted or set.

Hire me

Please reach out if you're looking for a Node.js API or CLI engineer (11 years of experience). Most recently I have been Netlify Build's and Netlify Plugins' technical lead for 2.5 years. I am available for full-time remote positions.

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
• -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(['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 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!