Persisting and restoring state

Author: davidkpiano

blog/2023-09-19-persisting-state/index.mdx

@@ -0,0 +1,136 @@
+---
+title: 'Persisting and restoring state in XState'
+description: Learn how to persist and restore your state machine state in XState
+tags: []
+authors: [david]
+date: 2023-09-19
+slug: 2023-09-19-persisting-state
+image: /blog/2023-09-19-persisting-state.png
+---
+
+State machines have a useful feature: modeling state. But what happens when your user closes the browser and comes back later? Or when your server restarts? Or when your user logs out and logs back in? In this article, we'll learn how to persist and restore state in XState.
+
+Note: this article applies to XState v5 beta.
+
+## Quick reference
+
+If you're already familiar with XState, here's a quick reference for persisting and restoring state:
+
+```ts
+import { createActor } from 'xstate';
+import { someMachine } from './someMachine';
+
+// Get the state from localStorage (if it exists)
+const stateString = localStorage.getItem('some-state');
+
+// Create the state from the string (if it exists)
+const restoredState = stateString ? JSON.parse(stateString) : undefined;
+
+const actor = createActor(machine, {
+  // Restore the state (if it exists)
+  state: restoredState,
+});
+
+actor.subscribe(() => {
+  // Persist the state to localStorage
+  const persistedState = actor.getPersistedState();
+  localStorage.setItem('some-state', JSON.stringify(persistedState));
+});
+
+actor.start();
+```
+
+## Persisting and restoring state
+
+Let's say we have a state machine that represents a user's shopping cart:
+
+```ts
+import { createMachine, createActor, assign } from 'xstate';
+
+const checkoutMachine = createMachine({
+  id: 'checkout',
+  initial: 'shopping',
+  context: {
+    items: [],
+  },
+  states: {
+    shopping: {
+      on: {
+        'item.add': {
+          actions: assign({
+            items: ({ context, event }) => {
+              return [...context.items, event.item];
+            },
+          }),
+        },
+        checkout: 'checkingOut',
+      },
+    },
+    checkingOut: {
+      // ...
+    },
+  },
+});
+
+const checkoutActor = createActor(machine, {
+  // ...
+});
+```
+
+You may want to persist the state of this machine so that when the user comes back to the site, the items in their cart are still there, and the step in the checkout process is still the same. To do this, we need to remember to do two things:
+
+- **Persist the state** to some storage (e.g., localStorage, a database, etc.)
+- **Restore the state** from the storage when creating the actor
+
+First, you should determine your [persistence strategy](#persistence-strategies). For this example, we'll use [the `localStorage` API](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage).
+
+Actors created with `createActor` have a `.getPersistedState()` method that returns the state that should be persisted. This state is a plain object that can be serialized to JSON using `JSON.stringify(persistedState)`. Note that this "persisted state" may be slightly different from the `snapshot` state returned from `actor.getSnapshot()`. Since the persisted state is a plain object, you can persist it to any storage that you want, as long as it can be restored as an object.
+
+```ts
+// Read the state to persist from the actor (sync)
+const persistedState = actor.getPersistedState();
+
+// Persist the state to localStorage
+localStorage.setItem('some-state-key', JSON.stringify(persistedState));
+```
+
+Retrieve the persisted state from storage and restore it as an object when creating the actor:
+
+```ts
+const actor = createActor(machine, {
+  // Restore the state (if it exists)
+  state: restoredState,
+});
+
+actor.start();
+```
+
+The actor will start at the `restoredState`, if it exists. If it is `undefined`, the actor will start at the initial state of the actor logic provided to `createActor(logic)`.
+
+## Persistence strategies
+
+For the browser, you can:
+
+- Use [localStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage)
+- Use a client-side database like [IndexedDB](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API)
+- Use [cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies)
+- Use [sessionStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage)
+- Store it in runtime memory (e.g., a global variable or some other persistent store)
+
+For the server, you can:
+
+- Use a database (e.g., [MongoDB](https://www.mongodb.com/), [PostgreSQL](https://www.postgresql.org/), etc.)
+- Use a cache (e.g., [Redis](https://redis.io/))
+- Use cookies or session storage
+
+## Persisting other kinds of actor logic
+
+TODO: all kinds of actor logic can be persisted, not just machines
+
+## Recursive persistence
+
+TODO: all invoked and spawned actors can be persisted, as long as they're named
+
+## Examples
+
+TODO: list example(s) here