Examples

// 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.
setArray(['a', 'b', 'c'], { 1: 'X' }) // ['a', 'X', 'c']
setArray(['a', 'b', 'c'], { 1: 'X', 2: 'Y' }) // ['a', 'X', 'Y']

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

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

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

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

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

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

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

// If the item is an array itself, it must be wrapped in another array
setArray(['a', 'b', 'c'], { 1: ['X'] }) // ['a', 'X', 'c']
setArray(['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

setArray(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]

setArray(['a', 'b', 'c'], { 1: 'X' }, { merge }) // ['a', ['b', 'X'], 'c']
setArray(['a', 'b', 'c'], { 1: ['X', 'Y'] }, { merge }) // ['a', ['b', 'X'], ['b', 'Y'], 'c']
setArray(['a', 'b', 'c'], { '1+': 'X' }, { merge }) // ['a', 'X', 'b', 'c']
setArray(['a', 'b', 'c'], { 4: 'X' }, { merge }) // ['a', 'b', 'c', undefined, [undefined, 'X']]

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!