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

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 (235) hide show
  1. package/README.md +223 -78
  2. package/bin/agent.js +347 -0
  3. package/bin/xstate.js +52 -0
  4. package/dist/createActor-25900f76.cjs.js +7015 -0
  5. package/dist/createActor-551369be.development.esm.js +7175 -0
  6. package/dist/createActor-a49ae0ce.development.cjs.js +7289 -0
  7. package/dist/createActor-cbe3abac.esm.js +6902 -0
  8. package/dist/declarations/src/SimulatedClock.d.ts +2 -1
  9. package/dist/declarations/src/State.d.ts +66 -5
  10. package/dist/declarations/src/StateMachine.d.ts +107 -32
  11. package/dist/declarations/src/StateNode.d.ts +21 -16
  12. package/dist/declarations/src/actions.d.ts +11 -6
  13. package/dist/declarations/src/actors/callback.d.ts +11 -2
  14. package/dist/declarations/src/actors/index.d.ts +6 -5
  15. package/dist/declarations/src/actors/listener.d.ts +8 -3
  16. package/dist/declarations/src/actors/logic.d.ts +42 -52
  17. package/dist/declarations/src/actors/observable.d.ts +15 -2
  18. package/dist/declarations/src/actors/promise.d.ts +90 -22
  19. package/dist/declarations/src/actors/subscription.d.ts +9 -3
  20. package/dist/declarations/src/assert.d.ts +1 -0
  21. package/dist/declarations/src/base.types.d.ts +102 -0
  22. package/dist/declarations/src/createActor.d.ts +101 -27
  23. package/dist/declarations/src/createMachine.d.ts +38 -17
  24. package/dist/declarations/src/delay.d.ts +8 -0
  25. package/dist/declarations/src/durable/index.d.ts +231 -0
  26. package/dist/declarations/src/effectDescriptor.d.ts +95 -0
  27. package/dist/declarations/src/eventTypes.d.ts +9 -0
  28. package/dist/declarations/src/fsm/index.d.ts +2 -0
  29. package/dist/declarations/src/fsm.d.ts +169 -0
  30. package/dist/declarations/src/graph/adjacency.d.ts +6 -3
  31. package/dist/declarations/src/graph/graph.d.ts +6 -3
  32. package/dist/declarations/src/graph/index.d.ts +2 -3
  33. package/dist/declarations/src/graph/pathFromEvents.d.ts +5 -2
  34. package/dist/declarations/src/graph/shortestPaths.d.ts +5 -3
  35. package/dist/declarations/src/graph/simplePaths.d.ts +5 -3
  36. package/dist/declarations/src/graph/types.d.ts +113 -59
  37. package/dist/declarations/src/hotSwap.d.ts +18 -0
  38. package/dist/declarations/src/index.d.ts +28 -19
  39. package/dist/declarations/src/inspection.d.ts +24 -1
  40. package/dist/declarations/src/machineFromJSON.d.ts +171 -0
  41. package/dist/declarations/src/machineSchemas.d.ts +27 -0
  42. package/dist/declarations/src/machineVersion.types.d.ts +53 -0
  43. package/dist/declarations/src/machineVersions.d.ts +103 -0
  44. package/dist/declarations/src/mapState.d.ts +2 -0
  45. package/dist/declarations/src/persist/index.d.ts +36 -0
  46. package/dist/declarations/src/persistedSnapshotValidation.d.ts +18 -0
  47. package/dist/declarations/src/runtimeHelpers.d.ts +43 -0
  48. package/dist/declarations/src/schema.types.d.ts +31 -4
  49. package/dist/declarations/src/serialize.d.ts +39 -28
  50. package/dist/declarations/src/setup.d.ts +1086 -147
  51. package/dist/declarations/src/spawn.d.ts +6 -4
  52. package/dist/declarations/src/stateUtils.d.ts +57 -14
  53. package/dist/declarations/src/system.d.ts +178 -17
  54. package/dist/declarations/src/systemTransition.d.ts +108 -0
  55. package/dist/declarations/src/toPromise.d.ts +1 -0
  56. package/dist/declarations/src/transition.d.ts +48 -10
  57. package/dist/declarations/src/transitionActions.d.ts +22 -4
  58. package/dist/declarations/src/typeUtils.d.ts +51 -0
  59. package/dist/declarations/src/types.d.ts +835 -318
  60. package/dist/declarations/src/types.v6.d.ts +547 -104
  61. package/dist/declarations/src/utils.d.ts +38 -8
  62. package/dist/declarations/src/validation/index.d.ts +49 -0
  63. package/dist/declarations/src/validation.types.d.ts +29 -0
  64. package/dist/declarations/src/waitFor.d.ts +1 -0
  65. package/dist/effectDescriptor-2fa27c54.cjs.js +351 -0
  66. package/dist/effectDescriptor-321a8ce9.development.esm.js +343 -0
  67. package/dist/effectDescriptor-d8b0f749.esm.js +343 -0
  68. package/dist/effectDescriptor-f73da4ec.development.cjs.js +351 -0
  69. package/dist/machineSchemas-45c21bc2.esm.js +1292 -0
  70. package/dist/machineSchemas-6d96bef4.development.cjs.js +1379 -0
  71. package/dist/machineSchemas-88d01821.cjs.js +1300 -0
  72. package/dist/machineSchemas-b5736804.development.esm.js +1371 -0
  73. package/dist/schema.types-0ecd17b8.esm.js +71 -0
  74. package/dist/schema.types-15a68ddc.cjs.js +74 -0
  75. package/dist/schema.types-1c16f035.development.cjs.js +74 -0
  76. package/dist/schema.types-1cd4652e.development.esm.js +71 -0
  77. package/dist/validation-05f1d517.esm.js +8 -0
  78. package/dist/validation-4561b43c.cjs.js +10 -0
  79. package/dist/validation-e69470ad.development.esm.js +8 -0
  80. package/dist/validation-f2714a35.development.cjs.js +10 -0
  81. package/dist/xstate-actors.cjs.js +1068 -12
  82. package/dist/xstate-actors.cjs.mjs +2 -4
  83. package/dist/xstate-actors.development.cjs.js +1068 -12
  84. package/dist/xstate-actors.development.cjs.mjs +2 -4
  85. package/dist/xstate-actors.development.esm.js +1064 -1
  86. package/dist/xstate-actors.esm.js +1064 -1
  87. package/dist/xstate-actors.umd.min.js +1 -1
  88. package/dist/xstate-actors.umd.min.js.map +1 -1
  89. package/dist/xstate-durable.cjs.d.mts +2 -0
  90. package/dist/xstate-durable.cjs.d.ts +2 -0
  91. package/dist/xstate-durable.cjs.js +513 -0
  92. package/dist/xstate-durable.cjs.mjs +5 -0
  93. package/dist/xstate-durable.development.cjs.js +513 -0
  94. package/dist/xstate-durable.development.cjs.mjs +5 -0
  95. package/dist/xstate-durable.development.esm.js +507 -0
  96. package/dist/xstate-durable.esm.js +507 -0
  97. package/dist/xstate-durable.umd.min.js +2 -0
  98. package/dist/xstate-durable.umd.min.js.map +1 -0
  99. package/dist/xstate-fsm.cjs.d.mts +2 -0
  100. package/dist/xstate-fsm.cjs.d.ts +2 -0
  101. package/dist/xstate-fsm.cjs.js +111 -0
  102. package/dist/xstate-fsm.cjs.mjs +5 -0
  103. package/dist/xstate-fsm.development.cjs.js +111 -0
  104. package/dist/xstate-fsm.development.cjs.mjs +5 -0
  105. package/dist/xstate-fsm.development.esm.js +105 -0
  106. package/dist/xstate-fsm.esm.js +105 -0
  107. package/dist/xstate-fsm.umd.min.js +2 -0
  108. package/dist/xstate-fsm.umd.min.js.map +1 -0
  109. package/dist/xstate-graph.cjs.js +173 -457
  110. package/dist/xstate-graph.cjs.mjs +2 -5
  111. package/dist/xstate-graph.development.cjs.js +173 -457
  112. package/dist/xstate-graph.development.cjs.mjs +2 -5
  113. package/dist/xstate-graph.development.esm.js +171 -451
  114. package/dist/xstate-graph.esm.js +171 -451
  115. package/dist/xstate-graph.umd.min.js +1 -1
  116. package/dist/xstate-graph.umd.min.js.map +1 -1
  117. package/dist/xstate-persist.cjs.d.mts +2 -0
  118. package/dist/xstate-persist.cjs.d.ts +2 -0
  119. package/dist/xstate-persist.cjs.js +314 -0
  120. package/dist/xstate-persist.cjs.mjs +6 -0
  121. package/dist/xstate-persist.development.cjs.js +325 -0
  122. package/dist/xstate-persist.development.cjs.mjs +6 -0
  123. package/dist/xstate-persist.development.esm.js +319 -0
  124. package/dist/xstate-persist.esm.js +308 -0
  125. package/dist/xstate-persist.umd.min.js +2 -0
  126. package/dist/xstate-persist.umd.min.js.map +1 -0
  127. package/dist/xstate-validation.cjs.d.mts +2 -0
  128. package/dist/xstate-validation.cjs.d.ts +2 -0
  129. package/dist/xstate-validation.cjs.js +330 -0
  130. package/dist/xstate-validation.cjs.mjs +5 -0
  131. package/dist/xstate-validation.development.cjs.js +330 -0
  132. package/dist/xstate-validation.development.cjs.mjs +5 -0
  133. package/dist/xstate-validation.development.esm.js +324 -0
  134. package/dist/xstate-validation.esm.js +324 -0
  135. package/dist/xstate-validation.umd.min.js +2 -0
  136. package/dist/xstate-validation.umd.min.js.map +1 -0
  137. package/dist/xstate.cjs.js +2486 -1430
  138. package/dist/xstate.cjs.mjs +23 -13
  139. package/dist/xstate.development.cjs.js +2486 -1430
  140. package/dist/xstate.development.cjs.mjs +23 -13
  141. package/dist/xstate.development.esm.js +2445 -1398
  142. package/dist/xstate.esm.js +2445 -1398
  143. package/dist/xstate.umd.min.js +1 -1
  144. package/dist/xstate.umd.min.js.map +1 -1
  145. package/docs/actions.md +75 -0
  146. package/docs/actor-logic.md +250 -0
  147. package/docs/actors.md +64 -0
  148. package/docs/agents.md +132 -0
  149. package/docs/api-stability.json +4287 -0
  150. package/docs/async-logic.md +75 -0
  151. package/docs/async-requests.md +157 -0
  152. package/docs/backend-workflows.md +124 -0
  153. package/docs/cancellation.md +42 -0
  154. package/docs/cheatsheet.md +563 -0
  155. package/docs/choice-states.md +109 -0
  156. package/docs/choose-xstate.md +47 -0
  157. package/docs/configuration.md +161 -0
  158. package/docs/context.md +67 -0
  159. package/docs/create-actor.md +159 -0
  160. package/docs/data-and-effects.md +48 -0
  161. package/docs/delays.md +81 -0
  162. package/docs/durable-execution.md +520 -0
  163. package/docs/emitted-events.md +146 -0
  164. package/docs/errors.md +812 -0
  165. package/docs/examples.md +75 -0
  166. package/docs/faq.md +60 -0
  167. package/docs/final-states.md +149 -0
  168. package/docs/forms-and-wizards.md +166 -0
  169. package/docs/frameworks.md +69 -0
  170. package/docs/fsm.md +164 -0
  171. package/docs/glossary.md +68 -0
  172. package/docs/guards.md +137 -0
  173. package/docs/history-states.md +161 -0
  174. package/docs/how-xstate-runs-machines.md +86 -0
  175. package/docs/index.md +74 -0
  176. package/docs/input-output.md +69 -0
  177. package/docs/inspect-actor-systems.md +118 -0
  178. package/docs/inspection.md +75 -0
  179. package/docs/internal-events.md +156 -0
  180. package/docs/invoke.md +371 -0
  181. package/docs/lifecycle-and-errors.md +48 -0
  182. package/docs/listen-and-subscribe.md +126 -0
  183. package/docs/model-based-testing.md +321 -0
  184. package/docs/modeling.md +40 -0
  185. package/docs/parallel-states.md +182 -0
  186. package/docs/persist-and-restore-actors.md +120 -0
  187. package/docs/persistence.md +312 -0
  188. package/docs/quick-start.md +55 -0
  189. package/docs/retries-and-timeouts.md +122 -0
  190. package/docs/route-states.md +104 -0
  191. package/docs/scxml.md +92 -0
  192. package/docs/selectors.md +99 -0
  193. package/docs/serialization.md +127 -0
  194. package/docs/setup-and-provide.md +273 -0
  195. package/docs/snapshots.md +134 -0
  196. package/docs/spawn.md +212 -0
  197. package/docs/state-input.md +162 -0
  198. package/docs/statecharts.md +54 -0
  199. package/docs/states-events-transitions.md +82 -0
  200. package/docs/states.md +168 -0
  201. package/docs/system-transitions.md +172 -0
  202. package/docs/systems.md +166 -0
  203. package/docs/testing.md +152 -0
  204. package/docs/timeouts.md +125 -0
  205. package/docs/transition-functions.md +89 -0
  206. package/docs/transitions.md +187 -0
  207. package/docs/troubleshooting.md +56 -0
  208. package/docs/tutorial.md +481 -0
  209. package/docs/typescript.md +213 -0
  210. package/docs/typestates.md +112 -0
  211. package/docs/utilities.md +39 -0
  212. package/docs/why-state-machines.md +59 -0
  213. package/docs/xstate-v5-to-v6.md +1923 -0
  214. package/docs/your-first-machine.md +79 -0
  215. package/durable/package.json +8 -0
  216. package/fsm/package.json +8 -0
  217. package/package.json +72 -10
  218. package/persist/package.json +8 -0
  219. package/validation/package.json +8 -0
  220. package/actions/package.json +0 -8
  221. package/dev/package.json +0 -8
  222. package/dist/StateMachine-0aa98f54.development.esm.js +0 -746
  223. package/dist/StateMachine-aef700df.cjs.js +0 -732
  224. package/dist/StateMachine-d4931336.esm.js +0 -729
  225. package/dist/StateMachine-da872dde.development.cjs.js +0 -749
  226. package/dist/declarations/src/createMachineFromConfig.d.ts +0 -177
  227. package/dist/declarations/src/getNextSnapshot.d.ts +0 -37
  228. package/dist/declarations/src/graph/TestModel.d.ts +0 -70
  229. package/dist/declarations/src/graph/pathGenerators.d.ts +0 -4
  230. package/dist/index-219cb621.development.cjs.js +0 -4476
  231. package/dist/index-2f2fbd9b.development.esm.js +0 -4421
  232. package/dist/index-559ceab3.cjs.js +0 -4437
  233. package/dist/index-8828376f.esm.js +0 -4382
  234. package/guards/package.json +0 -8
  235. package/invoke/package.json +0 -4
@@ -0,0 +1,324 @@
1
+ import { m as matchesEventDescriptor } from './createActor-551369be.development.esm.js';
2
+
3
+ const actorValidationErrorSymbol = Symbol.for('xstate.actorValidationError');
4
+
5
+ /** @experimental */
6
+
7
+ /** @experimental */
8
+
9
+ /**
10
+ * A structured failure produced by `standardSchemaValidator()`.
11
+ *
12
+ * @experimental
13
+ */
14
+ class ActorValidationError extends Error {
15
+ constructor(options) {
16
+ super(getMessage(options), {
17
+ cause: options.cause
18
+ });
19
+ this[actorValidationErrorSymbol] = true;
20
+ this.reason = void 0;
21
+ this.boundary = void 0;
22
+ this.logicId = void 0;
23
+ this.stateNodeId = void 0;
24
+ this.eventType = void 0;
25
+ this.eventOrigin = void 0;
26
+ this.childId = void 0;
27
+ this.issues = void 0;
28
+ this.cause = void 0;
29
+ this.name = 'ActorValidationError';
30
+ this.reason = options.reason;
31
+ this.boundary = options.boundary;
32
+ this.logicId = options.logicId;
33
+ this.stateNodeId = options.stateNodeId;
34
+ this.eventType = options.eventType;
35
+ this.eventOrigin = options.eventOrigin;
36
+ this.childId = options.childId;
37
+ this.issues = options.issues;
38
+ this.cause = options.cause;
39
+ }
40
+ }
41
+
42
+ /** @experimental */
43
+ function isActorValidationError(value) {
44
+ return !!(value && typeof value === 'object' && actorValidationErrorSymbol in value);
45
+ }
46
+
47
+ /** @experimental */
48
+
49
+ /**
50
+ * Creates a synchronous, assertion-only Standard Schema validator.
51
+ *
52
+ * @experimental
53
+ */
54
+ function standardSchemaValidator(options = {}) {
55
+ const unknownEvents = options.unknownEvents ?? 'error';
56
+ const unknownEmitted = options.unknownEmitted ?? 'error';
57
+ const checkTarget = target => {
58
+ if (!target.schema) {
59
+ if (target.boundary === 'event' && unknownEvents === 'error') {
60
+ return createError(target, 'unknownEvent');
61
+ }
62
+ if (target.boundary === 'emitted' && unknownEmitted === 'error') {
63
+ return createError(target, 'unknownEmitted');
64
+ }
65
+ return undefined;
66
+ }
67
+ let result;
68
+ try {
69
+ result = target.schema['~standard'].validate(target.value);
70
+ } catch (cause) {
71
+ return createError(target, 'schemaThrew', undefined, cause);
72
+ }
73
+ if (isPromiseLike(result)) {
74
+ void Promise.resolve(result).catch(() => {});
75
+ return createError(target, 'asyncValidationUnsupported');
76
+ }
77
+ if (result.issues) {
78
+ return createError(target, 'invalid', result.issues);
79
+ }
80
+ return undefined;
81
+ };
82
+
83
+ // Event schemas describe the payload, so `type` is removed before
84
+ // validation. A schema that reports an issue at `type` declares the key
85
+ // itself (e.g. one reused from a discriminated union), so it is checked
86
+ // against the complete event instead.
87
+ const checkEventTarget = (target, event) => {
88
+ const error = checkTarget({
89
+ ...target,
90
+ value: getPayload(event)
91
+ });
92
+ return error?.issues?.some(isTypeIssue) ? checkTarget({
93
+ ...target,
94
+ value: event
95
+ }) : error;
96
+ };
97
+ const checkEvent = (logic, event, eventOrigin) => {
98
+ const schemas = getSchemas(logic);
99
+ if (event.type.startsWith('xstate.') || event.type.startsWith('@xstate.')) {
100
+ return undefined;
101
+ }
102
+ const eventSchemas = schemas?.events;
103
+ const internalEventSchemas = schemas?.internalEvents;
104
+ const schema = findEventSchema(internalEventSchemas, event.type) ?? findEventSchema(eventSchemas, event.type);
105
+ if (!eventSchemas && !internalEventSchemas) {
106
+ return undefined;
107
+ }
108
+ return checkEventTarget({
109
+ schema,
110
+ boundary: 'event',
111
+ logicId: getLogicId(logic),
112
+ eventType: event.type,
113
+ eventOrigin
114
+ }, event);
115
+ };
116
+ const checkEmitted = (logic, effects) => {
117
+ const schemas = getSchemas(logic);
118
+ if (!schemas?.emitted) {
119
+ return undefined;
120
+ }
121
+ for (const effect of effects) {
122
+ if (effect.kind !== 'emit') {
123
+ continue;
124
+ }
125
+ const error = checkEventTarget({
126
+ schema: schemas.emitted[effect.event.type],
127
+ boundary: 'emitted',
128
+ logicId: getLogicId(logic),
129
+ eventType: effect.event.type
130
+ }, effect.event);
131
+ if (error) {
132
+ return error;
133
+ }
134
+ }
135
+ return undefined;
136
+ };
137
+ const checkMachineResult = (machine, snapshot) => {
138
+ let error = checkTarget({
139
+ schema: machine.schemas?.context,
140
+ value: snapshot.context,
141
+ boundary: 'context',
142
+ logicId: machine.id
143
+ });
144
+ if (error) {
145
+ return error;
146
+ }
147
+ for (const stateNode of snapshot.nodes) {
148
+ // the root state node reuses the machine-level `schemas` object, which is
149
+ // already validated above and elsewhere; those are not state-local
150
+ if (stateNode === machine.root) {
151
+ continue;
152
+ }
153
+ error = checkTarget({
154
+ schema: stateNode.schemas?.context,
155
+ value: snapshot.context,
156
+ boundary: 'state.context',
157
+ logicId: machine.id,
158
+ stateNodeId: stateNode.id
159
+ });
160
+ if (error) {
161
+ return error;
162
+ }
163
+ if (stateNode.schemas?.input) {
164
+ error = checkTarget({
165
+ schema: stateNode.schemas.input,
166
+ value: snapshot._stateInputs[stateNode.id],
167
+ boundary: 'state.input',
168
+ logicId: machine.id,
169
+ stateNodeId: stateNode.id
170
+ });
171
+ if (error) {
172
+ return error;
173
+ }
174
+ }
175
+ }
176
+ for (const childId of Object.keys(machine.schemas?.children ?? {})) {
177
+ const child = snapshot.children[childId];
178
+ if (child !== undefined) {
179
+ error = checkTarget({
180
+ schema: machine.schemas.children[childId],
181
+ value: child,
182
+ boundary: 'child',
183
+ logicId: machine.id,
184
+ childId
185
+ });
186
+ if (error) {
187
+ return error;
188
+ }
189
+ }
190
+ }
191
+ for (const timer of snapshot.timers) {
192
+ if (timer.type === '@xstate.raise') {
193
+ error = checkEvent(machine, timer.event, 'raised');
194
+ if (error) {
195
+ return error;
196
+ }
197
+ }
198
+ }
199
+ return undefined;
200
+ };
201
+ return {
202
+ check(request) {
203
+ const {
204
+ logic
205
+ } = request;
206
+ const schemas = getSchemas(logic);
207
+ if (request.kind === 'input') {
208
+ return checkTarget({
209
+ schema: schemas?.input,
210
+ value: request.input,
211
+ boundary: 'input',
212
+ logicId: getLogicId(logic)
213
+ });
214
+ }
215
+ if (request.kind === 'event') {
216
+ return checkEvent(logic, request.event, request.eventOrigin);
217
+ }
218
+ const {
219
+ snapshot,
220
+ effects
221
+ } = request;
222
+ if (isStateMachine(logic)) {
223
+ const error = checkMachineResult(logic, snapshot);
224
+ if (error) {
225
+ return error;
226
+ }
227
+ }
228
+ if (snapshot.status === 'done') {
229
+ const error = checkTarget({
230
+ schema: schemas?.output,
231
+ value: snapshot.output,
232
+ boundary: 'output',
233
+ logicId: getLogicId(logic)
234
+ });
235
+ if (error) {
236
+ return error;
237
+ }
238
+ }
239
+ return checkEmitted(logic, effects);
240
+ }
241
+ };
242
+ }
243
+ function createError(request, reason, issues, cause) {
244
+ return new ActorValidationError({
245
+ reason,
246
+ boundary: request.boundary,
247
+ ...(request.logicId === undefined ? {} : {
248
+ logicId: request.logicId
249
+ }),
250
+ ...(request.stateNodeId === undefined ? {} : {
251
+ stateNodeId: request.stateNodeId
252
+ }),
253
+ ...(request.eventType === undefined ? {} : {
254
+ eventType: request.eventType
255
+ }),
256
+ ...(request.eventOrigin === undefined ? {} : {
257
+ eventOrigin: request.eventOrigin
258
+ }),
259
+ ...(request.childId === undefined ? {} : {
260
+ childId: request.childId
261
+ }),
262
+ ...(issues === undefined ? {} : {
263
+ issues
264
+ }),
265
+ ...(cause === undefined ? {} : {
266
+ cause
267
+ })
268
+ });
269
+ }
270
+ function isStateMachine(logic) {
271
+ return 'root' in logic && 'schemas' in logic;
272
+ }
273
+ function getSchemas(logic) {
274
+ if (isStateMachine(logic)) {
275
+ return logic.schemas;
276
+ }
277
+ return logic.config?.schemas;
278
+ }
279
+ function findEventSchema(schemas, eventType) {
280
+ if (!schemas) {
281
+ return undefined;
282
+ }
283
+ if (Object.hasOwn(schemas, eventType)) {
284
+ return schemas[eventType];
285
+ }
286
+ const descriptor = Object.keys(schemas).find(key => matchesEventDescriptor(eventType, key));
287
+ return descriptor === undefined ? undefined : schemas[descriptor];
288
+ }
289
+ function getLogicId(logic) {
290
+ return 'id' in logic && typeof logic.id === 'string' ? logic.id : undefined;
291
+ }
292
+ function getPayload(event) {
293
+ const {
294
+ type: _,
295
+ ...payload
296
+ } = event;
297
+ return payload;
298
+ }
299
+ function isTypeIssue(issue) {
300
+ const segment = issue.path?.[0];
301
+ return (typeof segment === 'object' ? segment.key : segment) === 'type';
302
+ }
303
+ function getMessage(options) {
304
+ const subject = options.eventType !== undefined ? ` "${options.eventType}"` : options.childId !== undefined ? ` "${options.childId}"` : '';
305
+ switch (options.reason) {
306
+ case 'unknownEvent':
307
+ return `Unknown event${subject}`;
308
+ case 'unknownEmitted':
309
+ return `Unknown emitted event${subject}`;
310
+ case 'asyncValidationUnsupported':
311
+ return `Async schema validation is unsupported for ${options.boundary}${subject}`;
312
+ case 'transformationUnsupported':
313
+ return `Schema transformations are unsupported for ${options.boundary}${subject}`;
314
+ case 'schemaThrew':
315
+ return `Schema threw while validating ${options.boundary}${subject}`;
316
+ case 'invalid':
317
+ return `Invalid ${options.boundary}${subject}`;
318
+ }
319
+ }
320
+ function isPromiseLike(value) {
321
+ return !!value && typeof value.then === 'function';
322
+ }
323
+
324
+ export { ActorValidationError, isActorValidationError, standardSchemaValidator };
@@ -0,0 +1,324 @@
1
+ import { m as matchesEventDescriptor } from './createActor-cbe3abac.esm.js';
2
+
3
+ const actorValidationErrorSymbol = Symbol.for('xstate.actorValidationError');
4
+
5
+ /** @experimental */
6
+
7
+ /** @experimental */
8
+
9
+ /**
10
+ * A structured failure produced by `standardSchemaValidator()`.
11
+ *
12
+ * @experimental
13
+ */
14
+ class ActorValidationError extends Error {
15
+ constructor(options) {
16
+ super(getMessage(options), {
17
+ cause: options.cause
18
+ });
19
+ this[actorValidationErrorSymbol] = true;
20
+ this.reason = void 0;
21
+ this.boundary = void 0;
22
+ this.logicId = void 0;
23
+ this.stateNodeId = void 0;
24
+ this.eventType = void 0;
25
+ this.eventOrigin = void 0;
26
+ this.childId = void 0;
27
+ this.issues = void 0;
28
+ this.cause = void 0;
29
+ this.name = 'ActorValidationError';
30
+ this.reason = options.reason;
31
+ this.boundary = options.boundary;
32
+ this.logicId = options.logicId;
33
+ this.stateNodeId = options.stateNodeId;
34
+ this.eventType = options.eventType;
35
+ this.eventOrigin = options.eventOrigin;
36
+ this.childId = options.childId;
37
+ this.issues = options.issues;
38
+ this.cause = options.cause;
39
+ }
40
+ }
41
+
42
+ /** @experimental */
43
+ function isActorValidationError(value) {
44
+ return !!(value && typeof value === 'object' && actorValidationErrorSymbol in value);
45
+ }
46
+
47
+ /** @experimental */
48
+
49
+ /**
50
+ * Creates a synchronous, assertion-only Standard Schema validator.
51
+ *
52
+ * @experimental
53
+ */
54
+ function standardSchemaValidator(options = {}) {
55
+ const unknownEvents = options.unknownEvents ?? 'error';
56
+ const unknownEmitted = options.unknownEmitted ?? 'error';
57
+ const checkTarget = target => {
58
+ if (!target.schema) {
59
+ if (target.boundary === 'event' && unknownEvents === 'error') {
60
+ return createError(target, 'unknownEvent');
61
+ }
62
+ if (target.boundary === 'emitted' && unknownEmitted === 'error') {
63
+ return createError(target, 'unknownEmitted');
64
+ }
65
+ return undefined;
66
+ }
67
+ let result;
68
+ try {
69
+ result = target.schema['~standard'].validate(target.value);
70
+ } catch (cause) {
71
+ return createError(target, 'schemaThrew', undefined, cause);
72
+ }
73
+ if (isPromiseLike(result)) {
74
+ void Promise.resolve(result).catch(() => {});
75
+ return createError(target, 'asyncValidationUnsupported');
76
+ }
77
+ if (result.issues) {
78
+ return createError(target, 'invalid', result.issues);
79
+ }
80
+ return undefined;
81
+ };
82
+
83
+ // Event schemas describe the payload, so `type` is removed before
84
+ // validation. A schema that reports an issue at `type` declares the key
85
+ // itself (e.g. one reused from a discriminated union), so it is checked
86
+ // against the complete event instead.
87
+ const checkEventTarget = (target, event) => {
88
+ const error = checkTarget({
89
+ ...target,
90
+ value: getPayload(event)
91
+ });
92
+ return error?.issues?.some(isTypeIssue) ? checkTarget({
93
+ ...target,
94
+ value: event
95
+ }) : error;
96
+ };
97
+ const checkEvent = (logic, event, eventOrigin) => {
98
+ const schemas = getSchemas(logic);
99
+ if (event.type.startsWith('xstate.') || event.type.startsWith('@xstate.')) {
100
+ return undefined;
101
+ }
102
+ const eventSchemas = schemas?.events;
103
+ const internalEventSchemas = schemas?.internalEvents;
104
+ const schema = findEventSchema(internalEventSchemas, event.type) ?? findEventSchema(eventSchemas, event.type);
105
+ if (!eventSchemas && !internalEventSchemas) {
106
+ return undefined;
107
+ }
108
+ return checkEventTarget({
109
+ schema,
110
+ boundary: 'event',
111
+ logicId: getLogicId(logic),
112
+ eventType: event.type,
113
+ eventOrigin
114
+ }, event);
115
+ };
116
+ const checkEmitted = (logic, effects) => {
117
+ const schemas = getSchemas(logic);
118
+ if (!schemas?.emitted) {
119
+ return undefined;
120
+ }
121
+ for (const effect of effects) {
122
+ if (effect.kind !== 'emit') {
123
+ continue;
124
+ }
125
+ const error = checkEventTarget({
126
+ schema: schemas.emitted[effect.event.type],
127
+ boundary: 'emitted',
128
+ logicId: getLogicId(logic),
129
+ eventType: effect.event.type
130
+ }, effect.event);
131
+ if (error) {
132
+ return error;
133
+ }
134
+ }
135
+ return undefined;
136
+ };
137
+ const checkMachineResult = (machine, snapshot) => {
138
+ let error = checkTarget({
139
+ schema: machine.schemas?.context,
140
+ value: snapshot.context,
141
+ boundary: 'context',
142
+ logicId: machine.id
143
+ });
144
+ if (error) {
145
+ return error;
146
+ }
147
+ for (const stateNode of snapshot.nodes) {
148
+ // the root state node reuses the machine-level `schemas` object, which is
149
+ // already validated above and elsewhere; those are not state-local
150
+ if (stateNode === machine.root) {
151
+ continue;
152
+ }
153
+ error = checkTarget({
154
+ schema: stateNode.schemas?.context,
155
+ value: snapshot.context,
156
+ boundary: 'state.context',
157
+ logicId: machine.id,
158
+ stateNodeId: stateNode.id
159
+ });
160
+ if (error) {
161
+ return error;
162
+ }
163
+ if (stateNode.schemas?.input) {
164
+ error = checkTarget({
165
+ schema: stateNode.schemas.input,
166
+ value: snapshot._stateInputs[stateNode.id],
167
+ boundary: 'state.input',
168
+ logicId: machine.id,
169
+ stateNodeId: stateNode.id
170
+ });
171
+ if (error) {
172
+ return error;
173
+ }
174
+ }
175
+ }
176
+ for (const childId of Object.keys(machine.schemas?.children ?? {})) {
177
+ const child = snapshot.children[childId];
178
+ if (child !== undefined) {
179
+ error = checkTarget({
180
+ schema: machine.schemas.children[childId],
181
+ value: child,
182
+ boundary: 'child',
183
+ logicId: machine.id,
184
+ childId
185
+ });
186
+ if (error) {
187
+ return error;
188
+ }
189
+ }
190
+ }
191
+ for (const timer of snapshot.timers) {
192
+ if (timer.type === '@xstate.raise') {
193
+ error = checkEvent(machine, timer.event, 'raised');
194
+ if (error) {
195
+ return error;
196
+ }
197
+ }
198
+ }
199
+ return undefined;
200
+ };
201
+ return {
202
+ check(request) {
203
+ const {
204
+ logic
205
+ } = request;
206
+ const schemas = getSchemas(logic);
207
+ if (request.kind === 'input') {
208
+ return checkTarget({
209
+ schema: schemas?.input,
210
+ value: request.input,
211
+ boundary: 'input',
212
+ logicId: getLogicId(logic)
213
+ });
214
+ }
215
+ if (request.kind === 'event') {
216
+ return checkEvent(logic, request.event, request.eventOrigin);
217
+ }
218
+ const {
219
+ snapshot,
220
+ effects
221
+ } = request;
222
+ if (isStateMachine(logic)) {
223
+ const error = checkMachineResult(logic, snapshot);
224
+ if (error) {
225
+ return error;
226
+ }
227
+ }
228
+ if (snapshot.status === 'done') {
229
+ const error = checkTarget({
230
+ schema: schemas?.output,
231
+ value: snapshot.output,
232
+ boundary: 'output',
233
+ logicId: getLogicId(logic)
234
+ });
235
+ if (error) {
236
+ return error;
237
+ }
238
+ }
239
+ return checkEmitted(logic, effects);
240
+ }
241
+ };
242
+ }
243
+ function createError(request, reason, issues, cause) {
244
+ return new ActorValidationError({
245
+ reason,
246
+ boundary: request.boundary,
247
+ ...(request.logicId === undefined ? {} : {
248
+ logicId: request.logicId
249
+ }),
250
+ ...(request.stateNodeId === undefined ? {} : {
251
+ stateNodeId: request.stateNodeId
252
+ }),
253
+ ...(request.eventType === undefined ? {} : {
254
+ eventType: request.eventType
255
+ }),
256
+ ...(request.eventOrigin === undefined ? {} : {
257
+ eventOrigin: request.eventOrigin
258
+ }),
259
+ ...(request.childId === undefined ? {} : {
260
+ childId: request.childId
261
+ }),
262
+ ...(issues === undefined ? {} : {
263
+ issues
264
+ }),
265
+ ...(cause === undefined ? {} : {
266
+ cause
267
+ })
268
+ });
269
+ }
270
+ function isStateMachine(logic) {
271
+ return 'root' in logic && 'schemas' in logic;
272
+ }
273
+ function getSchemas(logic) {
274
+ if (isStateMachine(logic)) {
275
+ return logic.schemas;
276
+ }
277
+ return logic.config?.schemas;
278
+ }
279
+ function findEventSchema(schemas, eventType) {
280
+ if (!schemas) {
281
+ return undefined;
282
+ }
283
+ if (Object.hasOwn(schemas, eventType)) {
284
+ return schemas[eventType];
285
+ }
286
+ const descriptor = Object.keys(schemas).find(key => matchesEventDescriptor(eventType, key));
287
+ return descriptor === undefined ? undefined : schemas[descriptor];
288
+ }
289
+ function getLogicId(logic) {
290
+ return 'id' in logic && typeof logic.id === 'string' ? logic.id : undefined;
291
+ }
292
+ function getPayload(event) {
293
+ const {
294
+ type: _,
295
+ ...payload
296
+ } = event;
297
+ return payload;
298
+ }
299
+ function isTypeIssue(issue) {
300
+ const segment = issue.path?.[0];
301
+ return (typeof segment === 'object' ? segment.key : segment) === 'type';
302
+ }
303
+ function getMessage(options) {
304
+ const subject = options.eventType !== undefined ? ` "${options.eventType}"` : options.childId !== undefined ? ` "${options.childId}"` : '';
305
+ switch (options.reason) {
306
+ case 'unknownEvent':
307
+ return `Unknown event${subject}`;
308
+ case 'unknownEmitted':
309
+ return `Unknown emitted event${subject}`;
310
+ case 'asyncValidationUnsupported':
311
+ return `Async schema validation is unsupported for ${options.boundary}${subject}`;
312
+ case 'transformationUnsupported':
313
+ return `Schema transformations are unsupported for ${options.boundary}${subject}`;
314
+ case 'schemaThrew':
315
+ return `Schema threw while validating ${options.boundary}${subject}`;
316
+ case 'invalid':
317
+ return `Invalid ${options.boundary}${subject}`;
318
+ }
319
+ }
320
+ function isPromiseLike(value) {
321
+ return !!value && typeof value.then === 'function';
322
+ }
323
+
324
+ export { ActorValidationError, isActorValidationError, standardSchemaValidator };
@@ -0,0 +1,2 @@
1
+ !function(e,t){"object"==typeof exports&&"undefined"!=typeof module?t(exports):"function"==typeof define&&define.amd?define(["exports"],t):t((e="undefined"!=typeof globalThis?globalThis:e||self).XStateValidation={})}(this,function(e){"use strict";const t=Symbol.for("xstate.actorValidationError");class n extends Error{constructor(e){super(function(e){const t=void 0!==e.eventType?` "${e.eventType}"`:void 0!==e.childId?` "${e.childId}"`:"";switch(e.reason){case"unknownEvent":return`Unknown event${t}`;case"unknownEmitted":return`Unknown emitted event${t}`;case"asyncValidationUnsupported":return`Async schema validation is unsupported for ${e.boundary}${t}`;case"transformationUnsupported":return`Schema transformations are unsupported for ${e.boundary}${t}`;case"schemaThrew":return`Schema threw while validating ${e.boundary}${t}`;case"invalid":return`Invalid ${e.boundary}${t}`}}(e),{cause:e.cause}),this[t]=!0,this.reason=void 0,this.boundary=void 0,this.logicId=void 0,this.stateNodeId=void 0,this.eventType=void 0,this.eventOrigin=void 0,this.childId=void 0,this.issues=void 0,this.cause=void 0,this.name="ActorValidationError",this.reason=e.reason,this.boundary=e.boundary,this.logicId=e.logicId,this.stateNodeId=e.stateNodeId,this.eventType=e.eventType,this.eventOrigin=e.eventOrigin,this.childId=e.childId,this.issues=e.issues,this.cause=e.cause}}function i(e,t,i,o){return new n({reason:t,boundary:e.boundary,...void 0===e.logicId?{}:{logicId:e.logicId},...void 0===e.stateNodeId?{}:{stateNodeId:e.stateNodeId},...void 0===e.eventType?{}:{eventType:e.eventType},...void 0===e.eventOrigin?{}:{eventOrigin:e.eventOrigin},...void 0===e.childId?{}:{childId:e.childId},...void 0===i?{}:{issues:i},...void 0===o?{}:{cause:o}})}function o(e){return"root"in e&&"schemas"in e}function r(e){return o(e)?e.schemas:e.config?.schemas}function s(e,t){if(!e)return;if(Object.hasOwn(e,t))return e[t];const n=Object.keys(e).find(e=>function(e,t){if(t===e)return!0;if("*"===t)return!0;if(!t.endsWith(".*"))return!1;const n=t.split("."),i=e.split(".");for(let e=0;e<n.length;e++){const t=n[e],o=i[e];if("*"===t)return e===n.length-1;if(t!==o)return!1}return!0}(t,e));return void 0===n?void 0:e[n]}function d(e){return"id"in e&&"string"==typeof e.id?e.id:void 0}function a(e){const{type:t,...n}=e;return n}function c(e){const t=e.path?.[0];return"type"===("object"==typeof t?t.key:t)}e.ActorValidationError=n,e.isActorValidationError=function(e){return!(!e||"object"!=typeof e||!(t in e))},e.standardSchemaValidator=function(e={}){const t=e.unknownEvents??"error",n=e.unknownEmitted??"error",u=e=>{if(!e.schema)return"event"===e.boundary&&"error"===t?i(e,"unknownEvent"):"emitted"===e.boundary&&"error"===n?i(e,"unknownEmitted"):void 0;let o;try{o=e.schema["~standard"].validate(e.value)}catch(t){return i(e,"schemaThrew",void 0,t)}return(r=o)&&"function"==typeof r.then?(Promise.resolve(o).catch(()=>{}),i(e,"asyncValidationUnsupported")):o.issues?i(e,"invalid",o.issues):void 0;var r},h=(e,t)=>{const n=u({...e,value:a(t)});return n?.issues?.some(c)?u({...e,value:t}):n},v=(e,t,n)=>{const i=r(e);if(t.type.startsWith("xstate.")||t.type.startsWith("@xstate."))return;const o=i?.events,a=i?.internalEvents,c=s(a,t.type)??s(o,t.type);return o||a?h({schema:c,boundary:"event",logicId:d(e),eventType:t.type,eventOrigin:n},t):void 0};return{check(e){const{logic:t}=e,n=r(t);if("input"===e.kind)return u({schema:n?.input,value:e.input,boundary:"input",logicId:d(t)});if("event"===e.kind)return v(t,e.event,e.eventOrigin);const{snapshot:i,effects:s}=e;if(o(t)){const e=((e,t)=>{let n=u({schema:e.schemas?.context,value:t.context,boundary:"context",logicId:e.id});if(n)return n;for(const i of t.nodes)if(i!==e.root){if(n=u({schema:i.schemas?.context,value:t.context,boundary:"state.context",logicId:e.id,stateNodeId:i.id}),n)return n;if(i.schemas?.input&&(n=u({schema:i.schemas.input,value:t._stateInputs[i.id],boundary:"state.input",logicId:e.id,stateNodeId:i.id}),n))return n}for(const i of Object.keys(e.schemas?.children??{})){const o=t.children[i];if(void 0!==o&&(n=u({schema:e.schemas.children[i],value:o,boundary:"child",logicId:e.id,childId:i}),n))return n}for(const i of t.timers)if("@xstate.raise"===i.type&&(n=v(e,i.event,"raised"),n))return n})(t,i);if(e)return e}if("done"===i.status){const e=u({schema:n?.output,value:i.output,boundary:"output",logicId:d(t)});if(e)return e}return((e,t)=>{const n=r(e);if(n?.emitted)for(const i of t){if("emit"!==i.kind)continue;const t=h({schema:n.emitted[i.event.type],boundary:"emitted",logicId:d(e),eventType:i.event.type},i.event);if(t)return t}})(t,s)}}},Object.defineProperty(e,"__esModule",{value:!0})});
2
+ //# sourceMappingURL=xstate-validation.umd.min.js.map