ImmutableJS overview

Immutable library can be useful but documentation is quite tricky to understand. I have just played a little with this library and wanted to share with you some examples.

Written with TypeScript I guess it is why documentation is quite difficult to read first.

API

Documentation use a very generic template syntax.

Generic constructors

Map<K, V>(): Map<K, V> // create a new immutable map
Set<T>(): Set<T>
List<T>(): List<T>
Stack<T>(): Stack<T>
Set<T>(): Set<T>

Ok, it is quite simple, T (for Type) K (for Key) V (for Value) are generic type declaration which will be used by immutable implementation.

Following commonly notation, keep it mind the following type parameter names:

K - Key
V - Value
T - Type
number - Number
… maybe more

Generic methods

Function signature follow this convention:

nameCamelCase(...parameters) : newCurrentImmutableObjToReturn

What I just want to say is that you work on immutable data, so always use your returned value, otherwise…

parameters in documentation are often named for more readability

set(key: K, value: V): Map<K, V>
// will be call this way
// myMap.set('a', 'I am A');
// myMap.set('b', 'I am B');

ES6

Then Immutable embrace ES6 with Classes, Arrow Functions and Modules so it won’t help you to read documentation if you do not know anything about it.

But I am nice, I give you some details :)

Arrow Function

Arrow Function sample extracted from Immutable documentation:

// ES6
foo.map(x => x * x);
// ES3
foo.map(function (x) { return x * x; });

Ok, but let’s see an exemple on an Immutable Map.update() object method :

update(key: K, updater: (value: V) => V): Map<K, V>

OMG, do not worry, difficult part to read is the parameter in parenthesis.

(key: K, updater: (value: V) => V): Map<K, V>

Reminder

(value: V) => V

is equivalent to

function(value) {
  // do something with value
  return value;
}

As explained before key,updater keywords are just there for readability, you do not write it when coding.

Firt param is your map key, second one use an Arrow Function, see it in action:

var value = {
 name: 'julien',
 aka: 'darul75'
};

// create a new map
var myMap = Immutable.Map({});
// add a value, note we play with immutable object, so keep in mind
// to always return and erase old one
// Example:
// myMap = myMap.set('myMapKey', value);

// we gonna update 'aka' attribute value from 'darul75' to 'darul'
var newMyMap = myMap.update('myMapKey', (myMapValue) => {
  myMapValue.aka = 'darul';
  // if map value is also Immutable map it will be
  // myMapValue = myMapValue.set('aka', 'darul');
  return myMapValue;
});

console.log(newMyMap.get('myMapKey'));
// Object {name: "julien", aka: "darul"}

Iterable

Iterating over your collection of data, you might all know what Iterable and Iterator mean.

All collections in Immutable are extending Iterable following common (key, value) pattern.

Iterable<K, V>

Example with native Immutable Map

var value = {
 name: 'julien',
 aka: 'darul75'
};
var myMap = Immutable.Map({});
myMap = myMap.set('myMapKey', value);
var myArrayIterator = Immutable.Iterable(myMap);
// not needed by default as Map implement it by debault
console.log(myArrayIterator.first());
// Object {name: "julien", aka: "darul"}
console.log(myArrayIterator.get('myMapKey'));
// Object {name: "julien", aka: "darul"}

Example with native javascript Array []

Purpose of this example is to get an Iterable obj from a native javascript array.

Then play with all methods available on it

// constructor from documentation
// take an array
Iterable<T>(array: Array<T>): IndexedIterable<T>
// return and IndexIterable obj

in practice

var myArray = [1,2,3];
console.log(Immutable.Iterable.isIterable(myArray)); // false
var myArrayIterator = Immutable.Iterable(myArray);
console.log(Immutable.Iterable.isIterable(myArrayIterator)); // true
console.log(myArrayIterator.first()); // 1
console.log(myArrayIterator.get(2)); // 3

Behind it looks like Seq is used.

KeyPath

What is it ?

A keypath seach for you data according to a path represented by a sum of keys.

“Returns the value found by following a path of keys or indices through nested Iterables.”

Signature

getIn(searchKeyPath: Array<any>, notSetValue?: any): any

Example

var value = {
 name: 'julien',
 aka: 'darul75',
 address: {
  city: 'paris',
  country: 'france'
 }
};
var myMap = Immutable.Map({});
myMap = myMap.set('myMapKey', Immutable.fromJS(value)); // convert plain object to an Immutable Map
console.log(myMap.getIn(['address', 'city']));
// 'paris'

Many functions can be used as setIn(), deleteIn(), updateIn(), mergeIn()….

You can also edit this article by pressing edit button.

Just for fun

Tags: ImmutableJS Javascript

Written on hey July 6, 2015