@tinyactors/wasm 0.0.0-stage → 0.4.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/realms.mjs ADDED
@@ -0,0 +1,122 @@
1
+ // The realms of the native "ecmascript" datamodel (docs/browser.md, "The
2
+ // native datamodel without node:vm"): where a host's charts evaluate, never
3
+ // the application's realm where the runtime gives another one.
4
+ //
5
+ // node, bun a node:vm context (process.getBuiltinModule), as the addon's;
6
+ // a page a hidden same-origin iframe, one per host, removed when the
7
+ // host is freed (close(), or the FinalizationRegistry);
8
+ // a Worker the worker's own global: a Worker has no document, so an
9
+ // application that wants its charts apart from its own code
10
+ // gives tinyactors a worker of its own (the README says so).
11
+ //
12
+ // Every realm runs the realm's script (src/datamodel/realm.js, the addon's
13
+ // own, embedded as text by mise/wasm.rb into realm-script.mjs) for its
14
+ // kit: what must be made with that realm's constructors (copies of values,
15
+ // scopes, _event, XML nodes) is made by the kit's functions. The
16
+ // application's realm gets a kit of its own, for the values it reads.
17
+ //
18
+ // A realm is made at the host's first chart, not at its creation (an
19
+ // iframe costs about 600 KB and 3.6 ms in Chromium); the policy a page
20
+ // runs under is checked at the host's creation (policyRefusal), in this
21
+ // module's realm, whose policy an iframe inherits.
22
+ import { Address } from './address.mjs';
23
+ import realmScript from './realm-script.mjs';
24
+
25
+ const REALM_NAME = 'tinyactors:realm.js';
26
+
27
+ // The node:vm module where the runtime has one (node, bun), else null.
28
+ function nodeVM() {
29
+ const getBuiltinModule = globalThis.process?.getBuiltinModule;
30
+ if (typeof getBuiltinModule !== 'function') return null;
31
+ try {
32
+ return getBuiltinModule('node:vm') ?? null;
33
+ } catch {
34
+ return null;
35
+ }
36
+ }
37
+
38
+ // What kind of realm this runtime gives a host: 'vm', 'iframe' or 'global'.
39
+ export function realmKind() {
40
+ if (nodeVM() !== null) return 'vm';
41
+ if (typeof globalThis.document?.createElement === 'function') return 'iframe';
42
+ return 'global';
43
+ }
44
+
45
+ // Why a host on the native datamodel cannot run here, or null: the native
46
+ // datamodel evaluates the charts' text, so it needs string evaluation
47
+ // (`'unsafe-eval'` in a Content Security Policy's script-src) and, on a
48
+ // page, an iframe of the page's own origin (a CSP or iframe `sandbox`
49
+ // without allow-same-origin gives the page an opaque origin); Trusted
50
+ // Types enforced (`require-trusted-types-for 'script'`) refuse a string to
51
+ // evaluate even with 'unsafe-eval'. In node and bun there is no policy.
52
+ export function policyRefusal() {
53
+ if (nodeVM() !== null) return null;
54
+ try {
55
+ // eslint-disable-next-line no-new-func
56
+ new Function('');
57
+ } catch (error) {
58
+ const text = String(error?.message ?? error);
59
+ if (/trusted/i.test(text)) {
60
+ return 'the page enforces Trusted Types (require-trusted-types-for \'script\'), which refuse the chart text ' +
61
+ 'the native datamodel evaluates: use datamodel "quickjs"';
62
+ }
63
+ return 'the page\'s Content Security Policy refuses string evaluation (its script-src has no \'unsafe-eval\'), ' +
64
+ 'which the native datamodel needs to evaluate the charts\' text: allow it, or use datamodel "quickjs"';
65
+ }
66
+ // a sandboxed page's opaque origin: its iframes are cross-origin to it
67
+ // (spike, Chromium 141: reading the iframe's eval is a SecurityError)
68
+ if (realmKind() === 'iframe' && globalThis.origin === 'null' && globalThis.location?.protocol !== 'file:') {
69
+ return 'the page runs under a sandbox (CSP or iframe) without allow-same-origin: its opaque origin gives the ' +
70
+ 'native datamodel no realm of its own; use datamodel "quickjs"';
71
+ }
72
+ return null;
73
+ }
74
+
75
+ // The kit of this module's realm, the application's: made once.
76
+ let applicationKit = null;
77
+ export function application() {
78
+ if (applicationKit === null) applicationKit = (0, eval)(realmScript)(() => false, Address);
79
+ return applicationKit;
80
+ }
81
+
82
+ // A new realm for a host, with `In` (the evaluating session's In()) given to
83
+ // its kit: {kind, global, evaluate(source, name), Function, kit, free()}.
84
+ // `evaluate` runs `source` as the realm's global code and answers its
85
+ // value; `Function` is the realm's own constructor.
86
+ export function makeRealm(In) {
87
+ const vm = nodeVM();
88
+ let realm;
89
+ if (vm !== null) {
90
+ const context = vm.createContext();
91
+ realm = {
92
+ kind: 'vm',
93
+ evaluate: (source, name) => vm.runInContext(source, context, { filename: name }),
94
+ free() {},
95
+ };
96
+ realm.global = realm.evaluate('globalThis', REALM_NAME);
97
+ } else if (realmKind() === 'iframe') {
98
+ const frame = globalThis.document.createElement('iframe');
99
+ frame.style.display = 'none';
100
+ frame.setAttribute('aria-hidden', 'true');
101
+ frame.setAttribute('data-tinyactors', 'realm');
102
+ (globalThis.document.body ?? globalThis.document.documentElement).appendChild(frame);
103
+ const window = frame.contentWindow;
104
+ realm = {
105
+ kind: 'iframe',
106
+ global: window,
107
+ // the iframe's eval called as its method: indirect, its global code
108
+ evaluate: (source) => window.eval(source),
109
+ free() { frame.remove(); },
110
+ };
111
+ } else {
112
+ realm = {
113
+ kind: 'global',
114
+ global: globalThis,
115
+ evaluate: (source) => (0, eval)(source),
116
+ free() {},
117
+ };
118
+ }
119
+ realm.Function = realm.evaluate('Function', REALM_NAME);
120
+ realm.kit = realm.evaluate(realmScript, REALM_NAME)(In, Address);
121
+ return realm;
122
+ }
package/lib/state.mjs ADDED
@@ -0,0 +1,32 @@
1
+ // The module instance the package's classes use: loaded once by init(),
2
+ // which both entries share (index.mjs awaits it at the top level;
3
+ // init.mjs leaves it to the application, for a Service Worker or a
4
+ // bundler without top-level await). A call before it settles throws
5
+ // TA_ERROR_STATE.
6
+ import { TinyactorsError } from './errors.mjs';
7
+ import { load } from './module.mjs';
8
+
9
+ let current = null;
10
+ let loading = null;
11
+
12
+ // Loads the module once: the bundled tinyactors.wasm, or `source` (a URL,
13
+ // a Response, bytes or a WebAssembly.Module). Later calls answer the same
14
+ // instance, whatever they pass.
15
+ export function init(source) {
16
+ if (loading === null) {
17
+ loading = load(source).then((module) => {
18
+ current = module;
19
+ return module;
20
+ }, (error) => {
21
+ loading = null;
22
+ throw error;
23
+ });
24
+ }
25
+ return loading.then(() => undefined);
26
+ }
27
+
28
+ // The instance, once init() settled.
29
+ export function instance() {
30
+ if (current === null) throw new TinyactorsError('@tinyactors/wasm is not loaded: await init() first', { status: 'TA_ERROR_STATE' });
31
+ return current;
32
+ }
package/lib/values.mjs ADDED
@@ -0,0 +1,31 @@
1
+ // encode and decode, as the addon defines them (src/values.c): the one
2
+ // conversion the API uses, streaming through core's writer and reader
3
+ // (cbor.mjs), the call's text and bytes in the environment's arena, a mark
4
+ // per call. encode writes an Address as tag 32 on its text, decode reads
5
+ // tag 32 as an Address.
6
+ import * as cbor from './cbor.mjs';
7
+ import { bytesOf } from './checks.mjs';
8
+ import { instance } from './state.mjs';
9
+
10
+ // encode(value) -> Uint8Array: the value's CBOR, copied once out of the
11
+ // call's arena.
12
+ export function encode(value) {
13
+ const module = instance();
14
+ const scratch = module.scratch;
15
+ return module.scoped(scratch, () => {
16
+ const [at, length] = cbor.write(module, scratch, value, { addresses: true });
17
+ return module.copyOut(at, length);
18
+ });
19
+ }
20
+
21
+ // decode(bytes) -> value: a Uint8Array or an ArrayBuffer, read during the
22
+ // call.
23
+ export function decode(bytes) {
24
+ const view = bytesOf(bytes, 'decode takes a Uint8Array or an ArrayBuffer');
25
+ const module = instance();
26
+ const scratch = module.scratch;
27
+ return module.scoped(scratch, () => {
28
+ const [at, length] = module.copyIn(scratch, view);
29
+ return cbor.read(module, scratch, at, length, { addresses: true });
30
+ });
31
+ }
@@ -0,0 +1,5 @@
1
+ // The version of the package installed: package.json's, written here by the
2
+ // release (mise/tasks/release) beside package.json's, and into each packed
3
+ // copy by mise/pack.rb (a development build's version too). A module, not
4
+ // a JSON import, so the package needs no JSON modules in a browser.
5
+ export const version = '0.4.0';
package/package.json CHANGED
@@ -1,6 +1,53 @@
1
1
  {
2
2
  "name": "@tinyactors/wasm",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.4.0",
4
+ "description": "SCXML statecharts as actors on the tinyactors host, in the browser, Node.js and Bun (WebAssembly; the API of @tinyactors/node)",
5
+ "keywords": [
6
+ "actor",
7
+ "actors",
8
+ "statechart",
9
+ "scxml",
10
+ "state-machine",
11
+ "wasm",
12
+ "webassembly",
13
+ "browser"
14
+ ],
15
+ "homepage": "https://github.com/tinyactors-dev/tinyactors-napi#readme",
16
+ "repository": {
17
+ "type": "git",
18
+ "url": "git+https://github.com/tinyactors-dev/tinyactors.git",
19
+ "directory": "tinyactors-napi"
20
+ },
21
+ "bugs": {
22
+ "url": "https://github.com/tinyactors-dev/tinyactors/issues"
23
+ },
24
+ "license": "MIT",
25
+ "engines": {
26
+ "node": ">=22.3.0"
27
+ },
28
+ "type": "module",
29
+ "types": "./index.d.ts",
30
+ "exports": {
31
+ ".": {
32
+ "types": "./index.d.ts",
33
+ "default": "./index.mjs"
34
+ },
35
+ "./init": {
36
+ "types": "./init.d.ts",
37
+ "default": "./init.mjs"
38
+ },
39
+ "./tinyactors.wasm": "./tinyactors.wasm",
40
+ "./package.json": "./package.json"
41
+ },
42
+ "sideEffects": false,
43
+ "files": [
44
+ "index.mjs",
45
+ "init.mjs",
46
+ "init.d.ts",
47
+ "lib",
48
+ "tinyactors.wasm",
49
+ "index.d.ts",
50
+ "README.md",
51
+ "LICENSE"
52
+ ]
53
+ }
Binary file