@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/index.mjs ADDED
@@ -0,0 +1,6 @@
1
+ // @tinyactors/node: the direct layer (lib/direct.mjs: the addon's exports,
2
+ // nothing else) and the convenience layer above it (lib/convenience.mjs:
3
+ // JavaScript over the direct layer's exports only; AGENTS.md, "Layers and
4
+ // the resolver").
5
+ export * from './lib/direct.mjs';
6
+ export * from './lib/convenience.mjs';
@@ -0,0 +1,162 @@
1
+ // The convenience layer of @tinyactors/node and @tinyactors/wasm:
2
+ // JavaScript over the direct layer's exports only (AGENTS.md, "Layers and
3
+ // the resolver"). It adds shapes, not behaviour, and imports nothing but
4
+ // `#direct`, the package's direct exports (the lint rule
5
+ // convenience-imports-the-direct-layer): package.json's `imports` maps it
6
+ // to the addon's lib/direct.mjs, and under the export condition
7
+ // `tinyactors-wasm` to the wasm package's wasm/lib/direct.mjs
8
+ // (docs/browser.md, "One API"), so the two packages share this file.
9
+ //
10
+ // Then the shapes chosen for p3-shapes: host.addCharts, host.spawnChart,
11
+ // directoryResolver and Address.prototype.toJSON (below). The only
12
+ // built-ins it reaches are node:fs and node:path, for directoryResolver,
13
+ // through process.getBuiltinModule when the resolver is made: a runtime
14
+ // without them (a browser) refuses it there, with TA_ERROR_UNSUPPORTED.
15
+ //
16
+ // The typed methods return promises when given no handler (the
17
+ // maintainer, 2026-11-18): `host.actorState(params)` returns a promise that
18
+ // resolves with the result and rejects with the TinyactorsError, while
19
+ // `host.actorState(params, onResult, onError?)` is the direct method's call
20
+ // and returns nothing. Each direct method on Host.prototype is replaced by a
21
+ // function that passes a call with a handler straight to it (one argument
22
+ // check and one call more, measured in docs/log.xml,
23
+ // l-maint-promises-built) and otherwise calls it with a result handler that
24
+ // resolves and an error handler that rejects. The promise settles from the
25
+ // handler, in the drain; its continuation runs as a microtask after the
26
+ // turn's native call returns, outside the drain, on a result already
27
+ // converted. A refusal at the call (a closed host, a `this` that is not a
28
+ // Host, params the method cannot write) rejects too, as an async function's
29
+ // throw would. A method still pending at `close()` never settles: the
30
+ // direct layer drops its handlers uncalled. An `onError` without an
31
+ // `onResult` is the direct method's TypeError.
32
+ import { Address, compileCharts, Host, ResolveError, TinyactorsError } from '#direct';
33
+
34
+ /** The direct method `direct` as one that returns a promise of its result
35
+ * when it is given no handler. */
36
+ function promising(direct) {
37
+ return function (params, onResult, onError) {
38
+ if (onResult !== undefined || (onError !== undefined && onError !== null)) return direct.call(this, params, onResult, onError);
39
+ return new Promise((resolve, reject) => {
40
+ direct.call(this, params, (host, result) => resolve(result), (host, error) => reject(error));
41
+ });
42
+ };
43
+ }
44
+
45
+ /** The direct typed methods of Host. */
46
+ const TYPED_METHODS = [
47
+ 'actorState', 'actorContext', 'actorList', 'actorGet', 'hostStats', 'hostConfig',
48
+ 'traceConfigure', 'traceWatch', 'traceUnwatch', 'traceEnd', 'traceSpansDecode',
49
+ ];
50
+
51
+ for (const name of TYPED_METHODS) {
52
+ const direct = Host.prototype[name];
53
+ if (typeof direct !== 'function') throw new Error(`@tinyactors/node: the direct layer has no Host method ${name}`);
54
+ const method = promising(direct);
55
+ // the direct method's name and length (index.d.ts declares them)
56
+ Object.defineProperty(method, 'name', { value: name });
57
+ Object.defineProperty(method, 'length', { value: direct.length });
58
+ // as a class's methods are: writable, configurable, not enumerable
59
+ Object.defineProperty(Host.prototype, name, { value: method, writable: true, configurable: true, enumerable: false });
60
+ }
61
+
62
+ // ---- shapes a JavaScript programmer would otherwise write (p3-shapes) ----
63
+
64
+ /** Defines `value` on `target` as a class's method is: writable,
65
+ * configurable, not enumerable, its `name` the property's. */
66
+ function method(target, name, value) {
67
+ Object.defineProperty(value, 'name', { value: name });
68
+ Object.defineProperty(target, name, { value, writable: true, configurable: true, enumerable: false });
69
+ }
70
+
71
+ /** The options of addCharts: the compile call's resolver, nothing else. */
72
+ const ADD_CHARTS_OPTIONS = new Set(['resolver']);
73
+
74
+ // host.addCharts({name: text}, {resolver}?) → segment: compileCharts of the
75
+ // mapping's entries in their order (the first the boot chart), addImage of
76
+ // the image, close of the result, in one call. The result is closed on every
77
+ // path, so a refused image leaves nothing behind; a CompileError is
78
+ // compileCharts's own, with every diagnostic.
79
+ method(Host.prototype, 'addCharts', function (charts, options) {
80
+ if (typeof charts !== 'object' || charts === null || Array.isArray(charts))
81
+ throw new TypeError('addCharts: charts must be an object of document names to texts');
82
+ if (options !== undefined) {
83
+ if (typeof options !== 'object' || options === null) throw new TypeError('addCharts: options must be an object');
84
+ for (const key of Object.keys(options))
85
+ if (!ADD_CHARTS_OPTIONS.has(key)) throw new TypeError(`addCharts: unknown option ${key}`);
86
+ }
87
+ const sources = Object.entries(charts).map(([name, text]) => ({ name, text }));
88
+ const compiled = compileCharts(sources, options?.resolver);
89
+ try {
90
+ return this.addImage(compiled.image);
91
+ } finally {
92
+ compiled.close();
93
+ }
94
+ });
95
+
96
+ // host.spawnChart(name, options?) → session: spawn of the chart's current
97
+ // version, host.chart(name) then host.spawn(ref, options).
98
+ method(Host.prototype, 'spawnChart', function (name, options) {
99
+ return this.spawn(this.chart(name), options);
100
+ });
101
+
102
+ // Address.prototype.toJSON: its text, so JSON.stringify writes an address
103
+ // as the string an Address is made from (new Address(text) reads it back).
104
+ method(Address.prototype, 'toJSON', function () {
105
+ return this.text;
106
+ });
107
+
108
+ // directoryResolver(root) → resolver: a resolver for the compile calls that
109
+ // reads `source` as a file under `root`, relative to the directory of
110
+ // `base` (a document named `charts/order.scxml` asking for `child.scxml`
111
+ // reads `root/charts/child.scxml`), and refuses, with a ResolveError, a
112
+ // path that leaves `root`: `..`, an absolute path, or a symbolic link
113
+ // anywhere on the way that points outside. `root` is resolved through its
114
+ // own links once, when the resolver is made (a root that does not exist
115
+ // throws there). A file that does not exist is a ResolveError too, so the
116
+ // compile call reports it as a diagnostic; any other error of the file
117
+ // system (a directory, no permission) is thrown from the compile call as it
118
+ // is. The text must be UTF-8: bytes that are not are refused, never
119
+ // replaced.
120
+ const UTF8 = new TextDecoder('utf-8', { fatal: true });
121
+
122
+ /** node:fs and node:path, from the runtime (node, bun); a runtime without
123
+ * them refuses directoryResolver. */
124
+ function builtins() {
125
+ const get = globalThis.process?.getBuiltinModule;
126
+ if (typeof get !== 'function') {
127
+ throw new TinyactorsError('directoryResolver reads files with node:fs, which this runtime does not have', {
128
+ status: 'TA_ERROR_UNSUPPORTED',
129
+ });
130
+ }
131
+ return { fs: get.call(globalThis.process, 'node:fs'), path: get.call(globalThis.process, 'node:path') };
132
+ }
133
+
134
+ /** Whether `file`, absolute, is `root` or under it (`path`: node:path). */
135
+ function inside(path, root, file) {
136
+ const rest = path.relative(root, file);
137
+ return rest !== '' && rest !== '..' && !rest.startsWith(`..${path.sep}`) && !path.isAbsolute(rest);
138
+ }
139
+
140
+ export function directoryResolver(root) {
141
+ const { fs, path } = builtins();
142
+ const top = fs.realpathSync(root);
143
+ return function resolve(base, source) {
144
+ const file = path.resolve(top, path.dirname(base), source);
145
+ if (!inside(path, top, file)) throw new ResolveError(`${source} (from ${base}) leaves the resolver's root`);
146
+ let real;
147
+ try {
148
+ real = fs.realpathSync(file);
149
+ } catch (error) {
150
+ if (error?.code === 'ENOENT' || error?.code === 'ENOTDIR')
151
+ throw new ResolveError(`${source} (from ${base}): no such file under the resolver's root`);
152
+ throw error;
153
+ }
154
+ if (!inside(path, top, real)) throw new ResolveError(`${source} (from ${base}) leaves the resolver's root through a symbolic link`);
155
+ const bytes = fs.readFileSync(real);
156
+ try {
157
+ return UTF8.decode(bytes);
158
+ } catch {
159
+ throw new ResolveError(`${source} (from ${base}) is not UTF-8`);
160
+ }
161
+ };
162
+ }
package/lib/direct.mjs ADDED
@@ -0,0 +1,65 @@
1
+ // The direct layer of @tinyactors/node: loads the addon and re-exports it,
2
+ // nothing else (AGENTS.md, "Layers and the resolver"). index.mjs exports
3
+ // these names and the convenience layer's (lib/convenience.mjs), which
4
+ // imports this module only. In the repository the addon is
5
+ // build/tinyactors.node, which `mise run build` makes; an installed package
6
+ // has no build/, and its addon is this platform's package,
7
+ // @tinyactors/node-<platform>-<arch>, which an install of @tinyactors/node
8
+ // brings as an optional dependency at exactly its own version (npm, pnpm
9
+ // and Bun install only the one whose os and cpu match).
10
+ //
11
+ // The development build comes first: Bun, run where no node_modules is
12
+ // (the repository), installs a package it cannot resolve from the
13
+ // registry, so asking for the platform package there would load the last
14
+ // release's addon. The platform package's version must be this package's
15
+ // for the same reason.
16
+ import { createRequire } from 'node:module';
17
+
18
+ const require = createRequire(import.meta.url);
19
+ const platformPackage = `@tinyactors/node-${process.platform}-${process.arch}`;
20
+
21
+ function notFound(error) {
22
+ return error?.code === 'MODULE_NOT_FOUND';
23
+ }
24
+
25
+ function load() {
26
+ try {
27
+ return require('../build/tinyactors.node');
28
+ } catch (error) {
29
+ if (!notFound(error)) throw error;
30
+ }
31
+ const { version } = require('../package.json');
32
+ let installed;
33
+ try {
34
+ installed = require(`${platformPackage}/package.json`).version;
35
+ } catch (error) {
36
+ if (!notFound(error)) throw error;
37
+ throw new Error(
38
+ `@tinyactors/node: no addon for ${process.platform}-${process.arch}: ${platformPackage} is not installed ` +
39
+ '(an install of @tinyactors/node brings it where the platform has one), and this is not a build in the ' +
40
+ 'repository (mise run build); @tinyactors/wasm runs the same API on any platform, without an addon',
41
+ { cause: error },
42
+ );
43
+ }
44
+ if (installed !== version) {
45
+ throw new Error(`@tinyactors/node: ${platformPackage} is ${installed}, not ${version}: reinstall @tinyactors/node`);
46
+ }
47
+ return require(platformPackage);
48
+ }
49
+
50
+ const addon = load();
51
+
52
+ export const {
53
+ encode,
54
+ decode,
55
+ TinyactorsError,
56
+ CompileError,
57
+ ResolveError,
58
+ compileCharts,
59
+ compileSystem,
60
+ Host,
61
+ SimulatedClock,
62
+ Address,
63
+ encodeHTTPPost,
64
+ parseHTTPRequest,
65
+ } = addon;
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@tinyactors/node",
3
- "version": "0.1.0",
4
- "description": "Tinyactors for Node.js and Bun: SCXML statecharts as actors, on a native runtime",
3
+ "version": "0.3.0",
4
+ "description": "SCXML statecharts as actors on the tinyactors host, from Node.js and Bun (a Node-API addon)",
5
5
  "keywords": [
6
6
  "actor",
7
7
  "actors",
@@ -11,31 +11,44 @@
11
11
  "napi",
12
12
  "bun"
13
13
  ],
14
- "homepage": "https://github.com/dhamidi/tinyactors/tree/main/tinyactors-napi#readme",
14
+ "homepage": "https://github.com/tinyactors-dev/tinyactors-napi#readme",
15
15
  "repository": {
16
16
  "type": "git",
17
- "url": "git+https://github.com/dhamidi/tinyactors.git",
17
+ "url": "git+https://github.com/tinyactors-dev/tinyactors.git",
18
18
  "directory": "tinyactors-napi"
19
19
  },
20
20
  "bugs": {
21
- "url": "https://github.com/dhamidi/tinyactors/issues"
21
+ "url": "https://github.com/tinyactors-dev/tinyactors/issues"
22
22
  },
23
23
  "license": "MIT",
24
- "main": "index.js",
25
- "types": "index.d.ts",
24
+ "engines": {
25
+ "node": ">=22.3.0"
26
+ },
27
+ "type": "module",
28
+ "exports": {
29
+ ".": {
30
+ "types": "./index.d.ts",
31
+ "default": "./index.mjs"
32
+ }
33
+ },
26
34
  "files": [
27
- "index.js",
28
- "index.d.ts",
35
+ "index.mjs",
29
36
  "lib",
30
- "README.md"
37
+ "index.d.ts",
38
+ "README.md",
39
+ "LICENSE",
40
+ "docs/guide",
41
+ "docs/values.md"
31
42
  ],
32
- "engines": {
33
- "node": ">=22.14"
43
+ "imports": {
44
+ "#direct": {
45
+ "default": "./lib/direct.mjs"
46
+ }
34
47
  },
35
48
  "optionalDependencies": {
36
- "@tinyactors/node-darwin-arm64": "0.1.0",
37
- "@tinyactors/node-darwin-x64": "0.1.0",
38
- "@tinyactors/node-linux-x64": "0.1.0",
39
- "@tinyactors/node-linux-arm64": "0.1.0"
49
+ "@tinyactors/node-darwin-arm64": "0.3.0",
50
+ "@tinyactors/node-darwin-x64": "0.3.0",
51
+ "@tinyactors/node-linux-x64": "0.3.0",
52
+ "@tinyactors/node-linux-arm64": "0.3.0"
40
53
  }
41
54
  }
package/index.js DELETED
@@ -1,34 +0,0 @@
1
- 'use strict';
2
-
3
- const native = require('./lib/native');
4
- const { TinyactorsError } = require('./lib/errors');
5
- const { createSystem } = require('./lib/system');
6
- const { statechart, literal, content } = require('./lib/statechart');
7
- const { TRACE_KINDS, parseTraceparent, formatTraceparent, stepSpanID } = require('./lib/tracing');
8
- const { decodeTraces } = require('./lib/otlp');
9
- const { metricsToOTLP } = require('./lib/metrics');
10
- const { createDebugSession, DAPReader, encodeDAPMessage } = require('./lib/debug');
11
-
12
- module.exports = {
13
- version: native.version,
14
- createSystem,
15
- statechart,
16
- literal,
17
- content,
18
- TinyactorsError,
19
- // Tracing (core ADR 0067, napi ADR 0016): OTLP bytes, and a decoder; no
20
- // telemetry dependency.
21
- TRACE_KINDS,
22
- decodeTraces,
23
- parseTraceparent,
24
- formatTraceparent,
25
- stepSpanID,
26
- // Metrics (core ADR 0072, napi ADR 0017): system.metrics() and its OTLP bytes.
27
- metricsToOTLP,
28
- // The debug adapter (napi ADR 0026): a DAP session the application puts
29
- // behind its own transport, and the base protocol's framing for byte
30
- // streams.
31
- createDebugSession,
32
- DAPReader,
33
- encodeDAPMessage,
34
- };
package/lib/actor.js DELETED
@@ -1,85 +0,0 @@
1
- 'use strict';
2
-
3
- // ActorID/Actor view (ADR 0002). An actor is named by its slot and
4
- // generation, two small integers. A view holds its system and those two
5
- // numbers and nothing else: it has no native resource and no finalizer, and
6
- // every question about the actor is asked of core through the system. A view
7
- // of a destroyed actor is harmless: its calls fail with `not-found`.
8
- //
9
- // The pump makes views natively for the actors it passes to hooks, so the
10
- // class is registered with the addon once (setupActor).
11
-
12
- const native = require('./native');
13
-
14
- class ActorID {
15
- constructor(system, slot, generation) {
16
- this.system = system;
17
- this.slot = slot;
18
- this.generation = generation;
19
- }
20
-
21
- /** Equality is by value (ADR 0002 point 5). */
22
- equals(other) {
23
- return (
24
- other instanceof ActorID &&
25
- other.system === this.system &&
26
- other.slot === this.slot &&
27
- other.generation === this.generation
28
- );
29
- }
30
-
31
- /** Queue an event for this actor (System.post). */
32
- post(event, data, options) {
33
- this.system.post(this, event, data, options);
34
- }
35
-
36
- /** Queue an event for this actor and await its macrostep (System.send). */
37
- send(event, data, options) {
38
- return this.system.send(this, event, data, options);
39
- }
40
-
41
- /** A snapshot of core's view of this actor. */
42
- inspect() {
43
- return this.system.inspect(this);
44
- }
45
-
46
- /** True when no resident actor has this ID any more. */
47
- get destroyed() {
48
- return !this.system.exists(this);
49
- }
50
-
51
- /** The actor's live data-model root, shared, not copied; undefined under the null data model. */
52
- data() {
53
- return this.system.inspect(this).data;
54
- }
55
-
56
- /** Capture this actor in memory (System.capture). */
57
- capture() {
58
- return this.system.capture(this);
59
- }
60
-
61
- /** Offload this stable named actor from memory (System.unload, core ADR 0074). */
62
- unload() {
63
- this.system.unload(this);
64
- }
65
-
66
- /** Prepare a fresh unpublished actor of `definition` to replace this one (System.prepareReplacement). */
67
- prepareReplacement(definition, options) {
68
- return this.system.prepareReplacement(this, definition, options);
69
- }
70
-
71
- /** Terminate this actor. Invoked children are not destroyed implicitly. */
72
- destroy() {
73
- this.system.destroy(this);
74
- }
75
-
76
- [Symbol.dispose]() {
77
- if (!this.system.closed && !this.destroyed) {
78
- this.destroy();
79
- }
80
- }
81
- }
82
-
83
- native.setupActor(ActorID);
84
-
85
- module.exports = { ActorID };