@webreflection/bindings 0.1.0 → 0.2.0

package/README.md

@@ -64,6 +64,71 @@ await worker.sum(1, 2);
 
 Remote methods always return a `Promise`, even when the handler on the other side is synchronous.
 
+#### Transferable responses
+
+Import `options` and assign `this[options]` inside a local handler to pass
+`postMessage` options (typically `{ transfer: [...] }`) with the response.
+`options` is the only symbol used by this module. `bindings()` installs a
+setter-only accessor on the `local` object — assign before returning; it
+cannot be read back. Use method syntax (not arrow functions) so `this` refers
+to `local`:
+
+```js
+import bindings, { options } from '@webreflection/bindings/message-port';
+
+/** @typedef {import('@webreflection/bindings/message-port').RemoteProxy} RemoteProxy */
+/** @typedef {import('@webreflection/bindings/message-port').LocalOptionsHost} LocalOptionsHost */
+
+const { port1, port2 } = new MessageChannel();
+
+// this side exposes `readBuffer` to the other side
+bindings(port1, {
+  /** @this {LocalOptionsHost} */
+  readBuffer() {
+    const i32a = new Int32Array([1, 2, 3]);
+    this[options] = { transfer: [i32a.buffer] };
+    return i32a;
+  },
+});
+
+// other side calls it through the returned proxy
+/** @type {RemoteProxy<{ readBuffer: () => Int32Array }>} */
+const remote = bindings(port2, {});
+
+const i32a = await remote.readBuffer();
+```
+
+```ts
+import bindings, {
+  options,
+  type LocalOptionsHost,
+  type RemoteProxy,
+} from '@webreflection/bindings/message-port';
+
+const { port1, port2 } = new MessageChannel();
+
+type WorkerAPI = { readBuffer: () => Int32Array<ArrayBuffer> };
+
+bindings(port1, {
+  readBuffer(this: LocalOptionsHost) {
+    const i32a = new Int32Array([1, 2, 3]);
+    this[options] = { transfer: [i32a.buffer] };
+    return i32a;
+  },
+});
+
+const worker = bindings<Record<string, never>, WorkerAPI>(port2, {});
+await worker.readBuffer();
+```
+
+There is a single `opts` slot per `bindings()` call. Treat `this[options]` as an
+advanced feature: assign it right before returning, when something must be
+transferred, and only if you understand concurrent handlers on the same port
+can overwrite each other's options while they are in flight.
+
+On failure, any options set during that handler are discarded (`finally` clears
+the slot) and the error reply is sent without them.
+
 ## Currently Available
 
   * `@webreflection/bindings/message-port` — bind APIs over a *MessagePort* (workers, iframes, `MessageChannel`, etc.)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webreflection/bindings",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "A (soon to be) collection of bindings for various scenarios.",
   "types": {
     "./message-port": "./src/message-port.d.ts"
@@ -15,12 +15,20 @@
     "bindings",
     "MessagePort"
   ],
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
   "author": "Andrea Giammarchi",
   "license": "MIT",
   "type": "module",
+  "scripts": {
+    "test": "node test/verify-runtime.mjs"
+  },
   "dependencies": {
     "@webreflection/utils": "^0.3.6",
-    "next-resolver": "^0.2.1"
+    "next-resolver": "^0.2.2"
   },
   "main": "index.js",
   "repository": {

package/src/message-port.d.ts

@@ -1,3 +1,25 @@
+/** `postMessage` options for the next binding response (`transfer`, etc.). */
+export type PostMessageOptions = StructuredSerializeOptions;
+
+/**
+ * The only symbol exported by this module.
+ *
+ * {@link bindings} installs a setter-only `this[options]` accessor on the
+ * `local` object. Assign {@link PostMessageOptions} from local handlers;
+ * the value is not readable, is consumed on the next response, then cleared
+ * (including after errors).
+ */
+export declare const options: unique symbol;
+
+/**
+ * `local` object passed to {@link bindings}, after which handlers can assign
+ * `this[options]`. TypeScript has no write-only property type — reading
+ * `this[options]` is unsupported at runtime.
+ */
+export type LocalOptionsHost = {
+  [options]: PostMessageOptions;
+};
+
 /** Any function exposed as a local binding (sync or async). */
 export type Handler = (...args: any[]) => any;
 

package/src/message-port.js

@@ -3,8 +3,26 @@
 import nextResolver from 'next-resolver';
 import { nil } from '@webreflection/utils/empty';
 
+const { defineProperty } = Object;
 const [next, resolve] = nextResolver();
 
+/**
+ * @typedef {StructuredSerializeOptions} PostMessageOptions
+ */
+
+/**
+ * The only symbol exported by this module.
+ *
+ * {@link bindings} installs a setter-only `this[options]` accessor on the
+ * `local` object. Assign {@link PostMessageOptions} from local handlers
+ * before returning (e.g. `{ transfer: [...] }`). The value cannot be read
+ * back; it is consumed with the next response `postMessage`, then cleared
+ * (including after errors).
+ *
+ * @type {unique symbol}
+ */
+export const options = Symbol();
+
 /**
  * Creates a proxy for calling methods exposed on the remote side of the port,
  * while dispatching incoming calls to `local` on this side.
@@ -13,24 +31,40 @@ const [next, resolve] = nextResolver();
  * from that object alone: pass a second generic or assert the return type
  * (see README).
  *
+ * Also installs a setter-only `this[options]` accessor on `local` so handlers
+ * can assign {@link PostMessageOptions} for their response.
+ *
  * @template {import('./message-port.js').LocalBindings} Local
  * @template {import('./message-port.js').LocalBindings} Remote
  * @param {MessagePort} port
  * @param {Local} local Methods exposed to the remote side (sync or async).
  * @returns {import('./message-port.js').RemoteProxy<Remote>}
  */
-export default (port, local) => {
+const bindings = (port, local) => {
   // secure the postMessage method to avoid potential
   // MessagePort.prototype.postMessage overrides interfering
   // with the communication channel
   const post = port.postMessage.bind(port);
+
+  let opts = nil;
+
+  defineProperty(local, options, {
+    configurable: false,
+    set(value) { opts = value },
+  });
+
   port.onmessage = async ({ data: [exec, id, name, args] }) => {
     if (exec) {
-      try { post([!exec, id, await local[name](...args), null]) }
+      try {
+        const result = await local[name](...args);
+        post([!exec, id, result, null], opts);
+      }
       catch (error) { post([!exec, id, null, error]) }
+      finally { opts = nil }
     }
     else resolve(id, name, args);
   };
+
   return /** @type {import('./message-port.js').RemoteProxy<Remote>} */(new Proxy(nil, {
     get(_, name) {
       return (/** @type {any[]} */ ...args) => {
@@ -41,3 +75,5 @@ export default (port, local) => {
     }
   }));
 };
+
+export default bindings;