NOTE

This project is no longer actively supported. If anyone is interested in becoming the new maintainer, don't hesitate to contact me (hughfdjackson@googlemail.com).

The go-to immutable library is https://github.com/facebook/immutable-js.

immutable

Effecient immutable collections in javascript.

Why?

Using immutable objects can make code easier to reason about, allowing programmers to geniunely create sections of their programs that operate on a 'data-in/data-out' basis.

This style of code is easy to test, and use in a mix-and-match style.

Install

npm

npm install immutable

browser

Download build/immutable.js, and include it as a script tag.

AMD/require.js

Download build/immutable.js, and require it in:

require(['libs/immutable'],function(immutable){// ... assuming immutable is in libs/immutable.js, now it's ready to use})

Usage

Immutable has two types of collection: objects and arrays. Like regular JavaScript Objects and Arrays, both act as key:value stores (using strings as the keys).

Basic Manipulation

creation

varperson=im.object({name: 'joe bloggs',age: 34})varnumbers=im.array([1,2,3,4,5])

.assoc

varemptyObj=im.object()varperson=emptyObj.assoc({name: 'joe bloggs',age: 34})varpersonWithSports=person.assoc('sport','golf')varemptyArr=im.array()varnumbers=emptyArr.assoc([1,2,3,4,5])varupTo6=numbers.assoc(5,6)

.get

varperson=im.object({name: 'joe bloggs',age: 34})person.get('age')//= 34varnumbers=im.array([1,2,3,4,5])numbers.get(0)//= 1

.has

varperson=im.object({name: 'joe bloggs',age: 34})person.has('name')//= trueperson.has('discography')//= false

.dissoc

Create a collection like this one, but without a particular property:

varperson=im.object({name: 'joe bloggs',age: 34})varpersonShyAboutAge=person.dissoc('age')personShyAboutAge.has('age')//= falsevarnumbers=im.array([1,2,3,4,5])varupTo4=numbers.dissoc(4)// dissocs the 4th keynumbers.has(4)//= trueupTo4.has(4)//= false

.mutable / .toJSON

Create a regular JavaScript object from an immutable one:

varperson=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, sports: im.array(['golf', 'carting']) })
}
JSON.stringify(favouritePeople) // = '{ "joe": { "name": "joe bloggs", "age": 34, "sports": ["golf", "carting"] } }'

Value Equality

Collections can be checked for equality:

varperson1=im.object({name: 'joe bloggs',age: 34})varperson2=im.object({name: 'joe bloggs',age: 34})varperson3=im.object({name: 'joe bloggs',age: 34,sport: 'golf'})person1.equal(person2)//= trueperson3.equal(person2)//= false

Collections are considered equal when:

• They are immutable
• They have all the same keys
• All values are: ** Mutable objects or primtive values that are strictly equal (===), ** Immutable objects that are .equal to one another

Iteration methods

Immutable objects and arrays can be iterated over almost identically, except that:

• objects iterate over all keys, and return objects where appropriate;
• arrays iterate over only numberic keys, and return arrays where appropriate.

All iterator methods (unless mentioned) will pass the value, the key, and the original immutable object to their callback functions.

.map

varinc=function(a){returna+1}varcoordinates=im.object({x: 1,y: 1})coordinates.map(inc).mutable()//= { x: 2, y: 3 }varnumbers=im.array([1,2,3,4,5])numbers.map(inc).mutable()//= [2, 3, 4, 5, 6]

.forEach

varlog=console.log.bind(console)varperson=im.object({name: 'joe bloggs',age: 34})person.map(log)// *log output*// 'joe bloggs' 'name' person// 34 'age' person

.filter

varisNum=function(a){returntypeofa==='number'}varperson=im.object({name: 'joe bloggs',age: 34})person.filter(isNum).mutable()//= { age: 34 }varalphaNumber=im.array(['a',1,'b',2,'c',3])alphaNumber.filter(isNum).mutable()//= [1, 2, 3]

.every

varisNum=function(a){returntypeofa==='number'}im.object({name: 'joe bloggs',age: 34}).every(isNum)//= falseim.object({x: 1,y: 2}).every(isNum)//= trueim.array(['a',1,'b',2,'c',3]).every(isNum)//= falseim.array([1,2,3]).every(isNum)//= true

.some

varisNum=function(a){returntypeofa==='number'}im.object({name: 'joe bloggs',sport: 'golf'}).some(isNum)//= falseim.object({name: 'joe bloggs',age: 34}).some(isNum)//= trueim.array(['a','b','c']).some(isNum)//= falseim.array(['a',1,'b',2,'c',3]).every(isNum)//= true

.reduce

varflip=function(coll,val,key){returncoll.assoc(key,val)}varcoords=im.object({x: '1',y: '2',z: '3'})varflippedCoords=coords.reduce(flip,im.object())flippedCoords.mutable()//= { 1: 'x', 2: 'y', 3: 'z' }varcat=function(a,b){returna+b}varletters=im.array(['a','b','c'])letters.reduce(cat)//= 'abc'

Array Methods

Since arrays are ordered collections, they have some methods of their own, that only make sense in an ordered context:

.reduceRight

varcat=function(a,b){returna+b}varletters=im.array(['a','b','c'])letters.reduceRight(cat)//= 'cba'

.push

varnumbersTo3=im.array([1,2,3])varnumbersTo4=numbersTo3.push(4)numbersTo4.mutable()//= [1, 2, 3, 4]

.indexOf

varmixed=im.array([1,2,3,im.object({x: 3}),{x: 3}])mixed.indexOf('a')//= -1 -- 'a' not in arraymixed.indexOf({x: 3})//= -1 -- mutable objects are compared by referencemixed.indexOf(im.object({x: 3}))//= 3 -- immutable objects are compared by valuemixed.indexOf(3)//= 2 -- primitives are compared by value

Library Functions

.isImmutableCollection

A predicate that returns true if the object is an immutable one, such as produced by this library.

im.isImmutableCollection(im.array([1,2,3]))//= trueim.isImmutableCollection(Object.freeze({}))//= false - you couldn't assoc/dissoc/get/set on it