Immutable.js (v3.8.2)

Immutable data encourages pure functions (data-in, data-out) and lends itself to much simpler application development and enabling techniques from functional programming such as lazy evaluation.

While designed to bring these powerful functional concepts to JavaScript, it presents an Object-Oriented API familiar to Javascript engineers and closely mirroring that of Array, Map, and Set. It is easy and efficient to convert to and from plain Javascript types.

Note: all examples are presented in ES6. To run in all browsers, they need to be translated to ES3. For example:

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

API

fromJS()

Deeply converts plain JS objects and arrays to Immutable Maps and Lists.

is()

Value equality check with semantics similar to Object.is, but treats Immutable Iterables as values, equal if the second Iterable includes equivalent values.

List

Lists are ordered indexed dense collections, much like a JavaScript Array.

Map

Immutable Map is an unordered Iterable.Keyed of (key, value) pairs with O(log32 N) gets and O(log32 N) persistent sets.

OrderedMap

A type of Map that has the additional guarantee that the iteration order of entries will be the order in which they were set().

Set

A Collection of unique values with O(log32 N) adds and has.

OrderedSet

A type of Set that has the additional guarantee that the iteration order of values will be the order in which they were added.

Stack

Stacks are indexed collections which support very efficient O(1) addition and removal from the front using unshift(v) and shift().

Range()

Returns a Seq.Indexed of numbers from start (inclusive) to end (exclusive), by step, where start defaults to 0, step to 1, and end to infinity. When start is equal to end, returns empty range.

Repeat()

Returns a Seq.Indexed of value repeated times times. When times is not defined, returns an infinite Seq of value.

Record()

Creates a new Class which produces Record instances. A record is similar to a JS object, but enforce a specific set of allowed string keys, and have default values.

Record.Class

Seq

Represents a sequence of values, but may not be backed by a concrete data structure.

Seq.Keyed

Seq which represents key-value pairs.

Seq.Indexed

Seq which represents an ordered indexed list of values.

Seq.Set

Seq which represents a set of values.

Iterable

The Iterable is a set of (key, value) entries which can be iterated, and is the base class for all collections in immutable, allowing them to make use of all the Iterable methods (such as map and filter).

Iterable.Keyed

Keyed Iterables have discrete keys tied to each value.

Iterable.Indexed

Indexed Iterables have incrementing numeric keys. They exhibit slightly different behavior than Iterable.Keyed for some methods in order to better mirror the behavior of JavaScript's Array, and add methods which do not make sense on non-indexed Iterables such as indexOf.

Immutable.js