@xstate/immer

This package contains utilities for using Immer with XState.

• Read the full documentation in the XState docs.
• Read our contribution guidelines.

Quick start

Included in @xstate/immer:

• assign() - an Immer action that allows you to immutably assign to machine context in a convenient way
• createUpdater() - a useful function that allows you to cohesively define a context update event event creator and assign action, all together. (See an example below)

1. Install immer, xstate, @xstate/immer:

npm install immer xstate @xstate/immer

Note: You don't need to import anything from immer; it is a peer-dependency of @xstate/immer, so it must be installed.

2. Import the Immer utilities:

import { createMachine, interpret } from 'xstate';
import { assign, createUpdater } from '@xstate/immer';

const levelUpdater = createUpdater('UPDATE_LEVEL', (ctx, { input }) => {
  ctx.level = input;
});

const toggleMachine = createMachine({
  id: 'toggle',
  context: {
    count: 0,
    level: 0
  },
  initial: 'inactive',
  states: {
    inactive: {
      on: {
        TOGGLE: {
          target: 'active',
          // Immutably update context the same "mutable"
          // way as you would do with Immer!
          actions: assign((ctx) => ctx.count++)
        }
      }
    },
    active: {
      on: {
        TOGGLE: {
          target: 'inactive'
        },
        // Use the updater for more convenience:
        [levelUpdater.type]: {
          actions: levelUpdater.action
        }
      }
    }
  }
});

const toggleService = interpret(toggleMachine)
  .onTransition((state) => {
    console.log(state.context);
  })
  .start();

toggleService.send('TOGGLE');
// { count: 1, level: 0 }

toggleService.send(levelUpdater.update(9));
// { count: 1, level: 9 }

toggleService.send('TOGGLE');
// { count: 2, level: 9 }

toggleService.send(levelUpdater.update(-100));
// Notice how the level is not updated in 'inactive' state:
// { count: 2, level: 9 }