prpc-postmessage 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Colin Huang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,89 @@
+# prpc-postmessage
+
+![npm](https://img.shields.io/npm/v/prpc-postmessage)
+![license](https://img.shields.io/npm/l/prpc-postmessage)
+![npm downloads](https://img.shields.io/npm/dm/prpc-postmessage)
+![build](https://img.shields.io/github/actions/workflow/status/chuandeng/prpc-postMessage/release.yml)
+
+A Promise-based RPC programming experience built on **postMessage**.
+
+`prpc-postmessage` provides a lightweight and type-safe Promise RPC layer that makes it easy to call methods across different JavaScript execution contexts, including:
+
+- Browser windows and iframes
+- Main thread ↔ Service Worker
+- Figma plugin ↔ UI
+
+---
+
+## ✨ Features
+
+- Promise-based RPC API
+- TypeScript-first, fully typed methods
+- Built on standard `postMessage`
+- Works with Service Workers
+- No runtime dependencies
+- Suitable for Web and Figma plugin environments
+
+---
+
+## 📦 Installation
+
+```bash
+pnpm add prpc-postmessage
+
+```
+##🚀 Basic Usage
+
+### Service Worker (RPC Server)
+```javascript
+import { RPCServer } from 'prpc-postmessage';
+
+class WorkerService {
+  async add(a: number, b: number): Promise<number> {
+    return a + b;
+  }
+
+  async getVersion(): Promise<string> {
+    return 'v1.0.0';
+  }
+}
+
+new RPCServer(WorkerService);
+```
+
+### Web / Client (RPC Client)
+```javascript
+import { RPCClient } from 'prpc-postmessage';
+
+await navigator.serviceWorker.ready;
+interface PRCAPI {
+  getVersion(): Promise<string>;
+}
+
+const client = new RPCClient<PRCAPI>({
+  target: navigator.serviceWorker
+});
+
+const version = await client.getVersion();
+console.log(version);
+```
+## Demo
+[Service worker demo](https://github.com/chuandeng/prpc-postMessage/tree/main/examples/service-worker)
+[Iframe Demo](https://github.com/chuandeng/prpc-postMessage/tree/main/examples/iframe)
+
+
+## 🧩 Supported Scenarios
+	•	Window ↔ Window
+	•	Window ↔ iframe
+	•	Main thread ↔ Service Worker
+	•	Figma plugin ↔ UI
+
+## ⚠️ Notes
+	•	The Service Worker must be activated and controlling the page
+	•	Always wait for navigator.serviceWorker.ready before creating the client
+	•	Messages are transported via postMessage
+
+
+## 📄 License
+
+MIT © chuandeng

package/dist/index.d.ts

@@ -0,0 +1,56 @@
+export declare class RPCClient<T = any> {
+    private _type?;
+    private target;
+    private origin;
+    private timeout;
+    private typePrefix;
+    private pendingRequests;
+    private isServiceWorker;
+    constructor(options: RPCClientOptions);
+    private setupListener;
+    private request;
+}
+
+export declare interface RPCClientOptions {
+    target: Window | ServiceWorkerContainer | MessagePort;
+    origin?: string;
+    timeout?: number;
+    typePrefix?: string;
+}
+
+export declare interface RPCRequest {
+    jsonrpc: '2.0';
+    method: string;
+    params: any[];
+    id: string;
+    type?: string;
+}
+
+export declare interface RPCResponse {
+    jsonrpc: '2.0';
+    result?: any;
+    error?: {
+        code: number;
+        message: string;
+        data?: any;
+    };
+    id: string;
+    type?: string;
+}
+
+export declare class RPCServer {
+    private service;
+    private source?;
+    private origin;
+    private typePrefix;
+    constructor(service: any, options?: RPCServerOptions);
+    private setupListener;
+}
+
+export declare interface RPCServerOptions {
+    source?: Window | ServiceWorker | MessagePort;
+    origin?: string;
+    typePrefix?: string;
+}
+
+export { }

package/dist/prpc-postmessage.cjs

@@ -0,0 +1 @@
+"use strict";var l=Object.defineProperty;var f=(n,t,s)=>t in n?l(n,t,{enumerable:!0,configurable:!0,writable:!0,value:s}):n[t]=s;var r=(n,t,s)=>f(n,typeof t!="symbol"?t+"":t,s);Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});class h{constructor(t){r(this,"_type");r(this,"target");r(this,"origin");r(this,"timeout");r(this,"typePrefix");r(this,"pendingRequests",new Map);r(this,"isServiceWorker",!1);return this.target=t.target,this.origin=t.origin||"*",this.timeout=t.timeout||1e4,this.typePrefix=t.typePrefix||"prc",this.isServiceWorker=this.target instanceof ServiceWorkerContainer,this.setupListener(),new Proxy(this,{get:(s,e)=>{if(e in s)return s[e];if(typeof e=="string"&&e!=="then")return(...o)=>this.request(e,o)}})}setupListener(){const t=s=>{if(s.type!=="message")return;const e=s.data;if(!e||e.jsonrpc!=="2.0"||!e.id)return;const o=`${this.typePrefix}-response`;if(!(e.type&&e.type!==o)&&this.pendingRequests.has(e.id)){const{resolve:c,reject:a,timer:i}=this.pendingRequests.get(e.id);clearTimeout(i),this.pendingRequests.delete(e.id),e.error?a(new Error(e.error.message)):c(e.result)}};console.log("Client listener:",this.target.name),this.isServiceWorker?this.target.addEventListener("message",t):window.addEventListener("message",t)}request(t,s){const e=Math.random().toString(36).substr(2,9);return new Promise((o,c)=>{var d;const a=setTimeout(()=>{this.pendingRequests.has(e)&&(this.pendingRequests.delete(e),c(new Error(`Request timeout for method: ${t}`)))},this.timeout);this.pendingRequests.set(e,{resolve:o,reject:c,timer:a});const i={jsonrpc:"2.0",method:t,params:s,id:e,type:`${this.typePrefix}-request`};this.isServiceWorker?(console.log("Sending request to Service Worker:",i),(d=this.target.controller)==null||d.postMessage(i)):typeof window<"u"&&this.target instanceof Window?(console.log("Sending request to Window:",this.target.name,i),this.target.postMessage(i,this.origin)):this.target.postMessage(i)})}}class p{constructor(t,s={}){r(this,"service");r(this,"source");r(this,"origin","*");r(this,"typePrefix","prc");this.service=typeof t=="function"?new t:t,this.source=s.source,this.origin=s.origin||"*",this.typePrefix=s.typePrefix||"prc",this.setupListener()}setupListener(){const t=async s=>{const e=s.data;if(console.log("Received message:",e),!e||e.jsonrpc!=="2.0"||!e.method)return;const o=`${this.typePrefix}-request`;if(!(e.type&&e.type!==o)&&typeof this.service[e.method]=="function"){let c,a;try{c=await this.service[e.method](...e.params),console.log(`[RPCServer] Method ${e.method} executed successfully`)}catch(u){a={code:-32603,message:u.message||"Internal error"}}const i={jsonrpc:"2.0",id:e.id,result:c,error:a,type:`${this.typePrefix}-response`},d=this.source??s.source;if(d){const u=d;let g=!1;try{g="closed"in u}catch{g=!0}g?u.postMessage(i,this.origin):u.postMessage(i)}}};typeof window<"u"?(window.addEventListener("message",t),console.log("[RPCServer] setupListener for window",window.name)):typeof self<"u"&&(self.addEventListener("message",t),console.log("[RPCServer] setupListener for self",self))}}exports.RPCClient=h;exports.RPCServer=p;

package/dist/prpc-postmessage.js

@@ -0,0 +1,106 @@
+var f = Object.defineProperty;
+var h = (n, t, s) => t in n ? f(n, t, { enumerable: !0, configurable: !0, writable: !0, value: s }) : n[t] = s;
+var r = (n, t, s) => h(n, typeof t != "symbol" ? t + "" : t, s);
+class y {
+  constructor(t) {
+    // @ts-ignore
+    r(this, "_type");
+    r(this, "target");
+    r(this, "origin");
+    r(this, "timeout");
+    r(this, "typePrefix");
+    r(this, "pendingRequests", /* @__PURE__ */ new Map());
+    r(this, "isServiceWorker", !1);
+    return this.target = t.target, this.origin = t.origin || "*", this.timeout = t.timeout || 1e4, this.typePrefix = t.typePrefix || "prc", this.isServiceWorker = this.target instanceof ServiceWorkerContainer, this.setupListener(), new Proxy(this, {
+      get: (s, e) => {
+        if (e in s)
+          return s[e];
+        if (typeof e == "string" && e !== "then")
+          return (...o) => this.request(e, o);
+      }
+    });
+  }
+  setupListener() {
+    const t = (s) => {
+      if (s.type !== "message")
+        return;
+      const e = s.data;
+      if (!e || e.jsonrpc !== "2.0" || !e.id)
+        return;
+      const o = `${this.typePrefix}-response`;
+      if (!(e.type && e.type !== o) && this.pendingRequests.has(e.id)) {
+        const { resolve: c, reject: a, timer: i } = this.pendingRequests.get(e.id);
+        clearTimeout(i), this.pendingRequests.delete(e.id), e.error ? a(new Error(e.error.message)) : c(e.result);
+      }
+    };
+    console.log("Client listener:", this.target.name), this.isServiceWorker ? this.target.addEventListener("message", t) : window.addEventListener("message", t);
+  }
+  request(t, s) {
+    const e = Math.random().toString(36).substr(2, 9);
+    return new Promise((o, c) => {
+      var d;
+      const a = setTimeout(() => {
+        this.pendingRequests.has(e) && (this.pendingRequests.delete(e), c(new Error(`Request timeout for method: ${t}`)));
+      }, this.timeout);
+      this.pendingRequests.set(e, { resolve: o, reject: c, timer: a });
+      const i = {
+        jsonrpc: "2.0",
+        method: t,
+        params: s,
+        id: e,
+        type: `${this.typePrefix}-request`
+      };
+      this.isServiceWorker ? (console.log("Sending request to Service Worker:", i), (d = this.target.controller) == null || d.postMessage(i)) : typeof window < "u" && this.target instanceof Window ? (console.log("Sending request to Window:", this.target.name, i), this.target.postMessage(i, this.origin)) : this.target.postMessage(i);
+    });
+  }
+}
+class m {
+  constructor(t, s = {}) {
+    r(this, "service");
+    r(this, "source");
+    r(this, "origin", "*");
+    r(this, "typePrefix", "prc");
+    this.service = typeof t == "function" ? new t() : t, this.source = s.source, this.origin = s.origin || "*", this.typePrefix = s.typePrefix || "prc", this.setupListener();
+  }
+  setupListener() {
+    const t = async (s) => {
+      const e = s.data;
+      if (console.log("Received message:", e), !e || e.jsonrpc !== "2.0" || !e.method)
+        return;
+      const o = `${this.typePrefix}-request`;
+      if (!(e.type && e.type !== o) && typeof this.service[e.method] == "function") {
+        let c, a;
+        try {
+          c = await this.service[e.method](...e.params), console.log(`[RPCServer] Method ${e.method} executed successfully`);
+        } catch (u) {
+          a = {
+            code: -32603,
+            message: u.message || "Internal error"
+          };
+        }
+        const i = {
+          jsonrpc: "2.0",
+          id: e.id,
+          result: c,
+          error: a,
+          type: `${this.typePrefix}-response`
+        }, d = this.source ?? s.source;
+        if (d) {
+          const u = d;
+          let g = !1;
+          try {
+            g = "closed" in u;
+          } catch {
+            g = !0;
+          }
+          g ? u.postMessage(i, this.origin) : u.postMessage(i);
+        }
+      }
+    };
+    typeof window < "u" ? (window.addEventListener("message", t), console.log("[RPCServer] setupListener for window", window.name)) : typeof self < "u" && (self.addEventListener("message", t), console.log("[RPCServer] setupListener for self", self));
+  }
+}
+export {
+  y as RPCClient,
+  m as RPCServer
+};

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "prpc-postmessage",
+  "version": "0.1.0",
+  "description": "A Promise-based RPC layer built on postMessage for Web, Service Workers, and Figma plugins.",
+  "keywords": [
+    "postMessage",
+    "rpc",
+    "promise",
+    "service-worker",
+    "figma-plugin",
+    "cross-window",
+    "web"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chuandeng/prpc-postMessage.git"
+  },
+  "bugs": {
+    "url": "https://github.com/chuandeng/prpc-postMessage/issues"
+  },
+  "homepage": "https://github.com/chuandeng/prpc-postMessage#readme",
+  "main": "dist/prpc-postmessage.umd.js",
+  "module": "dist/prpc-postmessage.mjs",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/prpc-postmessage.mjs",
+      "require": "./dist/prpc-postmessage.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "author": "chuandeng<chuandeng99@sohu.com>",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^25.0.3",
+    "typescript": "^5.9.3",
+    "vite": "^5.4.21",
+    "vite-plugin-dts": "^4.5.4",
+    "rimraf": "^5.0.0",
+    "eslint": "^8.56.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "dev": "vite",
+    "demo-worker": "vite --open /examples/service-worker/index.html",
+    "demo-iframe": "vite --open /examples/iframe/index.html",
+    "build": "tsc && vite build",
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "clean": "rimraf dist",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit"
+  }
+}