immer

This feature release adds a new optional "array method overrides" plugin that significantly speeds up array methods when accessing drafts.

Changelog

Performance Improvements

As part of the recent performance optimization work, our benchmarks showed that all Proxy-based immutable update libraries were drastically slower than vanilla JS when calling both mutating and non-mutating array methods. After investigation, it turns out that an array method like arr.filter() causes the Proxy's get trap to trigger for every single item in the array. This in turn forces creation of a new Proxy and internal Immer metadata for every item, even though this was just a read operation and no items were being updated.

This release adds a new enableArrayMethods plugin that will override draft array methods to bypass the draft and directly operate on the underlying wrapped array instance. This significantly speeds up array operations.

When enabled, the plugin overrides these array methods:

• Mutating: push, pop, shift, unshift, splice, reverse, sort

• Non-mutating: filter, slice, concat, flat, find, findIndex, findLast, findLastIndex, some, every, indexOf, lastIndexOf, includes, join, toString, toLocaleString

Our benchmarks show that the overridden methods (plus the other perf changes in Immer 10.2 and 11.0) are 50-80% faster than the baseline behavior of Immer 10.1.

The plugin adds about 1.5-2K minified to Immer's bundle size.

It's important to note that the plugin does change the "safe to mutate a draft" semantics of Immer. Any of these methods that receives an array item as a callback argument will not automatically wrap that item in a Proxy!. That means that if you try to mutate an argument in a method such as filter, it will actually mutate the real underlying object, which will cause bugs in your app. This is an intentional design tradeoff. Semantically, all of these methods imply read-only access to array values, so if your code tries to mutate an array item in a callback, that is a bug in your code.

Note that this does not override map, flatMap, forEach, or reduce / reduceRight. Those methods do imply either side effects and potential mutations, or returning arbitrary values. Given that, we determined it was both safest and simplest to keep their behavior as-is.

See the Array Methods Plugin docs page for further details on the behavior of the overridden methods.

What's Changed

• Override array methods to avoid proxy creation while iterating and updating

Performance Improvements

• Rewrite finalization system to use a callback approach instead of tree traversal

Breaking changes

• breaking

  Enable loose iteration by default

• breaking

  Simplify some iteration checks

• breaking

  Allow passing type to get/set utils to skip archetype lookup

• breaking

  Convert assigned_ to Map

• breaking

  Enable loose iteration

• breaking

  Replace recursive tree finalization with targeted callbacks

Ported Mutative's "finalization callback" approach as a more targeted and performant implementation for finalization compared to the existing recursive tree traversal approach:

• breaking

  Added cleanup callbacks for each draft that's created

• breaking

  Added callbacks to handle root drafts, assigned values, and recursing
  inside of plain values

• breaking

  Updated state creation to return [draft, state] to avoid a lookup

• breaking

  Rewrote patch generation system to work with callbacks instead of
  during tree traversal

• breaking

  Update self-reference test with new behavior

• breaking

  Apply code review suggestions

• breaking

  Byte-shave scopes and patch plugin usage

• breaking

  Inline finalizeAssigned

• breaking

  Move fixPotentialSetContents to plugin

• breaking

  Byte-shave typeof utils

• breaking

  Byte-shave Object references

• breaking

  Byte-shave field names and arrow functions

Release notes

• breaking

  Immer 10 only supports modern browsers, that have support for Proxy, Reflect, Symbol and Map and Set.

• breaking

  There is no longer a UMD build exposed (thanks Mark Erikson for modernizing the build setup in #1032!

• breaking

  Getters and setters are ignored by default on plain object, as this is a very uncommon case and provides a significant performance boost (ca 33%, but depends a lot on the scenario). Fixes #867, #1012. Thanks hrsh7th for implementing it in #941!

• breaking

  Promise based reducers are no longer supported. Conceptually it is an anti pattern to hold on to drafts over time. If needed the old behavior can still be achieved by leveraging createDraft and finishDraft.

• breaking

  ES5 mode (for legacy browsers) has been dropped. If your project relies on enableES5(), you SHOULD NOT upgrade Immer. enableES5 has been removed.

• breaking

  produce is no longer exposed as the default export. This improves eco system compatibility, and makes sure that there is only one correct way of doing things

• breaking

  enableAllPlugins has been removed, use enablePatches(); enableMapSet() instead

• breaking

  Shortening the length of a JSON array now results in delete patches, rather than a mutation of the length property, in accordance with JSON spec. Thanks kshramt for implementing this in #964!

• Immer is now an ESM package that can be directly imported into the browser. CJS should still work, UMD support has been removed.

Overall, there is a rough performance increase of 33% for Immer (and in some cases significantly higher), and the (non gzipped) bundle size has reduced from 16 to 11.5 KB, while the the minimal gzipped import of just produce has remained roughly the same at 3.3 KB.

For more details, see #1015

Migration steps

1. If you have any enableES5() call, don't migrate

2. When using getters/ setters icmw plain objects, call useStrictShallowCopy(true) at startup

3. Replace all default imports: Replace import produce from "immer" with import {produce} from "immer"

4. Replace all calls to enableAllPlugins() with enablePatches(); enableMapSet(); to be more specific and smoothen future migrations.

5. If any producer returned a Promise, refactor it to leverage createDraft instead. Roughly:

const newState = await produce(oldState, recipe)

// becomes
const draft  = createDraft(oldState)
await recipe(draft)
const newState = finishDraft(draft)

Bug Fixes

• Don't freeze drafts returned from produce if they were passed in as draft

• Produce results should never be frozen when returned from nested produces, to prevent 'hiding' drafts. Fixes #935

• Release and publish from 'main' rather than 'master' branch

• Revert earlier fix (#990) for recursive types

• Upgrade Github actions to Node 16 attempt 1

• Upgrade Github actions to Node 16 attempt 2