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()
Map()
- Read values
- Read deep values
- Change Values
- Change deep values
- Conversion to JavaScript types
- Member
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)
get()
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
map.get("one").title;
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
getIn()
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.size;
set()
map.set("three", { title: "three", value: 3 });
delete()
map.delete("three", { title: "three", value: 3 });
update()
map.update(‘one’, item => '')
clear()
Returns a new Map containing no keys or values.
map.clear();
merge()
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
has
Returns a boolean if it finds the id key
map.has(item.id);
first
Returns the first element of a Map
map.first();
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.
groupBy
Returns the first element of a Map
items.groupBy((item) => {
return todo.completed;
});
Working with Subsets of a Map()
slice()
Returns the last two items of a Map()
slice(<from>, <to>)
items.slice(items.size - 2, todos.size);
takeLast()
Returns the last two items of a Map()
items.takeLast(2);
butLast()
Returns the last item
items.butLast();
rest()
items.rest();
skip()
Returns a Map() skipping the first 5 items
items.skip(5);
skipUntil()
Returns a Map() skipping until it finds the value
items.skipUntil((item) => item.value === 1);
skipWhile()
Returns a Map() up until it finds 1 included.
items.skipWhile((item) => item.value === 1);
Equality Methods
is()
let mapX = Inmutable.Map({ a: 10, b: 20, c: 30 });
let mapY = Inmutable.Map({ a: 10, b: 20, c: 30 });
Immutable.is(mapX, mapY); // true
FromJS
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
List()
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.push(3);
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.push(3);
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
of()
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);
Sequences
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 = sequence.map((num) => {
operations++;
return num * num;
});
operations; // 0
// Now using the sequence
squared.take(10).toArray();
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)
.take(1000);
console.log(squaredOdds.toArray());
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");
seq.take(1000);
console.timeEnd("First Run"); // First Run: 0.577ms
console.time("Second Run");
seq.take(1000);
console.timeEnd("Second Run"); // Second Run: 0.165ms