Rename snapshot-related methods on the ActorLogic (#4533)

* Rename `state` to `snapshot` in many variables and signatures * Rename snapshot-related methods on the logic * Deprecate options.state * Changeset --------- Co-authored-by: David Khourshid <[email protected]>
statelyai · Nov 30, 2023 · 2495aa2 · 2495aa2
1 parent 0012138
commit 2495aa2
Show file tree

Hide file tree

Showing 44 changed files with 400 additions and 334 deletions.
diff --git a/.changeset/brown-ways-explode.md b/.changeset/brown-ways-explode.md
@@ -0,0 +1,19 @@
+---
+'xstate': minor
+---
+
+The `state` option of `createActor(...)` has been renamed to `snapshot`:
+
+```diff
+createActor(machine, {
+- state: someState
++ snapshot: someState
+})
+```
+
+Likewise, the `.getPersistedState()` method has been renamed to `.getPersistedSnapshot()`:
+
+```diff
+-actor.getPersistedState()
++actor.getPersistedSnapshot()
+```
diff --git a/packages/core/src/State.ts b/packages/core/src/State.ts
@@ -397,16 +397,16 @@ export function createMachineSnapshot<
 }
 
 export function cloneMachineSnapshot<TState extends AnyMachineSnapshot>(
-  state: TState,
+  snapshot: TState,
   config: Partial<StateConfig<any, any>> = {}
 ): TState {
   return createMachineSnapshot(
-    { ...state, ...config } as StateConfig<any, any>,
-    state.machine
+    { ...snapshot, ...config } as StateConfig<any, any>,
+    snapshot.machine
   ) as TState;
 }
 
-export function getPersistedState<
+export function getPersistedSnapshot<
   TContext extends MachineContext,
   TEvent extends EventObject,
   TChildren extends Record<string, AnyActorRef | undefined>,
@@ -415,7 +415,7 @@ export function getPersistedState<
   TOutput,
   TResolvedTypesMeta = TypegenDisabled
 >(
-  state: MachineSnapshot<
+  snapshot: MachineSnapshot<
     TContext,
     TEvent,
     TChildren,
@@ -438,7 +438,7 @@ export function getPersistedState<
     getMeta,
     toJSON,
     ...jsonValues
-  } = state;
+  } = snapshot;
 
   const childrenJson: Record<string, unknown> = {};
 
@@ -452,7 +452,7 @@ export function getPersistedState<
       throw new Error('An inline child actor cannot be persisted.');
     }
     childrenJson[id as keyof typeof childrenJson] = {
-      state: child.getPersistedState(options),
+      snapshot: child.getPersistedSnapshot(options),
       src: child.src,
       systemId: child._systemId,
       syncSnapshot: child._syncSnapshot

diff --git a/packages/core/src/StateMachine.ts b/packages/core/src/StateMachine.ts
@@ -3,7 +3,7 @@ import { createInitEvent } from './eventUtils.ts';
 import { STATE_DELIMITER } from './constants.ts';
 import {
   createMachineSnapshot,
-  getPersistedState,
+  getPersistedSnapshot,
   MachineSnapshot
 } from './State.ts';
 import { StateNode } from './StateNode.ts';
@@ -144,7 +144,7 @@ export class StateMachine<
 
     this.transition = this.transition.bind(this);
     this.getInitialState = this.getInitialState.bind(this);
-    this.restoreState = this.restoreState.bind(this);
+    this.restoreSnapshot = this.restoreSnapshot.bind(this);
     this.start = this.start.bind(this);
 
     this.root = new StateNode(config, {
@@ -288,7 +288,7 @@ export class StateMachine<
     TOutput,
     TResolvedTypesMeta
   > {
-    return macrostep(snapshot, event, actorScope).state as typeof snapshot;
+    return macrostep(snapshot, event, actorScope).snapshot as typeof snapshot;
   }
 
   /**
@@ -299,7 +299,7 @@ export class StateMachine<
    * @param event The received event
    */
   public microstep(
-    state: MachineSnapshot<
+    snapshot: MachineSnapshot<
       TContext,
       TEvent,
       TChildren,
@@ -321,7 +321,8 @@ export class StateMachine<
       TResolvedTypesMeta
     >
   > {
-    return macrostep(state, event, actorScope).microstates as (typeof state)[];
+    return macrostep(snapshot, event, actorScope)
+      .microstates as (typeof snapshot)[];
   }
 
   public getTransitionData(
@@ -435,7 +436,7 @@ export class StateMachine<
       internalQueue
     );
 
-    const { state: macroState } = macrostep(
+    const { snapshot: macroState } = macrostep(
       nextState,
       initEvent as AnyEventObject,
       actorScope,
@@ -446,7 +447,7 @@ export class StateMachine<
   }
 
   public start(
-    state: MachineSnapshot<
+    snapshot: MachineSnapshot<
       TContext,
       TEvent,
       TChildren,
@@ -456,7 +457,7 @@ export class StateMachine<
       TResolvedTypesMeta
     >
   ): void {
-    Object.values(state.children as Record<string, AnyActorRef>).forEach(
+    Object.values(snapshot.children as Record<string, AnyActorRef>).forEach(
       (child: any) => {
         if (child.getSnapshot().status === 'active') {
           child.start();
@@ -489,8 +490,8 @@ export class StateMachine<
     return this.definition;
   }
 
-  public getPersistedState(
-    state: MachineSnapshot<
+  public getPersistedSnapshot(
+    snapshot: MachineSnapshot<
       TContext,
       TEvent,
       TChildren,
@@ -501,10 +502,10 @@ export class StateMachine<
     >,
     options?: unknown
   ) {
-    return getPersistedState(state, options);
+    return getPersistedSnapshot(snapshot, options);
   }
 
-  public restoreState(
+  public restoreSnapshot(
     snapshot: Snapshot<unknown>,
     _actorScope: ActorScope<
       MachineSnapshot<
@@ -532,7 +533,7 @@ export class StateMachine<
       string,
       {
         src: string | AnyActorLogic;
-        state: Snapshot<unknown>;
+        snapshot: Snapshot<unknown>;
         syncSnapshot?: boolean;
         systemId?: string;
       }
@@ -541,7 +542,7 @@ export class StateMachine<
     Object.keys(snapshotChildren).forEach((actorId) => {
       const actorData =
         snapshotChildren[actorId as keyof typeof snapshotChildren];
-      const childState = actorData.state;
+      const childState = actorData.snapshot;
       const src = actorData.src;
 
       const logic =
@@ -555,7 +556,7 @@ export class StateMachine<
         id: actorId,
         parent: _actorScope?.self,
         syncSnapshot: actorData.syncSnapshot,
-        state: childState,
+        snapshot: childState,
         src,
         systemId: actorData.systemId
       });

diff --git a/packages/core/src/StateNode.ts b/packages/core/src/StateNode.ts
@@ -368,7 +368,7 @@ export class StateNode<
   }
 
   public next(
-    state: MachineSnapshot<TContext, TEvent, any, any, any, any>,
+    snapshot: MachineSnapshot<TContext, TEvent, any, any, any, any>,
     event: TEvent
   ): TransitionDefinition<TContext, TEvent>[] | undefined {
     const eventType = event.type;
@@ -384,14 +384,19 @@ export class StateNode<
 
     for (const candidate of candidates) {
       const { guard } = candidate;
-      const resolvedContext = state.context;
+      const resolvedContext = snapshot.context;
 
       let guardPassed = false;
 
       try {
         guardPassed =
           !guard ||
-          evaluateGuard<TContext, TEvent>(guard, resolvedContext, event, state);
+          evaluateGuard<TContext, TEvent>(
+            guard,
+            resolvedContext,
+            event,
+            snapshot
+          );
       } catch (err: any) {
         const guardType =
           typeof guard === 'string'

diff --git a/packages/core/src/actions/assign.ts b/packages/core/src/actions/assign.ts
@@ -27,7 +27,7 @@ export interface AssignArgs<
 
 function resolveAssign(
   actorScope: AnyActorScope,
-  state: AnyMachineSnapshot,
+  snapshot: AnyMachineSnapshot,
   actionArgs: ActionArgs<any, any, any>,
   actionParams: ParameterizedObject['params'] | undefined,
   {
@@ -38,17 +38,22 @@ function resolveAssign(
       | PropertyAssigner<any, any, any, any, any>;
   }
 ) {
-  if (!state.context) {
+  if (!snapshot.context) {
     throw new Error(
       'Cannot assign to undefined `context`. Ensure that `context` is defined in the machine config.'
     );
   }
   const spawnedChildren: Record<string, AnyActorRef> = {};
 
   const assignArgs: AssignArgs<any, any, any, any> = {
-    context: state.context,
+    context: snapshot.context,
     event: actionArgs.event,
-    spawn: createSpawner(actorScope, state, actionArgs.event, spawnedChildren),
+    spawn: createSpawner(
+      actorScope,
+      snapshot,
+      actionArgs.event,
+      spawnedChildren
+    ),
     self: actorScope?.self,
     system: actorScope?.system
   };
@@ -65,17 +70,17 @@ function resolveAssign(
     }
   }
 
-  const updatedContext = Object.assign({}, state.context, partialUpdate);
+  const updatedContext = Object.assign({}, snapshot.context, partialUpdate);
 
   return [
-    cloneMachineSnapshot(state, {
+    cloneMachineSnapshot(snapshot, {
       context: updatedContext,
       children: Object.keys(spawnedChildren).length
         ? {
-            ...state.children,
+            ...snapshot.children,
             ...spawnedChildren
           }
-        : state.children
+        : snapshot.children
     })
   ];
 }

diff --git a/packages/core/src/actions/cancel.ts b/packages/core/src/actions/cancel.ts
@@ -23,14 +23,14 @@ type ResolvableSendId<
 
 function resolveCancel(
   _: AnyActorScope,
-  state: AnyMachineSnapshot,
+  snapshot: AnyMachineSnapshot,
   actionArgs: ActionArgs<any, any, any>,
   actionParams: ParameterizedObject['params'] | undefined,
   { sendId }: { sendId: ResolvableSendId<any, any, any, any> }
 ) {
   const resolvedSendId =
     typeof sendId === 'function' ? sendId(actionArgs, actionParams) : sendId;
-  return [state, resolvedSendId];
+  return [snapshot, resolvedSendId];
 }
 
 function executeCancel(actorScope: AnyActorScope, resolvedSendId: string) {

diff --git a/packages/core/src/actions/enqueueActions.ts b/packages/core/src/actions/enqueueActions.ts
@@ -80,7 +80,7 @@ interface ActionEnqueuer<
 
 function resolveEnqueueActions(
   _: AnyActorScope,
-  state: AnyMachineSnapshot,
+  snapshot: AnyMachineSnapshot,
   args: ActionArgs<any, any, any>,
   _actionParams: ParameterizedObject['params'] | undefined,
   {
@@ -143,10 +143,11 @@ function resolveEnqueueActions(
     context: args.context,
     event: args.event,
     enqueue,
-    check: (guard) => evaluateGuard(guard, state.context, args.event, state)
+    check: (guard) =>
+      evaluateGuard(guard, snapshot.context, args.event, snapshot)
   });
 
-  return [state, undefined, actions];
+  return [snapshot, undefined, actions];
 }
 
 export interface EnqueueActionsAction<

diff --git a/packages/core/src/actions/log.ts b/packages/core/src/actions/log.ts
@@ -18,7 +18,7 @@ type ResolvableLogValue<
 
 function resolveLog(
   _: AnyActorScope,
-  state: AnyMachineSnapshot,
+  snapshot: AnyMachineSnapshot,
   actionArgs: ActionArgs<any, any, any>,
   actionParams: ParameterizedObject['params'] | undefined,
   {
@@ -30,7 +30,7 @@ function resolveLog(
   }
 ) {
   return [
-    state,
+    snapshot,
     {
       value:
         typeof value === 'function' ? value(actionArgs, actionParams) : value,

diff --git a/packages/core/src/actions/raise.ts b/packages/core/src/actions/raise.ts
@@ -16,7 +16,7 @@ import {
 
 function resolveRaise(
   _: AnyActorScope,
-  state: AnyMachineSnapshot,
+  snapshot: AnyMachineSnapshot,
   args: ActionArgs<any, any, any>,
   actionParams: ParameterizedObject['params'] | undefined,
   {
@@ -47,7 +47,7 @@ function resolveRaise(
   },
   { internalQueue }: { internalQueue: AnyEventObject[] }
 ) {
-  const delaysMap = state.machine.implementations.delays;
+  const delaysMap = snapshot.machine.implementations.delays;
 
   if (typeof eventOrExpr === 'string') {
     throw new Error(
@@ -73,7 +73,7 @@ function resolveRaise(
   if (typeof resolvedDelay !== 'number') {
     internalQueue.push(resolvedEvent);
   }
-  return [state, { event: resolvedEvent, id, delay: resolvedDelay }];
+  return [snapshot, { event: resolvedEvent, id, delay: resolvedDelay }];
 }
 
 function executeRaise(