@webreflection/bindings 0.1.1 → 0.2.1

package/README.md

@@ -1,5 +1,7 @@
 # @webreflection/bindings
 
+[![Coverage Status](https://coveralls.io/repos/github/WebReflection/bindings/badge.svg?branch=main)](https://coveralls.io/github/WebReflection/bindings?branch=main)
+
 A (soon to be) collection of bindings for various scenarios.
 
 ### Example
@@ -64,6 +66,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.1",
+  "version": "0.2.1",
   "description": "A (soon to be) collection of bindings for various scenarios.",
   "types": {
     "./message-port": "./src/message-port.d.ts"
@@ -15,13 +15,27 @@
     "bindings",
     "MessagePort"
   ],
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
   "author": "Andrea Giammarchi",
   "license": "MIT",
   "type": "module",
+  "scripts": {
+    "coverage": "mkdir -p ./coverage; c8 report --reporter=text-lcov > ./coverage/lcov.info",
+    "test": "c8 node test/verify-runtime.mjs"
+  },
   "dependencies": {
     "@webreflection/utils": "^0.3.6",
     "next-resolver": "^0.2.2"
   },
+  "overrides": {
+    "c8": {
+      "yargs": "^18.0.0"
+    }
+  },
   "main": "index.js",
   "repository": {
     "type": "git",
@@ -30,5 +44,8 @@
   "bugs": {
     "url": "https://github.com/WebReflection/bindings/issues"
   },
-  "homepage": "https://github.com/WebReflection/bindings#readme"
+  "homepage": "https://github.com/WebReflection/bindings#readme",
+  "devDependencies": {
+    "c8": "^11.0.0"
+  }
 }

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

@@ -1,10 +1,29 @@
 //@ts-check
 
 import nextResolver from 'next-resolver';
+import Map from '@webreflection/utils/map';
 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,31 +32,47 @@ 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);
+  const post = port.postMessage.bind(port), $ = new Map;
+
+  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) => {
-        const [id, promise] = next();
-        post([true, id, name, args]);
-        return promise;
-      };
-    }
+    get: (_, name) => $.get(name) ?? $.put(name, (/** @type {any[]} */ ...args) => {
+      const [id, promise] = next();
+      post([true, id, name, args]);
+      return promise;
+    }),
   }));
 };
+
+export default bindings;