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

package/dist/{interpreter-ed3f81f7.development.cjs.js → interpreter-bae5c279.development.cjs.js}

@@ -174,7 +174,7 @@ function createSystem(rootActor) {
       system._sendInspectionEvent({
         type: '@xstate.event',
         sourceRef: source,
-        targetRef: target,
+        actorRef: target,
         event
       });
       target._send(event);
@@ -359,6 +359,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.
@@ -384,6 +388,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.
    *
@@ -403,7 +411,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;
@@ -427,10 +435,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;
@@ -439,7 +443,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,
@@ -464,9 +468,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
@@ -512,6 +520,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) {
@@ -547,7 +605,7 @@ class Actor {
     this.system._sendInspectionEvent({
       type: '@xstate.event',
       sourceRef: this._parent,
-      targetRef: this,
+      actorRef: this,
       event: initEvent
     });
     const status = this._state.status;
@@ -563,7 +621,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);
@@ -587,7 +645,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 = {
@@ -715,7 +773,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,
@@ -732,7 +793,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];
@@ -758,6 +822,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-c80ce92e.esm.js → interpreter-ed0fac7e.esm.js}

@@ -172,7 +172,7 @@ function createSystem(rootActor) {
       system._sendInspectionEvent({
         type: '@xstate.event',
         sourceRef: source,
-        targetRef: target,
+        actorRef: target,
         event
       });
       target._send(event);
@@ -354,6 +354,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.
@@ -379,6 +383,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.
    *
@@ -398,7 +406,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;
@@ -422,10 +430,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;
@@ -434,7 +438,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,
@@ -459,9 +463,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
@@ -507,6 +515,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) {
@@ -542,7 +600,7 @@ class Actor {
     this.system._sendInspectionEvent({
       type: '@xstate.event',
       sourceRef: this._parent,
-      targetRef: this,
+      actorRef: this,
       event: initEvent
     });
     const status = this._state.status;
@@ -558,7 +616,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);
@@ -582,7 +640,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 = {
@@ -702,7 +760,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,
@@ -719,7 +780,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];
@@ -745,6 +809,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;
   }