xstate 6.0.0-alpha.2 → 6.0.0-alpha.20

package/README.md

@@ -119,7 +119,7 @@ npm install xstate
 ```
 
 ```ts
-import { createMachine, createActor, assign } from 'xstate';
+import { createMachine, createActor } from 'xstate';
 
 // State machine
 const toggleMachine = createMachine({
@@ -135,7 +135,9 @@ const toggleMachine = createMachine({
       }
     },
     active: {
-      entry: assign({ count: ({ context }) => context.count + 1 }),
+      entry: ({ context }) => ({
+        context: { count: context.count + 1 }
+      }),
       on: {
         TOGGLE: { target: 'inactive' }
       }
@@ -164,7 +166,7 @@ toggleActor.send({ type: 'TOGGLE' });
 - Deploy to Stately Sky
 - Generate & modify machines with Stately AI
 
-<a href="stately.ai/registry/new?ref=github" title="Stately Studio">
+<a href="https://stately.ai/registry/new?ref=github" title="Stately Studio">
   <img src="https://github.com/statelyai/xstate/assets/1093738/74ed9cbc-b824-4ed7-a16d-f104947af8a7" alt="XState Viz" width="800" />
 </a>
 
@@ -365,10 +367,10 @@ const wordMachine = createMachine({
       initial: 'off',
       states: {
         on: {
-          on: { TOGGLE_BOLD: 'off' }
+          on: { TOGGLE_BOLD: { target: 'off' } }
         },
         off: {
-          on: { TOGGLE_BOLD: 'on' }
+          on: { TOGGLE_BOLD: { target: 'on' } }
         }
       }
     },
@@ -376,10 +378,10 @@ const wordMachine = createMachine({
       initial: 'off',
       states: {
         on: {
-          on: { TOGGLE_UNDERLINE: 'off' }
+          on: { TOGGLE_UNDERLINE: { target: 'off' } }
         },
         off: {
-          on: { TOGGLE_UNDERLINE: 'on' }
+          on: { TOGGLE_UNDERLINE: { target: 'on' } }
         }
       }
     },
@@ -387,10 +389,10 @@ const wordMachine = createMachine({
       initial: 'off',
       states: {
         on: {
-          on: { TOGGLE_ITALICS: 'off' }
+          on: { TOGGLE_ITALICS: { target: 'off' } }
         },
         off: {
-          on: { TOGGLE_ITALICS: 'on' }
+          on: { TOGGLE_ITALICS: { target: 'on' } }
         }
       }
     },
@@ -399,20 +401,20 @@ const wordMachine = createMachine({
       states: {
         none: {
           on: {
-            BULLETS: 'bullets',
-            NUMBERS: 'numbers'
+            BULLETS: { target: 'bullets' },
+            NUMBERS: { target: 'numbers' }
           }
         },
         bullets: {
           on: {
-            NONE: 'none',
-            NUMBERS: 'numbers'
+            NONE: { target: 'none' },
+            NUMBERS: { target: 'numbers' }
           }
         },
         numbers: {
           on: {
-            BULLETS: 'bullets',
-            NONE: 'none'
+            BULLETS: { target: 'bullets' },
+            NONE: { target: 'none' }
           }
         }
       }
@@ -493,10 +495,10 @@ const paymentMachine = createMachine({
         },
         hist: { type: 'history' }
       },
-      on: { NEXT: 'review' }
+      on: { NEXT: { target: 'review' } }
     },
     review: {
-      on: { PREVIOUS: 'method.hist' }
+      on: { PREVIOUS: { target: 'method.hist' } }
     }
   }
 });

package/bin/xstate.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+// Lightweight `xstate` CLI. Heavy commands are delegated to dedicated
+// packages fetched on demand so the core package stays dependency-free.
+const { spawnSync } = require('child_process');
+
+const [command, ...rest] = process.argv.slice(2);
+
+switch (command) {
+  case 'migrate': {
+    // Delegates to @xstate/codemod (ts-morph based v5 → v6 codemods).
+    const result = spawnSync(
+      process.platform === 'win32' ? 'npx.cmd' : 'npx',
+      ['-y', '@xstate/codemod', 'migrate', ...rest],
+      { stdio: 'inherit' }
+    );
+    process.exit(result.status ?? 1);
+    break;
+  }
+  case '--help':
+  case 'help':
+  case undefined:
+    console.log(
+      [
+        'Usage: xstate <command>',
+        '',
+        'Commands:',
+        '  migrate [globs...] [--dry]   Migrate source files to the current XState version',
+        '                               (delegates to @xstate/codemod)'
+      ].join('\n')
+    );
+    process.exit(command ? 0 : 1);
+    break;
+  default:
+    console.error(`Unknown command: ${command}`);
+    process.exit(1);
+}

package/dist/{StateMachine-2dcdb1f5.esm.js → StateMachine-42f1d26c.esm.js}

@@ -1,4 +1,4 @@
-import { P as ProcessingStatus, G as resolveReferencedActor, c as createActor, S as STATE_DELIMITER, H as mapValues, t as toArray, I as createInvokeId, J as getDelayedTransitions, K as evaluateCandidate, L as formatTransition, N as NULL_EVENT, M as toTransitionConfigArray, O as createInvokeTimeoutEvent, Q as getCandidates, R as formatRouteTransitions, U as resolveStateValue, V as getAllStateNodes, n as getStateNodes, W as createMachineSnapshot, X as isInFinalState, a as macrostep, Y as transitionNode, m as matchesEventDescriptor, Z as resolveAndExecuteActionsWithContext, b as createInitEvent, d as initialMicrostep, _ as toStatePath, $ as isStateId, a0 as getStateNodeByPath, a1 as getPersistedSnapshot, a2 as $$ACTOR_TYPE } from './index-93edd3bd.esm.js';
+import { P as ProcessingStatus, H as resolveReferencedActor, e as createActor, S as STATE_DELIMITER, I as mapValues, t as toArray, J as createInvokeId, K as getDelayedTransitions, L as evaluateCandidate, M as formatTransition, N as NULL_EVENT, O as toTransitionConfigArray, Q as createInvokeTimeoutEvent, R as getCandidates, U as formatRouteTransitions, V as resolveStateValue, W as getAllStateNodes, l as getStateNodes, Y as createMachineSnapshot, Z as isInFinalState, f as macrostep, d as deriveDeferredStarts, _ as cloneMachineSnapshot, $ as transitionNode, m as matchesEventDescriptor, a0 as getTransitionResult, a1 as hasEffect, a2 as createErrorPlatformEvent, r as resolveActionsWithContext, g as createInitEvent, h as initialMicrostep, a3 as toStatePath, a4 as isStateId, a5 as getStateNodeByPath, a6 as getPersistedSnapshot, a7 as $$ACTOR_TYPE } from './index-d88b0c55.esm.js';
 
 function createSpawner(actorScope, {
   machine,
@@ -20,7 +20,7 @@ function createSpawner(actorScope, {
           self: actorScope.self
         }) : options?.input,
         src,
-        systemId: options?.systemId
+        registryKey: options?.registryKey
       });
       spawnedChildren[actor.id] = actor;
       return actor;
@@ -31,7 +31,7 @@ function createSpawner(actorScope, {
         syncSnapshot: options?.syncSnapshot,
         input: options?.input,
         src,
-        systemId: options?.systemId
+        registryKey: options?.registryKey
       });
       return actor;
     }
@@ -64,7 +64,6 @@ function memo(object, key, fn) {
 }
 
 const EMPTY_OBJECT = {};
-const CHOICE_CONFIG_KEYS = ['invoke', 'after', 'on', 'entry', 'exit', 'always', 'states', 'initial', 'onDone', 'timeout', 'onTimeout', 'history', 'target', 'output'];
 class StateNode {
   constructor(/** The raw config used to create the machine. */
   config, options) {
@@ -171,7 +170,7 @@ class StateNode {
     this.invoke = toArray(this.config.invoke).map((invokeConfig, i) => {
       const {
         src,
-        systemId
+        registryKey
       } = invokeConfig;
       const invokeId = createInvokeId(this.id, i);
       const resolvedId = invokeConfig.id ?? invokeId;
@@ -184,7 +183,7 @@ class StateNode {
         src: sourceName,
         logic: src,
         id: resolvedId,
-        systemId
+        registryKey
       };
     });
   }
@@ -244,30 +243,17 @@ class StateNode {
 function validateStateNodeConfig(stateNode) {
   const config = stateNode.config;
   if (stateNode.type !== 'choice') {
-    if (config.choice !== undefined) {
-      throw new Error(`State "${stateNode.id}" has \`choice\`, but \`choice\` can only be used with \`type: 'choice'\`.`);
-    }
     return;
   }
   if (typeof config.choice !== 'function') {
-    throw new Error(`Choice state "${stateNode.id}" must declare a \`choice\` function.`);
-  }
-  for (const key of CHOICE_CONFIG_KEYS) {
-    if (config[key] !== undefined) {
-      throw new Error(`Choice state "${stateNode.id}" cannot declare \`${key}\`.`);
-    }
+    throw new Error(`Missing \`choice\` function on "${stateNode.id}"`);
   }
 }
 function formatChoiceTransitions(stateNode) {
   const choice = stateNode.config.choice;
   const validateChoiceResult = result => {
     if (!result || result.target === undefined) {
-      throw new Error(`Choice state "${stateNode.id}" must resolve to a target.`);
-    }
-    for (const key of ['actions', 'to', 'context']) {
-      if (result[key] !== undefined) {
-        throw new Error(`Choice state "${stateNode.id}" cannot declare \`${key}\` on a choice.`);
-      }
+      throw new Error(`Choice "${stateNode.id}" has no target`);
     }
     return result;
   };
@@ -288,7 +274,7 @@ function formatTransitions(stateNode) {
   if (stateNode.config.on) {
     for (const descriptor of Object.keys(stateNode.config.on)) {
       if (descriptor === NULL_EVENT) {
-        throw new Error('Null events ("") cannot be specified as a transition key. Use `always: { ... }` instead.');
+        throw new Error('Null event transition key');
       }
       const transitionsConfig = stateNode.config.on[descriptor];
       transitions.set(descriptor, mapTransitionConfigs(transitionsConfig, transition => formatTransition(stateNode, descriptor, transition)));
@@ -298,6 +284,10 @@ function formatTransitions(stateNode) {
     const descriptor = `xstate.done.state.${stateNode.id}`;
     transitions.set(descriptor, mapTransitionConfigs(stateNode.config.onDone, transition => formatTransition(stateNode, descriptor, transition)));
   }
+  if (stateNode.config.onError) {
+    const descriptor = 'xstate.error.*';
+    transitions.set(descriptor, mapTransitionConfigs(stateNode.config.onError, transition => formatTransition(stateNode, descriptor, transition)));
+  }
   const createCancelInvokeTimeoutTransition = (descriptor, timeoutEventType) => formatTransition(stateNode, descriptor, {
     to: (_args, enq) => {
       enq.cancel(timeoutEventType);
@@ -384,7 +374,7 @@ function formatInitialTransition(stateNode, _target) {
   const input = typeof _target === 'object' && _target !== null ? _target.input : undefined;
   const resolvedTarget = typeof targetString === 'string' ? stateNode.states[targetString] : undefined;
   if (!resolvedTarget && targetString) {
-    throw new Error(`Initial state node "${targetString}" not found on parent state node #${stateNode.id}`);
+    throw new Error(`Initial state "${targetString}" not found on "#${stateNode.id}"`);
   }
   const transition = {
     source: stateNode,
@@ -395,6 +385,45 @@ function formatInitialTransition(stateNode, _target) {
 }
 
 const STATE_IDENTIFIER = '#';
+let emptyCanActor;
+let emptyCanActorScope;
+function getEmptyCanActor() {
+  // A minimal inert actor used purely as the `self`/`parent` argument when
+  // dry-running transitions for `snapshot.can(...)`. Intentionally not built
+  // on `createLogic` so `can()` does not pull that machinery into bundles.
+  return emptyCanActor ??= createActor({
+    transition: snapshot => [snapshot, []],
+    initialTransition: () => [{
+      status: 'active',
+      output: undefined,
+      error: undefined
+    }, []],
+    getInitialSnapshot: () => ({
+      status: 'active',
+      output: undefined,
+      error: undefined
+    }),
+    getPersistedSnapshot: snapshot => snapshot
+  });
+}
+function getEmptyCanActorScope() {
+  if (emptyCanActorScope) {
+    return emptyCanActorScope;
+  }
+  const actor = getEmptyCanActor();
+  emptyCanActorScope = {
+    self: actor,
+    logger: () => {},
+    id: '',
+    sessionId: '',
+    defer: () => {},
+    system: actor.system,
+    stopChild: () => {},
+    emit: () => {},
+    actionExecutor: () => {}
+  };
+  return emptyCanActorScope;
+}
 class StateMachine {
   constructor(/** The raw config used to create the machine. */
   config, implementations) {
@@ -422,7 +451,7 @@ class StateMachine {
     this._json = void 0;
     this.id = config.id || '(machine)';
     this.implementations = {
-      actors: config.actors ?? {},
+      actorSources: config.actorSources ?? {},
       actions: config.actions ?? {},
       delays: config.delays ?? {},
       guards: config.guards ?? {},
@@ -436,6 +465,7 @@ class StateMachine {
       ...this.config.options
     };
     this.transition = this.transition.bind(this);
+    this.initialTransition = this.initialTransition.bind(this);
     this.getInitialSnapshot = this.getInitialSnapshot.bind(this);
     this.getPersistedSnapshot = this.getPersistedSnapshot.bind(this);
     this.restoreSnapshot = this.restoreSnapshot.bind(this);
@@ -454,15 +484,15 @@ class StateMachine {
   /**
    * Clones this state machine with the provided implementations.
    *
-   * @param implementations Options (`actions`, `guards`, `actors`, `delays`) to
-   *   recursively merge with the existing options.
+   * @param implementations Options (`actions`, `guards`, `actorSources`,
+   *   `delays`) to recursively merge with the existing options.
    * @returns A new `StateMachine` instance with the provided implementations.
    */
   provide(implementations) {
     const {
       actions,
       guards,
-      actors,
+      actorSources,
       delays
     } = this.implementations;
     const provided = new StateMachine(this.config, {
@@ -474,9 +504,9 @@ class StateMachine {
         ...guards,
         ...implementations.guards
       },
-      actors: {
-        ...actors,
-        ...implementations.actors
+      actorSources: {
+        ...actorSources,
+        ...implementations.actorSources
       },
       delays: {
         ...delays,
@@ -511,7 +541,56 @@ class StateMachine {
    * @param event The received event
    */
   transition(snapshot, event, actorScope) {
-    return macrostep(snapshot, event, actorScope, []).snapshot;
+    const fastSnapshot = this._transitionFast(snapshot, event, actorScope);
+    if (fastSnapshot) {
+      return [fastSnapshot, []];
+    }
+    const {
+      snapshot: nextSnapshot,
+      microsteps
+    } = macrostep(snapshot, event, actorScope, []);
+    return [nextSnapshot, this._collectEffects(microsteps)];
+  }
+  _collectEffects(microsteps, initialActions = []) {
+    const effects = [...initialActions, ...microsteps.flatMap(([, actions]) => actions)];
+    return [...effects, ...deriveDeferredStarts(effects)];
+  }
+  _transitionFast(snapshot, event, actorScope) {
+    if (snapshot.status !== 'active' || typeof snapshot.value !== 'string' || this.root.always?.length) {
+      return undefined;
+    }
+    const sourceNode = this.root.states[snapshot.value];
+    if (!sourceNode || sourceNode.type !== 'atomic' || sourceNode.exit || sourceNode.invoke.length || sourceNode.always?.length || sourceNode.after?.length) {
+      return undefined;
+    }
+    const transitions = sourceNode.transitions.get(event.type);
+    if (transitions?.length !== 1) {
+      return undefined;
+    }
+    const selected = transitions[0];
+    if (selected.guard || selected.actions || selected.to || selected.reenter || selected.input || typeof selected.context === 'function' || selected.target && selected.target.length !== 1) {
+      return undefined;
+    }
+    const targetNode = selected.target?.[0] ?? sourceNode;
+    const stateChanged = targetNode !== sourceNode;
+    if (targetNode.parent !== this.root || targetNode.type !== 'atomic' || stateChanged && (targetNode.entry || targetNode.invoke.length || targetNode.always?.length || targetNode.after?.length)) {
+      return undefined;
+    }
+    const context = selected.context !== undefined ? {
+      ...snapshot.context,
+      ...selected.context
+    } : snapshot.context;
+    const collectedMicrosteps = actorScope.self._collectedMicrosteps || [];
+    collectedMicrosteps.push(selected);
+    actorScope.self._collectedMicrosteps = collectedMicrosteps;
+    return cloneMachineSnapshot(snapshot, {
+      ...(context !== snapshot.context ? {
+        context
+      } : {}),
+      ...(stateChanged ? {
+        _nodes: [this.root, targetNode]
+      } : {})
+    });
   }
 
   /**
@@ -543,6 +622,49 @@ class StateMachine {
     return false;
   }
 
+  /**
+   * Determines whether sending the `event` to the given snapshot would select a
+   * non-forbidden transition. Backs `snapshot.can(...)`; lives here so that
+   * non-machine bundles don't pay for the transition-resolution machinery.
+   *
+   * @internal
+   */
+  _canTransition(snapshot, event) {
+    const emptyActor = getEmptyCanActor();
+    const emptyActorScope = getEmptyCanActorScope();
+    const transitionData = this.getTransitionData(snapshot, event, emptyActor);
+    if (!transitionData?.length) {
+      return false;
+    }
+
+    // Check that at least one transition is not forbidden
+    for (const transition of transitionData) {
+      if (transition.target !== undefined) {
+        return true;
+      }
+      const res = getTransitionResult(transition, snapshot, event, emptyActorScope, {
+        resolveActions: false
+      });
+      if (res.targets?.length || res.context || hasEffect(transition, snapshot.context, event, snapshot, emptyActor)) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  /**
+   * Returns the error event that the actor should transition with to recover
+   * from an execution error, if any active state node declares `onError`.
+   *
+   * @internal
+   */
+  getExecutionErrorEvent(snapshot, error) {
+    if (snapshot?.status !== 'active' || !snapshot._nodes?.some(stateNode => stateNode.config.onError)) {
+      return undefined;
+    }
+    return createErrorPlatformEvent('execution', error);
+  }
+
   /**
    * The initial state _before_ evaluating any microsteps. This "pre-initial"
    * state is provided to initial actions executed in the initial state.
@@ -566,9 +688,9 @@ class StateMachine {
         spawn,
         input: initEvent.input,
         self: actorScope.self,
-        actors: this.implementations.actors
+        actorSources: this.implementations.actorSources
       });
-      const nextState = resolveAndExecuteActionsWithContext(preInitial, initEvent, actorScope, []);
+      const [nextState] = resolveActionsWithContext(preInitial, initEvent, actorScope, []);
       if (resolvedContext) {
         nextState.context = resolvedContext;
       }
@@ -588,14 +710,33 @@ class StateMachine {
    * `ActorRef`.
    */
   getInitialSnapshot(actorScope, input) {
+    return this.initialTransition(input, actorScope)[0];
+  }
+  initialTransition(input, actorScope) {
     const initEvent = createInitEvent(input); // TODO: fix;
     const internalQueue = [];
     const preInitialState = this._getPreInitialState(actorScope, initEvent);
-    const [nextState] = initialMicrostep(this.root, preInitialState, actorScope, initEvent, internalQueue);
-    const {
-      snapshot: macroState
-    } = macrostep(nextState, initEvent, actorScope, internalQueue);
-    return macroState;
+    let nextState;
+    let initialActions = [];
+    let microsteps = [];
+    let macroState;
+    try {
+      [nextState, initialActions] = initialMicrostep(this.root, preInitialState, actorScope, initEvent, internalQueue);
+      ({
+        snapshot: macroState,
+        microsteps
+      } = macrostep(nextState, initEvent, actorScope, internalQueue));
+    } catch (err) {
+      if (!this.root.config.onError) {
+        throw err;
+      }
+      const errorEvent = createErrorPlatformEvent('execution', err);
+      const errorMacrostep = macrostep(preInitialState, errorEvent, actorScope, []);
+      macroState = errorMacrostep.snapshot;
+      microsteps = errorMacrostep.microsteps;
+      initialActions = [];
+    }
+    return [macroState, this._collectEffects(microsteps, initialActions)];
   }
   start(snapshot) {
     // Start rehydrated children that were active when persisted. Freshly
@@ -649,7 +790,7 @@ class StateMachine {
         syncSnapshot: actorData.syncSnapshot,
         snapshot: childState,
         src,
-        systemId: actorData.systemId
+        registryKey: actorData.registryKey
       });
       // Mark so `start()` knows to start this child (freshly invoked/spawned
       // children are started via deferred `@xstate.start` actions instead).
@@ -693,7 +834,8 @@ class StateMachine {
       children,
       _nodes: nodes,
       value: snapshotData.value,
-      historyValue: revivedHistoryValue
+      historyValue: revivedHistoryValue,
+      _stateInputs: snapshotData.stateInputs ?? {}
     }, this);
     const seen = new WeakSet();
     function reviveContext(contextPart) {