@tinyactors/node 0.1.0 → 0.2.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/lib/definition.js DELETED
@@ -1,139 +0,0 @@
1
- 'use strict';
2
-
3
- // Definition facade (ADRs 0001 and 0013). A Definition is a system and a
4
- // definition ID, and nothing else: its identity, inspection and retired flag
5
- // are read from core on every access, so the addon keeps no copy of a fact
6
- // core owns.
7
-
8
- const { core } = require('./native');
9
- const { TinyactorsError } = require('./errors');
10
-
11
- const utf8 = new TextDecoder('utf-8', { fatal: true });
12
-
13
- // Core stores a revision as bytes. It reads back as a string when the bytes
14
- // are valid UTF-8, and as a Uint8Array otherwise.
15
- function revisionOf(bytes) {
16
- try {
17
- return utf8.decode(bytes);
18
- } catch {
19
- return new Uint8Array(bytes);
20
- }
21
- }
22
-
23
- function identityOf(identity) {
24
- return { family: identity.family.name, revision: revisionOf(identity.revision) };
25
- }
26
-
27
- class Definition {
28
- #native;
29
-
30
- constructor(system, native, id) {
31
- this.#native = native;
32
- Object.defineProperty(this, 'system', { value: system, enumerable: true });
33
- Object.defineProperty(this, 'id', { value: id, enumerable: true });
34
- }
35
-
36
- /** The family and revision, read from core. */
37
- get identity() {
38
- return identityOf(core.definition_inspect(this.#native, this.id).identity);
39
- }
40
-
41
- /**
42
- * True once retire() has run. Core frees a retired definition as soon as
43
- * no resident actor uses it, and a freed definition's ID is stale, so
44
- * `not-found` also means retired: nothing else frees a registered
45
- * definition while its system is open.
46
- */
47
- get retired() {
48
- try {
49
- return core.definition_inspect(this.#native, this.id).retired;
50
- } catch (error) {
51
- if (error instanceof TinyactorsError && error.code === 'not-found') {
52
- return true;
53
- }
54
- throw error;
55
- }
56
- }
57
-
58
- /** A snapshot of core's view of this definition. */
59
- inspect() {
60
- const view = core.definition_inspect(this.#native, this.id);
61
- const inspection = {
62
- id: view.id,
63
- identity: identityOf(view.identity),
64
- datamodel: view.datamodel,
65
- binding: view.binding,
66
- retired: view.retired,
67
- actorCount: view.actor_count,
68
- stateCount: view.state_count,
69
- actorFixedBytes: view.actor_fixed_bytes,
70
- definitionBytes: view.definition_bytes,
71
- holds: view.holds,
72
- nestedBy: view.holders,
73
- };
74
- // Nesting is reported from parent to child (core ADR 0078): a child can
75
- // be nested by several parents, so it names none.
76
- const nested = [];
77
- for (let invoke = 0; invoke < view.invoke_count; invoke += 1) {
78
- const child = core.definition_invoke(this.#native, this.id, invoke).nested;
79
- if (child !== undefined && BigInt(child) !== 0n) {
80
- nested.push(child);
81
- }
82
- }
83
- if (nested.length > 0) {
84
- inspection.nested = nested;
85
- }
86
- if (view.document_name !== undefined && view.document_name !== '') {
87
- inspection.name = view.document_name;
88
- }
89
- return inspection;
90
- }
91
-
92
- /**
93
- * Where element `id` of `kind` ('state', 'transition', 'action' or
94
- * 'expression') was written (core ADR 0085): the file, and the line and
95
- * column of its builder call, or undefined when the definition keeps no
96
- * span for it. A chart built with statechart() records every state,
97
- * transition, initial transition and action; IDs are core's, as in
98
- * inspect() and trace records.
99
- */
100
- sourceOf(kind, id) {
101
- let found;
102
- try {
103
- found = core.definition_span(this.#native, this.id, kind, id);
104
- } catch (error) {
105
- if (error instanceof TinyactorsError && error.code === 'not-found') {
106
- return undefined;
107
- }
108
- throw error;
109
- }
110
- const { span, source } = found;
111
- // Core keeps zero for a column the front end did not know (a spec's
112
- // span may give only a line); the place leaves it out.
113
- const place = { source: source ?? '', line: span.line };
114
- if (span.column !== undefined && span.column !== 0) {
115
- place.column = span.column;
116
- }
117
- if (span.end_line !== undefined && span.end_line !== 0) {
118
- place.endLine = span.end_line;
119
- if (span.end_column !== undefined && span.end_column !== 0) {
120
- place.endColumn = span.end_column;
121
- }
122
- }
123
- if (span.length !== undefined && span.length !== 0) {
124
- place.offset = Number(span.offset ?? 0n);
125
- place.length = span.length;
126
- }
127
- return place;
128
- }
129
-
130
- /**
131
- * Prevent new actors from using this definition. Actors that use it keep
132
- * running; core frees it when the last one is gone. Idempotent.
133
- */
134
- retire() {
135
- core.system_retire_definition(this.#native, this.id);
136
- }
137
- }
138
-
139
- module.exports = { Definition, identityOf };
package/lib/errors.js DELETED
@@ -1,24 +0,0 @@
1
- 'use strict';
2
-
3
- // TinyactorsError (ADR 0008). API calls throw it synchronously for misuse,
4
- // such as wrong argument types or a closed system; the pump never throws.
5
- //
6
- // `code` is a TinyactorsErrorCode string. Native code derives codes from core
7
- // results; step 3 generates that table from the API description.
8
-
9
- const native = require('./native');
10
-
11
- class TinyactorsError extends Error {
12
- constructor(message, code, detail) {
13
- super(message);
14
- this.name = 'TinyactorsError';
15
- this.code = code;
16
- if (detail !== undefined) {
17
- this.detail = detail;
18
- }
19
- }
20
- }
21
-
22
- native.setup(TinyactorsError);
23
-
24
- module.exports = { TinyactorsError };
package/lib/events.js DELETED
@@ -1,56 +0,0 @@
1
- 'use strict';
2
-
3
- // Event-name cache: text -> ta_event_name_id (ADR 0004).
4
- //
5
- // One cache per system. A miss makes a single native call that validates and
6
- // interns the dotted name; a name seen before does no string work at all, and
7
- // native post paths take the numeric ID. Core interning is monotonic, so an
8
- // entry never goes stale. The cache grows with the number of distinct names
9
- // the application uses, not with traffic.
10
-
11
- const { TinyactorsError } = require('./errors');
12
- const { core } = require('./native');
13
-
14
- class EventNames {
15
- #native;
16
- #ids = new Map();
17
- #names = new Map();
18
-
19
- constructor(native) {
20
- this.#native = native;
21
- }
22
-
23
- /** The ta_event_name_id of `name`, interning it on first use. */
24
- id(name) {
25
- let id = this.#ids.get(name);
26
- if (id === undefined) {
27
- if (typeof name !== 'string') {
28
- throw new TinyactorsError('an event name must be a string', 'invalid');
29
- }
30
- id = this.#native.internEvent(name);
31
- this.#ids.set(name, id);
32
- }
33
- return id;
34
- }
35
-
36
- /**
37
- * The dotted text of a name core reports (inspections, events), formatted
38
- * once per ID and cached (ADR 0004 point 3).
39
- */
40
- name(id) {
41
- let text = this.#names.get(id);
42
- if (text === undefined) {
43
- text = core.event_name_format(this.#native, id);
44
- this.#names.set(id, text);
45
- this.#ids.set(text, id);
46
- }
47
- return text;
48
- }
49
-
50
- /** Distinct names interned through this cache. */
51
- get size() {
52
- return this.#ids.size;
53
- }
54
- }
55
-
56
- module.exports = { EventNames };
package/lib/image.js DELETED
@@ -1,90 +0,0 @@
1
- 'use strict';
2
-
3
- // Session images (ROADMAP step 14; core ADRs 0013, 0038, 0051, 0052). A
4
- // SessionImage wraps core's ta_session_image handle, captured in memory. The
5
- // handle's finalizer calls ta_session_image_destroy (ADR 0013 point 5), and
6
- // close() destroys every image still alive, so an image never outlives its
7
- // system (ADR 0012). Values the image holds (queued events, delayed-send
8
- // data) are value boxes (ADR 0011) and are released with it.
9
- //
10
- // Core's image does not hold the data-model root: load() and reconstruct()
11
- // bind one. The image keeps the root the actor had when it was captured, and
12
- // load() and reconstruct() use it unless given another binding. It is the
13
- // same object, not a copy: reconstructing an image of an actor that still
14
- // runs shares that actor's data unless a binding is passed.
15
-
16
- const native = require('./native');
17
- const { TinyactorsError } = require('./errors');
18
-
19
- const { core } = native;
20
-
21
- let handleOfImage;
22
-
23
- class SessionImage {
24
- #handle;
25
- #destroyed = false;
26
-
27
- static {
28
- handleOfImage = (image) => image.#handle;
29
- }
30
-
31
- constructor(system, handle, info) {
32
- this.origin = system;
33
- this.#handle = handle;
34
- /** The actor at capture; its ID goes stale once it is unloaded (core ADR 0066). */
35
- this.actor = info.actor;
36
- /** Stable across unload and load (core ADR 0066). */
37
- this.sessionID = info.sessionID;
38
- this.definition = info.definition;
39
- if (info.address !== undefined) {
40
- this.address = info.address;
41
- }
42
- /** The data-model root at capture, or undefined under the null data model. */
43
- this.data = info.data;
44
- }
45
-
46
- /** The earliest pending delayed send's due time, or undefined when none is pending. */
47
- get nextDeadline() {
48
- if (this.destroyed) {
49
- return undefined;
50
- }
51
- try {
52
- return core.session_image_next_deadline(this.#handle);
53
- } catch (error) {
54
- if (error instanceof TinyactorsError && error.code === 'not-found') {
55
- return undefined;
56
- }
57
- throw error;
58
- }
59
- }
60
-
61
- /** True once destroy() ran or the origin system closed. */
62
- get destroyed() {
63
- return this.#destroyed || this.origin.closed;
64
- }
65
-
66
- /** Release the image and the values it holds. Idempotent. */
67
- destroy() {
68
- if (!this.destroyed) {
69
- core.session_image_destroy(this.#handle);
70
- }
71
- this.#destroyed = true;
72
- }
73
-
74
- [Symbol.dispose]() {
75
- this.destroy();
76
- }
77
- }
78
-
79
- // The core handle of a live image of `system` (load, unload, reconstruct).
80
- function handleOf(image, system, caller) {
81
- if (!(image instanceof SessionImage) || image.origin !== system) {
82
- throw new TinyactorsError(`${caller}: expected a SessionImage captured in this system`, 'invalid');
83
- }
84
- if (image.destroyed) {
85
- throw new TinyactorsError(`${caller}: the image was destroyed`, 'invalid');
86
- }
87
- return handleOfImage(image);
88
- }
89
-
90
- module.exports = { SessionImage, handleOf };
package/lib/loader.js DELETED
@@ -1,68 +0,0 @@
1
- 'use strict';
2
-
3
- // Finds the compiled addon (docs/adr/0001-packaging-and-releases.md). An npm
4
- // install brings one platform package, the optional dependency whose `os`
5
- // and `cpu` match: `@tinyactors/node-<platform>-<arch>`, whose `main` is its
6
- // `tinyactors.node`. In the repository there is none, and the addon is the
7
- // one `mise run build` wrote. No libc is detected: the Linux addon links no
8
- // C library and serves glibc and musl alike.
9
-
10
- const fs = require('node:fs');
11
- const path = require('node:path');
12
-
13
- const SUPPORTED = ['darwin-arm64', 'darwin-x64', 'linux-x64', 'linux-arm64'];
14
- const REPOSITORY_BUILD = path.join(__dirname, '..', 'build', 'tinyactors_napi.node');
15
-
16
- function packageName(platform, arch) {
17
- return `@tinyactors/node-${platform}-${arch}`;
18
- }
19
-
20
- // Where `name` is installed, seen from `paths` (default: this package), or
21
- // undefined when it is not. A package counts as installed when its
22
- // package.json resolves, so one whose addon is missing or broken fails
23
- // loudly instead of falling back.
24
- function installed(name, paths) {
25
- try {
26
- return require.resolve(`${name}/package.json`, paths === undefined ? undefined : { paths });
27
- } catch (error) {
28
- if (error.code === 'MODULE_NOT_FOUND') {
29
- return undefined;
30
- }
31
- throw error;
32
- }
33
- }
34
-
35
- /**
36
- * Loads the addon: the platform package for `platform` and `arch` when it
37
- * is installed, else the repository build. An installed package that fails
38
- * to load throws its own error. With neither, one error names the package
39
- * looked for and the platforms there are packages for. The options exist
40
- * for tests.
41
- */
42
- function loadAddon({
43
- platform = process.platform,
44
- arch = process.arch,
45
- paths = undefined,
46
- repositoryBuild = REPOSITORY_BUILD,
47
- } = {}) {
48
- const name = packageName(platform, arch);
49
- const manifest = installed(name, paths);
50
- if (manifest !== undefined) {
51
- return require(path.dirname(manifest));
52
- }
53
- if (fs.existsSync(repositoryBuild)) {
54
- return require(repositoryBuild);
55
- }
56
- const supported = SUPPORTED.includes(`${platform}-${arch}`);
57
- const error = new Error(
58
- `tinyactors: no native addon for ${platform}-${arch}: ${name} is not installed` +
59
- (supported
60
- ? ' (it is an optional dependency of @tinyactors/node: install without --no-optional or --omit=optional)'
61
- : ' (there is no package for this platform)') +
62
- `. Platforms with a package: ${SUPPORTED.join(', ')}.`,
63
- );
64
- error.code = 'ERR_TINYACTORS_NO_ADDON';
65
- throw error;
66
- }
67
-
68
- module.exports = { loadAddon, packageName, SUPPORTED };