immutable-arrays

Immutable versions of normally mutable array methods

Install

$ 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

Old school browser global

<script src="https://unpkg.com/immutable-arrays@<VERSION_GOES_HERE>/dist/immutable-arrays.umd.min.js"></script> 

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

Node.js

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

ES2015 imports

import { push } from 'immutable-arrays';

API

push(array, ...elementN) ⇒ Array

Adds one or more elements to the end of an array by returning a new array instead of mutating the original one.

Returns: Array - A new array with the new entries added to the end.

Param	Type	Description
array	Array	The original array.
...elementN	*	The elements to add to the end of the array.

Example

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

pop(array) ⇒ Array

Removes the last element from an array by returning a new array instead of mutating the original one.

Returns: Array - A new array with the last element removed.

Param	Type	Description
array	Array	The original array.

Example

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

shift(array) ⇒ Array

Removes the first element from an array.

Returns: Array - A new array with the first element removed.

Param	Type	Description
array	Array	The original array.

Example

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

unshift(array, ...elementN) ⇒ Array

Adds one or more elements to the beginning of an array.

Returns: Array - A new array with the new elements added to the front.

Param	Type	Description
array	Array	The original array.
...elementN	*	[description] The elements to add to the front of the array.

Example

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

reverse(array) ⇒ Array

Reverses an array (not in place). The first array element becomes the last, and the last array element becomes the first.

Returns: Array - A new array reversed.

Param	Type	Description
array	Array	The original array.

Example

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

sort(array, [compareFunction]) ⇒ Array

Sorts the elements of an array (not in place) and returns a sorted array.

Returns: Array - A new sorted array.

Param	Type	Description
array	Array	The original array.
[compareFunction]	Function	Specifies a function that defines the sort order. If omitted, the array is sorted according to each character's Unicode code point value, according to the string conversion of each element.

Example

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

splice(array, [start], [deleteCount], [...elementN]) ⇒ Array

Removes existing elements and/or adds new elements to an array.

Returns: Array - The result array.

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

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

del(array, index) ⇒ Array

Deletes an element from an array by its index in the array.

Returns: Array - A new array with the element removed.

Param	Type	Description
array	Array	The original array.
index	Number	The index of the element to delete in the original array. If index is a negative number, a copy of the original array is returned.

Example

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

Build the library

$ 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.

$ npm run build

Builds the library for production.

Run the tests

$ npm run test

Tests coverage

$ npm run coverage

Changelog

For API updates and breaking changes, check the CHANGELOG.

License

The MIT License (MIT)