immutable-js

Immutable.js gives JavaScript persistent, immutable collections like List, Map, and Set. Updates return new values instead of editing in place, and structural sharing keeps that cheap on modern engines.

Data that cannot change once created removes a whole class of bugs. No defensive copying, and memoization and change detection become straightforward logic. The persistent side is the trickier half: the API looks mutative, but an update never touches the original, it always yields a new version of the data.

The provided collections are List, Stack, Map, OrderedMap, Set, OrderedSet, and Record. Performance comes from structural sharing built on hash array mapped tries and vector tries, the approach popularized by Clojure and Scala, which avoids copying or caching whole data sets. A lazy Seq sits alongside, so map and filter can chain without building intermediate collections, with Range and Repeat as generators.

Immutable collections are meant to be treated as values, which is why the docs push is() and equals() over the triple-equals operator. Two different Map instances holding the same entries are value equal, which lets collections serve as Map keys or Set members. The cost shows up in comparisons: value equality can walk every item in O(N), while reference equality is O(1), so the README suggests keeping the trade-off in mind when memoizing.

Each immutable update carries a little overhead, and a series of local mutations can add up. withMutations makes a temporary mutable copy, applies a batch of changes, and hands back an immutable result, which is how the library does its own complex updates. Only a few methods are allowed inside, set, push, and pop, because anything like map or filter always returns fresh immutable data. A lazy Seq works the other way, doing only as much work as a call asks for, and among the split methods filter stays lazy while partition and groupBy run eager.

The npm install brings type definitions for Flow, version 0.55.0 or higher, and TypeScript, version 4.5 or higher. The definitions embrace ES2015, so the tsconfig needs target or lib set to es2015. The library itself runs in legacy browsers, IE11 included, and can be dropped in as a script tag from a CDN or bundled with webpack, rollup, or browserify. Converting back out is handled by toJS, toArray, and toObject, with toJSON support for JSON.stringify.

The library earns its trade-off: immutable data simplifies change detection and memoization, at the cost of learning value equality instead of reference identity. The README walks through both sides.

• Source 1 · Project repository
• Source 2 · README