On this page
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.
How to read these docs
In order to better explain what kinds of values the Immutable.js API expects and produces, this documentation is presented in a statically typed dialect of JavaScript (like Flow or TypeScript). You don't need to use these type checking tools in order to use Immutable.js, however becoming familiar with their syntax will help you get a deeper understanding of this API.
A few examples and how to read them.
All methods describe the kinds of data they accept and the kinds of data they return. For example a function which accepts two numbers and returns a number would look like this:
sum(first: number, second: number): number
Sometimes, methods can accept different kinds of data or return different kinds of data, and this is described with a type variable, which is typically in all-caps. For example, a function which always returns the same kind of data it was provided would look like this:
identity<T>(value: T): T
Type variables are defined with classes and referred to in methods. For example, a class that holds onto a value for you might look like this:
class Box<T> {
constructor(value: T)
getValue(): T
}
In order to manipulate Immutable data, methods that we're used to affecting a Collection instead return a new Collection of the same type. The type this
refers to the same kind of class. For example, a List which returns new Lists when you push
a value onto it might look like:
class List<T> {
push(value: T): this
}
Many methods in Immutable.js accept values which implement the JavaScript Iterable protocol, and might appear like Iterable<string>
for something which represents sequence of strings. Typically in JavaScript we use plain Arrays ([]
) when an Iterable is expected, but also all of the Immutable.js collections are iterable themselves!
For example, to get a value deep within a structure of data, we might use getIn
which expects an Iterable
path:
getIn(path: Iterable<string | number>): unknown
To use this method, we could pass an array: data.getIn([ "key", 2 ])
.
Note: All examples are presented in the modern ES2015 version of JavaScript. Use tools like Babel to support older browsers.
For example:
// ES2015
const mappedFoo = foo.map(x => x * x);
// ES5
var mappedFoo = foo.map(function (x) { return x * x; });
API
List
Lists are ordered indexed dense collections, much like a JavaScript Array.
Map
Immutable Map is an unordered Collection.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 add
ed.
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
A record is similar to a JS object, but enforces a specific set of allowed string keys, and has default values.
Record.Factory
A Record.Factory is created by the Record()
function. Record instances are created by passing it some of the accepted values for that Record type:
Seq
Seq
describes a lazy operation, allowing them to efficiently chain use of all the higher-order collection methods (such as map
and filter
) by not creating intermediate collections.
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.
Collection
The Collection
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 Collection methods (such as map
and filter
).
Collection.Keyed
Keyed Collections have discrete keys tied to each value.
Collection.Indexed
Indexed Collections have incrementing numeric keys. They exhibit slightly different behavior than Collection.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 Collections such as indexOf
.
Collection.Set
Set Collections only represent values. They have no associated keys or indices. Duplicate values are possible in the lazy Seq.Set
s, however the concrete Set
Collection does not allow duplicate values.
ValueObject
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 Collection
s as values, equal if the second Collection
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.
isImmutable()
True if maybeImmutable
is an Immutable Collection or Record.
isCollection()
True if maybeCollection
is a Collection, or any of its subclasses.
isKeyed()
True if maybeKeyed
is a Collection.Keyed, or any of its subclasses.
isIndexed()
True if maybeIndexed
is a Collection.Indexed, or any of its subclasses.
isAssociative()
True if maybeAssociative
is either a Keyed or Indexed Collection.
isOrdered()
True if maybeOrdered
is a Collection where iteration order is well defined. True for Collection.Indexed as well as OrderedMap and OrderedSet.
isValueObject()
True if maybeValue
is a JavaScript Object which has both equals()
and hashCode()
methods.
isSeq()
True if maybeSeq
is a Seq.
isList()
True if maybeList
is a List.
isMap()
True if maybeMap
is a Map.
isOrderedMap()
True if maybeOrderedMap
is an OrderedMap.
isStack()
True if maybeStack
is a Stack.
isSet()
True if maybeSet
is a Set.
isOrderedSet()
True if maybeOrderedSet
is an OrderedSet.
isRecord()
True if maybeRecord
is a Record.
get()
has()
Returns true if the key is defined in the provided collection.
remove()
set()
update()
getIn()
Returns the value at the provided key path starting at the provided collection, or notSetValue if the key path is not defined.
hasIn()
Returns true if the key path is defined in the provided collection.
removeIn()
Returns a copy of the collection with the value at the key path removed.
setIn()
Returns a copy of the collection with the value at the key path set to the provided value.
updateIn()
merge()
Returns a copy of the collection with the remaining collections merged in.
mergeWith()
Returns a copy of the collection with the remaining collections merged in, calling the merger
function whenever an existing value is encountered.
mergeDeep()
Like merge()
, but when two compatible collections are encountered with the same key, it merges them as well, recursing deeply through the nested data. Two collections are considered to be compatible (and thus will be merged together) if they both fall into one of three categories: keyed (e.g., Map
s, Record
s, and objects), indexed (e.g., List
s and arrays), or set-like (e.g., Set
s). If they fall into separate categories, mergeDeep
will replace the existing collection with the collection being merged in. This behavior can be customized by using mergeDeepWith()
.
mergeDeepWith()
Like mergeDeep()
, but when two non-collections or incompatible collections are encountered at the same key, it uses the merger
function to determine the resulting value. Collections are considered incompatible if they fall into separate categories between keyed, indexed, and set-like.
© 2014–present, Lee Byron and other contributors
Licensed under the 3-clause BSD License.
https://immutable-js.com/docs/v4.2.1/