@provino/rpc 0.0.0-stage → 0.1.0-rc.1

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 Pixel Perfect Software
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 CHANGED
@@ -1,3 +1,9 @@
1
- # Temporary Holding Version
1
+ # @provino/rpc
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ A typed RPC between the coordinator and its workers: clone-safe method schemas over `MessagePort` and child-process IPC links.
4
+
5
+ This package is a building block of [Provino](https://github.com/pixel-perfect-software/provino), a test runner for Jest projects, on npm as [`provino`](https://www.npmjs.com/package/provino). The `provino` package ships every `@provino/*` package inlined in one bundle, so you install `provino`, not this package.
6
+
7
+ **Versioning:** this package is `@beta` as a whole. There is no semver promise for it before 1.0, and its API can change in any release.
8
+
9
+ [MIT](https://github.com/pixel-perfect-software/provino/blob/main/LICENSE)
@@ -0,0 +1,109 @@
1
+ import { MessageLink, RpcCall, RpcClient, RpcReply, RpcSchema, SerializedError } from "@provino/types";
2
+ import { ChildProcess } from "node:child_process";
3
+ import { MessagePort, Worker } from "node:worker_threads";
4
+ /**
5
+ * Error codes `@provino/rpc` uses. A caller sees `RPC_CLOSED` (the link went away, `cause` is why)
6
+ * and `RPC_REMOTE_ERROR` (the method threw, `remote` is what); `RPC_UNKNOWN_METHOD` and
7
+ * `RPC_UNCLONABLE` reach the caller as the `remote` error's `code`, or as the rejection's code when
8
+ * the caller's own arguments can't be sent.
9
+ * @public
10
+ */
11
+ type RpcErrorCode = "RPC_CLOSED" | "RPC_REMOTE_ERROR" | "RPC_UNKNOWN_METHOD" | "RPC_UNCLONABLE";
12
+ /**
13
+ * Options for an `RpcError`: `cause` as for any error, plus the remote error it reports.
14
+ * @public
15
+ */
16
+ interface RpcErrorOptions extends ErrorOptions {
17
+ readonly remote?: SerializedError;
18
+ }
19
+ /**
20
+ * An RPC failure with a stable code.
21
+ * @public
22
+ */
23
+ export declare class RpcError extends Error {
24
+ readonly code: RpcErrorCode;
25
+ /** For `RPC_REMOTE_ERROR`: the error the remote method threw, as it crossed the link. */
26
+ readonly remote?: SerializedError;
27
+ constructor(code: RpcErrorCode, message: string, options?: RpcErrorOptions);
28
+ }
29
+ /**
30
+ * A link over a `MessagePort`: a thread's `parentPort`, or either end of a `MessageChannel`.
31
+ * Closing it closes the port, which closes the other end too.
32
+ * @public
33
+ */
34
+ export declare function messagePortLink<Out, In>(port: MessagePort): MessageLink<Out, In>;
35
+ /**
36
+ * A link from a forked child to its parent, over `process.send`. The fork must use
37
+ * `serialization: 'advanced'` (as `forksTransport` does): JSON would turn a `Map`, a `Date` or a
38
+ * `bigint` into something else. Closing it disconnects the IPC
39
+ * channel once every message sent so far has been written (a disconnect cancels queued writes),
40
+ * so the child can exit once nothing else keeps it alive; `process` emits `disconnect` then.
41
+ * @public
42
+ */
43
+ export declare function processLink<Out, In>(proc: NodeJS.Process): MessageLink<Out, In>;
44
+ /**
45
+ * A link from the parent to a forked child, over `child.send`; the fork must use
46
+ * `serialization: 'advanced'`. It closes when the IPC channel
47
+ * disconnects, which happens after every message the child sent has arrived; a child's `exit`
48
+ * can come before its last messages are read, so the link doesn't close on it. A send that
49
+ * fails once the channel is going away is dropped: the link's exit is what reports it.
50
+ * @public
51
+ */
52
+ export declare function childProcessLink<Out, In>(child: ChildProcess): MessageLink<Out, In>;
53
+ /**
54
+ * A link from the parent to a worker thread. It closes when the thread exits; closing it doesn't
55
+ * stop the thread (the transport terminates it).
56
+ * @public
57
+ */
58
+ export declare function workerLink<Out, In>(worker: Worker): MessageLink<Out, In>;
59
+ /**
60
+ * What `createRpc` runs over: a `Transport` on the coordinator side and a `WorkerPort` on the
61
+ * worker side both fit as they are. `Out` is what this side sends (its calls and its replies);
62
+ * other messages on the port pass by untouched.
63
+ * @public
64
+ */
65
+ interface RpcPort<Out> {
66
+ send(message: Out): void;
67
+ onMessage(listener: (message: {
68
+ readonly t: string;
69
+ }) => void): () => void;
70
+ /** Called once when the port closes; `cause` becomes every pending call's rejection cause. */
71
+ onExit(listener: (cause: unknown) => void): () => void;
72
+ }
73
+ /**
74
+ * The implementations of `Methods` that this side serves. A handler may return its result or a
75
+ * promise of it.
76
+ * @public
77
+ */
78
+ type RpcHandlers<Methods> = { readonly [K in keyof Methods]: Methods[K] extends ((...args: infer A) => infer R) ? (...args: A) => Awaited<R> | Promise<Awaited<R>> : never; };
79
+ /**
80
+ * Options for `createRpc`.
81
+ * @public
82
+ */
83
+ interface RpcOptions {
84
+ /** Serializes a handler's error for its reply. The default keeps name, message, stack, `code` and causes. */
85
+ readonly serializeError?: (error: unknown) => SerializedError;
86
+ }
87
+ /**
88
+ * Serves `handlers` (this side's `Local` methods) on `port` and returns a client for the other
89
+ * side's `Remote` methods. Both method sets must be clone-safe (`RpcSchema`): a method taking
90
+ * `() => void` doesn't compile.
91
+ *
92
+ * Arguments and results must also survive the link: a fork's advanced serialization rejects a
93
+ * `SharedArrayBuffer` (threads and inline accept it), and a class instance arrives as a plain
94
+ * object everywhere, a `Buffer` as a `Uint8Array` over threads and inline.
95
+ *
96
+ * A handler's error comes back as `RpcError('RPC_REMOTE_ERROR')` with the error on `.remote`. When
97
+ * the port exits, every pending call, and every call made after, rejects with
98
+ * `RpcError('RPC_CLOSED')` whose `cause` is the port's exit value (the `WorkerExit` on the
99
+ * coordinator side).
100
+ * @public
101
+ */
102
+ export declare function createRpc<Local extends RpcSchema<Local>, Remote extends RpcSchema<Remote>>(port: RpcPort<RpcCall<Remote> | RpcReply<Local>>, handlers: RpcHandlers<Local>, options?: RpcOptions): RpcClient<Remote>;
103
+ /**
104
+ * Turns anything thrown into a clone-safe `SerializedError`. Never throws: a field that can't be
105
+ * read is left out.
106
+ * @public
107
+ */
108
+ export declare function serializeError(value: unknown): SerializedError;
109
+ export type { RpcErrorCode, RpcErrorOptions, RpcHandlers, RpcOptions, RpcPort };
package/dist/index.js ADDED
@@ -0,0 +1,361 @@
1
+ // src/errors.ts
2
+ /**
3
+ * An RPC failure with a stable code.
4
+ * @public
5
+ */
6
+ var RpcError = class extends Error {
7
+ code;
8
+ /** For `RPC_REMOTE_ERROR`: the error the remote method threw, as it crossed the link. */
9
+ remote;
10
+ constructor(code, message, options = {}) {
11
+ super(message, options);
12
+ this.name = "RpcError";
13
+ this.code = code;
14
+ if (options.remote !== void 0) this.remote = options.remote;
15
+ }
16
+ };
17
+
18
+ // src/links.ts
19
+ const CLOSED = Object.freeze({ type: "closed" });
20
+ /** A send that fails once the channel is going away is dropped; the link's exit reports it. */
21
+ const ignoreSendError = () => {};
22
+ function createLink(channel) {
23
+ const listeners = /* @__PURE__ */ new Set();
24
+ const exitListeners = /* @__PURE__ */ new Set();
25
+ /** Messages nobody has taken yet, oldest first. Short: it fills only while nobody listens. */
26
+ const queue = [];
27
+ let drainScheduled = false;
28
+ let closed = false;
29
+ /** Delivers queued messages, in order, while someone listens. */
30
+ const pump = () => {
31
+ while (queue.length > 0 && listeners.size > 0 && !closed) {
32
+ const message = queue.shift();
33
+ for (const listener of [...listeners]) listener(message);
34
+ }
35
+ };
36
+ const onClose = () => {
37
+ if (closed) return;
38
+ closed = true;
39
+ queue.length = 0;
40
+ listeners.clear();
41
+ for (const listener of exitListeners) listener(CLOSED);
42
+ exitListeners.clear();
43
+ };
44
+ channel.listen((message) => {
45
+ if (closed || typeof message !== "object" || message === null) return;
46
+ queue.push(message);
47
+ if (!drainScheduled) pump();
48
+ }, onClose);
49
+ return {
50
+ send(message, transfer) {
51
+ if (!closed) channel.post(message, transfer);
52
+ },
53
+ onMessage(listener) {
54
+ if (closed) return () => {};
55
+ listeners.add(listener);
56
+ if (queue.length > 0 && !drainScheduled) {
57
+ drainScheduled = true;
58
+ queueMicrotask(() => {
59
+ drainScheduled = false;
60
+ pump();
61
+ });
62
+ }
63
+ return () => {
64
+ listeners.delete(listener);
65
+ };
66
+ },
67
+ onExit(listener) {
68
+ if (closed) {
69
+ listener(CLOSED);
70
+ return () => {};
71
+ }
72
+ exitListeners.add(listener);
73
+ return () => {
74
+ exitListeners.delete(listener);
75
+ };
76
+ },
77
+ close() {
78
+ if (closed) return;
79
+ channel.close();
80
+ onClose();
81
+ }
82
+ };
83
+ }
84
+ /**
85
+ * A link over a `MessagePort`: a thread's `parentPort`, or either end of a `MessageChannel`.
86
+ * Closing it closes the port, which closes the other end too.
87
+ * @public
88
+ */
89
+ function messagePortLink(port) {
90
+ return createLink({
91
+ post: (message, transfer) => port.postMessage(message, transfer),
92
+ listen(onMessage, onClose) {
93
+ port.on("message", onMessage);
94
+ port.once("close", onClose);
95
+ },
96
+ close: () => port.close()
97
+ });
98
+ }
99
+ /**
100
+ * A link from a forked child to its parent, over `process.send`. The fork must use
101
+ * `serialization: 'advanced'` (as `forksTransport` does): JSON would turn a `Map`, a `Date` or a
102
+ * `bigint` into something else. Closing it disconnects the IPC
103
+ * channel once every message sent so far has been written (a disconnect cancels queued writes),
104
+ * so the child can exit once nothing else keeps it alive; `process` emits `disconnect` then.
105
+ * @public
106
+ */
107
+ function processLink(proc) {
108
+ const send = proc.send?.bind(proc);
109
+ if (send === void 0) throw new RpcError("RPC_CLOSED", "This process has no IPC channel");
110
+ let unwritten = 0;
111
+ let closing = false;
112
+ const disconnect = () => {
113
+ if (proc.connected) proc.disconnect();
114
+ };
115
+ const written = () => {
116
+ unwritten--;
117
+ if (closing && unwritten === 0) disconnect();
118
+ };
119
+ return createLink({
120
+ post: (message) => {
121
+ if (!proc.connected) return;
122
+ send(message, void 0, void 0, written);
123
+ unwritten++;
124
+ },
125
+ listen(onMessage, onClose) {
126
+ proc.on("message", onMessage);
127
+ proc.once("disconnect", onClose);
128
+ },
129
+ close: () => {
130
+ closing = true;
131
+ if (unwritten === 0) disconnect();
132
+ }
133
+ });
134
+ }
135
+ /**
136
+ * A link from the parent to a forked child, over `child.send`; the fork must use
137
+ * `serialization: 'advanced'`. It closes when the IPC channel
138
+ * disconnects, which happens after every message the child sent has arrived; a child's `exit`
139
+ * can come before its last messages are read, so the link doesn't close on it. A send that
140
+ * fails once the channel is going away is dropped: the link's exit is what reports it.
141
+ * @public
142
+ */
143
+ function childProcessLink(child) {
144
+ return createLink({
145
+ post: (message) => {
146
+ if (child.connected) child.send(message, ignoreSendError);
147
+ },
148
+ listen(onMessage, onClose) {
149
+ child.on("message", onMessage);
150
+ child.once("disconnect", onClose);
151
+ },
152
+ close: () => {
153
+ if (child.connected) child.disconnect();
154
+ }
155
+ });
156
+ }
157
+ /**
158
+ * A link from the parent to a worker thread. It closes when the thread exits; closing it doesn't
159
+ * stop the thread (the transport terminates it).
160
+ * @public
161
+ */
162
+ function workerLink(worker) {
163
+ return createLink({
164
+ post: (message, transfer) => worker.postMessage(message, transfer),
165
+ listen(onMessage, onClose) {
166
+ worker.on("message", onMessage);
167
+ worker.once("exit", onClose);
168
+ },
169
+ close: () => {}
170
+ });
171
+ }
172
+
173
+ // src/serialize.ts
174
+ /** How deep a `cause` chain is followed. */
175
+ const MAX_CAUSES = 10;
176
+ /**
177
+ * Turns anything thrown into a clone-safe `SerializedError`. Never throws: a field that can't be
178
+ * read is left out.
179
+ * @public
180
+ */
181
+ function serializeError(value) {
182
+ return serialize(value, 0);
183
+ }
184
+ function serialize(value, depth) {
185
+ if (typeof value !== "object" || value === null) return {
186
+ name: "Error",
187
+ message: describe(value)
188
+ };
189
+ const name = read(value, "name");
190
+ const message = read(value, "message");
191
+ const stack = read(value, "stack");
192
+ const code = read(value, "code");
193
+ const cause = depth < MAX_CAUSES ? read(value, "cause") : void 0;
194
+ return {
195
+ name: typeof name === "string" ? name : "Error",
196
+ message: typeof message === "string" ? message : describe(message),
197
+ ...typeof stack === "string" ? { stack } : {},
198
+ ...typeof code === "string" ? { code } : {},
199
+ ...cause === void 0 ? {} : { cause: serialize(cause, depth + 1) }
200
+ };
201
+ }
202
+ function read(value, key) {
203
+ try {
204
+ return value[key];
205
+ } catch {
206
+ return;
207
+ }
208
+ }
209
+ function describe(value) {
210
+ try {
211
+ return String(value);
212
+ } catch {
213
+ return Object.prototype.toString.call(value);
214
+ }
215
+ }
216
+
217
+ // src/rpc.ts
218
+ /**
219
+ * Serves `handlers` (this side's `Local` methods) on `port` and returns a client for the other
220
+ * side's `Remote` methods. Both method sets must be clone-safe (`RpcSchema`): a method taking
221
+ * `() => void` doesn't compile.
222
+ *
223
+ * Arguments and results must also survive the link: a fork's advanced serialization rejects a
224
+ * `SharedArrayBuffer` (threads and inline accept it), and a class instance arrives as a plain
225
+ * object everywhere, a `Buffer` as a `Uint8Array` over threads and inline.
226
+ *
227
+ * A handler's error comes back as `RpcError('RPC_REMOTE_ERROR')` with the error on `.remote`. When
228
+ * the port exits, every pending call, and every call made after, rejects with
229
+ * `RpcError('RPC_CLOSED')` whose `cause` is the port's exit value (the `WorkerExit` on the
230
+ * coordinator side).
231
+ * @public
232
+ */
233
+ function createRpc(port, handlers, options = {}) {
234
+ const serialize = options.serializeError ?? serializeError;
235
+ const pending = /* @__PURE__ */ new Map();
236
+ let nextId = 0;
237
+ let closed;
238
+ const send = port.send.bind(port);
239
+ const offMessage = port.onMessage((message) => {
240
+ if (message.t === "call") answer(message);
241
+ else if (message.t === "reply") settle(message);
242
+ });
243
+ port.onExit((cause) => {
244
+ if (closed !== void 0) return;
245
+ closed = { cause };
246
+ offMessage();
247
+ for (const call of pending.values()) call.reject(new RpcError("RPC_CLOSED", `The link closed before \`${call.method}\` was answered`, { cause }));
248
+ pending.clear();
249
+ });
250
+ async function answer(call) {
251
+ let reply;
252
+ try {
253
+ const value = await invoke(handlers, call.method, call.args);
254
+ reply = {
255
+ t: "reply",
256
+ id: call.id,
257
+ ok: true,
258
+ value
259
+ };
260
+ } catch (error) {
261
+ reply = {
262
+ t: "reply",
263
+ id: call.id,
264
+ ok: false,
265
+ error: serializeOr(error)
266
+ };
267
+ }
268
+ if (closed !== void 0) return;
269
+ try {
270
+ send(reply);
271
+ } catch (error) {
272
+ const what = reply.ok ? "result" : "error";
273
+ const message = `\`${call.method}\`'s ${what} can't cross the link: ${messageOf(error)}`;
274
+ try {
275
+ send({
276
+ t: "reply",
277
+ id: call.id,
278
+ ok: false,
279
+ error: unclonable(message)
280
+ });
281
+ } catch {}
282
+ }
283
+ }
284
+ /** The configured serializer, or a fixed error if it throws: a reply must always be built. */
285
+ function serializeOr(error) {
286
+ try {
287
+ return serialize(error);
288
+ } catch (failure) {
289
+ return unclonable(`The error couldn't be serialized: ${messageOf(failure)}`);
290
+ }
291
+ }
292
+ function settle(reply) {
293
+ const call = pending.get(reply.id);
294
+ if (call === void 0) return;
295
+ pending.delete(reply.id);
296
+ if (reply.ok) call.resolve(reply.value);
297
+ else call.reject(new RpcError("RPC_REMOTE_ERROR", reply.error.message, { remote: reply.error }));
298
+ }
299
+ function call(method, args) {
300
+ if (closed !== void 0) return Promise.reject(new RpcError("RPC_CLOSED", `The link is closed; \`${method}\` wasn't sent`, { cause: closed.cause }));
301
+ const id = nextId++;
302
+ return new Promise((resolve, reject) => {
303
+ pending.set(id, {
304
+ method,
305
+ resolve,
306
+ reject
307
+ });
308
+ try {
309
+ send({
310
+ t: "call",
311
+ id,
312
+ method,
313
+ args
314
+ });
315
+ } catch (error) {
316
+ pending.delete(id);
317
+ reject(new RpcError("RPC_UNCLONABLE", `\`${method}\`'s arguments can't cross the link: ${messageOf(error)}`, { cause: error }));
318
+ }
319
+ });
320
+ }
321
+ const methods = /* @__PURE__ */ new Map();
322
+ return new Proxy(Object.create(null), { get(_target, key) {
323
+ if (typeof key !== "string") return void 0;
324
+ let method = methods.get(key);
325
+ if (method === void 0) {
326
+ if (NOT_METHODS.has(key) || key in Object.prototype) return void 0;
327
+ method = (...args) => call(key, args);
328
+ methods.set(key, method);
329
+ }
330
+ return method;
331
+ } });
332
+ }
333
+ /** Names read by promise resolution, `JSON.stringify`, pretty-format and the like, never methods. */
334
+ const NOT_METHODS = /* @__PURE__ */ new Set([
335
+ "then",
336
+ "toJSON",
337
+ "asymmetricMatch",
338
+ "$$typeof",
339
+ "nodeType",
340
+ "@@__IMMUTABLE_ITERABLE__@@",
341
+ "@@__IMMUTABLE_RECORD__@@"
342
+ ]);
343
+ /** A plain-strings error for a reply that couldn't be built or sent. */
344
+ function unclonable(message) {
345
+ return {
346
+ name: "RpcError",
347
+ message,
348
+ code: "RPC_UNCLONABLE"
349
+ };
350
+ }
351
+ /** Calls `handlers[method]`, rejecting names that aren't served (including `Object.prototype`'s). */
352
+ function invoke(handlers, method, args) {
353
+ const handler = handlers[method];
354
+ if (typeof handler !== "function" || handler === Object.prototype[method]) throw new RpcError("RPC_UNKNOWN_METHOD", `No RPC method \`${method}\` is served here`);
355
+ return Reflect.apply(handler, handlers, args);
356
+ }
357
+ function messageOf(error) {
358
+ return error instanceof Error ? error.message : String(error);
359
+ }
360
+
361
+ export { RpcError, childProcessLink, createRpc, messagePortLink, processLink, serializeError, workerLink };
package/package.json CHANGED
@@ -1,6 +1,37 @@
1
1
  {
2
2
  "name": "@provino/rpc",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "0.1.0-rc.1",
4
+ "description": "Provino's typed RPC between the coordinator and its workers: clone-safe method schemas over MessagePort and child-process IPC links.",
5
+ "homepage": "https://github.com/pixel-perfect-software/provino#readme",
6
+ "bugs": {
7
+ "url": "https://github.com/pixel-perfect-software/provino/issues"
8
+ },
9
+ "repository": {
10
+ "type": "git",
11
+ "url": "git+https://github.com/pixel-perfect-software/provino.git",
12
+ "directory": "packages/rpc"
13
+ },
14
+ "license": "MIT",
15
+ "type": "module",
16
+ "sideEffects": false,
17
+ "exports": {
18
+ ".": {
19
+ "provino-source": "./src/index.ts",
20
+ "types": "./dist/index.d.ts",
21
+ "import": "./dist/index.js"
22
+ }
23
+ },
24
+ "files": [
25
+ "dist"
26
+ ],
27
+ "engines": {
28
+ "node": "^22.15.0 || >=24"
29
+ },
30
+ "dependencies": {
31
+ "@provino/types": "0.1.0-rc.1"
32
+ },
33
+ "scripts": {
34
+ "build": "tsdown --config ../../tooling/packaging/tsdown.config.ts",
35
+ "test": "node --test --conditions=provino-source \"src/**/*.test.ts\""
36
+ }
6
37
  }