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

package/dist/xstate-durable.esm.js

@@ -1,7 +1,7 @@
 import { restoreLogicSnapshot } from './xstate-persist.esm.js';
-import { j as encodeAddressSegment, aK as getRootActorId, aL as RUNTIME_OPERATIONS, aM as withSystemInspector, aH as isRemoteActorRef, aB as createStartEffect, aN as createTimerEffect, aO as getSnapshotActorRef, aP as withExecutionIdentity, ai as createInertActorScope, aj as setInertActorScopeSnapshot, al as attachSnapshotActorRef, z as matchesTimerKey, aQ as getTimerStart, aR as recordTimerStart, L as deliverEvent } from './createActor-cbe3abac.esm.js';
-import { a as initialTransition, t as transition, d as describeExecutableEffect } from './effectDescriptor-d8b0f749.esm.js';
-import './machineSchemas-45c21bc2.esm.js';
+import { j as encodeAddressSegment, aK as getRootActorId, aL as RUNTIME_OPERATIONS, aH as isRemoteActorRef, aB as createStartEffect, aM as createTimerEffect, aN as getSnapshotActorRef, A as isMachineSnapshot, aO as withExecutionOwner, z as matchesTimerKey, aP as getTimerStart, aQ as recordTimerStart, L as deliverEvent, aR as withSystemInspector, aS as adoptSystem, aT as withExecutionIdentity, ai as createInertActorScope, aj as setInertActorScopeSnapshot, al as attachSnapshotActorRef } from './createActor-20a97166.esm.js';
+import { d as describeExecutableEffect, a as initialTransition, t as transition } from './effectDescriptor-e93df910.esm.js';
+import './legacySnapshot-9e06feb4.esm.js';
 import './validation-05f1d517.esm.js';
 
 /** @experimental */
@@ -16,6 +16,36 @@ import './validation-05f1d517.esm.js';
  * @experimental
  */
 
+/**
+ * A root-addressed event that the execution received but has not processed,
+ * stored in a checkpoint. `source` is the sender's logical address.
+ *
+ * @experimental
+ */
+
+/**
+ * Everything needed to resume an execution: the persisted snapshot, the next
+ * transition index and the events received but not yet processed. Persist
+ * the whole object atomically and pass it to `restore()`.
+ *
+ * @experimental
+ */
+
+// Lifecycle events that address a child by `actorId`. Snapshot updates are
+// not stored: a restored child reports its current snapshot when it starts.
+const storedLifecycleEvents = new Set(['xstate.done.actor', 'xstate.error.actor', 'xstate.timeout.actor']);
+function isCheckpoint(value) {
+  return !!value && typeof value === 'object' && 'inbox' in value && 'nextTransitionIndex' in value && 'snapshot' in value;
+}
+function isInboxEntry(item) {
+  if (!item || typeof item !== 'object') return false;
+  const {
+    event,
+    source
+  } = item;
+  return !!event && typeof event.type === 'string' && (source === undefined || !!source && typeof source['@actor'] === 'string' && (source.incarnation === undefined || typeof source.incarnation === 'string'));
+}
+
 /** @experimental */
 
 /**
@@ -145,6 +175,15 @@ function createDurable(logic, adapter, options) {
   // loop to take them through `waitForEvent()`.
   const pendingRootEvents = [];
 
+  // For a stored lifecycle event: the child it addresses in `snapshot`, or
+  // `null` when that child is gone. `undefined` for any other event.
+  const lifecycleChild = (snapshot, event) => {
+    if (!isMachineSnapshot(snapshot) || !storedLifecycleEvents.has(event.type) || typeof event.actorId !== 'string') {
+      return undefined;
+    }
+    return snapshot.children[event.actorId] ?? null;
+  };
+
   // Every inter-actor edge is an async handoff to the runtime, and every
   // handoff queues behind the last one: hosts whose step or activity model
   // forbids concurrent entries depend on that, and so does deterministic
@@ -285,6 +324,16 @@ function createDurable(logic, adapter, options) {
   }
   const inspect = options?.inspect;
 
+  // Runs a transition as this execution: views it derives belong to this
+  // execution, and its systems report to the execution's inspector.
+  const owner = {
+    runtime: wrappedSystemRuntime,
+    inspect
+  };
+  function inExecution(fn) {
+    return withExecutionOwner(owner, () => withSystemInspector(inspect, fn));
+  }
+
   // Attaches the execution's inspector to a system that does not have it
   // yet. Systems constructed inside a transition get it at construction (the
   // ambient inspector); this covers systems materialized outside that window
@@ -315,10 +364,12 @@ function createDurable(logic, adapter, options) {
       const visit = actor => {
         if (!systems.has(actor.system)) {
           systems.add(actor.system);
-          if (wrappedSystemRuntime) {
-            actor.system.runtime = wrappedSystemRuntime;
+          if (adoptSystem(actor.system, owner)) {
+            if (wrappedSystemRuntime) {
+              actor.system.runtime = wrappedSystemRuntime;
+            }
+            wireInspection(actor.system);
           }
-          wireInspection(actor.system);
         }
         if (recursive) {
           const children = actor.getSnapshot().children;
@@ -350,14 +401,55 @@ function createDurable(logic, adapter, options) {
     get nextTransitionIndex() {
       return nextTransitionIndex;
     },
-    restore(persistedSnapshot) {
+    checkpoint(snapshot, persistOptions) {
+      const inbox = [];
+      for (const {
+        event,
+        source
+      } of pendingRootEvents) {
+        const child = lifecycleChild(snapshot, event);
+        if (event.type === 'xstate.snapshot.actor' || child !== undefined && (!child || event.sessionId !== undefined && child.sessionId !== undefined && child.sessionId !== event.sessionId)) {
+          continue;
+        }
+        inbox.push({
+          event,
+          source: source && {
+            '@actor': source.address,
+            ...(isRemoteActorRef(source) && source.sessionId !== undefined ? {
+              incarnation: source.sessionId
+            } : {})
+          }
+        });
+      }
+      return {
+        snapshot: logic.getPersistedSnapshot?.(snapshot, persistOptions) ?? snapshot,
+        nextTransitionIndex,
+        inbox
+      };
+    },
+    restore(checkpointOrSnapshot) {
+      const checkpoint = isCheckpoint(checkpointOrSnapshot) ? checkpointOrSnapshot : undefined;
       if (restored || nextTransitionIndex !== startingTransitionIndex || currentBatch) {
         throw new Error('restore() requires a fresh durable execution');
       }
+      if (checkpoint) {
+        if (!Array.isArray(checkpoint.inbox) || !checkpoint.inbox.every(isInboxEntry)) {
+          throw new TypeError('The checkpoint inbox is invalid.');
+        }
+        if (adapter.transitionIndex !== undefined && adapter.transitionIndex !== checkpoint.nextTransitionIndex) {
+          throw new RangeError(`The adapter's transitionIndex (${adapter.transitionIndex}) does not match the checkpoint's nextTransitionIndex (${checkpoint.nextTransitionIndex}).`);
+        }
+        if (!Number.isSafeInteger(checkpoint.nextTransitionIndex) || checkpoint.nextTransitionIndex < 0) {
+          throw new RangeError('nextTransitionIndex must be a non-negative safe integer');
+        }
+        nextTransitionIndex = checkpoint.nextTransitionIndex;
+        lastTransitionIndex = nextTransitionIndex === 0 ? undefined : nextTransitionIndex - 1;
+      }
+      const persistedSnapshot = checkpoint ? checkpoint.snapshot : checkpointOrSnapshot;
       const {
         snapshot,
         scope
-      } = withSystemInspector(inspect, () => withExecutionIdentity(executionIdentity, () => {
+      } = inExecution(() => withExecutionIdentity(executionIdentity, () => {
         const scope = createInertActorScope(logic);
         const snapshot = restoreLogicSnapshot(logic, persistedSnapshot, scope);
         setInertActorScopeSnapshot(scope, snapshot, false);
@@ -366,6 +458,24 @@ function createDurable(logic, adapter, options) {
           scope
         };
       }));
+      for (const {
+        event,
+        source
+      } of checkpoint?.inbox ?? []) {
+        const child = lifecycleChild(snapshot, event);
+        if (child === null) {
+          continue;
+        }
+        pendingRootEvents.push({
+          // A restored child has a new session; its pending lifecycle events
+          // follow it.
+          event: child && child.sessionId !== undefined && 'sessionId' in event ? {
+            ...event,
+            sessionId: child.sessionId
+          } : event,
+          source: source && execution.getActorRef(snapshot, source['@actor'])
+        });
+      }
       const effects = [];
       if (snapshot.status === 'active') {
         const {
@@ -395,11 +505,11 @@ function createDurable(logic, adapter, options) {
       if (restored) {
         throw new Error('initialTransition() cannot initialize a restored execution');
       }
-      const [snapshot, effects] = withSystemInspector(inspect, () => withExecutionIdentity(executionIdentity, () => initialTransition(logic, ...args)));
+      const [snapshot, effects] = inExecution(() => withExecutionIdentity(executionIdentity, () => initialTransition(logic, ...args)));
       return [installSystemRuntime(snapshot), tagEffects(effects)];
     },
     transition(snapshot, event) {
-      const [nextSnapshot, effects] = withSystemInspector(inspect, () => withExecutionIdentity(executionIdentity, () => transition(logic, snapshot, event)));
+      const [nextSnapshot, effects] = inExecution(() => withExecutionIdentity(executionIdentity, () => transition(logic, snapshot, event)));
       return [installSystemRuntime(nextSnapshot), tagEffects(effects)];
     },
     getActorRef(snapshot, address) {