Background Cover
October 22, 2016
7 min read

Immutable collections for JavaScript: ImmutableJS

jsjavascript data structures

InmutableJS is a library from Facebook that provides a series of inmutable data structures. Always immutable. The reference to them can change but the data inside of them cannot. This means you can build predictable and reliable state models. This makes it easier to manage your application state.

More here: Immutable.js More about Immutable Data and React React.js Conf 2015 - Immutable Data and React - YouTube

Why ImmutableJS?

  • Immutable Data is faster
  • Tracking mutation and maintaining state is difficult
  • Encourages you to think differently about how data flows through your application
  • Less error prone
  • Simplified development
  • Predictable
  • Performance enhancements, Optimizations
  • Mutation tracking

Getting Started

ImmutableJS API is quite big. We will try to cover the basics and a bit more to show its power.

ImmutableJS provides many Persistent Immutable data structures including: List(), Stack(), Map(), OrderedMap(), Set(), OrderedSet() and Record().

We will cover the most common data structures. Map() , List() and Record() and also we will describe the behavior of Seq() with Range()



Creates a new Immutable Map. An Object graph. Map - Immutable.js

const data = {
	‘one’: {
		title: ‘One’,
		value: 1
	'two': {
		title: 'Two',
		value: 2

let map = Inmutable.Map(data)


Returns the value associated with the provided key, Since inmutable data cannot be mutated they create a new reference to the new data. get() - Immutable.js

let obj = { 1: "one" };
Object.keys(obj); // [ "1" ]
obj["1"]; // "one"
obj[1]; // "one"

let map = Map(obj);
map.get("1"); // "one"
map.get(1); // undefined


To get data from a deeply nested structure. getIn() - Immutable.js

With a Map()

let map = Inmutable.Map({
	title: 'Todo One',
	text: 'Do todo'
	category: {
		title: 'Some category',
		order: 1

map.getIn(['category', 'title']) // 'Some Category'

length - size

To get the size of a Map() or a List()



map.set("three", { title: "three", value: 3 });


map.delete("three", { title: "three", value: 3 });


map.update(‘one’, item => '')


Returns a new Map containing no keys or values.



Returns a new Map resulting from merging the provided iterables.

let mapX = Inmutable.Map({ a: 10, b: 20, c: 30 });
let mapY = Inmutable.Map({ a: 10, b: 20, c: 30 });

mapX.merge(mapY); // { a: 50, b: 40, c: 30, d: 60 }

Querying Methods


Returns a boolean if it finds the id key



Returns the first element of a Map


Iteration Methods

We can use methods like .filter, .map, .reduce . However it’s not recommended to use .forEach since it can mutate the data producing side effects.


Returns the first element of a Map

items.groupBy((item) => {
  return todo.completed;

Working with Subsets of a Map()


Returns the last two items of a Map() slice(<from>, <to>)

items.slice(items.size - 2, todos.size);


Returns the last two items of a Map()



Returns the last item




Returns a Map() skipping the first 5 items



Returns a Map() skipping until it finds the value

items.skipUntil((item) => item.value === 1);


Returns a Map() up until it finds 1 included.

items.skipWhile((item) => item.value === 1);

Equality Methods


let mapX = Inmutable.Map({ a: 10, b: 20, c: 30 });
let mapY = Inmutable.Map({ a: 10, b: 20, c: 30 });, mapY); // true


Object to Map()

Creates deeply nested Map() from a plain Javascript Object

let object = { a: 10, b: 20, c: 30 };

Immutable.fromJS(object); // Map()

Array to List()

Creates List() from a JS Array

let array = [10, 20, 30];

Immutable.fromJS(object); // List()

Usage of the reviver function

The reviver function takes a key and a value. Converting JS to Map() or List()

let array = [10, 20, 30];

Immutable.fromJS(array, (key, value) => {
  return value.toMap();
}); // Map()

Note: the getIn will be index based instead of object based if it comes from an array


Most of the Map() methods can be used with List() But there are some differences.

Differences between the Immutable Map() and List()

List() have the same methods that a JS Array has. But instead of mutating the array it returns a new one.

Usually we wouldn’t use the push method in immutable data structures but with Immutable.List()s push methods are safe to be used.

let list = Immutable.List();
list.toArray(); // [3]

get() and getIn()

The get method with Map() is key based and with List() is index based.

// get()
let list = Immutable.List();
list.get(0); // 3

let map = Immutable.Map();
list.set("active", true);
list.get("active"); // true

// getIn()
let map = Inmutable.List([10, 20, 30, [40, 50]]);
map.getIn([3, 1]); // 50


We can create a List() by using the of method

const items = [];
const list = Immutable.List.of("red", "green", "blue");

Using the spread operator:

const items = ["red", "green", "blue"];
const list = Immutable.List.of(...items);


Represents a sequence of values. Seq() - Immutable.js

  • Sequences are immutable — Once a sequence is created, it cannot be changed.
  • Sequences are Lazy

Creating sequences with of()

let range = [0, 1, 2 ... 999]
let sequence = Immutable.Seq.of(...range)

For Example: the following performs no work, because the resulting of the sequence values are never iterated:

let operations = 0;

let squared = => {
  return num * num;
operations; // 0

// Now using the sequence
operations; // 10

Once the sequence is used, it performs only the work necessary. It will return it only when you ask for them.

This is really powerful because it doesn’t produce an overflow with infinite an infinite range.

let squaredRange = Immutable.Range(1, Infinity);

squaredRange.size; // Infinity

first1000squared = squaredRange.take(1000).map((n) => n * n);

first1000squared.size; // 1000

Seq() allows for the efficient chaining of operations

let squaredOdds = Immutable.Range(0, Infinity)
  .filter((n) => n % 2 !== 0)
  .map((n) => n * n)


You can fin this example here: Sequences - JS Bin

[image:34A1BA28-D9BD-4306-89EE-A28C340AFADA-227-00001B121A3513A7/Screen Shot 2016-12-22 at 8.23.33 AM.png]

Memoization with Immutable JS

Immutable JS provides advanced memoization.

const seq = Immutable.Range(1, Infinity).map((n) => ({
  value: n,

console.time("First Run");
console.timeEnd("First Run"); // First Run: 0.577ms

console.time("Second Run");
console.timeEnd("Second Run"); // Second Run: 0.165ms

Play with Immutable JS

JS Bin - Collaborative JavaScript Debugging