Immer

https://immerjs.github.io/immer
Admin
Immer is a tiny JavaScript package that allows developers to work with immutable state in a more...
Tokens:18,859
Snippets:200
Trust Score:8.3
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install Immer with Deno

Source: https://immerjs.github.io/immer/installation

Install Immer using Deno.

```bash
deno install immer
```

--------------------------------

### Install Immer with Yarn

Source: https://immerjs.github.io/immer/installation

Install Immer as a direct dependency using Yarn.

```bash
yarn add immer
```

--------------------------------

### Install Immer with NPM

Source: https://immerjs.github.io/immer/installation

Install Immer as a direct dependency using NPM.

```bash
npm install immer
```

--------------------------------

### Immer Producer Return Examples

Source: https://immerjs.github.io/immer/return

Demonstrates various return scenarios within an Immer producer, including modifying the draft, returning a new state, and incorrect patterns.

```javascript
const userReducer = produce((draft, action) => {
    switch (action.type) {
        case "renameUser":
            // OK: we modify the current state
            draft.users[action.payload.id].name = action.payload.name
            return draft // same as just 'return'
        case "loadUsers":
            // OK: we return an entirely new state
            return action.payload
        case "adduser-1":
            // NOT OK: This doesn't do change the draft nor return a new state!
            // It doesn't modify the draft (it just redeclares it)
            // In fact, this just doesn't do anything at all
            draft = {users: [...draft.users, action.payload]}
            return
        case "adduser-2":
            // NOT OK: modifying draft *and* returning a new state
            draft.userCount += 1
            return {users: [...draft.users, action.payload]}
        case "adduser-3":
            // OK: returning a new state. But, unnecessary complex and expensive
            return {
                userCount: draft.userCount + 1,
                users: [...draft.users, action.payload]
            }
        case "adduser-4":
            // OK: the immer way
            draft.userCount += 1
            draft.users.push(action.payload)
            return
    }
})
```

--------------------------------

### Base State Example

Source: https://immerjs.github.io/immer

This is the initial state structure used for comparison in Immer examples. It represents an array of todo objects.

```javascript
const baseState = [
    {
        title: "Learn TypeScript",
        done: true
    },
    {
        title: "Try Immer",
        done: false
    }
]
```

--------------------------------

### Extracting Current State Snapshot with Immer

Source: https://immerjs.github.io/immer/current

This example demonstrates using `current` to get a snapshot of the draft state. It also shows how `original` and `current` behave with asynchronous operations and future draft modifications.

```javascript
const base = {
    x: 0
}

const next = produce(base, draft => {
    draft.x++
    const orig = original(draft)
    const copy = current(draft)
    console.log(orig.x)
    console.log(copy.x)

    setTimeout(() => {
        // this will execute after the produce has finished!
        console.log(orig.x)
        console.log(copy.x)
    }, 100)

    draft.x++
    console.log(draft.x)
})
console.log(next.x)

// This will print
// 0 (orig.x)
// 1 (copy.x)
// 2 (draft.x)
// 2 (next.x)
// 0 (after timeout, orig.x)
// 1 (after timeout, copy.x)

```

--------------------------------

### useImmerReducer Example

Source: https://immerjs.github.io/immer/example-setstate

Demonstrates how to use the `useImmerReducer` hook from the `use-immer` package in React for state management with Immer.

```javascript
import React, { useCallback } from "react";  
import { useImmerReducer } from "use-immer";  
  
const TodoList = () => {  
  const [todos, dispatch] = useImmerReducer(  
    (draft, action) => {  
      switch (action.type) {  
        case "toggle":  
          const todo = draft.find((todo) => todo.id === action.id);  
          todo.done = !todo.done;  
          break;  
        case "add":  
          draft.push({  
            id: action.id,  
            title: "A new todo",  
            done: false  
          });  
          break;  
        default:  
          break;  
      }  
    },  
    [ /* initial todos */ ]  
  );  
  
  //etc  
  


```

--------------------------------

### Using produceWithPatches to Get State, Patches, and Inverse Patches

Source: https://immerjs.github.io/immer/patches

This snippet demonstrates how to use produceWithPatches to get the next state, the generated patches, and the inverse patches. It's useful for implementing undo/redo features.

```javascript
import {produceWithPatches} from "immer"

const [nextState, patches, inversePatches] = produceWithPatches(
    {
        age: 33
    },
    draft => {
        draft.age++
    }
)

```

```json
;[
    {
        age: 34
    },
    [
        {
            op: "replace",
            path: ["age"],
            value: 34
        }
    ],
    [
        {
            op: "replace",
            path: ["age"],
            value: 33
        }
    ]
]

```

--------------------------------

### Class Example with Immer

Source: https://immerjs.github.io/immer/complex-objects

Demonstrates using Immer with a custom class. The `tick` method produces a new instance with an updated minute value, preserving the class prototype and instance methods.

```javascript
import {immerable, produce} from "immer"  
  
class Clock {  
    [immerable] = true  
  
    constructor(hour, minute) {  
        this.hour = hour  
        this.minute = minute  
    }  
  
    get time() {  
        return `${this.hour}:${this.minute}`  
    }  
  
    tick() {  
        return produce(this, draft => {  
            draft.minute++  
        })  
    }  
}  
  
const clock1 = new Clock(12, 10)  
const clock2 = clock1.tick()  
console.log(clock1.time) // 12:10  
console.log(clock2.time) // 12:11  
console.log(clock2 instanceof Clock) // true  
```

--------------------------------

### Example Immer Patches (Add)

Source: https://immerjs.github.io/immer/patches

Another example of Immer patches, showing an 'add' operation and a 'replace' operation. Immer's patches use an array for the 'path' property.

```json
[
    {"op": "replace", "path": ["profile"], "value": {"name": "Noa", "age": 6}},
    {"op": "add", "path": ["tags", 3], "value": "kiddo"}
]
```

--------------------------------

### Example Immer Patches (Replace)

Source: https://immerjs.github.io/immer/patches

An example of patches generated by Immer, demonstrating a 'replace' operation on a nested path. The 'path' is an array, differing from the JSON patch standard.

```json
[
    {
        "op": "replace",
        "path": ["profile"],
        "value": {"name": "Veria", "age": 5}
    },
    {"op": "remove", "path": ["tags", 3]}
]
```

--------------------------------

### Immer with TypeScript Example

Source: https://immerjs.github.io/immer/typescript

Demonstrates how Immer's TypeScript typings allow modification of draft state within `produce` callbacks while maintaining immutability for the final state. Ensure your state is defined with `readonly` for best results.

```typescript
import {produce} from "immer"  
  
interface State {  
    readonly x: number  
}  
  
// `x` cannot be modified here  
const state: State = {  
    x: 0  
}  
  
const newState = produce(state, draft => {  
    // `x` can be modified here  
    draft.x++  
})  
  
// `newState.x` cannot be modified here  

```

--------------------------------

### Curried Immer Produce Usage

Source: https://immerjs.github.io/immer/curried-produce

This demonstrates the curried form of Immer's `produce`. Pass only the recipe function to `produce` to get a new function that applies the recipe to any state passed to it. This is useful for creating reusable update logic.

```javascript
import {produce} from "immer"

// curried producer:
const toggleTodo = produce((draft, id) => {
    const todo = draft.find(todo => todo.id === id)
    todo.done = !todo.done
})

const baseState = [
    /* as is */
]

const nextState = toggleTodo(baseState, "Immer")
```

--------------------------------

### Immer Array Primitive-Returning Methods: findIndex, some, every

Source: https://immerjs.github.io/immer/array-methods

Methods that return primitive values (numbers, booleans) do not pose tracking issues as primitives are not draftable. This example demonstrates findIndex, some, and every.

```javascript
const base = {
    items: [
        {id: 1, active: true},
        {id: 2, active: false}
    ]
}

const result = produce(base, draft => {
    const index = draft.items.findIndex(item => item.id === 2)
    const hasActive = draft.items.some(item => item.active)
    const allActive = draft.items.every(item => item.active)

    console.log(index) // 1
    console.log(hasActive) // true
    console.log(allActive) // false
})

```

--------------------------------

### Using castImmutable with Immer Produce

Source: https://immerjs.github.io/immer/typescript

This example shows how `castImmutable` can be combined with `produce` to ensure that the return type of `produce` is inferred as immutable, even if the original `baseState` is mutable. This is useful for enforcing immutability guarantees on the resulting state.

```typescript
// a mutable data structure
const baseState = {
    todos: [{
        done: false
    }]
}

const nextState = castImmutable(produce(baseState, _draft => {}))

// inferred type of nextState is now:
// {
//     readonly todos: ReadonlyArray<{
//         readonly done: boolean
//     }> 
// }
```

--------------------------------

### Referential Equality Check with Immer's `original` Helper

Source: https://immerjs.github.io/immer/pitfalls

Draft objects are Proxies and cannot be compared using `===` or `==`. Use the `original` helper to get the base state for comparisons or perform comparisons outside the `produce` function.

```javascript
const remove = produce((list, element) => {
    const index = list.indexOf(element) // this won't work!
    const index = original(list).indexOf(element) // do this instead
    if (index > -1) list.splice(index, 1)
})

const values = [a, b, c]
remove(values, a)
```

--------------------------------

### useState + Immer for Deep State Updates

Source: https://immerjs.github.io/immer/example-setstate

Use Immer's `produce` with `useState` for simplified immutable state updates in React. This is useful for complex state structures where direct mutation is cumbersome. Ensure `immer` is installed and imported.

```javascript
import React, {useCallback, useState} from "react"
import {produce} from "immer"

const TodoList = () => {
    const [todos, setTodos] = useState([
        {
            id: "React",
            title: "Learn React",
            done: true
        },
        {
            id: "Immer",
            title: "Try Immer",
            done: false
        }
    ])

    const handleToggle = useCallback(id => {
        setTodos(
            produce(draft => {
                const todo = draft.find(todo => todo.id === id)
                todo.done = !todo.done
            })
        )
    }, [])

    const handleAdd = useCallback(() => {
        setTodos(
            produce(draft => {
                draft.push({
                    id: "todo_" + Math.random(),
                    title: "A new todo",
                    done: false
                })
            })
        )
    }, [])

    return <div>{/* See CodeSandbox */}</div>
}
```

--------------------------------

### produceWithPatches

Source: https://immerjs.github.io/immer/api

Works the same as `produce`, but instead of just returning the produced object, it returns a tuple, consisting of `[result, patches, inversePatches]`.

```APIDOC
## produceWithPatches

### Description
Works the same as `produce`, but instead of just returning the produced object, it returns a tuple, consisting of `[result, patches, inversePatches]`.

### Usage
```javascript
import { produceWithPatches } from "immer"

const baseState = {
  name: "John Doe",
  age: 30
};

const [nextState, patches, inversePatches] = produceWithPatches(baseState, draftState => {
  draftState.age += 1;
});

console.log(nextState);
// Output: { name: "John Doe", age: 31 }
console.log(patches);
// Output: [ { op: 'replace', path: [ 'age' ], value: 31 } ]
console.log(inversePatches);
// Output: [ { op: 'replace', path: [ 'age' ], value: 30 } ]
```
```

--------------------------------

### Standard Immer Produce Usage

Source: https://immerjs.github.io/immer/curried-produce

This is the standard way to use Immer's `produce` function. It takes the current state and a recipe function to create the next state. Use this when you need to pass the state explicitly.

```javascript
import {produce} from "immer"

function toggleTodo(state, id) {
    return produce(state, draft => {
        const todo = draft.find(todo => todo.id === id)
        todo.done = !todo.done
    })
}

const baseState = [
    {
        id: "JavaScript",
        title: "Learn TypeScript",
        done: true
    },
    {
        id: "Immer",
        title: "Try Immer",
        done: false
    }
]

const nextState = toggleTodo(baseState, "Immer")
```

--------------------------------

### Extract Original State with ImmerJS `original`

Source: https://immerjs.github.io/immer/original

Use the `original` function to get the original object from a draft state. This is helpful for strict equality comparisons, such as when searching nodes in a tree structure.

```javascript
import {original, produce} from "immer"  
  
const baseState = {users: [{name: "Richie"}]}
const nextState = produce(baseState, draftState => {  
    original(draftState.users) // is === baseState.users  
})
```

--------------------------------

### Basic state update with produce

Source: https://immerjs.github.io/immer/produce

Demonstrates how to use produce to add an item and modify an existing item in an array immutably. The base state remains unchanged, while the next state reflects the modifications.

```javascript
import {produce} from "immer"
  
const baseState = [
    {
        title: "Learn TypeScript",
        done: true
    },
    {
        title: "Try Immer",
        done: false
    }
]
  
const nextState = produce(baseState, draftState => {
    draftState.push({title: "Tweet about it"})
    draftState[1].done = true
})
```

--------------------------------

### enableMapSet

Source: https://immerjs.github.io/immer/api

Enables support for `Map` and `Set` collections.

```APIDOC
## enableMapSet

### Description
Enables support for `Map` and `Set` collections.

### Usage
```javascript
import { enableMapSet } from "immer"

enableMapSet();

// Now Map and Set objects can be drafted and mutated.
```
```

--------------------------------

### Redux Reducer with Immer

Source: https://immerjs.github.io/immer/example-setstate

Shows how to use Immer's `produce` function to create a Redux reducer that allows direct state mutation.

```javascript
import {produce} from "immer"  
  
// Reducer with initial state  
const INITIAL_STATE = [  
    /* bunch of todos */  
]  
  
const todosReducer = produce((draft, action) => {  
    switch (action.type) {  
        case "toggle":  
            const todo = draft.find(todo => todo.id === action.id)  
            todo.done = !todo.done  
            break  
        case "add":  
            draft.push({  
                id: action.id,  
                title: "A new todo",  
                done: false  
            })  
            break  
        default:  
            break  
    }  
})
```

--------------------------------

### Enable Immer Array Methods Plugin

Source: https://immerjs.github.io/immer/array-methods

Enable the Array Methods Plugin once at your application's entry point. This adds approximately 2KB to your bundle size.

```javascript
import {enableArrayMethods} from "immer"

enableArrayMethods()
```

--------------------------------

### produceWithPatches

Source: https://immerjs.github.io/immer/patches

The `produceWithPatches` function generates the next state, a list of patches representing the changes, and a list of inverse patches for undo functionality. It has the same signature as `produce` and also supports currying.

```APIDOC
## produceWithPatches

### Description
Generates the next state, patches, and inverse patches.

### Method Signature
`produceWithPatches(originalStateOrFn, patchFn)`

### Parameters
- `originalStateOrFn` (any): The original state or a function that produces the state.
- `patchFn` (function): A function that receives the draft state and applies modifications.

### Returns
A tuple `[nextState, patches, inversePatches]`

### Example
```javascript
import { produceWithPatches } from "immer"

const [nextState, patches, inversePatches] = produceWithPatches(
    { age: 33 },
    draft => {
        draft.age++
    }
)

// nextState will be { age: 34 }
// patches will be [{ op: "replace", path: ["age"], value: 34 }]
// inversePatches will be [{ op: "replace", path: ["age"], value: 33 }]
```
```

--------------------------------

### Import Produce from Immer

Source: https://immerjs.github.io/immer/api

In most cases, the only thing you need to import from Immer is `produce`. In older versions, `produce` was also available as a default export, but this is no longer supported.

```javascript
import {produce} from "immer"

```

--------------------------------

### TypeScript Type Error with Immutable Arrays in Immer

Source: https://immerjs.github.io/immer/typescript

This example demonstrates a common TypeScript error when assigning a read-only array to a mutable draft property within Immer's `produce`. The error occurs because TypeScript perceives the source array as immutable and the draft property as mutable.

```typescript
type Todo = {readonly done: boolean}

type State = {
    readonly finishedTodos: readonly Todo[]
    readonly unfinishedTodos: readonly Todo[]
}

function markAllFinished(state: State) {
    produce(state, draft => {
        draft.finishedTodos = state.unfinishedTodos
    })
}
```

--------------------------------

### applyPatches

Source: https://immerjs.github.io/immer/api

Given a base state or draft, and a set of patches, applies the patches to produce the next state.

```APIDOC
## applyPatches

### Description
Given a base state or draft, and a set of patches, applies the patches to produce the next state.

### Usage
```javascript
import { applyPatches } from "immer"

const baseState = {
  name: "John Doe",
  age: 30
};

const patches = [
  { op: "replace", path: ["age"], value: 31 }
];

const nextState = applyPatches(baseState, patches);

console.log(nextState);
// Output: { name: "John Doe", age: 31 }
```
```

--------------------------------

### Inline Producer Shortcuts with 'void'

Source: https://immerjs.github.io/immer/return

Shows how to use the JavaScript 'void' operator for concise, inline mutations within Immer producers, especially for single or multiple updates.

```javascript
// Single mutation
produce(draft => void (draft.user.age += 1))
```

```javascript
// Multiple mutations
produce(draft => void ((draft.user.age += 1), (draft.user.height = 186)))
```

--------------------------------

### produce

Source: https://immerjs.github.io/immer/api

The core API of Immer. It takes the current state and a recipe function, returning the next state after applying mutations within the recipe.

```APIDOC
## produce

### Description
The core API of Immer. It takes the current state and a recipe function, returning the next state after applying mutations within the recipe.

### Usage
```javascript
import { produce } from "immer"

const baseState = {
  name: "John Doe",
  age: 30
};

const nextState = produce(baseState, draftState => {
  draftState.age += 1;
});

console.log(nextState);
// Output: { name: "John Doe", age: 31 }
```
```

--------------------------------

### nothing

Source: https://immerjs.github.io/immer/api

Value that can be returned from a recipe, to indicate that the value `undefined` should be produced.

```APIDOC
## nothing

### Description
Value that can be returned from a recipe, to indicate that the value `undefined` should be produced.

### Usage
```javascript
import { produce, nothing } from "immer"

const baseState = { value: 10 };
const nextState = produce(baseState, draftState => {
  draftState.value = nothing;
});

console.log(nextState.value); // undefined
```
```

--------------------------------

### Immer CDN Usage (Unpkg)

Source: https://immerjs.github.io/immer/installation

Include Immer in your project via CDN using Unpkg.

```html
<script src="https://unpkg.com/immer"></script>
```

--------------------------------

### Producing and Applying Patches with Immer

Source: https://immerjs.github.io/immer/patches

Demonstrates how to produce patches during state modification and apply them later, including handling inverse patches for undo functionality. Requires enabling patches explicitly in Immer version 6+.

```typescript
import {produce, applyPatches} from "immer"

// version 6
import {enablePatches} from "immer"
enablePatches()

let state = {
    name: "Micheal",
    age: 32
}

// Let's assume the user is in a wizard, and we don't know whether
// his changes should end up in the base state ultimately or not...
let fork = state
// all the changes the user made in the wizard
let changes = []
// the inverse of all the changes made in the wizard
let inverseChanges = []

fork = produce(
    fork,
    draft => {
        draft.age = 33
    },
    // The third argument to produce is a callback to which the patches will be fed
    (patches, inversePatches) => {
        changes.push(...patches)
        inverseChanges.push(...inversePatches)
    }
)

// In the meantime, our original state is replaced, as, for example,
// some changes were received from the server
state = produce(state, draft => {
    draft.name = "Michel"
})

// When the wizard finishes (successfully) we can replay the changes that were in the fork onto the *new* state!
state = applyPatches(state, changes)

// state now contains the changes from both code paths!
expect(state).toEqual({
    name: "Michel", // changed by the server
    age: 33 // changed by the wizard
})

// Finally, even after finishing the wizard, the user might change his mind and undo his changes...
state = applyPatches(state, inverseChanges)
expect(state).toEqual({
    name: "Michel", // Not reverted
    age: 32 // Reverted
})
```

--------------------------------

### Updating Maps with Immer Producers

Source: https://immerjs.github.io/immer/map-set

Demonstrates how to create and update Map objects using Immer's `produce` function. Each modification within a producer results in a new Map instance. Attempts to mutate a produced Map outside of a producer will throw an error.

```javascript
test("Producers can update Maps", () => {
    const usersById_v1 = new Map()

    const usersById_v2 = produce(usersById_v1, draft => {
        // Modifying a map results in a new map
        draft.set("michel", {name: "Michel Weststrate", country: "NL"})
    })

    const usersById_v3 = produce(usersById_v2, draft => {
        // Making a change deep inside a map, results in a new map as well!
        draft.get("michel").country = "UK"
    })

    // We got a new map each time!
    expect(usersById_v2).not.toBe(usersById_v1)
    expect(usersById_v3).not.toBe(usersById_v2)
    // With different content obviously
    expect(usersById_v1).toMatchInlineSnapshot(`Map {}`)
    expect(usersById_v2).toMatchInlineSnapshot(`
        Map {
          "michel" => Object {
            "country": "NL",
            "name": "Michel Weststrate",
          },
        }
    `)
    expect(usersById_v3).toMatchInlineSnapshot(`
        Map {
          "michel" => Object {
            "country": "UK",
            "name": "Michel Weststrate",
          },
        }
    `)
    // The old one was never modified
    expect(usersById_v1.size).toBe(0)
    // And trying to change a Map outside a producers is going to: NO!
    expect(() => usersById_v3.clear()).toThrowErrorMatchingInlineSnapshot(
        `"This object has been frozen and should not be mutated"`
    )
})
```

--------------------------------

### Immer constructor

Source: https://immerjs.github.io/immer/api

Constructor that can be used to create a second "immer" instance, exposing all APIs listed in this instance, that doesn't share its settings with the global instance.

```APIDOC
## Immer constructor

### Description
Constructor that can be used to create a second "immer" instance (exposing all APIs listed in this instance), that doesn't share its settings with global instance.

### Usage
```javascript
import { Immer } from "immer"

const immerInstance = new Immer();
const produce = immerInstance.produce;

const baseState = { count: 0 };
const nextState = produce(baseState, draft => {
  draft.count++;
});

console.log(nextState); // { count: 1 }
```
```

--------------------------------

### Async Update with createDraft and finishDraft

Source: https://immerjs.github.io/immer/async

Demonstrates how createDraft and finishDraft can be used to handle asynchronous updates to a draft. Note that this pattern is generally discouraged due to potential race conditions where other updates to the original state might be missed during the async operation. It's recommended to fetch data first before creating the draft.

```javascript
import {createDraft, finishDraft} from "immer"

const user = {
    name: "michel",
    todos: []
}

const draft = createDraft(user)
draft.todos = await (await window.fetch("http://host/" + draft.name)).json()
const loadedUser = finishDraft(draft)
```

--------------------------------

### Immer CDN Usage (JSDelivr)

Source: https://immerjs.github.io/immer/installation

Include Immer in your project via CDN using JSDelivr.

```html
<script src="https://cdn.jsdelivr.net/npm/immer"></script>
```

--------------------------------

### current

Source: https://immerjs.github.io/immer/api

Given a draft object, takes a snapshot of the current state of the draft.

```APIDOC
## current

### Description
Given a draft object (doesn't have to be a tree root), takes a snapshot of the current state of the draft.

### Usage
```javascript
import { produce, current } from "immer"

const baseState = {
  name: "John Doe",
  age: 30
};

const nextState = produce(baseState, draftState => {
  draftState.age += 1;
  console.log(current(draftState)); // Logs the current state of the draft
});

console.log(nextState);
// Output: { name: "John Doe", age: 31 }
```
```

--------------------------------

### enablePatches

Source: https://immerjs.github.io/immer/api

Enables support for JSON patches.

```APIDOC
## enablePatches

### Description
Enables support for JSON patches.

### Usage
```javascript
import { enablePatches } from "immer"

enablePatches();

// Now produceWithPatches will generate standard JSON patches.
```
```

--------------------------------

### Enable Map and Set Support in Immer

Source: https://immerjs.github.io/immer/installation

Enable Immer to operate on native Map and Set collections. This must be called once in your application's entry point before using `produce` with Maps or Sets.

```javascript
// In your application's entrypoint  
import {enableMapSet} from "immer"  
  
enableMapSet()  
  
// ...later  
import {produce} from "immer"  
  
const usersById_v1 = new Map([
    ["michel", {name: "Michel Weststrate", country: "NL"}]
])  
  
const usersById_v2 = produce(usersById_v1, draft => {
    draft.get("michel").country = "UK"
})
  
expect(usersById_v1.get("michel").country).toBe("NL")  
expect(usersById_v2.get("michel").country).toBe("UK")  
```

--------------------------------

### useReducer with Immer for State Management

Source: https://immerjs.github.io/immer/example-setstate

Combine useReducer with Immer's produce function to manage state immutably. This pattern is useful for complex state logic where actions need to modify nested state.

```javascript
import React, {useCallback, useReducer} from "react"
import {produce} from "immer"

const TodoList = () => {
    const [todos, dispatch] = useReducer(
        produce((draft, action) => {
            switch (action.type) {
                case "toggle":
                    const todo = draft.find(todo => todo.id === action.id)
                    todo.done = !todo.done
                    break
                case "add":
                    draft.push({
                        id: action.id,
                        title: "A new todo",
                        done: false
                    })
                    break
                default:
                    break
            }
        }),
        [
            /* initial todos */
        ]
    )

    const handleToggle = useCallback(id => {
        dispatch({
            type: "toggle",
            id
        })
    }, [])

    const handleAdd = useCallback(() => {
        dispatch({
            type: "add",
            id: "todo_" + Math.random()
        })
    }, [])

    // etc
}


```

--------------------------------

### original

Source: https://immerjs.github.io/immer/api

Given a draft object, returns the original object at the same path in the original state tree, if present.

```APIDOC
## original

### Description
Given a draft object (doesn't have to be a tree root), returns the original object at the same path in the original state tree, if present.

### Usage
```javascript
import { produce, original } from "immer"

const baseState = {
  user: {
    name: "John Doe"
  }
};

const nextState = produce(baseState, draftState => {
  const originalUser = original(draftState.user);
  console.log(originalUser === baseState.user); // true
});
```
```

--------------------------------

### Immer Array Methods Plugin Performance

Source: https://immerjs.github.io/immer/array-methods

Compares proxy trap invocations with and without the Immer Array Methods plugin. The plugin significantly reduces proxy creations by only creating proxies for mutated elements or those matching filtering predicates.

```javascript
// Without plugin: ~3000+ proxy trap invocations  
// With plugin: ~10-20 proxy trap invocations  
const result = produce(largeState, draft => {
    const filtered = draft.items.filter(x => x.value > threshold)  
    // Only items you mutate get proxied  
    filtered.forEach(item => {
        item.processed = true  
    })
})
```

--------------------------------

### Mutating Array Methods with Immer

Source: https://immerjs.github.io/immer/array-methods

Demonstrates the use of mutating array methods like push, sort, and reverse within an Immer producer after enabling the Array Methods Plugin. These methods operate directly on the draft's internal copy.

```javascript
import {produce, enableArrayMethods} from "immer"

enableArrayMethods()

const base = {items: [3, 1, 4, 1, 5]}

const result = produce(base, draft => {
    draft.items.push(9) // Adds 9 to end
    draft.items.sort() // Sorts: [1, 1, 3, 4, 5, 9]
    draft.items.reverse() // Reverses: [9, 5, 4, 3, 1, 1]
})
```

--------------------------------

### Verifying immutability after produce

Source: https://immerjs.github.io/immer/produce

Verifies that the base state is unmodified and the next state contains the changes after using produce. It also shows that unchanged parts of the state are structurally shared.

```javascript
// the new item is only added to the next state,
// base state is unmodified
expect(baseState.length).toBe(2)
expect(nextState.length).toBe(3)

// same for the changed 'done' prop
expect(baseState[1].done).toBe(false)
expect(nextState[1].done).toBe(true)

// unchanged data is structurally shared
expect(nextState[0]).toBe(baseState[0])
// ...but changed data isn't.
expect(nextState[1]).not.toBe(baseState[1])
```

--------------------------------

### enableArrayMethods

Source: https://immerjs.github.io/immer/api

Enables optimized array method handling for improved performance with array-heavy operations.

```APIDOC
## enableArrayMethods

### Description
Enables optimized array method handling for improved performance with array-heavy operations.

### Usage
```javascript
import { enableArrayMethods } from "immer"

enableArrayMethods();

// Now array methods like push, pop, splice are optimized within Immer recipes.
```
```

--------------------------------

### Specific Immer Version CDN Usage

Source: https://immerjs.github.io/immer/installation

Include a specific version of Immer via CDN, using Unpkg for production or development builds.

```html
https://unpkg.com/immer@6.0.3/dist/immer.umd.production.min.js
```

--------------------------------

### Producing Undefined with 'nothing' Token

Source: https://immerjs.github.io/immer/return

Illustrates how to explicitly return 'undefined' from an Immer producer using the 'nothing' token, differentiating it from not returning anything.

```javascript
import {produce, nothing} from "immer"

const state = {
    hello: "world"
}

produce(state, draft => {}) 
produce(state, draft => undefined)
// Both return the original state: { hello: "world"}

produce(state, draft => nothing)
// Produces a new state, 'undefined'
```

--------------------------------

### Updating Immutable State With Immer

Source: https://immerjs.github.io/immer

Shows how to update immutable state using Immer's `produce` function. Changes are made to a draft object within a recipe function, and Immer handles the creation of the new state.

```javascript
import {produce} from "immer"

const nextState = produce(baseState, draft => {
    draft[1].done = true
    draft.push({title: "Tweet about it"})
})
```

--------------------------------

### ImmerJS Array Methods: forEach and map (Not Overridden)

Source: https://immerjs.github.io/immer/array-methods

Demonstrates the behavior of `forEach` and `map` when used with ImmerJS. These methods are not overridden, meaning callbacks receive drafts, and mutations to the returned values (like `mapped[0].count`) correctly propagate back to the draft.

```javascript
const base = {
    items: [
        {id: 1, value: 10, nested: {count: 0}},
        {id: 2, value: 20, nested: {count: 0}}
    ]
}

const result = produce(base, draft => {
    // forEach receives drafts - mutations work normally
    draft.items.forEach(item => {
        item.value *= 2
    })

    // map is NOT overridden - callbacks receive drafts
    // The returned array items are also drafts (extracted from draft.items)
    const mapped = draft.items.map(item => item.nested)
    // Mutations to the result array propagate back
    mapped[0].count = 999 // ✅ This affects draft.items[0].nested.count
})

console.log(result.items[0].nested.count) // 999

```

--------------------------------

### Enable ES5 Fallback Implementation in Immer

Source: https://immerjs.github.io/immer/installation

Explicitly enable Immer's ES5 compatible fallback implementation for older JavaScript environments that do not support Proxies. This is required for Immer versions 6 and later.

```javascript
enableES5()
```

--------------------------------

### createDraft

Source: https://immerjs.github.io/immer/api

Given a base state, creates a mutable draft for which any modifications will be recorded. This is useful for asynchronous operations.

```APIDOC
## createDraft

### Description
Given a base state, creates a mutable draft for which any modifications will be recorded. This is useful for asynchronous operations.

### Usage
```javascript
import { createDraft, finishDraft } from "immer"

const baseState = {
  name: "John Doe",
  age: 30
};

const draft = createDraft(baseState);
draft.age += 1;

const nextState = finishDraft(draft);

console.log(nextState);
// Output: { name: "John Doe", age: 31 }
```
```

--------------------------------

### Immer Import Size Report

Source: https://immerjs.github.io/immer/installation

A breakdown of import sizes for Immer and its features, generated by npmjs.com/package/import-size.

```plaintext
Import size report for immer:  
┌───────────────────────┬───────────┬────────────┬───────────┐  
│ (index)               │ just this │ cumulative │ increment │  
├───────────────────────┼───────────┼────────────┼───────────┤  
│ import * from 'immer' │ 6908      │ 0          │ 0         │  
│ produce               │ 4183      │ 4183       │ 0         │  
│ enableMapSet          │ 4971      │ 4980       │ 797       │  
│ enablePatches         │ 5335      │ 6097       │ 1117      │  
│ enableArrayMethods    │ 4768      │ 6659       │ 562       │  
└───────────────────────┴───────────┴────────────┴───────────┘  
(this report was generated by npmjs.com/package/import-size)
```

--------------------------------

### Updating Immutable State Without Immer

Source: https://immerjs.github.io/immer

Demonstrates how to update an immutable array by manually creating shallow copies at each affected level. This approach requires careful handling of spread operations and can be error-prone.

```javascript
const nextState = baseState.slice() // shallow clone the array
nextState[1] = {
    // replace element 1...
    ...nextState[1], // with a shallow clone of element 1
    done: true // ...combined with the desired update
}
// since nextState was freshly cloned, using push is safe here,
// but doing the same thing at any arbitrary time in the future would
// violate the immutability principles and introduce a bug!
nextState.push({title: "Tweet about it"})
```

--------------------------------

### Enable Array Methods Plugin

Source: https://immerjs.github.io/immer/performance

Enables a plugin to optimize array operations like filter, find, some, every, and slice by avoiding proxy creation for every element during iteration. Use this for applications with significant array iteration within producers.

```javascript
import {enableArrayMethods} from "immer"
enableArrayMethods()
```

--------------------------------

### Immer Array Subset Operations: filter, find, slice

Source: https://immerjs.github.io/immer/array-methods

Subset operations like filter, find, and slice return draft proxies. Mutations to these returned items will affect the draft state. Use these when you need to select existing items and potentially modify them within the Immer producer.

```javascript
const base = {
    items: [
        {id: 1, value: 10},
        {id: 2, value: 20},
        {id: 3, value: 30}
    ]
}

const result = produce(base, draft => {
    // filter returns drafts - mutations track back to original
    const filtered = draft.items.filter(item => item.value > 15)
    filtered[0].value = 999 // This WILL affect draft.items[1]

    // find returns a draft - mutations track back
    const found = draft.items.find(item => item.id === 3)
    if (found) {
        found.value = 888 // This WILL affect draft.items[2]
    }

    // slice returns drafts
    const sliced = draft.items.slice(0, 2)
    sliced[0].value = 777 // This WILL affect draft.items[0]
})

console.log(result.items[0].value) // 777
console.log(result.items[1].value) // 999
console.log(result.items[2].value) // 888

```

--------------------------------

### Array Methods Plugin: Base Values in Callbacks

Source: https://immerjs.github.io/immer/pitfalls

When using Immer's Array Methods Plugin, callbacks for overridden methods like filter receive base values, not drafts. This optimizes performance by avoiding proxy creation for iterated elements. Direct mutation within these callbacks is not tracked; use the returned result which contains drafts for mutations.

```javascript
import {enableArrayMethods, produce} from "immer"
enableArrayMethods()

produce(state, draft => {
    draft.items.filter(item => {
        // `item` is a base value here, NOT a draft  
        // Reading works fine:
        return item.value > 10

        // But direct mutation here won't be tracked:
        // item.value = 999  // ❌ Won't affect the draft!
    })

    // Instead, use the returned result (which contains drafts):
    const filtered = draft.items.filter(item => item.value > 10)
    filtered[0].value = 999 // ✅ This works - filtered[0] is a draft
})
```

--------------------------------

### setAutoFreeze

Source: https://immerjs.github.io/immer/api

Enables / disables automatic freezing of the trees produced. By default enabled.

```APIDOC
## setAutoFreeze

### Description
Enables / disables automatic freezing of the trees produced. By default enabled.

### Usage
```javascript
import { produce, setAutoFreeze } from "immer"

setAutoFreeze(false);

const baseState = { count: 0 };
const nextState = produce(baseState, draft => {
  draft.count++;
});

console.log(Object.isFrozen(nextState)); // false

setAutoFreeze(true);
```
```

--------------------------------

### finishDraft

Source: https://immerjs.github.io/immer/api

Given an draft created using `createDraft`, seals the draft and produces and returns the next immutable state that captures all the changes.

```APIDOC
## finishDraft

### Description
Given an draft created using `createDraft`, seals the draft and produces and returns the next immutable state that captures all the changes.

### Usage
```javascript
import { createDraft, finishDraft } from "immer"

const baseState = {
  name: "John Doe",
  age: 30
};

const draft = createDraft(baseState);
draft.age += 1;

const nextState = finishDraft(draft);

console.log(nextState);
// Output: { name: "John Doe", age: 31 }
```
```

--------------------------------

### Set Use Strict Iteration

Source: https://immerjs.github.io/immer/performance

Configures Immer to use strict iteration, which includes symbols and non-enumerable properties. The default is loose iteration (false) for better performance. Only enable strict iteration if you specifically need to track symbol or non-enumerable properties.

```javascript
import {setUseStrictIteration} from "immer"

// Default: false (loose iteration for better performance)
setUseStrictIteration(false)
```

--------------------------------

### freeze

Source: https://immerjs.github.io/immer/api

Freezes draftable objects. Returns the original object. By default freezes shallowly, but if the second argument is `true` it will freeze recursively.

```APIDOC
## freeze

### Description
Freezes draftable objects. Returns the original object. By default freezes shallowly, but if the second argument is `true` it will freeze recursively.

### Usage
```javascript
import { freeze } from "immer"

const obj = { a: 1 };
const frozenObj = freeze(obj, true);

console.log(frozenObj === obj); // true
// frozenObj is now deeply frozen
```
```

--------------------------------

### useImmer Hook for State Management

Source: https://immerjs.github.io/immer/example-setstate

Use the useImmer hook from the 'use-immer' package to simplify state updates in React components. It automatically wraps updater functions with Immer's produce, allowing direct mutation of the draft state.

```javascript
import React, { useCallback } from "react";
import { useImmer } from "use-immer";

const TodoList = () => {
  const [todos, setTodos] = useImmer([
    {
      id: "React",
      title: "Learn React",
      done: true
    },
    {
      id: "Immer",
      title: "Try Immer",
      done: false
    }
  ]);

  const handleToggle = useCallback((id) => {
    setTodos((draft) => {
      const todo = draft.find((todo) => todo.id === id);
      todo.done = !todo.done;
    });
  }, []);

  const handleAdd = useCallback(() => {
    setTodos((draft) => {
      draft.push({
        id: "todo_" + Math.random(),
        title: "A new todo",
        done: false
      });
    });
  }, []);

  // etc


```

--------------------------------

### setUseStrictShallowCopy

Source: https://immerjs.github.io/immer/api

Can be used to enable strict shallow copy. If enabled, Immer copies non-enumerable properties as much as possible.

```APIDOC
## setUseStrictShallowCopy

### Description
Can be used to enable strict shallow copy. If enabled, Immer copies non-enumerable properties as much as possible.

### Usage
```javascript
import { produce, setUseStrictShallowCopy } from "immer"

// Example demonstrating effect (requires setup of non-enumerable property)
// setUseStrictShallowCopy(true);
// ... produce logic ...
// setUseStrictShallowCopy(false);
```
```

--------------------------------

### Correctly Using Nested Producers in Immer

Source: https://immerjs.github.io/immer/pitfalls

When using nested `produce` calls, the result of the inner producer must be explicitly assigned or returned to be incorporated into the outer draft. Directly nesting `produce` without handling its return value will not apply changes.

```javascript
produce(state, draft => {
    draft.user = produce(draft.user, userDraft => {
        userDraft.name += "!"
    })
})
```

--------------------------------

### setUseStrictIteration

Source: https://immerjs.github.io/immer/api

Controls iteration behavior: pass `false` for loose iteration (enumerable properties only, better performance) or `true` for strict iteration (includes symbols and non-enumerable properties). By default disabled (loose iteration).

```APIDOC
## setUseStrictIteration

### Description
Controls iteration behavior: pass `false` for loose iteration (enumerable properties only, better performance) or `true` for strict iteration (includes symbols and non-enumerable properties). By default disabled (loose iteration).

### Usage
```javascript
import { produce, setUseStrictIteration } from "immer"

// Example demonstrating effect (requires setup of symbols/non-enumerable properties)
// setUseStrictIteration(true);
// ... produce logic ...
// setUseStrictIteration(false);
```
```

--------------------------------

### Defining Additional Arguments in Curried Producers

Source: https://immerjs.github.io/immer/typescript

When a curried producer has no initial state and its state generic is explicitly set, define the types of any additional arguments as a tuple type.

```typescript
const toggler = produce<Todo, [boolean]>((draft, newState) => {  
    draft.done = newState  
})  
  
// typeof toggler = (state: Todo, newState: boolean) => Todo
```
Tokens:
Raw