xstate 6.0.0-beta.1 → 6.0.0-beta.2

package/dist/{createActor-a49ae0ce.development.cjs.js → createActor-c029d29f.development.cjs.js}

@@ -213,11 +213,11 @@ function isRemoteActorRef(actorRef) {
  * JSON (`actor.toJSON()`): plain data carrying an address, not an actor.
  */
 function isSerializedActorRef(target) {
-  if (typeof target !== 'object' || target === null || Array.isArray(target) || typeof target.$actor !== 'string') {
+  if (typeof target !== 'object' || target === null || Array.isArray(target) || typeof target['@actor'] !== 'string') {
     return false;
   }
   for (const key in target) {
-    if (key !== '$actor' && key !== 'incarnation') {
+    if (key !== '@actor' && key !== 'incarnation') {
       return false;
     }
   }
@@ -233,7 +233,7 @@ function getAddressId(address) {
 
 /** @internal The error reported when no live actor has a serialized address. */
 function createMissingAddressError(target) {
-  return new Error(target.incarnation === undefined ? `Unable to send event to actor '${target.$actor}': no live actor has that address` : `Unable to send event to actor '${target.$actor}' (incarnation '${target.incarnation}'): no live actor has that address and incarnation`);
+  return new Error(target.incarnation === undefined ? `Unable to send event to actor '${target['@actor']}': no live actor has that address` : `Unable to send event to actor '${target['@actor']}' (incarnation '${target.incarnation}'): no live actor has that address and incarnation`);
 }
 
 /**
@@ -242,7 +242,7 @@ function createMissingAddressError(target) {
  * without one follows whichever actor is live at the address.
  */
 function resolveSerializedActorRef(system, target) {
-  const live = system._getByAddress?.(target.$actor);
+  const live = system._getByAddress?.(target['@actor']);
   return live && (target.incarnation === undefined || live.sessionId === target.incarnation) ? live : undefined;
 }
 
@@ -295,7 +295,7 @@ function createInertActorRef(options) {
         throw new Error(`Cannot serialize actor ref '${id}': it was returned by a spawn during speculative transition evaluation, which creates no actor and has no parent address.` );
       }
       return {
-        $actor: address
+        '@actor': address
       };
     }
   };
@@ -381,7 +381,7 @@ function createRemoteActorRef(system, options) {
     // one actor-reference shape whether a child is co-located or remote.
     toJSON() {
       return {
-        $actor: options.address
+        '@actor': options.address
       };
     }
   };
@@ -501,7 +501,7 @@ function deliverEvent(source, target, event) {
         throw error;
       }
       void system.deadLetter(source, undefined, event, 'missingTarget', {
-        targetId: getAddressId(serialized.$actor),
+        targetId: getAddressId(serialized['@actor']),
         error
       });
       return;
@@ -2203,6 +2203,18 @@ function withSystemInspector(inspect, fn) {
 
 /** Snapshot-scoped actor identity and system view. @internal */
 
+// Each view's execution system and whether it forwards inspection. Views
+// never chain: they all inherit from the execution system directly.
+const snapshotSystemViews = new WeakMap();
+// Facilities owned by the execution rather than by one snapshot's view. A view
+// reads and writes them on the execution system, so timers, listeners and the
+// runtime installed through any snapshot are visible through every other.
+const executionFacilities = ['runtime', '_timerMap', '_rejectionListeners', '_inspectionObservers', '_emissionListeners'];
+// The durable execution that owns each execution system.
+/** A durable execution, as the owner of the views its transitions create. @internal */
+
+const executionOwners = new WeakMap();
+let ambientExecutionOwner;
 const snapshotActorRefs = new WeakMap();
 const lazySnapshotActorRefs = new WeakMap();
 const emptyKeyedActors = new Map();
@@ -2262,12 +2274,22 @@ function getSnapshotChildren(snapshot) {
  *
  * @internal
  */
-function createSnapshotSystem(baseSystem, children, baseState) {
-  const forwardInspection = hasAmbientInspector();
+function createSnapshotSystem(baseSystem, children, baseState, owner) {
+  const baseView = snapshotSystemViews.get(baseSystem);
+  const baseExecutionSystem = baseView?.executionSystem ?? baseSystem;
+  // The runtime system under every view. A view runs its methods against the
+  // execution system's facilities.
+  const rootSystem = baseView?.rootSystem ?? baseSystem;
+  const forks = owner !== undefined && executionOwners.get(baseExecutionSystem) !== owner;
+  // A view an execution owns reports to that execution's inspector.
+  const forwardInspection = owner ? !!owner.inspect : hasAmbientInspector() && (baseView?.forwardInspection ?? true);
   const registeredActors = copyRegisteredActors(baseSystem, baseState);
   const keyedActors = new Map(baseState?.keyedActors ?? getKeyedActors(baseSystem));
   const reverseKeyedActors = new WeakMap();
-  const system = Object.assign(Object.create(baseSystem), {
+  // The view's execution system; adoption can make the view its own.
+  const execution = () => snapshotSystemViews.get(system).executionSystem;
+  const forwards = () => snapshotSystemViews.get(system).forwardInspection;
+  const system = Object.assign(Object.create(baseExecutionSystem), {
     children: registeredActors,
     keyedActors,
     reverseKeyedActors,
@@ -2302,15 +2324,38 @@ function createSnapshotSystem(baseSystem, children, baseState) {
     },
     get: registryKey => keyedActors.get(registryKey),
     getAll: () => Object.fromEntries(keyedActors),
-    onEmitted: listener => baseSystem.onEmitted(listener),
-    _notifyEmitted: (actorRef, event) => baseSystem._notifyEmitted(actorRef, event),
+    onEmitted: listener => rootSystem.onEmitted.call(execution(), listener),
+    _notifyEmitted: (actorRef, event) => rootSystem._notifyEmitted.call(execution(), actorRef, event),
     // Pure transition resolution must not leak topology inspection events
     // into a live runtime system — planning branches stay silent. The one
     // exception is a durable execution's own transitions (marked by the
     // ambient inspector at creation time): there the pure path IS the
-    // execution, so inspection forwards to the base system's observers.
-    _hasInspectionObservers: forwardInspection ? () => baseSystem._hasInspectionObservers?.() ?? false : () => false,
-    _sendInspectionEvent: forwardInspection ? event => baseSystem._sendInspectionEvent(event) : () => {}
+    // execution, so inspection forwards to the execution system's observers.
+    _hasInspectionObservers: () => forwards() && (rootSystem._hasInspectionObservers?.call(execution()) ?? false),
+    _sendInspectionEvent: event => {
+      if (forwards()) {
+        rootSystem._sendInspectionEvent.call(execution(), event);
+      }
+    }
+  });
+  const executionSystem = forks ? system : baseExecutionSystem;
+  if (forks) {
+    forkFacilities(system, baseExecutionSystem, owner);
+  } else {
+    for (const key of executionFacilities) {
+      Object.defineProperty(system, key, {
+        configurable: true,
+        get: () => execution()[key],
+        set: value => {
+          execution()[key] = value;
+        }
+      });
+    }
+  }
+  snapshotSystemViews.set(system, {
+    executionSystem,
+    rootSystem,
+    forwardInspection
   });
   for (const [registryKey, actor] of keyedActors) {
     if (!actor) {
@@ -2334,6 +2379,83 @@ function createSnapshotSystem(baseSystem, children, baseState) {
   return system;
 }
 
+/**
+ * Makes `system` the execution system of `owner`, a new incarnation: it gets
+ * the owner's runtime and the pending timers it saw, and starts with no
+ * listeners or inspectors, so nothing registered on another execution
+ * observes it.
+ */
+function forkFacilities(system, from, owner) {
+  const timers = from._timerMap;
+  for (const key of executionFacilities) {
+    Object.defineProperty(system, key, {
+      configurable: true,
+      writable: true,
+      value: key === 'runtime' ? owner.runtime : key === '_timerMap' && timers ? {
+        ...timers
+      } : undefined
+    });
+  }
+  executionOwners.set(system, owner);
+  if (owner.inspect) {
+    system.inspect(owner.inspect);
+  }
+}
+
+/**
+ * Makes `owner` own `system` before it installs its runtime there, and
+ * returns whether it does. An unowned view forks in place, so the install
+ * never reaches the system it was derived from. A system another execution
+ * owns is left alone.
+ *
+ * @internal
+ */
+function adoptSystem(system, owner) {
+  const view = snapshotSystemViews.get(system);
+  const current = executionOwners.get(view?.executionSystem ?? system);
+  if (current === owner) {
+    if (view) {
+      view.forwardInspection = !!owner.inspect;
+    }
+    return true;
+  }
+  // A system another execution owns stays with it.
+  if (current) {
+    return false;
+  }
+  if (!view) {
+    executionOwners.set(system, owner);
+    return true;
+  }
+  forkFacilities(system, view.executionSystem, owner);
+  view.executionSystem = system;
+  view.forwardInspection = !!owner.inspect;
+  return true;
+}
+
+/**
+ * Runs `fn` as a transition of `owner`. A view it derives from a system the
+ * owner does not own forks into the owner's own execution system.
+ *
+ * @internal
+ */
+function withExecutionOwner(owner, fn) {
+  const previous = ambientExecutionOwner;
+  ambientExecutionOwner = owner;
+  try {
+    return fn();
+  } finally {
+    ambientExecutionOwner = previous;
+  }
+}
+
+/** Hands the ambient owner to the first scope that asks for it. @internal */
+function takeExecutionOwner() {
+  const owner = ambientExecutionOwner;
+  ambientExecutionOwner = undefined;
+  return owner;
+}
+
 /** Returns the actor identity associated with a transition snapshot. @internal */
 function getSnapshotActorRef(snapshot) {
   const existing = snapshotActorRefs.get(snapshot);
@@ -2527,8 +2649,9 @@ function setInertActorScopeSnapshot(actorScope, snapshot, attachActorRef = true)
   const lazyState = getLazyInertActorState(actorScope);
   if (lazyState) {
     lazyState.snapshot = snapshot;
-    if (lazyState.materialized) {
-      lazyState.materialized.self._snapshot = snapshot;
+    const scope = lazyState.materialized ?? lazyState.identityScope;
+    if (scope) {
+      scope.self._snapshot = snapshot;
     }
   } else {
     actorScope.self._snapshot = snapshot;
@@ -2563,6 +2686,15 @@ function attachSnapshotActorRef(actorScope, snapshot) {
   setLazySnapshotActorRef(snapshot, create);
   return snapshot;
 }
+/** Records the materialized scope and releases its consumed source. */
+function commitMaterialization(state, scope) {
+  // Dropping the consumed source keeps this scope from retaining earlier snapshots.
+  state.sourceRef = undefined;
+  state.sourceChildren = {};
+  state.materialized = scope;
+  state.materialize = () => scope;
+  return scope;
+}
 const lazyInertActorState = Symbol();
 const snapshotActorScopes = new WeakMap();
 let inertActorMaterializationObserver;
@@ -2607,12 +2739,14 @@ const lazyInertActorScopePrototype = {
     return materializeInertActorScope(this).actionExecutor;
   }
 };
-function createMaterializedInertActorScope(actorLogic, sourceRef, sourceChildren, currentSnapshot, sourceSelf) {
+
+/** Creates a transactional planning scope backed by an inert actor. */
+function createMaterializedInertActorScope(actorLogic, sourceRef, sourceChildren, currentSnapshot, sourceSelf, owner) {
   inertActorMaterializationObserver?.();
   const snapshotRef = sourceRef?.();
   const previousSelf = sourceSelf ?? snapshotRef?.actor;
   const baseSystem = previousSelf?.system;
-  const system = previousSelf && baseSystem ? createSnapshotSystem(baseSystem, sourceChildren, sourceSelf ? undefined : snapshotRef?.systemState) : undefined;
+  const system = previousSelf && baseSystem ? createSnapshotSystem(baseSystem, sourceChildren, sourceSelf ? undefined : snapshotRef?.systemState, owner) : undefined;
   const self = createActor(actorLogic, {
     _inert: true,
     ...(previousSelf ? {
@@ -2632,12 +2766,8 @@ function createMaterializedInertActorScope(actorLogic, sourceRef, sourceChildren
     // a future construction-time read cannot pin a root-shaped address.
     self._address = undefined;
   }
-  if (currentSnapshot) {
-    self._snapshot = currentSnapshot;
-  }
-
   // Reuse the branch actor's scope while keeping planning transactional.
-  return Object.create(self._actorScope, {
+  const scope = Object.create(self._actorScope, {
     defer: {
       value: () => {}
     },
@@ -2646,8 +2776,20 @@ function createMaterializedInertActorScope(actorLogic, sourceRef, sourceChildren
     },
     actionExecutor: {
       value: () => {}
+    },
+    _snapshot: {
+      enumerable: true,
+      configurable: true,
+      get: () => self._snapshot,
+      set: snapshot => {
+        self._snapshot = snapshot;
+      }
     }
   });
+  if (currentSnapshot) {
+    scope._snapshot = currentSnapshot;
+  }
+  return scope;
 }
 
 /** @internal */
@@ -2662,22 +2804,34 @@ function createInertActorScope(actorLogic, snapshot, sourceSelf, sourceActorScop
     sourceChildren: isMachineSnapshot(snapshot) ? snapshot.children : {},
     identityProvider: sourceState?.identityProvider ?? sourceRef,
     parent: sourceSelf?._parent ?? sourceState?.parent ?? eagerSourceRef?.actor._parent,
+    // Only the outermost scope of an owned transition belongs to the owner;
+    // scopes for its intermediate snapshots inherit it, and nested pure
+    // transitions run unowned.
+    owner: sourceActorScope ? sourceState?.owner : takeExecutionOwner(),
     parentKnown: !!sourceSelf || !!sourceState?.parentKnown || !!eagerSourceRef || !snapshot
   };
-  state.materialize = () => state.materialized ??= createMaterializedInertActorScope(actorLogic, state.sourceRef, state.sourceChildren, state.snapshot, sourceSelf);
+  state.materialize = () => {
+    const scope = createMaterializedInertActorScope(actorLogic, state.sourceRef, state.sourceChildren, state.snapshot, sourceSelf, state.owner);
+    return commitMaterialization(state, scope);
+  };
   if (!state.identityProvider && !snapshot) {
     const identitySnapshot = {};
-    const identitySourceRef = state.sourceRef;
-    const identitySourceChildren = state.sourceChildren;
-    let identityScope;
     let identityRef;
-    const getIdentityScope = () => identityScope ??= createMaterializedInertActorScope(actorLogic, identitySourceRef, identitySourceChildren, undefined, sourceSelf);
+    const getIdentityScope = () => {
+      if (!state.identityScope) {
+        state.identityScope = createMaterializedInertActorScope(actorLogic, state.sourceRef, state.sourceChildren, undefined, sourceSelf, state.owner);
+        if (state.snapshot !== undefined) {
+          state.identityScope.self._snapshot = state.snapshot;
+        }
+      }
+      return state.identityScope;
+    };
     state.materialize = () => {
       const scope = getIdentityScope();
       if (state.snapshot !== undefined) {
         scope.self._snapshot = state.snapshot;
       }
-      return state.materialized = scope;
+      return commitMaterialization(state, scope);
     };
     state.identityProvider = () => {
       if (identityRef) {
@@ -4661,7 +4815,7 @@ function findNonJsonPath(value, path) {
       };
     }
     if ('sessionId' in current && 'send' in current && 'ref' in current) {
-      // Actor refs persist as `{ $actor: address }`.
+      // Actor refs persist as `{ "@actor": address }`.
       return undefined;
     }
     if (ancestors.has(current)) {
@@ -4784,6 +4938,8 @@ const machineSnapshotToJSON = function toJSON() {
   const {
     nodes,
     _stateInputs,
+    _nextTimerId,
+    _nextActorIds,
     tags,
     machine,
     getMeta,
@@ -4908,6 +5064,8 @@ function getPersistedSnapshot(snapshot, options) {
   const {
     nodes,
     _stateInputs,
+    _nextTimerId,
+    _nextActorIds,
     tags,
     machine,
     children,
@@ -5043,6 +5201,11 @@ function getPersistedSnapshot(snapshot, options) {
   if (_stateInputs && Object.keys(_stateInputs).length > 0) {
     persisted.stateInputs = _stateInputs;
   }
+  // Stores such as Convex reject `_`-prefixed field names.
+  persisted.nextTimerId = _nextTimerId;
+  if (_nextActorIds && Object.keys(_nextActorIds).length > 0) {
+    persisted.nextActorIds = _nextActorIds;
+  }
   if (machine.version !== undefined) {
     persisted.machine = {
       id: machine.id,
@@ -5074,7 +5237,7 @@ function persistContext(contextPart, getActorId, path = 'context', ancestors = [
         };
         // The address lets refs to non-children still route after restore.
         copy[key] = {
-          $actor: value.address
+          '@actor': value.address
         };
       } else {
         const valuePath = Array.isArray(contextPart) ? `${path}[${key}]` : `${path}.${key}`;
@@ -5716,11 +5879,18 @@ class RuntimeSystem {
   // Records a send on the *sender's* transition for the `sent[]` inspection
   // facet. Captures the send when it is initiated (including delayed sends that
   // may never deliver), keyed to the source actor's in-flight transition.
+  // A send made with no transition in flight (a callback's `sendBack`, a value
+  // an observable relays to its parent) is not recorded: no transition reports
+  // it, so it would be held until the source's next transition, or for as long
+  // as the source lives if it never makes one.
   _recordSent(source, target, event, delay, id) {
     if (!this._inspectionObservers?.size || !source) {
       return;
     }
     const inspectionSource = source;
+    if (!inspectionSource._inTransition) {
+      return;
+    }
     const collected = inspectionSource._collectedSent ??= [];
     collected.push({
       targetRef: target,
@@ -5957,9 +6127,9 @@ class RuntimeSystem {
       } else if (
       // A live actor of another incarnation is stale locally; an
       // address this system cannot see may belong to a host runtime.
-      this._getByAddress(target.$actor) || !this.runtime?.sendEvent) {
+      this._getByAddress(target['@actor']) || !this.runtime?.sendEvent) {
         return this.deadLetter(source, undefined, event, 'missingTarget', {
-          targetId: getAddressId(target.$actor),
+          targetId: getAddressId(target['@actor']),
           error: createMissingAddressError(target)
         });
       }
@@ -6246,6 +6416,12 @@ class Actor {
     this._collectedActions = void 0;
     /** @internal Events relayed to other actors during the in-flight transition. */
     this._collectedSent = void 0;
+    /**
+     * @internal Whether a transition is in flight: while the actor starts,
+     * processes an event, or recovers from an execution error. Sends are recorded
+     * for `sent[]` only then.
+     */
+    this._inTransition = false;
     this._initialEffects = void 0;
     this.registryKey = void 0;
     /** The globally unique process ID for this invocation. */
@@ -6318,9 +6494,14 @@ class Actor {
         // transition functions; computing an initial snapshot here would run
         // init-time side effects (context factories, entry) a second time.
       } else {
-        const [snapshot, effects] = finalizeTransitionResult(this._actorScope, undefined, this.logic.initialTransition(this.options?.input, this._actorScope));
-        this._setSnapshot(snapshot);
-        this._initialEffects = effects.length ? effects : undefined;
+        this._inTransition = true;
+        try {
+          const [snapshot, effects] = finalizeTransitionResult(this._actorScope, undefined, this.logic.initialTransition(this.options?.input, this._actorScope));
+          this._setSnapshot(snapshot);
+          this._initialEffects = effects.length ? effects : undefined;
+        } finally {
+          this._inTransition = false;
+        }
       }
     } catch (err) {
       // Restored logic may keep its snapshot shape on restore failures (e.g.
@@ -6473,6 +6654,8 @@ class Actor {
     if (!errorEvent) {
       return false;
     }
+    const inTransition = this._inTransition;
+    this._inTransition = true;
     try {
       const [nextSnapshot, effects] = finalizeTransitionResult(this._actorScope, snapshot, this.logic.transition(snapshot, errorEvent, this._actorScope));
       this._setSnapshot(nextSnapshot);
@@ -6481,6 +6664,8 @@ class Actor {
       return true;
     } catch {
       return false;
+    } finally {
+      this._inTransition = inTransition;
     }
   }
   _next(snapshot) {
@@ -6692,6 +6877,15 @@ class Actor {
 
   /** Starts the Actor from the initial state */
   start() {
+    const inTransition = this._inTransition;
+    this._inTransition = true;
+    try {
+      return this._start();
+    } finally {
+      this._inTransition = inTransition;
+    }
+  }
+  _start() {
     if (this._processingStatus === ProcessingStatus.Running) {
       // Do not restart the service if it is already started
       return this;
@@ -6807,7 +7001,16 @@ class Actor {
     this.mailbox?.start();
     return this;
   }
-  _process({
+  _process(item) {
+    const inTransition = this._inTransition;
+    this._inTransition = true;
+    try {
+      this._processEvent(item);
+    } finally {
+      this._inTransition = inTransition;
+    }
+  }
+  _processEvent({
     event,
     sourceRef
   }) {
@@ -7055,12 +7258,12 @@ class Actor {
   }
 
   /**
-   * Returns the actor's serializable logical identity: `{ $actor: address }`.
+   * Returns the actor's serializable logical identity: `{ "@actor": address }`.
    * The result can be used as an `enq.sendTo(...)` target.
    */
   toJSON() {
     return {
-      $actor: this.address
+      '@actor': this.address
     };
   }
 
@@ -7187,6 +7390,7 @@ exports.XSTATE_LOGIC_EFFECT_START = XSTATE_LOGIC_EFFECT_START;
 exports.XSTATE_STOP = XSTATE_STOP;
 exports.XSTATE_STOP_EFFECT = XSTATE_STOP_EFFECT;
 exports.XSTATE_TIMER = XSTATE_TIMER;
+exports.adoptSystem = adoptSystem;
 exports.allocateChildId = allocateChildId;
 exports.assertChildIdFree = assertChildIdFree;
 exports.assertUnreservedSourceName = assertUnreservedSourceName;
@@ -7286,4 +7490,5 @@ exports.toTransitionConfigArray = toTransitionConfigArray;
 exports.transitionNode = transitionNode;
 exports.withActorSelf = withActorSelf;
 exports.withExecutionIdentity = withExecutionIdentity;
+exports.withExecutionOwner = withExecutionOwner;
 exports.withSystemInspector = withSystemInspector;