xstate-migrate

xstate-migrate is a migration library for persisted XState machines, designed to facilitate state machine migrations when updating your XState configurations. This library generates and applies migration patches to ensure seamless transitions between different versions of your state machines.

Features

• Generate migration patches for XState machines
• Apply migration patches to persisted snapshots
• Handle nested and parallel state machines
• Support for adding and removing context properties

Installation

You can install xstate-migrate using npm:

npm install xstate-migrate

Usage

Generating Migrations

Use the generateMigrations function to generate a set of migration patches between the current and a new version of an XState machine.

import { createMachine, createActor } from 'xstate';
import { xstateMigrate } from 'xstate-migrate';

// Define your initial state machine
const machineV1 = createMachine({
  types: {
    input: {} as { initialData: string },
    context: {} as { data: string },
  },
  id: 'example',
  initial: 'idle',
  context: ({ input }) => ({ data: input.initialData }),
  states: {
    idle: { on: { NEXT: 'active' } },
    active: {},
  },
});

// Create an actor and get the initial snapshot
const actor = createActor(machineV1, {
  input: { initialData: 'Hello' },
}).start();
actor.send({ type: 'NEXT' });
const persistedSnapshot = actor.getSnapshot();

// Define your new state machine
const machineV2 = createMachine({
  types: {
    input: {} as { initialData: string },
    context: {} as { data: string; newData: number },
  },
  id: 'example',
  initial: 'idle',
  context: ({ input }) => ({ data: input.initialData, newData: 0 }),
  states: {
    idle: { on: { NEXT: 'active' } },
    active: {},
    newState: {},
  },
});

// Generate the migration patches
const migrations = xstateMigrate.generateMigrations(machineV2, persistedSnapshot, {
  initialData: 'Hello',
});

console.log(migrations);
/*
[
  { op: 'add', path: '/context/newData', value: 0 }
]
*/

Applying Migrations

Use the applyMigrations function to apply a set of migration patches to a persisted snapshot.

import { xstateMigrate } from 'xstate-migrate';

const persistedSnapshot = {
  context: { data: 'Hello' },
  value: 'active',
};

const migrations = [{ op: 'add', path: '/context/newData', value: 0 }];

const migratedSnapshot = xstateMigrate.applyMigrations(persistedSnapshot, migrations);

console.log(migratedSnapshot);
/*
{
  context: { data: 'Hello', newData: 0 },
  value: 'active'
}
*/

How Migrations Work

• Migrations are generated as a list of JSON Patch operations that describe the changes needed to update a persisted snapshot to match a new state machine configuration.
• The operations can include adding, removing, or replacing properties in the state machine's context or value.
• The generateMigrations function compares the initial snapshot of the new state machine with the persisted snapshot and creates the necessary operations.
• Existing context values are preserved during the migration process.
• The applyMigrations function applies these operations to the persisted snapshot, updating it to reflect the new state machine configuration.

API

xstateMigrate.generateMigrations<TMachine extends AnyStateMachine>(machine: TMachine, persistedSnapshot: AnyMachineSnapshot, input?: InputFrom<TMachine>): Operation[]

Generates a list of migration patches for updating a persisted snapshot to match the new state machine configuration.

• machine: The new version of the state machine.
• persistedSnapshot: The persisted snapshot of the previous state machine.
• input (optional): The input for the new state machine, matching its input type.

xstateMigrate.applyMigrations(persistedSnapshot: AnyMachineSnapshot, migrations: Operation[]): AnyMachineSnapshot

Applies a list of migration patches to a persisted snapshot.

• persistedSnapshot: The persisted snapshot to be migrated.
• migrations: The list of migration patches to apply.

Migration Format

The migrations generated by xstate-migrate follow the JSON Patch standard (RFC 6902). JSON Patch is a format for describing changes to a JSON document. It is a JSON document itself that contains an array of operations. Each operation is an object with the following properties:

• op: The operation to perform. Can be one of add, remove, replace, move, copy, or test.
• path: A JSON Pointer that indicates the location in the target document where the operation is to be performed.
• value: The value to be used within the operations add, replace, and test.

Example migration:

[{ "op": "add", "path": "/context/newProp", "value": "default" }]

License

This project is licensed under the MIT License.