# Immutable.js — Persistent Immutable Data Collections for JavaScript

> Immutable.js provides efficient immutable List, Stack, Map, OrderedMap, Set, and Record collections for JavaScript with structural sharing for minimal memory overhead.

## Install

Save as a script file and run:

# Immutable.js — Persistent Immutable Data Collections for JavaScript

## Quick Use
```bash
npm install immutable
```
```js
const { Map, List } = require('immutable');
const map1 = Map({ a: 1, b: 2, c: 3 });
const map2 = map1.set('b', 50);
console.log(map1.get('b')); // 2
console.log(map2.get('b')); // 50
```

## 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/

---
Source: https://tokrepo.com/en/workflows/asset-5adcf466
Author: Script Depot