@tinyactors/node 0.1.0 → 0.3.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 (43) hide show
  1. package/README.md +648 -154
  2. package/docs/guide/browser.md +494 -0
  3. package/docs/guide/capacity.md +202 -0
  4. package/docs/guide/charts.md +578 -0
  5. package/docs/guide/hibernation.md +201 -0
  6. package/docs/guide/inspection.md +381 -0
  7. package/docs/guide/io-processors.md +269 -0
  8. package/docs/guide/migration.md +323 -0
  9. package/docs/guide/other-systems.md +275 -0
  10. package/docs/guide/quickjs.md +135 -0
  11. package/docs/guide/services.md +317 -0
  12. package/docs/guide/snapshots.md +186 -0
  13. package/docs/guide/telemetry.md +265 -0
  14. package/docs/guide/testing.md +272 -0
  15. package/docs/values.md +107 -0
  16. package/index.d.ts +1166 -1820
  17. package/index.mjs +6 -0
  18. package/lib/convenience.mjs +162 -0
  19. package/lib/direct.mjs +65 -0
  20. package/package.json +29 -16
  21. package/index.js +0 -34
  22. package/lib/actor.js +0 -85
  23. package/lib/debug/breakpoints.js +0 -349
  24. package/lib/debug/console.js +0 -149
  25. package/lib/debug/expressions.js +0 -133
  26. package/lib/debug/frames.js +0 -119
  27. package/lib/debug/labels.js +0 -142
  28. package/lib/debug/macrosteps.js +0 -207
  29. package/lib/debug/protocol.js +0 -186
  30. package/lib/debug/sources.js +0 -218
  31. package/lib/debug/variables.js +0 -265
  32. package/lib/debug.js +0 -1434
  33. package/lib/definition.js +0 -139
  34. package/lib/errors.js +0 -24
  35. package/lib/events.js +0 -56
  36. package/lib/image.js +0 -90
  37. package/lib/loader.js +0 -68
  38. package/lib/metrics.js +0 -333
  39. package/lib/native.js +0 -8
  40. package/lib/otlp.js +0 -332
  41. package/lib/statechart.js +0 -768
  42. package/lib/system.js +0 -2183
  43. package/lib/tracing.js +0 -164
package/lib/statechart.js DELETED
@@ -1,768 +0,0 @@
1
- 'use strict';
2
-
3
- // The fluent statechart builder (docs/design.md, "Fluent authoring"). It
4
- // emits the generated spec shape directly (ADR 0013 point 6): the same shape
5
- // `System.define()` accepts as a plain object and core's definition export
6
- // returns. There is no separate normalization step.
7
- //
8
- // Expressions are JavaScript (ADR 0011): a function is an expression (a
9
- // condition, a value or a script) called with `this` bound to the actor's
10
- // data and one argument, the evaluation context. A value that is not a
11
- // function is data, and literal() makes a function data too. A location is
12
- // a declared data name, or an object with `get` and `set`. Source text is
13
- // accepted only as `In(state)` conditions and data names. Every builder
14
- // chart compiles against the JavaScript data model.
15
-
16
- const native = require('./native');
17
- const { TinyactorsError } = require('./errors');
18
- const { Definition } = require('./definition');
19
-
20
- function isDefinition(value) {
21
- return value instanceof Definition;
22
- }
23
-
24
- const literalBrand = Symbol('tinyactors.literal');
25
- native.setupLiteral(literalBrand);
26
-
27
- /** Force a callable JavaScript value to be data rather than an expression. */
28
- function literal(value) {
29
- return Object.freeze({ [literalBrand]: true, value });
30
- }
31
-
32
- function isLiteral(value) {
33
- return value !== null && typeof value === 'object' && value[literalBrand] === true;
34
- }
35
-
36
- const contentBrand = Symbol('tinyactors.content');
37
-
38
- /**
39
- * Literal SCXML <content>: text or bytes kept in the definition, with an
40
- * optional media type. The bytes are copied.
41
- */
42
- function content(body, options = {}) {
43
- let bytes;
44
- if (typeof body === 'string') {
45
- bytes = new TextEncoder().encode(body);
46
- } else if (body instanceof Uint8Array) {
47
- bytes = new Uint8Array(body);
48
- } else {
49
- throw invalid('content(): expected a string or a Uint8Array');
50
- }
51
- const mediaType = options?.mediaType;
52
- if (mediaType !== undefined && (typeof mediaType !== 'string' || mediaType.length === 0)) {
53
- throw invalid('content(): mediaType must be a non-empty string');
54
- }
55
- return Object.freeze(mediaType === undefined ? { [contentBrand]: true, bytes }
56
- : { [contentBrand]: true, bytes, mediaType });
57
- }
58
-
59
- function isContent(value) {
60
- return value !== null && typeof value === 'object' && value[contentBrand] === true;
61
- }
62
-
63
- function isLocation(value) {
64
- return value !== null && typeof value === 'object' && !isLiteral(value) &&
65
- typeof value.get === 'function' && typeof value.set === 'function';
66
- }
67
-
68
- function invalid(message) {
69
- return new TinyactorsError(message, 'invalid');
70
- }
71
-
72
- function text(value, what) {
73
- if (typeof value !== 'string' || value.length === 0) {
74
- throw invalid(`${what}: expected a non-empty string`);
75
- }
76
- return value;
77
- }
78
-
79
- // An expression: a function, a literal(), or source text (In(state) or a
80
- // data name).
81
- function expression(value, what) {
82
- if (typeof value === 'function' || isLiteral(value)) {
83
- return value;
84
- }
85
- return text(value, what);
86
- }
87
-
88
- // A location: a data name, or an object with get and set.
89
- function location(value, what) {
90
- if (isLocation(value)) {
91
- return value;
92
- }
93
- return text(value, what);
94
- }
95
-
96
- // A value source: a function is evaluated, content() is literal content,
97
- // anything else is data.
98
- function valueSpec(value) {
99
- if (isContent(value)) {
100
- const { bytes, mediaType } = value;
101
- return { kind: 'content', content: mediaType === undefined ? { bytes } : { media_type: mediaType, bytes } };
102
- }
103
- if (typeof value === 'function' || isLiteral(value)) {
104
- return { kind: 'expr', expr: value };
105
- }
106
- return { kind: 'expr', expr: literal(value) };
107
- }
108
-
109
- function targets(value, what) {
110
- const list = typeof value === 'string' ? value.split(/\s+/).filter(Boolean) : value;
111
- if (!Array.isArray(list) || list.length === 0) {
112
- throw invalid(`${what}: expected a state ID or a non-empty list of state IDs`);
113
- }
114
- return list.map((target, index) => text(target, `${what}[${index}]`));
115
- }
116
-
117
- // A literal/expression attribute pair (`x` / `xexpr`).
118
- function stringSpec(value, what) {
119
- if (typeof value === 'function') {
120
- return { kind: 'expr', expr: value };
121
- }
122
- return { kind: 'literal', literal: text(value, what) };
123
- }
124
-
125
- // A number of milliseconds becomes an SCXML duration, for literals and for
126
- // what a delay function returns.
127
- function duration(value) {
128
- return typeof value === 'number' ? `${value}ms` : value;
129
- }
130
-
131
- function delaySpec(value, what) {
132
- if (typeof value === 'number') {
133
- if (!Number.isFinite(value) || value < 0) {
134
- throw invalid(`${what}: expected a non-negative number of milliseconds`);
135
- }
136
- return { kind: 'literal', literal: `${value}ms` };
137
- }
138
- if (typeof value === 'function') {
139
- const delay = value;
140
- return {
141
- kind: 'expr',
142
- expr: function delayInMilliseconds(context) {
143
- return duration(delay.call(this, context));
144
- },
145
- };
146
- }
147
- return stringSpec(value, what);
148
- }
149
-
150
- // An `id` / `idlocation` pair.
151
- function idLocation(value, what) {
152
- return { kind: 'location', location: location(value, what) };
153
- }
154
-
155
- // Where a builder call was written (core ADR 0085): the first stack frame
156
- // outside this file, as V8 reports it. Structured call sites cost less than
157
- // formatting and parsing a stack string, and ten frames are enough to leave
158
- // this file's own helpers.
159
- const structured = (_, frames) => frames;
160
-
161
- function callSite() {
162
- const { prepareStackTrace, stackTraceLimit } = Error;
163
- Error.prepareStackTrace = structured;
164
- Error.stackTraceLimit = 6;
165
- const holder = {};
166
- Error.captureStackTrace(holder, callSite);
167
- const frames = holder.stack;
168
- Error.prepareStackTrace = prepareStackTrace;
169
- Error.stackTraceLimit = stackTraceLimit;
170
- if (!Array.isArray(frames)) {
171
- return undefined;
172
- }
173
- const frame = frames.find((each) => {
174
- const file = each.getFileName();
175
- return file !== null && file !== undefined && file !== __filename;
176
- });
177
- return frame === undefined ? undefined : { file: frame.getFileName(), line: frame.getLineNumber(), column: frame.getColumnNumber() };
178
- }
179
-
180
- // One builder tree shares one root: once build() or System.define() has
181
- // consumed it, every builder in the tree refuses changes. The root also
182
- // holds the spec's spans: where each state, transition, initial transition
183
- // and action was written, with the JavaScript files as the sources.
184
- class Root {
185
- constructor() {
186
- this.consumed = false;
187
- this.spans = [];
188
- this.sources = new Map();
189
- }
190
-
191
- check() {
192
- if (this.consumed) {
193
- throw invalid('this statechart builder was already built; start a new one with statechart()');
194
- }
195
- }
196
-
197
- // The span of the builder call being evaluated: its index into the spec's
198
- // spans, from 1, or undefined when the stack says nothing.
199
- span() {
200
- const site = callSite();
201
- if (site === undefined || !(site.line > 0)) {
202
- return undefined;
203
- }
204
- let source = this.sources.get(site.file);
205
- if (source === undefined) {
206
- source = this.sources.size;
207
- this.sources.set(site.file, source);
208
- }
209
- this.spans.push({ source, line: site.line, column: site.column });
210
- return this.spans.length;
211
- }
212
-
213
- // The spec's spans and sources, or nothing when no call was located.
214
- located() {
215
- if (this.spans.length === 0) {
216
- return {};
217
- }
218
- return { spans: this.spans, sources: [...this.sources.keys()].map((name) => ({ name })) };
219
- }
220
- }
221
-
222
- // Sets `span` on an element when the call that wrote it was located.
223
- function located(root, element) {
224
- const span = root.span();
225
- if (span !== undefined) {
226
- element.span = span;
227
- }
228
- return element;
229
- }
230
-
231
- function block(root, build, what) {
232
- if (typeof build !== 'function') {
233
- throw invalid(`${what}: expected a function that receives the builder`);
234
- }
235
- const actions = new ActionBuilder(root);
236
- build(actions);
237
- return actions.actions;
238
- }
239
-
240
- // Actions shared by transitions, handlers, initial transitions and
241
- // <finalize>. Each method appends one action spec to `this.actions`.
242
- class ActionSequenceBuilder {
243
- #root;
244
-
245
- constructor(root) {
246
- this.#root = root;
247
- this.actions = [];
248
- }
249
-
250
- #push(action) {
251
- this.#root.check();
252
- this.actions.push(located(this.#root, action));
253
- return this;
254
- }
255
-
256
- raise(event, data) {
257
- const raise = { event: text(event, 'raise event') };
258
- if (data !== undefined) {
259
- raise.data = valueSpec(data);
260
- }
261
- return this.#push({ kind: 'raise', raise });
262
- }
263
-
264
- send(event, build) {
265
- this.#root.check();
266
- const send = {
267
- event: typeof event === 'function' ? { kind: 'expr', expr: event } : { kind: 'name', name: text(event, 'send event') },
268
- };
269
- if (build !== undefined) {
270
- if (typeof build !== 'function') {
271
- throw invalid('send(): expected a function that receives the send builder');
272
- }
273
- build(new SendBuilder(this.#root, send));
274
- }
275
- return this.#push({ kind: 'send', send });
276
- }
277
-
278
- cancel(sendID) {
279
- return this.#push({ kind: 'cancel', cancel: { sendid: stringSpec(sendID, 'cancel send ID') } });
280
- }
281
-
282
- log(label, value) {
283
- const log = {};
284
- if (label !== undefined) {
285
- log.label = text(label, 'log label');
286
- }
287
- if (value !== undefined) {
288
- log.expr = expression(value, 'log value');
289
- }
290
- return this.#push({ kind: 'log', log });
291
- }
292
-
293
- choose(condition, then, otherwise) {
294
- this.#root.check();
295
- const conditional = {
296
- condition: expression(condition, 'choose() condition'),
297
- then_actions: block(this.#root, then, 'choose() then'),
298
- };
299
- if (otherwise !== undefined) {
300
- conditional.else_actions = block(this.#root, otherwise, 'choose() otherwise');
301
- }
302
- return this.#push({ kind: 'if', conditional });
303
- }
304
-
305
- /** Assign a declared top-level data property. */
306
- assign(name, value) {
307
- return this.#push({ kind: 'assign', assign: { location: text(name, 'assign() location'), value: valueSpec(value) } });
308
- }
309
-
310
- /** Assign through an explicit { get, set } location. */
311
- assignAt(at, value) {
312
- if (!isLocation(at)) {
313
- throw invalid('assignAt(): expected a location with get and set functions');
314
- }
315
- return this.#push({ kind: 'assign', assign: { location: at, value: valueSpec(value) } });
316
- }
317
-
318
- /** Run a synchronous function with `this` bound to the actor's data. */
319
- script(run) {
320
- if (typeof run !== 'function') {
321
- throw invalid('script(): expected a function');
322
- }
323
- return this.#push({ kind: 'script', script: { script: run } });
324
- }
325
-
326
- /**
327
- * Run `build`'s actions once per element of a snapshot of `array`, with
328
- * data property `item` bound to the element and `index` to its index.
329
- */
330
- forEach(array, item, build, index) {
331
- this.#root.check();
332
- const foreach = {
333
- array: expression(array, 'forEach() array'),
334
- item: text(item, 'forEach() item'),
335
- body: block(this.#root, build, 'forEach() body'),
336
- };
337
- if (index !== undefined) {
338
- foreach.index = text(index, 'forEach() index');
339
- }
340
- return this.#push({ kind: 'foreach', foreach });
341
- }
342
- }
343
-
344
- class ActionBuilder extends ActionSequenceBuilder {}
345
-
346
- class SendBuilder {
347
- #root;
348
- #send;
349
-
350
- constructor(root, send) {
351
- this.#root = root;
352
- this.#send = send;
353
- }
354
-
355
- #set(member, value) {
356
- this.#root.check();
357
- this.#send[member] = value;
358
- return this;
359
- }
360
-
361
- to(target) {
362
- return this.#set('target', stringSpec(target, 'send target'));
363
- }
364
-
365
- via(ioType) {
366
- return this.#set('type', stringSpec(ioType, 'send I/O processor type'));
367
- }
368
-
369
- after(delay) {
370
- return this.#set('delay', delaySpec(delay, 'send delay'));
371
- }
372
-
373
- id(id) {
374
- return this.#set('id', { kind: 'literal', literal: text(id, 'send ID') });
375
- }
376
-
377
- idLocation(at) {
378
- return this.#set('id', idLocation(at, 'send idLocation'));
379
- }
380
-
381
- data(value) {
382
- return this.#set('data', valueSpec(value));
383
- }
384
-
385
- param(name, value) {
386
- this.#root.check();
387
- (this.#send.params ??= []).push({ name: text(name, 'send param name'), value: valueSpec(value) });
388
- return this;
389
- }
390
- }
391
-
392
- class TransitionBuilder extends ActionSequenceBuilder {
393
- #root;
394
-
395
- constructor(root, transition) {
396
- super(root);
397
- this.#root = root;
398
- this.transition = transition;
399
- }
400
-
401
- when(condition) {
402
- this.#root.check();
403
- this.transition.condition = expression(condition, 'transition condition');
404
- return this;
405
- }
406
-
407
- target(target) {
408
- this.#root.check();
409
- this.transition.targets = targets(target, 'transition target');
410
- return this;
411
- }
412
-
413
- internal() {
414
- this.#root.check();
415
- this.transition.kind = 'internal';
416
- return this;
417
- }
418
-
419
- external() {
420
- this.#root.check();
421
- this.transition.kind = 'external';
422
- return this;
423
- }
424
- }
425
-
426
- class InvokeBuilder {
427
- #root;
428
- #invoke;
429
-
430
- constructor(root, invoke) {
431
- this.#root = root;
432
- this.#invoke = invoke;
433
- }
434
-
435
- #set(member, value) {
436
- this.#root.check();
437
- this.#invoke[member] = value;
438
- return this;
439
- }
440
-
441
- id(id) {
442
- return this.#set('id', { kind: 'literal', literal: text(id, 'invoke ID') });
443
- }
444
-
445
- idLocation(at) {
446
- return this.#set('id', idLocation(at, 'invoke idLocation'));
447
- }
448
-
449
- type(type) {
450
- return this.#set('type', stringSpec(type, 'invoke type'));
451
- }
452
-
453
- source(source) {
454
- return this.#set('src', stringSpec(source, 'invoke source'));
455
- }
456
-
457
- // A Definition as content names the child of the in-system SCXML invoker:
458
- // it is carried as its ID (adapters/invoker.h).
459
- content(value) {
460
- return this.#set('data', valueSpec(isDefinition(value) ? value.id : value));
461
- }
462
-
463
- param(name, value) {
464
- this.#root.check();
465
- (this.#invoke.params ??= []).push({ name: text(name, 'invoke param name'), value: valueSpec(value) });
466
- return this;
467
- }
468
-
469
- autoforward(enabled = true) {
470
- if (typeof enabled !== 'boolean') {
471
- throw invalid('autoforward(): expected a boolean');
472
- }
473
- return this.#set('autoforward', enabled);
474
- }
475
-
476
- finalize(build) {
477
- return this.#set('finalize', block(this.#root, build, 'invoke finalize()'));
478
- }
479
- }
480
-
481
- // data(name, value): the value is data even when it is a function.
482
- function literalOf(value) {
483
- return isLiteral(value) || isContent(value) ? value : literal(value);
484
- }
485
-
486
- function functionSpec(value, what) {
487
- if (typeof value !== 'function') {
488
- throw invalid(`${what}: expected a function`);
489
- }
490
- return { kind: 'expr', expr: value };
491
- }
492
-
493
- function dataSpec(name, initializer) {
494
- const data = { name: text(name, 'data name') };
495
- if (initializer !== undefined) {
496
- data.initializer = initializer;
497
- }
498
- return data;
499
- }
500
-
501
- class DoneDataBuilder {
502
- #root;
503
- #done;
504
-
505
- constructor(root, done) {
506
- this.#root = root;
507
- this.#done = done;
508
- }
509
-
510
- content(value) {
511
- this.#root.check();
512
- this.#done.content = valueSpec(value);
513
- return this;
514
- }
515
-
516
- param(name, value) {
517
- this.#root.check();
518
- (this.#done.params ??= []).push({ name: text(name, 'doneData param name'), value: valueSpec(value) });
519
- return this;
520
- }
521
- }
522
-
523
- function initialSpec(root, target, actions) {
524
- const initial = located(root, { targets: targets(target, 'initial target') });
525
- if (actions !== undefined) {
526
- initial.actions = block(root, actions, 'initial actions');
527
- }
528
- return initial;
529
- }
530
-
531
- // Methods that add child states. `this.states` holds the child specs.
532
- class StateContainerBuilder {
533
- #root;
534
-
535
- constructor(root) {
536
- this.#root = root;
537
- this.states = [];
538
- }
539
-
540
- #child(kind, id, build, what) {
541
- this.#root.check();
542
- const state = new StateBuilder(this.#root, kind, text(id, `${what} ID`), this.#root.span());
543
- if (build !== undefined) {
544
- if (typeof build !== 'function') {
545
- throw invalid(`${what}(): expected a function that receives the state builder`);
546
- }
547
- build(state);
548
- }
549
- this.states.push(state.finish());
550
- return this;
551
- }
552
-
553
- state(id, build) {
554
- return this.#child(undefined, id, build, 'state');
555
- }
556
-
557
- parallel(id, build) {
558
- return this.#child('parallel', id, build, 'parallel');
559
- }
560
-
561
- final(id, build) {
562
- return this.#child('final', id, build, 'final');
563
- }
564
-
565
- history(id, depth, build) {
566
- if (depth !== 'shallow' && depth !== 'deep') {
567
- throw invalid('history(): depth must be "shallow" or "deep"');
568
- }
569
- return this.#child(`history_${depth}`, id, build, 'history');
570
- }
571
- }
572
-
573
- const stateKinds = new Set(['atomic', 'compound', 'parallel', 'final', 'history_shallow', 'history_deep']);
574
-
575
- class StateBuilder extends StateContainerBuilder {
576
- #root;
577
- #kind;
578
- #spec;
579
-
580
- constructor(root, kind, id, span) {
581
- super(root);
582
- this.#root = root;
583
- this.#kind = kind;
584
- this.#spec = { kind: undefined, id };
585
- if (span !== undefined) {
586
- this.#spec.span = span;
587
- }
588
- }
589
-
590
- #list(member, value) {
591
- this.#root.check();
592
- (this.#spec[member] ??= []).push(value);
593
- return this;
594
- }
595
-
596
- /** Override the kind normally inferred from the builder method and children. */
597
- kind(kind) {
598
- this.#root.check();
599
- if (!stateKinds.has(kind)) {
600
- throw invalid(`kind(): expected one of ${[...stateKinds].join(', ')}`);
601
- }
602
- this.#kind = kind;
603
- return this;
604
- }
605
-
606
- initial(target, actions) {
607
- this.#root.check();
608
- this.#spec.initial = initialSpec(this.#root, target, actions);
609
- return this;
610
- }
611
-
612
- /** Declare data property `name` with `initial` as data (a function too: use dataExpression). */
613
- data(name, initial) {
614
- return this.#list('data', dataSpec(name, initial === undefined ? undefined : valueSpec(literalOf(initial))));
615
- }
616
-
617
- /** Declare data property `name`, initialized by calling `initial`. */
618
- dataExpression(name, initial) {
619
- return this.#list('data', dataSpec(name, functionSpec(initial, 'dataExpression()')));
620
- }
621
-
622
- entry(build) {
623
- return this.#list('onentry', { actions: block(this.#root, build, 'entry()') });
624
- }
625
-
626
- exit(build) {
627
- return this.#list('onexit', { actions: block(this.#root, build, 'exit()') });
628
- }
629
-
630
- on(event, build) {
631
- return this.#transition({ kind: 'external', event: text(event, 'transition event') }, build, 'on()');
632
- }
633
-
634
- always(build) {
635
- if (typeof build !== 'function') {
636
- throw invalid('always(): expected a function that receives the transition builder');
637
- }
638
- return this.#transition({ kind: 'external' }, build, 'always()');
639
- }
640
-
641
- #transition(transition, build, what) {
642
- this.#root.check();
643
- located(this.#root, transition);
644
- if (build !== undefined) {
645
- if (typeof build !== 'function') {
646
- throw invalid(`${what}: expected a function that receives the transition builder`);
647
- }
648
- const builder = new TransitionBuilder(this.#root, transition);
649
- build(builder);
650
- if (builder.actions.length > 0) {
651
- transition.actions = builder.actions;
652
- }
653
- }
654
- return this.#list('transitions', transition);
655
- }
656
-
657
- invoke(build) {
658
- this.#root.check();
659
- if (typeof build !== 'function') {
660
- throw invalid('invoke(): expected a function that receives the invoke builder');
661
- }
662
- const invoke = { kind: 'invoke' };
663
- build(new InvokeBuilder(this.#root, invoke));
664
- return this.#list('invokes', invoke);
665
- }
666
-
667
- /** The data a final state reports on completion: content(), or param()s. */
668
- doneData(build) {
669
- this.#root.check();
670
- if (typeof build !== 'function') {
671
- throw invalid('doneData(): expected a function that receives the done-data builder');
672
- }
673
- const done = {};
674
- build(new DoneDataBuilder(this.#root, done));
675
- this.#spec.done_data = done;
676
- return this;
677
- }
678
-
679
- // The finished spec. An unspecified kind is compound with children, and
680
- // atomic without.
681
- finish() {
682
- const spec = this.#spec;
683
- spec.kind = this.#kind ?? (this.states.length > 0 ? 'compound' : 'atomic');
684
- if (this.states.length > 0) {
685
- spec.states = this.states;
686
- }
687
- return spec;
688
- }
689
- }
690
-
691
- class DefinitionBuilder extends StateContainerBuilder {
692
- #root;
693
- #spec;
694
-
695
- constructor(options) {
696
- const root = new Root();
697
- super(root);
698
- this.#root = root;
699
- if (options === null || typeof options !== 'object') {
700
- throw invalid('statechart(): expected an options object with family and revision');
701
- }
702
- const { family, revision, name, binding } = options;
703
- if (typeof revision !== 'string' && !(revision instanceof Uint8Array)) {
704
- throw invalid('statechart(): revision must be a string or a Uint8Array');
705
- }
706
- this.#spec = { identity: { family: { name: text(family, 'statechart() family') }, revision } };
707
- if (name !== undefined) {
708
- this.#spec.name = text(name, 'statechart() name');
709
- }
710
- if (binding !== undefined) {
711
- if (binding !== 'early' && binding !== 'late') {
712
- throw invalid('statechart(): binding must be "early" or "late"');
713
- }
714
- this.#spec.binding = binding;
715
- }
716
- }
717
-
718
- /** Declare top-level data property `name` with `initial` as data. */
719
- data(name, initial) {
720
- this.#root.check();
721
- (this.#spec.data ??= []).push(dataSpec(name, initial === undefined ? undefined : valueSpec(literalOf(initial))));
722
- return this;
723
- }
724
-
725
- /** Declare top-level data property `name`, initialized by calling `initial`. */
726
- dataExpression(name, initial) {
727
- this.#root.check();
728
- (this.#spec.data ??= []).push(dataSpec(name, functionSpec(initial, 'dataExpression()')));
729
- return this;
730
- }
731
-
732
- /** A script run once at initialization, after early-bound data (SCXML 3.2.2). */
733
- script(run) {
734
- this.#root.check();
735
- if (typeof run !== 'function') {
736
- throw invalid('script(): expected a function');
737
- }
738
- this.#spec.script = run;
739
- const span = this.#root.span();
740
- if (span !== undefined) {
741
- this.#spec.script_span = span;
742
- }
743
- return this;
744
- }
745
-
746
- initial(target, actions) {
747
- this.#root.check();
748
- this.#spec.initial = initialSpec(this.#root, target, actions);
749
- return this;
750
- }
751
-
752
- /** The spec in the generated shape, with its spans. Consumes the builder. */
753
- build() {
754
- this.#root.check();
755
- this.#root.consumed = true;
756
- return { ...this.#spec, states: this.states, ...this.#root.located() };
757
- }
758
- }
759
-
760
- /**
761
- * Begin an ordered statechart definition. The builder is mutable until
762
- * build() or System.define() consumes it.
763
- */
764
- function statechart(options) {
765
- return new DefinitionBuilder(options);
766
- }
767
-
768
- module.exports = { statechart, literal, content, isLiteral, DefinitionBuilder, literalBrand };