DOCSEARCHbyAlgolia
Submit Docs

Immutable.js

website·Indexed 35 days ago

https://immutable-js.com/docs

Documentation for Immutable.js versions v3.8.4 and v4.3.9, featuring persistent immutable data structures such as Map, List, OrderedMap, OrderedSet, and Seq. Includes detailed API references for construction, value equality, deep value reading, and conversion to JavaScript types.

Tokens
164.3K
Snippets
1.2K
Records
1.5K
Agent score
70%

What's inside Immutable.js

  1. Overview of Immutable.js Iterable.Set

    v3.8.4

    Iterable.Set represents a collection of values without associated keys or indices. While the concrete Set implementation prohibits duplicate values, Seq.Set (the sequence version of an Iterable.Set) may allow duplicates.

    When using methods like map() or forEach() on an Iterable.Set, the value is provided as both the first and second arguments to the callback function because there are no distinct keys.

    var seq = Seq.Set.of('A', 'B', 'C');
// v (value) and k (key) are the same in Iterable.Set
assert.equal(seq.every((v, k) => v === k), true);

  2. Overview of the Immutable.js Iterable interface

    v3.8.4
    The Iterable is the base class for all collections in Immutable.js. It represents a set of (key, value) entries that can be iterated. All immutable collections inherit from Iterable, allowing them to use common methods like map() and filter(). Note that while an iterable is always iterated in the same order, that order may not always be well-defined (e.g., for Map and Set).

  3. Overview of Immutable.js List

    v4.3.9
    A List is an ordered, indexed, dense collection similar to a JavaScript Array. It is immutable and fully persistent, providing O(log32 N) time complexity for gets and sets, and O(1) for push and pop operations. Unlike JavaScript Arrays, there is no distinction between an 'unset' index and an index set to undefined; forEach visits all indices from 0 to the list's size.

  4. Overview of Immutable.js Map

    v3.8.4

    An Immutable Map is an unordered, persistent collection of (key, value) pairs. It provides O(log32 N) time complexity for both gets and persistent sets. While the iteration order is undefined, it is stable (multiple iterations of the same Map will yield the same order).

    Key characteristics:

    • Keys can be of any type.
    • Key equality is determined using Immutable.is, allowing values like NaN or other Immutable collections to be used as keys.
    • JavaScript objects can be used as keys, but they are evaluated by strict identity (two different objects with the same properties are treated as different keys).
    // Using an Immutable List as a key
Map().set(List.of(1), 'listofone').get(List.of(1)); // 'listofone'

  5. Overview of Immutable.js OrderedSet

    v5
    An OrderedSet is a type of Set that guarantees the iteration order of values matches the order in which they were added. Its iteration behavior is identical to the native ES6 Set. Note that OrderedSet is more memory-intensive than a standard Set, and the add operation has an amortized time complexity of O(log32 N).

  6. Overview of Immutable.js OrderedMap

    v4.3.9
    An OrderedMap is a specialized Map that guarantees the iteration order of entries matches the order in which they were added using set(). Its iteration behavior is consistent with native ES6 Maps and JavaScript Objects. Note that OrderedMap is more memory-intensive and computationally more expensive than a standard Map; the set() operation has an amortized time complexity of O(log32 N) and is not stable.

  7. Overview of Immutable.js Stack

    v5
    A Stack is an indexed collection that supports highly efficient O(1) addition and removal from the front. It is implemented as a singly-linked list. Note that reverse() and reverse traversal methods (like reduceRight or lastIndexOf) are inefficient for this data structure.

  9. Overview of Immutable.js Iterable.Indexed

    v3.8.4
    Iterable.Indexed is a collection of elements with incrementing numeric keys, designed to mirror JavaScript Array behavior. Unlike JS arrays, Iterable.Indexed collections are always dense; indices from 0 to size are always visited during iteration, and unset indices are indistinguishable from undefined indices. All methods on Iterable.Indexed return re-indexed Iterables (starting at 0). To preserve indices as keys, convert the collection to an Iterable.Keyed using toKeyedSeq().

  10. Overview of Immutable.js Seq

    v3.8.4
    The Seq class represents an immutable, lazy sequence of values. Because it is immutable, any mutative method returns a new Seq instance. Because it is lazy, Seq performs the minimum amount of work necessary to respond to a method call, avoiding the creation of intermediate data structures during operation chaining. This makes it highly efficient for processing large or infinite data sets.
    // Lazy evaluation: no work is performed until the value is requested
var oddSquares = Immutable.Seq.of(1,2,3,4,5,6,7,8)
  .filter(x => x % 2)
  .map(x => x * x);

console.log(oddSquares.get(1)); // 9

  11. Overview of Immutable.js core concepts

    v5
    Immutable.js provides data structures that cannot be changed once created. This approach eliminates the need for defensive copying and enables advanced memoization and change detection using simple logic. It encourages the use of pure functions (data-in, data-out) and supports functional programming techniques like lazy evaluation. The library provides an Object-Oriented API that mirrors standard JavaScript Array, Map, and Set, allowing for efficient conversion between immutable structures and plain JavaScript types.

  12. Overview of Collection.Keyed

    v4.3.9
    Keyed Collections in Immutable.js are collections where each value is tied to a discrete key. The default iterator for a Collection.Keyed yields a [K, V] tuple, equivalent to calling the entries() method.