xstate 6.0.0-alpha.8 → 6.0.0-beta.0

package/dist/xstate-durable.cjs.d.mts

@@ -0,0 +1,2 @@
+export * from "./declarations/src/durable/index.js";
+//# sourceMappingURL=data:application/json;charset=utf-8;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoieHN0YXRlLWR1cmFibGUuY2pzLmQubXRzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi9kZWNsYXJhdGlvbnMvc3JjL2R1cmFibGUvaW5kZXguZC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSJ9

package/dist/xstate-durable.cjs.d.ts

@@ -0,0 +1,2 @@
+export * from "./declarations/src/durable/index.js";
+//# sourceMappingURL=data:application/json;charset=utf-8;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoieHN0YXRlLWR1cmFibGUuY2pzLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuL2RlY2xhcmF0aW9ucy9zcmMvZHVyYWJsZS9pbmRleC5kLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBIn0=

package/dist/xstate-durable.cjs.js

@@ -0,0 +1,513 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var dist_xstatePersist = require('./xstate-persist.cjs.js');
+var createActor = require('./createActor-25900f76.cjs.js');
+var effectDescriptor = require('./effectDescriptor-2fa27c54.cjs.js');
+require('./machineSchemas-88d01821.cjs.js');
+require('./validation-4561b43c.cjs.js');
+
+/** @experimental */
+
+/** @experimental */
+
+/**
+ * An event addressed to a durable execution's root actor, captured while
+ * effects settled. `source` is the live reference of the sending actor when
+ * one initiated the send.
+ *
+ * @experimental
+ */
+
+/** @experimental */
+
+/**
+ * A durable host adapter: the runtime operations that execute this
+ * execution's effects, plus the durable loop hooks.
+ *
+ * The runtime operations (`sendEvent`, `scheduleTimer`, …) are installed on
+ * the actor system of every snapshot the execution produces, including
+ * children created during transitions and actors rehydrated from restored
+ * snapshots. Operations initiated by live child actors (parent sends,
+ * timers, terminations) route to them without any per-actor wiring; omitted
+ * operations keep their default local behavior.
+ *
+ * By default, events addressed to this execution's root actor do not reach
+ * `sendEvent` during `executeEffects`: the execution captures and retains
+ * them, and `waitForEvent()` hands them out before deferring to this adapter. While the loop is parked, a root-addressed event reaches
+ * `enqueueRootEvent`, or the broader `sendEvent` override when implemented,
+ * so the host can place it in its own mailbox.
+ *
+ * @experimental
+ */
+
+/** @experimental */
+class DurableExecutionCancelledError extends Error {
+  constructor() {
+    super('Durable execution was stopped');
+    this.name = 'DurableExecutionCancelledError';
+  }
+}
+
+/** @experimental */
+class DurableExecutionResumeError extends Error {
+  constructor() {
+    super('run() can only start a fresh durable execution; resume checkpoints with restore() and the explicit transition loop');
+    this.name = 'DurableExecutionResumeError';
+  }
+}
+
+/**
+ * The snapshot type a durable execution hands back: the logic's own snapshot,
+ * intersected with the base `Snapshot` union so the `status`/`output`/`error`
+ * discriminant stays visible even when `TLogic` is an unresolved type
+ * parameter (a generic host library), where `SnapshotFrom` alone is opaque.
+ *
+ * @experimental
+ */
+
+/** @experimental */
+
+/**
+ * Creates a host-neutral durable execution around pure actor transitions.
+ *
+ * The returned transition methods only calculate snapshots and tag their
+ * effects. Persistence, retries, messaging, timers and child execution remain
+ * responsibilities of the adapter.
+ *
+ * @experimental
+ */
+
+/** @experimental */
+function createDurable(logic, adapter, options) {
+  let nextTransitionIndex = adapter.transitionIndex ?? 0;
+  const startingTransitionIndex = nextTransitionIndex;
+  let restored = false;
+  const now = () => adapter.now?.() ?? Date.now();
+  const observedRoots = new WeakSet();
+  let lastTransitionIndex = nextTransitionIndex === 0 ? undefined : nextTransitionIndex - 1;
+  const restoredTimerDeadlines = new WeakMap();
+  if (!Number.isSafeInteger(nextTransitionIndex) || nextTransitionIndex < 0) {
+    throw new RangeError('transitionIndex must be a non-negative safe integer');
+  }
+  const tagEffects = (effects, restoring = false) => {
+    const transitionIndex = restoring ? nextTransitionIndex : nextTransitionIndex++;
+    lastTransitionIndex = restoring ? lastTransitionIndex ?? transitionIndex : transitionIndex;
+    return effects.map((effect, effectIndex) => {
+      const tagged = {
+        id: `${restoring ? 'restore:' : ''}${transitionIndex}:${effectIndex}`,
+        transitionIndex,
+        effectIndex,
+        effect
+      };
+      // Journaling hosts read the descriptor; executing hosts never do, so
+      // compute it (and its address walks) lazily, once.
+      let descriptor;
+      Object.defineProperty(tagged, 'descriptor', {
+        enumerable: true,
+        get: () => descriptor ??= effectDescriptor.describeExecutableEffect(effect)
+      });
+      return tagged;
+    });
+  };
+
+  // The root's address as the root actor reports it: root-event capture
+  // compares against `target.address`, which percent-encodes each segment.
+  const rootAddress = createActor.encodeAddressSegment(createActor.getRootActorId(logic));
+  const machineId = logic.id ?? rootAddress;
+  const machineVersion = logic.version;
+  // One identity object for the whole execution: session numbering continues
+  // across this execution's transitions, and a replay (a fresh createDurable
+  // with the same executionId) re-numbers identically.
+  const executionIdentity = adapter.executionId ? {
+    executionId: adapter.executionId,
+    nextSessionId: 0
+  } : undefined;
+
+  // The adapter's runtime operations, picked off the flat adapter shape.
+  const systemRuntime = {};
+  for (const operation of [...createActor.RUNTIME_OPERATIONS, 'sendEvent', 'runStep', 'runLogic']) {
+    const impl = adapter[operation];
+    if (impl) {
+      systemRuntime[operation] = impl.bind(adapter);
+    }
+  }
+  const hasSystemRuntime = Object.keys(systemRuntime).length > 0 || !!adapter.enqueueRootEvent;
+
+  // One batch per `executeEffects` call. The wrapped runtime stays installed
+  // on the actor system for the whole execution, so it also sees operations
+  // initiated while the loop is parked in `waitForEvent()` (for example a
+  // live child reacting to a host-originated delivery). Those belong to the
+  // host's domain: they run untracked and uncaptured, so a parked-window
+  // failure cannot be attributed to an unrelated later batch. Discarding a
+  // failed batch discards its captures and failures with it.
+
+  let currentBatch;
+
+  // Root-addressed events captured by settled batches, waiting for the drive
+  // loop to take them through `waitForEvent()`.
+  const pendingRootEvents = [];
+
+  // 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
+  // replay. An operation must therefore never await another operation of the
+  // same execution through the actor system — it would wait behind itself.
+  let operationTail = Promise.resolve();
+  const track = (batch, operation) => {
+    batch.pending.add(operation);
+    void operation.catch(error => {
+      // Collect the failure so it reaches `executeEffects` even when the
+      // operation leaves the pending set before settle() samples it.
+      batch.failures.push(error);
+    }).then(() => batch.pending.delete(operation));
+    return operation;
+  };
+  const handOff = (batch, run) => {
+    const operation = operationTail.then(run).then(() => undefined);
+    operationTail = operation.catch(() => {});
+    return track(batch, operation);
+  };
+
+  // Hands an operation over according to where it was initiated: batched
+  // during `executeEffects`, immediate while the loop is parked.
+  const dispatch = run => currentBatch ? handOff(currentBatch, run) : run();
+  const drain = async batch => {
+    while (batch.pending.size) {
+      await Promise.allSettled([...batch.pending]);
+    }
+  };
+  const settle = async batch => {
+    await drain(batch);
+    if (batch.failures.length) {
+      throw batch.failures[0];
+    }
+  };
+  function wrapRuntime(runtime, localDeliveryFallback,
+  // When set, operations neither this runtime nor the adapter implements
+  // keep the behavior they would have had without a per-effect runtime,
+  // running against the operation's own actor's system (per-system timer
+  // bookkeeping must land on that system, not the root's). Safe from
+  // re-entrant dispatch: that system's installed runtime lacks these
+  // operations by construction, so the call falls through to local
+  // behavior.
+  fallbackToActorSystem = false, timerDeadline) {
+    const wrapped = {};
+    for (const operation of createActor.RUNTIME_OPERATIONS) {
+      const impl = runtime[operation] ?? (fallbackToActorSystem ? (...args) => {
+        const owner = operation === 'spawnActor' ? args[1] : args[0];
+        return owner.system[operation](...args);
+      } : undefined);
+      if (impl) {
+        wrapped[operation] = (...args) => dispatch(() => {
+          // Runtime operations can queue behind asynchronous child startup.
+          // Calculate the remaining time when dispatching to the adapter.
+          if (operation === 'scheduleTimer' && timerDeadline) {
+            args[2] = Math.min(timerDeadline.delay, Math.max(0, timerDeadline.deadline - now()));
+          }
+          if (operation === 'scheduleTimer') {
+            const source = args[0];
+            const key = args[1];
+            const timer = source.getSnapshot()?.timers?.find(pending => createActor.matchesTimerKey(pending, key));
+            if (timer) {
+              const previousStart = createActor.getTimerStart(timer);
+              if (previousStart !== undefined && !timerDeadline) {
+                args[2] = Math.min(timer.delay, Math.max(0, previousStart + timer.delay - now()));
+              }
+              const result = impl(...args);
+              if (result) {
+                return Promise.resolve(result).then(() => {
+                  createActor.recordTimerStart(timer, previousStart ?? now());
+                });
+              }
+              createActor.recordTimerStart(timer, previousStart ?? now());
+              return;
+            }
+          }
+          return impl(...args);
+        });
+      }
+    }
+    // A step is an orchestration frame: it may itself await runtime
+    // operations of this execution, so it passes through undispatched —
+    // queuing it on the operation tail would make it wait behind (and
+    // deadlock with) the operations its own body initiates.
+    if (runtime.runStep) {
+      wrapped.runStep = runtime.runStep;
+    }
+    if (runtime.runLogic) {
+      wrapped.runLogic = runtime.runLogic;
+    }
+    wrapped.sendEvent = (source, target, event) => {
+      const captureBatch = options?.captureRootEvents !== false ? currentBatch : undefined;
+      if (!captureBatch && target.address === rootAddress && !runtime.sendEvent && adapter.enqueueRootEvent) {
+        return dispatch(() => adapter.enqueueRootEvent(source, event));
+      }
+      if (!captureBatch && target.address === rootAddress && !runtime.sendEvent) {
+        // The root actor is inert; delivering locally would enqueue into a
+        // mailbox that never runs, silently losing the event.
+        throw new Error(`A root-addressed event ("${event.type}") was produced outside batch capture (for example, while the durable loop was parked), but the adapter has no enqueueRootEvent or sendEvent to receive it. Implement enqueueRootEvent to place root-addressed events in the host's mailbox.`);
+      }
+      if (captureBatch && target.address === rootAddress) {
+        captureBatch.rootEvents.push({
+          event,
+          source
+        });
+        return;
+      }
+      const impl = runtime.sendEvent;
+      if (impl) {
+        return dispatch(() => impl(source, target, event));
+      }
+      if (localDeliveryFallback) {
+        return dispatch(() => createActor.deliverEvent(source, target, event));
+      }
+      throw new TypeError(`The durable runtime does not support the sendEvent operation (target '${target.address}')`);
+    };
+    return wrapped;
+  }
+  const wrappedSystemRuntime = hasSystemRuntime ? wrapRuntime(systemRuntime, true) : undefined;
+
+  // Depth-first walk of the live actor tree by logical address. Subtrees
+  // whose address is not a prefix of the target are pruned.
+  function findByAddress(actor, address) {
+    if (actor.address === address) {
+      return actor;
+    }
+    if (!address.startsWith(`${actor.address}/`)) {
+      return undefined;
+    }
+    const children = actor.getSnapshot().children;
+    for (const child of Object.values(children ?? {})) {
+      const found = child && findByAddress(child, address);
+      if (found) {
+        return found;
+      }
+    }
+    return undefined;
+  }
+  const inspect = options?.inspect;
+
+  // 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
+  // — a snapshot's system first touched here, or a restored child's foreign
+  // system. Observer presence doubles as the dedup check: this execution is
+  // the only thing attaching observers to its systems.
+  function wireInspection(system) {
+    if (inspect && !system._hasInspectionObservers?.()) {
+      system.inspect(inspect);
+    }
+  }
+  function installSystemRuntime(snapshot, recursive = false) {
+    if (snapshot.status === 'error') {
+      const root = createActor.getSnapshotActorRef(snapshot)?.actor;
+      if (root && !observedRoots.has(root)) {
+        // The host consumes error snapshots (run() rejects with their error).
+        // Observe before termination effects execute, without materializing
+        // otherwise lazy roots during successful pure transitions.
+        root.subscribe({
+          error() {}
+        });
+        observedRoots.add(root);
+      }
+    }
+    if (wrappedSystemRuntime || inspect) {
+      const ref = createActor.getSnapshotActorRef(snapshot)?.actor;
+      const systems = new Set();
+      const visit = actor => {
+        if (!systems.has(actor.system)) {
+          systems.add(actor.system);
+          if (wrappedSystemRuntime) {
+            actor.system.runtime = wrappedSystemRuntime;
+          }
+          wireInspection(actor.system);
+        }
+        if (recursive) {
+          const children = actor.getSnapshot().children;
+          for (const child of Object.values(children ?? {})) {
+            if (child) {
+              visit(child);
+            }
+          }
+        }
+      };
+      if (ref) {
+        visit(ref);
+      }
+      if (!recursive || !ref) {
+        const children = snapshot.children;
+        for (const child of Object.values(children ?? {})) {
+          if (child) {
+            visit(child);
+          }
+        }
+      }
+    }
+    return snapshot;
+  }
+  const execution = {
+    rootAddress,
+    machineId,
+    machineVersion,
+    get nextTransitionIndex() {
+      return nextTransitionIndex;
+    },
+    restore(persistedSnapshot) {
+      if (restored || nextTransitionIndex !== startingTransitionIndex || currentBatch) {
+        throw new Error('restore() requires a fresh durable execution');
+      }
+      const {
+        snapshot,
+        scope
+      } = createActor.withSystemInspector(inspect, () => createActor.withExecutionIdentity(executionIdentity, () => {
+        const scope = createActor.createInertActorScope(logic);
+        const snapshot = dist_xstatePersist.restoreLogicSnapshot(logic, persistedSnapshot, scope);
+        createActor.setInertActorScopeSnapshot(scope, snapshot, false);
+        return {
+          snapshot: installSystemRuntime(createActor.attachSnapshotActorRef(scope, snapshot), true),
+          scope
+        };
+      }));
+      const effects = [];
+      if (snapshot.status === 'active') {
+        const {
+          children,
+          timers
+        } = snapshot;
+        for (const child of Object.values(children ?? {})) {
+          if (child && !createActor.isRemoteActorRef(child) && child.getSnapshot().status === 'active') {
+            effects.push(createActor.createStartEffect(child));
+          }
+        }
+        for (const timer of timers ?? []) {
+          const effect = createActor.createTimerEffect(scope, timer, timer.delay);
+          if (timer.scheduledAt !== undefined) {
+            restoredTimerDeadlines.set(effect, {
+              deadline: timer.scheduledAt + timer.delay,
+              delay: timer.delay
+            });
+          }
+          effects.push(effect);
+        }
+      }
+      restored = true;
+      return [snapshot, tagEffects(effects, true)];
+    },
+    initialTransition(...args) {
+      if (restored) {
+        throw new Error('initialTransition() cannot initialize a restored execution');
+      }
+      const [snapshot, effects] = createActor.withSystemInspector(inspect, () => createActor.withExecutionIdentity(executionIdentity, () => effectDescriptor.initialTransition(logic, ...args)));
+      return [installSystemRuntime(snapshot), tagEffects(effects)];
+    },
+    transition(snapshot, event) {
+      const [nextSnapshot, effects] = createActor.withSystemInspector(inspect, () => createActor.withExecutionIdentity(executionIdentity, () => effectDescriptor.transition(logic, snapshot, event)));
+      return [installSystemRuntime(nextSnapshot), tagEffects(effects)];
+    },
+    getActorRef(snapshot, address) {
+      const root = createActor.getSnapshotActorRef(snapshot)?.actor;
+      if (!root || address === undefined) {
+        return root;
+      }
+      return findByAddress(root, address);
+    },
+    async executeEffects(effects) {
+      if (currentBatch) {
+        throw new Error('executeEffects calls must not overlap: await the previous call before starting the next batch.');
+      }
+      const batch = {
+        rootEvents: [],
+        failures: [],
+        pending: new Set()
+      };
+      currentBatch = batch;
+      // `undefined` lets the effect's default parameter (the actor's system,
+      // and through it the installed `systemRuntime`) apply; without any
+      // runtime, the empty object makes unsupported operations throw instead
+      // of silently running local behavior on a durable host.
+      const fallbackRuntime = hasSystemRuntime ? undefined : {};
+      try {
+        for (const tagged of effects) {
+          const {
+            effect
+          } = tagged;
+          const metadata = {
+            id: tagged.id,
+            transitionIndex: tagged.transitionIndex,
+            effectIndex: tagged.effectIndex
+          };
+          const perEffectRuntime = adapter.runtime?.(metadata, effect);
+          const timerDeadline = restoredTimerDeadlines.get(effect);
+          // A per-effect runtime overrides the system runtime
+          // operation-by-operation; operations it omits keep the system
+          // runtime's behavior.
+          const runtime = perEffectRuntime || timerDeadline ? wrapRuntime({
+            ...systemRuntime,
+            ...perEffectRuntime
+          }, hasSystemRuntime, !!perEffectRuntime || hasSystemRuntime, timerDeadline) : fallbackRuntime;
+          if (effect.kind === 'action') {
+            // Custom actions have no default-parameter fallback to the actor's
+            // system, so hand them the wrapped system runtime directly.
+            await adapter.executeAction(effect, metadata, runtime ?? wrappedSystemRuntime ?? {});
+          } else {
+            await effect.exec(runtime);
+          }
+        }
+        await settle(batch);
+        pendingRootEvents.push(...batch.rootEvents);
+      } catch (error) {
+        // Drain before discarding so batch-initiated operations are not still
+        // running when the retrying host re-executes the effects. The failed
+        // batch's captures and failures are discarded with it.
+        await drain(batch);
+        throw error;
+      } finally {
+        // Runs after `settle()`/`drain()`, so operations the batch initiated
+        // are still treated as in-batch while they finish.
+        currentBatch = undefined;
+      }
+    },
+    async waitForEvent() {
+      if (lastTransitionIndex === undefined) {
+        throw new Error('Cannot wait for an event before the first transition or restore');
+      }
+      // Root-bound events produced while effects executed are handed out
+      // before durably waiting for an external event.
+      const queued = pendingRootEvents.shift();
+      if (queued) {
+        return queued.event;
+      }
+      return adapter.waitForEvent({
+        id: restored && nextTransitionIndex === 0 ? 'event:restore:0' : `event:${lastTransitionIndex}`,
+        transitionIndex: lastTransitionIndex
+      });
+    },
+    async run(...args) {
+      if (restored || startingTransitionIndex !== 0 || nextTransitionIndex !== startingTransitionIndex) {
+        throw new DurableExecutionResumeError();
+      }
+      let [snapshot, effects] = execution.initialTransition(...args);
+      await execution.executeEffects(effects);
+      while (snapshot.status === 'active') {
+        const event = await execution.waitForEvent();
+        [snapshot, effects] = execution.transition(snapshot, event);
+        await execution.executeEffects(effects);
+      }
+      const terminalSnapshot = snapshot;
+      if (terminalSnapshot.status === 'done') {
+        return terminalSnapshot.output;
+      }
+      if (terminalSnapshot.status === 'error') {
+        throw terminalSnapshot.error;
+      }
+      throw new DurableExecutionCancelledError();
+    }
+  };
+  return execution;
+}
+
+exports.DurableExecutionCancelledError = DurableExecutionCancelledError;
+exports.DurableExecutionResumeError = DurableExecutionResumeError;
+exports.createDurable = createDurable;

package/dist/xstate-durable.cjs.mjs

@@ -0,0 +1,5 @@
+export {
+  DurableExecutionCancelledError,
+  DurableExecutionResumeError,
+  createDurable
+} from "./xstate-durable.cjs.js";