@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 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).