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.
- package/README.md +99 -75
- package/dist/{createActor-b14a387c.development.cjs.js → createActor-11e36865.development.cjs.js} +476 -251
- package/dist/{createActor-009673a7.cjs.js → createActor-54296cf2.cjs.js} +474 -249
- package/dist/{createActor-c121cbf9.development.esm.js → createActor-9529bbaf.development.esm.js} +473 -250
- package/dist/{createActor-a8baa71f.esm.js → createActor-eaa95ae0.esm.js} +471 -248
- package/dist/declarations/src/State.d.ts +1 -1
- package/dist/declarations/src/StateMachine.d.ts +25 -2
- package/dist/declarations/src/StateNode.d.ts +2 -1
- package/dist/declarations/src/actors/callback.d.ts +3 -2
- package/dist/declarations/src/actors/index.d.ts +1 -1
- package/dist/declarations/src/actors/listener.d.ts +2 -2
- package/dist/declarations/src/actors/logic.d.ts +3 -2
- package/dist/declarations/src/actors/observable.d.ts +3 -2
- package/dist/declarations/src/actors/promise.d.ts +3 -2
- package/dist/declarations/src/actors/subscription.d.ts +2 -2
- package/dist/declarations/src/createActor.d.ts +7 -0
- package/dist/declarations/src/createMachine.d.ts +6 -5
- package/dist/declarations/src/eventTypes.d.ts +2 -1
- package/dist/declarations/src/graph/adjacency.d.ts +4 -3
- package/dist/declarations/src/graph/pathFromEvents.d.ts +4 -2
- package/dist/declarations/src/graph/shortestPaths.d.ts +4 -3
- package/dist/declarations/src/graph/simplePaths.d.ts +4 -3
- package/dist/declarations/src/graph/types.d.ts +58 -4
- package/dist/declarations/src/index.d.ts +1 -1
- package/dist/declarations/src/machineFromJSON.d.ts +13 -3
- package/dist/declarations/src/setup.d.ts +24 -38
- package/dist/declarations/src/spawn.d.ts +3 -2
- package/dist/declarations/src/stateUtils.d.ts +18 -8
- package/dist/declarations/src/transitionActions.d.ts +1 -0
- package/dist/declarations/src/typeUtils.d.ts +52 -0
- package/dist/declarations/src/types.d.ts +48 -83
- package/dist/declarations/src/types.v6.d.ts +82 -28
- package/dist/declarations/src/utils.d.ts +22 -3
- package/dist/{effectDescriptor-75145bce.cjs.js → effectDescriptor-425644eb.cjs.js} +1 -1
- package/dist/{effectDescriptor-7326693b.development.esm.js → effectDescriptor-97802bb8.esm.js} +1 -1
- package/dist/{effectDescriptor-acfd606c.esm.js → effectDescriptor-df768c71.development.esm.js} +1 -1
- package/dist/{effectDescriptor-3e92534c.development.cjs.js → effectDescriptor-fd2aaf45.development.cjs.js} +1 -1
- package/dist/{index-d064963f.esm.js → index-967ad7fa.esm.js} +1 -1
- package/dist/{index-43ce8782.development.cjs.js → index-9826ee1d.development.cjs.js} +1 -1
- package/dist/{index-a2835490.cjs.js → index-986372f2.cjs.js} +1 -1
- package/dist/{index-52951124.development.esm.js → index-e30fe161.development.esm.js} +1 -1
- package/dist/xstate-actors.cjs.js +2 -2
- package/dist/xstate-actors.development.cjs.js +2 -2
- package/dist/xstate-actors.development.esm.js +2 -2
- package/dist/xstate-actors.esm.js +2 -2
- package/dist/xstate-actors.umd.min.js +1 -1
- package/dist/xstate-actors.umd.min.js.map +1 -1
- package/dist/xstate-durable.cjs.js +2 -2
- package/dist/xstate-durable.development.cjs.js +2 -2
- package/dist/xstate-durable.development.esm.js +2 -2
- package/dist/xstate-durable.esm.js +2 -2
- package/dist/xstate-durable.umd.min.js +1 -1
- package/dist/xstate-durable.umd.min.js.map +1 -1
- package/dist/xstate-graph.cjs.js +58 -22
- package/dist/xstate-graph.development.cjs.js +58 -22
- package/dist/xstate-graph.development.esm.js +59 -23
- package/dist/xstate-graph.esm.js +59 -23
- package/dist/xstate-graph.umd.min.js +1 -1
- package/dist/xstate-graph.umd.min.js.map +1 -1
- package/dist/xstate-validation.cjs.js +1 -1
- package/dist/xstate-validation.development.cjs.js +1 -1
- package/dist/xstate-validation.development.esm.js +1 -1
- package/dist/xstate-validation.esm.js +1 -1
- package/dist/xstate-validation.umd.min.js.map +1 -1
- package/dist/xstate.cjs.js +148 -56
- package/dist/xstate.cjs.mjs +1 -0
- package/dist/xstate.development.cjs.js +162 -62
- package/dist/xstate.development.cjs.mjs +1 -0
- package/dist/xstate.development.esm.js +164 -65
- package/dist/xstate.esm.js +150 -59
- package/dist/xstate.umd.min.js +1 -1
- package/dist/xstate.umd.min.js.map +1 -1
- package/docs/actions.md +75 -0
- package/docs/actor-logic.md +250 -0
- package/docs/actors.md +64 -0
- package/docs/async-logic.md +75 -0
- package/docs/async-requests.md +157 -0
- package/docs/backend-workflows.md +121 -0
- package/docs/cancellation.md +42 -0
- package/docs/cheatsheet.md +561 -0
- package/docs/choice-states.md +109 -0
- package/docs/choose-xstate.md +47 -0
- package/docs/configuration.md +161 -0
- package/docs/context.md +63 -0
- package/docs/create-actor.md +156 -0
- package/docs/data-and-effects.md +48 -0
- package/docs/delays.md +81 -0
- package/docs/durable-execution.md +510 -0
- package/docs/emitted-events.md +127 -0
- package/docs/examples.md +75 -0
- package/docs/faq.md +60 -0
- package/docs/final-states.md +149 -0
- package/docs/forms-and-wizards.md +166 -0
- package/docs/frameworks.md +69 -0
- package/docs/fsm.md +164 -0
- package/docs/glossary.md +68 -0
- package/docs/guards.md +137 -0
- package/docs/history-states.md +159 -0
- package/docs/how-xstate-runs-machines.md +84 -0
- package/docs/index.md +71 -0
- package/docs/input-output.md +69 -0
- package/docs/inspect-actor-systems.md +116 -0
- package/docs/inspection.md +73 -0
- package/docs/internal-events.md +156 -0
- package/docs/invoke.md +354 -0
- package/docs/lifecycle-and-errors.md +48 -0
- package/docs/listen-and-subscribe.md +126 -0
- package/docs/model-based-testing.md +319 -0
- package/docs/modeling.md +40 -0
- package/docs/parallel-states.md +182 -0
- package/docs/persist-and-restore-actors.md +115 -0
- package/docs/persistence.md +325 -0
- package/docs/quick-start.md +55 -0
- package/docs/retries-and-timeouts.md +122 -0
- package/docs/route-states.md +104 -0
- package/docs/scxml.md +59 -0
- package/docs/selectors.md +99 -0
- package/docs/serialization.md +124 -0
- package/docs/setup-and-provide.md +271 -0
- package/docs/snapshots.md +134 -0
- package/docs/spawn.md +220 -0
- package/docs/state-input.md +162 -0
- package/docs/statecharts.md +54 -0
- package/docs/states-events-transitions.md +82 -0
- package/docs/states.md +168 -0
- package/docs/system-transitions.md +170 -0
- package/docs/systems.md +134 -0
- package/docs/testing.md +150 -0
- package/docs/timeouts.md +125 -0
- package/docs/transition-functions.md +87 -0
- package/docs/transitions.md +185 -0
- package/docs/troubleshooting.md +48 -0
- package/docs/tutorial.md +481 -0
- package/docs/typescript.md +211 -0
- package/docs/typestates.md +110 -0
- package/docs/utilities.md +39 -0
- package/docs/why-state-machines.md +59 -0
- package/docs/xstate-v5-to-v6.md +1756 -0
- package/docs/your-first-machine.md +79 -0
- package/package.json +2 -1
package/dist/{createActor-b14a387c.development.cjs.js → createActor-11e36865.development.cjs.js}
RENAMED
|
@@ -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 =
|
|
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
|
-
|
|
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
|
-
//
|
|
1043
|
-
|
|
1044
|
-
|
|
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
|
-
|
|
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' ?
|
|
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
|
|
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
|
-
|
|
3507
|
-
|
|
3508
|
-
|
|
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
|
-
|
|
3804
|
-
|
|
3805
|
-
|
|
3806
|
-
|
|
3807
|
-
|
|
3808
|
-
|
|
3809
|
-
|
|
3810
|
-
|
|
3811
|
-
|
|
3812
|
-
|
|
3813
|
-
|
|
3814
|
-
|
|
3815
|
-
}
|
|
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
|
|
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),
|
|
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
|
-
|
|
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
|
-
|
|
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 &&
|
|
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
|
-
|
|
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
|
|
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
|
-
//
|
|
4604
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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:
|
|
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 `${
|
|
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
|
-
|
|
4756
|
-
|
|
4757
|
-
|
|
4758
|
-
|
|
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
|
-
|
|
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.
|
|
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
|
-
//
|
|
5089
|
-
//
|
|
5090
|
-
return typeof logicId === 'string' && logicId.length
|
|
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 =>
|
|
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 (
|
|
5613
|
-
|
|
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
|
-
|
|
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
|
|
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(
|
|
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(
|
|
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(
|
|
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.
|
|
7024
|
+
exports.resolveInvokedActorLogic = resolveInvokedActorLogic;
|
|
6800
7025
|
exports.resolveRegisteredActorSource = resolveRegisteredActorSource;
|
|
6801
7026
|
exports.resolveStateValue = resolveStateValue;
|
|
6802
7027
|
exports.runStep = runStep;
|