mutative

Mutative powers several specialized libraries designed for different state management patterns and frameworks. You can use these ecosystem tools to integrate Mutative's high-performance mutable updates into your existing workflow:

React & Hooks

• use-mutative: A high-performance alternative to useState that uses spread operations, performing 2-6x faster.
• use-travel: A React hook providing state time travel, including undo, redo, reset, and archive functionalities.
• reactant: A framework specifically designed for building React applications using Mutative.

State Management Middleware & Extensions

• zustand-mutative: Middleware for Zustand that enhances the efficiency of immutable state updates.
• jotai-mutative: An extension for the Jotai state management library.
• xstate-mutative: Utilities for using Mutative with XState, offering faster and more flexible integration.
• mutative-compat: A wrapper that provides full Immer API compatibility for Mutative.

Time Travel & Transactional Updates

• travels: A fast, framework-agnostic core for undo/redo powered by Mutative JSON Patch.
• zustand-travel: A high-performance time-travel middleware specifically for Zustand.
• mutability: A JavaScript library focused on transactional mutable updates.

Collaborative & Universal State

• mutative-yjs: A library for building collaborative web applications using Yjs and Mutative.
• usm: A universal state modular library supporting Redux (5.x), MobX (6.x), Vuex (4.x), and Angular (2.0+).

When performing a mutation, if your logic requires returning an object that spreads or includes parts of the current draft, do not use rawReturn(). Instead, return the object normally, and Mutative will handle the draft-to-state transition.

If you use rawReturn() on a value containing drafts, it can lead to unexpected behavior or performance issues. It is highly recommended to enable strict: true in development to catch these instances via warnings.

const baseState = { a: 1, b: { c: 1 } };
const state = create(
  baseState,
  (draft) => {
    if (draft.b.c === 1) {
      // it will warn `The return value contains drafts, please don't use 'rawReturn()' to wrap the return value.` in strict mode.
      return rawReturn({
        ...draft,
        a: 2,
      });
    }
  },
  {
    strict: true,
  }
);
expect(state).toEqual({ a: 2, b: { c: 1 } });
expect(isDraft(state.b)).toBeFalsy();

Mutative supports Directed Acyclic Graphs (DAGs) where multiple paths lead to the same node, but it treats these paths independently during the drafting process.

When an object is referenced by multiple paths in your base state, Mutative creates independent drafts for each path. Consequently, a mutation performed on one path will not be reflected in the other paths. This behavior is intentional and matches Immer's behavior.

Key constraints:

• Shared nodes in base state: Each path gets its own independent draft. Mutations are path-specific.
• Manual assignment: You can create shared references in the final state by explicitly assigning one draft to another (e.g., draft.a = draft.b).
• Cycles: Real cycles (where a node refers back to an ancestor) are not supported and are detected in development mode when auto-freeze is enabled.

import { create } from 'mutative';

const obj = {};
// Same object referenced by two keys
obj.color1 = obj.color2 = { name: 'Red' };

const result = create(obj, (draft) => {
  // ⚠️ Different drafts created for each path!
  console.log(draft.color1 === draft.color2); // false

  draft.color1.name = 'Blue';
  
  // color2 remains unchanged because it has a separate draft
  console.log(draft.color2.name); // 'Red'
});

console.log(result.color1 === result.color2); // false
// Result: { color1: { name: 'Blue' }, color2: { name: 'Red' } }

Mutative follows a three-stage process to perform immutable updates using a mutable interface:

1. Current State: The initial, unchanged immutable state.
2. Draft: A mutable phase where changes are made to a draft. When you access properties of the state, Mutative generates corresponding draft proxy objects for those nodes.
3. Next State: The final immutable data produced after the draft function completes. Only the parts of the state tree that were actually modified (or had drafts generated for them) are updated; unchanged branches are preserved via structural sharing.

This allows you to write code that looks like direct mutation while maintaining strict immutability for the resulting state.

const baseState = {
  a0: {
    b0: {},
  },
  a1: {
    b1: {},
    b2: {
      c0: 0,
    },
  },
  a2: {},
}

const nextState = create(baseState, (draft) => {
  const { a0 } = draft;
  // If it is draftable, once it has been accessed, it will generate a corresponding draft.
  expect(isDraft(a0)).toBeTruthy();
  // each node is a draft, and the draft is a proxy object
  draft.a1.b2.c0 = 1;
});

expect(nextState).not.toBe(baseState);
expect(nextState.a0).toBe(baseState.a0); // generated draft, but not changed
expect(nextState.a2).toBe(baseState.a2); // no generated draft, not changed
expect(nextState.a1).not.toBe(baseState.a1);
expect(nextState.a1.b2).not.toBe(baseState.a1.b2);
expect(nextState.a1.b2.c0).toBe(1);