Immutable.js — Persistent Immutable Data Collections for JavaScript

Introduction

Immutable.js implements persistent immutable data structures for JavaScript. It brings the benefits of value semantics—predictable state, easy undo/redo, and simplified change detection—without the performance cost of deep-copying objects on every mutation.

What Immutable.js Does

• Provides List, Stack, Map, OrderedMap, Set, OrderedSet, and Record types
• Uses structural sharing via hash array mapped tries for efficient updates
• Offers lazy Seq for chaining collection operations without intermediate allocations
• Enables deep equality checks with built-in .equals() and .hashCode()
• Works seamlessly with ES6 iterables and JavaScript's native collection protocols

Architecture Overview

Under the hood, Immutable.js stores data in hash array mapped tries (HAMTs). When you call .set() or .push(), only the path from root to the changed leaf is copied, sharing all unaffected branches with the previous version. This makes updates O(log32 N)—effectively constant—while keeping memory usage proportional to the number of changes, not the total collection size.

Installation & Configuration

• Install via npm: npm install immutable or yarn: yarn add immutable
• Ships with full TypeScript declarations out of the box
• Supports tree-shaking via ES module imports: import { Map } from 'immutable'
• Works in Node.js and all modern browsers without polyfills
• No external dependencies; the library is entirely self-contained

Key Features

• Structural sharing keeps updates fast and memory-efficient
• Rich functional API: map, filter, reduce, groupBy, flatMap across all collection types
• Deep merging with mergeDeep() for nested data structures
• Lazy evaluation via Seq defers computation until values are consumed
• Interoperable with plain JS via .toJS(), .toJSON(), and fromJS() conversions

Comparison with Similar Tools

• Immer — uses proxies for a mutable-looking API on plain objects; Immutable.js provides dedicated persistent data types with richer APIs
• seamless-immutable — freezes plain objects; Immutable.js uses specialized tries for better large-collection performance
• Mori — ClojureScript data structures for JS; Immutable.js has better TypeScript support and a more idiomatic JS API
• Object.freeze — shallow freeze only; no structural sharing or collection operations
• Structura.js — newer proxy-based approach; Immutable.js is more mature with a larger ecosystem

FAQ

Q: Does Immutable.js work with React and Redux? A: Yes. Redux historically recommended Immutable.js for store state. Its value equality makes shouldComponentUpdate checks trivial.

Q: What is the performance overhead compared to plain objects? A: Creation is slightly slower, but updates to large collections are faster because only changed paths are copied. Read access is O(log32 N).

Q: Can I use Immutable.js with TypeScript? A: Yes. The library ships with comprehensive TypeScript type definitions for all collection types and their methods.

Q: Is the project still maintained? A: Immutable.js 4.x was released with modern ES module support, TypeScript improvements, and continued community maintenance.

Sources

• https://github.com/immutable-js/immutable-js
• https://immutable-js.com/