@tinyactors/node 0.1.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/LICENSE +21 -0
- package/README.md +169 -0
- package/index.d.ts +1875 -0
- package/index.js +34 -0
- package/lib/actor.js +85 -0
- package/lib/debug/breakpoints.js +349 -0
- package/lib/debug/console.js +149 -0
- package/lib/debug/expressions.js +133 -0
- package/lib/debug/frames.js +119 -0
- package/lib/debug/labels.js +142 -0
- package/lib/debug/macrosteps.js +207 -0
- package/lib/debug/protocol.js +186 -0
- package/lib/debug/sources.js +218 -0
- package/lib/debug/variables.js +265 -0
- package/lib/debug.js +1434 -0
- package/lib/definition.js +139 -0
- package/lib/errors.js +24 -0
- package/lib/events.js +56 -0
- package/lib/image.js +90 -0
- package/lib/loader.js +68 -0
- package/lib/metrics.js +333 -0
- package/lib/native.js +8 -0
- package/lib/otlp.js +332 -0
- package/lib/statechart.js +768 -0
- package/lib/system.js +2183 -0
- package/lib/tracing.js +164 -0
- package/package.json +41 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Dario Hamidi
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,169 @@
|
|
|
1
|
+
# @tinyactors/node
|
|
2
|
+
|
|
3
|
+
Tinyactors for Node.js (22.14 or newer) and Bun: SCXML statecharts run as
|
|
4
|
+
actors on a native runtime, through Node-API.
|
|
5
|
+
|
|
6
|
+
```text
|
|
7
|
+
npm install @tinyactors/node
|
|
8
|
+
```
|
|
9
|
+
|
|
10
|
+
The install brings a prebuilt addon for your platform: no compiler, no
|
|
11
|
+
`node-gyp` and no postinstall script. There are addons for macOS on Apple
|
|
12
|
+
silicon and Intel (11.0 or newer) and for Linux on x64 and arm64; the Linux
|
|
13
|
+
addon links no C library, so one build serves glibc and musl (Alpine).
|
|
14
|
+
|
|
15
|
+
```js
|
|
16
|
+
const { createSystem, statechart } = require('@tinyactors/node');
|
|
17
|
+
|
|
18
|
+
const light = statechart({ family: 'light', revision: 'v1' })
|
|
19
|
+
.data('switches', 0)
|
|
20
|
+
.state('off', (s) => s.on('toggle', (t) => t.target('on').assign('switches', function () { return this.switches + 1; })))
|
|
21
|
+
.state('on', (s) => s.on('toggle', (t) => t.target('off')));
|
|
22
|
+
|
|
23
|
+
async function main() {
|
|
24
|
+
const system = createSystem();
|
|
25
|
+
const lamp = system.spawn(system.define(light), { name: 'lamp' });
|
|
26
|
+
await lamp.send('toggle'); // resolves once the macrostep it started ends
|
|
27
|
+
console.log(lamp.inspect().activeStates, lamp.data().switches); // [ 'on' ] 1
|
|
28
|
+
system.close();
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
main();
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
`index.d.ts` describes the whole API. The package is 0.x: its API changes
|
|
35
|
+
in minor versions.
|
|
36
|
+
|
|
37
|
+
## Working on it in the repository
|
|
38
|
+
|
|
39
|
+
In this repository the package is built and tested through the task
|
|
40
|
+
interface; the addon it loads is the one `mise run build` writes:
|
|
41
|
+
|
|
42
|
+
```text
|
|
43
|
+
mise run build
|
|
44
|
+
mise run test
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
The tests load the same native addon with Node.js and Bun. See
|
|
48
|
+
[`docs/design.md`](docs/design.md) for the binding architecture, and
|
|
49
|
+
[ADR 0001](../docs/adr/0001-packaging-and-releases.md) for how the packages
|
|
50
|
+
are built and released: `mise run build --target <t>` builds a release
|
|
51
|
+
target's addon with zig, `mise run symbols` checks what it imports, and
|
|
52
|
+
`mise run package` stages and packs the npm packages into
|
|
53
|
+
`build/npm/tarballs/`.
|
|
54
|
+
|
|
55
|
+
## `index.d.ts` is the desired API
|
|
56
|
+
|
|
57
|
+
`index.d.ts` is the design target, not a description of what `lib/`
|
|
58
|
+
implements. A declaration that is not implemented yet carries
|
|
59
|
+
`// status: unimplemented`, or `// status: partial: <what is missing>`, on
|
|
60
|
+
the line directly above it. Don't delete a declaration because `lib/` lacks
|
|
61
|
+
it: implement it, or leave it marked. `grep -n "^ *// status:" index.d.ts`
|
|
62
|
+
lists what is outstanding, and `mise run check-api-status` (part of
|
|
63
|
+
`mise run test`) fails when a marker is stale or a missing declaration is
|
|
64
|
+
unmarked, for the exports and for the objects it can probe at runtime.
|
|
65
|
+
|
|
66
|
+
## Benchmarks
|
|
67
|
+
|
|
68
|
+
`mise run bench [population ...]` runs the tracing bench on Node and Bun and
|
|
69
|
+
prints throughput and memory side by side; `mise run bench-compare <commit>`
|
|
70
|
+
builds another commit beside the working tree and runs both alternately on
|
|
71
|
+
this machine, flagging changes past 5%. Results are stored under
|
|
72
|
+
`bench/results/<machine signature>/` (see its README).
|
|
73
|
+
|
|
74
|
+
**Reporting convention.** A benchmark report always gives throughput and
|
|
75
|
+
memory together, names the machine signature it ran under, and compares
|
|
76
|
+
builds side by side with `bench-compare`, never against numbers from another
|
|
77
|
+
day or another machine: the same build measured 30% apart on two days on
|
|
78
|
+
one machine.
|
|
79
|
+
|
|
80
|
+
## Loading actors on demand
|
|
81
|
+
|
|
82
|
+
`System.setLoader(family, loader)` brings actors of a family back when mail
|
|
83
|
+
arrives for them. Mail for a name with no resident actor waits while the
|
|
84
|
+
loader runs, then is delivered first, in order. The loader returns a
|
|
85
|
+
`SessionImage` (process-local: for actors offloaded from memory in this
|
|
86
|
+
process), `{ spawn: definition, binding }` to rebuild an actor from data
|
|
87
|
+
the application stored (after a restart, for example), `"not-found"`, or
|
|
88
|
+
`"reject"` for "not now". An unloaded actor's own timers wake it through
|
|
89
|
+
its loader. See [ADR 0020](docs/adr/0020-mail-for-an-unloaded-actor-waits-while-a-loader-brings-it-back.md).
|
|
90
|
+
|
|
91
|
+
## Tracing
|
|
92
|
+
|
|
93
|
+
`System.setTraceSink()` hands a function you register the spans of each
|
|
94
|
+
pump turn as OTLP protobuf bytes, which any OTLP/HTTP collector takes as
|
|
95
|
+
they are; `decodeTraces()` reads them back into objects. There is no
|
|
96
|
+
telemetry dependency. See
|
|
97
|
+
[`docs/tracing.md`](docs/tracing.md), and `mise run otel-demo` to look at
|
|
98
|
+
a trace in otel-tui.
|
|
99
|
+
|
|
100
|
+
SCXML documents import with `define(xml, { format: 'scxml' })`, and
|
|
101
|
+
`registerDatamodel()` plugs in a compiler for their expression text. See
|
|
102
|
+
[`docs/scxml.md`](docs/scxml.md).
|
|
103
|
+
|
|
104
|
+
## Debugging an actor
|
|
105
|
+
|
|
106
|
+
`createDebugSession(system, { allow, audit, send })` is a Debug Adapter
|
|
107
|
+
Protocol session over one actor of a running system: give it each incoming
|
|
108
|
+
message with `receive()`, and it hands each outgoing one to `send`. It
|
|
109
|
+
opens no socket and checks no credentials; put it behind your own
|
|
110
|
+
transport and authentication, and decide each user's permissions before
|
|
111
|
+
you create it. `DAPReader` and `encodeDAPMessage` frame messages on a byte
|
|
112
|
+
stream (stdio, a TCP socket); a WebSocket needs neither.
|
|
113
|
+
|
|
114
|
+
A client attaches with `{ "address": "family/name" }` (or `"sessionID"`),
|
|
115
|
+
and may ask for fewer permissions with `"allow"`. The session watches the
|
|
116
|
+
actor live and never stops it: a production actor is never held by a
|
|
117
|
+
debugger. The client hears the actor stopped on entry, so it shows the
|
|
118
|
+
stack and the variables, and after each macrostep the summary in the
|
|
119
|
+
console and a refresh of both that leaves the keyboard focus where it is,
|
|
120
|
+
so typing in the Debug Console is never interrupted. `pause` and the
|
|
121
|
+
steps are refused, and `continue` changes nothing. Breakpoints are
|
|
122
|
+
tracepoints: the console says where one would have stopped, and a logpoint
|
|
123
|
+
writes its message.
|
|
124
|
+
|
|
125
|
+
What `allow` grants are pokes, each a transition the watcher sees as a new
|
|
126
|
+
macrostep: `send` an event through the mailbox, `set` a data-model
|
|
127
|
+
location, `goto` (an operator transition, with `abandon`, `cancel` and
|
|
128
|
+
`replace`), and `evaluate`. With none, the session only watches.
|
|
129
|
+
|
|
130
|
+
**`evaluate` runs arbitrary code.** Watch, hover and console expressions,
|
|
131
|
+
breakpoint conditions and logpoint `{expression}` parts run JavaScript in
|
|
132
|
+
your process. They need the `evaluate` permission, which is off unless
|
|
133
|
+
granted, and each is checked against the attach it runs under: a
|
|
134
|
+
condition set before a watch-only attach never runs. Without it the
|
|
135
|
+
Variables pane and the console commands still work. Grant it only to
|
|
136
|
+
someone who may run code on the host.
|
|
137
|
+
|
|
138
|
+
Frames and line breakpoints are on the lines a chart was written on:
|
|
139
|
+
the builder calls of statechart(), or the lines of an SCXML document you
|
|
140
|
+
name with `define(text, { format: 'scxml', name: path })`. A document
|
|
141
|
+
defined without a name, or a child chart inline in `<content>`, is shown
|
|
142
|
+
as SCXML the session writes from the definition, which the client asks
|
|
143
|
+
for by `sourceReference` and sets breakpoints in.
|
|
144
|
+
|
|
145
|
+
`audit(entry)` hears every attach, detach, breakpoint change, console
|
|
146
|
+
command, evaluation and mutation before it happens; a hook that throws
|
|
147
|
+
refuses it. That includes each breakpoint condition and logpoint part at
|
|
148
|
+
each hit: a refused condition does not fire, and a refused part is
|
|
149
|
+
written as `<refused>`. Only a detach is heard after it happens.
|
|
150
|
+
|
|
151
|
+
`mise run dap-server` serves sessions for a small example system over
|
|
152
|
+
stdio, or on a local port with `-- --port 4711`, to try a DAP client
|
|
153
|
+
against. It grants every permission; it is a development tool, not part
|
|
154
|
+
of the package. In VS Code, install
|
|
155
|
+
[tinyactors-vscode](../tinyactors-vscode/README.md): an `attach`
|
|
156
|
+
configuration with the `port` and the actor's `address` connects to such a
|
|
157
|
+
server. See
|
|
158
|
+
[ADR 0026](docs/adr/0026-a-debugger-watches-and-pokes-one-live-actor.md)
|
|
159
|
+
and [the status of every DAP message](../docs/debug-adapter.md).
|
|
160
|
+
|
|
161
|
+
`test/dap-transcripts.js` plays the DAP transcripts napi shares with the
|
|
162
|
+
test host's adapter (`../tinyactors-test/dap/transcripts/`), under Node
|
|
163
|
+
and Bun, so the two adapters stay in step. To add one, write the
|
|
164
|
+
transcript, and the chart in both forms (`dap/charts/<chart>.js` and
|
|
165
|
+
`.rb`) if it needs a new one, then play it in both hosts: `node
|
|
166
|
+
test/dap-transcripts.js <name>` here (`DAP_TRACE=1` prints every message)
|
|
167
|
+
and `ruby ruby/dap_transcripts.rb <name>` in tinyactors-test. The format
|
|
168
|
+
and where the adapters differ are in
|
|
169
|
+
[its README](../tinyactors-test/dap/README.md).
|