Immutable data cannot be changed once created, leading to much simpler application development, no defensive copying, and enabling advanced memoization and change detection techniques with simple logic. Persistent data presents a mutative API which does not update the data in-place, but instead always yields new updated data.

  • fromJS(): Deeply converts plain JS objects and arrays to Immutable Maps and Lists. If reviver is not provided, the default behavior will convert Arrays into Lists and Objects into Maps.

List

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

  • List.isList(maybeList): True if the provided value is a List
  • set(index, value): Returns a new List which includes value at index. If index already exists in this List, it will be replaced.
  • get(index): Returns the value associated with the provided key, or notSetValue if the Iterable does not contain this key.
  • set(index, value): Returns a new List which includes value at index. If index already exists in this List, it will be replaced.
  • delete(index): Returns a new List which excludes this index and with a size 1 less than this List. Values at indices above index are shifted down by 1 to fill the position.
  • insert(index, value): Returns a new List with value at index with a size 1 more than this List. Values at indices above index are shifted over by 1.
  • push(...values): Returns a new List with the provided values appended, starting at this List’s size.

Map

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

Docs

  • Map.isMap(maybeMap): True if the provided value is a Map
  • myMap.toJS(): Deeply converts this Iterable to equivalent JS.

  • set(key, value): Returns a new Map also containing the new key, value pair. If an equivalent key already exists in this Map, it will be replaced.

    1
    var newMap = oldMap.set('key', 'value')

  • get(key): Returns the value associated with the provided key, or notSetValue if the Iterable does not contain this key.

  • getIn(): Returns the value found by following a path of keys or indices through nested Iterables.

    1
    2
    3
    4
    getIn(searchKeyPath: Array<any>, notSetValue?: any): any
    const aVotes = vote.getIn(['tally', a], 0);
    const bVotes = vote.getIn(['tally', b], 0);

  • delete(key): Returns a new Map which excludes this key.

  • has(key): True if a key exists within this Iterable, using Immutable.is to determine equality
  • includes(value): True if a value exists within this Iterable, using Immutable.is to determine equality

  • merge(): Returns a new Map resulting from merging the provided Iterables (or JS objects) into this Map.

    1
    2
    3
    4
    var x = Immutable.Map({a: 10, b: 20, c: 30});
    var y = Immutable.Map({b: 40, a: 50, d: 60});
    x.merge(y) // { a: 50, b: 40, c: 30, d: 60 }
    y.merge(x) // { b: 20, a: 10, d: 60, c: 30 }

  • take(amount): Returns a new Iterable of the same type which includes the first amount entries from this Iterable.

  • skip(amount): Returns a new Iterable of the same type which excludes the first amount entries from this Iterable.

  • update(): Returns a new Map having updated the value at this key with the return value of calling updater with the existing value, or notSetValue if the key was not set. If called with only a single argument, updater is called with the Map itself.

    1
    2
    3
    4
    5
    6
    update(updater: (value: Map<K, V>) => Map<K, V>): Map<K, V>
    update(key: K, updater: (value: V) => V): Map<K, V>
    update(key: K, notSetValue: V, updater: (value: V) => V): Map<K, V>
    //Equivalent to:
    map.set(key, updater(map.get(key, notSetValue))).

  • updateIn(): Returns a new Map having applied the updater to the entry found at the keyPath.

    1
    2
    3
    4
    5
    6
    7
    updateIn(keyPath: Array<any>, updater: (value: any) => any): Map<K, V>
    var data = Immutable.fromJS({ a: { b: { c: 10 } } });
    data = data.updateIn(['a', 'b', 'c'], val => val * 2);
    // { a: { b: { c: 20 } } }
    //If the value at the end is missing, initialize it with "0".
    data = data.updateIn(['a', 'b', 'c'], 0,  val => val = myValue);

ImmutableJS Docs