Examples

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']

// Negative indices are matched from the end
set(['a', 'b', 'c'], { '-1': 'X' }) // ['a', 'b', 'X']

// Large positive indices extend the array
set(['a', 'b', 'c'], { 4: 'X' }) // ['a', 'b', 'c', undefined, 'X']

// Large negative indices stop at the first item
set(['a', 'b', 'c'], { '-10': 'X' }) // ['X', 'b', 'c']

// -0 appends items
set(['a', 'b', 'c'], { '-0': 'X' }) // ['a', 'b', 'c', 'X']

// If the key ends with +, items are prepended, not replaced
set(['a', 'b', 'c'], { '1+': 'X' }) // ['a', 'X', 'b', 'c']

// Array of items can be used
set(['a', 'b', 'c'], { 1: ['X', 'Y'] }) // ['a', 'X', 'Y', 'c']

// Empty arrays remove items
set(['a', 'b', 'c'], { 1: [] }) // ['a', 'c']

// If the item is an array itself, it must be wrapped in another array
set(['a', 'b', 'c'], { 1: ['X'] }) // ['a', 'X', 'c']
set(['a', 'b', 'c'], { 1: [['X']] }) // ['a', ['X'], 'c']

Install

npm install set-array

This package is an ES module and must be loaded using an import or import() statement, not require().

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

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'], { 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({}) // true

test({ notAnIndex: 'X' }) // false
test('X') // false

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!