xstate 6.0.0-alpha.16 → 6.0.0-alpha.17

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-dfe616b4.development.esm.js → StateMachine-114b1598.development.esm.js}

@@ -1,4 +1,4 @@
-import { P as ProcessingStatus, G as resolveReferencedActor, d 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, k as getStateNodes, W as createMachineSnapshot, Y as isInFinalState, e as macrostep, Z as cloneMachineSnapshot, _ as transitionNode, m as matchesEventDescriptor, r as resolveActionsWithContext, f as createInitEvent, g as initialMicrostep, $ as toStatePath, a0 as isStateId, a1 as getStateNodeByPath, a2 as getPersistedSnapshot, a3 as $$ACTOR_TYPE, a4 as createErrorPlatformEvent } from './index-5d18ec0c.development.esm.js';
+import { P as ProcessingStatus, G as resolveReferencedActor, d 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, k as getStateNodes, W as createMachineSnapshot, Y as isInFinalState, e as macrostep, Z as cloneMachineSnapshot, _ as transitionNode, m as matchesEventDescriptor, $ as getTransitionResult, a0 as hasEffect, a1 as createErrorPlatformEvent, r as resolveActionsWithContext, f as createInitEvent, g as initialMicrostep, a2 as toStatePath, a3 as isStateId, a4 as getStateNodeByPath, a5 as getPersistedSnapshot, a6 as $$ACTOR_TYPE } from './index-31e8ad34.development.esm.js';
 
 function createSpawner(actorScope, {
   machine,
@@ -403,6 +403,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) {
@@ -469,9 +508,6 @@ class StateMachine {
     this.root._refreshEventMetadata();
     this.states = this.root.states; // TODO: remove!
     this.events = this.root.events;
-    if (!('output' in this.root) && Object.values(this.states).some(state => state.type === 'final' && 'output' in state)) {
-      console.warn('Missing `machine.output` declaration (top-level final state with output detected)');
-    }
   }
 
   /**
@@ -611,6 +647,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.

package/dist/{StateMachine-7572fbeb.development.cjs.js → StateMachine-4d17c47e.development.cjs.js}

@@ -1,6 +1,6 @@
 'use strict';
 
-var dist_xstateActors = require('./index-4a0afbfa.development.cjs.js');
+var dist_xstateActors = require('./index-415cdd3a.development.cjs.js');
 
 function createSpawner(actorScope, {
   machine,
@@ -405,6 +405,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 ??= dist_xstateActors.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) {
@@ -471,9 +510,6 @@ class StateMachine {
     this.root._refreshEventMetadata();
     this.states = this.root.states; // TODO: remove!
     this.events = this.root.events;
-    if (!('output' in this.root) && Object.values(this.states).some(state => state.type === 'final' && 'output' in state)) {
-      console.warn('Missing `machine.output` declaration (top-level final state with output detected)');
-    }
   }
 
   /**
@@ -613,6 +649,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 = dist_xstateActors.getTransitionResult(transition, snapshot, event, emptyActorScope, {
+        resolveActions: false
+      });
+      if (res.targets?.length || res.context || dist_xstateActors.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 dist_xstateActors.createErrorPlatformEvent('execution', error);
+  }
+
   /**
    * The initial state _before_ evaluating any microsteps. This "pre-initial"
    * state is provided to initial actions executed in the initial state.

package/dist/{StateMachine-18299be7.cjs.js → StateMachine-a10528bb.cjs.js}

@@ -1,6 +1,6 @@
 'use strict';
 
-var dist_xstateActors = require('./index-64839116.cjs.js');
+var dist_xstateActors = require('./index-1ac35571.cjs.js');
 
 function createSpawner(actorScope, {
   machine,
@@ -387,6 +387,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 ??= dist_xstateActors.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) {
@@ -581,6 +620,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 = dist_xstateActors.getTransitionResult(transition, snapshot, event, emptyActorScope, {
+        resolveActions: false
+      });
+      if (res.targets?.length || res.context || dist_xstateActors.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 dist_xstateActors.createErrorPlatformEvent('execution', error);
+  }
+
   /**
    * The initial state _before_ evaluating any microsteps. This "pre-initial"
    * state is provided to initial actions executed in the initial state.

package/dist/{StateMachine-4a0a8848.esm.js → StateMachine-c2d32ddd.esm.js}

@@ -1,4 +1,4 @@
-import { P as ProcessingStatus, G as resolveReferencedActor, d 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, k as getStateNodes, W as createMachineSnapshot, Y as isInFinalState, e as macrostep, Z as cloneMachineSnapshot, _ as transitionNode, m as matchesEventDescriptor, r as resolveActionsWithContext, f as createInitEvent, g as initialMicrostep, $ as toStatePath, a0 as isStateId, a1 as getStateNodeByPath, a2 as getPersistedSnapshot, a3 as $$ACTOR_TYPE, a4 as createErrorPlatformEvent } from './index-9fc97b9e.esm.js';
+import { P as ProcessingStatus, G as resolveReferencedActor, d 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, k as getStateNodes, W as createMachineSnapshot, Y as isInFinalState, e as macrostep, Z as cloneMachineSnapshot, _ as transitionNode, m as matchesEventDescriptor, $ as getTransitionResult, a0 as hasEffect, a1 as createErrorPlatformEvent, r as resolveActionsWithContext, f as createInitEvent, g as initialMicrostep, a2 as toStatePath, a3 as isStateId, a4 as getStateNodeByPath, a5 as getPersistedSnapshot, a6 as $$ACTOR_TYPE } from './index-addc01a2.esm.js';
 
 function createSpawner(actorScope, {
   machine,
@@ -385,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) {
@@ -579,6 +618,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.

package/dist/declarations/src/createActor.d.ts

@@ -58,6 +58,8 @@ export declare class Actor<TLogic extends AnyActorLogic> implements ActorInstanc
     private _deferred;
     private _pendingEffects?;
     private _setErrorSnapshot;
+    /** Recover via the logic's error event if possible; otherwise error out. */
+    private _recoverOrError;
     private _tryHandleExecutionError;
     private _next;
     private update;

package/dist/declarations/src/types.d.ts

@@ -327,7 +327,11 @@ export type InvokeConfig<TContext extends MachineContext, TEvent extends EventOb
 export type AnyInvokeConfig = InvokeConfig<any, any, any, any, any, any, any, any>;
 export type AnyStateNodeConfig = Next_StateNodeConfig<any, any, any, any, any, any, any, any, any, any, any, any>;
 export type AnyStateNode = StateNode<any, any> | StateNode<never, EventObject> | StateNode<any, EventObject> | StateNode<never, any>;
-export type AnyMachineSnapshot = MachineSnapshot<any, any, any, any, any, any, any, any>;
+type LoosenMachineSnapshot<TSnapshot> = TSnapshot extends MachineSnapshot<any, any, any, any, any, any, any, any> ? Omit<TSnapshot, 'matches' | 'can'> & {
+    matches(partialStateValue: StateValue): boolean;
+    can(event: any): boolean;
+} : never;
+export type AnyMachineSnapshot = LoosenMachineSnapshot<MachineSnapshot<any, any, any, any, any, any, any, any>>;
 export interface AnyStateMachine extends AnyActorLogic {
     id: string;
     root: AnyStateNode;
@@ -764,7 +768,11 @@ export type SendableEventFromLogic<TLogic extends AnyActorLogic> = TLogic extend
 } ? ExcludeInternalEvents<TEvent, TConfig['internalEvents'] extends readonly EventDescriptor<TEvent>[] ? TConfig['internalEvents'] extends readonly (infer TDesc)[] ? Extract<TDesc, string> : never : never> : TEvent : EventFromLogic<TLogic>;
 type OpaqueMachineSnapshot<TSnapshot extends Snapshot<unknown>> = TSnapshot extends MachineSnapshot<infer TContext, infer TEvent, infer TChildren, infer TStateValue, infer TTag, infer TOutput, infer TMeta, infer _TStateSchema> ? MachineSnapshot<TContext, TEvent, TChildren, TStateValue, TTag, TOutput, TMeta, any> : TSnapshot;
 export type ActorRefFromLogic<T extends AnyActorLogic> = ActorRef<OpaqueMachineSnapshot<SnapshotFrom<T>>, EventFromLogic<T>, EmittedFrom<T>, SendableEventFromLogic<T>>;
-export type AnyActorRef = ActorRef<any, any, any, any>;
+export interface AnyActorRef extends Subscribable<any>, InteropObservable<any> {
+    send(event: any): void;
+    getSnapshot(): any;
+    on(type: string, handler: (emitted: any) => void): Subscription;
+}
 /** The concrete actor instance type produced from actor logic. */
 export type ActorFromLogic<T extends AnyActorLogic> = ActorInstance<SnapshotFrom<T>, EventFromLogic<T>, EmittedFrom<T>, SendableEventFromLogic<T>>;
 type SendableEventFromActorRef<TActorRef, TFallback extends EventObject = AnyEventObject> = [NonNullable<TActorRef>] extends [never] ? TFallback : NonNullable<TActorRef> extends infer TNonNullableActorRef ? TNonNullableActorRef extends {
@@ -883,6 +891,12 @@ in TInput = NonReducibleUnknown, TSystem extends AnyActorSystem = AnyActorSystem
      * returns such effects can omit this.
      */
     executeEffects?: (effects: readonly unknown[], actorScope: ActorScope<TSnapshot, TEvent, TSystem, TEmitted>) => void;
+    /**
+     * Returns an event that the actor should transition with to recover from an
+     * execution error, or `undefined` if the given snapshot cannot handle it.
+     * Actor logic without error-recovery semantics can omit this.
+     */
+    getExecutionErrorEvent?: (snapshot: TSnapshot, error: unknown) => TEvent | undefined;
 }
 export interface AnyActorLogic {
     config?: unknown;
@@ -893,6 +907,7 @@ export interface AnyActorLogic {
     start?(snapshot: any, actorScope: any): void;
     getPersistedSnapshot(snapshot: any, options?: unknown): Snapshot<unknown>;
     executeEffects?(effects: readonly unknown[], actorScope: any): void;
+    getExecutionErrorEvent?(snapshot: any, error: unknown): any;
 }
 export type UnknownActorLogic = ActorLogic<any, // snapshot
 any, // event