@tinyactors/node 0.2.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.
- package/README.md +616 -354
- package/docs/guide/browser.md +494 -0
- package/docs/guide/capacity.md +202 -0
- package/docs/guide/charts.md +578 -0
- package/docs/guide/hibernation.md +201 -0
- package/docs/guide/inspection.md +381 -0
- package/docs/guide/io-processors.md +269 -0
- package/docs/guide/migration.md +323 -0
- package/docs/guide/other-systems.md +275 -0
- package/docs/guide/quickjs.md +135 -0
- package/docs/guide/services.md +317 -0
- package/docs/guide/snapshots.md +186 -0
- package/docs/guide/telemetry.md +265 -0
- package/docs/guide/testing.md +272 -0
- package/docs/values.md +107 -0
- package/index.d.ts +1221 -0
- package/index.mjs +6 -0
- package/lib/convenience.mjs +162 -0
- package/lib/direct.mjs +65 -0
- package/package.json +29 -21
- package/node/index.d.ts +0 -915
- package/node/index.js +0 -44
- package/node/transports.js +0 -60
- package/node/ws.js +0 -152
- package/shared/core.mjs +0 -2966
- package/shared/ecmascript.mjs +0 -670
|
@@ -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 < target" target="on"/>
|
|
46
|
+
</state>
|
|
47
|
+
<state id="on">
|
|
48
|
+
<onentry><log expr="'heater on'"/></onentry>
|
|
49
|
+
<transition event="reading" cond="_event.data.celsius >= 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 `<` for `<` and `&` 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>`.
|