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).
For an alternative, consider https://npmjs.org/package/mori.
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){
})
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
var person = im.object({ name: 'joe bloggs', age: 34 })
var numbers = im.array([1, 2, 3, 4, 5])
.assoc
var emptyObj = im.object()
var person = emptyObj.assoc({ name: 'joe bloggs', age: 34 })
var personWithSports = person.assoc('sport', 'golf')
var emptyArr = im.array()
var numbers = emptyArr.assoc([1, 2, 3, 4, 5])
var upTo6 = numbers.assoc(5, 6)
.get
var person = im.object({ name: 'joe bloggs', age: 34 })
person.get('age')
var numbers = im.array([1, 2, 3, 4, 5])
numbers.get(0)
.has
var person = im.object({ name: 'joe bloggs', age: 34 })
person.has('name')
person.has('discography')
.dissoc
Create a collection like this one, but without a particular property:
var person = im.object({ name: 'joe bloggs', age: 34 })
var personShyAboutAge = person.dissoc('age')
personShyAboutAge.has('age')
var numbers = im.array([1, 2, 3, 4, 5])
var upTo4 = numbers.dissoc(4)
numbers.has(4)
upTo4.has(4)
.mutable / .toJSON
Create a regular JavaScript object from an immutable one:
var person = im.object({ name: 'joe bloggs', age: 34 })
person.mutable()
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:
var person1 = im.object({ name: 'joe bloggs', age: 34 })
var person2 = im.object({ name: 'joe bloggs', age: 34 })
var person3 = im.object({ name: 'joe bloggs', age: 34, sport: 'golf' })
person1.equal(person2)
person3.equal(person2)
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
var inc = function(a){ return a + 1 }
var coordinates = im.object({ x: 1, y: 1 })
coordinates.map(inc).mutable()
var numbers = im.array([1, 2, 3, 4, 5])
numbers.map(inc).mutable()
.forEach
var log = console.log.bind(console)
var person = im.object({ name: 'joe bloggs', age: 34 })
person.map(log)
.filter
var isNum = function(a){ return typeof a === 'number' }
var person = im.object({ name: 'joe bloggs', age: 34 })
person.filter(isNum).mutable()
var alphaNumber = im.array(['a', 1, 'b', 2, 'c', 3])
alphaNumber.filter(isNum).mutable()
.every
var isNum = function(a){ return typeof a === 'number' }
im.object({ name: 'joe bloggs', age: 34 }).every(isNum)
im.object({ x: 1, y: 2 }).every(isNum)
im.array(['a', 1, 'b', 2, 'c', 3]).every(isNum)
im.array([1, 2, 3]).every(isNum)
.some
var isNum = function(a){ return typeof a === 'number' }
im.object({ name: 'joe bloggs', sport: 'golf' }).some(isNum)
im.object({ name: 'joe bloggs', age: 34 }).some(isNum)
im.array(['a', 'b', 'c']).some(isNum)
im.array(['a', 1, 'b', 2, 'c', 3]).every(isNum)
.reduce
var flip = function(coll, val, key){
return coll.assoc(key, val)
}
var coords = im.object({ x: '1', y: '2', z: '3' })
var flippedCoords = coords.reduce(flip, im.object())
flippedCoords.mutable()
var cat = function(a, b){ return a + b }
var letters = im.array(['a', 'b', 'c'])
letters.reduce(cat)
Array Methods
Since arrays are ordered collections, they have some methods of their own, that only make sense in an ordered context:
.reduceRight
var cat = function(a, b){ return a + b }
var letters = im.array(['a', 'b', 'c'])
letters.reduceRight(cat)
.push
var numbersTo3 = im.array([1, 2, 3])
var numbersTo4 = numbersTo3.push(4)
numbersTo4.mutable()
.indexOf
var mixed = im.array([1, 2, 3, im.object({ x: 3 }), { x: 3 }])
mixed.indexOf('a')
mixed.indexOf({ x: 3 })
mixed.indexOf(im.object({ x: 3 }))
mixed.indexOf(3)
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]))
im.isImmutableCollection(Object.freeze({}))