xstate 5.0.0-beta.37 → 5.0.0-beta.39

package/dist/{interpreter-97aff8d2.cjs.js → interpreter-5dfcd203.cjs.js}

@@ -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) {
@@ -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];
@@ -742,11 +806,26 @@ class Actor {
     };
   }
   getPersistedState() {
-    return this.logic.getPersistedState?.(this._state);
+    return this.logic.getPersistedState(this._state);
   }
   [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-1c52b23c.development.esm.js → interpreter-70cd9217.development.esm.js}

@@ -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) {
@@ -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];
@@ -751,11 +815,26 @@ class Actor {
     };
   }
   getPersistedState() {
-    return this.logic.getPersistedState?.(this._state);
+    return this.logic.getPersistedState(this._state);
   }
   [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;
   }