Want to take your software engineering career to the next level? Join the mailing list for career tips & advice Click here


Immutable persistent data collections for Javascript which increase efficiency and simplicity.

Star full 4f7b624809470f25b6493d5a7b30d9b9cb905931146e785d67c86ef0c205a402Star full 4f7b624809470f25b6493d5a7b30d9b9cb905931146e785d67c86ef0c205a402Star full 4f7b624809470f25b6493d5a7b30d9b9cb905931146e785d67c86ef0c205a402Star full 4f7b624809470f25b6493d5a7b30d9b9cb905931146e785d67c86ef0c205a402Star full 4f7b624809470f25b6493d5a7b30d9b9cb905931146e785d67c86ef0c205a402 (1 ratings)
Rated 5.0 out of 5
Subscribe to updates I use immutable-js

Statistics on immutable-js

Number of watchers on Github 22823
Number of open issues 86
Average time to close an issue 11 days
Main language JavaScript
Average time to merge a PR 4 days
Open pull requests 134+
Closed pull requests 40+
Last commit over 2 years ago
Repo Created almost 6 years ago
Repo Last Updated about 2 years ago
Size 20.1 MB
Homepage http://facebook.g...
Organization / Authorfacebook
Latest Releasev3.8.2
Page Updated
Do you use immutable-js? Leave a review!
View open issues (86)
View immutable-js activity
View on github
Fresh, new opensource launches ๐Ÿš€๐Ÿš€๐Ÿš€
Software engineers: It's time to get promoted. Starting NOW! Subscribe to my mailing list and I will equip you with tools, tips and actionable advice to grow in your career.
Evaluating immutable-js for your project? Score Explanation
Commits Score (?)
Issues & PR Score (?)
What people are saying about immutable-js Leave a review
Efficient, simple to use.

Immutable collections for JavaScript

Build Status

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.

Immutable.js provides many Persistent Immutable data structures including: List, Stack, Map, OrderedMap, Set, OrderedSet and Record.

These data structures are highly efficient on modern JavaScript VMs by using structural sharing via hash maps tries and vector tries as popularized by Clojure and Scala, minimizing the need to copy or cache data.

Immutable.js also provides a lazy Seq, allowing efficient chaining of collection methods like map and filter without creating intermediate representations. Create some Seq with Range and Repeat.

Want to hear more? Watch the presentation about Immutable.js:

Getting started

Install immutable using npm.

npm install immutable

Then require it into any module.

const { Map } = require('immutable')
const map1 = Map({ a: 1, b: 2, c: 3 })
const map2 = map1.set('b', 50)
map1.get('b') + " vs. " + map2.get('b') // 2 vs. 50


Immutable.js has no dependencies, which makes it predictable to include in a Browser.

It's highly recommended to use a module bundler like webpack, rollup, or browserify. The immutable npm module works without any additional consideration. All examples throughout the documentation will assume use of this kind of tool.

Alternatively, Immutable.js may be directly included as a script tag. Download or link to a CDN such as CDNJS or jsDelivr.

Use a script tag to directly add Immutable to the global scope:

<script src="immutable.min.js"></script>
  var map1 = Immutable.Map({a:1, b:2, c:3});
  var map2 = map1.set('b', 50);
  map1.get('b'); // 2
  map2.get('b'); // 50

Or use an AMD-style loader (such as RequireJS):

require(['./immutable.min.js'], function (Immutable) {
  var map1 = Immutable.Map({a:1, b:2, c:3});
  var map2 = map1.set('b', 50);
  map1.get('b'); // 2
  map2.get('b'); // 50

Flow & TypeScript

Use these Immutable collections and sequences as you would use native collections in your Flowtype or TypeScript programs while still taking advantage of type generics, error detection, and auto-complete in your IDE.

Installing immutable via npm brings with it type definitions for Flow (v0.55.0 or higher) and TypeScript (v2.1.0 or higher), so you shouldn't need to do anything at all!

Using TypeScript with Immutable.js v4

Immutable.js type definitions embrace ES2015. While Immutable.js itself supports legacy browsers and environments, its type definitions require TypeScript's 2015 lib. Include either "target": "es2015" or "lib": "es2015" in your tsconfig.json, or provide --target es2015 or --lib es2015 to the tsc command.

const { Map } = require("immutable");
const map1 = Map({ a: 1, b: 2, c: 3 });
const map2 = map1.set('b', 50);
map1.get('b') + " vs. " + map2.get('b') // 2 vs. 50

Using TypeScript with Immutable.js v3 and earlier:

Previous versions of Immutable.js include a reference file which you can include via relative path to the type definitions at the top of your file.

///<reference path='./node_modules/immutable/dist/immutable.d.ts'/>
import Immutable from require('immutable');
var map1: Immutable.Map<string, number>;
map1 = Immutable.Map({a:1, b:2, c:3});
var map2 = map1.set('b', 50);
map1.get('b'); // 2
map2.get('b'); // 50

The case for Immutability

Much of what makes application development difficult is tracking mutation and maintaining state. Developing with immutable data encourages you to think differently about how data flows through your application.

Subscribing to data events throughout your application creates a huge overhead of book-keeping which can hurt performance, sometimes dramatically, and creates opportunities for areas of your application to get out of sync with each other due to easy to make programmer error. Since immutable data never changes, subscribing to changes throughout the model is a dead-end and new data can only ever be passed from above.

This model of data flow aligns well with the architecture of React and especially well with an application designed using the ideas of Flux.

When data is passed from above rather than being subscribed to, and you're only interested in doing work when something has changed, you can use equality.

Immutable collections should be treated as values rather than objects. While objects represent some thing which could change over time, a value represents the state of that thing at a particular instance of time. This principle is most important to understanding the appropriate use of immutable data. In order to treat Immutable.js collections as values, it's important to use the Immutable.is() function or .equals() method to determine value equality instead of the === operator which determines object reference identity.

const { Map } = require('immutable')
const map1 = Map( {a: 1, b: 2, c: 3 })
const map2 = map1.set('b', 2)
assert.equal(map1, map2) // uses map1.equals
assert.strictEqual(map1, map2) // uses ===
const map3 = map1.set('b', 50)
assert.notEqual(map1, map3) // uses map1.equals

Note: As a performance optimization Immutable.js attempts to return the existing collection when an operation would result in an identical collection, allowing for using === reference equality to determine if something definitely has not changed. This can be extremely useful when used within a memoization function which would prefer to re-run the function if a deeper equality check could potentially be more costly. The === equality check is also used internally by Immutable.is and .equals() as a performance optimization.

If an object is immutable, it can be copied simply by making another reference to it instead of copying the entire object. Because a reference is much smaller than the object itself, this results in memory savings and a potential boost in execution speed for programs which rely on copies (such as an undo-stack).

const { Map } = require('immutable')
const map1 = Map({ a: 1, b: 2, c: 3 })
const clone = map1;

JavaScript-first API

While Immutable.js is inspired by Clojure, Scala, Haskell and other functional programming environments, it's designed to bring these powerful concepts to JavaScript, and therefore has an Object-Oriented API that closely mirrors that of ES2015 Array, Map, and Set.

The difference for the immutable collections is that methods which would mutate the collection, like push, set, unshift or splice, instead return a new immutable collection. Methods which return new arrays, like slice or concat, instead return new immutable collections.

const { List } = require('immutable')
const list1 = List([ 1, 2 ]);
const list2 = list1.push(3, 4, 5);
const list3 = list2.unshift(0);
const list4 = list1.concat(list2, list3);
assert.equal(list1.size, 2);
assert.equal(list2.size, 5);
assert.equal(list3.size, 6);
assert.equal(list4.size, 13);
assert.equal(list4.get(0), 1);

Almost all of the methods on Array will be found in similar form on Immutable.List, those of Map found on Immutable.Map, and those of Set found on Immutable.Set, including collection operations like forEach() and map().

const { Map } = require('immutable')
const alpha = Map({ a: 1, b: 2, c: 3, d: 4 });
alpha.map((v, k) => k.toUpperCase()).join();
// 'A,B,C,D'

Convert from raw JavaScript objects and arrays.

Designed to inter-operate with your existing JavaScript, Immutable.js accepts plain JavaScript Arrays and Objects anywhere a method expects an Collection.

const { Map, List } = require('immutable')
const map1 = Map({ a: 1, b: 2, c: 3, d: 4 })
const map2 = Map({ c: 10, a: 20, t: 30 })
const obj = { d: 100, o: 200, g: 300 }
const map3 = map1.merge(map2, obj);
// Map { a: 20, b: 2, c: 10, d: 100, t: 30, o: 200, g: 300 }
const list1 = List([ 1, 2, 3 ])
const list2 = List([ 4, 5, 6 ])
const array = [ 7, 8, 9 ]
const list3 = list1.concat(list2, array)
// List [ 1, 2, 3, 4, 5, 6, 7, 8, 9 ]

This is possible because Immutable.js can treat any JavaScript Array or Object as a Collection. You can take advantage of this in order to get sophisticated collection methods on JavaScript Objects, which otherwise have a very sparse native API. Because Seq evaluates lazily and does not cache intermediate results, these operations can be extremely efficient.

const { Seq } = require('immutable')
const myObject = { a: 1, b: 2, c: 3 }
Seq(myObject).map(x => x * x).toObject();
// { a: 1, b: 4, c: 9 }

Keep in mind, when using JS objects to construct Immutable Maps, that JavaScript Object properties are always strings, even if written in a quote-less shorthand, while Immutable Maps accept keys of any type.

const { fromJS } = require('immutable')

const obj = { 1: "one" }
Object.keys(obj) // [ "1" ]
assert.equal(obj["1"], obj[1])   // "one" === "one"

const map = fromJS(obj)
assert.notEqual(map.get("1"), map.get(1)) // "one" !== undefined

Property access for JavaScript Objects first converts the key to a string, but since Immutable Map keys can be of any type the argument to get() is not altered.

Converts back to raw JavaScript objects.

All Immutable.js Collections can be converted to plain JavaScript Arrays and Objects shallowly with toArray() and toObject() or deeply with toJS(). All Immutable Collections also implement toJSON() allowing them to be passed to JSON.stringify directly.

const { Map, List } = require('immutable')
const deep = Map({ a: 1, b: 2, c: List([ 3, 4, 5 ]) })
console.log(deep.toObject()) // { a: 1, b: 2, c: List [ 3, 4, 5 ] }
console.log(deep.toArray()) // [ 1, 2, List [ 3, 4, 5 ] ]
console.log(deep.toJS()) // { a: 1, b: 2, c: [ 3, 4, 5 ] }
JSON.stringify(deep) // '{"a":1,"b":2,"c":[3,4,5]}'

Embraces ES2015

Immutable.js supports all JavaScript environments, including legacy browsers (even IE8). However it also takes advantage of features added to JavaScript in ES2015, the latest standard version of JavaScript, including Iterators, Arrow Functions, Classes, and Modules. It's inspired by the native Map and Set collections added to ES2015.

All examples in the Documentation are presented in ES2015. To run in all browsers, they need to be translated to ES5.

// ES2015
const mapped = foo.map(x => x * x);
// ES5
var mapped = foo.map(function (x) { return x * x; });

All Immutable.js collections are Iterable, which allows them to be used anywhere an Iterable is expected, such as when spreading into an Array.

const { List } = require('immutable')
const aList = List([ 1, 2, 3 ])
const anArray = [ 0, ...aList, 4, 5 ] // [ 0, 1, 2, 3, 4, 5 ]

Note: A Collection is always iterated in the same order, however that order may not always be well defined, as is the case for the Map and Set.

Nested Structures

The collections in Immutable.js are intended to be nested, allowing for deep trees of data, similar to JSON.

const { fromJS } = require('immutable')
const nested = fromJS({ a: { b: { c: [ 3, 4, 5 ] } } })
// Map { a: Map { b: Map { c: List [ 3, 4, 5 ] } } }

A few power-tools allow for reading and operating on nested data. The most useful are mergeDeep, getIn, setIn, and updateIn, found on List, Map and OrderedMap.

const { fromJS } = require('immutable')
const nested = fromJS({ a: { b: { c: [ 3, 4, 5 ] } } })

const nested2 = nested.mergeDeep({ a: { b: { d: 6 } } })
// Map { a: Map { b: Map { c: List [ 3, 4, 5 ], d: 6 } } }

console.log(nested2.getIn([ 'a', 'b', 'd' ])) // 6

const nested3 = nested2.updateIn([ 'a', 'b', 'd' ], value => value + 1)
// Map { a: Map { b: Map { c: List [ 3, 4, 5 ], d: 7 } } }

const nested4 = nested3.updateIn([ 'a', 'b', 'c' ], list => list.push(6))
// Map { a: Map { b: Map { c: List [ 3, 4, 5, 6 ], d: 7 } } }

Equality treats Collections as Values

Immutable.js collections are treated as pure data values. Two immutable collections are considered value equal (via .equals() or is()) if they represent the same collection of values. This differs from JavaScript's typical reference equal (via === or ==) for Objects and Arrays which only determines if two variables represent references to the same object instance.

Consider the example below where two identical Map instances are not reference equal but are value equal.

// First consider:
const obj1 = { a: 1, b: 2, c: 3 }
const obj2 = { a: 1, b: 2, c: 3 }
obj1 !== obj2 // two different instances are always not equal with ===

const { Map, is } = require('immutable')
const map1 = Map({ a: 1, b: 2, c: 3 })
const map2 = Map({ a: 1, b: 2, c: 3 })
map1 !== map2 // two different instances are not reference-equal
map1.equals(map2) // but are value-equal if they have the same values
is(map1, map2) // alternatively can use the is() function

Value equality allows Immutable.js collections to be used as keys in Maps or values in Sets, and retrieved with different but equivalent collections:

const { Map, Set } = require('immutable')
const map1 = Map({ a: 1, b: 2, c: 3 })
const map2 = Map({ a: 1, b: 2, c: 3 })
const set = Set().add(map1)
set.has(map2) // true because these are value-equal

Note: is() uses the same measure of equality as Object.is for scalar strings and numbers, but uses value equality for Immutable collections, determining if both are immutable and all keys and values are equal using the same measure of equality.

Performance tradeoffs

While value equality is useful in many circumstances, it has different performance characteristics than reference equality. Understanding these tradeoffs may help you decide which to use in each case, especially when used to memoize some operation.

When comparing two collections, value equality may require considering every item in each collection, on an O(N) time complexity. For large collections of values, this could become a costly operation. Though if the two are not equal and hardly similar, the inequality is determined very quickly. In contrast, when comparing two collections with reference equality, only the initial references to memory need to be compared which is not based on the size of the collections, which has an O(1) time complexity. Checking reference equality is always very fast, however just because two collections are not reference-equal does not rule out the possibility that they may be value-equal.

Return self on no-op optimization

When possible, Immutable.js avoids creating new objects for updates where no change in value occurred, to allow for efficient reference equality checking to quickly determine if no change occurred.

const { Map } = require('immutable')
const originalMap = Map({ a: 1, b: 2, c: 3 })
const updatedMap = originalMap.set('b', 2)
updatedMap === originalMap // No-op .set() returned the original reference.

However updates which do result in a change will return a new reference. Each of these operations occur independently, so two similar updates will not return the same reference:

const { Map } = require('immutable')
const originalMap = Map({ a: 1, b: 2, c: 3 })
const updatedMap = originalMap.set('b', 1000)
// New instance, leaving the original immutable.
updatedMap !== originalMap
const anotherUpdatedMap = originalMap.set('b', 1000)
// Despite both the results of the same operation, each created a new reference.
anotherUpdatedMap !== updatedMap
// However the two are value equal.

Batching Mutations

If a tree falls in the woods, does it make a sound?

If a pure function mutates some local data in order to produce an immutable return value, is that ok?

Rich Hickey, Clojure

Applying a mutation to create a new immutable object results in some overhead, which can add up to a minor performance penalty. If you need to apply a series of mutations locally before returning, Immutable.js gives you the ability to create a temporary mutable (transient) copy of a collection and apply a batch of mutations in a performant manner by using withMutations. In fact, this is exactly how Immutable.js applies complex mutations itself.

As an example, building list2 results in the creation of 1, not 3, new immutable Lists.

const { List } = require('immutable')
const list1 = List([ 1, 2, 3 ]);
const list2 = list1.withMutations(function (list) {
assert.equal(list1.size, 3);
assert.equal(list2.size, 6);

Note: Immutable.js also provides asMutable and asImmutable, but only encourages their use when withMutations will not suffice. Use caution to not return a mutable copy, which could result in undesired behavior.

Important!: Only a select few methods can be used in withMutations including set, push and pop. These methods can be applied directly against a persistent data-structure where other methods like map, filter, sort, and splice will always return new immutable data-structures and never mutate a mutable collection.

Lazy 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 is immutable Once a Seq is created, it cannot be changed, appended to, rearranged or otherwise modified. Instead, any mutative method called on a Seq will return a new Seq.

Seq is lazy Seq does as little work as necessary to respond to any method call. Values are often created during iteration, including implicit iteration when reducing or converting to a concrete data structure such as a List or JavaScript Array.

For example, the following performs no work, because the resulting Seq's values are never iterated:

const { Seq } = require('immutable')
const oddSquares = Seq([ 1, 2, 3, 4, 5, 6, 7, 8 ])
  .filter(x => x % 2 !== 0)
  .map(x => x * x)

Once the Seq is used, it performs only the work necessary. In this example, no intermediate arrays are ever created, filter is called three times, and map is only called once:

oddSquares.get(1); // 9

Any collection can be converted to a lazy Seq with Seq().

const { Map } = require('immutable')
const map = Map({ a: 1, b: 2, c: 3 }
const lazySeq = Seq(map)

Seq allows for the efficient chaining of operations, allowing for the expression of logic that can otherwise be very tedious:

  .map(key => key.toUpperCase())
// Seq { A: 1, B: 1, C: 1 }

As well as expressing logic that would otherwise seem memory or time limited, for example Range is a special kind of Lazy sequence.

const { Range } = require('immutable')
Range(1, Infinity)
  .map(n => -n)
  .filter(n => n % 2 === 0)
  .reduce((r, n) => r * n, 1)
// 1006008


Read the docs and eat your vegetables.

Docs are automatically generated from Immutable.d.ts. Please contribute!

Also, don't miss the Wiki which contains articles on specific topics. Can't find something? Open an issue.


If you are using the Chai Assertion Library, Chai Immutable provides a set of assertions to use against Immutable.js collections.


Use Github issues for requests.

We actively welcome pull requests, learn how to contribute.


Changes are tracked as Github releases.


Phil Bagwell, for his inspiration and research in persistent data structures.

Hugh Jackson, for providing the npm package name. If you're looking for his unsupported package, see this repository.


Immutable.js is MIT-licensed.

immutable-js open issues Ask a question     (View All Issues)
  • over 3 years Map#setIn overwrites nested Maps when key in keyPath is a Number
  • over 3 years shallowEqual should return true for two identical immutable-objects
  • over 3 years Open up immutable.js to more contributors
  • over 3 years Mori's zipmap - is there an equivalent?
  • over 3 years Iterator missing in type definitions
  • over 3 years Map.set: Wierd behavior when the first argument is an array
  • over 3 years Node 6+ conversion of anonymous objects
  • over 3 years Record flow declaration does not follow Map
  • over 3 years Concerning the `size` member
  • over 3 years Seq methods problem. Returns new object
  • over 3 years Repetitive code to check for null/undefined Immutable objects
  • over 3 years A 'move' function
  • over 3 years Can we strengthen the return type of Record constructor?
  • over 3 years flow: Map#equals incompatible with Map?
  • over 3 years misreference to this in equals function
  • over 3 years 1000
  • over 3 years Immutable.Record keys not enforced consistently on initialization and set
  • over 3 years Update doc for updateIn() to explain usages mentioned in issue responses
  • over 3 years Documentation Nomenclature
  • over 3 years Flow: static `Map.of` constructor not included in flow definition
  • over 3 years Make reduceRight lazy
  • over 3 years Flow: OrderedMap is typed as a regular Map
  • over 3 years Immutable.Set does not correctly filter duplicates using `.equals` past set size of 8
  • over 3 years Flow: single method used twice in chain & type of values at different keys / keypaths
  • over 3 years Flow: dynamic type tests & Set.isSet
  • over 3 years map.mergeIn converts Record to Map
  • over 3 years `.flatten` behaves differently on a List of 1 Set vs a List of 2 Sets
  • over 3 years get() and getIn() return type in flow definition is not correct
  • over 3 years "_name" is not usable as a key in Record classes, and it is not documented
  • over 3 years Record constructor does not ignore keys with undefined values
immutable-js open pull requests (View All Pulls)
  • Added caveat to ES6 iterable protocols
  • fix broken link for immutable.min.js
  • Add eslintrc file
  • Add typings to package.json. Fixes #734
  • Documentation: fix reference to evenSquares in Seq
  • Make cursor typescript definition accessible from other ambient external modules
  • Use Object.defineProperty in .toObject
  • Fix toOrderedMap and toOrderedSet method definitions
  • Fixed Range.toString step
  • Minor grammar improvement: โ€˜โ€ฆregardless of ifโ€ฆโ€™ --> โ€˜โ€ฆregardless of whetherโ€ฆโ€™
  • Cursor: adding function to be able to easily identify an object as a cursor
  • Inheritance
  • Using `typings` in `package.json`
  • Remove homogeneous collection methods from Record Fixes #505
  • Add subtract method to Immutable.Map
  • Make it obvious that a Record is a Map
  • Global type definition fixes
  • Prefer explicit string conversion
  • Document usage of Immutable.is() in docs for Iterable.includes and Iterable.has
  • Add subtract function for Maps
  • change findIndex in Lists default value
  • Add ability to group cursor operations
  • added method keyPath to Cursor
  • Add transducer protocol to Immutable Data Structures
  • Add a link to chai-immutable for testing purposes
  • Update `bundle` task to build each immutable class individually.
  • Remove .apply in favor of ES6 spreads.
  • Fix isPlainObj function for objects from different context
  • fromJS: should return the same result if used with or withour converter
  • get set intersect working after add or union in withMutations
  • Support typings in package.json by auto-generating immutable-nonambieโ€ฆ
  • Type definitions for use with Flow
  • add test for calling toJS on results of entrySeq (see #803)
  • Fix links
  • add keyPath to merger function in mergeDeepWith
  • Add function for intersecting an unknown number of sets
  • Implementation of Record Lists
  • Implement sub-record construction / update preserving record types
  • Update index.html
  • Iterable.findEntry and Iterable.findLastEntry now respect notSetValue argument #676
  • Fix flow nullable type definitions
  • New test for a possible bug with the 'map' function of the Stack
  • added an example for the groupBy method
  • Fix for a hundred typescript warnings
  • Use latest version of Immutable in docs
  • Deprecate the use of map/fiter/reduce (see #505)
  • Fix toOrderedMap, toOrderedSet Flow annotations
  • Update Immutable example console version to 3.8.1
  • Rebuild and reload typedefs in dev server on change
  • Modernification: using Mocha for tests
  • Uncomment types for Record, fix for .equals
  • Added a few ES6 examples to docs
  • Website fixup: don't overlap the footer with sidebar
  • Updated flow types
  • Update README.md Relative Links with Absolute URLs
  • WIP: Flow type declarations test
  • link build badge to master branch
  • Nit: Fix License and Patent links for gh-pages
  • fix #852 footer is behind sidebar and sidebar is cutoff on short pages
  • Update Immutable.d.ts
  • Test for the possible bug with the 'map' function of the Stack
  • Removed additional 'the' in comments
  • Fix capitalization of GitHub in docs header
  • ignore JetBrains WebStorm IDE config folder
  • deliver #825 add Map::deleteAll for removing multiple keys from a map
  • Ensure 'Example' header shows for method documentation that end with examples
  • Typescript typings. Use polymirphic this.
  • Typescript typings. Add overloads for `map` method to all classes.
  • Improves default sorting comparator when undefined values are present.
  • Better typings for constructors of empty containers.
  • Update Immutable.d.ts to support TypeScript 2.0
  • Make the documentation sidebar position fixed.
  • Use polymorphic 'this' return types for Map methods
  • Make `isXXX` functions guard functions.
  • Add [Symbol.iterator] signature to `Iterable.Keyed`, `Iterable.Indexd` & `Iterable.Set`.
  • Overloads for concat
  • Adding a default export to the flow definition file
  • Fix minor mistake
  • Update README.md
  • Efficient trie diff
  • minor fix to README
  • Add support for `Iterable.splice(n, Infinity)`
  • TypeScript typings: fix incorrect undefined
  • Update Record Flow Type Definition
  • Add Default Export to Flow Type definitions
  • Update README.md
  • [Flow]: Add JS objects to Map.mergeIn & Map.mergeDeepIn
  • fixed 'memorization' typo
  • Add "static" to flow type for OrderedSet<t>
  • Add named exports
  • Custom comparator
  • export hash function
  • Build with the changes from pull request 1027
  • Add missing characters to end of sentence in documentation
  • Add '| undefined' to TypeScript definitions, which can return undefined
  • fix for typescript error
  • Make header nav links dark gray; increase contrast for usability
  • Contains fix for error during equals check on Record with undefined or null
  • Bundle an es module
  • Implement the transformer protocol (transducers)
  • [WIP] Implement dtslint
  • Make fromJS() doc more consistent with code
  • Implement zipAll (Issue #458)
  • expect setting Record property to throw
  • Flow: Record: Fix created class types
  • Add safe refs for no-op 'map' for List and Map
  • Add back deleteIn() and removeIn() to Record
  • Add failing test for power-of-2 hashes
  • Deprecate getIn null throwing
  • Change the has method of Record to be a type guard
  • Fix genTypeDef for MappedType to make Record documentation work
  • Fix to issue #1220 - exception thrown when iterating the result of reโ€ฆ
  • Fix typo: change 'hiearchy' to 'hierarchy'
  • Fix โ€œGithubโ€ typos on Immutable.js website
  • Improve Typescript support for Record
  • add "& T" to some places where it's missing in RecordInstance
  • Make notSetValue optional for typed Records
  • Fix runnable examples for Map.getIn
  • Fix typo 'ofters' -> 'offers'
  • Add safe refs for no-op 'map' for List and Map
  • Solves Record.get() issue. Second parameter notSetValue made optional
  • use default path prefix while loading
  • Fixing some minor typos
  • Fix typo in Record documentation
  • revert export type of RecordInstance
  • Fix README typo
  • fromJS doc should reference value.toMap() instead of value.Map()
  • Fix minor docs typos for Immutable.merge and Immutable.mergeWith
  • Fix some typos in the README
  • Adds support for symbols as keys in Maps.
  • Fix typo
  • fix: fix typo in docs. ES3 -> ES5
  • Documentation: correct the default reviver
  • Hashing functions as objects
immutable-js questions on Stackoverflow (View All Questions)
  • How to use Immutable JS with typed ES6 classes?
  • Failed to compare Immutable-js objects
  • How in immutable js i can each in map method?
  • How do I get a specific object from an immutable js map by value?
  • React merge immutable array of objects using React Immutability helpers or Immutable js
  • Immutable js Map population
  • Immutable JS lazy Seq chained method
  • Immutable JS compare nested structures
  • Using PropTypes when immutable-js in react-js
  • How do I make a custom immutable type using facebook/immutable-js?
  • Immutable-JS: Merge a List of Maps by key
  • Searching an immutable JS Map
  • Immutable JS - Convert List to Map
  • How do I import immutable js into angular 2 (alpha)?
  • Wield scope in reflux and immutable js ES6 webpack chrome
  • Immutable-js: Best way to use referential equality, when searching in List
immutable-js list of languages used
immutable-js latest release notes


  • Improved typescript definitions for new functional API (#1395)
  • Improved flow types for Record setIn()/getIn() key-paths. (#1399)
  • Improved flow types for functional merge() definitions. (#1400)


  • list.concat() now has a slightly more efficient implementation and map.concat() is an alias for map.merge(). (#1373)

In rare cases, this may affect use of map.concat() which expected slightly different behavior from map.merge().

  • isImmutable() now returns true for collections currently within a withMutations() call. (#1374)

Previously, isImmutable() did double-duty of both determining if a value was a Collection or Record from this library as well as if it was outside a withMutations() call. This latter case caused confusion and was rarely used.

  • Plain Objects and Arrays are no longer considered opaque values (#1369)

This changes the behavior of a few common methods with respect to plain Objects and Arrays where these were previously considered opaque to merge() and setIn(), they now are treated as collections and can be merged into and updated (persistently). This offers an exciting alternative to small Lists and Records.

  • No longer use value-equality within merge() (#1391)

This rectifies an inconsistent behavior between x.merge(y) and x.mergeDeep(y) where merge would use === on leaf values to determine return-self optimizations, while mergeDeep would use is(). This improves consistency across the library and avoids a possible performance pitfall.


  • Dramatically better Flow types for getIn(), setIn(), updateIn() which understand key paths (#1366, #1377)
  • Functional API for get(), set(), and more which support both Immutable.js collections and plain Objects and Arrays (#1369)


  • getIn() no longer throws when encountering a missing path (#1361)
  • Flow string enums can now be used as Map keys or Record fields (#1376)
  • Flow now allows record.get() to provide a not-set-value (#1378)
  • Fixed Flow return type for Seq.Set() (3e671a2b6dc76ab3dd141c65659bce55ffd64f44)


  • Fixed syntax error in typescript definitions which limited some checking (#1354)
Other projects in JavaScript