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.

hash()

The hash() function is an important part of how Immutable determines if two values are equivalent and is used to determine how to store those values. Provided with any value, hash() will return a 31-bit integer.

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.

Seq

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

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).

Collection

Collection is the abstract base class for concrete data structures. It cannot be constructed directly.