xstate 5.0.0-beta.38 → 5.0.0-beta.40

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

@@ -1,4 +1,4 @@
-import { ActorRefFrom, AnyActorContext, AnyActorLogic, AnyActorRef, AnyEventObject, AnyState, InputFrom, IsLiteralString, ProvidedActor } from "./types.js";
+import { ActorRefFrom, AnyActorScope, AnyActorLogic, AnyActorRef, AnyEventObject, AnyState, InputFrom, IsLiteralString, ProvidedActor } from "./types.js";
 export type SpawnOptions<TActor extends ProvidedActor, TSrc extends TActor['src']> = TActor extends {
     src: TSrc;
 } ? 'id' extends keyof TActor ? [
@@ -24,4 +24,4 @@ export type Spawner<TActor extends ProvidedActor> = IsLiteralString<TActor['src'
     input?: unknown;
     syncSnapshot?: boolean;
 }) => TLogic extends string ? AnyActorRef : ActorRefFrom<TLogic>;
-export declare function createSpawner(actorContext: AnyActorContext, { machine, context }: AnyState, event: AnyEventObject, spawnedChildren: Record<string, AnyActorRef>): Spawner<any>;
+export declare function createSpawner(actorScope: AnyActorScope, { machine, context }: AnyState, event: AnyEventObject, spawnedChildren: Record<string, AnyActorRef>): Spawner<any>;

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

@@ -1,6 +1,6 @@
 import { State } from "./State.js";
 import type { StateNode } from "./StateNode.js";
-import { AnyActorContext, AnyEventObject, AnyHistoryValue, AnyState, AnyStateNode, AnyTransitionDefinition, DelayedTransitionDefinition, EventObject, InitialTransitionConfig, InitialTransitionDefinition, MachineContext, StateValue, StateValueMap, TransitionDefinition, TODO, UnknownAction, AnyTransitionConfig } from "./types.js";
+import { AnyEventObject, AnyHistoryValue, AnyState, AnyStateNode, AnyTransitionDefinition, DelayedTransitionDefinition, EventObject, InitialTransitionConfig, InitialTransitionDefinition, MachineContext, StateValue, StateValueMap, TransitionDefinition, TODO, UnknownAction, AnyTransitionConfig, AnyActorScope } from "./types.js";
 type Configuration<TContext extends MachineContext, TE extends EventObject> = Iterable<StateNode<TContext, TE>>;
 type AnyConfiguration = Configuration<any, any>;
 type AdjList = Map<AnyStateNode, Array<AnyStateNode>>;
@@ -45,9 +45,9 @@ export declare function removeConflictingTransitions(enabledTransitions: Array<A
 /**
  * https://www.w3.org/TR/scxml/#microstepProcedure
  */
-export declare function microstep<TContext extends MachineContext, TEvent extends EventObject>(transitions: Array<AnyTransitionDefinition>, currentState: AnyState, actorCtx: AnyActorContext, event: AnyEventObject, isInitial: boolean, internalQueue: Array<AnyEventObject>): AnyState;
-export declare function resolveActionsAndContext(currentState: AnyState, event: AnyEventObject, actorCtx: AnyActorContext, actions: UnknownAction[], internalQueue: AnyEventObject[], deferredActorIds?: string[]): AnyState;
-export declare function macrostep(state: AnyState, event: EventObject, actorCtx: AnyActorContext, internalQueue?: AnyEventObject[]): {
+export declare function microstep<TContext extends MachineContext, TEvent extends EventObject>(transitions: Array<AnyTransitionDefinition>, currentState: AnyState, actorScope: AnyActorScope, event: AnyEventObject, isInitial: boolean, internalQueue: Array<AnyEventObject>): AnyState;
+export declare function resolveActionsAndContext(currentState: AnyState, event: AnyEventObject, actorScope: AnyActorScope, actions: UnknownAction[], internalQueue: AnyEventObject[], deferredActorIds?: string[]): AnyState;
+export declare function macrostep(state: AnyState, event: EventObject, actorScope: AnyActorScope, internalQueue?: AnyEventObject[]): {
     state: typeof state;
     microstates: Array<typeof state>;
 };

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

@@ -2,21 +2,25 @@ import { AnyEventObject, ActorSystem, ActorSystemInfo, AnyActorRef, Snapshot } f
 export declare function createSystem<T extends ActorSystemInfo>(rootActor: AnyActorRef): ActorSystem<T>;
 export interface BaseInspectionEventProperties {
     rootId: string;
+    /**
+     * The relevant actorRef for the inspection event.
+     * - For snapshot events, this is the `actorRef` of the snapshot.
+     * - For event events, this is the target `actorRef` (recipient of event).
+     * - For actor events, this is the `actorRef` of the registered actor.
+     */
+    actorRef: AnyActorRef;
 }
 export interface InspectedSnapshotEvent extends BaseInspectionEventProperties {
     type: '@xstate.snapshot';
-    actorRef: AnyActorRef;
     event: AnyEventObject;
     snapshot: Snapshot<unknown>;
 }
 export interface InspectedEventEvent extends BaseInspectionEventProperties {
     type: '@xstate.event';
     sourceRef: AnyActorRef | undefined;
-    targetRef: AnyActorRef;
     event: AnyEventObject;
 }
 export interface InspectedActorEvent extends BaseInspectionEventProperties {
     type: '@xstate.actor';
-    actorRef: AnyActorRef;
 }
 export type InspectionEvent = InspectedSnapshotEvent | InspectedEventEvent | InspectedActorEvent;

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

@@ -658,7 +658,7 @@ any, // tag
 any, // input
 any, // output
 infer TResolvedTypesMeta> ? TResolvedTypesMeta : never;
-export interface ActorContext<TSnapshot extends Snapshot<unknown>, TEvent extends EventObject, TSystem extends ActorSystem<any> = ActorSystem<any>> {
+export interface ActorScope<TSnapshot extends Snapshot<unknown>, TEvent extends EventObject, TSystem extends ActorSystem<any> = ActorSystem<any>> {
     self: ActorRef<TEvent, TSnapshot>;
     id: string;
     sessionId: string;
@@ -667,7 +667,7 @@ export interface ActorContext<TSnapshot extends Snapshot<unknown>, TEvent extend
     system: TSystem;
     stopChild: (child: AnyActorRef) => void;
 }
-export type AnyActorContext = ActorContext<any, any, AnyActorSystem>;
+export type AnyActorScope = ActorScope<any, any, AnyActorSystem>;
 export type Snapshot<TOutput> = {
     status: 'active';
     output: undefined;
@@ -687,10 +687,10 @@ export type Snapshot<TOutput> = {
 };
 export interface ActorLogic<TSnapshot extends Snapshot<unknown>, TEvent extends EventObject, TInput = unknown, TSystem extends ActorSystem<any> = ActorSystem<any>> {
     config?: unknown;
-    transition: (state: TSnapshot, message: TEvent, ctx: ActorContext<TSnapshot, TEvent, TSystem>) => TSnapshot;
-    getInitialState: (actorCtx: ActorContext<TSnapshot, TEvent, TSystem>, input: TInput) => TSnapshot;
-    restoreState?: (persistedState: Snapshot<unknown>, actorCtx: ActorContext<TSnapshot, TEvent>) => TSnapshot;
-    start?: (state: TSnapshot, actorCtx: ActorContext<TSnapshot, TEvent>) => void;
+    transition: (state: TSnapshot, message: TEvent, ctx: ActorScope<TSnapshot, TEvent, TSystem>) => TSnapshot;
+    getInitialState: (actorScope: ActorScope<TSnapshot, TEvent, TSystem>, input: TInput) => TSnapshot;
+    restoreState?: (persistedState: Snapshot<unknown>, actorScope: ActorScope<TSnapshot, TEvent>) => TSnapshot;
+    start?: (state: TSnapshot, actorScope: ActorScope<TSnapshot, TEvent>) => void;
     /**
      * @returns Persisted state
      */
@@ -700,7 +700,7 @@ export type AnyActorLogic = ActorLogic<any, // snapshot
 any, // event
 any, // input
 any>;
-export type SnapshotFrom<T> = ReturnTypeOrValue<T> extends infer R ? R extends ActorRef<infer _, infer TSnapshot> ? TSnapshot : R extends Actor<infer TLogic> ? SnapshotFrom<TLogic> : R extends StateMachine<infer _TContext, infer _TEvent, infer _TActor, infer _TAction, infer _TGuard, infer _TDelay, infer _TTag, infer _TInput, infer _TOutput, infer _TResolvedTypesMeta> ? StateFrom<R> : R extends ActorLogic<any, any, any, any> ? ReturnType<R['transition']> : R extends ActorContext<infer TSnapshot, infer _, infer __> ? TSnapshot : never : never;
+export type SnapshotFrom<T> = ReturnTypeOrValue<T> extends infer R ? R extends ActorRef<infer _, infer TSnapshot> ? TSnapshot : R extends Actor<infer TLogic> ? SnapshotFrom<TLogic> : R extends StateMachine<infer _TContext, infer _TEvent, infer _TActor, infer _TAction, infer _TGuard, infer _TDelay, infer _TTag, infer _TInput, infer _TOutput, infer _TResolvedTypesMeta> ? StateFrom<R> : R extends ActorLogic<any, any, any, any> ? ReturnType<R['transition']> : R extends ActorScope<infer TSnapshot, infer _, infer __> ? TSnapshot : never : never;
 export type EventFromLogic<TLogic extends ActorLogic<any, any, any, any>> = TLogic extends ActorLogic<infer _, infer TEvent, infer __, infer _____> ? TEvent : never;
 type ResolveEventType<T> = ReturnTypeOrValue<T> extends infer R ? R extends StateMachine<infer _TContext, infer TEvent, infer _TActor, infer _TAction, infer _TGuard, infer _TDelay, infer _TTag, infer _TInput, infer _TOutput, infer _TResolvedTypesMeta> ? TEvent : R extends State<infer _TContext, infer TEvent, infer _TActor, infer _TOutput, infer _TResolvedTypesMeta> ? TEvent : R extends ActorRef<infer TEvent, infer _> ? TEvent : never : never;
 export type EventFrom<T, K extends Prop<TEvent, 'type'> = never, TEvent extends EventObject = ResolveEventType<T>> = IsNever<K> extends true ? TEvent : ExtractEvent<TEvent, K>;

package/dist/{interpreter-4005eb36.development.esm.js → interpreter-410d7ca9.development.esm.js}

@@ -172,7 +172,7 @@ function createSystem(rootActor) {
       system._sendInspectionEvent({
         type: '@xstate.event',
         sourceRef: source,
-        targetRef: target,
+        actorRef: target,
         event
       });
       target._send(event);
@@ -357,6 +357,10 @@ const defaultOptions = {
   logger: console.log.bind(console),
   devTools: false
 };
+
+/**
+ * An Actor is a running process that can receive events, send events and change its behavior based on the events it receives, which can cause effects outside of the actor. When you run a state machine, it becomes an actor.
+ */
 class Actor {
   /**
    * The current internal state of the actor.
@@ -382,6 +386,10 @@ class Actor {
    * The globally unique process ID for this invocation.
    */
 
+  /**
+   * The system to which this actor belongs.
+   */
+
   /**
    * Creates a new actor instance for the given logic with the provided options, if any.
    *
@@ -401,7 +409,7 @@ class Actor {
     this.status = ActorStatus.NotStarted;
     this._parent = void 0;
     this.ref = void 0;
-    this._actorContext = void 0;
+    this._actorScope = void 0;
     this._systemId = void 0;
     this.sessionId = void 0;
     this.system = void 0;
@@ -425,10 +433,6 @@ class Actor {
       // Always inspect at the system-level
       this.system.inspect(toObserver(inspect));
     }
-    if (systemId) {
-      this._systemId = systemId;
-      this.system._set(systemId, this);
-    }
     this.sessionId = this.system._bookId();
     this.id = id ?? this.sessionId;
     this.logger = logger;
@@ -437,7 +441,7 @@ class Actor {
     this.options = resolvedOptions;
     this.src = resolvedOptions.src;
     this.ref = this;
-    this._actorContext = {
+    this._actorScope = {
       self: this,
       id: this.id,
       sessionId: this.sessionId,
@@ -462,9 +466,13 @@ class Actor {
       actorRef: this
     });
     this._initState();
+    if (systemId && this._state.status === 'active') {
+      this._systemId = systemId;
+      this.system._set(systemId, this);
+    }
   }
   _initState() {
-    this._state = this.options.state ? this.logic.restoreState ? this.logic.restoreState(this.options.state, this._actorContext) : this.options.state : this.logic.getInitialState(this._actorContext, this.options?.input);
+    this._state = this.options.state ? this.logic.restoreState ? this.logic.restoreState(this.options.state, this._actorScope) : this.options.state : this.logic.getInitialState(this._actorScope, this.options?.input);
   }
 
   // array of functions to defer
@@ -510,6 +518,56 @@ class Actor {
       snapshot
     });
   }
+
+  /**
+   * Subscribe an observer to an actor’s snapshot values.
+   *
+   * @remarks
+   * The observer will receive the actor’s snapshot value when it is emitted. The observer can be:
+   * - A plain function that receives the latest snapshot, or
+   * - An observer object whose `.next(snapshot)` method receives the latest snapshot
+   *
+   * @example
+   * ```ts
+   * // Observer as a plain function
+   * const subscription = actor.subscribe((snapshot) => {
+   *   console.log(snapshot);
+   * });
+   * ```
+   *
+   * @example
+   * ```ts
+   * // Observer as an object
+   * const subscription = actor.subscribe({
+   *   next(snapshot) {
+   *     console.log(snapshot);
+   *   },
+   *   error(err) {
+   *     // ...
+   *   },
+   *   complete() {
+   *     // ...
+   *   },
+   * });
+   * ```
+   *
+   * The return value of `actor.subscribe(observer)` is a subscription object that has an `.unsubscribe()` method. You can call `subscription.unsubscribe()` to unsubscribe the observer:
+   *
+   * @example
+   * ```ts
+   * const subscription = actor.subscribe((snapshot) => {
+   *   // ...
+   * });
+   *
+   * // Unsubscribe the observer
+   * subscription.unsubscribe();
+   * ```
+   *
+   * When the actor is stopped, all of its observers will automatically be unsubscribed.
+   *
+   * @param observer - Either a plain function that receives the latest snapshot, or an observer object whose `.next(snapshot)` method receives the latest snapshot
+   */
+
   subscribe(nextListenerOrObserver, errorListener, completeListener) {
     const observer = toObserver(nextListenerOrObserver, errorListener, completeListener);
     if (this.status !== ActorStatus.Stopped) {
@@ -545,7 +603,7 @@ class Actor {
     this.system._sendInspectionEvent({
       type: '@xstate.event',
       sourceRef: this._parent,
-      targetRef: this,
+      actorRef: this,
       event: initEvent
     });
     const status = this._state.status;
@@ -561,7 +619,7 @@ class Actor {
     }
     if (this.logic.start) {
       try {
-        this.logic.start(this._state, this._actorContext);
+        this.logic.start(this._state, this._actorScope);
       } catch (err) {
         this._stopProcedure();
         this._error(err);
@@ -585,7 +643,7 @@ class Actor {
     let nextState;
     let caughtError;
     try {
-      nextState = this.logic.transition(this._state, event, this._actorContext);
+      nextState = this.logic.transition(this._state, event, this._actorScope);
     } catch (err) {
       // we wrap it in a box so we can rethrow it later even if falsy value gets caught here
       caughtError = {
@@ -713,7 +771,10 @@ class Actor {
     this.system._relay(undefined, this, event);
   }
 
-  // TODO: make private (and figure out a way to do this within the machine)
+  /**
+   * TODO: figure out a way to do this within the machine
+   * @internal
+   */
   delaySend(params) {
     const {
       event,
@@ -730,7 +791,10 @@ class Actor {
     }
   }
 
-  // TODO: make private (and figure out a way to do this within the machine)
+  /**
+   * TODO: figure out a way to do this within the machine
+   * @internal
+   */
   cancel(sendId) {
     this.clock.clearTimeout(this.delayedEventsMap[sendId]);
     delete this.delayedEventsMap[sendId];
@@ -756,6 +820,21 @@ class Actor {
   [symbolObservable]() {
     return this;
   }
+
+  /**
+   * Read an actor’s snapshot synchronously.
+   *
+   * @remarks
+   * The snapshot represent an actor's last emitted value.
+   *
+   * When an actor receives an event, its internal state may change.
+   * An actor may emit a snapshot when a state transition occurs.
+   *
+   * Note that some actors, such as callback actors generated with `fromCallback`, will not emit snapshots.
+   *
+   * @see {@link Actor.subscribe} to subscribe to an actor’s snapshot values.
+   * @see {@link Actor.getPersistedState} to persist the internal state of an actor (which is more than just a snapshot).
+   */
   getSnapshot() {
     return this._state;
   }

package/dist/{interpreter-b6f22ee2.cjs.js → interpreter-586abde4.cjs.js}

@@ -174,7 +174,7 @@ function createSystem(rootActor) {
       system._sendInspectionEvent({
         type: '@xstate.event',
         sourceRef: source,
-        targetRef: target,
+        actorRef: target,
         event
       });
       target._send(event);
@@ -356,6 +356,10 @@ const defaultOptions = {
   logger: console.log.bind(console),
   devTools: false
 };
+
+/**
+ * An Actor is a running process that can receive events, send events and change its behavior based on the events it receives, which can cause effects outside of the actor. When you run a state machine, it becomes an actor.
+ */
 class Actor {
   /**
    * The current internal state of the actor.
@@ -381,6 +385,10 @@ class Actor {
    * The globally unique process ID for this invocation.
    */
 
+  /**
+   * The system to which this actor belongs.
+   */
+
   /**
    * Creates a new actor instance for the given logic with the provided options, if any.
    *
@@ -400,7 +408,7 @@ class Actor {
     this.status = ActorStatus.NotStarted;
     this._parent = void 0;
     this.ref = void 0;
-    this._actorContext = void 0;
+    this._actorScope = void 0;
     this._systemId = void 0;
     this.sessionId = void 0;
     this.system = void 0;
@@ -424,10 +432,6 @@ class Actor {
       // Always inspect at the system-level
       this.system.inspect(toObserver(inspect));
     }
-    if (systemId) {
-      this._systemId = systemId;
-      this.system._set(systemId, this);
-    }
     this.sessionId = this.system._bookId();
     this.id = id ?? this.sessionId;
     this.logger = logger;
@@ -436,7 +440,7 @@ class Actor {
     this.options = resolvedOptions;
     this.src = resolvedOptions.src;
     this.ref = this;
-    this._actorContext = {
+    this._actorScope = {
       self: this,
       id: this.id,
       sessionId: this.sessionId,
@@ -461,9 +465,13 @@ class Actor {
       actorRef: this
     });
     this._initState();
+    if (systemId && this._state.status === 'active') {
+      this._systemId = systemId;
+      this.system._set(systemId, this);
+    }
   }
   _initState() {
-    this._state = this.options.state ? this.logic.restoreState ? this.logic.restoreState(this.options.state, this._actorContext) : this.options.state : this.logic.getInitialState(this._actorContext, this.options?.input);
+    this._state = this.options.state ? this.logic.restoreState ? this.logic.restoreState(this.options.state, this._actorScope) : this.options.state : this.logic.getInitialState(this._actorScope, this.options?.input);
   }
 
   // array of functions to defer
@@ -509,6 +517,56 @@ class Actor {
       snapshot
     });
   }
+
+  /**
+   * Subscribe an observer to an actor’s snapshot values.
+   *
+   * @remarks
+   * The observer will receive the actor’s snapshot value when it is emitted. The observer can be:
+   * - A plain function that receives the latest snapshot, or
+   * - An observer object whose `.next(snapshot)` method receives the latest snapshot
+   *
+   * @example
+   * ```ts
+   * // Observer as a plain function
+   * const subscription = actor.subscribe((snapshot) => {
+   *   console.log(snapshot);
+   * });
+   * ```
+   *
+   * @example
+   * ```ts
+   * // Observer as an object
+   * const subscription = actor.subscribe({
+   *   next(snapshot) {
+   *     console.log(snapshot);
+   *   },
+   *   error(err) {
+   *     // ...
+   *   },
+   *   complete() {
+   *     // ...
+   *   },
+   * });
+   * ```
+   *
+   * The return value of `actor.subscribe(observer)` is a subscription object that has an `.unsubscribe()` method. You can call `subscription.unsubscribe()` to unsubscribe the observer:
+   *
+   * @example
+   * ```ts
+   * const subscription = actor.subscribe((snapshot) => {
+   *   // ...
+   * });
+   *
+   * // Unsubscribe the observer
+   * subscription.unsubscribe();
+   * ```
+   *
+   * When the actor is stopped, all of its observers will automatically be unsubscribed.
+   *
+   * @param observer - Either a plain function that receives the latest snapshot, or an observer object whose `.next(snapshot)` method receives the latest snapshot
+   */
+
   subscribe(nextListenerOrObserver, errorListener, completeListener) {
     const observer = toObserver(nextListenerOrObserver, errorListener, completeListener);
     if (this.status !== ActorStatus.Stopped) {
@@ -544,7 +602,7 @@ class Actor {
     this.system._sendInspectionEvent({
       type: '@xstate.event',
       sourceRef: this._parent,
-      targetRef: this,
+      actorRef: this,
       event: initEvent
     });
     const status = this._state.status;
@@ -560,7 +618,7 @@ class Actor {
     }
     if (this.logic.start) {
       try {
-        this.logic.start(this._state, this._actorContext);
+        this.logic.start(this._state, this._actorScope);
       } catch (err) {
         this._stopProcedure();
         this._error(err);
@@ -584,7 +642,7 @@ class Actor {
     let nextState;
     let caughtError;
     try {
-      nextState = this.logic.transition(this._state, event, this._actorContext);
+      nextState = this.logic.transition(this._state, event, this._actorScope);
     } catch (err) {
       // we wrap it in a box so we can rethrow it later even if falsy value gets caught here
       caughtError = {
@@ -704,7 +762,10 @@ class Actor {
     this.system._relay(undefined, this, event);
   }
 
-  // TODO: make private (and figure out a way to do this within the machine)
+  /**
+   * TODO: figure out a way to do this within the machine
+   * @internal
+   */
   delaySend(params) {
     const {
       event,
@@ -721,7 +782,10 @@ class Actor {
     }
   }
 
-  // TODO: make private (and figure out a way to do this within the machine)
+  /**
+   * TODO: figure out a way to do this within the machine
+   * @internal
+   */
   cancel(sendId) {
     this.clock.clearTimeout(this.delayedEventsMap[sendId]);
     delete this.delayedEventsMap[sendId];
@@ -747,6 +811,21 @@ class Actor {
   [symbolObservable]() {
     return this;
   }
+
+  /**
+   * Read an actor’s snapshot synchronously.
+   *
+   * @remarks
+   * The snapshot represent an actor's last emitted value.
+   *
+   * When an actor receives an event, its internal state may change.
+   * An actor may emit a snapshot when a state transition occurs.
+   *
+   * Note that some actors, such as callback actors generated with `fromCallback`, will not emit snapshots.
+   *
+   * @see {@link Actor.subscribe} to subscribe to an actor’s snapshot values.
+   * @see {@link Actor.getPersistedState} to persist the internal state of an actor (which is more than just a snapshot).
+   */
   getSnapshot() {
     return this._state;
   }