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 TypeScript syntax. You don't need to write TypeScript in order to use Immutable.js, however becoming familiar with its notation 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 a sequence of strings. Typically in JavaScript we use plain Arrays ([]) when an Iterable is expected, but 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 ]).

Inheritance cheatsheet

The following diagram shows the inheritance relationships between the Immutable.js collections. Click on the image to view it in full size.