Get immutable versions of Array methods
Tags: immutable, javascript, library, array
Published: 2017-10-17 14:02:29

---
title: "Get immutable versions of Array methods"
published: true
tags: immutable,javascript,library,array
---

Have you ever thought about immutable version of `Array.prototype` methods?
For example, `Array.prototype.push` return a new `Array` instead of number of items.

I've created [immutable-array-prototype](https://github.com/azu/immutable-array-prototype) package.

## Why immutable?

ECMAScript Array has some mutable methods.  

- [Array - JavaScript | MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array "Array - JavaScript | MDN")

![](https://cdn-images-1.medium.com/max/599/1*DOwBN5p5bCJ5ZKKRiKQCgg.png)<figcaption>Mutable vs Immutable</figcaption>

For example, Redux require [Immutable Update](http://redux.js.org/docs/recipes/reducers/ImmutableUpdatePatterns.html "Immutable Update Patterns Â· Redux") on your Store implementation.

`Object.assign` or object spread(`{ ...object }`) can realize immutable updating for Object. But, immutale updating on Array is difficult.

- [Immutable Update Patterns Â· Redux](http://redux.js.org/docs/recipes/reducers/ImmutableUpdatePatterns.html "Immutable Update Patterns Â· Redux")

Of course, [Immutable.js](https://facebook.github.io/immutable-js/ "Immutable.js") is useful. But [Immutable.js](https://facebook.github.io/immutable-js/ "Immutable.js") is very large library.

So, I want to get minimal and easy to use library.


## [`@immutable-array/prototype`](https://github.com/azu/immutable-array-prototype)

[`@immutable-array/prototype`](https://github.com/azu/immutable-array-prototype) includes immutable version of theses `Array.prototype` methods.

```
npm install @immutable-array/prototype
```

Or, If you want to a single method, you can use a method as independent package.

```
npm install @immutable-array/pop
npm install @immutable-array/push
npm install @immutable-array/shift
npm install @immutable-array/unshift
npm install @immutable-array/sort
npm install @immutable-array/reverse
npm install @immutable-array/fill
npm install @immutable-array/splice
npm install @immutable-array/copy-within
```

#### Example

This library provide same API and behavior without first argument.


```js
import {
  sort,
  unshift,
  push,
  fill,
  splice,
  pop,
  reverse,
  copyWithin,
  shift
} from '@immutable-array/prototype';
describe('prototype', () => {
  it('shift', () => {
    assert.deepStrictEqual(shift(['a', 'b', 'c', 'd', 'e']), [
      'b',
      'c',
      'd',
      'e'
    ]);
  });
  it('unshift', () => {
    assert.deepStrictEqual(unshift(['a', 'b', 'c', 'd', 'e'], 'x'), [
      'x',
      'a',
      'b',
      'c',
      'd',
      'e'
    ]);
  });
  it('pop', () => {
    assert.deepStrictEqual(pop(['a', 'b', 'c', 'd', 'e']), [
      'a',
      'b',
      'c',
      'd'
    ]);
  });
  it('push', () => {
    assert.deepStrictEqual(push(['a', 'b', 'c', 'd', 'e'], 'x'), [
      'a',
      'b',
      'c',
      'd',
      'e',
      'x'
    ]);
  });
  it('splice', () => {
    assert.deepStrictEqual(splice(['a', 'b', 'c', 'd', 'e'], 0, 1, 'x'), [
      'x',
      'b',
      'c',
      'd',
      'e'
    ]);
  });
  it('sort', () => {
    assert.deepStrictEqual(sort(['e', 'a', 'c', 'b', 'd']), [
      'a',
      'b',
      'c',
      'd',
      'e'
    ]);
  });
  it('reverse', () => {
    assert.deepStrictEqual(reverse(['a', 'b', 'c', 'd', 'e']), [
      'e',
      'd',
      'c',
      'b',
      'a'
    ]);
  });
  it('fill', () => {
    assert.deepStrictEqual(fill(new Array(5), 'x'), ['x', 'x', 'x', 'x', 'x']);
  });
  it('copyWithin', () => {
    assert.deepStrictEqual(copyWithin(['a', 'b', 'c', 'd', 'e'], 0, 3, 4), [
      'd',
      'b',
      'c',
      'd',
      'e'
    ]);
  });
});
```

## Use Case

[Faao](https://github.com/azu/faao "Faao") that is GitHub Issue application use [`@immutable-array/prototype`](https://github.com/azu/immutable-array-prototype) for creating domain model.
Faao apply DDD/CQRS pattern using [Almin](https://github.com/almin/almin "Almin"). Immutable domain model help to work application in safety.

## Policy

[`@immutable-array/prototype`](https://github.com/azu/immutable-array-prototype) has a support policy.

### Do

- Provide immutable version of `Array.prototype` method
- Provide each method as an module
    - For exaple, `import push from "@immutable-array/push"`
    - All prototype method: `import { push } from "@immutable-array/prototype"`
- ECMAScript compatible API without first arguments

For example, `@immutable-array/*` method should return same result with native API.

```js
import { splice } from '@immutable-array/splice';
var array = [1, 2, 3];
// immutable
var resultArray = splice(array, -1, 1, 'x');
// native
array.splice(-1, 1, 'x');
assert.deepStrictEqual(array, resultArray);
```

### Do not

- Should not add non-standard method in ECMAScript
    - For example, It does not provide `update`, `delete`, `merge` methods.
- Each method should not depended on other method

## Finally

Pull requests and stars are always welcome :)

- [https://github.com/azu/immutable-array-prototype](https://github.com/azu/immutable-array-prototype)