immerjs/immer
github.com/immerjs/immer ↗ · 155 files · 1.6 MB
Immer Create the next immutable state tree by simply modifying the current tree Winner of the "Breakthrough of the year" React open source award and "Most impactful contribution" JavaScript open source award in 2019 Contribute using one-click online setup You
Overview
Immer is a JavaScript and TypeScript library that turns mutations inside a recipe callback into immutable state updates with structural sharing. It serves application developers using plain objects, arrays, and optionally Maps, Sets, or marked classes, including React and Redux state workflows. At commit 061c2425e1c9dff89e4e4189d42af1b7839dfe0a, its implementation combines revocable proxies, scope-owned finalization callbacks, optional patch generation, and an opt-in array-method interception plugin; separate packages provide documentation and performance tooling.
System map
The principal runtime is an in-process state transformation library whose public entrypoint is src/immer.ts. Core modules manage proxies, execution scopes, snapshots, and finalization, while three optional plugins supply collection, patch, and array-method behavior. Distribution includes multiple JavaScript module formats and declarations; documentation and benchmarking have separate manifests and execution boundaries.
- src/immer.ts constructs one default Immer instance and exposes its produce method plus bound patch, configuration, and manual-draft methods; it also exports Immer for independent instances.
- src/internal.ts is the shared barrel connecting utility constants, errors, types, plugin interfaces, scopes, finalization, proxies, Immer, and current snapshots.
- Each producer scope owns draft references, optional forward/inverse patches, parent scope, finalization tracking sets, and its Immer instance; currentScope is module-level execution state.
- Package export conditions select legacy ESM for React Native, modern ESM for imports, and a CJS dispatcher for require, with dist/immer.d.ts supplied across these conditions.
- tsup builds declarations, development ESM/CJS, legacy ESM targeting es2017, and minified production ESM/CJS; production builds replace NODE_ENV and mangle properties ending in an underscore.
- The root package uses Yarn-oriented scripts for source tests, built-package tests, Flow checks, coverage, performance workloads, import-size reports, and semantic-release.
- The separate React/Docusaurus website serves documentation at routeBasePath '/', supports English and zh-CN, and deploys website/build to gh-pages through its public-docs workflow.
- perf-testing is a private ESM package using Mitata and Rolldown; aliases connect its current-development comparison to ../dist/immer.mjs alongside historical Immer versions and alternative libraries.
Feature catalog
The user-facing surface is primarily a library API for creating and examining immutable updates. Recipes support direct and curried calls, explicit replacement, manual draft lifecycles, and optional reversible patches. Collection support, class draftability, type helpers, configurable copying, and array interception extend that surface, while the website explains their usage.
- produce accepts a base value and recipe, validates callback arguments, drafts eligible objects, handles primitive inputs directly, and returns either the resulting state or a replacement.
- Curried produce captures a recipe and optional default base, then forwards later arguments and the caller's this context into recipe.call.
- enablePatches activates produce listeners, produceWithPatches tuples, and applyPatches replay; Patch exposes add, remove, and replace operations with array-valued paths.
- createDraft opens a mutable draft without a recipe callback, and finishDraft finalizes only drafts marked manual, optionally reporting patches.
- enableMapSet supplies DraftMap and DraftSet implementations with mutation methods, iteration, nested value drafting, and revocation checks.
- enableArrayMethods intercepts seven mutating methods and selected read methods; filter, slice, find, and findLast return selected drafts, while concat and flat return base elements.
- isDraft, isDraftable, original, and current inspect draft state; immerable marks custom instances or constructors as draftable, and nothing requests an undefined replacement.
- Configuration APIs control auto-freezing, strict shallow copying, and strict iteration; Draft and Immutable recursively map types, while castDraft and castImmutable are runtime identity casts.
Data flow
Inputs enter as application-owned state and executable recipes, then become scope-owned drafts with lazily allocated copies. Writes record assignments and propagate modification flags toward parents; finalization substitutes ordinary values and preserves unchanged base references. Results and optional patch arrays leave through returns and listeners, with persistence delegated to the calling application in these inspected API paths.
- The draftability boundary accepts plain objects, arrays, marked instances or constructors, Maps, and Sets; other truthy object inputs to produce reach die(1).
- createProxy selects collection plugins or createProxyProxy, registers the draft in its scope, and shares the parent's callback array while recording the child's key.
- objectTraps.get reads latest(state), creates a child draft only for eligible base or relocated references, and caches that draft in copy_; merely reading can allocate a copy without marking a change.
- objectTraps.set ignores equal-value assignments under its presence checks, otherwise prepares a copy, marks ancestors changed, records assigned_ entries, and registers cross-reference handling.
- Finalization returns base_ for unmodified drafts, drains registered callbacks for modified drafts, and updates parent references to finalized values before returning copy_.
- Patch generation uses assignment records for objects and Maps, index comparisons for arrays, and membership changes for Sets, producing corresponding inverse operations.
- applyPatches clones draftable patch values before dispatching writes; arrays use splice or push, Maps use set/delete, Sets use add/delete, and ordinary objects use property assignment/deletion.
- processResult optionally deep-freezes eligible root results, revokes drafts, invokes the patch listener, and returns state; these core output boundaries contain no persistence operation.
Behavior traces
Source inspection followed ordinary production, manual drafting, and patch replay end-to-end, plus startup, snapshots, collections, and array reordering. These traces describe execution order and meaningful branches rather than observed runtime results. They show where drafts are created, how outputs are finalized, and when user callbacks execute.
- Startup: src/immer.ts creates new Immer(), exposing its methods; instance defaults are autoFreeze_=true, useStrictShallowCopy_=false, and useStrictIteration_=false, while optional plugins require explicit enable calls.
- Recipe update: produce → isDraftable → enterScope → createProxy → createProxyProxy → recipe(proxy); nested reads draft lazily and writes call prepareCopy → markChanged → handleCrossReference.
- Recipe completion: successful execution leaves the scope, enables requested patch collection, then processResult → finalize → callback cleanup/patch generation → maybeFreeze → revokeScope → patchListener; a thrown recipe instead revokes in finally.
- Manual lifecycle: createDraft validates the base, snapshots it with current if already drafted, enters a scope, creates and marks a manual proxy, then leaves; finishDraft retrieves its owning scope and calls processResult.
- Patch round trip: produceWithPatches → produce with a listener → tuple capture; applyPatches scans backward for the last root replacement, skips earlier patches, then applies through the plugin directly to a draft or inside another produce.
- Snapshot: current rejects non-drafts, returns unchanged bases directly, temporarily marks modified drafts finalized to suppress drafting during copying, recursively snapshots children, and restores finalized_=false.
- Map update: createProxy selects proxyMap_ → DraftMap; get(key) lazily creates and caches a child draft, set(key,value) prepares a Map copy and records modification, and finalization callbacks replace nested draft references.
- Array reordering: objectTraps.get selects createMethodInterceptor → enterOperation → handleReorderingOperation → executeArrayMethod → native copy sort/reverse → markAllIndicesReassigned; later element reads detect relocated base references, and finally clears operationMethod.
Testing signals
Tests and CI were inspected, not executed; test existence is not a passing result. The inspected suite uses Vitest in Node, repeats core behavior across configuration combinations, and has a separate production-CJS test configuration. Coverage includes structural sharing, manual lifecycles, patch replay, collection behavior, and array regressions, but inspected scripts and configurations leave specific verification limits.
- Source tests use Vitest with Node environment, global test APIs, and __tests__ JavaScript/TypeScript discovery; coverage uses V8 with text and LCOV outputs, but no execution or coverage result was obtained.
- __tests__/base.js repeats its core suite across auto-freeze, strict-copy, and listener booleans, with one additional array-plugin configuration rather than a full plugin/configuration cross-product.
- Core assertions check unchanged-root identity, structural sharing, deep-change propagation, plugin no-op identity, and reorder-then-mutate preservation with patch replay/reversal.
- Patch fixtures assert exact patches, replay, and inverse restoration; dedicated cases assert that __proto__ traversal through objects and arrays throws without polluting unrelated objects.
- Manual-draft tests exercise argument errors, immutable results, repeated finish rejection, and patch listeners; post-finish mutation checks are conditional on non-production mode, while plugins.js tests missing-plugin errors.
- Production tests alias public source imports to the production CJS build, define USES_BUILD and production NODE_ENV, and use separate snapshots; their custom reporter can reset exitCode when its failure predicate and errors array are empty.
- TypeScript fixtures use compile-time assert signatures whose runtime body is an identity function; inspected Yarn/Vitest configuration does not explicitly enable checking those fixtures with tsc, while two reconciliation identity tests are explicitly skipped.
- Inspected CI runs Node 24 with frozen-lockfile install, yarn test, coverage, performance workloads, and Coveralls; this is one configured Node version, and the separate Mitata package is not invoked by those listed test steps.
Risk map
These are source observations and maintenance risks, not confirmed vulnerabilities. Sensitive boundaries include executable recipes and accessors, externally supplied patch paths, documentation scripts, and release permissions. Core correctness depends on coupled scope, callback, and array-reference bookkeeping; the inspection is bounded and does not establish whole-repository security or test completeness.
- Patch application rejects reserved intermediate traversal keys for objects/arrays and function prototypes, but final-key writes use a separate dispatch; security edits must preserve and assess both boundaries rather than generalizing the traversal guard.
- Recipes execute caller code directly, strict copying reads own accessors, and proxy access can invoke prototype getters/setters; these APIs are executable object interactions rather than a sanitization boundary.
- Array interception passes base values into predicates and native copy operations; mutation inside intercepted callbacks or through concat/flat elements bypasses ordinary nested-draft tracking.
- Reordered arrays depend on allIndicesReassigned_ and baseRefs_ to draft relocated base objects; inserted objects containing drafts depend on string-keyed assignment records and cross-reference callbacks to avoid revoked proxies in results.
- Strict-iteration comments say the default is enabled, but Immer initializes useStrictIteration_=false; the constructor also accepts only boolean strict-copy config values although StrictMode includes 'class_only'.
- Manual drafts can miss application updates made while awaiting asynchronous work, and externally inserted objects are not automatically drafted; both usage traps are explicitly documented.
- The profiling analyzer reads a caller-selected filesystem path without a repo-root containment check and loads ../dist sourcemaps; these file reads belong to development tooling, while tsup separately writes distribution files.
- The documentation site loads external button/ad scripts and two analytics plugins; release CI grants contents, id-token, and pull-request write permissions and publishes only for immerjs/immer after tests/build.
Extension points
Extension mechanisms are concrete and mostly internal rather than a general third-party plugin API. The public library supports configurable instances and three enable functions, while internal typed interfaces connect implementations to scope behavior. Additional seams exist in draftable classes, producer abstractions, declaration mappings, packaging, documentation routing, and benchmark comparisons.
- New Immer instances provide independent auto-freeze, strict-copy, and iteration settings; produce is an instance arrow function, while the public singleton binds other exposed methods.
- The internal plugin registry has typed MapSet, Patches, and ArrayMethods slots; getPlugin rejects missing implementations and loadPlugin preserves the first loaded implementation.
- Collection extension hooks return draft/state tuples and provide fixSetContents; createProxy dispatches Maps/Sets through these hooks, and finalization calls collection cleanup.
- Array-method support plugs into objectTraps.get through detection and interceptor hooks; method Sets define dispatch, and registered handlers own operation flags, mutation bookkeeping, and return semantics.
- Custom classes opt into drafting by defining the exported immerable symbol on an instance or constructor; strict shallow copying preserves their prototype using descriptor-based Object.create.
- Libraries can build producer abstractions on createDraft/finishDraft and consume PatchListener output; these hooks reuse the same scope finalization rather than requiring a separate state engine.
- Public type behavior is concentrated in Draft, Immutable, IProduce, and IProduceWithPatches; distribution changes connect src/immer.ts exports to package conditions and tsup's format/declaration variants.
- Website additions join explicit sidebar lists and Docusaurus plugins/routes; performance-provider additions join benchmark imports, the private package dependencies, and current-build aliases.
Contributor handoff
Begin with public exports and the scope/proxy/finalization chain, then inspect the plugin and tests relevant to the requested behavior. Tests and CI were inspected, not executed, and this bounded inventory supplies no passing result or measured speedup. Future implementation work should preserve the existing Yarn, formatting, packaging, and lifecycle conventions, with execution performed only under separate authorization.
- For core changes, read src/immer.ts, Immer.produce, scope management, proxy traps, and processResult together before editing; exports and state lifecycle span those files.
- Follow Prettier's tabs, no semicolons, double quotes, no trailing commas, and 80-column code formatting; package hooks apply pretty-quick to staged files.
- When execution is authorized, start with the relevant suite through the existing test:src script and Vitest file filtering, then test:build for production CJS behavior; full test adds Flow checking. (inferred)
- Tests and CI were inspected only: configured source/build/Flow, coverage, and performance commands are verification plans, not evidence of passing tests, CI success, or benchmark improvements.
- Array edits must preserve no-op identity, drafting after reorder, inserted nested-draft cleanup, and patch round trips; targeted existing assertions cover these interacting invariants.
- For type changes, inspect compile-time assertion helpers and the actual compiler command; runtime assert returns its first argument, and inspected Vitest configuration does not establish TypeScript fixture checking.
- Treat underscore-suffixed internals and build aliases as packaging-sensitive: tsup mangles those properties, while base tests import src/internal and production tests alias public source imports to a built artifact.
- Before changing defaults or lifecycle semantics, reconcile comments with initialized values, preserve recipe exception revocation and listener timing, and account for documented tree, external-data, and nested-producer constraints.
Languages
| Language | Files | Share of source |
|---|---|---|
| Markdown | 54 | docs/config |
| TypeScript | 29 | 53% |
| JavaScript | 26 | 47% |
| JSON | 11 | docs/config |
| YAML | 6 | docs/config |
| HTML | 3 | docs/config |
| CSS | 1 | docs/config |
Start reading here
Probable source entrypoint: src/ — inferred from the directory tree and manifest, not the upstream docs.
Source roots
src/ (18 files)
Source layout — src/
| Path | Files |
|---|---|
src/core/ | 5 |
src/plugins/ | 3 |
src/types/ | 4 |
src/utils/ | 4 |
src/immer.ts | 1 |
src/internal.ts | 1 |
Repository structure
| Top-level path | Files |
|---|---|
website/ | 57 |
__tests__/ | 41 |
src/ | 18 |
.github/ | 8 |
perf-testing/ | 7 |
__performance_tests__/ | 6 |
_site/ | 3 |
.codesandbox/ | 1 |
Docs found: readme.md
Package
package.json — immer v10.0.3-beta, 23 declared dependencies.
@babel/core@types/node@vitest/coverage-v8coverallscpx2deep-freezeflow-binhuskyimmutableimport-sizelodashlodash.clonedeep
CI & config entrypoints
.github/workflows/release.yml— GitHub Actions workflow.github/workflows/docs-public.yml— GitHub Actions workflow.github/workflows/test.yml— GitHub Actions workflowpackage.json— npm scripts: build, coverage, coveralls, publish-docs, release, start, test, test:buildperf-testing/package.json— npm scripts: analyze-profile, benchmark, build, build-and-benchmark, build-and-profile, build-immer, build-with-latest, profilewebsite/package.json— npm scripts: build, examples, publish-gh-pages, start, write-translations
Structural health signals
Average score 8.5/10 across 48 analyzed source files; 2 hotspots surfaced.
__tests__/base.js— 2674 lines, score 6.2 (Large file, Long function/block)__tests__/patch.js— 1607 lines, score 6.2 (Large file, Long function/block)src/plugins/arrayMethods.ts— 508 lines, score 6.7 (Large file, Long function/block)
These are deterministic review leads — size, churn, and structural signals — not proof of a bug in this project.
Recent history
061c2425e1c92026-08-19 — chore(test): pin draft prototype-inspection behavior restored by #1271 (#1272)955c5f5f3d5a2026-08-19 — docs: add typed custom produce function (#1239)2f0ea7f3f0c02026-08-19 — docs: add zh-CN array methods translation (#1285)9daf3cdad0d32026-08-19 — chore(deps): bump svgo from 2.8.2 to 2.8.3 in /website (#1291)3405b656db5d2026-08-19 — chore(deps): bump postcss from 8.5.13 to 8.5.26 in /website (#1281)