@webreflection/bindings 0.0.1 → 0.1.0

package/README.md

@@ -7,18 +7,19 @@ A (soon to be) collection of bindings for various scenarios.
 ```js
 import bindings from '@webreflection/bindings/message-port';
 
-const { port1, port2 } = new MessageChannel;
-
-// expose bindings the remote can invoke
-// the `remote` itself can invoke (asynchronously)
-// bindings exposed via the other port
-const remote = /** @type {{sum: (a:number, b:number) => Promise<number>}} */(
-  bindings(port1, {
-    log(...values) {
-      console.log(...values);
-    }
-  })
-);
+/** @typedef {import('@webreflection/bindings/message-port').RemoteProxy} RemoteProxy */
+
+const { port1, port2 } = new MessageChannel();
+
+// `local` is inferred from the object below.
+// `remote` calls methods exposed on the other side of the port — declare that
+// shape explicitly; it cannot be inferred from `local`.
+/** @type {RemoteProxy<{ sum: (a: number, b: number) => number }>} */
+const remote = bindings(port1, {
+  log(...values) {
+    console.log(...values);
+  },
+});
 
 // assuming this is an iframe
 parent.postMessage(null, '*', [port2]);
@@ -27,8 +28,42 @@ parent.postMessage(null, '*', [port2]);
 const value = await remote.sum(1, 2);
 ```
 
-The remote counterpart can use or expose bindings in a similar way, this module just orchestrate a reliable way to invoke exposed APIs via `postMessage` dances.
+Each side calls `bindings(port, local)` with its own port and local handlers. The returned proxy always targets the *other* side's `local` object. This module only orchestrates the `postMessage` protocol.
+
+#### Typing
+
+| What | Known at call site? |
+| --- | --- |
+| Second argument (`local`) | yes — inferred from the object you pass |
+| Return value (remote proxy) | no — depends on the other context (worker, iframe, another window) |
+
+Without an explicit remote type, TypeScript falls back to a loose string-keyed proxy (`RemoteProxy` defaults to `Record<string, Handler>`). For a known remote API, pick one of:
+
+```js
+// assertion (JavaScript / checkJs)
+const remote = /** @type {RemoteProxy<{ sum: (a: number, b: number) => number }>} */ (
+  bindings(port1, { log() {} })
+);
+```
+
+```ts
+// generic parameter (TypeScript)
+import bindings, { type RemoteProxy } from '@webreflection/bindings/message-port';
+
+type MainAPI = { log: (...values: unknown[]) => void };
+type WorkerAPI = { sum: (a: number, b: number) => number };
+
+const worker = bindings<MainAPI, WorkerAPI>(port1, {
+  log(...values) {
+    console.log(...values);
+  },
+});
+
+await worker.sum(1, 2);
+```
+
+Remote methods always return a `Promise`, even when the handler on the other side is synchronous.
 
 ## Currently Available
 
-  * `@webreflection/bindings/port` to add bindings via *MessagePort* orchestration
+  * `@webreflection/bindings/message-port` — bind APIs over a *MessagePort* (workers, iframes, `MessageChannel`, etc.)

package/package.json

@@ -1,14 +1,18 @@
 {
   "name": "@webreflection/bindings",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "description": "A (soon to be) collection of bindings for various scenarios.",
-  "exports": {
-    "./message-port": "./src/message-port.js"
+  "types": {
+    "./message-port": "./src/message-port.d.ts"
   },
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+  "exports": {
+    "./message-port": {
+      "types": "./src/message-port.d.ts",
+      "import": "./src/message-port.js"
+    }
   },
   "keywords": [
+    "bindings",
     "MessagePort"
   ],
   "author": "Andrea Giammarchi",
@@ -16,10 +20,9 @@
   "type": "module",
   "dependencies": {
     "@webreflection/utils": "^0.3.6",
-    "next-resolver": "^0.2.0"
+    "next-resolver": "^0.2.1"
   },
   "main": "index.js",
-  "devDependencies": {},
   "repository": {
     "type": "git",
     "url": "git+https://github.com/WebReflection/bindings.git"

package/src/message-port.d.ts

@@ -0,0 +1,23 @@
+/** Any function exposed as a local binding (sync or async). */
+export type Handler = (...args: any[]) => any;
+
+/** Map of method names to handlers exposed on this side of the port. */
+export type LocalBindings = Record<string, Handler>;
+
+/**
+ * Proxy for methods exposed on the remote side.
+ * Every remote call is asynchronous, even when the remote handler is sync.
+ */
+export type RemoteProxy<T extends LocalBindings = LocalBindings> = {
+  [K in keyof T]: (...args: Parameters<T[K]>) => Promise<Awaited<ReturnType<T[K]>>>;
+};
+
+declare function bindings<
+  Local extends LocalBindings,
+  Remote extends LocalBindings = LocalBindings,
+>(
+  port: MessagePort,
+  local: Local,
+): RemoteProxy<Remote>;
+
+export default bindings;

package/src/message-port.js

@@ -1,29 +1,43 @@
+//@ts-check
+
 import nextResolver from 'next-resolver';
 import { nil } from '@webreflection/utils/empty';
 
 const [next, resolve] = nextResolver();
 
 /**
- * Creates a proxy that can be used to call methods remotely via the port.
- * @param {MessagePort} port - The port to use for communication.
- * @param {Record<string, (...args: any[]) => Promise<any>>} bindings - The bindings to use for the methods.
- * @returns {unknown}
+ * Creates a proxy for calling methods exposed on the remote side of the port,
+ * while dispatching incoming calls to `local` on this side.
+ *
+ * `local` is inferred from the second argument. The remote API is never known
+ * from that object alone: pass a second generic or assert the return type
+ * (see README).
+ *
+ * @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, bindings) => {
+export default (port, local) => {
+  // secure the postMessage method to avoid potential
+  // MessagePort.prototype.postMessage overrides interfering
+  // with the communication channel
+  const post = port.postMessage.bind(port);
   port.onmessage = async ({ data: [exec, id, name, args] }) => {
     if (exec) {
-      try { port.postMessage([!exec, id, await bindings[name](...args), null]) }
-      catch (error) { port.postMessage([!exec, id, null, error]) }
+      try { post([!exec, id, await local[name](...args), null]) }
+      catch (error) { post([!exec, id, null, error]) }
     }
     else resolve(id, name, args);
   };
-  return new Proxy(nil, {
+  return /** @type {import('./message-port.js').RemoteProxy<Remote>} */(new Proxy(nil, {
     get(_, name) {
-      return (...args) => {
+      return (/** @type {any[]} */ ...args) => {
         const [id, promise] = next();
-        port.postMessage([true, id, name, args]);
+        post([true, id, name, args]);
         return promise;
       };
     }
-  });
+  }));
 };