@livequery/rpc 2.0.100 → 2.0.102

package/README.md

@@ -1,6 +1,10 @@
 # @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
+
+Repository-specific guidance for coding agents lives in `AGENTS.md`.
 
 This package is built for a simple model:
 
@@ -25,6 +29,7 @@ bun add @livequery/rpc rxjs
 ## What It Exports
 
 ```ts
+export * from "./ExtensionChannel"
 export * from "./RpcChannel"
 export * from "./SharedWorkerChannel"
 export * from "./ServiceLinker"
@@ -45,6 +50,36 @@ 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` is a transport for extension contexts such as a background service worker, popup, options page, or content script. Its current implementation listens on `chrome.runtime.onMessage` and sends messages with `chrome.runtime.sendMessage`.
+
 ## When To Use This Package
 
 Use it when you want to:
@@ -157,7 +192,7 @@ In practice:
 
 ## BehaviorSubject Mirroring
 
-If your service exposes a property with a `getValue()` method, `WorkerManager` will include its initial value during service initialization.
+If your service exposes a `BehaviorSubject` property, the client can treat it like remote reactive state.
 
 This is what allows a worker-side `BehaviorSubject` to feel usable on the client:
 
@@ -177,24 +212,12 @@ settings.theme.subscribe((theme) => {
 
 Notes:
 
-- the initial snapshot is fetched through an internal `____initialize____` call
-- later updates are streamed by subscribing to the remote property
+- `ServiceLinker` special-cases only `subscribe()`, `pipe()`, and `getValue()` on remote properties
+- updates are fetched by subscribing to the remote property path, not through a separate initialization API
+- `getValue()` reads the locally cached value, so subscribe first if you need the current worker value to be populated locally
 - this pattern is designed around `BehaviorSubject`-like objects
 
-## Waiting For Multiple Services To Initialize
-
-`ServiceLinker` exposes a helper for waiting until all linked services have loaded their initial state.
-
-```ts
-const counter = linker.linkService<WorkerService<CounterService>>("counter")
-const settings = linker.linkService<WorkerService<SettingsService>>("settings")
-
-ServiceLinker.ready$({ counter, settings }).subscribe((ready) => {
-  if (ready) {
-    console.log("all services initialized")
-  }
-})
-```
+There is currently no built-in readiness helper in `ServiceLinker`.
 
 ## Nested Access
 
@@ -310,7 +333,6 @@ Creates and caches client-side proxies.
 class ServiceLinker {
   constructor(channel: RpcChannel)
   linkService<T>(name: string): WorkerService<T>
-  static ready$(services: Record<string, any>): Observable<boolean>
 }
 ```
 
@@ -320,7 +342,7 @@ Behavior:
 - assigns incrementing request ids
 - returns an `Observable` that is also `PromiseLike`
 - sends cancellation when a request is unsubscribed early
-- initializes `BehaviorSubject`-style values via `____initialize____`
+- special-cases `subscribe`, `pipe`, and `getValue` for remote observable-like properties
 
 ### `WorkerService<T>`
 
@@ -330,7 +352,7 @@ Rules:
 
 - `BehaviorSubject<T>` stays `BehaviorSubject<T>`
 - `Observable<T>` stays `Observable<T>`
-- methods become async call signatures
+- methods become async call signatures unless their awaited return type is already an `Observable`
 
 Example:
 
@@ -422,8 +444,6 @@ bun run build
 Other scripts:
 
 - `bun run clean`
-- `bun run build:js`
-- `bun run build:types`
 - `bun run build:watch`
 
 ## Package Output

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;AA4B7D,qBAAa,gBAAiB,SAAQ,UAAU;;;IAqB5C,IAAI,CAAC,OAAO,EAAE,UAAU,GAAG,IAAI;CAGlC"}

package/dist/ExtensionChannel.js

@@ -0,0 +1,32 @@
+import { RpcChannel } from "./RpcChannel.js";
+const runtime = (() => {
+    const runtime = globalThis.chrome?.runtime;
+    if (!runtime) {
+        throw new Error("chrome.runtime is not available");
+    }
+    return runtime;
+})();
+function isRpcMessage(value) {
+    return !!value && typeof value === "object" && "id" in value;
+}
+export class ExtensionChannel extends RpcChannel {
+    constructor() {
+        super();
+        runtime.onMessage.addListener(this.#onMessage);
+    }
+    #onMessage = (message) => {
+        if (!isRpcMessage(message))
+            return;
+        const respond = (response) => {
+            runtime.sendMessage({
+                id: message.id,
+                response
+            });
+        };
+        this.next({ ...message, respond });
+    };
+    send(message) {
+        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,OAAO,GAAG,CAAC,GAAG,EAAE;IAClB,MAAM,OAAO,GAAI,UAEf,CAAC,MAAM,EAAE,OAAO,CAAA;IAElB,IAAI,CAAC,OAAO,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAA;IACtD,CAAC;IAED,OAAO,OAAO,CAAA;AAClB,CAAC,CAAC,EAAE,CAAA;AAEJ,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;IAE5C;QACI,KAAK,EAAE,CAAA;QAEP,OAAO,CAAC,SAAS,CAAC,WAAW,CAAC,IAAI,CAAC,UAAU,CAAC,CAAA;IAClD,CAAC;IAED,UAAU,GAAG,CAAC,OAAgB,EAAE,EAAE;QAC9B,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC;YAAE,OAAM;QAElC,MAAM,OAAO,GAAG,CAAC,QAAgC,EAAE,EAAE;YACjD,OAAO,CAAC,WAAW,CAAC;gBAChB,EAAE,EAAE,OAAO,CAAC,EAAE;gBACd,QAAQ;aACU,CAAC,CAAA;QAC3B,CAAC,CAAA;QAED,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,OAAO,EAAE,OAAO,EAAE,CAAC,CAAA;IACtC,CAAC,CAAA;IAED,IAAI,CAAC,OAAmB;QACpB,OAAO,CAAC,WAAW,CAAC,OAAO,CAAC,CAAA;IAChC,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.100",
+  "version": "2.0.102",
   "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",