cross-tab-worker-databus 0.4.0 → 0.5.0

package/dist/core/data-bus.d.ts

@@ -1,17 +1,21 @@
 import type { WorkerClusterOptions } from './cluster';
 import type { DataBusErrorHandler, DataBusMessageHandler, DataBusStatusHandler, DataBusTransport, WorkerStatus } from './types';
 import type { DataBusTraceOptions } from './trace';
+import type { DataBusReplayPersistence } from './replay-persistence';
 /** Constructor options for {@link CrossTabDataBus}. Extends WorkerClusterOptions
  * (cluster coordination config) with the transport, initial connection config,
  * and trace options. */
 /** Replay (bounded local history) configuration. When present, the DataBus
- * keeps an in-memory ring buffer of the most recent dispatched publications
- * per topic, and `subscribe()` can deliver that history to late-joining
- * handlers. Buffers live in memory only — nothing is persisted. */
-export interface DataBusReplayOptions {
+ * keeps a bounded ring buffer of the most recent dispatched publications per
+ * topic, and `subscribe()` can deliver that history to late-joining handlers.
+ * Buffers live in memory by default; an optional persistence backend can make
+ * them durable. */
+export interface DataBusReplayOptions<TData = unknown> {
     /** Maximum buffered publications per topic. Oldest entries are evicted
      * first. Default 100. */
     maxPerTopic?: number;
+    /** Optional durable history backend. Defaults to in-memory only. */
+    persistence?: DataBusReplayPersistence<TData>;
 }
 export interface CrossTabDataBusOptions<TConfig, TData> extends Omit<WorkerClusterOptions, 'handlers'> {
     transport: DataBusTransport<TConfig, TData>;
@@ -19,7 +23,7 @@ export interface CrossTabDataBusOptions<TConfig, TData> extends Omit<WorkerClust
     autoStart?: boolean;
     trace?: DataBusTraceOptions;
     /** Opt-in bounded per-topic history. Absent → no buffering, zero overhead. */
-    replay?: DataBusReplayOptions;
+    replay?: DataBusReplayOptions<TData>;
 }
 /**
  * High-level cross-tab pub/sub client.
@@ -38,6 +42,8 @@ export declare class CrossTabDataBus<TConfig = unknown, TData = unknown> {
     private readonly errorHandlers;
     private readonly replayBuffers;
     private readonly replayMaxPerTopic;
+    private readonly replayPersistence;
+    private readonly replayHydration;
     private readonly initialConfig;
     private readonly hasInitialConfig;
     private readonly trace;
@@ -117,6 +123,7 @@ export declare class CrossTabDataBus<TConfig = unknown, TData = unknown> {
     /** Append a dispatched publication to the topic's replay ring buffer.
      * No-op when replay is disabled. */
     private recordReplay;
+    private hydrateReplay;
     /** Deliver buffered history to a newly-registered handler. For an exact
      * topic this is that topic's ring; for a wildcard subscription every
      * buffered topic matching the pattern contributes (in buffer insertion

package/dist/core/data-bus.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"data-bus.d.ts","sourceRoot":"","sources":["../../src/core/data-bus.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"data-bus.d.ts","sourceRoot":"","sources":["../../src/core/data-bus.ts"],"names":[],"mappings":"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"}

package/dist/core/replay-persistence.d.ts

@@ -0,0 +1,13 @@
+import type { DataBusMessage } from './types';
+/** Optional persistence backend for replay history. */
+export interface DataBusReplayPersistence<TData = unknown> {
+    load(): Promise<ReadonlyArray<DataBusMessage<TData>>>;
+    append(message: DataBusMessage<TData>): Promise<void>;
+}
+export interface IndexedDbReplayPersistenceOptions {
+    dbName?: string;
+    maxPerTopic: number;
+}
+/** Create a browser IndexedDB-backed replay store. */
+export declare function createIndexedDbReplayPersistence<TData = unknown>(options: IndexedDbReplayPersistenceOptions): DataBusReplayPersistence<TData>;
+//# sourceMappingURL=replay-persistence.d.ts.map

package/dist/core/replay-persistence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay-persistence.d.ts","sourceRoot":"","sources":["../../src/core/replay-persistence.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C,uDAAuD;AACvD,MAAM,WAAW,wBAAwB,CAAC,KAAK,GAAG,OAAO;IACvD,IAAI,IAAI,OAAO,CAAC,aAAa,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACtD,MAAM,CAAC,OAAO,EAAE,cAAc,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACvD;AAED,MAAM,WAAW,iCAAiC;IAChD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,sDAAsD;AACtD,wBAAgB,gCAAgC,CAAC,KAAK,GAAG,OAAO,EAC9D,OAAO,EAAE,iCAAiC,GACzC,wBAAwB,CAAC,KAAK,CAAC,CA6CjC"}

package/dist/index.d.ts

@@ -10,6 +10,8 @@
  */
 export { CrossTabDataBus } from './core/data-bus';
 export type { CrossTabDataBusOptions, DataBusReplayOptions } from './core/data-bus';
+export { createIndexedDbReplayPersistence } from './core/replay-persistence';
+export type { DataBusReplayPersistence, IndexedDbReplayPersistenceOptions } from './core/replay-persistence';
 export type { DataBusCoordinationTraceEvent, DataBusErrorTraceEvent, DataBusLifecycleTraceEvent, DataBusMetricsTraceEvent, DataBusStatusTraceEvent, DataBusSubscriptionTraceEvent, DataBusTraceEvent, DataBusTraceMode, DataBusTraceOptions } from './core/trace';
 export { WorkerClusterRuntime } from './core/cluster';
 export type { WorkerClusterHandlers, WorkerClusterOptions, WorkerClusterSnapshot } from './core/cluster';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,YAAY,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AACpF,YAAY,EACV,6BAA6B,EAC7B,sBAAsB,EACtB,0BAA0B,EAC1B,wBAAwB,EACxB,uBAAuB,EACvB,6BAA6B,EAC7B,iBAAiB,EACjB,gBAAgB,EAChB,mBAAmB,EACpB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AACtD,YAAY,EACV,qBAAqB,EACrB,oBAAoB,EACpB,qBAAqB,EACtB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,wBAAwB,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAChF,YAAY,EAAE,cAAc,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAC1F,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EACL,kBAAkB,EAClB,sBAAsB,EACvB,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,6BAA6B,EAC7B,sBAAsB,EACtB,aAAa,EACd,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACpD,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC/D,OAAO,EACL,0BAA0B,EAC1B,cAAc,EACd,eAAe,EACf,mBAAmB,EACnB,uBAAuB,EACvB,qBAAqB,EACrB,mBAAmB,EACpB,MAAM,gBAAgB,CAAC;AACxB,YAAY,EACV,mBAAmB,EACnB,cAAc,EACd,qBAAqB,EACrB,oBAAoB,EACpB,gBAAgB,EAChB,wBAAwB,EACxB,YAAY,EACZ,kBAAkB,EAClB,qBAAqB,EACrB,oBAAoB,EACpB,mBAAmB,EACnB,YAAY,EACZ,UAAU,EACV,WAAW,EACX,YAAY,EACb,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,YAAY,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AACpF,OAAO,EAAE,gCAAgC,EAAE,MAAM,2BAA2B,CAAC;AAC7E,YAAY,EAAE,wBAAwB,EAAE,iCAAiC,EAAE,MAAM,2BAA2B,CAAC;AAC7G,YAAY,EACV,6BAA6B,EAC7B,sBAAsB,EACtB,0BAA0B,EAC1B,wBAAwB,EACxB,uBAAuB,EACvB,6BAA6B,EAC7B,iBAAiB,EACjB,gBAAgB,EAChB,mBAAmB,EACpB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AACtD,YAAY,EACV,qBAAqB,EACrB,oBAAoB,EACpB,qBAAqB,EACtB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,wBAAwB,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAChF,YAAY,EAAE,cAAc,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAC1F,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EACL,kBAAkB,EAClB,sBAAsB,EACvB,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,6BAA6B,EAC7B,sBAAsB,EACtB,aAAa,EACd,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACpD,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC/D,OAAO,EACL,0BAA0B,EAC1B,cAAc,EACd,eAAe,EACf,mBAAmB,EACnB,uBAAuB,EACvB,qBAAqB,EACrB,mBAAmB,EACpB,MAAM,gBAAgB,CAAC;AACxB,YAAY,EACV,mBAAmB,EACnB,cAAc,EACd,qBAAqB,EACrB,oBAAoB,EACpB,gBAAgB,EAChB,wBAAwB,EACxB,YAAY,EACZ,kBAAkB,EAClB,qBAAqB,EACrB,oBAAoB,EACpB,mBAAmB,EACnB,YAAY,EACZ,UAAU,EACV,WAAW,EACX,YAAY,EACb,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -12,9 +12,57 @@ import {
   selectRebalanceTarget,
   selectWorkerBackend,
   topicMatchesPattern
-} from "./chunk-ZGQRELIV.js";
+} from "./chunk-W7DAXK4D.js";
 import "./chunk-5WRI5ZAA.js";
 
+// src/core/replay-persistence.ts
+function createIndexedDbReplayPersistence(options) {
+  const indexedDb = globalThis.indexedDB;
+  if (!indexedDb) throw new Error("IndexedDB is unavailable in this environment.");
+  const dbName = options.dbName ?? "cross-tab-worker-databus";
+  const storeName = "replay";
+  const maxPerTopic = options.maxPerTopic;
+  if (!Number.isSafeInteger(maxPerTopic) || maxPerTopic <= 0) {
+    throw new TypeError(`maxPerTopic must be a positive safe integer, got ${String(maxPerTopic)}.`);
+  }
+  let dbPromise = null;
+  const open = () => {
+    if (dbPromise) return dbPromise;
+    dbPromise = new Promise((resolve, reject) => {
+      const request = indexedDb.open(dbName, 1);
+      request.onupgradeneeded = () => request.result.createObjectStore(storeName, { keyPath: "topic" });
+      request.onsuccess = () => resolve(request.result);
+      request.onerror = () => reject(request.error ?? new Error("Failed to open replay database."));
+    });
+    return dbPromise;
+  };
+  return {
+    async load() {
+      const db = await open();
+      return new Promise((resolve, reject) => {
+        const request = db.transaction(storeName, "readonly").objectStore(storeName).getAll();
+        request.onsuccess = () => resolve(request.result.flatMap((record) => record.messages));
+        request.onerror = () => reject(request.error ?? new Error("Failed to load replay history."));
+      });
+    },
+    async append(message) {
+      const db = await open();
+      await new Promise((resolve, reject) => {
+        const transaction = db.transaction(storeName, "readwrite");
+        const store = transaction.objectStore(storeName);
+        const request = store.get(message.topic);
+        request.onsuccess = () => {
+          const messages = (request.result?.messages ?? []).concat(message).slice(-maxPerTopic);
+          store.put({ topic: message.topic, messages });
+        };
+        request.onerror = () => reject(request.error ?? new Error("Failed to read replay history."));
+        transaction.oncomplete = () => resolve();
+        transaction.onerror = () => reject(transaction.error ?? new Error("Failed to persist replay history."));
+      });
+    }
+  };
+}
+
 // src/websocket.ts
 var WS_OPEN = 1;
 var WebSocketTransport = class {
@@ -123,6 +171,7 @@ export {
   WebSocketTransport,
   WorkerClusterRuntime,
   createBrowserEnvironment,
+  createIndexedDbReplayPersistence,
   createOpaqueKey,
   createWebSocketDataBus,
   getOrCreateTabId,

package/dist/index.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
-  "sources": ["../src/websocket.ts"],
-  "sourcesContent": ["/**\n * WebSocketTransport \u2014 a dependency-free transport over a plain WebSocket.\n *\n * Validates the `DataBusTransport` abstraction with a second, minimal backend:\n * any WebSocket server that speaks the tiny JSON protocol below can back the\n * same cross-tab clustering stack (owner dedup, sticky routes, EVENT fan-out)\n * that the Centrifuge backend uses.\n *\n * Wire protocol (JSON text frames):\n * - client \u2192 server: `{\"op\":\"subscribe\"|\"unsubscribe\"|\"publish\",\"topic\":...,\"data\":...}`\n * - server \u2192 client: `{\"topic\":...,\"data\":...}` for publications; anything\n *   without a string `topic` field is ignored (forward-compatible).\n */\nimport { CrossTabDataBus } from './core/data-bus';\nimport type { CrossTabDataBusOptions } from './core/data-bus';\nimport type {\n  DataBusTransport,\n  DataBusTransportHandlers,\n  MaybePromise,\n  WorkerStatus\n} from './core/types';\n\n/** Minimal WebSocket surface used by the transport. Matches the browser\n * `WebSocket` subset the transport touches; injectable for tests and runtimes. */\nexport interface WebSocketLike {\n  /** Current connection state; 1 (OPEN) means frames may be sent. */\n  readonly readyState?: number;\n  send(data: string): void;\n  close(code?: number, reason?: string): void;\n  onopen: (() => void) | null;\n  onclose: (() => void) | null;\n  onerror: (() => void) | null;\n  onmessage: ((event: { data: unknown }) => void) | null;\n}\n\n/** Connection configuration for {@link WebSocketTransport}. */\nexport interface WebSocketDataBusConfig {\n  /** WebSocket endpoint, e.g. `wss://example.test/ws`. */\n  url: string;\n  /** Subprotocol(s) passed to the WebSocket handshake. */\n  protocols?: string | string[];\n  /** Custom socket factory. Defaults to the global `WebSocket`; injectable\n   * for tests and non-browser runtimes. */\n  webSocketFactory?: (url: string, protocols?: string | string[]) => WebSocketLike;\n}\n\n/** Options for creating a fully-configured CrossTabDataBus with a WebSocket transport. */\nexport interface CreateWebSocketDataBusOptions<TData = unknown>\n  extends Omit<\n    CrossTabDataBusOptions<WebSocketDataBusConfig, TData>,\n    'autoStart' | 'clusterKey' | 'initialConfig' | 'transport'\n  > {\n  /** WebSocket connection configuration. */\n  connection: WebSocketDataBusConfig;\n  /** Cluster key for cross-tab coordination. Defaults to the connection URL. */\n  clusterKey?: string;\n}\n\nconst WS_OPEN = 1;\n\n/** Transport that talks a minimal JSON protocol over a plain WebSocket.\n * Connection lifecycle maps directly to the DataBus status vocabulary:\n * open \u2192 `connected`, close \u2192 `disconnected`, error \u2192 `error` (which the\n * DataBus treats as its auto-recovery trigger). The transport holds no\n * reconnection logic of its own \u2014 reopening is the DataBus's job. */\nexport class WebSocketTransport<TData = unknown>\n  implements DataBusTransport<WebSocketDataBusConfig, TData>\n{\n  private socket: WebSocketLike | null = null;\n  private handlers: DataBusTransportHandlers<TData> | null = null;\n  private readonly subscribedTopics = new Set<string>();\n\n  constructor(private readonly connection: WebSocketDataBusConfig) {}\n\n  /** Open the WebSocket and wire lifecycle listeners. A factory failure is\n   * reported through `onStatus('error')` so the DataBus can recover. */\n  start(config: WebSocketDataBusConfig, handlers: DataBusTransportHandlers<TData>): MaybePromise<void> {\n    if (this.socket) return;\n    this.handlers = handlers;\n    // The factory may live on the constructor connection (createWebSocketDataBus\n    // path) or on the runtime config (direct transport use) \u2014 accept both.\n    const factory = config.webSocketFactory ?? this.connection.webSocketFactory ?? defaultWebSocketFactory;\n    const protocols = config.protocols ?? this.connection.protocols;\n    let socket: WebSocketLike;\n    try {\n      socket = factory(config.url, protocols);\n    } catch (error) {\n      handlers.onStatus('error');\n      handlers.onError(error);\n      return;\n    }\n    socket.onopen = () => {\n      // Re-assert every topic so a reopened socket (recovery path) restores\n      // the server-side subscriptions without DataBus involvement.\n      for (const topic of this.subscribedTopics) {\n        this.sendFrame({ op: 'subscribe', topic });\n      }\n      handlers.onStatus('connected');\n    };\n    socket.onclose = () => handlers.onStatus('disconnected');\n    socket.onerror = () => handlers.onStatus('error');\n    socket.onmessage = event => this.handleMessage(event.data);\n    this.socket = socket;\n  }\n\n  /** Idempotent: re-subscribing an active topic re-sends the frame but does\n   * not duplicate the local tracking entry. */\n  subscribe(topic: string): MaybePromise<void> {\n    this.subscribedTopics.add(topic);\n    this.sendFrame({ op: 'subscribe', topic });\n  }\n\n  /** Idempotent: unsubscribing an unknown topic is a no-op. */\n  unsubscribe(topic: string): MaybePromise<void> {\n    this.subscribedTopics.delete(topic);\n    this.sendFrame({ op: 'unsubscribe', topic });\n  }\n\n  /** Publish `data` to `topic` as a JSON frame. Requires an open socket. */\n  publish(topic: string, data: unknown): MaybePromise<void> {\n    this.sendFrame({ op: 'publish', topic, data });\n  }\n\n  /** Close the socket and drop all state. Safe to call multiple times. */\n  stop(): MaybePromise<void> {\n    const socket = this.socket;\n    this.socket = null;\n    this.handlers = null;\n    this.subscribedTopics.clear();\n    socket?.close();\n  }\n\n  /** Send one JSON frame. Frames are dropped with an `onError` report when\n   * the socket is not open \u2014 subscribe frames are re-sent on open, so the\n   * only real loss is a publish during a disconnect window. */\n  private sendFrame(payload: { op: string; topic: string; data?: unknown }): void {\n    if (this.socket?.readyState !== WS_OPEN) {\n      this.handlers?.onError(new Error(`WebSocket is not open; dropped \"${payload.op}\" frame.`));\n      return;\n    }\n    this.socket.send(JSON.stringify(payload));\n  }\n\n  /** Parse a server frame. Only objects carrying a string `topic` are\n   * publications; malformed JSON and unknown shapes are ignored so a chatty\n   * server cannot crash the message path. */\n  private handleMessage(raw: unknown): void {\n    let parsed: unknown;\n    if (typeof raw !== 'string') return;\n    try {\n      parsed = JSON.parse(raw);\n    } catch {\n      this.handlers?.onError(new Error('WebSocket server sent a non-JSON frame.'));\n      return;\n    }\n    if (!parsed || typeof parsed !== 'object') return;\n    const frame = parsed as Record<string, unknown>;\n    if (typeof frame.topic !== 'string') return;\n    this.handlers?.onMessage({ topic: frame.topic, data: frame.data as TData });\n  }\n}\n\n/** Resolve the platform WebSocket, or null in runtimes without one (SSR/Node). */\nfunction defaultWebSocketFactory(url: string, protocols?: string | string[]): WebSocketLike {\n  if (typeof WebSocket === 'undefined') {\n    throw new Error('WebSocketTransport requires a WebSocket implementation.');\n  }\n  return new WebSocket(url, protocols) as unknown as WebSocketLike;\n}\n\n/** Create a CrossTabDataBus backed by a plain WebSocket transport.\n * Cross-tab clustering (owner dedup, sticky routes, failover) works identically\n * to the Centrifuge backend \u2014 only the transport I/O differs. */\nexport function createWebSocketDataBus<TData = unknown>(\n  options: CreateWebSocketDataBusOptions<TData>\n): CrossTabDataBus<WebSocketDataBusConfig, TData> {\n  const { clusterKey, connection, ...dataBusOptions } = options;\n  return new CrossTabDataBus({\n    ...dataBusOptions,\n    autoStart: true,\n    clusterKey: clusterKey ?? connection.url,\n    initialConfig: connection,\n    transport: new WebSocketTransport<TData>(connection)\n  });\n}\n\n/** Re-export for convenience: the status type used by the transport. */\nexport type { WorkerStatus };\n"],
-  "mappings": ";;;;;;;;;;;;;;;;;;AA0DA,IAAM,UAAU;AAOT,IAAM,qBAAN,MAEP;AAAA,EAKE,YAA6B,YAAoC;AAApC;AAAA,EAAqC;AAAA,EAJ1D,SAA+B;AAAA,EAC/B,WAAmD;AAAA,EAC1C,mBAAmB,oBAAI,IAAY;AAAA;AAAA;AAAA,EAMpD,MAAM,QAAgC,UAA+D;AACnG,QAAI,KAAK,OAAQ;AACjB,SAAK,WAAW;AAGhB,UAAM,UAAU,OAAO,oBAAoB,KAAK,WAAW,oBAAoB;AAC/E,UAAM,YAAY,OAAO,aAAa,KAAK,WAAW;AACtD,QAAI;AACJ,QAAI;AACF,eAAS,QAAQ,OAAO,KAAK,SAAS;AAAA,IACxC,SAAS,OAAO;AACd,eAAS,SAAS,OAAO;AACzB,eAAS,QAAQ,KAAK;AACtB;AAAA,IACF;AACA,WAAO,SAAS,MAAM;AAGpB,iBAAW,SAAS,KAAK,kBAAkB;AACzC,aAAK,UAAU,EAAE,IAAI,aAAa,MAAM,CAAC;AAAA,MAC3C;AACA,eAAS,SAAS,WAAW;AAAA,IAC/B;AACA,WAAO,UAAU,MAAM,SAAS,SAAS,cAAc;AACvD,WAAO,UAAU,MAAM,SAAS,SAAS,OAAO;AAChD,WAAO,YAAY,WAAS,KAAK,cAAc,MAAM,IAAI;AACzD,SAAK,SAAS;AAAA,EAChB;AAAA;AAAA;AAAA,EAIA,UAAU,OAAmC;AAC3C,SAAK,iBAAiB,IAAI,KAAK;AAC/B,SAAK,UAAU,EAAE,IAAI,aAAa,MAAM,CAAC;AAAA,EAC3C;AAAA;AAAA,EAGA,YAAY,OAAmC;AAC7C,SAAK,iBAAiB,OAAO,KAAK;AAClC,SAAK,UAAU,EAAE,IAAI,eAAe,MAAM,CAAC;AAAA,EAC7C;AAAA;AAAA,EAGA,QAAQ,OAAe,MAAmC;AACxD,SAAK,UAAU,EAAE,IAAI,WAAW,OAAO,KAAK,CAAC;AAAA,EAC/C;AAAA;AAAA,EAGA,OAA2B;AACzB,UAAM,SAAS,KAAK;AACpB,SAAK,SAAS;AACd,SAAK,WAAW;AAChB,SAAK,iBAAiB,MAAM;AAC5B,YAAQ,MAAM;AAAA,EAChB;AAAA;AAAA;AAAA;AAAA,EAKQ,UAAU,SAA8D;AAC9E,QAAI,KAAK,QAAQ,eAAe,SAAS;AACvC,WAAK,UAAU,QAAQ,IAAI,MAAM,mCAAmC,QAAQ,EAAE,UAAU,CAAC;AACzF;AAAA,IACF;AACA,SAAK,OAAO,KAAK,KAAK,UAAU,OAAO,CAAC;AAAA,EAC1C;AAAA;AAAA;AAAA;AAAA,EAKQ,cAAc,KAAoB;AACxC,QAAI;AACJ,QAAI,OAAO,QAAQ,SAAU;AAC7B,QAAI;AACF,eAAS,KAAK,MAAM,GAAG;AAAA,IACzB,QAAQ;AACN,WAAK,UAAU,QAAQ,IAAI,MAAM,yCAAyC,CAAC;AAC3E;AAAA,IACF;AACA,QAAI,CAAC,UAAU,OAAO,WAAW,SAAU;AAC3C,UAAM,QAAQ;AACd,QAAI,OAAO,MAAM,UAAU,SAAU;AACrC,SAAK,UAAU,UAAU,EAAE,OAAO,MAAM,OAAO,MAAM,MAAM,KAAc,CAAC;AAAA,EAC5E;AACF;AAGA,SAAS,wBAAwB,KAAa,WAA8C;AAC1F,MAAI,OAAO,cAAc,aAAa;AACpC,UAAM,IAAI,MAAM,yDAAyD;AAAA,EAC3E;AACA,SAAO,IAAI,UAAU,KAAK,SAAS;AACrC;AAKO,SAAS,uBACd,SACgD;AAChD,QAAM,EAAE,YAAY,YAAY,GAAG,eAAe,IAAI;AACtD,SAAO,IAAI,gBAAgB;AAAA,IACzB,GAAG;AAAA,IACH,WAAW;AAAA,IACX,YAAY,cAAc,WAAW;AAAA,IACrC,eAAe;AAAA,IACf,WAAW,IAAI,mBAA0B,UAAU;AAAA,EACrD,CAAC;AACH;",
+  "sources": ["../src/core/replay-persistence.ts", "../src/websocket.ts"],
+  "sourcesContent": ["import type { DataBusMessage } from './types';\n\n/** Optional persistence backend for replay history. */\nexport interface DataBusReplayPersistence<TData = unknown> {\n  load(): Promise<ReadonlyArray<DataBusMessage<TData>>>;\n  append(message: DataBusMessage<TData>): Promise<void>;\n}\n\nexport interface IndexedDbReplayPersistenceOptions {\n  dbName?: string;\n  maxPerTopic: number;\n}\n\n/** Create a browser IndexedDB-backed replay store. */\nexport function createIndexedDbReplayPersistence<TData = unknown>(\n  options: IndexedDbReplayPersistenceOptions\n): DataBusReplayPersistence<TData> {\n  const indexedDb = globalThis.indexedDB;\n  if (!indexedDb) throw new Error('IndexedDB is unavailable in this environment.');\n  const dbName = options.dbName ?? 'cross-tab-worker-databus';\n  const storeName = 'replay';\n  const maxPerTopic = options.maxPerTopic;\n  if (!Number.isSafeInteger(maxPerTopic) || maxPerTopic <= 0) {\n    throw new TypeError(`maxPerTopic must be a positive safe integer, got ${String(maxPerTopic)}.`);\n  }\n  let dbPromise: Promise<IDBDatabase> | null = null;\n  const open = (): Promise<IDBDatabase> => {\n    if (dbPromise) return dbPromise;\n    dbPromise = new Promise((resolve, reject) => {\n      const request = indexedDb.open(dbName, 1);\n      request.onupgradeneeded = () => request.result.createObjectStore(storeName, { keyPath: 'topic' });\n      request.onsuccess = () => resolve(request.result);\n      request.onerror = () => reject(request.error ?? new Error('Failed to open replay database.'));\n    });\n    return dbPromise;\n  };\n  return {\n    async load() {\n      const db = await open();\n      return new Promise((resolve, reject) => {\n        const request = db.transaction(storeName, 'readonly').objectStore(storeName).getAll();\n        request.onsuccess = () => resolve(request.result.flatMap(record => record.messages as DataBusMessage<TData>[]));\n        request.onerror = () => reject(request.error ?? new Error('Failed to load replay history.'));\n      });\n    },\n    async append(message) {\n      const db = await open();\n      await new Promise<void>((resolve, reject) => {\n        const transaction = db.transaction(storeName, 'readwrite');\n        const store = transaction.objectStore(storeName);\n        const request = store.get(message.topic);\n        request.onsuccess = () => {\n          const messages = ((request.result?.messages ?? []) as DataBusMessage<TData>[]).concat(message).slice(-maxPerTopic);\n          store.put({ topic: message.topic, messages });\n        };\n        request.onerror = () => reject(request.error ?? new Error('Failed to read replay history.'));\n        transaction.oncomplete = () => resolve();\n        transaction.onerror = () => reject(transaction.error ?? new Error('Failed to persist replay history.'));\n      });\n    }\n  };\n}\n", "/**\n * WebSocketTransport \u2014 a dependency-free transport over a plain WebSocket.\n *\n * Validates the `DataBusTransport` abstraction with a second, minimal backend:\n * any WebSocket server that speaks the tiny JSON protocol below can back the\n * same cross-tab clustering stack (owner dedup, sticky routes, EVENT fan-out)\n * that the Centrifuge backend uses.\n *\n * Wire protocol (JSON text frames):\n * - client \u2192 server: `{\"op\":\"subscribe\"|\"unsubscribe\"|\"publish\",\"topic\":...,\"data\":...}`\n * - server \u2192 client: `{\"topic\":...,\"data\":...}` for publications; anything\n *   without a string `topic` field is ignored (forward-compatible).\n */\nimport { CrossTabDataBus } from './core/data-bus';\nimport type { CrossTabDataBusOptions } from './core/data-bus';\nimport type {\n  DataBusTransport,\n  DataBusTransportHandlers,\n  MaybePromise,\n  WorkerStatus\n} from './core/types';\n\n/** Minimal WebSocket surface used by the transport. Matches the browser\n * `WebSocket` subset the transport touches; injectable for tests and runtimes. */\nexport interface WebSocketLike {\n  /** Current connection state; 1 (OPEN) means frames may be sent. */\n  readonly readyState?: number;\n  send(data: string): void;\n  close(code?: number, reason?: string): void;\n  onopen: (() => void) | null;\n  onclose: (() => void) | null;\n  onerror: (() => void) | null;\n  onmessage: ((event: { data: unknown }) => void) | null;\n}\n\n/** Connection configuration for {@link WebSocketTransport}. */\nexport interface WebSocketDataBusConfig {\n  /** WebSocket endpoint, e.g. `wss://example.test/ws`. */\n  url: string;\n  /** Subprotocol(s) passed to the WebSocket handshake. */\n  protocols?: string | string[];\n  /** Custom socket factory. Defaults to the global `WebSocket`; injectable\n   * for tests and non-browser runtimes. */\n  webSocketFactory?: (url: string, protocols?: string | string[]) => WebSocketLike;\n}\n\n/** Options for creating a fully-configured CrossTabDataBus with a WebSocket transport. */\nexport interface CreateWebSocketDataBusOptions<TData = unknown>\n  extends Omit<\n    CrossTabDataBusOptions<WebSocketDataBusConfig, TData>,\n    'autoStart' | 'clusterKey' | 'initialConfig' | 'transport'\n  > {\n  /** WebSocket connection configuration. */\n  connection: WebSocketDataBusConfig;\n  /** Cluster key for cross-tab coordination. Defaults to the connection URL. */\n  clusterKey?: string;\n}\n\nconst WS_OPEN = 1;\n\n/** Transport that talks a minimal JSON protocol over a plain WebSocket.\n * Connection lifecycle maps directly to the DataBus status vocabulary:\n * open \u2192 `connected`, close \u2192 `disconnected`, error \u2192 `error` (which the\n * DataBus treats as its auto-recovery trigger). The transport holds no\n * reconnection logic of its own \u2014 reopening is the DataBus's job. */\nexport class WebSocketTransport<TData = unknown>\n  implements DataBusTransport<WebSocketDataBusConfig, TData>\n{\n  private socket: WebSocketLike | null = null;\n  private handlers: DataBusTransportHandlers<TData> | null = null;\n  private readonly subscribedTopics = new Set<string>();\n\n  constructor(private readonly connection: WebSocketDataBusConfig) {}\n\n  /** Open the WebSocket and wire lifecycle listeners. A factory failure is\n   * reported through `onStatus('error')` so the DataBus can recover. */\n  start(config: WebSocketDataBusConfig, handlers: DataBusTransportHandlers<TData>): MaybePromise<void> {\n    if (this.socket) return;\n    this.handlers = handlers;\n    // The factory may live on the constructor connection (createWebSocketDataBus\n    // path) or on the runtime config (direct transport use) \u2014 accept both.\n    const factory = config.webSocketFactory ?? this.connection.webSocketFactory ?? defaultWebSocketFactory;\n    const protocols = config.protocols ?? this.connection.protocols;\n    let socket: WebSocketLike;\n    try {\n      socket = factory(config.url, protocols);\n    } catch (error) {\n      handlers.onStatus('error');\n      handlers.onError(error);\n      return;\n    }\n    socket.onopen = () => {\n      // Re-assert every topic so a reopened socket (recovery path) restores\n      // the server-side subscriptions without DataBus involvement.\n      for (const topic of this.subscribedTopics) {\n        this.sendFrame({ op: 'subscribe', topic });\n      }\n      handlers.onStatus('connected');\n    };\n    socket.onclose = () => handlers.onStatus('disconnected');\n    socket.onerror = () => handlers.onStatus('error');\n    socket.onmessage = event => this.handleMessage(event.data);\n    this.socket = socket;\n  }\n\n  /** Idempotent: re-subscribing an active topic re-sends the frame but does\n   * not duplicate the local tracking entry. */\n  subscribe(topic: string): MaybePromise<void> {\n    this.subscribedTopics.add(topic);\n    this.sendFrame({ op: 'subscribe', topic });\n  }\n\n  /** Idempotent: unsubscribing an unknown topic is a no-op. */\n  unsubscribe(topic: string): MaybePromise<void> {\n    this.subscribedTopics.delete(topic);\n    this.sendFrame({ op: 'unsubscribe', topic });\n  }\n\n  /** Publish `data` to `topic` as a JSON frame. Requires an open socket. */\n  publish(topic: string, data: unknown): MaybePromise<void> {\n    this.sendFrame({ op: 'publish', topic, data });\n  }\n\n  /** Close the socket and drop all state. Safe to call multiple times. */\n  stop(): MaybePromise<void> {\n    const socket = this.socket;\n    this.socket = null;\n    this.handlers = null;\n    this.subscribedTopics.clear();\n    socket?.close();\n  }\n\n  /** Send one JSON frame. Frames are dropped with an `onError` report when\n   * the socket is not open \u2014 subscribe frames are re-sent on open, so the\n   * only real loss is a publish during a disconnect window. */\n  private sendFrame(payload: { op: string; topic: string; data?: unknown }): void {\n    if (this.socket?.readyState !== WS_OPEN) {\n      this.handlers?.onError(new Error(`WebSocket is not open; dropped \"${payload.op}\" frame.`));\n      return;\n    }\n    this.socket.send(JSON.stringify(payload));\n  }\n\n  /** Parse a server frame. Only objects carrying a string `topic` are\n   * publications; malformed JSON and unknown shapes are ignored so a chatty\n   * server cannot crash the message path. */\n  private handleMessage(raw: unknown): void {\n    let parsed: unknown;\n    if (typeof raw !== 'string') return;\n    try {\n      parsed = JSON.parse(raw);\n    } catch {\n      this.handlers?.onError(new Error('WebSocket server sent a non-JSON frame.'));\n      return;\n    }\n    if (!parsed || typeof parsed !== 'object') return;\n    const frame = parsed as Record<string, unknown>;\n    if (typeof frame.topic !== 'string') return;\n    this.handlers?.onMessage({ topic: frame.topic, data: frame.data as TData });\n  }\n}\n\n/** Resolve the platform WebSocket, or null in runtimes without one (SSR/Node). */\nfunction defaultWebSocketFactory(url: string, protocols?: string | string[]): WebSocketLike {\n  if (typeof WebSocket === 'undefined') {\n    throw new Error('WebSocketTransport requires a WebSocket implementation.');\n  }\n  return new WebSocket(url, protocols) as unknown as WebSocketLike;\n}\n\n/** Create a CrossTabDataBus backed by a plain WebSocket transport.\n * Cross-tab clustering (owner dedup, sticky routes, failover) works identically\n * to the Centrifuge backend \u2014 only the transport I/O differs. */\nexport function createWebSocketDataBus<TData = unknown>(\n  options: CreateWebSocketDataBusOptions<TData>\n): CrossTabDataBus<WebSocketDataBusConfig, TData> {\n  const { clusterKey, connection, ...dataBusOptions } = options;\n  return new CrossTabDataBus({\n    ...dataBusOptions,\n    autoStart: true,\n    clusterKey: clusterKey ?? connection.url,\n    initialConfig: connection,\n    transport: new WebSocketTransport<TData>(connection)\n  });\n}\n\n/** Re-export for convenience: the status type used by the transport. */\nexport type { WorkerStatus };\n"],
+  "mappings": "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",
   "names": []
 }

package/docs/README.md

@@ -10,6 +10,7 @@
 | [API Reference](./api.md) | Public API, types, methods, return values, and behavior |
 | [Architecture](./architecture.md) | Worker cluster, routing, storage, migration, and degradation design |
 | [Capabilities Matrix](./capabilities.md) | Implemented, not implemented, and planned capabilities matrix |
+| [Roadmap](./roadmap.md) | Release-oriented priorities and verification checklist |
 | [../examples/demo](../examples/demo) | Runnable multi-tab browser demo |
 | [../CHANGELOG.md](../CHANGELOG.md) | Version changelog |
 
@@ -19,4 +20,4 @@
 2. For production configuration, read [Configuration](./configuration.md).
 3. When developing wrappers or custom transports, read [API Reference](./api.md).
 4. When troubleshooting cross-tab behavior, read [Architecture](./architecture.md).
-5. When evaluating current boundaries and future plans, read [Capabilities Matrix](./capabilities.md).
+5. When evaluating current boundaries and future plans, read [Capabilities Matrix](./capabilities.md).

package/docs/api.md

@@ -80,7 +80,7 @@ Registers a local subscription and returns a cleanup function.
 - The current tab only leaves the topic after the last handler is released.
 - Subscriptions are automatically queued when the transport is not yet ready.
 - Wildcard subscriptions: a topic ending in `.*` (`chat.*`) matches any remainder, and `*` matches everything. The pattern is routed, owned, and transport-subscribed as a literal channel; publications tagged with a matching concrete topic (or with the pattern itself) are delivered to wildcard handlers. See `topicMatchesPattern` below.
-- Replay (opt-in): construct the bus with `replay: { maxPerTopic }` and pass `{ replay: true | n }` as the third `subscribe()` argument. `maxPerTopic` must be a positive safe integer. The new handler immediately receives the buffered history (up to `n`, capped by `maxPerTopic`, default 100) with `message.replayed: true`, so late joiners do not miss earlier publications. Only dispatched publications are buffered (a topic with no local subscriber drops them as unowned); buffers are in-memory and cleared when the last handler for the topic unsubscribes. Wildcard subscriptions replay across every buffered topic matching the pattern.
+- Replay (opt-in): construct the bus with `replay: { maxPerTopic }` and pass `{ replay: true | n }` as the third `subscribe()` argument. `maxPerTopic` must be a positive safe integer. The new handler immediately receives the buffered history (up to `n`, capped by `maxPerTopic`, default 100) with `message.replayed: true`, so late joiners do not miss earlier publications. Only dispatched publications are buffered (a topic with no local subscriber drops them as unowned); buffers are in-memory and cleared when the last handler for the topic unsubscribes. Wildcard subscriptions replay across every buffered topic matching the pattern. For reload/BFCache persistence, pass an optional `persistence` created by `createIndexedDbReplayPersistence({ maxPerTopic })`; persistence is asynchronous and failures are reported through `onError` without breaking live delivery.
 
 ### `unsubscribe(topic, handler?)`
 

package/docs/roadmap.md

@@ -0,0 +1,18 @@
+# Roadmap
+
+0.4.0 is released. The next work is intentionally organized as 0.5.0 candidates so performance and persistence changes can land together with their compatibility notes.
+
+## 0.5.0 candidates
+
+1. **Publish-path profiling and optimization** — use both `pnpm bench` and `pnpm bench:browser`; optimize only after isolating storage batching, routing, and UI/server overhead separately.
+2. **Persistent replay history** — add an IndexedDB adapter for replay history across page reloads and BFCache sessions, with explicit retention and schema-version controls. Keep in-memory replay as the zero-dependency default.
+3. **Vue composables** — provide a Vue 3 adapter mirroring the React hooks lifecycle and subscription semantics without making Vue a core dependency.
+4. **End-to-end binary demo** — exercise real `ArrayBuffer` frames through the WebSocket demo path; keep the existing base64 JSON fallback for servers that only support JSON.
+5. **Push CI browser gate** — run the existing Playwright suite on pushes when a Chrome environment is available; keep local/manual execution as the fallback for contributors.
+
+## Release checklist
+
+- Update the `[Unreleased]` section and version date.
+- Run `pnpm check`, `pnpm lint`, `pnpm test:e2e`, `pnpm bench`, and `pnpm bench:browser`.
+- Run ESM/CJS package-consumption smoke tests from the packed tarball.
+- Tag the release and verify the GitHub Release and npm `latest` dist-tag.

package/docs/zh/README.md

@@ -12,6 +12,7 @@
 | [API 参考](./api.md) | 公共入口、类型、方法、返回值和行为 |
 | [架构说明](./architecture.md) | Worker 集群、路由、存储、迁移和降级设计 |
 | [能力矩阵](./capabilities.md) | 已实现、未实现和计划待实现的能力矩阵 |
+| [路线图](./roadmap.md) | 面向版本的优先级与验证清单 |
 | [../..//examples/demo](../../examples/demo) | 可运行的多标签浏览器演示 |
 | [../../CHANGELOG.md](../../CHANGELOG.md) | 版本变更记录 |
 
@@ -21,4 +22,4 @@
 2. 生产配置阅读 [配置说明](./configuration.md)。
 3. 开发封装或自定义 transport 时阅读 [API 参考](./api.md)。
 4. 排查跨 Tab 行为时阅读 [架构说明](./architecture.md)。
-5. 评估当前边界和后续计划时阅读 [能力矩阵](./capabilities.md)。
+5. 评估当前边界和后续计划时阅读 [能力矩阵](./capabilities.md)。

package/docs/zh/api.md

@@ -80,7 +80,7 @@ subscribe(
 - 最后一个 handler 释放后，当前 Tab 才退出该 Topic。
 - transport 尚未 ready 时订阅自动排队。
 - 通配符订阅：以 `.*` 结尾的 Topic（如 `chat.*`）匹配任意后缀，`*` 匹配全部。pattern 以字面量参与路由、归属与传输订阅；携带匹配的具体 topic（或 pattern 本身）的发布都会投递给通配 handler。匹配规则见下方 `topicMatchesPattern`。
-- 重放（可选）：构造 bus 时传 `replay: { maxPerTopic }` 开启缓冲，`maxPerTopic` 必须是正安全整数；`subscribe()` 第三个参数传 `{ replay: true | n }` 后，新 handler 会立即收到缓冲历史（最多 `n` 条，受 `maxPerTopic` 上限约束，默认 100），消息带 `message.replayed: true` 标记——晚加入的 handler 不会错过更早的发布。只有被分发过的消息才入缓冲（无本地订阅者的 topic 会被 owner 丢弃）；缓冲仅存内存，该 topic 最后一个 handler 退订时清空。通配订阅会对所有匹配 pattern 的已缓冲 topic 做回放。
+- 重放（可选）：构造 bus 时传 `replay: { maxPerTopic }` 开启缓冲，`maxPerTopic` 必须是正安全整数；`subscribe()` 第三个参数传 `{ replay: true | n }` 后，新 handler 会立即收到缓冲历史（最多 `n` 条，受 `maxPerTopic` 上限约束，默认 100），消息带 `message.replayed: true` 标记——晚加入的 handler 不会错过更早的发布。只有被分发过的消息才入缓冲（无本地订阅者的 topic 会被 owner 丢弃）；缓冲仅存内存，该 topic 最后一个 handler 退订时清空。通配订阅会对所有匹配 pattern 的已缓冲 topic 做回放。需要跨 reload/BFCache 持久化时，可传入 `createIndexedDbReplayPersistence({ maxPerTopic })` 创建的 `persistence`；持久化为异步操作，失败会通过 `onError` 报告，不影响实时投递。
 
 ### `unsubscribe(topic, handler?)`
 

package/docs/zh/roadmap.md

@@ -0,0 +1,18 @@
+# 路线图
+
+0.4.0 已发布。下一阶段统一按 0.5.0 候选推进，让性能、持久化和兼容性说明一起落地。
+
+## 0.5.0 候选
+
+1. **publish 路径 profile 与优化**：结合 `pnpm bench` 和 `pnpm bench:browser`，先拆分 storage batching、路由和页面/服务端开销，再决定是否优化；
+2. **重放持久化**：增加 IndexedDB 历史适配器，支持 reload 与 BFCache 会话间恢复；保留纯内存重放作为零依赖默认；
+3. **Vue composable**：复制 React hooks 的生命周期与订阅语义，Vue 仍保持可选依赖；
+4. **二进制 demo 真链路**：让 WebSocket demo 端到端覆盖真实 `ArrayBuffer` 帧，同时保留仅支持 JSON 服务端的 base64 fallback；
+5. **Push CI 浏览器门禁**：环境提供 Chrome 时在 push 上运行 Playwright，贡献者本地仍可手动执行。
+
+## 发版检查清单
+
+- 更新 `[Unreleased]` 与版本日期；
+- 执行 `pnpm check`、`pnpm lint`、`pnpm test:e2e`、`pnpm bench`、`pnpm bench:browser`；
+- 从打包 tarball 做 ESM/CJS 消费冒烟验证；
+- 推送 tag 后核验 GitHub Release 与 npm `latest` dist-tag。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cross-tab-worker-databus",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Framework-agnostic cross-tab data bus with Dedicated/Shared Worker clustering and Centrifuge support.",
   "type": "module",
   "license": "MIT",
@@ -71,6 +71,7 @@
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
     "bench": "vitest bench --run",
+    "bench:browser": "pnpm build && node scripts/bench-browser.mjs",
     "test:e2e": "pnpm build && playwright test",
     "typecheck": "tsc --noEmit",
     "prepublishOnly": "pnpm check"