Nested structures

The collections in Immutable.js are intended to be nested, allowing for deep trees of data, similar to JSON.

fromJS() converts a plain JavaScript tree into nested Immutable collections: objects become Map and arrays become List.

Reading and updating in depth

A few power-tools allow for reading and operating on nested data. The most useful are getIn(), setIn(), updateIn() and mergeDeep(), found on List, Map and OrderedMap.

Each of them takes a key path — an iterable of keys describing where to look in the tree.

mergeDeep() merges a whole subtree in one call, recursing into the nested collections instead of replacing them:

updateIn() applies a function to the value at a key path, and returns a new collection with the result in place. Every level of the tree above it is rebuilt, while everything else is shared with the original:

The value at a key path can itself be a collection, so nested updates compose naturally:

Note that setIn() and updateIn() never mutate the original: nested still holds its initial value after every example above.