@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
@@ -0,0 +1,578 @@
1
+ # Writing charts
2
+
3
+ A chart is an SCXML document whose data and expressions are JavaScript.
4
+ This guide covers what a chart can hold on this package's datamodel: the
5
+ variables and expressions, scripts, XML data, how several charts become
6
+ one image, a chart that starts another, and a system that starts its
7
+ actors itself. The README's [Concepts](../../README.md#concepts) come
8
+ first.
9
+
10
+ ## Variables and expressions
11
+
12
+ A chart's variables are its `<data>` elements. Each `expr` is evaluated
13
+ once, when the actor starts, unless `spawn`'s `params` give the variable
14
+ another value ([README](../../README.md#starting-an-actor-with-data)).
15
+ Every expression in the chart (`cond`, `expr`, `<log expr>`, `<script>`)
16
+ sees the variables by name, plus these:
17
+
18
+ | Name | What it holds |
19
+ |---|---|
20
+ | `_event` | the event being handled: `name`, `data`, `type` (`'external'`, `'internal'` or `'platform'`), `sendid`, `origin`, `origintype`, `invokeid`, and `raw` when an I/O processor's answer gave one |
21
+ | `_sessionid` | the actor's session, as a string |
22
+ | `_name` | the actor's name, or its chart's name when it has none |
23
+ | `_ioprocessors` | the I/O processors, by type; `_ioprocessors.scxml.location` is the actor's address |
24
+ | `In(id)` | whether state `id` is active |
25
+
26
+ An expression is ordinary JavaScript: arrow functions, template strings,
27
+ `JSON.stringify`, methods of arrays and strings. It cannot assign to a
28
+ name the chart does not declare, nor to `_event` or the system variables:
29
+ that raises `error.execution`, as an expression that throws does.
30
+
31
+ ```js
32
+ import { compileCharts, Host } from '@tinyactors/node';
33
+
34
+ const chart = `
35
+ <scxml xmlns="http://www.w3.org/2005/07/scxml" version="1.0"
36
+ datamodel="ecmascript" name="thermostat" initial="running">
37
+ <datamodel>
38
+ <data id="readings" expr="[]"/>
39
+ <data id="target" expr="20"/>
40
+ </datamodel>
41
+ <parallel id="running">
42
+ <state id="heater" initial="off">
43
+ <state id="off">
44
+ <onentry><log expr="'heater off'"/></onentry>
45
+ <transition event="reading" cond="_event.data.celsius &lt; target" target="on"/>
46
+ </state>
47
+ <state id="on">
48
+ <onentry><log expr="'heater on'"/></onentry>
49
+ <transition event="reading" cond="_event.data.celsius &gt;= target" target="off"/>
50
+ </state>
51
+ </state>
52
+ <state id="recorder">
53
+ <transition event="reading">
54
+ <assign location="readings" expr="[...readings, _event.data.celsius].slice(-3)"/>
55
+ <log expr="_event.data.celsius + '°C, last ' + readings.join(' ') + ', heating: ' + In('on')"/>
56
+ </transition>
57
+ <transition event="typo"><assign location="tagret" expr="21"/></transition>
58
+ <transition event="error.execution"><log expr="'that was an error.execution'"/></transition>
59
+ </state>
60
+ </parallel>
61
+ </scxml>`;
62
+
63
+ const compiled = compileCharts([{ name: 'thermostat.scxml', text: chart }]);
64
+ const host = new Host({ systemID: 'home' }, { log: (host, entry) => console.log(entry.text) });
65
+ host.addImage(compiled.image);
66
+ compiled.close();
67
+
68
+ const thermostat = host.spawn(host.chart('thermostat'));
69
+ for (const celsius of [18, 19, 21]) host.send(thermostat, 'reading', { celsius });
70
+ host.send(thermostat, 'typo');
71
+ await host.idle();
72
+ host.close();
73
+ ```
74
+
75
+ ```output
76
+ heater off
77
+ 18°C, last 18, heating: false
78
+ heater on
79
+ 19°C, last 18 19, heating: true
80
+ 21°C, last 18 19 21, heating: false
81
+ heater off
82
+ that was an error.execution
83
+ ```
84
+
85
+ XML needs `&lt;` for `<` and `&amp;` for `&` inside an attribute. The
86
+ `<parallel>` holds two regions, both active at once, and a `reading`
87
+ event is handled by both, in one step: the states a transition leaves
88
+ are exited first, then every transition's actions run, then the new
89
+ states are entered. So `In('on')` in the recorder is true only when the
90
+ heater stays on: at 18°C the heater is turning on, and the recorder logs
91
+ `heating: false` before the heater's `heater on`. The `typo` event assigns to
92
+ `tagret`, which the chart never declared.
93
+
94
+ ## Scripts
95
+
96
+ `<script>` runs statements: in a transition, in `<onentry>`, or at the top
97
+ of the chart, once when an actor starts. A chart-level script is where a
98
+ chart's helper functions go, and how it declares them decides what each
99
+ actor costs.
100
+
101
+ **A script in a transition, `<onentry>` or `<onexit>` runs in a block**,
102
+ as a function body would: its top-level `let`, `const` and `class` are
103
+ its own at each run, so it runs again and again, and they declare nothing
104
+ for the chart. Its `var`s are the actor's, as a chart-level script's are.
105
+
106
+ **A script that declares nothing** (no top-level `var`, `function`,
107
+ `let`, `const` or `class` in a chart-level script, no `var` or `function`
108
+ in one in executable content) runs in a context the host shares between the
109
+ actors of every such chart. Hold a helper function in a `<data>` and
110
+ assign it:
111
+
112
+ ```js
113
+ import { compileCharts, Host } from '@tinyactors/node';
114
+
115
+ const chart = `
116
+ <scxml xmlns="http://www.w3.org/2005/07/scxml" version="1.0"
117
+ datamodel="ecmascript" name="basket" initial="open">
118
+ <datamodel>
119
+ <data id="items" expr="[]"/>
120
+ <data id="price"/>
121
+ </datamodel>
122
+ <script>
123
+ price = (sku) => ({ tea: 4, cake: 7 })[sku] ?? 0;
124
+ </script>
125
+ <state id="open">
126
+ <transition event="add"><script>items.push(_event.data.sku)</script></transition>
127
+ <transition event="checkout" target="closed">
128
+ <log expr="'total ' + items.map(price).reduce((a, b) => a + b, 0)"/>
129
+ </transition>
130
+ </state>
131
+ <final id="closed"/>
132
+ </scxml>`;
133
+
134
+ const compiled = compileCharts([{ name: 'basket.scxml', text: chart }]);
135
+ const host = new Host({ systemID: 'shop' }, { log: (host, entry) => console.log(entry.text) });
136
+ host.addImage(compiled.image);
137
+ compiled.close();
138
+
139
+ const basket = host.spawn(host.chart('basket'));
140
+ for (const sku of ['tea', 'cake', 'tea']) host.send(basket, 'add', { sku });
141
+ host.send(basket, 'checkout');
142
+ await host.idle();
143
+ host.close();
144
+ ```
145
+
146
+ ```output
147
+ total 15
148
+ ```
149
+
150
+ **A script that declares top-level names** (`function price(sku) {...}`)
151
+ gets a `vm` context for each actor, where the script runs as global code
152
+ and its functions close over its own variables, as they would in a file.
153
+ That costs about 143 KB an actor on Node.js and 60 KB on Bun, so keep it
154
+ for charts with few actors. Such a chart's actors can still be
155
+ hibernated, migrated and snapshotted when it declares with `var` and
156
+ `function`; one that declares with `let`, `const` or `class` keeps its
157
+ actors in memory, because a new context cannot be given those bindings
158
+ back.
159
+
160
+ A function held in a variable keeps its actor in memory too: hibernation
161
+ stores the variables as values, and a function is not one. So the
162
+ `basket` above cannot be hibernated, while a chart that declares its
163
+ helpers with `function` in a script can, at the cost of its context.
164
+
165
+ ## Sending events
166
+
167
+ `<send>` is how an actor talks to anything: itself, another actor, an I/O
168
+ processor, a service. Its attributes, each with an `...expr` form that
169
+ computes it:
170
+
171
+ | Attribute | What it gives | Default |
172
+ |---|---|---|
173
+ | `event`, `eventexpr` | the event's name | required |
174
+ | `target`, `targetexpr` | where it goes: an address, `#_scxml_<session>`, `#_parent`, `#_<invokeid>`, `#_internal` | the actor itself, at the back of its queue |
175
+ | `type`, `typeexpr` | the I/O processor ([I/O processors](io-processors.md)) | SCXML's own, between actors |
176
+ | `id`, `idlocation` | the send's id, for `<cancel>` and the answer's `_event.sendid`; `idlocation` names a declared `<data>` that gets a generated id, unique in the actor's session only (every session's first is `send.1`) | none |
177
+ | `delay`, `delayexpr` | when: `500ms`, `1.5s`, `30s` | now |
178
+ | `namelist` | variables whose names and values become the data | none |
179
+
180
+ The data is `<param name expr>`s and `namelist` (an object), or one
181
+ `<content expr>` (any value). `#_internal` puts the event in the actor's
182
+ internal queue, which runs before anything waiting outside, as `<raise>`
183
+ does.
184
+
185
+ ```js
186
+ import { compileCharts, Host } from '@tinyactors/node';
187
+
188
+ const sender = `
189
+ <scxml xmlns="http://www.w3.org/2005/07/scxml" version="1.0"
190
+ datamodel="ecmascript" name="sender" initial="s">
191
+ <datamodel>
192
+ <data id="qty" expr="2"/>
193
+ <data id="sku" expr="'tea'"/>
194
+ <data id="lastid"/>
195
+ <data id="peer" expr="'#_scxml_2'"/>
196
+ </datamodel>
197
+ <state id="s">
198
+ <onentry>
199
+ <send event="self.order" namelist="qty sku" idlocation="lastid"/>
200
+ <send event="self.note" target="#_internal"/>
201
+ <send eventexpr="'hello.' + sku" targetexpr="peer"/>
202
+ <log expr="'the order went out as ' + lastid"/>
203
+ </onentry>
204
+ <transition event="self.*"><log expr="_event.name + ' (' + _event.type + ') ' + JSON.stringify(_event.data)"/></transition>
205
+ </state>
206
+ </scxml>`;
207
+ const receiver = `
208
+ <scxml xmlns="http://www.w3.org/2005/07/scxml" version="1.0"
209
+ datamodel="ecmascript" name="receiver" initial="s">
210
+ <state id="s"><transition event="hello"><log expr="'receiver got ' + _event.name"/></transition></state>
211
+ </scxml>`;
212
+
213
+ const compiled = compileCharts([{ name: 'sender.scxml', text: sender }, { name: 'receiver.scxml', text: receiver }]);
214
+ const host = new Host({ systemID: 'demo' }, { log: (host, entry) => console.log(entry.text) });
215
+ host.addImage(compiled.image);
216
+ compiled.close();
217
+ host.spawn(host.chart('sender'));
218
+ host.spawn(host.chart('receiver'));
219
+ await host.idle();
220
+ host.close();
221
+ ```
222
+
223
+ ```output
224
+ the order went out as send.1
225
+ receiver got hello.tea
226
+ self.note (internal) undefined
227
+ self.order (external) {"qty":2,"sku":"tea"}
228
+ ```
229
+
230
+ `idlocation` must name a declared `<data>`, as every assignment must;
231
+ otherwise the `<send>` fails with `error.execution` and nothing is sent.
232
+
233
+ ## XML data
234
+
235
+ A `<data>` whose content is XML holds a document, a small DOM of the
236
+ package's own (neither Node.js nor Bun has a `DOMParser`). Its nodes have
237
+ `nodeType`, `nodeName`, `nodeValue`, `attributes`, `childNodes`,
238
+ `firstChild`, `lastChild`, `parentNode` and `textContent`; a document
239
+ has `documentElement`; and every node has `getElementsByTagName(name)`
240
+ (an array, `'*'` for every element), `getAttribute(name)` and
241
+ `hasAttribute(name)`:
242
+
243
+ ```js
244
+ import { compileCharts, Host } from '@tinyactors/node';
245
+
246
+ const chart = `
247
+ <scxml xmlns="http://www.w3.org/2005/07/scxml" version="1.0"
248
+ datamodel="ecmascript" name="menu" initial="s">
249
+ <datamodel>
250
+ <data id="catalog">
251
+ <prices xmlns=""><price sku="tea">4</price><price sku="cake">7</price></prices>
252
+ </data>
253
+ </datamodel>
254
+ <state id="s">
255
+ <onentry>
256
+ <foreach array="catalog.getElementsByTagName('price')" item="node" index="i">
257
+ <log expr="(i + 1) + '. ' + node.getAttribute('sku') + ' ' + node.textContent"/>
258
+ </foreach>
259
+ </onentry>
260
+ </state>
261
+ </scxml>`;
262
+
263
+ const compiled = compileCharts([{ name: 'menu.scxml', text: chart }]);
264
+ const host = new Host({ systemID: 'shop' }, { log: (host, entry) => console.log(entry.text) });
265
+ host.addImage(compiled.image);
266
+ compiled.close();
267
+ host.spawn(host.chart('menu'));
268
+ await host.idle();
269
+ host.close();
270
+ ```
271
+
272
+ ```output
273
+ 1. tea 4
274
+ 2. cake 7
275
+ ```
276
+
277
+ An actor whose variable holds a DOM stays in memory: hibernation and
278
+ snapshots refuse it. A DOM that leaves the chart for your program (the
279
+ `<content>` of a `<send>` to an I/O processor, a value `actorContext`
280
+ reads) reaches it as its XML text, a string: the text a document was read
281
+ from, or a node written out, on both datamodels.
282
+
283
+ ## Several charts in one image
284
+
285
+ `compileCharts` takes a list of documents, each `{ name, text }`, and
286
+ compiles them into one image. Each chart is known by its `<scxml name>`;
287
+ `host.chart(name)` finds it. The `name` of a document is what error
288
+ messages and `src` attributes name.
289
+
290
+ A chart may read another document through `src`: `<invoke
291
+ src="child.scxml">`, `<script src>`, `<data src>`. A document in the list
292
+ answers a `src` with its name. For the others, give `compileCharts` a
293
+ **resolver**, a function `(base, source) => text` called during the
294
+ compile for each `src` it does not have (`base` is the document that
295
+ names it). It may read a file, a map or a database. To refuse, it throws
296
+ a `ResolveError`, which becomes a compile error at the line and column
297
+ you give:
298
+
299
+ ```js
300
+ import { compileCharts, CompileError, ResolveError } from '@tinyactors/node';
301
+
302
+ const files = { 'child.scxml': '<scxml xmlns="http://www.w3.org/2005/07/scxml" version="1.0" name="child"><final id="f"/></scxml>' };
303
+ const resolver = (base, source) => {
304
+ if (!(source in files)) throw new ResolveError(`${base} asks for ${source}, which is not in the store`, { line: 1, column: 1 });
305
+ return files[source];
306
+ };
307
+
308
+ const parent = (src) => `<scxml xmlns="http://www.w3.org/2005/07/scxml" version="1.0" name="parent">
309
+ <state id="s"><invoke src="${src}"/></state>
310
+ </scxml>`;
311
+
312
+ const compiled = compileCharts([{ name: 'parent.scxml', text: parent('child.scxml') }], resolver);
313
+ console.log('compiled', compiled.image.length > 0);
314
+ compiled.close();
315
+
316
+ try {
317
+ compileCharts([{ name: 'parent.scxml', text: parent('missing.scxml') }], resolver);
318
+ } catch (error) {
319
+ if (!(error instanceof CompileError)) throw error;
320
+ console.log(error.message);
321
+ }
322
+ ```
323
+
324
+ ```output
325
+ compiled true
326
+ missing.scxml:1:1: error: parent.scxml asks for missing.scxml, which is not in the store
327
+ ```
328
+
329
+ Any other error a resolver throws (a file that cannot be read) is thrown
330
+ from `compileCharts` as it is.
331
+
332
+ **The compile result.** `compileCharts` returns an object whose `image`
333
+ is a `Buffer`, yours from the first read, and whose `diagnostics` lists
334
+ the compiler's warnings. `close()` frees the compiler's memory at once (the
335
+ garbage collector does it otherwise); read `image` first. An image is
336
+ plain bytes: write it to a file and load it in another process with
337
+ `host.addImage(readFileSync(path))`. `addImage` copies it and returns the
338
+ image's **segment**, a number the host uses for that image.
339
+
340
+ **In one call.** `host.addCharts({ [name]: text }, { resolver })`
341
+ compiles the documents of an object, adds the image and closes the
342
+ compile result, and returns the segment: `compileCharts`, `addImage` and
343
+ `close()` as you would write them. The object's first key is the boot
344
+ chart (JavaScript keeps an object's keys in the order they were written,
345
+ except keys that are integers, which come first). A compile error throws
346
+ the same `CompileError`, with every diagnostic, and adds nothing.
347
+ `host.spawnChart(name, options)` spawns the current version of chart
348
+ `name`, as `host.spawn(host.chart(name), options)` does:
349
+
350
+ ```js
351
+ import { Host } from '@tinyactors/node';
352
+
353
+ const host = new Host({ systemID: 'demo' }, { log: (host, entry) => console.log(entry.text) });
354
+ const segment = host.addCharts({
355
+ 'hello.scxml': `<scxml xmlns="http://www.w3.org/2005/07/scxml" version="1.0" datamodel="ecmascript" name="hello">
356
+ <datamodel><data id="who" expr="'world'"/></datamodel>
357
+ <state id="s"><onentry><log expr="'hello, ' + who"/></onentry></state>
358
+ </scxml>`,
359
+ });
360
+ console.log('segment', segment);
361
+ host.spawnChart('hello');
362
+ host.spawnChart('hello', { params: { who: 'Ada' } });
363
+ await host.idle();
364
+ host.close();
365
+ ```
366
+
367
+ ```output
368
+ segment 0
369
+ hello, world
370
+ hello, Ada
371
+ ```
372
+
373
+ **Charts in a directory.** `directoryResolver(root)` is a resolver that
374
+ reads each `src` as a file under `root`, relative to the directory of
375
+ the document that names it: a document named `orders/order.scxml` that
376
+ asks for `payment.scxml` reads `<root>/orders/payment.scxml`. It refuses,
377
+ as a compile error, a path that leaves `root` (`..` past it, an absolute
378
+ path, or a symbolic link that points outside), a file that does not
379
+ exist, and a file that is not UTF-8; another error of the file system (a
380
+ directory, no permission) is thrown as it is:
381
+
382
+ ```js
383
+ import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
384
+ import { tmpdir } from 'node:os';
385
+ import { join } from 'node:path';
386
+ import { CompileError, directoryResolver, Host } from '@tinyactors/node';
387
+
388
+ const root = mkdtempSync(join(tmpdir(), 'charts-'));
389
+ mkdirSync(join(root, 'orders'));
390
+ writeFileSync(join(root, 'orders', 'payment.scxml'), `<scxml xmlns="http://www.w3.org/2005/07/scxml" version="1.0"
391
+ datamodel="ecmascript" name="payment">
392
+ <state id="s"><onentry><log expr="'paying'"/></onentry></state>
393
+ </scxml>`);
394
+ const order = (src) => `<scxml xmlns="http://www.w3.org/2005/07/scxml" version="1.0" datamodel="ecmascript" name="order">
395
+ <state id="s"><invoke src="${src}"/></state>
396
+ </scxml>`;
397
+
398
+ const resolver = directoryResolver(root);
399
+ const host = new Host({ systemID: 'demo' }, { log: (host, entry) => console.log(entry.text) });
400
+ host.addCharts({ 'orders/order.scxml': order('payment.scxml') }, { resolver });
401
+ host.spawnChart('order');
402
+ await host.idle();
403
+
404
+ try {
405
+ host.addCharts({ 'orders/order.scxml': order('../../etc/passwd') }, { resolver });
406
+ } catch (error) {
407
+ if (!(error instanceof CompileError)) throw error;
408
+ console.log(error.diagnostics[0].message);
409
+ }
410
+ host.close();
411
+ rmSync(root, { recursive: true });
412
+ ```
413
+
414
+ ```output
415
+ paying
416
+ ../../etc/passwd (from orders/order.scxml) leaves the resolver's root
417
+ ```
418
+
419
+ A document the resolver read is named by its `src` as written, so a
420
+ `src` inside it is read relative to that name's directory.
421
+
422
+ ## A chart that starts another
423
+
424
+ `<invoke src="child.scxml">` starts an actor of another chart, a
425
+ **child**, when its state is entered, and stops it when the state is
426
+ left. Its `<param>`s set the child's variables, as `spawn`'s `params` do.
427
+ The child sends to its parent with `target="#_parent"`; its events reach
428
+ the parent with `_event.invokeid` set to the invoke's `id`. When the child
429
+ reaches a final state, the parent gets `done.invoke.<id>`, with the
430
+ child's `<donedata>` as its data.
431
+
432
+ ```js
433
+ import { compileCharts, Host } from '@tinyactors/node';
434
+
435
+ const parent = `
436
+ <scxml xmlns="http://www.w3.org/2005/07/scxml" version="1.0"
437
+ datamodel="ecmascript" name="parent" initial="waiting">
438
+ <state id="waiting">
439
+ <invoke id="worker" src="worker.scxml"><param name="n" expr="21"/></invoke>
440
+ <transition event="progress"><log expr="'progress from ' + _event.invokeid + ': ' + _event.data.step"/></transition>
441
+ <transition event="done.invoke.worker" target="done">
442
+ <log expr="'the worker answered ' + _event.data.answer"/>
443
+ </transition>
444
+ </state>
445
+ <final id="done"/>
446
+ </scxml>`;
447
+
448
+ const worker = `
449
+ <scxml xmlns="http://www.w3.org/2005/07/scxml" version="1.0"
450
+ datamodel="ecmascript" name="worker" initial="working">
451
+ <datamodel><data id="n" expr="0"/></datamodel>
452
+ <state id="working">
453
+ <onentry><send event="progress" target="#_parent"><param name="step" expr="'halfway'"/></send></onentry>
454
+ <transition target="finished"/>
455
+ </state>
456
+ <final id="finished">
457
+ <donedata><param name="answer" expr="n * 2"/></donedata>
458
+ </final>
459
+ </scxml>`;
460
+
461
+ const compiled = compileCharts([{ name: 'parent.scxml', text: parent }, { name: 'worker.scxml', text: worker }]);
462
+ const host = new Host({ systemID: 'demo' }, { log: (host, entry) => console.log(entry.text) });
463
+ host.addImage(compiled.image);
464
+ compiled.close();
465
+ host.spawn(host.chart('parent'));
466
+ await host.idle();
467
+ host.close();
468
+ ```
469
+
470
+ ```output
471
+ progress from worker: halfway
472
+ the worker answered 42
473
+ ```
474
+
475
+ A parent sends to its child with `target="#_worker"` (`#_` and the
476
+ invoke's id). `<invoke>` of a type other than SCXML is a service your
477
+ program runs: [Invoked services](services.md).
478
+
479
+ **The child exists from the end of the macrostep that entered its
480
+ state**, as SCXML starts invocations then. Until that point a send to
481
+ `#_worker` gets `error.communication`: from the state's own `<onentry>`,
482
+ and from anything else in the same macrostep, such as a `<raise>`d
483
+ event's transition, an eventless transition, or a history state that
484
+ re-enters several states at once. Send from a later event: the child's
485
+ first message to its parent (`ready` below) is the usual signal, and
486
+ what the child must know at its start goes in as a `<param>`, which is
487
+ evaluated when it starts.
488
+
489
+ ```js
490
+ import { compileCharts, Host } from '@tinyactors/node';
491
+
492
+ const parent = `
493
+ <scxml xmlns="http://www.w3.org/2005/07/scxml" version="1.0"
494
+ datamodel="ecmascript" name="parent" initial="running">
495
+ <state id="running">
496
+ <onentry>
497
+ <send event="hello" target="#_kid"/>
498
+ <raise event="soon"/>
499
+ </onentry>
500
+ <invoke id="kid" src="kid.scxml"/>
501
+ <transition event="soon"><send event="hello" target="#_kid"/></transition>
502
+ <transition event="error.communication"><log expr="'no child yet: error.communication'"/></transition>
503
+ <transition event="ready"><send event="hello" target="#_kid"/></transition>
504
+ </state>
505
+ </scxml>`;
506
+ const kid = `
507
+ <scxml xmlns="http://www.w3.org/2005/07/scxml" version="1.0"
508
+ datamodel="ecmascript" name="kid" initial="s">
509
+ <state id="s">
510
+ <onentry><send event="ready" target="#_parent"/></onentry>
511
+ <transition event="hello"><log expr="'the child got hello'"/></transition>
512
+ </state>
513
+ </scxml>`;
514
+
515
+ const compiled = compileCharts([{ name: 'parent.scxml', text: parent }, { name: 'kid.scxml', text: kid }]);
516
+ const host = new Host({ systemID: 'demo' }, { log: (host, entry) => console.log(entry.text) });
517
+ host.addImage(compiled.image);
518
+ compiled.close();
519
+ host.spawn(host.chart('parent'));
520
+ await host.idle();
521
+ host.close();
522
+ ```
523
+
524
+ ```output
525
+ no child yet: error.communication
526
+ no child yet: error.communication
527
+ the child got hello
528
+ ```
529
+
530
+ ## A system that starts its own actors
531
+
532
+ `compileSystem` compiles a **manifest**, a `<system>` document that lists
533
+ its charts (`<chart name src>`, read through the resolver) and the actors
534
+ to start (`<actor name chart>`). `host.boot(segment)` spawns those actors,
535
+ each with its name:
536
+
537
+ ```js
538
+ import { compileSystem, Host } from '@tinyactors/node';
539
+
540
+ const files = {
541
+ 'counter.scxml': `<scxml xmlns="http://www.w3.org/2005/07/scxml" version="1.0"
542
+ datamodel="ecmascript" name="counter" initial="s">
543
+ <datamodel><data id="n" expr="0"/></datamodel>
544
+ <state id="s">
545
+ <transition event="tick"><assign location="n" expr="n + 1"/><log expr="_name + ' ' + n"/></transition>
546
+ </state>
547
+ </scxml>`,
548
+ };
549
+ const manifest = `<system>
550
+ <chart name="counter" src="counter.scxml"/>
551
+ <actor name="left" chart="counter"/>
552
+ <actor name="right" chart="counter"/>
553
+ </system>`;
554
+
555
+ const compiled = compileSystem({ name: 'system.xml', text: manifest }, (base, source) => files[source]);
556
+ const host = new Host({ systemID: 'demo' }, { log: (host, entry) => console.log(entry.text) });
557
+ const segment = host.addImage(compiled.image);
558
+ compiled.close();
559
+
560
+ host.boot(segment);
561
+ host.send(host.actorByName('left'), 'tick');
562
+ host.send(host.actorByName('right'), 'tick');
563
+ host.send(host.actorByName('left'), 'tick');
564
+ await host.idle();
565
+ host.close();
566
+ ```
567
+
568
+ ```output
569
+ left 1
570
+ right 1
571
+ left 2
572
+ ```
573
+
574
+ Booting is for a system that should start the same actors every time it
575
+ starts: the manifest names them, and the program does not need to know
576
+ which. A program that spawns its own actors never needs `boot`. An image
577
+ from `compileCharts` has one boot actor too: an actor of its first chart,
578
+ named after its `<scxml name>`.