Immutable.js<br>Docs<br>v5<br>v4.3.8<br>v3.8.3
PlaygroundBrowser extensionQuestionsGitHub
Docs<br>v5<br>v4.3.8<br>v3.8.3
PlaygroundBrowser extensionQuestionsGitHub
Star
Immutable collections for JavaScript
Read the docs and eat your vegetables.
Docs are automatically generated from README.md and immutable.d.ts.<br>Please contribute! Also, don't miss the wiki which contains articles on<br>additional specific topics. Can't find something? Open an issue.
Table of contents:
Introduction
Getting started
The case for Immutability
JavaScript-first API
Nested Structures
Equality treats Collections as Values
Batching Mutations
Lazy Seq
Additional Tools and Resources
Contributing
Introduction
Immutable data cannot be changed once created, leading to much simpler<br>application development, no defensive copying, and enabling advanced memoization<br>and change detection techniques with simple logic. Persistent data presents<br>a mutative API which does not update the data in-place, but instead always<br>yields new updated data.
Immutable.js provides many Persistent Immutable data structures including:<br>List, Stack, Map, OrderedMap, Set, OrderedSet and Record.
These data structures are highly efficient on modern JavaScript VMs by using<br>structural sharing via hash maps tries and vector tries as popularized<br>by Clojure and Scala, minimizing the need to copy or cache data.
Immutable.js also provides a lazy Seq, allowing efficient<br>chaining of collection methods like map and filter without creating<br>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.
# using npm<br>npm install immutable
# using Yarn<br>yarn add immutable
# using pnpm<br>pnpm add immutable
# using Bun<br>bun add immutableThen require it into any module.
import { Map } from 'immutable';<br>const map1 = Map({ a: 1, b: 2, c: 3 });<br>const map2 = map1.set('b', 50);<br>map1.get('b') + ' vs. ' + map2.get('b'); // 2 vs. 50Browser
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,<br>rollup, or<br>browserify. The immutable npm module works<br>without any additional consideration. All examples throughout the documentation<br>will assume use of this kind of tool.
Alternatively, Immutable.js may be directly included as a script tag. Download<br>or link to a CDN such as CDNJS<br>or jsDelivr.
Use a script tag to directly add Immutable to the global scope:
script src="immutable.min.js">/script><br>script><br>var map1 = Immutable.Map({ a: 1, b: 2, c: 3 });<br>var map2 = map1.set('b', 50);<br>map1.get('b'); // 2<br>map2.get('b'); // 50<br>/script>Or use an AMD-style loader (such as RequireJS):
require(['./immutable.min.js'], function (Immutable) {<br>var map1 = Immutable.Map({ a: 1, b: 2, c: 3 });<br>var map2 = map1.set('b', 50);<br>map1.get('b'); // 2<br>map2.get('b'); // 50<br>});Flow & TypeScript
Use these Immutable collections and sequences as you would use native<br>collections in your Flowtype or TypeScript programs while still taking<br>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)<br>and TypeScript (v4.5 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<br>legacy browsers and environments, its type definitions require TypeScript's 2015<br>lib. Include either "target": "es2015" or "lib": "es2015" in your<br>tsconfig.json, or provide --target es2015 or --lib es2015 to the<br>tsc command.
import { Map } from 'immutable';<br>const map1 = Map({ a: 1, b: 2, c: 3 });<br>const map2 = map1.set('b', 50);<br>map1.get('b') + ' vs. ' + map2.get('b'); // 2 vs. 50Using TypeScript with Immutable.js v3 and earlier:
Previous versions of Immutable.js include a reference file which you can include<br>via relative path to the type definitions at the top of your file.
///<br>import { Map } from 'immutable';<br>var map1: Mapstring, number>;<br>map1 = Map({ a: 1, b: 2, c: 3 });<br>var map2 = map1.set('b', 50);<br>map1.get('b'); // 2<br>map2.get('b'); // 50The case for Immutability
Much of what makes application development difficult is tracking mutation and<br>maintaining state. Developing with immutable data encourages you to think<br>differently about how data flows through your application.
Subscribing to data events throughout your application creates a huge overhead of<br>book-keeping which can hurt performance, sometimes dramatically, and creates<br>opportunities for areas of your application to get out of sync with each other<br>due to easy to make programmer error. Since immutable data never changes,<br>subscribing to changes throughout the model is a dead-end and new data can only<br>ever be passed from above.
This model of data flow aligns well with the architecture of React<br>and especially well with an application designed using the ideas of Flux.
When...