immutable-arrays

Immutable versions of normally mutable array methods


Install

``sh
$ npm install --save immutable-arrays
`

Usage

The library is exported in the following formats:
- UMD (Universal Module Definition) for usage in browsers
- CJS (CommonJS) for usage in Node.js
- ESM (Ecmascript Modules) for usage in browsers or environments that support ESM

$3

`html

`

After importing the library it can be accessed via the global variable immutableArrays.

$3

`js
const push = require('immutable-arrays').push;
`

$3

`js
import { push } from 'immutable-arrays';
`

API

$3

Example
`js
const originalArray = ['a', 'b', 'c', 'd', 'e'];
const resultArray = push(originalArray, 'f', 'g');
// -> originalArray ['a', 'b', 'c', 'd', 'e']
// -> resultArray ['a', 'b', 'c', 'd', 'e', 'f', 'g']
`

$3

Example
`js
const originalArray = ['a', 'b', 'c', 'd', 'e'];
const resultArray = pop(originalArray);
// -> originalArray ['a', 'b', 'c', 'd', 'e']
// -> resultArray ['a', 'b', 'c', 'd']
`

$3

Example
`js
const originalArray = ['a', 'b', 'c', 'd', 'e'];
const resultArray = shift(originalArray);
// -> originalArray ['a', 'b', 'c', 'd', 'e']
// -> resultArray ['b', 'c', 'd', 'e']
`

$3

Example
`js
const originalArray = ['a', 'b', 'c', 'd', 'e'];
const resultArray = unshift(originalArray, 'f', 'g');
// -> originalArray ['a', 'b', 'c', 'd', 'e']
// -> resultArray ['f', 'g', 'a', 'b', 'c', 'd', 'e']
`

$3

Example
`js
const originalArray = ['a', 'b', 'c', 'd', 'e'];
const resultArray = reverse(originalArray);
// -> originalArray ['a', 'b', 'c', 'd', 'e']
// -> resultArray ['e', 'd', 'c', 'b', 'a']
`

$3

Example
`js
const numberArray = [20, 3, 4, 10, -3, 1, 0, 5];
const stringArray = ['Blue', 'Humpback', 'Beluga'];

const resultArray = sort(numberArray, (a, b) => a - b);
// -> numberArray [20, 3, 4, 10, -3, 1, 0, 5]
// -> resultArray [-3, 0, 1, 3, 4, 5, 10, 20]

const resultArray = sort(numberArray, (a, b) => b - a);
// -> numberArray [20, 3, 4, 10, -3, 1, 0, 5]
// -> resultArray [20, 10, 5, 4, 3, 1, 0, -3]

const resultArray = sort(stringArray);
// -> stringArray ['Blue', 'Humpback', 'Beluga']
// -> resultArray ['Beluga', 'Blue', 'Humpback']

const resultArray = sort(stringArray, (a, b) => a.toLowerCase() < b.toLowerCase());
// -> stringArray ['Blue', 'Humpback', 'Beluga']
// -> resultArray ['Humpback', 'Blue', 'Beluga']
`

$3

| Param | Type | Default | Description |
| --- | --- | --- | --- |
| array | Array | | The original array. |
| [start] | Number | array.length | Zero based index at which to start changing the array. If greater than the length of the array, actual starting index will be set to the length of the array. |
| [deleteCount] | Number | array.length - start | An integer indicating the number of old array elements to remove. If deleteCount is 0, no elements are removed. If deleteCount is lower than 0, deleteCount will be equal to 0. If deleteCount is greater than the number of elements left in the array starting at start, then all of the elements through the end of the array will be deleted. If deleteCount is omitted, deleteCount will be equal to (array.length - start), i.e., all of the elements beginning with start index on through the end of the array will be deleted. |
| [...elementN] | \* | | The elements to add to the array, beginning at the start index. If you don't specify any elements, will only remove elements from the array. |

Example
`js
const originalArray = ['a', 'b', 'c', 'd', 'e'];
const resultArray = splice(originalArray, 0);
// -> originalArray ['a', 'b', 'c', 'd', 'e']
// -> resultArray []

const originalArray = ['a', 'b', 'c', 'd', 'e'];
const resultArray = splice(originalArray, 0, 1);
// -> originalArray ['a', 'b', 'c', 'd', 'e']
// -> resultArray ['b', 'c', 'd', 'e']

const originalArray = ['a', 'b', 'c', 'd', 'e'];
const resultArray = splice(originalArray, 0, 3);
// -> originalArray ['a', 'b', 'c', 'd', 'e']
// -> resultArray ['d', 'e']

const originalArray = ['a', 'b', 'c', 'd', 'e'];
const resultArray = splice(originalArray, 0, originalArray.length);
// -> originalArray ['a', 'b', 'c', 'd', 'e']
// -> resultArray []

const originalArray = ['a', 'b', 'c', 'd', 'e'];
const resultArray = splice(originalArray, 0, -3);
// -> originalArray ['a', 'b', 'c', 'd', 'e']
// -> resultArray ['a', 'b', 'c', 'd', 'e']

const originalArray = ['a', 'b', 'c', 'd', 'e'];
const resultArray = splice(originalArray, 0, 0, 'lorem', 'ipsum');
// -> originalArray ['a', 'b', 'c', 'd', 'e']
// -> resultArray ['lorem', 'ipsum', 'a', 'b', 'c', 'd', 'e']

const originalArray = ['a', 'b', 'c', 'd', 'e'];
const resultArray = splice(originalArray, originalArray.length, 0, 'lorem', 'ipsum');
// -> originalArray ['a', 'b', 'c', 'd', 'e']
// -> resultArray ['a', 'b', 'c', 'd', 'e', 'lorem', 'ipsum']

const originalArray = ['a', 'b', 'c', 'd', 'e'];
const resultArray = splice(originalArray, 0, 2, 'lorem', 'ipsum');
// -> originalArray ['a', 'b', 'c', 'd', 'e']
// -> resultArray ['lorem', 'ipsum', 'c', 'd', 'e']

const originalArray = ['a', 'b', 'c', 'd', 'e'];
const resultArray = splice(originalArray, originalArray.length - 2, 2, 'lorem', 'ipsum');
// -> originalArray ['a', 'b', 'c', 'd', 'e']
// -> resultArray ['a', 'b', 'c', 'lorem', 'ipsum']
`

$3

Example
`js
const originalArray = ['a', 'b', 'c', 'd', 'e'];
const resultArray = del(originalArray, 2);
// -> originalArray ['a', 'b', 'c', 'd', 'e']
// -> resultArray ['a', 'b', 'd', 'e']

const resultArray2 = del(originalArray, -1);
// -> originalArray ['a', 'b', 'c', 'd', 'e']
// -> resultArray2 ['a', 'b', 'c', 'd', 'e']
`

For developers

$3

`sh
$ npm run dev
`
Builds the library and watches for changes while developing. If you want to build only for a specific format, there are other npm scripts available; check in package.json.

`sh
$ npm run build
`
Builds the library for production.

$3

`sh
$ npm run test
`

$3

`sh
$ npm run coverage
``

Changelog

For API updates and breaking changes, check the CHANGELOG.

License

The MIT License (MIT)