@tinyactors/wasm 0.0.0-stage → 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.
package/index.mjs ADDED
@@ -0,0 +1,11 @@
1
+ // @tinyactors/wasm: the package's names, its module loaded with top-level
2
+ // await (the bundled tinyactors.wasm, beside this file), so
3
+ // `import { Host } from '@tinyactors/wasm'` is the line it is in Node: the
4
+ // direct layer (lib/direct.mjs) and the convenience layer over it
5
+ // (../lib/convenience.mjs, which imports `#direct`).
6
+ import { init } from './lib/state.mjs';
7
+
8
+ await init();
9
+
10
+ export * from './lib/direct.mjs';
11
+ export * from './lib/convenience.mjs';
package/init.d.ts ADDED
@@ -0,0 +1,16 @@
1
+ // The types of @tinyactors/wasm/init: the package's names (index.d.ts, one
2
+ // API for both packages) and init(), which loads the WebAssembly module
3
+ // that @tinyactors/wasm's default entry loads with top-level await.
4
+ export * from './index.js';
5
+
6
+ /** Loads the WebAssembly module, once: every later call answers the same
7
+ * instance, whatever it passes. `source` is where the module is: the
8
+ * package's own `tinyactors.wasm` beside its files when absent, a URL (a
9
+ * string relative to the package's files), a `Response` or a promise of
10
+ * one, the bytes, or a compiled `WebAssembly.Module`. Use this entry where
11
+ * a module graph cannot hold top-level await (a Service Worker) or a
12
+ * bundler does not place `tinyactors.wasm`; until the promise settles,
13
+ * every call of the package throws `TinyactorsError` with
14
+ * `TA_ERROR_STATE`. A load that fails rejects, and a later call may try
15
+ * again. */
16
+ export function init(source?: string | URL | Response | PromiseLike<Response> | BufferSource | WebAssembly.Module): Promise<void>;
package/init.mjs ADDED
@@ -0,0 +1,7 @@
1
+ // @tinyactors/wasm/init: the package's names and `await init(url?)`, for a
2
+ // Service Worker (which refuses a module graph with top-level await) and
3
+ // for bundlers that do not handle it. A call before init() settles throws
4
+ // TA_ERROR_STATE.
5
+ export { init } from './lib/state.mjs';
6
+ export * from './lib/direct.mjs';
7
+ export * from './lib/convenience.mjs';
@@ -0,0 +1,112 @@
1
+ // Address, as the addon defines it (src/address.c): an actor's address,
2
+ // immutable. It holds its text, an own read-only property `text`; its parts
3
+ // are read by core's parser on each access (ta_address_parse,
4
+ // ta_address_name_decode, wasm/src/codecs.c), undefined for a part the
5
+ // text lacks, so no binding parses the grammar. Address.fromSession and
6
+ // Address.fromName make one with core's formatter. The calls' scratch is
7
+ // the environment's arena, a mark per call. A private brand stands for the
8
+ // addon's type tag: a getter on another object is refused.
9
+ import { refusal } from './errors.mjs';
10
+ import { instance } from './state.mjs';
11
+ import { sessionOf } from './checks.mjs';
12
+
13
+ const KIND_SESSION = 1, KIND_NAME = 2;
14
+ const utf8 = new TextDecoder('utf-8', { fatal: true });
15
+
16
+ export class Address {
17
+ #brand = true;
18
+
19
+ constructor(text) {
20
+ if (new.target === undefined) throw new TypeError('Address is a class: new Address(text)');
21
+ if (typeof text !== 'string') throw new TypeError('an Address is made of its text, a string');
22
+ Object.defineProperty(this, 'text', { value: text, enumerable: true });
23
+ Object.freeze(this);
24
+ }
25
+
26
+ static #is(value) {
27
+ return value !== null && typeof value === 'object' && #brand in value;
28
+ }
29
+
30
+ static is(value) { return Address.#is(value); }
31
+
32
+ // The parts of `self`'s text: a function of the module, or undefined
33
+ // when it is no address; `part` reads them in the environment's arena.
34
+ static #parts(self, part) {
35
+ if (!Address.#is(self)) throw new TypeError('not an Address');
36
+ const module = instance();
37
+ const scratch = module.scratch;
38
+ return module.scoped(scratch, () => {
39
+ const [at, length] = module.text(scratch, self.text);
40
+ module.setWord(0, at);
41
+ module.setWord(1, length);
42
+ if (module.call('ta_web_address_parse', module.env) !== 0) return undefined;
43
+ return part(module);
44
+ });
45
+ }
46
+
47
+ get system() {
48
+ return Address.#parts(this, (module) => module.string(module.word(1), module.word(2)));
49
+ }
50
+
51
+ get session() {
52
+ return Address.#parts(this, (module) => (module.word(0) === KIND_SESSION ? module.word64(3) : undefined));
53
+ }
54
+
55
+ get name() {
56
+ return Address.#parts(this, (module) => {
57
+ if (module.word(0) !== KIND_NAME) return undefined;
58
+ module.setWord(0, module.word(5));
59
+ module.setWord(1, module.word(6));
60
+ const status = module.call('ta_web_address_name', module.env);
61
+ if (status !== 0) throw refusal(module.statusName(status), 'the address\'s name does not decode');
62
+ try {
63
+ return utf8.decode(module.bytes().subarray(module.word(0), module.word(0) + module.word(1)));
64
+ } catch {
65
+ throw refusal('TA_ERROR_INVALID', 'the address\'s name is not UTF-8');
66
+ }
67
+ });
68
+ }
69
+
70
+ toString() {
71
+ if (!Address.#is(this)) throw new TypeError('not an Address');
72
+ return this.text;
73
+ }
74
+
75
+ static fromSession(system, session) {
76
+ if (arguments.length < 2) throw new TypeError('Address.fromSession(system, session)');
77
+ if (typeof system !== 'string') throw new TypeError('a system id is a string');
78
+ const id = sessionOf(session);
79
+ return Address.#format(KIND_SESSION, system, (module) => module.setWord64(2, id));
80
+ }
81
+
82
+ static fromName(system, name) {
83
+ if (arguments.length < 2) throw new TypeError('Address.fromName(system, name)');
84
+ if (typeof system !== 'string') throw new TypeError('a system id is a string');
85
+ if (typeof name !== 'string') throw new TypeError('an actor\'s name is a string');
86
+ return Address.#format(KIND_NAME, system, (module, scratch) => {
87
+ const [at, length] = module.text(scratch, name);
88
+ module.setWord(2, at);
89
+ module.setWord(3, length);
90
+ });
91
+ }
92
+
93
+ static #format(kind, system, fill) {
94
+ const module = instance();
95
+ const scratch = module.scratch;
96
+ return module.scoped(scratch, () => {
97
+ const [at, length] = module.text(scratch, system);
98
+ fill(module, scratch);
99
+ module.setWord(0, at);
100
+ module.setWord(1, length);
101
+ const status = module.call('ta_web_address_format', module.env, kind);
102
+ if (status !== 0) throw refusal(module.statusName(status), 'core refused the address\'s parts');
103
+ return new Address(module.string(module.word(0), module.word(1)));
104
+ });
105
+ }
106
+ }
107
+
108
+ // Whether `value` is an Address: the layer's, not the API's.
109
+ export const isAddress = Address.is;
110
+ delete Address.is;
111
+ // An Address's text, or `value` itself.
112
+ export const addressText = (value) => (isAddress(value) ? value.text : value);
package/lib/cbor.mjs ADDED
@@ -0,0 +1,262 @@
1
+ // The value table (docs/values.md; tinyactors-core/docs/protocol.md,
2
+ // "Values") over CBOR tokens: core's ta_cbor_writer and ta_cbor_reader in C
3
+ // (wasm/src/cbor.c) write and read one token per call, and this file makes
4
+ // the JavaScript values and refuses what the table has no row for, as the
5
+ // addon's src/values.c does:
6
+ //
7
+ // undefined, null, true, false simple values 23, 22, 21, 20
8
+ // a number an integer when Number.isSafeInteger holds
9
+ // and it is not -0, else a float
10
+ // a bigint an integer, -2^64 to 2^64-1
11
+ // a string text, valid UTF-8: a lone surrogate refused
12
+ // a Uint8Array bytes (another typed array refused)
13
+ // an array an array, holes as undefined
14
+ // a plain object a map of its own enumerable string keys,
15
+ // in Object.keys order (its prototype
16
+ // Object.prototype or null)
17
+ // an Address with `addresses`, tag 32 on its text
18
+ // (encode); else refused as a class's instance
19
+ //
20
+ // and back: integers within +-(2^53-1) numbers, others bigints; bytes a
21
+ // Uint8Array; tag 32 on text an Address with `addresses` (decode), else its
22
+ // text. Refused: TA_ERROR_UNSUPPORTED for a value outside the table (a
23
+ // function, a symbol, a Date, a class's instance), TA_ERROR_INVALID for one
24
+ // it cannot hold (a bigint past 64 bits, a lone surrogate, nesting deeper
25
+ // than 64, which a cycle reaches) and for malformed CBOR. Core checks
26
+ // UTF-8, nesting and the shortest forms.
27
+ import { Address, addressText, isAddress } from './address.mjs';
28
+ import { TinyactorsError } from './errors.mjs';
29
+
30
+ const UINT = 1, NEGINT = 2, BYTES = 3, TEXT = 4, ARRAY = 5, MAP = 6, TAG = 7, SIMPLE = 8, FLOAT = 9, END = 16;
31
+ const WIDE = 0x100;
32
+ const LATER = 0xFFFFFFFF; // TA_CBOR_COUNT_LATER: closed by an END
33
+ const DEPTH = 64;
34
+ const SAFE = Number.MAX_SAFE_INTEGER;
35
+
36
+ const refuse = (status, message) => new TinyactorsError(message, { status });
37
+ const UNSUPPORTED_OBJECT = 'only plain objects, arrays and Uint8Arrays are values (docs/values.md)';
38
+
39
+ // Whether `prototype` is an Object.prototype, of this realm or another one
40
+ // (the native datamodel's realms): its own constructor is the native
41
+ // Object and it has no prototype (the addon's src/values.c, `realms`).
42
+ const nativeSource = Function.prototype.toString;
43
+ function objectPrototype(prototype) {
44
+ if (prototype === Object.prototype) return true;
45
+ if (Object.getPrototypeOf(prototype) !== null || !Object.hasOwn(prototype, 'constructor')) return false;
46
+ const made = prototype.constructor;
47
+ return typeof made === 'function' && made.prototype === prototype && made.name === 'Object' &&
48
+ nativeSource.call(made).includes('[native code]');
49
+ }
50
+ const tagOf = Object.prototype.toString;
51
+
52
+ // Writes `value` with a writer in `scratch` (a host's arena or the
53
+ // environment's, above the caller's mark); answers [pointer, length] of the
54
+ // bytes, a view valid until the call's leave. `addresses`: an Address is
55
+ // tag 32 on its text (encode, and a payload toward quickjs). `realms`: a
56
+ // plain object or a Uint8Array of another realm is one too (the native
57
+ // datamodel's values). `wire`: to_wire's mode (the addon's src/values.c):
58
+ // what JSON.stringify leaves out (undefined, a function, a symbol) is null
59
+ // at the top and in an array and drops its key in an object, toJSON is
60
+ // applied, an ArrayBuffer, a typed array and a DataView are their bytes,
61
+ // any other object the map of its own enumerable string keys; its
62
+ // refusals are TA_ERROR_INVALID.
63
+ export function write(module, scratch, value, { addresses = false, realms = false, wire = false } = {}) {
64
+ if (wire) realms = true;
65
+ const writer = module.call('ta_web_writer_new', module.env, scratch);
66
+ if (writer === 0) throw refuse('TA_ERROR_NO_MEMORY', 'no memory for a CBOR writer');
67
+ const exports = module.fn;
68
+ const token = (kind, number) => exports.ta_web_write(writer, kind, number);
69
+ const integer = (negative, n) => {
70
+ // n: the CBOR argument (a number below 2^53 or a bigint)
71
+ if (typeof n === 'number' && n <= 0xFFFFFFFF) return token(negative ? NEGINT : UINT, n);
72
+ module.setWord64(0, n);
73
+ return token((negative ? NEGINT : UINT) | WIDE, 0);
74
+ };
75
+ const text = (string) => {
76
+ const [at, length] = module.text(scratch, string);
77
+ module.setWord(0, at);
78
+ module.setWord(1, length);
79
+ token(TEXT, 0);
80
+ };
81
+ const bytes = (view) => {
82
+ const [at, length] = module.copyIn(scratch, view);
83
+ module.setWord(0, at);
84
+ module.setWord(1, length);
85
+ return token(BYTES, 0);
86
+ };
87
+ // wire mode: toJSON applied, as JSON.stringify applies it (each call a level)
88
+ const resolved = (v, depth) => {
89
+ for (;;) {
90
+ if (depth.n > DEPTH) throw refuse('TA_ERROR_INVALID', 'a value nested deeper than 64 (or a cycle)');
91
+ if (v === null || typeof v !== 'object' || ArrayBuffer.isView(v) || tagOf.call(v) === '[object ArrayBuffer]') return v;
92
+ const toJSON = v.toJSON;
93
+ if (typeof toJSON !== 'function') return v;
94
+ v = toJSON.call(v, '');
95
+ depth.n++;
96
+ }
97
+ };
98
+ const dropped = (v) => v === undefined || typeof v === 'function' || typeof v === 'symbol';
99
+ const put = (v, depth) => {
100
+ if (depth > DEPTH) throw refuse('TA_ERROR_INVALID', 'a value nested deeper than 64 (or a cycle)');
101
+ if (wire && v !== null && typeof v === 'object' && !Array.isArray(v)) {
102
+ if (ArrayBuffer.isView(v)) return bytes(new Uint8Array(v.buffer, v.byteOffset, v.byteLength));
103
+ if (tagOf.call(v) === '[object ArrayBuffer]') return bytes(new Uint8Array(v));
104
+ token(MAP, LATER);
105
+ for (const key of Object.keys(v)) {
106
+ const at = { n: depth + 1 };
107
+ const item = resolved(v[key], at);
108
+ if (dropped(item)) continue;
109
+ text(key);
110
+ put(item, at.n);
111
+ }
112
+ return token(END, 0);
113
+ }
114
+ switch (typeof v) {
115
+ case 'undefined': return token(SIMPLE, 23);
116
+ case 'boolean': return token(SIMPLE, v ? 21 : 20);
117
+ case 'number':
118
+ if (Number.isSafeInteger(v) && !Object.is(v, -0)) return v >= 0 ? integer(false, v) : integer(true, -1 - v);
119
+ module.setWordFloat(0, v);
120
+ return token(FLOAT, 0);
121
+ case 'bigint': {
122
+ if (v >= 0n) {
123
+ if (v >= 1n << 64n) throw refuse('TA_ERROR_INVALID', 'a bigint past 64 bits');
124
+ return integer(false, v <= BigInt(SAFE) ? Number(v) : v);
125
+ }
126
+ const n = -1n - v;
127
+ if (n >= 1n << 64n) throw refuse('TA_ERROR_INVALID', 'a bigint past 64 bits');
128
+ return integer(true, n <= BigInt(SAFE) ? Number(n) : n);
129
+ }
130
+ case 'string': return text(v);
131
+ case 'object': {
132
+ if (v === null) return token(SIMPLE, 22);
133
+ if (Array.isArray(v)) {
134
+ token(ARRAY, LATER);
135
+ for (let i = 0, n = v.length; i < n; i++) {
136
+ if (!wire) {
137
+ put(v[i], depth + 1);
138
+ continue;
139
+ }
140
+ const at = { n: depth + 1 };
141
+ const item = resolved(v[i], at);
142
+ if (dropped(item)) token(SIMPLE, 22);
143
+ else put(item, at.n);
144
+ }
145
+ return token(END, 0);
146
+ }
147
+ if (ArrayBuffer.isView(v)) {
148
+ if (!(v instanceof Uint8Array) && !(realms && tagOf.call(v) === '[object Uint8Array]')) {
149
+ throw refuse('TA_ERROR_UNSUPPORTED', 'bytes are a Uint8Array, not another typed array');
150
+ }
151
+ return bytes(v);
152
+ }
153
+ if (addresses && isAddress(v)) {
154
+ token(TAG, 32);
155
+ return text(addressText(v));
156
+ }
157
+ const prototype = Object.getPrototypeOf(v);
158
+ if (prototype !== null && prototype !== Object.prototype && !(realms && objectPrototype(prototype))) {
159
+ throw refuse('TA_ERROR_UNSUPPORTED', UNSUPPORTED_OBJECT);
160
+ }
161
+ token(MAP, LATER);
162
+ for (const key of Object.keys(v)) {
163
+ const item = v[key];
164
+ text(key);
165
+ put(item, depth + 1);
166
+ }
167
+ return token(END, 0);
168
+ }
169
+ default:
170
+ throw refuse('TA_ERROR_UNSUPPORTED', 'a function, a symbol or an external is not a value (docs/values.md)');
171
+ }
172
+ };
173
+ if (wire) {
174
+ try {
175
+ const at = { n: 0 };
176
+ const top = resolved(value, at);
177
+ if (dropped(top)) token(SIMPLE, 22);
178
+ else put(top, at.n);
179
+ } catch (error) {
180
+ if (error instanceof TinyactorsError && error.status !== 'TA_ERROR_NO_MEMORY') {
181
+ throw refuse('TA_ERROR_INVALID', error.message);
182
+ }
183
+ throw error;
184
+ }
185
+ } else put(value, 0);
186
+ const status = module.call('ta_web_writer_bytes', writer);
187
+ if (status !== 0) {
188
+ throw refuse(module.statusName(status), status === -4 ? 'no memory for the encoded value' : 'the CBOR writer refused the value');
189
+ }
190
+ return [module.word(0), module.word(1)];
191
+ }
192
+
193
+ // The value of the CBOR at [pointer, length] (in linear memory, valid while
194
+ // it reads), read with a reader in `scratch`, nothing after it.
195
+ // `addresses`: tag 32 is an Address (decode), else its text.
196
+ export function read(module, scratch, pointer, length, { addresses = false } = {}) {
197
+ module.setWord(0, pointer);
198
+ module.setWord(1, length);
199
+ const reader = module.call('ta_web_reader_new', module.env, scratch);
200
+ if (reader === 0) throw refuse('TA_ERROR_NO_MEMORY', 'no memory for a CBOR reader');
201
+ const exports = module.fn;
202
+ const malformed = (got) => refuse(module.statusName(got < 0 ? got : -3), 'malformed or truncated CBOR');
203
+ const step = () => {
204
+ const got = exports.ta_web_read(reader);
205
+ if (got !== 1) throw malformed(got);
206
+ };
207
+ const next = () => {
208
+ step();
209
+ const kind = module.word(0), count = module.word(1);
210
+ switch (kind) {
211
+ case UINT: {
212
+ const high = module.word(3);
213
+ if (high < 0x200000) return high * 0x100000000 + module.word(2);
214
+ return module.word64(2);
215
+ }
216
+ case NEGINT: {
217
+ const high = module.word(3);
218
+ if (high < 0x1FFFFF || (high === 0x1FFFFF && module.word(2) < 0xFFFFFFFF)) return -1 - (high * 0x100000000 + module.word(2));
219
+ return -1n - module.word64(2);
220
+ }
221
+ case BYTES: return module.copyOut(module.word(4), module.word(5));
222
+ case TEXT: return module.string(module.word(4), module.word(5));
223
+ case ARRAY: {
224
+ const out = new Array(count);
225
+ for (let i = 0; i < count; i++) out[i] = next();
226
+ return out;
227
+ }
228
+ case MAP: {
229
+ const out = {};
230
+ for (let i = 0; i < count; i++) {
231
+ step();
232
+ if (module.word(0) !== TEXT) throw refuse('TA_ERROR_INVALID', 'a map key that is not text');
233
+ const key = module.string(module.word(4), module.word(5));
234
+ // defined, not set: "__proto__" is an own key and no setter runs
235
+ Object.defineProperty(out, key, { value: next(), enumerable: true, writable: true, configurable: true });
236
+ }
237
+ return out;
238
+ }
239
+ case TAG: {
240
+ if (module.word(2) !== 32 || module.word(3) !== 0) throw refuse('TA_ERROR_INVALID', 'a tag other than 32');
241
+ step();
242
+ if (module.word(0) !== TEXT) throw refuse('TA_ERROR_INVALID', 'tag 32 on something but text');
243
+ const text = module.string(module.word(4), module.word(5));
244
+ return addresses ? new Address(text) : text;
245
+ }
246
+ case SIMPLE:
247
+ switch (module.word(2)) {
248
+ case 20: return false;
249
+ case 21: return true;
250
+ case 22: return null;
251
+ case 23: return undefined;
252
+ default: throw refuse('TA_ERROR_INVALID', 'a simple value other than false, true, null, undefined');
253
+ }
254
+ case FLOAT: return module.wordFloat(2);
255
+ default: throw refuse('TA_ERROR_INVALID', 'an item the value table has no row for');
256
+ }
257
+ };
258
+ const value = next();
259
+ const after = exports.ta_web_read(reader);
260
+ if (after !== 0) throw refuse(module.statusName(after < 0 ? after : -3), 'bytes after the item');
261
+ return value;
262
+ }
package/lib/checks.mjs ADDED
@@ -0,0 +1,54 @@
1
+ // The checks of the API's arguments, as the addon makes them (src/host.c,
2
+ // src/values.c): each a TypeError naming what was expected, never a value
3
+ // wrapped or saturated.
4
+
5
+ // A session an input takes: a bigint from 1 to 2^64-1, or a number that is
6
+ // a safe integer from 1; as a bigint.
7
+ export function sessionOf(value) {
8
+ if (typeof value === 'bigint') {
9
+ if (value >= 1n && value < 1n << 64n) return value;
10
+ } else if (typeof value === 'number' && Number.isSafeInteger(value) && value >= 1) return BigInt(value);
11
+ throw new TypeError('a session is a bigint from 1 to 2^64-1 or a safe integer from 1');
12
+ }
13
+
14
+ // A non-negative integer at most `limit` (2^32-1 unless said).
15
+ export function countOf(value, what, limit = 4294967295) {
16
+ if (typeof value === 'number' && Number.isInteger(value) && value >= 0 && value <= limit) return value;
17
+ throw new TypeError(what);
18
+ }
19
+
20
+ // Bytes in: a Uint8Array (a Buffer too) or an ArrayBuffer, as a Uint8Array
21
+ // over the same memory.
22
+ export function bytesOf(value, what) {
23
+ if (value instanceof Uint8Array) return value;
24
+ if (value instanceof ArrayBuffer) return new Uint8Array(value);
25
+ throw new TypeError(what);
26
+ }
27
+
28
+ // Text: a string, else a TypeError naming `what`.
29
+ export function textOf(value, what) {
30
+ if (typeof value !== 'string') throw new TypeError(what);
31
+ return value;
32
+ }
33
+
34
+ // Optional text: undefined and null are none (''), else a string.
35
+ export function optionalText(value, what) {
36
+ if (value === undefined || value === null) return '';
37
+ return textOf(value, what);
38
+ }
39
+
40
+ // Every own key of `object` one of `names`: an option misspelled is
41
+ // refused, not ignored.
42
+ export function onlyKnown(object, names, what) {
43
+ for (const key of Object.keys(object)) {
44
+ if (!names.includes(key)) throw new TypeError(`unknown ${what}: ${key}`);
45
+ }
46
+ }
47
+
48
+ // Options of an input: undefined, or an object of `names`.
49
+ export function inputOptions(value, names, what) {
50
+ if (value === undefined) return undefined;
51
+ if (value === null || typeof value !== 'object') throw new TypeError('options are an object');
52
+ onlyKnown(value, names, what);
53
+ return value;
54
+ }