Mutative

Common errors

• TypeError: Cannot perform 'set' on a proxy that has been revoked

  cause Attempting to modify a Mutative draft object or its properties after the producer function has completed and the proxy has been revoked (finalized).
  fix Ensure all modifications to the draft state are confined within the producer function passed to `create`. Do not store or attempt to modify the `draft` object reference after `create` returns.

• TypeError: Cannot assign to read only property 'propertyName' of object '[object Object]'

  cause Trying to directly mutate the object returned by `create`. This object is frozen and immutable, meaning its properties cannot be changed directly.
  fix Always use the `create` function with a producer callback to make changes. The return value of `create` is the new, immutable state.

• TypeError: create is not a function

  cause Incorrect import statement for the `create` function, particularly common with CommonJS `require` when `mutative` is primarily an ESM package, or if using a default import instead of a named import.
  fix For ES Modules, use `import { create } from 'mutative'`. For CommonJS in environments where it's supported, use `const { create } = require('mutative')`.

Warnings

• gotcha Mutative's significant performance claims (e.g., '10x faster than Immer', '6x faster than naive handcrafted reducer') are highly dependent on the specific benchmark scenarios and comparison implementations. Real-world performance may vary, and for simple updates, the difference might be negligible or even in favor of highly optimized manual spread operations.
  Fix: Always benchmark Mutative against your specific use cases and existing update patterns to confirm actual performance benefits in your application.
• gotcha When working with `mutative`, ensure all modifications occur strictly within the producer function provided to `create`. Attempting to modify the draft object or any part of the returned immutable state outside this function will lead to errors or unexpected behavior due to proxy revocation or frozen objects.
  Fix: Encapsulate all state mutation logic within the `create` callback. Treat the object returned by `create` as strictly immutable.
• deprecated The `current()` API underwent multiple refactorings and a temporary revert in early 1.x versions (specifically around v1.0.7-v1.0.8). While now stable in later 1.x releases, developers on older patch versions might encounter inconsistencies or incorrect behavior when using `current()` to access the latest draft state.
  Fix: Upgrade to the latest stable version of Mutative (v1.1.0 or newer) to ensure reliable and correct functionality of the `current()` API.
• gotcha Mutative uses JavaScript Proxies for its copy-on-write mechanism. While powerful, Proxies can sometimes have subtle interactions or edge cases with certain non-plain JavaScript objects (e.g., custom classes, complex data structures with internal state not exposed via standard properties) or when strict equality checks are used in specific contexts.
  Fix: Thoroughly test Mutative with any custom classes or non-standard JavaScript objects in your state. For complex scenarios, inspect the `original()` reference or the final state to ensure expected immutability and data integrity.

Install

• npm install mutative npm
• yarn add mutative yarn
• pnpm add mutative pnpm

Imports

• create
  wrong:

  const create = require('mutative')

  correct:

  import { create } from 'mutative'

  The primary function for creating immutable updates. Always use named import.
• apply
  wrong:

  const apply = require('mutative')

  correct:

  import { apply } from 'mutative'

  Used for applying a list of patches to a base state, often generated by `enablePatches`.
• original
  wrong:

  import original from 'mutative'

  correct:

  import { original } from 'mutative'

  A utility function to retrieve the original (non-draft) object from within a draft context. It's a named export.
• IPatch
  wrong:

  import { IPatch } from 'mutative'

  correct:

  import type { IPatch } from 'mutative'

  Used for type hinting when working with patches; should be imported as a type.

Quickstart

Demonstrates how to use `create` to immutably update nested objects and arrays, showcasing efficient partial updates and reference preservation for unchanged parts.

import { create, original } from 'mutative';

interface TodoItem {
  id: number;
  text: string;
  completed: boolean;
}

interface AppState {
  todos: TodoItem[];
  filter: 'all' | 'active' | 'completed';
  user: { name: string; id: string };
}

const initialState: AppState = {
  todos: [
    { id: 1, text: 'Learn Mutative', completed: false },
    { id: 2, text: 'Build Something', completed: true },
  ],
  filter: 'all',
  user: { name: 'John Doe', id: 'user-123' },
};

// Update an item and add a new one
const newState = create(initialState, (draft) => {
  const todoToUpdate = draft.todos.find(todo => todo.id === 1);
  if (todoToUpdate) {
    todoToUpdate.completed = true;
    todoToUpdate.text = 'Learn Mutative (done!)';
  }
  draft.todos.push({ id: 3, text: 'Deploy App', completed: false });
  draft.user.name = 'Jane Doe';
});

console.log('Initial State:', original(initialState));
console.log('New State:', newState);
console.log('Are states different?', initialState !== newState); // true
console.log('Is todos array different?', initialState.todos !== newState.todos); // true
console.log('Are other parts (e.g., filter) unchanged by reference?', initialState.filter === newState.filter); // true
console.log('Original todo 1 text (from initial state):', initialState.todos[0]?.text); // Learn Mutative
console.log('New todo 1 text (from new state):', newState.todos[0]?.text); // Learn Mutative (done!)