Mutative

license

Mutative - A JavaScript library for efficient immutable updates, 2-6x faster than naive handcrafted reducer, and more than 10x faster than Immer.

Why is Mutative faster than the spread operation(naive handcrafted reducer)?

The spread operation has performance pitfalls, which can be detailed in the following article:

<a href="https://www.richsnapp.com/article/2019/06-09-reduce-spread-anti-pattern" target="_blank">The reduce ({...spread}) anti-pattern</a>
<a href="https://jonlinnell.co.uk/articles/spread-operator-performance?fbclid=IwAR0mElQwz2aOxl8rcsqoYwkcQDlcXcwuyIsTmTAbmyzrarysS8-BC1lSY9k" target="_blank">How slow is the Spread operator in JavaScript?</a>

And Mutative optimization focus on shallow copy optimization, more complete lazy drafts, finalization process optimization, and more.

Motivation

Writing immutable updates by hand is usually difficult, prone to errors, and cumbersome. Immer helps us write simpler immutable updates with "mutative" logic.

But its performance issue causes a runtime performance overhead. Immer must have auto-freeze enabled by default(Performance will be worse if auto-freeze is disabled), such immutable state with Immer is not common. In scenarios such as cross-processing, remote data transfer, etc., these immutable data must be constantly frozen.

There are more parts that could be improved, such as better type inference, non-intrusive markup, support for more types of immutability, Safer immutability, more edge cases, and so on.

This is why Mutative was created.

Mutative vs Naive Handcrafted Reducer Performance

<details> <summary><b>Mutative vs Reducer benchmark by object: </b></summary>

Naive handcrafted reducer

// baseState type: Record<string, { value: number }>
const state = {
  ...baseState,
  key0: {
    ...baseState.key0,
    value: i,
  },
};

Mutative

const state = create(baseState, (draft) => {
  draft.key0.value = i;
});

Mutative vs Reducer benchmark by object

Measure(seconds) to update the 1K-100K items object, lower is better(view source).

</details>

Mutative is up to 2x faster than naive handcrafted reducer for updating immutable objects.

<details> <summary><b>Mutative vs Reducer benchmark by array: </b></summary>

Naive handcrafted reducer

// baseState type: { value: number }[]

// slower 6x than Mutative
const state = [
  { ...baseState[0], value: i },
  ...baseState.slice(1, baseState.length),
];

// slower 2.5x than Mutative
// const state = baseState.map((item, index) =>
//   index === 0 ? { ...item, value: i } : item
// );

// same performance as Mutative
// const state = [...baseState];
// state[0] = { ...baseState[0], value: i };

The actual difference depends on which spread operation syntax you use.

Mutative

const state = create(baseState, (draft) => {
  draft[0].value = i;
});

Mutative vs Reducer benchmark by array

Measure(seconds) to update the 1K-100K items array, lower is better(view source).

</details>

Mutative is up to 6x faster than naive handcrafted reducer for updating immutable arrays.

Mutative vs Immer Performance

Mutative passed all of Immer's test cases.

Measure(ops/sec) to update 50K arrays and 1K objects, bigger is better(view source). [Mutative v1.3.0 vs Immer v10.1.3]

Benchmark

Naive handcrafted reducer - No Freeze x 4,777 ops/sec ±1.06% (94 runs sampled)
Mutative - No Freeze x 6,783 ops/sec ±0.71% (96 runs sampled)
Immer - No Freeze x 5.72 ops/sec ±0.39% (19 runs sampled)

Mutative - Freeze x 1,069 ops/sec ±0.75% (97 runs sampled)
Immer - Freeze x 392 ops/sec ±0.66% (92 runs sampled)

Mutative - Patches and No Freeze x 1,006 ops/sec ±1.73% (95 runs sampled)
Immer - Patches and No Freeze x 5.73 ops/sec ±0.16% (19 runs sampled)

Mutative - Patches and Freeze x 548 ops/sec ±1.06% (94 runs sampled)
Immer - Patches and Freeze x 287 ops/sec ±0.84% (93 runs sampled)

The fastest method is Mutative - No Freeze

Run yarn benchmark to measure performance.

OS: macOS 14.7, CPU: Apple M1 Max, Node.js: v22.11.0

Immer relies on auto-freeze to be enabled, if auto-freeze is disabled, Immer will have a huge performance drop and Mutative will have a huge performance lead, especially with large data structures it will have a performance lead of more than 50x.

So if you are using Immer, you will have to enable auto-freeze for performance. Mutative is disabled auto-freeze by default. With the default configuration of both, we can see the 17x performance gap between Mutative (6,783 ops/sec) and Immer (392 ops/sec).

Overall, Mutative has a huge performance lead over Immer in more performance testing scenarios. Run yarn performance to get all the performance results locally.

<details> <summary><b>More Performance Testing Scenarios, Mutative is up to `2.5X-82.9` faster than Immer: </b></summary>

Mutative vs Immer - All benchmark results by average multiplier

view source.

</details>

Features and Benefits

Mutation makes immutable updates - Immutable data structures supporting objects, arrays, Sets and Maps.
High performance - 10x faster than immer by default, even faster than naive handcrafted reducer.
Optional freezing state - No freezing of immutable data by default.
Support for JSON Patch - Full compliance with JSON Patch specification.
Custom shallow copy - Support for more types of immutable data.
Support mark for immutable and mutable data - Allows for non-invasive marking.
Safer mutable data access in strict mode - It brings more secure immutable updates.
Support for reducer - Support reducer function and any other immutable state library.

Difference between Mutative and Immer

| | Mutative | Immer | | :------------------------------------ | -------: | :---: | | Custom shallow copy | ✅ | ❌ | | Strict mode | ✅ | ❌ | | No data freeze by default | ✅ | ❌ | | Non-invasive marking | ✅ | ❌ | | Complete freeze data | ✅ | ❌ | | Non-global config | ✅ | ❌ | | async draft function | ✅ | ❌ | | Fully compatible with JSON Patch spec | ✅ | ❌ | | new Set methods(Mutative v1.1.0+) | ✅ | ❌ |

Mutative has fewer bugs such as accidental draft escapes than Immer, view details.

Installation

Yarn

yarn add mutative

NPM

npm install mutative

CDN

Unpkg: <script src="https://unpkg.com/mutative"></script>
JSDelivr: <script src="https://cdn.jsdelivr.net/npm/mutative"></script>

Usage

import { create } from 'mutative';

const baseState = {
  foo: 'bar',
  list: [{ text: 'coding' }],
};

const state = create(baseState, (draft) => {
  draft.list.push({ text: 'learning' });
});

expect(state).not.toBe(baseState);
expect(state.list).not.toBe(baseState.list);

create(baseState, (draft) => void, options?: Options): newState

The first argument of create() is the base state. Mutative drafts it and passes it to the arguments of the draft function, and performs the draft mutation until the draft function finishes, then Mutative will finalize it and produce the new state.

Use create() for more advanced features by setting options.

`create()`

Use create() for draft mutation to get a new state, which also supports currying.

import { create } from 'mutative';

const baseState = {
  foo: 'bar',
  list: [{ text: 'todo' }],
};

const state = create(baseState, (draft) => {
  draft.foo = 'foobar';
  draft.list.push({ text: 'learning' });
});

In this basic example, the changes to the draft are 'mutative' within the draft callback, and create() is finally executed with a new immutable state.

`create(state, fn, options)`

Then options is optional.

strict - boolean, the default is false.

Forbid accessing non-draftable values in strict mode(unless using unsafe()).

When strict mode is enabled, mutable data can only be accessed using unsafe().

It is recommended to enable strict in development mode and disable strict in production mode. This will ensure safe explicit returns and also keep good performance in the production build. If the

Mutative

Install / Use

README

Mutative

Motivation

Mutative vs Naive Handcrafted Reducer Performance

Mutative vs Immer Performance

Features and Benefits

Difference between Mutative and Immer

Installation

Usage

APIs

`create()`

`create(state, fn, options)`