@livequery/rpc 2.0.101 → 2.0.104

package/README.md

@@ -1,6 +1,6 @@
 # @livequery/rpc
 
-Lightweight RxJS-based RPC utilities for exposing services from a `SharedWorker` and consuming them from the main thread with typed proxies.
+Lightweight RxJS-based RPC utilities for exposing services from a `SharedWorker` or an extension background runtime and consuming them from the main thread with typed proxies.
 
 ## AI Agent Notes
 
@@ -29,6 +29,7 @@ bun add @livequery/rpc rxjs
 ## What It Exports
 
 ```ts
+export * from "./ExtensionChannel"
 export * from "./RpcChannel"
 export * from "./SharedWorkerChannel"
 export * from "./ServiceLinker"
@@ -49,6 +50,41 @@ ServiceLinker --(RpcMessage)--> SharedWorkerChannel --> WorkerManager --> your s
      |--------------------(response stream)-----------------------|
 ```
 
+For extension Manifest V3, the same flow can run over `ExtensionChannel` and `chrome.runtime` messaging instead of `SharedWorker`.
+
+## Extension MV3 Example
+
+### Background service worker
+
+```ts
+import { ExtensionChannel, WorkerManager } from "@livequery/rpc"
+import { CounterService } from "./CounterService"
+
+const channel = new ExtensionChannel()
+const manager = new WorkerManager(channel)
+
+manager.exposeService("counter", new CounterService())
+```
+
+### Popup, options page, or content script
+
+```ts
+import { ExtensionChannel, ServiceLinker, type WorkerService } from "@livequery/rpc"
+import type { CounterService } from "./CounterService"
+
+const channel = new ExtensionChannel()
+const linker = new ServiceLinker(channel)
+
+const counter = linker.linkService<WorkerService<CounterService>>("counter")
+```
+
+`ExtensionChannel` auto-detects its context at construction time:
+
+- **Background service worker** (`typeof window === 'undefined'`): listens on `chrome.runtime.onMessage` and routes responses back to the originating tab via `chrome.tabs.sendMessage`, or falls back to `chrome.runtime.sendMessage` when the message did not originate from a tab.
+- **Foreground context** (popup, options page, content script): listens on `chrome.runtime.onMessage` for responses arriving from the background and sends requests with `chrome.runtime.sendMessage`.
+
+If `chrome` is not available (e.g. during SSR), all operations silently no-op.
+
 ## When To Use This Package
 
 Use it when you want to:
@@ -275,6 +311,29 @@ const worker = new SharedWorker(new URL("./worker.ts", import.meta.url), { type:
 const channel = new SharedWorkerChannel(worker)
 ```
 
+### `ExtensionChannel`
+
+Concrete `RpcChannel` implementation for Chrome extension Manifest V3 messaging.
+
+Auto-detects its context at construction time — no argument is required.
+
+```ts
+const channel = new ExtensionChannel()
+```
+
+**Background service worker** (`typeof window === 'undefined'`):
+
+- listens on `chrome.runtime.onMessage`
+- responds to tab-originated messages via `chrome.tabs.sendMessage(tabId, …)`
+- responds to non-tab messages via `chrome.runtime.sendMessage(…)`
+
+**Foreground context** (popup, options page, content script):
+
+- listens on `chrome.runtime.onMessage` for responses from the background
+- sends requests with `chrome.runtime.sendMessage`
+
+If `chrome` is unavailable (e.g. during SSR), all operations silently no-op.
+
 ### `WorkerManager`
 
 Registers named services and routes incoming RPC requests.

package/dist/ExtensionChannel.d.ts

@@ -0,0 +1,7 @@
+import { RpcChannel, type RpcMessage } from "./RpcChannel.js";
+export declare class ExtensionChannel extends RpcChannel {
+    #private;
+    constructor();
+    send(message: RpcMessage): void;
+}
+//# sourceMappingURL=ExtensionChannel.d.ts.map

package/dist/ExtensionChannel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExtensionChannel.d.ts","sourceRoot":"","sources":["../src/ExtensionChannel.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAyB7D,qBAAa,gBAAiB,SAAQ,UAAU;;;IAmD5C,IAAI,CAAC,OAAO,EAAE,UAAU,GAAG,IAAI;CAIlC"}

package/dist/ExtensionChannel.js

@@ -0,0 +1,62 @@
+import { RpcChannel } from "./RpcChannel.js";
+const chrome = globalThis.chrome;
+function isRpcMessage(value) {
+    return !!value && typeof value === "object" && "id" in value;
+}
+export class ExtensionChannel extends RpcChannel {
+    constructor() {
+        super();
+        if (typeof window == 'undefined') {
+            this.#initBackground();
+        }
+        else {
+            this.#initForegound();
+        }
+    }
+    #initForegound() {
+        if (!chrome)
+            return;
+        const runtime = chrome.runtime;
+        runtime?.onMessage.addListener((message, sender, sendResponse) => {
+            if (!isRpcMessage(message))
+                return;
+            const respond = (response) => {
+                runtime?.sendMessage({
+                    id: message.id,
+                    response
+                });
+            };
+            this.next({ ...message, respond });
+        });
+    }
+    #initBackground() {
+        if (!chrome)
+            return;
+        chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
+            if (!isRpcMessage(message))
+                return;
+            const tabId = sender.tab?.id;
+            const respond = (response) => {
+                if (tabId) {
+                    chrome.tabs.sendMessage(tabId, {
+                        id: message.id,
+                        response
+                    });
+                }
+                else {
+                    chrome.runtime.sendMessage({
+                        id: message.id,
+                        response
+                    });
+                }
+            };
+            this.next({ ...message, respond });
+        });
+    }
+    send(message) {
+        if (!chrome)
+            return;
+        chrome.runtime.sendMessage(message);
+    }
+}
+//# sourceMappingURL=ExtensionChannel.js.map

package/dist/ExtensionChannel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExtensionChannel.js","sourceRoot":"","sources":["../src/ExtensionChannel.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAmB,MAAM,iBAAiB,CAAA;AAY7D,MAAM,MAAM,GAAI,UAOd,CAAC,MAAM,CAAA;AAET,SAAS,YAAY,CAAC,KAAc;IAChC,OAAO,CAAC,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,IAAI,IAAI,KAAK,CAAA;AAChE,CAAC;AAED,MAAM,OAAO,gBAAiB,SAAQ,UAAU;IAI5C;QACI,KAAK,EAAE,CAAA;QACP,IAAI,OAAO,MAAM,IAAI,WAAW,EAAE,CAAC;YAC/B,IAAI,CAAC,eAAe,EAAE,CAAA;QAC1B,CAAC;aAAM,CAAC;YACJ,IAAI,CAAC,cAAc,EAAE,CAAA;QACzB,CAAC;IACL,CAAC;IAED,cAAc;QACV,IAAI,CAAC,MAAM;YAAE,OAAM;QACnB,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAA;QAC9B,OAAO,EAAE,SAAS,CAAC,WAAW,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,EAAE;YAC7D,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC;gBAAE,OAAM;YAClC,MAAM,OAAO,GAAG,CAAC,QAAgC,EAAE,EAAE;gBACjD,OAAO,EAAE,WAAW,CAAC;oBACjB,EAAE,EAAE,OAAO,CAAC,EAAE;oBACd,QAAQ;iBACU,CAAC,CAAA;YAC3B,CAAC,CAAA;YACD,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,OAAO,EAAE,OAAO,EAAE,CAAC,CAAA;QACtC,CAAC,CAAC,CAAC;IACP,CAAC;IAED,eAAe;QACX,IAAI,CAAC,MAAM;YAAE,OAAM;QACnB,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,EAAE;YACnE,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC;gBAAE,OAAM;YAClC,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,EAAE,EAAE,CAAA;YAC5B,MAAM,OAAO,GAAG,CAAC,QAAgC,EAAE,EAAE;gBACjD,IAAI,KAAK,EAAE,CAAC;oBACR,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE;wBAC3B,EAAE,EAAE,OAAO,CAAC,EAAE;wBACd,QAAQ;qBACU,CAAC,CAAA;gBAC3B,CAAC;qBAAM,CAAC;oBACJ,MAAM,CAAC,OAAO,CAAC,WAAW,CAAC;wBACvB,EAAE,EAAE,OAAO,CAAC,EAAE;wBACd,QAAQ;qBACU,CAAC,CAAA;gBAC3B,CAAC;YACL,CAAC,CAAA;YACD,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,OAAO,EAAE,OAAO,EAAE,CAAC,CAAA;QACtC,CAAC,CAAC,CAAC;IACP,CAAC;IAGD,IAAI,CAAC,OAAmB;QACpB,IAAI,CAAC,MAAM;YAAE,OAAM;QACnB,MAAM,CAAC,OAAO,CAAC,WAAW,CAAC,OAAO,CAAC,CAAA;IACvC,CAAC;CACJ"}

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./RpcChannel.js";
+export * from "./ExtensionChannel.js";
 export * from "./SharedWorkerChannel.js";
 export * from "./ServiceLinker.js";
 export * from "./WorkerService.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAA;AAC/B,cAAc,0BAA0B,CAAA;AACxC,cAAc,oBAAoB,CAAA;AAClC,cAAc,oBAAoB,CAAA;AAClC,cAAc,oBAAoB,CAAA;AAClC,cAAc,uBAAuB,CAAA;AACrC,cAAc,6BAA6B,CAAA;AAC3C,cAAc,gBAAgB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAA;AAC/B,cAAc,uBAAuB,CAAA;AACrC,cAAc,0BAA0B,CAAA;AACxC,cAAc,oBAAoB,CAAA;AAClC,cAAc,oBAAoB,CAAA;AAClC,cAAc,oBAAoB,CAAA;AAClC,cAAc,uBAAuB,CAAA;AACrC,cAAc,6BAA6B,CAAA;AAC3C,cAAc,gBAAgB,CAAA"}

package/dist/index.js

@@ -1,4 +1,5 @@
 export * from "./RpcChannel.js";
+export * from "./ExtensionChannel.js";
 export * from "./SharedWorkerChannel.js";
 export * from "./ServiceLinker.js";
 export * from "./WorkerService.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAA;AAC/B,cAAc,0BAA0B,CAAA;AACxC,cAAc,oBAAoB,CAAA;AAClC,cAAc,oBAAoB,CAAA;AAClC,cAAc,oBAAoB,CAAA;AAClC,cAAc,uBAAuB,CAAA;AACrC,cAAc,6BAA6B,CAAA;AAC3C,cAAc,gBAAgB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAA;AAC/B,cAAc,uBAAuB,CAAA;AACrC,cAAc,0BAA0B,CAAA;AACxC,cAAc,oBAAoB,CAAA;AAClC,cAAc,oBAAoB,CAAA;AAClC,cAAc,oBAAoB,CAAA;AAClC,cAAc,uBAAuB,CAAA;AACrC,cAAc,6BAA6B,CAAA;AAC3C,cAAc,gBAAgB,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livequery/rpc",
-  "version": "2.0.101",
+  "version": "2.0.104",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -21,6 +21,11 @@
       "import": "./dist/index.js",
       "default": "./dist/index.js"
     },
+    "./ExtensionChannel": {
+      "types": "./dist/ExtensionChannel.d.ts",
+      "import": "./dist/ExtensionChannel.js",
+      "default": "./dist/ExtensionChannel.js"
+    },
     "./RpcChannel": {
       "types": "./dist/RpcChannel.d.ts",
       "import": "./dist/RpcChannel.js",