cry-synced-db-client 0.1.178 → 0.1.180

package/CHANGELOG.md

@@ -1,5 +1,114 @@
 # Versions
 
+## 0.1.180 (2026-05-14)
+
+### `SyncedDb.callWorker` — invoke ebus2 worker services over the WS
+
+New API for calling any registered cry-ebus2 worker directly from the
+client, riding the same WebSocket connection the notifier already uses
+for pub/sub. Built on ebus-proxy 2.0's WS `request` / `response`
+correlation frames, so there's no extra TCP/TLS handshake and no HTTP
+overhead — the worker reply arrives on the open socket.
+
+```typescript
+// echo round-trip (any msgpack-serializable value)
+const echoed = await syncedDb.callWorker<string>("echo", "hello");
+
+// pass an object payload, type the reply
+const result = await syncedDb.callWorker<{ ok: boolean; jobId: string }>(
+  "billing",
+  { customerId, amount: 1990 },
+);
+
+// per-call timeout (default 5000 ms) + caller AbortSignal
+const ctrl = new AbortController();
+setTimeout(() => ctrl.abort(), 200);
+const fast = await syncedDb.callWorker("priority-queue", null, {
+  timeoutMs: 200,
+  signal: ctrl.signal,
+});
+```
+
+API contract:
+
+| Argument | Type | Notes |
+|---|---|---|
+| `service` | `string` | Worker service name registered on the broker. |
+| `payload` | `unknown?` | Anything `msgpack+structuredClone` can serialize. BSON `ObjectId` / `Timestamp` preprocessed automatically. Omit (or pass `undefined`) to call without a payload. |
+| `options.timeoutMs` | `number?` | Per-call timeout; also forwarded to the proxy. Default `5000`. |
+| `options.signal` | `AbortSignal?` | External cancellation. |
+| Returns | `Promise<T>` | Worker's reply, typed as caller-asserted `T`. |
+
+Error semantics:
+
+- WebSocket not OPEN → synchronous reject (no implicit reconnect).
+- Worker error / proxy error → rejects with the proxy's error message.
+- Per-call `timeoutMs` elapses → rejects with timeout error and frees
+  the pending entry (the proxy may still complete the call server-side;
+  client-side state is freed regardless).
+- WebSocket closes mid-flight → all in-flight calls reject with
+  "WebSocket closed before reply".
+- Caller's `signal` aborts → rejects with "aborted"; pending entry is
+  freed and the abort listener is removed.
+
+Multiple concurrent calls are safe — each request uses a unique
+correlation id and the response/error dispatch keys off it. The
+existing pub/sub channel and keepalive ping/pong are unaffected.
+
+Implementation:
+
+- `I_ServerUpdateNotifier.callWorker?` — optional interface method, so
+  REST-only / polling notifier alternatives can omit it.
+- `Ebus2ProxyServerUpdateNotifier.callWorker` — sends `{type:"request",
+  service, payload, timeout, id}` and registers the resolver in a
+  `_pendingRequests` Map keyed by id (same pattern as `_pendingRttPings`
+  for `measureWsRtt`).
+- `handleMessage` adds `case "response"` to dispatch replies and routes
+  correlated `case "error"` to the matching pending promise instead of
+  module-level `console.error`.
+- `handleClose` rejects every in-flight call with a clear "WebSocket
+  closed before reply" message — the socket they were sent over is
+  gone; the client can't observe replies on a different connection.
+- `dispose` is a defensive backstop (`handleClose` normally drains
+  first) and rejects any stragglers with "notifier disposed".
+- AbortSignal listeners are cleaned up on every exit path (resolve,
+  reject, timeout, dispose) so callers don't leak listeners.
+
+Peer-dep bump: `cry-ebus-proxy` now `^2.0.0` (needed for
+`WsRequestMessage` / `WsResponseMessage` types and the proxy-side
+request/response handling).
+
+Tests: 8 new mock-based cases in `test/callWorker.test.ts` covering
+delegation, generic return, payload+options forwarding, undefined
+payload preservation, error propagation, missing-notifier guard,
+concurrent independence. 736 bun + 18 vitest pass (was 728 + 18 — 8 new
+bun cases).
+
+## 0.1.179 (2026-05-13)
+
+### Non-error `console.*` calls now pass numbers as separate arguments
+
+The console-reporting skill was updated to distinguish two flavors of
+Rule 3:
+
+- For `console.error` (and error-reporting `console.warn`): interpolate
+  critical info into the first-arg string. Grep-friendly single line.
+- For progress / count / duration style writes: separate strings and
+  numbers into separate arguments. Dev console renders numbers natively
+  and the runtime avoids eager string coercion.
+
+Five sites updated:
+
+- `RestProxy` timing logs (`operation: 12.34 ms (total: 567.89 ms, count: 42)`)
+  in both `restCall` and `findNewerManyStream`.
+- `SyncEngine.uploadDirtyItems` "X dirty entries but 0 resolvable" warn.
+- `SyncEngine.uploadDirtyItems` "X items sent but not acknowledged" warn.
+- `SyncedDb.init` "X dirty record(s) had no matching Dexie main row" warn.
+
+`console.error` sites (including the `typeof` debug log in
+`PendingChangesManager`) keep their fully-interpolated form — they
+report errors and grep-friendliness wins there.
+
 ## 0.1.178 (2026-05-13)
 
 ### Error reason interpolated into every `console.*` tag line

package/dist/index.js

@@ -3298,7 +3298,9 @@ var _SyncEngine = class _SyncEngine {
       }
       if (updates.length === 0) {
         console.warn(
-          `[SyncEngine] uploadDirtyItems: ${collectionName} has ${dirtyChanges.length} dirty entries but 0 resolvable items`,
+          `[SyncEngine] uploadDirtyItems: ${collectionName} has`,
+          dirtyChanges.length,
+          "dirty entries but 0 resolvable items",
           skipped
         );
         if (this.callbacks.onUploadSkip) {
@@ -3571,7 +3573,9 @@ var _SyncEngine = class _SyncEngine {
       }
       if (unacked.length > 0) {
         console.warn(
-          `[SyncEngine] uploadDirtyItems: ${collection}: ${unacked.length} items sent but not acknowledged:`,
+          `[SyncEngine] uploadDirtyItems: ${collection}:`,
+          unacked.length,
+          "items sent but not acknowledged:",
           unacked
         );
       }
@@ -4678,6 +4682,24 @@ var _SyncedDb = class _SyncedDb {
     }
     return fn.call(this.serverUpdateNotifier, timeoutMs);
   }
+  /**
+   * Call an arbitrary worker service via the configured server-update
+   * notifier (typically over its WebSocket). Delegates to
+   * `serverUpdateNotifier.callWorker`. Throws if no notifier is
+   * configured or the notifier doesn't support worker invocation.
+   *
+   * @see I_ServerUpdateNotifier.callWorker
+   */
+  async callWorker(service, payload, options) {
+    var _a;
+    const fn = (_a = this.serverUpdateNotifier) == null ? void 0 : _a.callWorker;
+    if (!fn) {
+      throw new Error(
+        "[SyncedDb] callWorker: no serverUpdateNotifier or notifier does not support callWorker"
+      );
+    }
+    return fn.call(this.serverUpdateNotifier, service, payload, options);
+  }
   /**
    * Register a collection for sync at runtime. See `I_SyncedDb.addCollectionToSync`.
    */
@@ -6409,7 +6431,9 @@ var _SyncedDb = class _SyncedDb {
       }
       if (orphanCount > 0) {
         console.warn(
-          `[SyncedDb] init(${name}): ${orphanCount} dirty record(s) had no matching Dexie main row \u2014 included in in-mem pending next sync.`
+          `[SyncedDb] init(${name}):`,
+          orphanCount,
+          "dirty record(s) had no matching Dexie main row \u2014 included in in-mem pending next sync."
         );
       }
       allItems.length = 0;
@@ -9385,7 +9409,13 @@ var RestProxy = class {
         this._requestCount++;
         if (this.timeRequestsPrint) {
           console.log(
-            `[RestProxy] ${operation}: ${elapsed.toFixed(2)}ms (total: ${this._totalRequestMs.toFixed(2)}ms, count: ${this._requestCount})`
+            `[RestProxy] ${operation}:`,
+            elapsed.toFixed(2),
+            "ms (total:",
+            this._totalRequestMs.toFixed(2),
+            "ms, count:",
+            this._requestCount,
+            ")"
           );
         }
       }
@@ -9517,7 +9547,13 @@ var RestProxy = class {
         this._requestCount++;
         if (this.timeRequestsPrint) {
           console.log(
-            `[RestProxy] findNewerManyStream: ${elapsed.toFixed(2)}ms (total: ${this._totalRequestMs.toFixed(2)}ms, count: ${this._requestCount})`
+            "[RestProxy] findNewerManyStream:",
+            elapsed.toFixed(2),
+            "ms (total:",
+            this._totalRequestMs.toFixed(2),
+            "ms, count:",
+            this._requestCount,
+            ")"
           );
         }
       }
@@ -9695,6 +9731,13 @@ var Ebus2ProxyServerUpdateNotifier = class {
      * after if any are still pending).
      */
     this._pendingRttPings = /* @__PURE__ */ new Map();
+    /**
+     * Pending `callWorker` promises keyed by request id. The matching
+     * `response` (or correlated `error`) frame resolves/rejects them.
+     * Cleared on disconnect — pending callers are rejected with a
+     * "WebSocket closed" error and the per-call timeout is freed.
+     */
+    this._pendingRequests = /* @__PURE__ */ new Map();
     var _a, _b, _c, _d, _e;
     this.endpoint = config.wsUrl;
     this.wsUrl = config.wsUrl;
@@ -9751,6 +9794,18 @@ var Ebus2ProxyServerUpdateNotifier = class {
     this.onWsDisconnectCallbacks.length = 0;
     this.onWsReconnectCallbacks.length = 0;
     this._pendingRttPings.clear();
+    for (const [, pending] of this._pendingRequests) {
+      clearTimeout(pending.timer);
+      if (pending.abortListener && pending.signal) {
+        pending.signal.removeEventListener("abort", pending.abortListener);
+      }
+      pending.reject(
+        new Error(
+          `[Ebus2ProxyNotifier] callWorker(${pending.service}): notifier disposed`
+        )
+      );
+    }
+    this._pendingRequests.clear();
   }
   isConnected() {
     return this.connected && !this.forcedOffline;
@@ -9832,6 +9887,111 @@ var Ebus2ProxyServerUpdateNotifier = class {
     }
     return performance.now() - t0;
   }
+  /**
+   * Call an arbitrary ebus2 worker service over the existing
+   * WebSocket and return its msgpack-decoded reply.
+   *
+   * Uses the WS `request` / `response` correlation introduced in
+   * ebus-proxy 2.0 — the whole frame is msgpack, so the payload is
+   * sent as a raw value (no base64, no JSON envelope). Lower latency
+   * than HTTP (no TCP/TLS handshake, no per-call connection setup)
+   * and reuses the same auth + connection that the pub/sub channel
+   * is already using.
+   *
+   * Errors:
+   * - WebSocket not OPEN → throws synchronously (rejects).
+   * - Worker error / proxy error → rejects with the proxy's `error`
+   *   frame message.
+   * - Per-call `timeoutMs` elapses → rejects with timeout error and
+   *   removes the pending entry. The proxy may still process the
+   *   call server-side; client-side state is freed regardless.
+   * - WebSocket closes mid-flight → rejects with "WebSocket closed
+   *   before reply".
+   * - Caller `options.signal` aborts → rejects with "aborted".
+   *
+   * Multiple concurrent calls are safe — each request uses a unique
+   * correlation id and the `response`/`error` dispatch keys off it.
+   *
+   * @param service Worker service name registered on cry-ebus2.
+   * @param payload Anything msgpack+structuredClone can serialize.
+   *   BSON ObjectId/Timestamp are preprocessed like all other WS
+   *   frames. Pass `undefined` to call without a payload.
+   * @param options.timeoutMs Per-call timeout (default 5000). Also
+   *   forwarded as the proxy-side `timeout` field.
+   * @param options.signal External AbortSignal for cancellation.
+   * @returns Worker's reply, msgpack-decoded as T.
+   */
+  async callWorker(service, payload, options) {
+    var _a;
+    if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+      throw new Error(
+        `[Ebus2ProxyNotifier] callWorker(${service}): WebSocket not OPEN`
+      );
+    }
+    const timeoutMs = (_a = options == null ? void 0 : options.timeoutMs) != null ? _a : 5e3;
+    const id = `req-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    return new Promise((resolve, reject) => {
+      var _a2;
+      if ((_a2 = options == null ? void 0 : options.signal) == null ? void 0 : _a2.aborted) {
+        reject(new Error(`[Ebus2ProxyNotifier] callWorker(${service}): aborted`));
+        return;
+      }
+      const timer = setTimeout(() => {
+        const pending = this._pendingRequests.get(id);
+        if (!pending) return;
+        this._pendingRequests.delete(id);
+        if (pending.abortListener && pending.signal) {
+          pending.signal.removeEventListener("abort", pending.abortListener);
+        }
+        reject(
+          new Error(
+            `[Ebus2ProxyNotifier] callWorker(${service}): timeout after ${timeoutMs}ms`
+          )
+        );
+      }, timeoutMs);
+      const abortListener = (options == null ? void 0 : options.signal) ? () => {
+        const pending = this._pendingRequests.get(id);
+        if (!pending) return;
+        clearTimeout(pending.timer);
+        this._pendingRequests.delete(id);
+        reject(
+          new Error(`[Ebus2ProxyNotifier] callWorker(${service}): aborted`)
+        );
+      } : void 0;
+      if (abortListener && options.signal) {
+        options.signal.addEventListener("abort", abortListener, { once: true });
+      }
+      this._pendingRequests.set(id, {
+        resolve,
+        reject,
+        timer,
+        service,
+        abortListener,
+        signal: options == null ? void 0 : options.signal
+      });
+      const req = {
+        type: "request",
+        service,
+        payload: payload !== void 0 ? preprocessForPack2(payload) : void 0,
+        timeout: timeoutMs,
+        id
+      };
+      try {
+        this.ws.send(packr2.pack(req));
+      } catch (err) {
+        clearTimeout(timer);
+        this._pendingRequests.delete(id);
+        if (abortListener && options.signal) {
+          options.signal.removeEventListener("abort", abortListener);
+        }
+        reject(
+          new Error(
+            `[Ebus2ProxyNotifier] callWorker(${service}): send failed: ${err}`
+          )
+        );
+      }
+    });
+  }
   /**
    * Set connection lifecycle callbacks.
    * These are merged with any callbacks provided in the constructor config.
@@ -9943,6 +10103,20 @@ var Ebus2ProxyServerUpdateNotifier = class {
     this.connected = false;
     this.subscribedChannels.clear();
     this.clearTimers();
+    if (this._pendingRequests.size > 0) {
+      for (const [, pending] of this._pendingRequests) {
+        clearTimeout(pending.timer);
+        if (pending.abortListener && pending.signal) {
+          pending.signal.removeEventListener("abort", pending.abortListener);
+        }
+        pending.reject(
+          new Error(
+            `[Ebus2ProxyNotifier] callWorker(${pending.service}): WebSocket closed before reply`
+          )
+        );
+      }
+      this._pendingRequests.clear();
+    }
     const reason = event.reason || `Code: ${event.code}`;
     if (wasConnected) {
       for (const callback of this.onWsDisconnectCallbacks) {
@@ -9986,7 +10160,37 @@ var Ebus2ProxyServerUpdateNotifier = class {
             }
           }
           break;
+        case "response": {
+          if (message.id !== void 0) {
+            const pending = this._pendingRequests.get(message.id);
+            if (pending) {
+              clearTimeout(pending.timer);
+              this._pendingRequests.delete(message.id);
+              if (pending.abortListener && pending.signal) {
+                pending.signal.removeEventListener("abort", pending.abortListener);
+              }
+              pending.resolve(message.data);
+            }
+          }
+          break;
+        }
         case "error":
+          if (message.id !== void 0) {
+            const pending = this._pendingRequests.get(message.id);
+            if (pending) {
+              clearTimeout(pending.timer);
+              this._pendingRequests.delete(message.id);
+              if (pending.abortListener && pending.signal) {
+                pending.signal.removeEventListener("abort", pending.abortListener);
+              }
+              pending.reject(
+                new Error(
+                  `[Ebus2ProxyNotifier] callWorker(${pending.service}): ${message.error}`
+                )
+              );
+              break;
+            }
+          }
           console.error(`[Ebus2ProxyNotifier] WebSocket server error: ${message.error}`, message.error);
           break;
       }

package/dist/src/db/Ebus2ProxyServerUpdateNotifier.d.ts

@@ -69,6 +69,13 @@ export declare class Ebus2ProxyServerUpdateNotifier implements I_ServerUpdateNot
      * after if any are still pending).
      */
     private _pendingRttPings;
+    /**
+     * Pending `callWorker` promises keyed by request id. The matching
+     * `response` (or correlated `error`) frame resolves/rejects them.
+     * Cleared on disconnect — pending callers are rejected with a
+     * "WebSocket closed" error and the per-call timeout is freed.
+     */
+    private _pendingRequests;
     constructor(config: Ebus2ProxyServerUpdateNotifierConfig);
     subscribe(callback: ServerUpdateCallback): () => void;
     connect(): Promise<void>;
@@ -110,6 +117,44 @@ export declare class Ebus2ProxyServerUpdateNotifier implements I_ServerUpdateNot
      * @returns RTT in milliseconds (full round-trip)
      */
     measureEndToEndRtt(timeoutMs?: number): Promise<number>;
+    /**
+     * Call an arbitrary ebus2 worker service over the existing
+     * WebSocket and return its msgpack-decoded reply.
+     *
+     * Uses the WS `request` / `response` correlation introduced in
+     * ebus-proxy 2.0 — the whole frame is msgpack, so the payload is
+     * sent as a raw value (no base64, no JSON envelope). Lower latency
+     * than HTTP (no TCP/TLS handshake, no per-call connection setup)
+     * and reuses the same auth + connection that the pub/sub channel
+     * is already using.
+     *
+     * Errors:
+     * - WebSocket not OPEN → throws synchronously (rejects).
+     * - Worker error / proxy error → rejects with the proxy's `error`
+     *   frame message.
+     * - Per-call `timeoutMs` elapses → rejects with timeout error and
+     *   removes the pending entry. The proxy may still process the
+     *   call server-side; client-side state is freed regardless.
+     * - WebSocket closes mid-flight → rejects with "WebSocket closed
+     *   before reply".
+     * - Caller `options.signal` aborts → rejects with "aborted".
+     *
+     * Multiple concurrent calls are safe — each request uses a unique
+     * correlation id and the `response`/`error` dispatch keys off it.
+     *
+     * @param service Worker service name registered on cry-ebus2.
+     * @param payload Anything msgpack+structuredClone can serialize.
+     *   BSON ObjectId/Timestamp are preprocessed like all other WS
+     *   frames. Pass `undefined` to call without a payload.
+     * @param options.timeoutMs Per-call timeout (default 5000). Also
+     *   forwarded as the proxy-side `timeout` field.
+     * @param options.signal External AbortSignal for cancellation.
+     * @returns Worker's reply, msgpack-decoded as T.
+     */
+    callWorker<T = unknown>(service: string, payload?: unknown, options?: {
+        timeoutMs?: number;
+        signal?: AbortSignal;
+    }): Promise<T>;
     /**
      * Set connection lifecycle callbacks.
      * These are merged with any callbacks provided in the constructor config.

package/dist/src/db/SyncedDb.d.ts

@@ -78,6 +78,18 @@ export declare class SyncedDb implements I_SyncedDb {
      * notifier is configured or the notifier doesn't support it.
      */
     measureEndToEndRtt(timeoutMs?: number): Promise<number>;
+    /**
+     * Call an arbitrary worker service via the configured server-update
+     * notifier (typically over its WebSocket). Delegates to
+     * `serverUpdateNotifier.callWorker`. Throws if no notifier is
+     * configured or the notifier doesn't support worker invocation.
+     *
+     * @see I_ServerUpdateNotifier.callWorker
+     */
+    callWorker<T = unknown>(service: string, payload?: unknown, options?: {
+        timeoutMs?: number;
+        signal?: AbortSignal;
+    }): Promise<T>;
     /**
      * Register a collection for sync at runtime. See `I_SyncedDb.addCollectionToSync`.
      */

package/dist/src/types/I_ServerUpdateNotifier.d.ts

@@ -83,4 +83,29 @@ export interface I_ServerUpdateNotifier {
      * @param timeoutMs Max wait for response (default: 5000)
      */
     measureEndToEndRtt?(timeoutMs?: number): Promise<number>;
+    /**
+     * Call an arbitrary worker service via the notifier's transport and
+     * return its decoded reply.
+     *
+     * For WS-capable notifiers, this typically rides the same WebSocket
+     * connection as pub/sub (lower latency than spinning up an HTTP
+     * fetch) and uses transport-native correlation (`request` /
+     * `response` frames). Implementations may fall back to HTTP if the
+     * transport doesn't support inline RPC.
+     *
+     * Optional. Throws if transport is not connected, the worker errors,
+     * or the per-call timeout elapses. Implementations that don't
+     * support worker invocation may omit this method.
+     *
+     * @param service Worker service name (e.g. `"echo"`, `"print"`).
+     * @param payload Service-specific payload — must be serializable by
+     *   the transport's codec (msgpack with `structuredClone: true` for
+     *   the WS implementation).
+     * @param options.timeoutMs Per-call timeout in milliseconds.
+     * @param options.signal External AbortSignal for cancellation.
+     */
+    callWorker?<T = unknown>(service: string, payload?: unknown, options?: {
+        timeoutMs?: number;
+        signal?: AbortSignal;
+    }): Promise<T>;
 }

package/dist/src/types/I_SyncedDb.d.ts

@@ -1118,6 +1118,26 @@ export interface I_SyncedDb {
      * @returns RTT in milliseconds (full round-trip)
      */
     measureEndToEndRtt(timeoutMs?: number): Promise<number>;
+    /**
+     * Call an arbitrary ebus2 worker service via the configured server-
+     * update notifier and return the worker's decoded reply. Routes
+     * through the existing WebSocket on the
+     * `Ebus2ProxyServerUpdateNotifier` implementation (ebus-proxy ≥ 2.0
+     * `request` / `response` frames). Throws if no notifier is
+     * configured, the transport is not connected, the worker errors, or
+     * the per-call timeout elapses.
+     *
+     * @param service Worker service name (e.g. "echo", "print").
+     * @param payload Anything msgpack+structuredClone can serialize.
+     *   BSON ObjectId/Timestamp preprocessed automatically.
+     * @param options.timeoutMs Per-call timeout (default 5000).
+     * @param options.signal External AbortSignal for cancellation.
+     * @returns Worker's reply typed as T (caller-asserted).
+     */
+    callWorker<T = unknown>(service: string, payload?: unknown, options?: {
+        timeoutMs?: number;
+        signal?: AbortSignal;
+    }): Promise<T>;
     /**
      * Get metadata for a single object.
      * @param collection Collection name

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cry-synced-db-client",
-  "version": "0.1.178",
+  "version": "0.1.180",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -29,12 +29,12 @@
   "devDependencies": {
     "@types/bun": "latest",
     "bson": "^7.2.0",
-    "cry-ebus-proxy": "^1.0.3",
+    "cry-ebus-proxy": "^2.0.0",
     "dexie": "^4.4.2",
     "esbuild": "^0.28.0",
     "fake-indexeddb": "^6.2.5",
     "typescript": "^6",
-    "vitest": "^4.1.5"
+    "vitest": "^4.1.6"
   },
   "dependencies": {
     "cry-helpers": "^2.1.194",