xstate 6.0.0-alpha.69 → 6.0.0-alpha.70

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (140) hide show
  1. package/README.md +99 -75
  2. package/dist/{createActor-b14a387c.development.cjs.js → createActor-11e36865.development.cjs.js} +476 -251
  3. package/dist/{createActor-009673a7.cjs.js → createActor-54296cf2.cjs.js} +474 -249
  4. package/dist/{createActor-c121cbf9.development.esm.js → createActor-9529bbaf.development.esm.js} +473 -250
  5. package/dist/{createActor-a8baa71f.esm.js → createActor-eaa95ae0.esm.js} +471 -248
  6. package/dist/declarations/src/State.d.ts +1 -1
  7. package/dist/declarations/src/StateMachine.d.ts +25 -2
  8. package/dist/declarations/src/StateNode.d.ts +2 -1
  9. package/dist/declarations/src/actors/callback.d.ts +3 -2
  10. package/dist/declarations/src/actors/index.d.ts +1 -1
  11. package/dist/declarations/src/actors/listener.d.ts +2 -2
  12. package/dist/declarations/src/actors/logic.d.ts +3 -2
  13. package/dist/declarations/src/actors/observable.d.ts +3 -2
  14. package/dist/declarations/src/actors/promise.d.ts +3 -2
  15. package/dist/declarations/src/actors/subscription.d.ts +2 -2
  16. package/dist/declarations/src/createActor.d.ts +7 -0
  17. package/dist/declarations/src/createMachine.d.ts +6 -5
  18. package/dist/declarations/src/eventTypes.d.ts +2 -1
  19. package/dist/declarations/src/graph/adjacency.d.ts +4 -3
  20. package/dist/declarations/src/graph/pathFromEvents.d.ts +4 -2
  21. package/dist/declarations/src/graph/shortestPaths.d.ts +4 -3
  22. package/dist/declarations/src/graph/simplePaths.d.ts +4 -3
  23. package/dist/declarations/src/graph/types.d.ts +58 -4
  24. package/dist/declarations/src/index.d.ts +1 -1
  25. package/dist/declarations/src/machineFromJSON.d.ts +13 -3
  26. package/dist/declarations/src/setup.d.ts +24 -38
  27. package/dist/declarations/src/spawn.d.ts +3 -2
  28. package/dist/declarations/src/stateUtils.d.ts +18 -8
  29. package/dist/declarations/src/transitionActions.d.ts +1 -0
  30. package/dist/declarations/src/typeUtils.d.ts +52 -0
  31. package/dist/declarations/src/types.d.ts +48 -83
  32. package/dist/declarations/src/types.v6.d.ts +82 -28
  33. package/dist/declarations/src/utils.d.ts +22 -3
  34. package/dist/{effectDescriptor-75145bce.cjs.js → effectDescriptor-425644eb.cjs.js} +1 -1
  35. package/dist/{effectDescriptor-7326693b.development.esm.js → effectDescriptor-97802bb8.esm.js} +1 -1
  36. package/dist/{effectDescriptor-acfd606c.esm.js → effectDescriptor-df768c71.development.esm.js} +1 -1
  37. package/dist/{effectDescriptor-3e92534c.development.cjs.js → effectDescriptor-fd2aaf45.development.cjs.js} +1 -1
  38. package/dist/{index-d064963f.esm.js → index-967ad7fa.esm.js} +1 -1
  39. package/dist/{index-43ce8782.development.cjs.js → index-9826ee1d.development.cjs.js} +1 -1
  40. package/dist/{index-a2835490.cjs.js → index-986372f2.cjs.js} +1 -1
  41. package/dist/{index-52951124.development.esm.js → index-e30fe161.development.esm.js} +1 -1
  42. package/dist/xstate-actors.cjs.js +2 -2
  43. package/dist/xstate-actors.development.cjs.js +2 -2
  44. package/dist/xstate-actors.development.esm.js +2 -2
  45. package/dist/xstate-actors.esm.js +2 -2
  46. package/dist/xstate-actors.umd.min.js +1 -1
  47. package/dist/xstate-actors.umd.min.js.map +1 -1
  48. package/dist/xstate-durable.cjs.js +2 -2
  49. package/dist/xstate-durable.development.cjs.js +2 -2
  50. package/dist/xstate-durable.development.esm.js +2 -2
  51. package/dist/xstate-durable.esm.js +2 -2
  52. package/dist/xstate-durable.umd.min.js +1 -1
  53. package/dist/xstate-durable.umd.min.js.map +1 -1
  54. package/dist/xstate-graph.cjs.js +58 -22
  55. package/dist/xstate-graph.development.cjs.js +58 -22
  56. package/dist/xstate-graph.development.esm.js +59 -23
  57. package/dist/xstate-graph.esm.js +59 -23
  58. package/dist/xstate-graph.umd.min.js +1 -1
  59. package/dist/xstate-graph.umd.min.js.map +1 -1
  60. package/dist/xstate-validation.cjs.js +1 -1
  61. package/dist/xstate-validation.development.cjs.js +1 -1
  62. package/dist/xstate-validation.development.esm.js +1 -1
  63. package/dist/xstate-validation.esm.js +1 -1
  64. package/dist/xstate-validation.umd.min.js.map +1 -1
  65. package/dist/xstate.cjs.js +148 -56
  66. package/dist/xstate.cjs.mjs +1 -0
  67. package/dist/xstate.development.cjs.js +162 -62
  68. package/dist/xstate.development.cjs.mjs +1 -0
  69. package/dist/xstate.development.esm.js +164 -65
  70. package/dist/xstate.esm.js +150 -59
  71. package/dist/xstate.umd.min.js +1 -1
  72. package/dist/xstate.umd.min.js.map +1 -1
  73. package/docs/actions.md +75 -0
  74. package/docs/actor-logic.md +250 -0
  75. package/docs/actors.md +64 -0
  76. package/docs/async-logic.md +75 -0
  77. package/docs/async-requests.md +157 -0
  78. package/docs/backend-workflows.md +121 -0
  79. package/docs/cancellation.md +42 -0
  80. package/docs/cheatsheet.md +561 -0
  81. package/docs/choice-states.md +109 -0
  82. package/docs/choose-xstate.md +47 -0
  83. package/docs/configuration.md +161 -0
  84. package/docs/context.md +63 -0
  85. package/docs/create-actor.md +156 -0
  86. package/docs/data-and-effects.md +48 -0
  87. package/docs/delays.md +81 -0
  88. package/docs/durable-execution.md +510 -0
  89. package/docs/emitted-events.md +127 -0
  90. package/docs/examples.md +75 -0
  91. package/docs/faq.md +60 -0
  92. package/docs/final-states.md +149 -0
  93. package/docs/forms-and-wizards.md +166 -0
  94. package/docs/frameworks.md +69 -0
  95. package/docs/fsm.md +164 -0
  96. package/docs/glossary.md +68 -0
  97. package/docs/guards.md +137 -0
  98. package/docs/history-states.md +159 -0
  99. package/docs/how-xstate-runs-machines.md +84 -0
  100. package/docs/index.md +71 -0
  101. package/docs/input-output.md +69 -0
  102. package/docs/inspect-actor-systems.md +116 -0
  103. package/docs/inspection.md +73 -0
  104. package/docs/internal-events.md +156 -0
  105. package/docs/invoke.md +354 -0
  106. package/docs/lifecycle-and-errors.md +48 -0
  107. package/docs/listen-and-subscribe.md +126 -0
  108. package/docs/model-based-testing.md +319 -0
  109. package/docs/modeling.md +40 -0
  110. package/docs/parallel-states.md +182 -0
  111. package/docs/persist-and-restore-actors.md +115 -0
  112. package/docs/persistence.md +325 -0
  113. package/docs/quick-start.md +55 -0
  114. package/docs/retries-and-timeouts.md +122 -0
  115. package/docs/route-states.md +104 -0
  116. package/docs/scxml.md +59 -0
  117. package/docs/selectors.md +99 -0
  118. package/docs/serialization.md +124 -0
  119. package/docs/setup-and-provide.md +271 -0
  120. package/docs/snapshots.md +134 -0
  121. package/docs/spawn.md +220 -0
  122. package/docs/state-input.md +162 -0
  123. package/docs/statecharts.md +54 -0
  124. package/docs/states-events-transitions.md +82 -0
  125. package/docs/states.md +168 -0
  126. package/docs/system-transitions.md +170 -0
  127. package/docs/systems.md +134 -0
  128. package/docs/testing.md +150 -0
  129. package/docs/timeouts.md +125 -0
  130. package/docs/transition-functions.md +87 -0
  131. package/docs/transitions.md +185 -0
  132. package/docs/troubleshooting.md +48 -0
  133. package/docs/tutorial.md +481 -0
  134. package/docs/typescript.md +211 -0
  135. package/docs/typestates.md +110 -0
  136. package/docs/utilities.md +39 -0
  137. package/docs/why-state-machines.md +59 -0
  138. package/docs/xstate-v5-to-v6.md +1756 -0
  139. package/docs/your-first-machine.md +79 -0
  140. package/package.json +2 -1
@@ -177,6 +177,38 @@ function reportUnhandledError(err) {
177
177
 
178
178
  const symbolObservable = (() => typeof Symbol === 'function' && Symbol.observable || '@@observable')();
179
179
 
180
+ const selectionFrames = [];
181
+ const transitionEffectSignal = new Error('Transition effect');
182
+ function protectSelectionRelay(target) {
183
+ let matched = false;
184
+ let abort = false;
185
+ for (const frame of selectionFrames) {
186
+ if (frame.parent === target) {
187
+ frame.requiresReevaluation = true;
188
+ matched = true;
189
+ abort ||= frame.mode === 'abort';
190
+ }
191
+ }
192
+ if (abort) {
193
+ throw transitionEffectSignal;
194
+ }
195
+ return matched;
196
+ }
197
+ function beginTransitionSelection(parent, mode = 'abort') {
198
+ const frame = {
199
+ mode,
200
+ parent,
201
+ requiresReevaluation: false
202
+ };
203
+ selectionFrames.push(frame);
204
+ return {
205
+ frame,
206
+ close() {
207
+ selectionFrames.pop();
208
+ }
209
+ };
210
+ }
211
+
180
212
  /**
181
213
  * @internal The identity fields of a built-in timer event (`after`, state and
182
214
  * invoke `timeout`), or `undefined` for any other event.
@@ -567,6 +599,198 @@ function createSubscriptionLogic() {
567
599
  /** @internal The logic of helper actors created by `enq.subscribeTo()`. */
568
600
  const subscriptionLogic = /* #__PURE__ */createSubscriptionLogic();
569
601
 
602
+ const emptySubscription = {
603
+ unsubscribe() {}
604
+ };
605
+ const restoreHint = 'or restore this snapshot with embedded children on the runtime that owns them.';
606
+
607
+ /** @internal */
608
+ function isRemoteActorRef(actorRef) {
609
+ return actorRef._remote === true;
610
+ }
611
+
612
+ /**
613
+ * @internal Whether a send target is an actor reference that went through
614
+ * JSON (`actor.toJSON()`): plain data carrying an address, not an actor.
615
+ */
616
+ function isSerializedActorRef(target) {
617
+ if (typeof target !== 'object' || target === null || Array.isArray(target) || typeof target.$actor !== 'string') {
618
+ return false;
619
+ }
620
+ for (const key in target) {
621
+ if (key !== '$actor' && key !== 'incarnation') {
622
+ return false;
623
+ }
624
+ }
625
+ const incarnation = target.incarnation;
626
+ return incarnation === undefined || typeof incarnation === 'string';
627
+ }
628
+
629
+ /** @internal The actor id that the last segment of an address encodes. */
630
+ function getAddressId(address) {
631
+ const segment = address.slice(address.lastIndexOf('/') + 1);
632
+ return segment.includes('%') ? segment.replaceAll('%2F', '/').replaceAll('%25', '%') : segment;
633
+ }
634
+
635
+ /** @internal The error reported when no live actor has a serialized address. */
636
+ function createMissingAddressError(target) {
637
+ 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`);
638
+ }
639
+
640
+ /**
641
+ * @internal The live actor a serialized ref names: the actor at its address,
642
+ * and, when the ref carries an `incarnation`, only that incarnation. A ref
643
+ * without one follows whichever actor is live at the address.
644
+ */
645
+ function resolveSerializedActorRef(system, target) {
646
+ const live = system._getByAddress?.(target.$actor);
647
+ return live && (target.incarnation === undefined || live.sessionId === target.incarnation) ? live : undefined;
648
+ }
649
+
650
+ /**
651
+ * The lifecycle-only snapshot a remote handle exposes. `active` is accurate
652
+ * by construction: a completion removes the child from its parent's
653
+ * `children`, so a handle only exists while the child is presumed active,
654
+ * and the terminal result arrives as a completion event instead of a
655
+ * snapshot. Full snapshots are a co-location capability.
656
+ */
657
+ const remoteSnapshot = Object.freeze({
658
+ status: 'active',
659
+ output: undefined,
660
+ error: undefined
661
+ });
662
+
663
+ /**
664
+ * Creates the inert ref `enq.spawn(...)` returns while a transition is only
665
+ * evaluated (for example by `snapshot.can(...)`, or to resolve conflicting
666
+ * transitions) and no actor is created. It carries the identity the spawn
667
+ * would get, accepts and drops events, exposes the same lifecycle-only
668
+ * snapshot as a remote handle, and serializes like any actor ref. Its address
669
+ * is unknown when the evaluating scope is detached from the parent actor.
670
+ *
671
+ * @internal
672
+ */
673
+ function createInertActorRef(options) {
674
+ const {
675
+ id,
676
+ address
677
+ } = options;
678
+ const handle = {
679
+ ref: undefined,
680
+ id,
681
+ address,
682
+ src: options.src,
683
+ sessionId: undefined,
684
+ send() {},
685
+ getSnapshot() {
686
+ return remoteSnapshot;
687
+ },
688
+ subscribe() {
689
+ return emptySubscription;
690
+ },
691
+ on() {
692
+ return emptySubscription;
693
+ },
694
+ toJSON() {
695
+ if (address === undefined) {
696
+ 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.`);
697
+ }
698
+ return {
699
+ $actor: address
700
+ };
701
+ }
702
+ };
703
+ const ref = handle;
704
+ handle.ref = ref;
705
+ return ref;
706
+ }
707
+
708
+ /**
709
+ * Creates a location-transparent handle to an actor whose state lives with
710
+ * another runtime. The handle is constructed from identity alone — no lookup
711
+ * — and every send routes through the system's runtime; its state is not
712
+ * synchronously readable.
713
+ *
714
+ * The surface is deliberately minimal: it covers every member the runtime
715
+ * reaches for a restored child (send/_send, lifecycle via start/_stop and
716
+ * system.stopActor, persistence, subscribe/on as inert subscriptions).
717
+ * Members that only make sense for a co-located actor (public stop(),
718
+ * select(), trigger) throw a descriptive error rather than being absent, so
719
+ * calling one reports what went wrong instead of a bare TypeError. Observable
720
+ * interop and _processingStatus are omitted entirely.
721
+ *
722
+ * @internal
723
+ */
724
+ function createRemoteActorRef(system, options) {
725
+ const handle = {
726
+ _remote: true,
727
+ // Self-reference so context persistence recognizes the handle as an
728
+ // actor reference instead of recursing into it.
729
+ ref: undefined,
730
+ id: options.id,
731
+ address: options.address,
732
+ src: options.src,
733
+ registryKey: options.registryKey,
734
+ // The host-supplied incarnation token, when present: the owner's
735
+ // sessionId for this child, letting this side drop stale completions and
736
+ // journaled sends name the intended incarnation. Without one the handle
737
+ // does not know the child's incarnation and the owning runtime is the
738
+ // authority on staleness.
739
+ sessionId: options.incarnation,
740
+ system,
741
+ _parent: options.parent,
742
+ // Round-trips through persistence verbatim (undefined stays undefined,
743
+ // so re-persisting is byte-stable); a remote handle cannot act on it
744
+ // locally.
745
+ _syncSnapshot: options.syncSnapshot,
746
+ send(event) {
747
+ void system.sendEvent(undefined, ref, event);
748
+ },
749
+ _send(event) {
750
+ throw new Error(`Remote actor '${options.address}' has no local mailbox to receive "${event.type}". Its state lives with another runtime; install a runtime that can reach it (via \`createDurable\`'s adapter runtime operations, or \`system.runtime\`) before sending, ${restoreHint}`);
751
+ },
752
+ getSnapshot() {
753
+ return remoteSnapshot;
754
+ },
755
+ getPersistedSnapshot() {
756
+ throw new Error(`Cannot persist remote actor '${options.address}' from here: its state lives with the runtime that owns it. Persist it there, ${restoreHint}`);
757
+ },
758
+ start() {},
759
+ _stop() {},
760
+ stop() {
761
+ throw new Error(`Cannot stop remote actor '${options.address}' directly: stopping is a co-located operation. Stop it through the system runtime that owns it (\`system.stopActor(ref)\`), ${restoreHint}`);
762
+ },
763
+ select() {
764
+ throw new Error(`Cannot select from remote actor '${options.address}': its snapshot is not synchronously readable because its state lives with another runtime. Read it on the runtime that owns it, ${restoreHint}`);
765
+ },
766
+ get trigger() {
767
+ throw new Error(`Remote actor '${options.address}' has no \`trigger\` shorthand: it requires a co-located actor. Use \`send(...)\`, which routes through the system runtime.`);
768
+ },
769
+ // Observation is a co-location capability: a remote handle never emits,
770
+ // so subscriptions are inert rather than errors — generic observers may
771
+ // attach to any ref.
772
+ subscribe() {
773
+ return emptySubscription;
774
+ },
775
+ on() {
776
+ return emptySubscription;
777
+ },
778
+ _isRunning() {
779
+ return false;
780
+ },
781
+ // The same shape Actor.toJSON produces, so serialized snapshots carry
782
+ // one actor-reference shape whether a child is co-located or remote.
783
+ toJSON() {
784
+ return {
785
+ $actor: options.address
786
+ };
787
+ }
788
+ };
789
+ const ref = handle;
790
+ handle.ref = ref;
791
+ return ref;
792
+ }
793
+
570
794
  function execCustomEffect() {
571
795
  const result = this.action?.(...this.args);
572
796
  {
@@ -908,6 +1132,20 @@ function nextChildIndex(actorScope, allocation, prefix) {
908
1132
  return Math.max(allocation.counters.get(prefix) ?? 0, getWorkingSnapshotOf(actorScope)?._nextActorIds?.[prefix] ?? 0);
909
1133
  }
910
1134
 
1135
+ /**
1136
+ * The next generated index for a prefix that is not claimed in this
1137
+ * transition or held by a live child, such as an implicit invoke id
1138
+ * (`worker:0` for an invoke in state `worker`). Does not allocate.
1139
+ */
1140
+ function nextFreeChildIndex(actorScope, allocation, prefix) {
1141
+ let next = nextChildIndex(actorScope, allocation, prefix);
1142
+ const children = getWorkingSnapshotOf(actorScope)?.children;
1143
+ while (allocation.explicitIds.has(`${prefix}:${next}`) || children?.[`${prefix}:${next}`]) {
1144
+ next++;
1145
+ }
1146
+ return next;
1147
+ }
1148
+
911
1149
  /**
912
1150
  * Allocates the next generated child id for the transition's allocation
913
1151
  * transaction, seeded from the parent snapshot's own persisted counters. This
@@ -923,7 +1161,7 @@ function allocateChildId(actorScope, src, localAllocation) {
923
1161
  const allocation = spawnAllocations.get(actorScope) ?? localAllocation ?? createSpawnAllocation();
924
1162
  const prefix = getActorIdPrefix(src);
925
1163
  assertUnreservedPrefix(prefix);
926
- const next = nextChildIndex(actorScope, allocation, prefix);
1164
+ const next = nextFreeChildIndex(actorScope, allocation, prefix);
927
1165
  allocation.counters.set(prefix, next + 1);
928
1166
  return {
929
1167
  id: `${prefix}:${next}`,
@@ -1008,6 +1246,19 @@ function takeSpawnAllocationCounters(actorScope) {
1008
1246
  }
1009
1247
  return Object.fromEntries(counters);
1010
1248
  }
1249
+
1250
+ /**
1251
+ * Scopes whose `self` is not the evaluated snapshot's actor (the shared
1252
+ * `snapshot.can(...)` scope), so spawned inert refs have no address.
1253
+ *
1254
+ * @internal
1255
+ */
1256
+ const detachedScopes = new WeakSet();
1257
+ function assertRaiseEvent(event) {
1258
+ if (typeof event === 'string') {
1259
+ throw new Error(`Only event objects may be used with raise; use raise({ type: "${event}" }) instead` );
1260
+ }
1261
+ }
1011
1262
  function createTransitionEnqueue(actorScope, actions, internalEvents, actorSubscriptions = false, createActors = true) {
1012
1263
  // Paths that never begin a transaction keep a per-enqueue scope.
1013
1264
  const localAllocation = spawnAllocations.get(actorScope) ?? createSpawnAllocation();
@@ -1024,9 +1275,7 @@ function createTransitionEnqueue(actorScope, actions, internalEvents, actorSubsc
1024
1275
  pushBuiltInAction(actions, actorScope.logger, ...args);
1025
1276
  },
1026
1277
  raise: (raisedEvent, options) => {
1027
- if (typeof raisedEvent === 'string') {
1028
- throw new Error(`Only event objects may be used with raise; use raise({ type: "${raisedEvent}" }) instead` );
1029
- }
1278
+ assertRaiseEvent(raisedEvent);
1030
1279
  if (options?.delay !== undefined) {
1031
1280
  pushBuiltInAction(actions, builtInActions['@xstate.raise'], actorScope, raisedEvent, options);
1032
1281
  } else {
@@ -1039,10 +1288,15 @@ function createTransitionEnqueue(actorScope, actions, internalEvents, actorSubsc
1039
1288
  src
1040
1289
  } = resolveTransitionSpawnSource(actorScope, source);
1041
1290
  if (!createActors) {
1042
- // TODO: replace this speculative placeholder with a typed inert actor ref.
1043
- return {
1044
- id: options?.id ?? options?.registryKey ?? src ?? logic.id
1045
- };
1291
+ // Speculative evaluation creates no actor and allocates no id: return
1292
+ // an inert ref with the id this spawn would get.
1293
+ const prefix = getActorIdPrefix(src ?? logic);
1294
+ const id = options?.id ?? `${prefix}:${nextFreeChildIndex(actorScope, spawnAllocations.get(actorScope) ?? localAllocation, prefix)}`;
1295
+ return createInertActorRef({
1296
+ id,
1297
+ address: detachedScopes.has(actorScope) ? undefined : `${actorScope.self.address}/${encodeAddressSegment(id)}`,
1298
+ src
1299
+ });
1046
1300
  }
1047
1301
  // Generated ids allocate from the parent snapshot's own counters
1048
1302
  // through the transition's allocation transaction; explicit
@@ -2297,7 +2551,8 @@ function getDelayedTransitions(stateNode) {
2297
2551
  event: createAfterEvent(delay, stateNode.id),
2298
2552
  delay,
2299
2553
  transitions: afterConfig[key],
2300
- fromDelaysMap: true
2554
+ fromDelaysMap: true,
2555
+ name: `after.${key}`
2301
2556
  });
2302
2557
  }
2303
2558
  }
@@ -2306,7 +2561,8 @@ function getDelayedTransitions(stateNode) {
2306
2561
  event: createTimeoutEvent(stateNode.id),
2307
2562
  delay: timeoutConfig,
2308
2563
  transitions: onTimeoutConfig,
2309
- fromDelaysMap: true
2564
+ fromDelaysMap: true,
2565
+ name: 'onTimeout'
2310
2566
  });
2311
2567
  }
2312
2568
  for (const invokeDef of invokeDefs) {
@@ -2318,7 +2574,8 @@ function getDelayedTransitions(stateNode) {
2318
2574
  eventMatcher: (event, snapshot) => matchesActorSession(event, snapshot, invokeDef.id),
2319
2575
  delay: invokeDef.timeout,
2320
2576
  transitions: invokeDef.onTimeout,
2321
- fromDelaysMap: false
2577
+ fromDelaysMap: false,
2578
+ name: 'invoke.onTimeout'
2322
2579
  });
2323
2580
  }
2324
2581
 
@@ -2332,7 +2589,8 @@ function getDelayedTransitions(stateNode) {
2332
2589
  eventMatcher,
2333
2590
  delay,
2334
2591
  transitions,
2335
- fromDelaysMap
2592
+ fromDelaysMap,
2593
+ name
2336
2594
  } of sources) {
2337
2595
  scheduleDelayedEvent(stateNode, event, resolveEvent ?? (() => event), x => resolveDelay(delay, fromDelaysMap ? x.delays : {}, {
2338
2596
  context: x.context,
@@ -2344,7 +2602,7 @@ function getDelayedTransitions(stateNode) {
2344
2602
  type: eventType,
2345
2603
  ...eventPattern
2346
2604
  } = event;
2347
- for (const transition of toTransitionConfigArray(transitions)) {
2605
+ for (const transition of toTransitionConfigArray(transitions, name, stateNode.id)) {
2348
2606
  delayedTransitions.push({
2349
2607
  ...transition,
2350
2608
  matches: {
@@ -2595,9 +2853,6 @@ function getInitialStateNodes(stateNode) {
2595
2853
 
2596
2854
  /** Returns the child state node from its relative `stateKey`, or throws. */
2597
2855
  function getStateNode(stateNode, stateKey) {
2598
- if (isStateId(stateKey)) {
2599
- return stateNode.machine.getStateNodeById(stateKey);
2600
- }
2601
2856
  const result = stateNode.states?.[stateKey];
2602
2857
  if (!result) {
2603
2858
  throw new Error(!stateNode.states ? `Unable to retrieve child state '${stateKey}' from '${stateNode.id}'; no child states exist.` : `Child state '${stateKey}' does not exist on '${stateNode.id}'`);
@@ -2611,13 +2866,9 @@ function getStateNode(stateNode, stateKey) {
2611
2866
  * @param statePath The string or string array relative path to the state node.
2612
2867
  */
2613
2868
  function getStateNodeByPath(stateNode, statePath) {
2869
+ // `#id` is an exact id lookup, never an id followed by a path.
2614
2870
  if (typeof statePath === 'string' && isStateId(statePath)) {
2615
- try {
2616
- return stateNode.machine.getStateNodeById(statePath);
2617
- } catch {
2618
- // try individual paths
2619
- // throw e;
2620
- }
2871
+ return stateNode.machine.getStateNodeById(statePath);
2621
2872
  }
2622
2873
  const arrayStatePath = toStatePath(statePath).slice();
2623
2874
  let currentStateNode = stateNode;
@@ -3264,9 +3515,9 @@ function microstep(transitions, currentSnapshot, actorScope, event, isInitial, i
3264
3515
  self: actorScope.self
3265
3516
  });
3266
3517
  }
3267
- const logic = typeof src === 'string' ? resolveReferencedActor(currentSnapshot.machine, src) : src;
3518
+ const logic = typeof src === 'string' ? currentSnapshot.machine.sources.actors[src] : src;
3268
3519
  if (!logic) {
3269
- throw new Error(`Actor logic '${typeof src === 'string' ? src : 'inline'}' not implemented in machine '${currentSnapshot.machine.id}'` );
3520
+ throw new Error(`Actor logic '${typeof src === 'string' ? src : 'inline'}' not implemented in ${describeMachine(currentSnapshot.machine.id)}` );
3270
3521
  }
3271
3522
  const input = typeof invokeDef.input === 'function' ? invokeDef.input({
3272
3523
  self: actorScope.self,
@@ -3278,10 +3529,15 @@ function microstep(transitions, currentSnapshot, actorScope, event, isInitial, i
3278
3529
  assertChildIdFree(actorScope, invokeDef.id);
3279
3530
  const actor = actorScope.system.createActorRef(logic, {
3280
3531
  ...invokeDef,
3532
+ // A `src` function may return a registered key, which persists.
3533
+ src: typeof src === 'string' ? src : undefined,
3281
3534
  input,
3282
3535
  parent: actorScope.self,
3283
3536
  syncSnapshot: !!invokeDef.onSnapshot
3284
3537
  });
3538
+ // Persistence restores a source-less child through its invoke
3539
+ // definition only when the invoke created it.
3540
+ actor._invoked = true;
3285
3541
  actions.push({
3286
3542
  action: builtInActions['@xstate.spawn'],
3287
3543
  args: [actor]
@@ -3499,13 +3755,25 @@ function getTransitionResult(transition, snapshot, event, actorScope, options) {
3499
3755
  const actions = [];
3500
3756
  const internalEvents = [];
3501
3757
  let res;
3502
- if (options?.selectionResult?.reusable) {
3758
+ if (options?.selectionResult?.reusable && (options.resolveActions === false || options.selectionResult.operations.length === 0)) {
3503
3759
  res = options.selectionResult.result;
3504
3760
  } else {
3505
3761
  const enqueue = createTransitionEnqueue(actorScope, actions, internalEvents, true, options?.resolveActions ?? true);
3506
- res = transition.to(getTransitionArgs(), enqueue);
3507
- closeTransitionEnqueue(enqueue);
3508
- assertSyncTransitionResult(res, event, transition.source.id);
3762
+ const speculativeSelection = options?.resolveActions === false ? beginTransitionSelection(getActorScopeParent(actorScope), 'suppress') : undefined;
3763
+ try {
3764
+ if (options?.selectionResult?.reusable) {
3765
+ res = options.selectionResult.result;
3766
+ for (const operation of options.selectionResult.operations) {
3767
+ operation(enqueue);
3768
+ }
3769
+ } else {
3770
+ res = transition.to(getTransitionArgs(), enqueue);
3771
+ assertSyncTransitionResult(res, event, transition.source.id);
3772
+ }
3773
+ } finally {
3774
+ speculativeSelection?.close();
3775
+ closeTransitionEnqueue(enqueue);
3776
+ }
3509
3777
  }
3510
3778
  const targets = res?.target ? resolveTarget(transition.source, toArray(res.target)) : undefined;
3511
3779
  const resolvedInput = res?.input ?? (typeof transition.input === 'function' ? transition.input({
@@ -3780,16 +4048,6 @@ function hasEffect(transition, context, event, snapshot, actorScope) {
3780
4048
  return false;
3781
4049
  }
3782
4050
 
3783
- // Depth of in-flight selection-phase transition function calls; the shared
3784
- // selection enqueue is only valid while one runs.
3785
- let selectionDepth = 0;
3786
- const triggerTransitionEffect = () => {
3787
- if (!selectionDepth) {
3788
- return lateEnqueueCall();
3789
- }
3790
- throw transitionEffectSignal;
3791
- };
3792
-
3793
4051
  /**
3794
4052
  * Throws when a transition, entry, or exit function returned a promise. The promise's
3795
4053
  * rejection is observed so it is never reported as unhandled.
@@ -3800,27 +4058,56 @@ function assertSyncTransitionResult(res, event, sourceId, kind) {
3800
4058
  throw new Error(kind ? `${kind === 'entry' ? 'Entry' : 'Exit'} functions must be synchronous. The ${kind} function of state "${sourceId}" returned a promise (event "${event.type}"). Move async work into an invoked or spawned actor, or enq.effect.` : `Transition functions must be synchronous. Transition for event "${event.type}" in state "${sourceId}" returned a promise. Move async work into an invoked or spawned actor, or enq.effect.`);
3801
4059
  }
3802
4060
  }
3803
- let transitionEffectEnqueue;
3804
- function getTransitionEffectEnqueue() {
3805
- return transitionEffectEnqueue ??= createEnqueueObject({
3806
- emit: triggerTransitionEffect,
3807
- cancel: triggerTransitionEffect,
3808
- log: triggerTransitionEffect,
3809
- raise: triggerTransitionEffect,
3810
- spawn: triggerTransitionEffect,
3811
- sendTo: triggerTransitionEffect,
3812
- stop: triggerTransitionEffect,
3813
- listen: triggerTransitionEffect,
3814
- subscribeTo: triggerTransitionEffect
3815
- }, triggerTransitionEffect);
4061
+ function createTransitionSelection(parent) {
4062
+ const selection = beginTransitionSelection(parent);
4063
+ const {
4064
+ frame
4065
+ } = selection;
4066
+ const operations = [];
4067
+ let closed = false;
4068
+ const record = operation => {
4069
+ if (closed) {
4070
+ return lateEnqueueCall();
4071
+ }
4072
+ operations.push(operation);
4073
+ };
4074
+ const abortRefProducingCall = () => {
4075
+ if (closed) {
4076
+ return lateEnqueueCall();
4077
+ }
4078
+ frame.requiresReevaluation = true;
4079
+ throw transitionEffectSignal;
4080
+ };
4081
+ const enqueue = createEnqueueObject({
4082
+ cancel: (...args) => record(enq => enq.cancel(...args)),
4083
+ emit: (...args) => record(enq => enq.emit(...args)),
4084
+ log: (...args) => record(enq => enq.log(...args)),
4085
+ raise: (event, options) => {
4086
+ if (closed) {
4087
+ return lateEnqueueCall();
4088
+ }
4089
+ assertRaiseEvent(event);
4090
+ record(enq => enq.raise(event, options));
4091
+ },
4092
+ sendTo: (...args) => record(enq => enq.sendTo(...args)),
4093
+ stop: (...args) => record(enq => enq.stop(...args)),
4094
+ spawn: abortRefProducingCall,
4095
+ listen: abortRefProducingCall,
4096
+ subscribeTo: abortRefProducingCall
4097
+ }, (...args) => record(enq => enq(...args)));
4098
+ return {
4099
+ frame,
4100
+ enqueue,
4101
+ operations,
4102
+ close() {
4103
+ closed = true;
4104
+ selection.close();
4105
+ }
4106
+ };
3816
4107
  }
3817
4108
  function evaluateTransitionFunction(transitionTo, context, event, snapshot, actorScope, sources, sourceId) {
3818
4109
  let res;
3819
- const parent = getActorScopeParent(actorScope);
3820
- if (parent) {
3821
- transitionEffectTargets.push(parent);
3822
- }
3823
- selectionDepth++;
4110
+ const selection = createTransitionSelection(getActorScopeParent(actorScope));
3824
4111
  try {
3825
4112
  res = transitionTo(withActorScope({
3826
4113
  context,
@@ -3833,7 +4120,7 @@ function evaluateTransitionFunction(transitionTo, context, event, snapshot, acto
3833
4120
  guards: sources.guards,
3834
4121
  delays: sources.delays,
3835
4122
  input: getStateInput(snapshot, sourceId)
3836
- }, actorScope), getTransitionEffectEnqueue());
4123
+ }, actorScope), selection.enqueue);
3837
4124
  } catch (err) {
3838
4125
  if (err === transitionEffectSignal) {
3839
4126
  return {
@@ -3844,16 +4131,21 @@ function evaluateTransitionFunction(transitionTo, context, event, snapshot, acto
3844
4131
  }
3845
4132
  throw err;
3846
4133
  } finally {
3847
- selectionDepth--;
3848
- if (parent) {
3849
- transitionEffectTargets.pop();
3850
- }
4134
+ selection.close();
3851
4135
  }
3852
4136
  assertSyncTransitionResult(res, event, sourceId);
4137
+ if (selection.frame.requiresReevaluation) {
4138
+ return {
4139
+ enabled: true,
4140
+ result: undefined,
4141
+ reusable: false
4142
+ };
4143
+ }
3853
4144
  return {
3854
- enabled: res !== undefined,
4145
+ enabled: res !== undefined || selection.operations.length > 0,
3855
4146
  result: res,
3856
- reusable: true
4147
+ reusable: true,
4148
+ operations: selection.operations
3857
4149
  };
3858
4150
  }
3859
4151
  function stopChildren(snapshot, event, actorScope) {
@@ -3929,153 +4221,6 @@ function evaluateCandidate(candidate, event, snapshot, stateNode, actorScope, se
3929
4221
  return true;
3930
4222
  }
3931
4223
 
3932
- const emptySubscription = {
3933
- unsubscribe() {}
3934
- };
3935
- const restoreHint = 'or restore this snapshot with embedded children on the runtime that owns them.';
3936
-
3937
- /** @internal */
3938
- function isRemoteActorRef(actorRef) {
3939
- return actorRef._remote === true;
3940
- }
3941
-
3942
- /**
3943
- * @internal Whether a send target is an actor reference that went through
3944
- * JSON (`actor.toJSON()`): plain data carrying an address, not an actor.
3945
- */
3946
- function isSerializedActorRef(target) {
3947
- if (typeof target !== 'object' || target === null || Array.isArray(target) || typeof target.$actor !== 'string') {
3948
- return false;
3949
- }
3950
- for (const key in target) {
3951
- if (key !== '$actor' && key !== 'incarnation') {
3952
- return false;
3953
- }
3954
- }
3955
- const incarnation = target.incarnation;
3956
- return incarnation === undefined || typeof incarnation === 'string';
3957
- }
3958
-
3959
- /** @internal The actor id that the last segment of an address encodes. */
3960
- function getAddressId(address) {
3961
- const segment = address.slice(address.lastIndexOf('/') + 1);
3962
- return segment.includes('%') ? segment.replaceAll('%2F', '/').replaceAll('%25', '%') : segment;
3963
- }
3964
-
3965
- /** @internal The error reported when no live actor has a serialized address. */
3966
- function createMissingAddressError(target) {
3967
- 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`);
3968
- }
3969
-
3970
- /**
3971
- * @internal The live actor a serialized ref names: the actor at its address,
3972
- * and, when the ref carries an `incarnation`, only that incarnation. A ref
3973
- * without one follows whichever actor is live at the address.
3974
- */
3975
- function resolveSerializedActorRef(system, target) {
3976
- const live = system._getByAddress?.(target.$actor);
3977
- return live && (target.incarnation === undefined || live.sessionId === target.incarnation) ? live : undefined;
3978
- }
3979
-
3980
- /**
3981
- * The lifecycle-only snapshot a remote handle exposes. `active` is accurate
3982
- * by construction: a completion removes the child from its parent's
3983
- * `children`, so a handle only exists while the child is presumed active,
3984
- * and the terminal result arrives as a completion event instead of a
3985
- * snapshot. Full snapshots are a co-location capability.
3986
- */
3987
- const remoteSnapshot = Object.freeze({
3988
- status: 'active',
3989
- output: undefined,
3990
- error: undefined
3991
- });
3992
-
3993
- /**
3994
- * Creates a location-transparent handle to an actor whose state lives with
3995
- * another runtime. The handle is constructed from identity alone — no lookup
3996
- * — and every send routes through the system's runtime; its state is not
3997
- * synchronously readable.
3998
- *
3999
- * The surface is deliberately minimal: it covers every member the runtime
4000
- * reaches for a restored child (send/_send, lifecycle via start/_stop and
4001
- * system.stopActor, persistence, subscribe/on as inert subscriptions).
4002
- * Members that only make sense for a co-located actor (public stop(),
4003
- * select(), trigger) throw a descriptive error rather than being absent, so
4004
- * calling one reports what went wrong instead of a bare TypeError. Observable
4005
- * interop and _processingStatus are omitted entirely.
4006
- *
4007
- * @internal
4008
- */
4009
- function createRemoteActorRef(system, options) {
4010
- const handle = {
4011
- _remote: true,
4012
- // Self-reference so context persistence recognizes the handle as an
4013
- // actor reference instead of recursing into it.
4014
- ref: undefined,
4015
- id: options.id,
4016
- address: options.address,
4017
- src: options.src,
4018
- registryKey: options.registryKey,
4019
- // The host-supplied incarnation token, when present: the owner's
4020
- // sessionId for this child, letting this side drop stale completions and
4021
- // journaled sends name the intended incarnation. Without one the handle
4022
- // does not know the child's incarnation and the owning runtime is the
4023
- // authority on staleness.
4024
- sessionId: options.incarnation,
4025
- system,
4026
- _parent: options.parent,
4027
- // Round-trips through persistence verbatim (undefined stays undefined,
4028
- // so re-persisting is byte-stable); a remote handle cannot act on it
4029
- // locally.
4030
- _syncSnapshot: options.syncSnapshot,
4031
- send(event) {
4032
- void system.sendEvent(undefined, ref, event);
4033
- },
4034
- _send(event) {
4035
- throw new Error(`Remote actor '${options.address}' has no local mailbox to receive "${event.type}". Its state lives with another runtime; install a runtime that can reach it (via \`createDurable\`'s adapter runtime operations, or \`system.runtime\`) before sending, ${restoreHint}`);
4036
- },
4037
- getSnapshot() {
4038
- return remoteSnapshot;
4039
- },
4040
- getPersistedSnapshot() {
4041
- throw new Error(`Cannot persist remote actor '${options.address}' from here: its state lives with the runtime that owns it. Persist it there, ${restoreHint}`);
4042
- },
4043
- start() {},
4044
- _stop() {},
4045
- stop() {
4046
- throw new Error(`Cannot stop remote actor '${options.address}' directly: stopping is a co-located operation. Stop it through the system runtime that owns it (\`system.stopActor(ref)\`), ${restoreHint}`);
4047
- },
4048
- select() {
4049
- throw new Error(`Cannot select from remote actor '${options.address}': its snapshot is not synchronously readable because its state lives with another runtime. Read it on the runtime that owns it, ${restoreHint}`);
4050
- },
4051
- get trigger() {
4052
- throw new Error(`Remote actor '${options.address}' has no \`trigger\` shorthand: it requires a co-located actor. Use \`send(...)\`, which routes through the system runtime.`);
4053
- },
4054
- // Observation is a co-location capability: a remote handle never emits,
4055
- // so subscriptions are inert rather than errors — generic observers may
4056
- // attach to any ref.
4057
- subscribe() {
4058
- return emptySubscription;
4059
- },
4060
- on() {
4061
- return emptySubscription;
4062
- },
4063
- _isRunning() {
4064
- return false;
4065
- },
4066
- // The same shape Actor.toJSON produces, so serialized snapshots carry
4067
- // one actor-reference shape whether a child is co-located or remote.
4068
- toJSON() {
4069
- return {
4070
- $actor: options.address
4071
- };
4072
- }
4073
- };
4074
- const ref = handle;
4075
- handle.ref = ref;
4076
- return ref;
4077
- }
4078
-
4079
4224
  /**
4080
4225
  * Returns the path of the first value in `value` that does not survive
4081
4226
  * `JSON.stringify` → `JSON.parse` (functions, symbols, bigints, non-finite
@@ -4402,14 +4547,18 @@ function getPersistedSnapshot(snapshot, options) {
4402
4547
  const embedChildren = options?.embedChildren !== false;
4403
4548
  for (const id in children) {
4404
4549
  const child = children[id];
4405
- if (typeof child.src !== 'string' && (!options || !('__unsafeAllowInlineActors' in options))) {
4550
+ const sourceKey = typeof child.src === 'string' ? child.src : undefined;
4551
+ // An inline invoke has no source key; it restores through the invoke
4552
+ // definition with its id among the active states.
4553
+ const invoked = sourceKey === undefined && child._invoked === true && nodes.some(node => node.invoke.some(def => def.id === id));
4554
+ if (sourceKey === undefined && !invoked && (!options || !('__unsafeAllowInlineActors' in options))) {
4406
4555
  throw new Error('An inline child actor cannot be persisted.');
4407
4556
  }
4408
4557
  // Children are referenced by their logical address. Embedding the child
4409
4558
  // state is the co-locating runtime's whole-tree checkpoint capability;
4410
4559
  // remote handles never embed — their state lives with another runtime.
4411
4560
  const embed = embedChildren && !isRemoteActorRef(child);
4412
- if (!embed && typeof child.src !== 'string') {
4561
+ if (!embed && sourceKey === undefined) {
4413
4562
  // Fail where it is actionable: a by-address reference without a
4414
4563
  // registered source key could be persisted but never restored.
4415
4564
  throw new Error(`Unable to persist child '${id}' by address: it requires a registered source key.`);
@@ -4429,7 +4578,9 @@ function getPersistedSnapshot(snapshot, options) {
4429
4578
  // persisted snapshots nondeterministic across replays.
4430
4579
  incarnation: isRemoteActorRef(child) ? child.sessionId : undefined
4431
4580
  }),
4432
- src: child.src,
4581
+ ...(invoked ? {} : {
4582
+ src: child.src
4583
+ }),
4433
4584
  registryKey: child.registryKey,
4434
4585
  syncSnapshot: child._syncSnapshot
4435
4586
  };
@@ -4516,7 +4667,7 @@ function warnOnNonJsonPayload(persisted, machineId) {
4516
4667
  for (const key of ['context', 'output', 'error', 'stateInputs']) {
4517
4668
  const found = findNonJsonPath(persisted[key], key);
4518
4669
  if (found) {
4519
- console.warn(`Persisted snapshot of machine '${machineId}' contains a non-JSON value (${found.kind}) at '${found.path}'. Persisted snapshots must be JSON-serializable; this value will be lost or throw in JSON.stringify.`);
4670
+ console.warn(`Persisted snapshot of ${describeMachine(machineId)} contains a non-JSON value (${found.kind}) at '${found.path}'. Persisted snapshots must be JSON-serializable; this value will be lost or throw in JSON.stringify.`);
4520
4671
  return;
4521
4672
  }
4522
4673
  }
@@ -4589,6 +4740,18 @@ function assertUnreservedSourceName(kind, name) {
4589
4740
  throw new Error(`Invalid ${kind} name '${name}': the 'xstate.' and '@xstate.' prefixes are reserved for built-in names.`);
4590
4741
  }
4591
4742
  }
4743
+
4744
+ /** Whether a state key contains a `.` that is not escaped as `\\.`. */
4745
+ function hasUnescapedDot(key) {
4746
+ for (let i = 0; i < key.length; i++) {
4747
+ if (key[i] === '\\') {
4748
+ i++;
4749
+ } else if (key[i] === '.') {
4750
+ return true;
4751
+ }
4752
+ }
4753
+ return false;
4754
+ }
4592
4755
  function toStatePath(stateId) {
4593
4756
  if (isArray(stateId)) {
4594
4757
  return stateId;
@@ -4600,8 +4763,10 @@ function toStatePath(stateId) {
4600
4763
  switch (char) {
4601
4764
  // \
4602
4765
  case 92:
4603
- // consume the next character
4604
- segment += stateId[i + 1];
4766
+ // An escaped `.` stays escaped: `foo\\.bar` is one path segment, the
4767
+ // literal state key `'foo\\.bar'`. Other escapes consume the next
4768
+ // character.
4769
+ segment += stateId[i + 1] === '.' ? '\\.' : stateId[i + 1];
4605
4770
  // and skip over it
4606
4771
  i++;
4607
4772
  continue;
@@ -4709,11 +4874,22 @@ function isArray(value) {
4709
4874
  function isErrorEvent(event) {
4710
4875
  return event.type.startsWith('xstate.error.');
4711
4876
  }
4712
- function toTransitionConfigArray(configLike) {
4877
+
4878
+ /**
4879
+ * Normalizes authored transitions to config objects. A bare string target is
4880
+ * rejected (the types and `machineFromJSON` reject it too): `name` and
4881
+ * `stateId` locate it in the error.
4882
+ */
4883
+ function toTransitionConfigArray(configLike, name, stateId) {
4713
4884
  return toArrayStrict(configLike).map(transitionLike => {
4714
- if (typeof transitionLike === 'undefined' || typeof transitionLike === 'string') {
4885
+ // Untyped (JS or JSON-parsed) configs can still contain a string.
4886
+ const value = transitionLike;
4887
+ if (typeof value === 'string') {
4888
+ throw new Error(`Transition for "${name}" in ${stateId ? `state "${stateId}"` : 'the root state'} is the string "${value}". Use { target: '${value}' }. The @xstate/codemod string-targets transform rewrites these.`);
4889
+ }
4890
+ if (typeof transitionLike === 'undefined') {
4715
4891
  return {
4716
- target: transitionLike
4892
+ target: undefined
4717
4893
  };
4718
4894
  }
4719
4895
  if (typeof transitionLike === 'function') {
@@ -4744,25 +4920,54 @@ function toObserver(nextHandler, errorHandler, completionHandler) {
4744
4920
  } : {})
4745
4921
  };
4746
4922
  }
4923
+
4924
+ /**
4925
+ * Names a machine in messages: `machine 'shop'`, or `the machine` when it
4926
+ * has no id.
4927
+ */
4928
+ function describeMachine(id) {
4929
+ return id ? `machine '${id}'` : 'the machine';
4930
+ }
4931
+
4932
+ /** The implicit id of an invoke: `<stateId>:<index>`, e.g. `loading:0`. */
4747
4933
  function createInvokeId(stateNodeId, index) {
4748
- return `${index}.${stateNodeId}`;
4934
+ return `${stateNodeId}:${index}`;
4749
4935
  }
4750
4936
 
4751
4937
  /** Whether `value` looks like an actor ref (as persisted context detects them). */
4752
4938
  function isActorRefLike(value) {
4753
4939
  return 'sessionId' in value && 'send' in value && 'ref' in value;
4754
4940
  }
4755
- function resolveReferencedActor(machine, src) {
4756
- const match = src.match(/^xstate\.invoke\.(\d+)\.(.*)/);
4757
- if (!match) {
4758
- return machine.sources.actors[src];
4941
+
4942
+ /**
4943
+ * Resolves the logic of a persisted child that has no source key: an inline
4944
+ * invoke, identified by its id among the invoke definitions of the active
4945
+ * state nodes.
4946
+ */
4947
+ function resolveInvokedActorLogic(machine, nodes, childId) {
4948
+ const definitions = [];
4949
+ for (const node of nodes) {
4950
+ for (const definition of node.invoke) {
4951
+ if (definition.id === childId) {
4952
+ definitions.push(definition);
4953
+ }
4954
+ }
4955
+ }
4956
+ if (definitions.length !== 1) {
4957
+ throw new Error(`Unable to restore child actor '${childId}': it has no source key, and ${definitions.length ? 'several active states' : 'no active state'} of ${describeMachine(machine.id)} ${definitions.length ? 'invoke' : 'invokes'} it.`);
4958
+ }
4959
+ const logic = definitions[0].logic;
4960
+ if (typeof logic === 'string') {
4961
+ const registered = machine.sources.actors[logic];
4962
+ if (!registered) {
4963
+ throw new Error(`Unable to restore child actor '${childId}': child source '${logic}' is not provided in ${describeMachine(machine.id)}.`);
4964
+ }
4965
+ return registered;
4966
+ }
4967
+ if (typeof logic === 'function') {
4968
+ throw new Error(`Unable to restore child actor '${childId}': its invoke resolves \`src\` with a function that returned inline logic. Register the logic in \`actors\` and return its key so the child persists by source key.`);
4759
4969
  }
4760
- const [, indexStr, nodeId] = match;
4761
- const node = machine.getStateNodeById(nodeId);
4762
- const invokeConfig = node.config.invoke;
4763
- const configSrc = (Array.isArray(invokeConfig) ? invokeConfig[indexStr] : invokeConfig).src;
4764
- // A referenced actor may itself be registered by name.
4765
- return typeof configSrc === 'string' ? machine.sources.actors[configSrc] : configSrc;
4970
+ return logic;
4766
4971
  }
4767
4972
 
4768
4973
  /**
@@ -4954,8 +5159,7 @@ function deliverEvent(source, target, event) {
4954
5159
  return;
4955
5160
  }
4956
5161
  const runtimeTarget = target;
4957
- runtimeTarget._lastSourceRef = source;
4958
- runtimeTarget._send(event);
5162
+ runtimeTarget._send(event, source);
4959
5163
  }
4960
5164
 
4961
5165
  /**
@@ -5012,11 +5216,6 @@ function stopActor(actor) {
5012
5216
 
5013
5217
  let executionIdPrefix;
5014
5218
  let nextExecutionId = 0;
5015
-
5016
- /** @internal */
5017
- const transitionEffectSignal = new Error('Transition effect');
5018
- /** @internal */
5019
- const transitionEffectTargets = [];
5020
5219
  function createExecutionIdPrefix() {
5021
5220
  let crypto;
5022
5221
  try {
@@ -5085,9 +5284,9 @@ function getActorIdPrefix(src) {
5085
5284
  return src;
5086
5285
  }
5087
5286
  const logicId = src?.id;
5088
- // Anonymous machines get the placeholder id '(machine)'; only named logic
5089
- // earns a named id prefix.
5090
- return typeof logicId === 'string' && logicId.length && logicId !== '(machine)' ? logicId : 'x';
5287
+ // Only named logic earns a named id prefix; machines without an id have
5288
+ // the empty id.
5289
+ return typeof logicId === 'string' && logicId.length ? logicId : 'x';
5091
5290
  }
5092
5291
 
5093
5292
  /**
@@ -5468,7 +5667,13 @@ class RuntimeSystem {
5468
5667
  ...event,
5469
5668
  rootId: this._rootActor.sessionId
5470
5669
  };
5471
- this._inspectionObservers.forEach(observer => observer.next?.(resolvedInspectionEvent));
5670
+ this._inspectionObservers.forEach(observer => {
5671
+ try {
5672
+ observer.next?.(resolvedInspectionEvent);
5673
+ } catch (err) {
5674
+ reportUnhandledError(err);
5675
+ }
5676
+ });
5472
5677
  }
5473
5678
 
5474
5679
  // Unlike the other operations, spawn has no local work: local actors
@@ -5609,8 +5814,8 @@ class RuntimeSystem {
5609
5814
  this.cancelAll(source);
5610
5815
  }
5611
5816
  _relay(source, target, event) {
5612
- if (transitionEffectTargets.length && transitionEffectTargets.includes(target)) {
5613
- throw transitionEffectSignal;
5817
+ if (protectSelectionRelay(target)) {
5818
+ return;
5614
5819
  }
5615
5820
  // Returned so callers that can observe a host runtime's asynchronous
5616
5821
  // delivery do; the built-in runtime delivers synchronously.
@@ -5687,6 +5892,12 @@ function executeExecutableEffects(effects, actorScope) {
5687
5892
  actorScope.actionExecutor(effect);
5688
5893
  }
5689
5894
  }
5895
+
5896
+ /**
5897
+ * Options core passes when it creates actors: the public {@link ActorOptions}
5898
+ * plus the parent of a child actor. Not exported from the package entry.
5899
+ */
5900
+
5690
5901
  function createActorRef(logic, options) {
5691
5902
  return new Actor(logic, options);
5692
5903
  }
@@ -5849,7 +6060,12 @@ class Actor {
5849
6060
  const persistedState = options?.snapshot;
5850
6061
  this._restored = persistedState !== undefined;
5851
6062
  try {
5852
- if (persistedState) {
6063
+ // Only `undefined` means "no snapshot": an explicit `null` (or another
6064
+ // non-object) is a malformed snapshot the logic reports.
6065
+ if (persistedState !== undefined) {
6066
+ if (!this.logic.restoreSnapshot && persistedState === null) {
6067
+ throw new Error('Persisted snapshot must be an object.');
6068
+ }
5853
6069
  this._setSnapshot(this.logic.restoreSnapshot ? this.logic.restoreSnapshot(persistedState, this._actorScope) : persistedState);
5854
6070
  } else if (options?._inert) {
5855
6071
  // Inert actors (createInertActorScope) only anchor a scope for pure
@@ -5861,7 +6077,7 @@ class Actor {
5861
6077
  this._initialEffects = effects.length ? effects : undefined;
5862
6078
  }
5863
6079
  } catch (err) {
5864
- const restoreErrorSnapshot = persistedState && this.logic._createRestoreErrorSnapshot?.(persistedState, err);
6080
+ const restoreErrorSnapshot = persistedState === undefined ? undefined : this.logic._createRestoreErrorSnapshot?.(persistedState, err);
5865
6081
  // Machine logic keeps its snapshot shape on restore failures. Otherwise
5866
6082
  // we can't get the true `TSnapshot & { status: 'error'; }`, so this is a
5867
6083
  // lie of sorts.
@@ -6346,7 +6562,11 @@ class Actor {
6346
6562
  this.mailbox?.start();
6347
6563
  return this;
6348
6564
  }
6349
- _process(event) {
6565
+ _process({
6566
+ event,
6567
+ sourceRef
6568
+ }) {
6569
+ this._lastSourceRef = sourceRef;
6350
6570
  const previousSnapshot = this._snapshot;
6351
6571
  let nextState;
6352
6572
  let caughtError;
@@ -6561,9 +6781,9 @@ class Actor {
6561
6781
  }
6562
6782
 
6563
6783
  /** @internal */
6564
- _send(event) {
6784
+ _send(event, sourceRef) {
6565
6785
  if (this._processingStatus === ProcessingStatus.Stopped) {
6566
- this.system.deadLetter(this._lastSourceRef, this, event, 'stopped');
6786
+ this.system.deadLetter(sourceRef, this, event, 'stopped');
6567
6787
  return;
6568
6788
  }
6569
6789
  let mailbox = this.mailbox;
@@ -6574,7 +6794,10 @@ class Actor {
6574
6794
  mailbox.start();
6575
6795
  }
6576
6796
  }
6577
- mailbox.enqueue(event);
6797
+ mailbox.enqueue({
6798
+ event,
6799
+ sourceRef
6800
+ });
6578
6801
  }
6579
6802
 
6580
6803
  /**
@@ -6748,6 +6971,8 @@ exports.createStartEffect = createStartEffect;
6748
6971
  exports.createSubscriptionLogic = createSubscriptionLogic;
6749
6972
  exports.createTimerEffect = createTimerEffect;
6750
6973
  exports.deliverEvent = deliverEvent;
6974
+ exports.describeMachine = describeMachine;
6975
+ exports.detachedScopes = detachedScopes;
6751
6976
  exports.encodeAddressSegment = encodeAddressSegment;
6752
6977
  exports.evaluateCandidate = evaluateCandidate;
6753
6978
  exports.executeEffects = executeEffects;
@@ -6764,13 +6989,13 @@ exports.getPersistedSnapshot = getPersistedSnapshot;
6764
6989
  exports.getProperAncestors = getProperAncestors;
6765
6990
  exports.getRootActorId = getRootActorId;
6766
6991
  exports.getSnapshotActorRef = getSnapshotActorRef;
6767
- exports.getStateNodeByPath = getStateNodeByPath;
6768
6992
  exports.getStateNodes = getStateNodes;
6769
6993
  exports.getTimerKey = getTimerKey;
6770
6994
  exports.getTimerStart = getTimerStart;
6771
6995
  exports.getTransitionResult = getTransitionResult;
6772
6996
  exports.hasAmbientInspector = hasAmbientInspector;
6773
6997
  exports.hasEffect = hasEffect;
6998
+ exports.hasUnescapedDot = hasUnescapedDot;
6774
6999
  exports.initialMicrostep = initialMicrostep;
6775
7000
  exports.isActorRefLike = isActorRefLike;
6776
7001
  exports.isAtomicStateNode = isAtomicStateNode;
@@ -6796,7 +7021,7 @@ exports.readTimerKey = readTimerKey;
6796
7021
  exports.recordTimerStart = recordTimerStart;
6797
7022
  exports.reserveChildId = reserveChildId;
6798
7023
  exports.resolveActionsWithContext = resolveActionsWithContext;
6799
- exports.resolveReferencedActor = resolveReferencedActor;
7024
+ exports.resolveInvokedActorLogic = resolveInvokedActorLogic;
6800
7025
  exports.resolveRegisteredActorSource = resolveRegisteredActorSource;
6801
7026
  exports.resolveStateValue = resolveStateValue;
6802
7027
  exports.runStep = runStep;