xstate 6.0.0-alpha.61 → 6.0.0-alpha.63

package/README.md

@@ -17,6 +17,13 @@ XState is a state management and orchestration solution for JavaScript and TypeS
 
 It uses event-driven programming, state machines, statecharts, and the actor model to handle complex logic in predictable, robust, and visual ways. XState provides a powerful and flexible way to manage application and workflow state by allowing developers to model logic as actors and state machines.
 
+<!-- durable execution and checkpoint restoration from packages/core/src/durable/index.ts -->
+
+For durable hosts, the experimental `xstate/durable` entry point provides
+`createDurable`. Resume a checkpoint with `execution.restore(persistedSnapshot)`
+and execute the returned effects to restart active embedded children and pending
+timers without replaying entry actions. See [durable execution](../../docs/durable-execution.md).
+
 For flat finite state machines, `xstate/fsm` provides a tiny pure transition
 table with context and TypeScript support:
 

package/dist/{createActor-0d08a5f3.development.esm.js → createActor-48f753a9.development.esm.js}

@@ -1129,6 +1129,8 @@ function getBuiltInActionFields(action, args) {
       return undefined;
   }
 }
+
+/** @internal Creates an actor-start effect, including for restored children. */
 function createStartEffect(actor) {
   const args = [actor];
   return {
@@ -1142,6 +1144,41 @@ function createStartEffect(actor) {
     id: actor.id
   };
 }
+
+/** @internal Recreates a pending logical timer without re-entering its state. */
+function createTimerEffect(actorScope, timer, delay) {
+  const source = actorScope.self;
+  const options = {
+    id: timer.id,
+    delay
+  };
+  if (timer.type === '@xstate.raise') {
+    return {
+      kind: 'builtin',
+      type: timer.type,
+      source,
+      event: timer.event,
+      id: timer.id,
+      delay,
+      params: undefined,
+      args: [actorScope, timer.event, options],
+      exec: execRaiseEffect
+    };
+  }
+  const target = timer.target === 'self' ? source : timer.target;
+  return {
+    kind: 'builtin',
+    type: timer.type,
+    source,
+    target,
+    event: timer.event,
+    id: timer.id,
+    delay,
+    params: undefined,
+    args: [actorScope, target, timer.event, options],
+    exec: execSendToEffect
+  };
+}
 function createSpawnEffect(actor) {
   const args = [actor];
   return {
@@ -2097,11 +2134,19 @@ function getCandidates(stateNode, event) {
 function scheduleDelayedEvent(stateNode, timerId, resolveEvent, resolveScheduledDelay) {
   const oldEntry = stateNode.entry;
   stateNode.entry = (x, enq) => {
+    const result = typeof oldEntry === 'function' ? oldEntry(x, enq) : undefined;
+    // The entry context patch is applied by the caller after this wrapper returns.
+    const context = result?.context !== undefined ? mergeContextPatch(x.context, result.context) : x.context;
     enq.raise(resolveEvent(x), {
       id: timerId,
-      delay: resolveScheduledDelay(x)
+      delay: resolveScheduledDelay({
+        context,
+        event: x.event,
+        delays: x.delays,
+        input: x.input
+      })
     });
-    return typeof oldEntry === 'function' ? oldEntry(x, enq) : undefined;
+    return result;
   };
   const oldExit = stateNode.exit;
   stateNode.exit = (_, enq) => {
@@ -5412,6 +5457,9 @@ class Actor {
     this._deferred = void 0;
     this._restored = false;
     this._warnedUnhandledTypes = void 0;
+    if (options && 'state' in options) {
+      throw new Error('The "state" actor option was removed. Pass the persisted snapshot as "snapshot" instead: createActor(logic, { snapshot }).');
+    }
     const resolvedOptions = options ? {
       ...defaultOptions,
       ...options
@@ -5428,7 +5476,7 @@ class Actor {
     this.system = parent ? parent.system : resolvedOptions._systemRef?.current ?? createRuntimeSystem(this, {
       clock,
       logger,
-      snapshot: resolvedOptions.snapshot ?? resolvedOptions.state,
+      snapshot: resolvedOptions.snapshot,
       createActorRef
     });
     if (!parent && resolvedOptions._systemRef && !resolvedOptions._systemRef.current) {
@@ -5461,7 +5509,7 @@ class Actor {
 
     // prepare to collect initial microsteps during initialTransition
     this._collectedMicrosteps = undefined;
-    const persistedState = options?.snapshot ?? options?.state;
+    const persistedState = options?.snapshot;
     this._restored = persistedState !== undefined;
     try {
       if (persistedState) {
@@ -6223,7 +6271,7 @@ class Actor {
    * {@link Actor.getSnapshot}. Persisted state represents the internal state of
    * the actor, while snapshots represent the actor's last emitted value.
    *
-   * Can be restored with {@link ActorOptions.state}
+   * Can be restored with {@link ActorOptions.snapshot}
    * @see https://stately.ai/docs/persistence
    */
 
@@ -6271,7 +6319,7 @@ class Actor {
 
 /**
  * The options `createActor` (and framework hooks) require for `TLogic`:
- * `{ input }` or a persisted `{ snapshot }` (or deprecated `{ state }`) when
+ * `{ input }` or a persisted `{ snapshot }` when
  * the logic requires input, otherwise nothing.
  *
  * @public
@@ -6323,4 +6371,4 @@ function createActor(logic, ...[options]) {
   return new Actor(logic, options);
 }
 
-export { ACTOR_REF_TYPE as $, attachSnapshotActorRef as A, macrostep as B, isInertActorScope as C, setSnapshotActorRef as D, cloneMachineSnapshot as E, transitionNode as F, getTransitionResult as G, hasEffect as H, createErrorPlatformEvent as I, withActorSelf as J, resolveActionsWithContext as K, takeSpawnAllocationCounters as L, mergeActorIdCounters as M, NULL_EVENT as N, createInitEvent as O, createSpawnEffect as P, initialMicrostep as Q, toStatePath as R, STATE_DELIMITER as S, isStateId as T, getStateNodeByPath as U, getPersistedSnapshot as V, createRemoteActorRef as W, XSTATE_TIMER as X, resolveReferencedActor as Y, createInvokeTimeoutEvent as Z, parseGeneratedActorId as _, allocateChildId as a, createActor as a0, parseDelayToMilliseconds as a1, isAtomicStateNode as a2, ProcessingStatus as a3, isActorRefLike as a4, createListenerLogic as a5, createSubscriptionLogic as a6, listenerLogic as a7, subscriptionLogic as a8, Actor as a9, getAllOwnEvents as aA, matchesEvent as aB, encodeAddressSegment as aC, getRootActorId as aD, RUNTIME_OPERATIONS as aE, withSystemInspector as aF, getSnapshotActorRef as aG, withExecutionIdentity as aH, isMachineSnapshot as aa, InfiniteTransitionError as ab, getAllOwnEventDescriptors as ac, matchesState as ad, checkStateIn as ae, pathToStateValue as af, toObserver as ag, executeEffects as ah, isBuiltInExecutableAction as ai, deliverEvent as aj, runStep as ak, stopActor as al, terminateActor as am, XSTATE_STOP as an, createCustomEffect as ao, XSTATE_LOGIC_EFFECT_START as ap, XSTATE_LOGIC_EFFECT_RESOLVE as aq, XSTATE_LOGIC_EFFECT_REJECT as ar, finalizeTransitionResult as as, createEmitEffect as at, createSendToEffect as au, XSTATE_INIT as av, hasAmbientInspector as aw, getProperAncestors as ax, isRemoteActorRef as ay, getActorIdPrefix as az, assertChildIdFree as b, reserveChildId as c, mapValues as d, createInvokeId as e, getEventDescriptorKey as f, getDelayedTransitions as g, getCandidates as h, evaluateCandidate as i, formatTransition as j, toTransitionConfigArray as k, createInvokeTimeoutEventId as l, matchesEventDescriptor as m, matchesActorSession as n, formatRouteTransitions as o, resolveStateValue as p, getAllStateNodes as q, resolveRegisteredActorSource as r, getStateNodes as s, toArray as t, createMachineSnapshot as u, isInFinalState as v, createInertActorScope as w, setInertActorScopeSnapshot as x, createDeadLetterEffect as y, beginSpawnAllocation as z };
+export { parseGeneratedActorId as $, attachSnapshotActorRef as A, macrostep as B, isInertActorScope as C, setSnapshotActorRef as D, cloneMachineSnapshot as E, transitionNode as F, getTransitionResult as G, hasEffect as H, createErrorPlatformEvent as I, withActorSelf as J, resolveActionsWithContext as K, takeSpawnAllocationCounters as L, mergeActorIdCounters as M, NULL_EVENT as N, createInitEvent as O, createSpawnEffect as P, initialMicrostep as Q, createStartEffect as R, STATE_DELIMITER as S, toStatePath as T, isStateId as U, getStateNodeByPath as V, getPersistedSnapshot as W, XSTATE_TIMER as X, createRemoteActorRef as Y, resolveReferencedActor as Z, createInvokeTimeoutEvent as _, allocateChildId as a, ACTOR_REF_TYPE as a0, createActor as a1, parseDelayToMilliseconds as a2, isAtomicStateNode as a3, ProcessingStatus as a4, isActorRefLike as a5, createListenerLogic as a6, createSubscriptionLogic as a7, listenerLogic as a8, subscriptionLogic as a9, getActorIdPrefix as aA, getAllOwnEvents as aB, matchesEvent as aC, encodeAddressSegment as aD, getRootActorId as aE, RUNTIME_OPERATIONS as aF, withSystemInspector as aG, createTimerEffect as aH, getSnapshotActorRef as aI, withExecutionIdentity as aJ, Actor as aa, isMachineSnapshot as ab, InfiniteTransitionError as ac, getAllOwnEventDescriptors as ad, matchesState as ae, checkStateIn as af, pathToStateValue as ag, toObserver as ah, executeEffects as ai, isBuiltInExecutableAction as aj, deliverEvent as ak, runStep as al, stopActor as am, terminateActor as an, XSTATE_STOP as ao, createCustomEffect as ap, XSTATE_LOGIC_EFFECT_START as aq, XSTATE_LOGIC_EFFECT_RESOLVE as ar, XSTATE_LOGIC_EFFECT_REJECT as as, finalizeTransitionResult as at, createEmitEffect as au, createSendToEffect as av, XSTATE_INIT as aw, hasAmbientInspector as ax, getProperAncestors as ay, isRemoteActorRef as az, assertChildIdFree as b, reserveChildId as c, mapValues as d, createInvokeId as e, getEventDescriptorKey as f, getDelayedTransitions as g, getCandidates as h, evaluateCandidate as i, formatTransition as j, toTransitionConfigArray as k, createInvokeTimeoutEventId as l, matchesEventDescriptor as m, matchesActorSession as n, formatRouteTransitions as o, resolveStateValue as p, getAllStateNodes as q, resolveRegisteredActorSource as r, getStateNodes as s, toArray as t, createMachineSnapshot as u, isInFinalState as v, createInertActorScope as w, setInertActorScopeSnapshot as x, createDeadLetterEffect as y, beginSpawnAllocation as z };

package/dist/{createActor-f4b06bda.esm.js → createActor-523a98c7.esm.js}

@@ -1119,6 +1119,8 @@ function getBuiltInActionFields(action, args) {
       return undefined;
   }
 }
+
+/** @internal Creates an actor-start effect, including for restored children. */
 function createStartEffect(actor) {
   const args = [actor];
   return {
@@ -1132,6 +1134,41 @@ function createStartEffect(actor) {
     id: actor.id
   };
 }
+
+/** @internal Recreates a pending logical timer without re-entering its state. */
+function createTimerEffect(actorScope, timer, delay) {
+  const source = actorScope.self;
+  const options = {
+    id: timer.id,
+    delay
+  };
+  if (timer.type === '@xstate.raise') {
+    return {
+      kind: 'builtin',
+      type: timer.type,
+      source,
+      event: timer.event,
+      id: timer.id,
+      delay,
+      params: undefined,
+      args: [actorScope, timer.event, options],
+      exec: execRaiseEffect
+    };
+  }
+  const target = timer.target === 'self' ? source : timer.target;
+  return {
+    kind: 'builtin',
+    type: timer.type,
+    source,
+    target,
+    event: timer.event,
+    id: timer.id,
+    delay,
+    params: undefined,
+    args: [actorScope, target, timer.event, options],
+    exec: execSendToEffect
+  };
+}
 function createSpawnEffect(actor) {
   const args = [actor];
   return {
@@ -2087,11 +2124,19 @@ function getCandidates(stateNode, event) {
 function scheduleDelayedEvent(stateNode, timerId, resolveEvent, resolveScheduledDelay) {
   const oldEntry = stateNode.entry;
   stateNode.entry = (x, enq) => {
+    const result = typeof oldEntry === 'function' ? oldEntry(x, enq) : undefined;
+    // The entry context patch is applied by the caller after this wrapper returns.
+    const context = result?.context !== undefined ? mergeContextPatch(x.context, result.context) : x.context;
     enq.raise(resolveEvent(x), {
       id: timerId,
-      delay: resolveScheduledDelay(x)
+      delay: resolveScheduledDelay({
+        context,
+        event: x.event,
+        delays: x.delays,
+        input: x.input
+      })
     });
-    return typeof oldEntry === 'function' ? oldEntry(x, enq) : undefined;
+    return result;
   };
   const oldExit = stateNode.exit;
   stateNode.exit = (_, enq) => {
@@ -5301,7 +5346,7 @@ class Actor {
     this.system = parent ? parent.system : resolvedOptions._systemRef?.current ?? createRuntimeSystem(this, {
       clock,
       logger,
-      snapshot: resolvedOptions.snapshot ?? resolvedOptions.state,
+      snapshot: resolvedOptions.snapshot,
       createActorRef
     });
     if (!parent && resolvedOptions._systemRef && !resolvedOptions._systemRef.current) {
@@ -5334,7 +5379,7 @@ class Actor {
 
     // prepare to collect initial microsteps during initialTransition
     this._collectedMicrosteps = undefined;
-    const persistedState = options?.snapshot ?? options?.state;
+    const persistedState = options?.snapshot;
     this._restored = persistedState !== undefined;
     try {
       if (persistedState) {
@@ -6086,7 +6131,7 @@ class Actor {
    * {@link Actor.getSnapshot}. Persisted state represents the internal state of
    * the actor, while snapshots represent the actor's last emitted value.
    *
-   * Can be restored with {@link ActorOptions.state}
+   * Can be restored with {@link ActorOptions.snapshot}
    * @see https://stately.ai/docs/persistence
    */
 
@@ -6131,7 +6176,7 @@ class Actor {
 
 /**
  * The options `createActor` (and framework hooks) require for `TLogic`:
- * `{ input }` or a persisted `{ snapshot }` (or deprecated `{ state }`) when
+ * `{ input }` or a persisted `{ snapshot }` when
  * the logic requires input, otherwise nothing.
  *
  * @public
@@ -6183,4 +6228,4 @@ function createActor(logic, ...[options]) {
   return new Actor(logic, options);
 }
 
-export { ACTOR_REF_TYPE as $, attachSnapshotActorRef as A, macrostep as B, isInertActorScope as C, setSnapshotActorRef as D, cloneMachineSnapshot as E, transitionNode as F, getTransitionResult as G, hasEffect as H, createErrorPlatformEvent as I, withActorSelf as J, resolveActionsWithContext as K, takeSpawnAllocationCounters as L, mergeActorIdCounters as M, NULL_EVENT as N, createInitEvent as O, createSpawnEffect as P, initialMicrostep as Q, toStatePath as R, STATE_DELIMITER as S, isStateId as T, getStateNodeByPath as U, getPersistedSnapshot as V, createRemoteActorRef as W, XSTATE_TIMER as X, resolveReferencedActor as Y, createInvokeTimeoutEvent as Z, parseGeneratedActorId as _, allocateChildId as a, createActor as a0, parseDelayToMilliseconds as a1, isAtomicStateNode as a2, ProcessingStatus as a3, isActorRefLike as a4, createListenerLogic as a5, createSubscriptionLogic as a6, listenerLogic as a7, subscriptionLogic as a8, Actor as a9, getAllOwnEvents as aA, matchesEvent as aB, encodeAddressSegment as aC, getRootActorId as aD, RUNTIME_OPERATIONS as aE, withSystemInspector as aF, getSnapshotActorRef as aG, withExecutionIdentity as aH, isMachineSnapshot as aa, InfiniteTransitionError as ab, getAllOwnEventDescriptors as ac, matchesState as ad, checkStateIn as ae, pathToStateValue as af, toObserver as ag, executeEffects as ah, isBuiltInExecutableAction as ai, deliverEvent as aj, runStep as ak, stopActor as al, terminateActor as am, XSTATE_STOP as an, createCustomEffect as ao, XSTATE_LOGIC_EFFECT_START as ap, XSTATE_LOGIC_EFFECT_RESOLVE as aq, XSTATE_LOGIC_EFFECT_REJECT as ar, finalizeTransitionResult as as, createEmitEffect as at, createSendToEffect as au, XSTATE_INIT as av, hasAmbientInspector as aw, getProperAncestors as ax, isRemoteActorRef as ay, getActorIdPrefix as az, assertChildIdFree as b, reserveChildId as c, mapValues as d, createInvokeId as e, getEventDescriptorKey as f, getDelayedTransitions as g, getCandidates as h, evaluateCandidate as i, formatTransition as j, toTransitionConfigArray as k, createInvokeTimeoutEventId as l, matchesEventDescriptor as m, matchesActorSession as n, formatRouteTransitions as o, resolveStateValue as p, getAllStateNodes as q, resolveRegisteredActorSource as r, getStateNodes as s, toArray as t, createMachineSnapshot as u, isInFinalState as v, createInertActorScope as w, setInertActorScopeSnapshot as x, createDeadLetterEffect as y, beginSpawnAllocation as z };
+export { parseGeneratedActorId as $, attachSnapshotActorRef as A, macrostep as B, isInertActorScope as C, setSnapshotActorRef as D, cloneMachineSnapshot as E, transitionNode as F, getTransitionResult as G, hasEffect as H, createErrorPlatformEvent as I, withActorSelf as J, resolveActionsWithContext as K, takeSpawnAllocationCounters as L, mergeActorIdCounters as M, NULL_EVENT as N, createInitEvent as O, createSpawnEffect as P, initialMicrostep as Q, createStartEffect as R, STATE_DELIMITER as S, toStatePath as T, isStateId as U, getStateNodeByPath as V, getPersistedSnapshot as W, XSTATE_TIMER as X, createRemoteActorRef as Y, resolveReferencedActor as Z, createInvokeTimeoutEvent as _, allocateChildId as a, ACTOR_REF_TYPE as a0, createActor as a1, parseDelayToMilliseconds as a2, isAtomicStateNode as a3, ProcessingStatus as a4, isActorRefLike as a5, createListenerLogic as a6, createSubscriptionLogic as a7, listenerLogic as a8, subscriptionLogic as a9, getActorIdPrefix as aA, getAllOwnEvents as aB, matchesEvent as aC, encodeAddressSegment as aD, getRootActorId as aE, RUNTIME_OPERATIONS as aF, withSystemInspector as aG, createTimerEffect as aH, getSnapshotActorRef as aI, withExecutionIdentity as aJ, Actor as aa, isMachineSnapshot as ab, InfiniteTransitionError as ac, getAllOwnEventDescriptors as ad, matchesState as ae, checkStateIn as af, pathToStateValue as ag, toObserver as ah, executeEffects as ai, isBuiltInExecutableAction as aj, deliverEvent as ak, runStep as al, stopActor as am, terminateActor as an, XSTATE_STOP as ao, createCustomEffect as ap, XSTATE_LOGIC_EFFECT_START as aq, XSTATE_LOGIC_EFFECT_RESOLVE as ar, XSTATE_LOGIC_EFFECT_REJECT as as, finalizeTransitionResult as at, createEmitEffect as au, createSendToEffect as av, XSTATE_INIT as aw, hasAmbientInspector as ax, getProperAncestors as ay, isRemoteActorRef as az, assertChildIdFree as b, reserveChildId as c, mapValues as d, createInvokeId as e, getEventDescriptorKey as f, getDelayedTransitions as g, getCandidates as h, evaluateCandidate as i, formatTransition as j, toTransitionConfigArray as k, createInvokeTimeoutEventId as l, matchesEventDescriptor as m, matchesActorSession as n, formatRouteTransitions as o, resolveStateValue as p, getAllStateNodes as q, resolveRegisteredActorSource as r, getStateNodes as s, toArray as t, createMachineSnapshot as u, isInFinalState as v, createInertActorScope as w, setInertActorScopeSnapshot as x, createDeadLetterEffect as y, beginSpawnAllocation as z };

package/dist/{createActor-3347cc32.cjs.js → createActor-eba8226e.cjs.js}

@@ -1121,6 +1121,8 @@ function getBuiltInActionFields(action, args) {
       return undefined;
   }
 }
+
+/** @internal Creates an actor-start effect, including for restored children. */
 function createStartEffect(actor) {
   const args = [actor];
   return {
@@ -1134,6 +1136,41 @@ function createStartEffect(actor) {
     id: actor.id
   };
 }
+
+/** @internal Recreates a pending logical timer without re-entering its state. */
+function createTimerEffect(actorScope, timer, delay) {
+  const source = actorScope.self;
+  const options = {
+    id: timer.id,
+    delay
+  };
+  if (timer.type === '@xstate.raise') {
+    return {
+      kind: 'builtin',
+      type: timer.type,
+      source,
+      event: timer.event,
+      id: timer.id,
+      delay,
+      params: undefined,
+      args: [actorScope, timer.event, options],
+      exec: execRaiseEffect
+    };
+  }
+  const target = timer.target === 'self' ? source : timer.target;
+  return {
+    kind: 'builtin',
+    type: timer.type,
+    source,
+    target,
+    event: timer.event,
+    id: timer.id,
+    delay,
+    params: undefined,
+    args: [actorScope, target, timer.event, options],
+    exec: execSendToEffect
+  };
+}
 function createSpawnEffect(actor) {
   const args = [actor];
   return {
@@ -2089,11 +2126,19 @@ function getCandidates(stateNode, event) {
 function scheduleDelayedEvent(stateNode, timerId, resolveEvent, resolveScheduledDelay) {
   const oldEntry = stateNode.entry;
   stateNode.entry = (x, enq) => {
+    const result = typeof oldEntry === 'function' ? oldEntry(x, enq) : undefined;
+    // The entry context patch is applied by the caller after this wrapper returns.
+    const context = result?.context !== undefined ? mergeContextPatch(x.context, result.context) : x.context;
     enq.raise(resolveEvent(x), {
       id: timerId,
-      delay: resolveScheduledDelay(x)
+      delay: resolveScheduledDelay({
+        context,
+        event: x.event,
+        delays: x.delays,
+        input: x.input
+      })
     });
-    return typeof oldEntry === 'function' ? oldEntry(x, enq) : undefined;
+    return result;
   };
   const oldExit = stateNode.exit;
   stateNode.exit = (_, enq) => {
@@ -5303,7 +5348,7 @@ class Actor {
     this.system = parent ? parent.system : resolvedOptions._systemRef?.current ?? createRuntimeSystem(this, {
       clock,
       logger,
-      snapshot: resolvedOptions.snapshot ?? resolvedOptions.state,
+      snapshot: resolvedOptions.snapshot,
       createActorRef
     });
     if (!parent && resolvedOptions._systemRef && !resolvedOptions._systemRef.current) {
@@ -5336,7 +5381,7 @@ class Actor {
 
     // prepare to collect initial microsteps during initialTransition
     this._collectedMicrosteps = undefined;
-    const persistedState = options?.snapshot ?? options?.state;
+    const persistedState = options?.snapshot;
     this._restored = persistedState !== undefined;
     try {
       if (persistedState) {
@@ -6088,7 +6133,7 @@ class Actor {
    * {@link Actor.getSnapshot}. Persisted state represents the internal state of
    * the actor, while snapshots represent the actor's last emitted value.
    *
-   * Can be restored with {@link ActorOptions.state}
+   * Can be restored with {@link ActorOptions.snapshot}
    * @see https://stately.ai/docs/persistence
    */
 
@@ -6133,7 +6178,7 @@ class Actor {
 
 /**
  * The options `createActor` (and framework hooks) require for `TLogic`:
- * `{ input }` or a persisted `{ snapshot }` (or deprecated `{ state }`) when
+ * `{ input }` or a persisted `{ snapshot }` when
  * the logic requires input, otherwise nothing.
  *
  * @public
@@ -6219,7 +6264,9 @@ exports.createMachineSnapshot = createMachineSnapshot;
 exports.createRemoteActorRef = createRemoteActorRef;
 exports.createSendToEffect = createSendToEffect;
 exports.createSpawnEffect = createSpawnEffect;
+exports.createStartEffect = createStartEffect;
 exports.createSubscriptionLogic = createSubscriptionLogic;
+exports.createTimerEffect = createTimerEffect;
 exports.deliverEvent = deliverEvent;
 exports.encodeAddressSegment = encodeAddressSegment;
 exports.evaluateCandidate = evaluateCandidate;

package/dist/{createActor-81470538.development.cjs.js → createActor-f71670cf.development.cjs.js}

@@ -1131,6 +1131,8 @@ function getBuiltInActionFields(action, args) {
       return undefined;
   }
 }
+
+/** @internal Creates an actor-start effect, including for restored children. */
 function createStartEffect(actor) {
   const args = [actor];
   return {
@@ -1144,6 +1146,41 @@ function createStartEffect(actor) {
     id: actor.id
   };
 }
+
+/** @internal Recreates a pending logical timer without re-entering its state. */
+function createTimerEffect(actorScope, timer, delay) {
+  const source = actorScope.self;
+  const options = {
+    id: timer.id,
+    delay
+  };
+  if (timer.type === '@xstate.raise') {
+    return {
+      kind: 'builtin',
+      type: timer.type,
+      source,
+      event: timer.event,
+      id: timer.id,
+      delay,
+      params: undefined,
+      args: [actorScope, timer.event, options],
+      exec: execRaiseEffect
+    };
+  }
+  const target = timer.target === 'self' ? source : timer.target;
+  return {
+    kind: 'builtin',
+    type: timer.type,
+    source,
+    target,
+    event: timer.event,
+    id: timer.id,
+    delay,
+    params: undefined,
+    args: [actorScope, target, timer.event, options],
+    exec: execSendToEffect
+  };
+}
 function createSpawnEffect(actor) {
   const args = [actor];
   return {
@@ -2099,11 +2136,19 @@ function getCandidates(stateNode, event) {
 function scheduleDelayedEvent(stateNode, timerId, resolveEvent, resolveScheduledDelay) {
   const oldEntry = stateNode.entry;
   stateNode.entry = (x, enq) => {
+    const result = typeof oldEntry === 'function' ? oldEntry(x, enq) : undefined;
+    // The entry context patch is applied by the caller after this wrapper returns.
+    const context = result?.context !== undefined ? mergeContextPatch(x.context, result.context) : x.context;
     enq.raise(resolveEvent(x), {
       id: timerId,
-      delay: resolveScheduledDelay(x)
+      delay: resolveScheduledDelay({
+        context,
+        event: x.event,
+        delays: x.delays,
+        input: x.input
+      })
     });
-    return typeof oldEntry === 'function' ? oldEntry(x, enq) : undefined;
+    return result;
   };
   const oldExit = stateNode.exit;
   stateNode.exit = (_, enq) => {
@@ -5414,6 +5459,9 @@ class Actor {
     this._deferred = void 0;
     this._restored = false;
     this._warnedUnhandledTypes = void 0;
+    if (options && 'state' in options) {
+      throw new Error('The "state" actor option was removed. Pass the persisted snapshot as "snapshot" instead: createActor(logic, { snapshot }).');
+    }
     const resolvedOptions = options ? {
       ...defaultOptions,
       ...options
@@ -5430,7 +5478,7 @@ class Actor {
     this.system = parent ? parent.system : resolvedOptions._systemRef?.current ?? createRuntimeSystem(this, {
       clock,
       logger,
-      snapshot: resolvedOptions.snapshot ?? resolvedOptions.state,
+      snapshot: resolvedOptions.snapshot,
       createActorRef
     });
     if (!parent && resolvedOptions._systemRef && !resolvedOptions._systemRef.current) {
@@ -5463,7 +5511,7 @@ class Actor {
 
     // prepare to collect initial microsteps during initialTransition
     this._collectedMicrosteps = undefined;
-    const persistedState = options?.snapshot ?? options?.state;
+    const persistedState = options?.snapshot;
     this._restored = persistedState !== undefined;
     try {
       if (persistedState) {
@@ -6225,7 +6273,7 @@ class Actor {
    * {@link Actor.getSnapshot}. Persisted state represents the internal state of
    * the actor, while snapshots represent the actor's last emitted value.
    *
-   * Can be restored with {@link ActorOptions.state}
+   * Can be restored with {@link ActorOptions.snapshot}
    * @see https://stately.ai/docs/persistence
    */
 
@@ -6273,7 +6321,7 @@ class Actor {
 
 /**
  * The options `createActor` (and framework hooks) require for `TLogic`:
- * `{ input }` or a persisted `{ snapshot }` (or deprecated `{ state }`) when
+ * `{ input }` or a persisted `{ snapshot }` when
  * the logic requires input, otherwise nothing.
  *
  * @public
@@ -6359,7 +6407,9 @@ exports.createMachineSnapshot = createMachineSnapshot;
 exports.createRemoteActorRef = createRemoteActorRef;
 exports.createSendToEffect = createSendToEffect;
 exports.createSpawnEffect = createSpawnEffect;
+exports.createStartEffect = createStartEffect;
 exports.createSubscriptionLogic = createSubscriptionLogic;
+exports.createTimerEffect = createTimerEffect;
 exports.deliverEvent = deliverEvent;
 exports.encodeAddressSegment = encodeAddressSegment;
 exports.evaluateCandidate = evaluateCandidate;

package/dist/declarations/src/StateMachine.d.ts

@@ -13,12 +13,17 @@ type CompatibleProvidedActorSource<TExpected extends AnyActorLogic, TActual exte
 type ProvidedActors<TExpectedActorMap extends Sources['actors'], TProvidedActorMap extends Partial<Record<keyof TExpectedActorMap & string, AnyActorLogic>>> = {
     [K in keyof TProvidedActorMap]: K extends keyof TExpectedActorMap ? TProvidedActorMap[K] extends AnyActorLogic ? CompatibleProvidedActorSource<TExpectedActorMap[K], TProvidedActorMap[K]> : never : never;
 };
+type ProvidedSourceMap<TDeclared, TProvided> = {
+    [K in keyof TDeclared]: K extends keyof TProvided ? {} extends Pick<TProvided, K> ? TDeclared[K] | Exclude<TProvided[K], undefined> : Exclude<TProvided[K], undefined> : TDeclared[K];
+};
+type ProvidedActionContracts<T> = {
+    [K in keyof T]: T[K] extends (...args: infer TArgs) => any ? (...args: TArgs) => void : never;
+};
 /** @public */
 export declare class StateMachine<TContext extends MachineContext, TEvent extends EventObject, TChildren extends Record<string, AnyActorRef | undefined>, TStateValue extends StateValue, TTag extends string, TInput, TOutput, TEmitted extends EventObject, TMeta extends MetaObject, TConfig extends StateSchema, TActionMap extends Sources['actions'], TActorMap extends Sources['actors'], TGuardMap extends Sources['guards'], TDelayMap extends Sources['delays'], TInternalEvent extends EventObject = never, TTransitionMeta extends MetaObject = TMeta> implements ActorLogic<MachineSnapshot<TContext, TEvent, TChildren, TStateValue, TTag, TOutput, TMeta, TConfig>, TEvent, TInput, AnyActorSystem, TEmitted> {
     /** The raw config used to create the machine. */
     config: Next_MachineConfig<any, any, any, any, any, any, any, any, any, any, any, any, any> & {
         schemas?: AnyMachineSchemas;
-        internalEvents?: readonly string[];
     };
     validator?: ActorLogicValidator | undefined;
     /**
@@ -49,7 +54,9 @@ export declare class StateMachine<TContext extends MachineContext, TEvent extend
     readonly _actorMap: TActorMap;
     readonly _stateSchema: TConfig;
     /** The machine's own version. */
-    version?: string;
+    version: TConfig extends {
+        version: infer TVersion extends string;
+    } ? TVersion : undefined;
     schemas: AnyMachineSchemas | undefined;
     /** Standard Schema for snapshots persisted by this machine version. */
     readonly snapshotSchema: StandardSchemaV1<unknown, Snapshot<unknown> & PersistedMachineSnapshot & {
@@ -61,7 +68,9 @@ export declare class StateMachine<TContext extends MachineContext, TEvent extend
     /** Runtime options for machine execution. */
     options: MachineOptions;
     root: StateNode<TContext, TEvent, TMeta, TTransitionMeta>;
-    id: string;
+    id: TConfig extends {
+        id: infer TId extends string;
+    } ? TId : '(machine)';
     states: StateNode<TContext, TEvent, TMeta, TTransitionMeta>['states'];
     events: Array<EventDescriptor<TEvent>>;
     internalEventDescriptors: ReadonlyArray<string>;
@@ -76,7 +85,6 @@ export declare class StateMachine<TContext extends MachineContext, TEvent extend
     /** The raw config used to create the machine. */
     config: Next_MachineConfig<any, any, any, any, any, any, any, any, any, any, any, any, any> & {
         schemas?: AnyMachineSchemas;
-        internalEvents?: readonly string[];
     }, sources?: Sources, validator?: ActorLogicValidator | undefined);
     /**
      * Clones this state machine with the provided sources.
@@ -85,8 +93,8 @@ export declare class StateMachine<TContext extends MachineContext, TEvent extend
      *   recursively merge with the existing options.
      * @returns A new `StateMachine` instance with the provided sources.
      */
-    provide<const TProvidedActorMap extends Partial<Record<keyof TActorMap & string, AnyActorLogic>> = {}>(sources: {
-        actions?: Partial<TActionMap>;
+    provide<const TProvidedActorMap extends Partial<Record<keyof TActorMap & string, AnyActorLogic>> = {}, const TProvidedActionMap extends Partial<ProvidedActionContracts<TActionMap>> = {}>(sources: {
+        actions?: TProvidedActionMap & Partial<ProvidedActionContracts<TActionMap>> & Record<Exclude<keyof TProvidedActionMap, keyof TActionMap>, never>;
         actors?: TProvidedActorMap & ProvidedActors<TActorMap, TProvidedActorMap>;
         guards?: Partial<TGuardMap> & {
             [K in keyof TGuardMap]?: GuardSourceMap<TContext, TEvent>[string];
@@ -94,7 +102,7 @@ export declare class StateMachine<TContext extends MachineContext, TEvent extend
         delays?: {
             [K in keyof TDelayMap]?: DelaySourceMap<TContext, TEvent>[string];
         };
-    }): this;
+    }): StateMachine<TContext, TEvent, TChildren, TStateValue, TTag, TInput, TOutput, TEmitted, TMeta, TConfig, ProvidedSourceMap<TActionMap, TProvidedActionMap>, ProvidedSourceMap<TActorMap, TProvidedActorMap>, TGuardMap, TDelayMap, TInternalEvent, TTransitionMeta>;
     resolveState(config: {
         value: StateValue;
         context?: TContext;
@@ -132,7 +140,7 @@ export declare class StateMachine<TContext extends MachineContext, TEvent extend
      */
     getInitialSnapshot(actorScope?: ActorScope<MachineSnapshot<TContext, TEvent, TChildren, TStateValue, TTag, TOutput, TMeta, TConfig>, TEvent, AnyActorSystem, TEmitted>, input?: TInput): MachineSnapshot<TContext, TEvent, TChildren, TStateValue, TTag, TOutput, TMeta, TConfig>;
     initialTransition(input: TInput | undefined, actorScope?: ActorScope<MachineSnapshot<TContext, TEvent, TChildren, TStateValue, TTag, TOutput, TMeta, TConfig>, TEvent, AnyActorSystem, TEmitted>): ActorLogicTransitionResult<MachineSnapshot<TContext, TEvent, TChildren, TStateValue, TTag, TOutput, TMeta, TConfig>, ExecutableActionObjectFromLogic<this>>;
-    start(snapshot?: MachineSnapshot<TContext, TEvent, TChildren, TStateValue, TTag, TOutput, TMeta, TConfig>): void;
+    start(snapshot?: MachineSnapshot<TContext, TEvent, TChildren, TStateValue, TTag, TOutput, TMeta, TConfig>, actorScope?: ActorScope<MachineSnapshot<TContext, TEvent, TChildren, TStateValue, TTag, TOutput, TMeta, TConfig>, TEvent, AnyActorSystem, TEmitted>): void;
     getStateNodeById(stateId: string): StateNode<TContext, TEvent, TMeta, TTransitionMeta>;
     getPersistedSnapshot(snapshot: MachineSnapshot<TContext, TEvent, TChildren, TStateValue, TTag, TOutput, TMeta, TConfig>, options?: unknown): Snapshot<unknown>;
     restoreSnapshot(snapshot: Snapshot<unknown>, actorScope?: ActorScope<MachineSnapshot<TContext, TEvent, TChildren, TStateValue, TTag, TOutput, TMeta, TConfig>, TEvent, AnyActorSystem, TEmitted>): MachineSnapshot<TContext, TEvent, TChildren, TStateValue, TTag, TOutput, TMeta, TConfig>;

package/dist/declarations/src/createActor.d.ts

@@ -202,7 +202,7 @@ export declare class Actor<TLogic extends AnyActorLogic> implements ActorInstanc
      * {@link Actor.getSnapshot}. Persisted state represents the internal state of
      * the actor, while snapshots represent the actor's last emitted value.
      *
-     * Can be restored with {@link ActorOptions.state}
+     * Can be restored with {@link ActorOptions.snapshot}
      * @see https://stately.ai/docs/persistence
      */
     getPersistedSnapshot(options?: {
@@ -246,7 +246,7 @@ export declare class Actor<TLogic extends AnyActorLogic> implements ActorInstanc
 export type RequiredActorOptionsKeys<TLogic extends AnyActorLogic> = undefined extends InputFrom<TLogic> ? never : 'input';
 /**
  * The options `createActor` (and framework hooks) require for `TLogic`:
- * `{ input }` or a persisted `{ snapshot }` (or deprecated `{ state }`) when
+ * `{ input }` or a persisted `{ snapshot }` when
  * the logic requires input, otherwise nothing.
  *
  * @public
@@ -257,8 +257,6 @@ export type RequiredActorOptionsFor<TLogic extends AnyActorLogic> = [
     [K in RequiredActorOptionsKeys<TLogic>]: unknown;
 } | {
     snapshot: NonNullable<ActorOptions<TLogic>['snapshot']>;
-} | {
-    state: NonNullable<ActorOptions<TLogic>['state']>;
 };
 /** Options accepted by {@link createActor}. */
 type CreateActorOptionsArgs<TLogic extends AnyActorLogic> = [

package/dist/declarations/src/createMachineFromConfig.d.ts

@@ -123,6 +123,11 @@ export interface MachineJSON extends StateNodeJSON {
         duration: number | string | ResolvableJSON;
     }>;
     schemas?: Record<string, unknown>;
+    /**
+     * Event types that only the machine itself (and its children) may send;
+     * external senders are rejected with reason `internalEvent`.
+     */
+    internalEvents?: string[];
 }
 type EvaluatorSlot = 'context' | 'guard' | 'choice' | 'action' | 'actionParams' | 'transition' | 'input' | 'output' | 'delay' | 'transitionContext' | 'unknown';
 type EvaluatorKind = 'expr' | 'code';

package/dist/declarations/src/durable/index.d.ts

@@ -134,6 +134,17 @@ export interface DurableExecution<TLogic extends AnyActorLogic> {
     readonly machineVersion: string | undefined;
     /** Index assigned to the next transition. Persist this with checkpoints. */
     readonly nextTransitionIndex: number;
+    /**
+     * Restores a checkpoint on a fresh execution. Returns effects that start
+     * active embedded children and re-arm pending root timers; execute them
+     * with `executeEffects` before waiting or processing the next event.
+     * Does not send a machine event, replay entry actions, or advance the
+     * transition index. Restoration effect IDs use `restore:<index>:<effect>`.
+     */
+    restore(persistedSnapshot: Snapshot<unknown>): [
+        snapshot: DurableSnapshot<TLogic>,
+        effects: DurableEffect<ExecutableActionObjectFromLogic<TLogic>>[]
+    ];
     initialTransition(...[input]: undefined extends InputFrom<TLogic> ? [input?: InputFrom<TLogic>] : [input: InputFrom<TLogic>]): [
         snapshot: DurableSnapshot<TLogic>,
         effects: DurableEffect<ExecutableActionObjectFromLogic<TLogic>>[]
@@ -146,7 +157,7 @@ export interface DurableExecution<TLogic extends AnyActorLogic> {
      * Returns the actor reference behind a snapshot produced by this execution,
      * for addressing and inspection. `undefined` for snapshots this execution
      * has not seen (for example a freshly deserialized checkpoint that has not
-     * been passed through `transition()` yet).
+     * been passed through `restore()` or `transition()` yet).
      *
      * With an `address`, returns the live actor at that logical address in the
      * snapshot's actor tree instead — the root itself, one of its transitive