immutable

What is immutable?

The immutable npm package provides persistent immutable data structures that do not change once created, enabling advanced memoization, change detection, and functional programming techniques. It offers a variety of data structures such as List, Map, Set, and Record.

What are immutable's main functionalities?

Persistent Immutable List

Create and manipulate immutable lists, where modifications return new lists without altering the original.

const { List } = require('immutable');
const list1 = List([1, 2, 3]);
const list2 = list1.push(4);
console.log(list1.size); // 3
console.log(list2.size); // 4

Persistent Immutable Map

Create and manipulate immutable maps, with key-value pairs. Changes produce new maps without changing the original.

const { Map } = require('immutable');
const map1 = Map({ a: 1, b: 2, c: 3 });
const map2 = map1.set('b', 50);
console.log(map1.get('b')); // 2
console.log(map2.get('b')); // 50

Persistent Immutable Set

Create and manipulate immutable sets, which are collections of unique values. Adding existing values does not change the set.

const { Set } = require('immutable');
const set1 = Set([1, 2, 3]);
const set2 = set1.add(3).add(4);
console.log(set1.has(3)); // true
console.log(set2.has(4)); // true

Record Factory

Define 'Record' factories to create immutable records with default values and specific shapes.

const { Record } = require('immutable');
const Person = Record({ name: null, age: null });
const person1 = new Person({ name: 'Alice', age: 30 });
const person2 = person1.set('name', 'Bob');
console.log(person1.name); // Alice
console.log(person2.name); // Bob

Other packages similar to immutable

mori

Mori is a library that provides immutable data structures and functional programming utilities. It is similar to immutable but wraps the ClojureScript's data structures and has a different API.

immer

Immer offers a different approach to immutable data. Instead of persistent data structures, it allows you to work with the standard JavaScript data structures in an immutable way by using a draft state and producing the next immutable state.

seamless-immutable

Seamless-immutable provides immutability for arrays and objects without introducing new data structures. It is simpler and has a smaller API surface compared to immutable, but it does not offer the same level of functional programming support.

README

immutable

Effecient immutable data-structures in javascript.

Why?

Mutability causes headaches; immutability soothes them. JavaScript's Object and Array are crying out for immutable counterparts to complement first-class functions.

Support

Example

var im = require('immutable')
var person = im.object({ firstName: 'hugh', secondName: 'jackson' })

var personWithAge = person.assoc({ age: 24 })

person.has('age')          //= false
personWithAge.has('age')   //= true
personWithAge.get('age')   //= 24

Install

npm install immutable

immutable.object

Create an empty immutable object:

var emptyObject = im.object()

Or define the initial set of properties:

var person = im.object({ name: 'joe bloggs', age: 34 })

.assoc

Create a new immutable object with a property added or updated:

var emptyObject = im.object()

var basicPerson = emptyObject.assoc('human', true)

Or pass an object to define multiple properties at once:

var personRecord = basicPerson.assoc({ name: 'joe bloggs', age: 34 })

.get

Get a property:

var person = im.object({ name: 'joe bloggs', age: 34 })

person.get('age') //= 34

It works on numeric keys too, although you're more likely to use an array for this:

var readingList = im.object({ 1: 'Operating System Design: The Xinu Approach' })

readingList.get(1) //= 'Operating System Design: The Xinu Approach'

.has

Check if an immutable object has a property:

var person = im.object({ name: 'joe bloggs', age: 34 })

person.has('name')        //= true
person.has('discography') //= false

.dissoc

Create a new immutable object without a property:

var person = im.object({ name: 'joe bloggs', age: 34 })

var personShyAboutAge = person.dissoc('age')

personShyAboutAge.get('age') //= undefined

.mutable / .toJSON

Create a regular JavaScript object from an immutable one:

var person = im.object({ name: 'joe bloggs', age: 34 })

person.mutable() //= { name: 'joe bloggs', age: 34 }

The .toJSON alias allows immutable objects to be serialised seamlessly with regular objects:

var favouritePeople = {
	joe: im.object({ name: 'joe bloggs', age: 34 })
}

var data = JSON.stringify(favouritePeople)

data // = { joe: { name: 'joe bloggs', age: 34 } }

immutable.array

Create a new immutable array:

var arr = im.array()

or with initial values:

var arr = im.array([1, 2, 3, 4])

.assoc/.dissoc/.get/.has

Work identically in imutable.array as they do in immutable.object, except that they keep the .length property of the array up to date.

.length

Check the 'length' of an immutable array:

var arr = im.array([1, 2, 3])
arr.length //= 3

.mutable / .toJSON

Create a regular JavaScript object from an immutable one:

var todo = im.array(['write README', 'run tests on all supported platform'])

todo.mutable() //= ['write README', 'run tests on all supported platform']

The .toJSON alias allows immutable objects to be serialised seamlessly with regular objects:

var lists = {
	todo: im.array(['write README', 'run tests on all supported platform'])
}

var data = JSON.stringify(lists)

data // = { todo: ['write README', 'run tests on all supported platform'] }