[v5] Recursive persistence

.changeset/shy-cobras-ring.md

@@ -0,0 +1,2 @@
+---
+---

README.md

@@ -218,8 +218,9 @@ const lightMachine = createMachine({
 
 const currentState = 'green';
 
-const nextState = lightMachine.transition(currentState, { type: 'TIMER' })
-  .value;
+const nextState = lightMachine.transition(currentState, {
+  type: 'TIMER'
+}).value;
 
 // => 'yellow'
 ```
@@ -278,8 +279,9 @@ const lightMachine = createMachine({
 
 const currentState = 'yellow';
 
-const nextState = lightMachine.transition(currentState, { type: 'TIMER' })
-  .value;
+const nextState = lightMachine.transition(currentState, {
+  type: 'TIMER'
+}).value;
 // => {
 //   red: 'walk'
 // }
@@ -374,8 +376,9 @@ const wordMachine = createMachine({
   }
 });
 
-const boldState = wordMachine.transition('bold.off', { type: 'TOGGLE_BOLD' })
-  .value;
+const boldState = wordMachine.transition('bold.off', {
+  type: 'TOGGLE_BOLD'
+}).value;
 
 // {
 //   bold: 'on',

docs/fr/guides/communication.md

@@ -131,23 +131,24 @@ The resolved data is placed into a `'done.invoke.<id>'` event, under the `data`
 If a Promise rejects, the `onError` transition will be taken with a `{ type: 'error.platform' }` event. The error data is available on the event's `data` property:
 
 ```js
-const search = (context, event) => new Promise((resolve, reject) => {
-  if (!event.query.length) {
-    return reject('No query specified');
-    // or:
-    // throw new Error('No query specified');
-  }
+const search = (context, event) =>
+  new Promise((resolve, reject) => {
+    if (!event.query.length) {
+      return reject('No query specified');
+      // or:
+      // throw new Error('No query specified');
+    }
 
-  return resolve(getSearchResults(event.query));
-});
+    return resolve(getSearchResults(event.query));
+  });
 
 // ...
 const searchMachine = createMachine({
   id: 'search',
   initial: 'idle',
   context: {
     results: undefined,
-    errorMessage: undefined,
+    errorMessage: undefined
   },
   states: {
     idle: {

docs/zh/guides/communication.md

@@ -131,23 +131,24 @@ const userMachine = createMachine({
 如果 Promise 拒绝，则将使用 `{ type: 'error.platform' }` 事件进行 `onError` 转换。 错误数据在事件的 `data` 属性中可用：
 
 ```js
-const search = (context, event) => new Promise((resolve, reject) => {
-  if (!event.query.length) {
-    return reject('No query specified');
-    // or:
-    // throw new Error('No query specified');
-  }
+const search = (context, event) =>
+  new Promise((resolve, reject) => {
+    if (!event.query.length) {
+      return reject('No query specified');
+      // or:
+      // throw new Error('No query specified');
+    }
 
-  return resolve(getSearchResults(event.query));
-});
+    return resolve(getSearchResults(event.query));
+  });
 
 // ...
 const searchMachine = createMachine({
   id: 'search',
   initial: 'idle',
   context: {
     results: undefined,
-    errorMessage: undefined,
+    errorMessage: undefined
   },
   states: {
     idle: {

packages/core/src/State.ts

@@ -16,6 +16,7 @@ import type {
   EventObject,
   HistoryValue,
   MachineContext,
+  PersistedMachineState,
   Prop,
   SCXML,
   StateConfig,
@@ -124,7 +125,7 @@ export class State<
       return stateValue;
     }
 
-    const _event = initEvent as SCXML.Event<TEvent>;
+    const _event = initEvent as SCXML.Event<TEvent>; // TODO: fix
 
     const configuration = getConfiguration(
       getStateNodes(machine.root, stateValue)
@@ -167,7 +168,7 @@ export class State<
     this.configuration =
       config.configuration ??
       Array.from(getConfiguration(getStateNodes(machine.root, config.value)));
-    this.transitions = config.transitions;
+    this.transitions = config.transitions as any;
     this.children = config.children;
 
     this.value = getStateValue(machine.root, this.configuration);
@@ -287,3 +288,24 @@ export function cloneState<TState extends AnyState>(
     state.machine
   ) as TState;
 }
+
+export function getPersistedState<TState extends AnyState>(
+  state: TState
+): PersistedMachineState<TState> {
+  const { configuration, transitions, tags, machine, children, ...jsonValues } =
+    state;
+
+  const childrenJson: Partial<PersistedMachineState<any>['children']> = {};
+
+  for (const id in children) {
+    childrenJson[id] = {
+      state: children[id].getPersistedState?.(),
+      src: children[id].src
+    };
+  }
+
+  return {
+    ...jsonValues,
+    children: childrenJson
+  } as PersistedMachineState<TState>;
+}

packages/core/src/StateMachine.ts

@@ -1,8 +1,9 @@
-import { initEvent } from './actions.js';
+import { error, initEvent } from './actions.js';
 import { STATE_DELIMITER } from './constants.js';
 import { createSpawner } from './spawn.js';
-import { isStateConfig, State } from './State.js';
+import { getPersistedState, State } from './State.js';
 import { StateNode } from './StateNode.js';
+import { interpret } from './interpreter.js';
 import {
   getConfiguration,
   getInitialConfiguration,
@@ -41,7 +42,8 @@ import type {
   StateConfig,
   StateMachineDefinition,
   StateValue,
-  TransitionDefinition
+  TransitionDefinition,
+  PersistedMachineState
 } from './types.js';
 import { isFunction, isSCXMLErrorEvent, toSCXMLEvent } from './utils.js';
 
@@ -88,18 +90,28 @@ export class StateMachine<
     ActorBehavior<
       TEvent | SCXML.Event<TEvent>,
       State<TContext, TEvent, TResolvedTypesMeta>,
-      State<TContext, TEvent, TResolvedTypesMeta>
+      State<TContext, TEvent, TResolvedTypesMeta>,
+      PersistedMachineState<State<TContext, TEvent, TResolvedTypesMeta>>
     >
 {
   private _contextFactory: (stuff: { spawn: Spawner }) => TContext;
+  // TODO: this getter should be removed
   public get context(): TContext {
     return this.getContextAndActions()[0];
   }
-  private getContextAndActions(): [TContext, InvokeActionObject[]] {
+  private getContextAndActions(
+    actorCtx?: ActorContext<any, any>
+  ): [TContext, InvokeActionObject[]] {
     const actions: InvokeActionObject[] = [];
     // TODO: merge with this.options.context
     const context = this._contextFactory({
-      spawn: createSpawner(this, null as any, null as any, actions) // TODO: fix types
+      spawn: createSpawner(
+        actorCtx?.self,
+        this,
+        null as any,
+        null as any,
+        actions
+      ) // TODO: fix types
     });
 
     return [context, actions];
@@ -151,7 +163,6 @@ export class StateMachine<
             partialContext
           ) as TContext;
         }; // TODO: fix types
-    // this.context = resolveContext(config.context, options?.context);
     this.delimiter = this.config.delimiter || STATE_DELIMITER;
     this.version = this.config.version;
     this.schema = this.config.schema ?? ({} as any as this['schema']);
@@ -315,13 +326,13 @@ export class StateMachine<
   private getPreInitialState(
     actorCtx: ActorContext<any, any> | undefined
   ): State<TContext, TEvent, TResolvedTypesMeta> {
-    const [context, actions] = this.getContextAndActions();
+    const [context, actions] = this.getContextAndActions(actorCtx);
     const config = getInitialConfiguration(this.root);
     const preInitial = this.resolveState(
       this.createState({
         value: {}, // TODO: this is computed in state constructor
         context,
-        _event: initEvent as SCXML.Event<TEvent>,
+        _event: initEvent as SCXML.Event<TEvent>, // TODO: fix
         _sessionid: actorCtx?.sessionId ?? undefined,
         actions: [],
         meta: undefined,
@@ -374,16 +385,24 @@ export class StateMachine<
 
     return macroState;
   }
+
   public start(
     state: State<TContext, TEvent, TResolvedTypesMeta>,
     actorCtx: ActorContext<TEvent, State<TContext, TEvent, TResolvedTypesMeta>>
-  ): State<TContext, TEvent, TResolvedTypesMeta> {
-    // When starting from a restored state, execute the actions
+  ): void {
     state.actions.forEach((action) => {
       action.execute?.(actorCtx);
     });
-
-    return state;
+    Object.values(state.children).forEach((child) => {
+      if (child.status === 0) {
+        try {
+          child.start?.();
+        } catch (err) {
+          // TODO: unify error handling when child starts
+          actorCtx.self.send(error(child.id, err) as unknown as TEvent);
+        }
+      }
+    });
   }
 
   public getStateNodeById(stateId: string): StateNode<TContext, TEvent> {
@@ -411,6 +430,12 @@ export class StateMachine<
     return this.definition;
   }
 
+  public getPersistedState(
+    state: State<TContext, TEvent, TResolvedTypesMeta>
+  ): PersistedMachineState<State<TContext, TEvent, TResolvedTypesMeta>> {
+    return getPersistedState(state);
+  }
+
   public createState(
     stateConfig:
       | State<TContext, TEvent, TResolvedTypesMeta>
@@ -436,15 +461,80 @@ export class StateMachine<
   }
 
   public restoreState(
-    state: State<TContext, TEvent, TResolvedTypesMeta>,
-    _actorCtx?: ActorContext<
-      TEvent,
-      State<TContext, TEvent, TResolvedTypesMeta>
-    >
+    state: PersistedMachineState<State<TContext, TEvent, TResolvedTypesMeta>>,
+    _actorCtx: ActorContext<TEvent, State<TContext, TEvent, TResolvedTypesMeta>>
   ): State<TContext, TEvent, TResolvedTypesMeta> {
-    const restoredState = isStateConfig(state)
-      ? this.resolveState(state as any)
-      : this.resolveState(State.from(state as any, this.context, this));
+    const children = {};
+
+    Object.keys(state.children).forEach((actorId) => {
+      const actorData = state.children[actorId];
+      const childState = actorData.state;
+      const src = actorData.src;
+
+      const behaviorImpl = src ? this.options.actors[src.type] : undefined;
+
+      if (!behaviorImpl) {
+        return;
+      }
+
+      const behavior =
+        typeof behaviorImpl === 'function'
+          ? behaviorImpl(state.context, state._event.data, {
+              id: actorId,
+              data: undefined,
+              src: src!,
+              _event: state._event,
+              meta: {}
+            })
+          : behaviorImpl;
+
+      const actorState = behavior.restoreState?.(childState, _actorCtx);
+
+      const actorRef = interpret(behavior, {
+        id: actorId,
+        state: actorState
+      });
+
+      children[actorId] = actorRef;
+    });
+
+    const restoredState: State<TContext, TEvent, TResolvedTypesMeta> =
+      this.createState(new State({ ...state, children }, this));
+
+    // TODO: DRY this up
+    restoredState.configuration.forEach((stateNode) => {
+      if (stateNode.invoke) {
+        stateNode.invoke.forEach((invokeConfig) => {
+          const { id, src } = invokeConfig;
+
+          if (children[id]) {
+            return;
+          }
+
+          const behaviorImpl = this.options.actors[src.type];
+
+          const behavior =
+            typeof behaviorImpl === 'function'
+              ? behaviorImpl(state.context, state._event.data, {
+                  id,
+                  data: undefined,
+                  src,
+                  _event: state._event,
+                  meta: {}
+                })
+              : behaviorImpl;
+
+          if (behavior) {
+            const actorRef = interpret(behavior, {
+              id,
+              parent: _actorCtx?.self
+            });
+
+            children[id] = actorRef;
+          }
+        });
+      }
+    });
 
     return restoredState;
   }

packages/core/src/StateNode.ts

@@ -272,6 +272,7 @@ export class StateNode<
         ) {
           this.machine.options.actors = {
             ...this.machine.options.actors,
+            // TODO: this should accept `src` as-is
             [resolvedId]: typeof src === 'function' ? src : () => src
           };
         }

packages/core/src/actions/assign.ts

@@ -44,7 +44,7 @@ export function assign<
         assignment
       }
     },
-    (_event, { state, action }) => {
+    (_event, { state, action, actorContext }) => {
       const capturedActions: InvokeActionObject[] = [];
 
       if (!state.context) {
@@ -58,6 +58,7 @@ export function assign<
         action,
         _event,
         spawn: createSpawner(
+          actorContext?.self,
           state.machine,
           state.context,
           _event,