cross-tab-worker-databus 0.3.0 → 0.5.0

package/dist/cjs/index.cjs

@@ -25,6 +25,7 @@ __export(src_exports, {
   WebSocketTransport: () => WebSocketTransport,
   WorkerClusterRuntime: () => WorkerClusterRuntime,
   createBrowserEnvironment: () => createBrowserEnvironment,
+  createIndexedDbReplayPersistence: () => createIndexedDbReplayPersistence,
   createOpaqueKey: () => createOpaqueKey,
   createWebSocketDataBus: () => createWebSocketDataBus,
   getOrCreateTabId: () => getOrCreateTabId,
@@ -1210,6 +1211,7 @@ function roundMs(value) {
 
 // src/core/data-bus.ts
 var PUBLICATION_EVENT = "DATABUS_PUBLICATION";
+var DEFAULT_REPLAY_MAX_PER_TOPIC = 100;
 var CrossTabDataBus = class _CrossTabDataBus {
   transport;
   cluster;
@@ -1220,6 +1222,12 @@ var CrossTabDataBus = class _CrossTabDataBus {
   transportSubscribedTopics = /* @__PURE__ */ new Set();
   statusHandlers = /* @__PURE__ */ new Set();
   errorHandlers = /* @__PURE__ */ new Set();
+  // Bounded per-topic ring of recent dispatched publications. Null unless
+  // replay is enabled — buffering is opt-in and must cost nothing otherwise.
+  replayBuffers;
+  replayMaxPerTopic;
+  replayPersistence;
+  replayHydration;
   initialConfig;
   hasInitialConfig;
   trace;
@@ -1248,6 +1256,19 @@ var CrossTabDataBus = class _CrossTabDataBus {
   // Minimum interval in ms between automatic recovery attempts.
   static RECOVERY_COOLDOWN_MS = 1e3;
   constructor(options) {
+    const replay = options.replay;
+    if (replay) {
+      const maxPerTopic = replay.maxPerTopic ?? DEFAULT_REPLAY_MAX_PER_TOPIC;
+      if (!Number.isSafeInteger(maxPerTopic) || maxPerTopic <= 0) {
+        throw new TypeError(
+          `replay.maxPerTopic must be a positive safe integer, got ${String(maxPerTopic)}.`
+        );
+      }
+    }
+    this.replayMaxPerTopic = replay?.maxPerTopic ?? DEFAULT_REPLAY_MAX_PER_TOPIC;
+    this.replayBuffers = replay ? /* @__PURE__ */ new Map() : null;
+    this.replayPersistence = replay?.persistence ?? null;
+    this.replayHydration = this.hydrateReplay();
     const { autoStart, initialConfig, trace, transport, ...clusterOptions } = options;
     this.transport = transport;
     this.initialConfig = initialConfig;
@@ -1404,13 +1425,26 @@ var CrossTabDataBus = class _CrossTabDataBus {
    * delivered to this tab, regardless of which tab published it. Returns an
    * unsubscribe function for convenience.
    */
-  subscribe(topic, handler) {
+  subscribe(topic, handler, options) {
     this.ensureStarted();
     const handlers = this.topicHandlers.get(topic) ?? /* @__PURE__ */ new Set();
     const wasUnused = handlers.size === 0;
     handlers.add(handler);
     this.topicHandlers.set(topic, handlers);
     if (wasUnused) this.cluster.subscribe(topic);
+    if (options?.replay) {
+      const limit = Math.min(
+        typeof options.replay === "number" ? Math.floor(options.replay) : this.replayMaxPerTopic,
+        this.replayMaxPerTopic
+      );
+      if (this.replayPersistence) {
+        void this.replayHydration.then(() => {
+          if (this.topicHandlers.get(topic)?.has(handler)) this.deliverReplay(topic, limit, handler);
+        });
+      } else {
+        this.deliverReplay(topic, limit, handler);
+      }
+    }
     return () => this.unsubscribe(topic, handler);
   }
   /** Remove a specific handler, or all handlers for `topic`.
@@ -1424,6 +1458,7 @@ var CrossTabDataBus = class _CrossTabDataBus {
     else handlers.clear();
     if (handlers.size > 0) return;
     this.topicHandlers.delete(topic);
+    this.replayBuffers?.delete(topic);
     this.cluster.unsubscribe(topic);
   }
   /** Publish a message to `topic`. The owning Worker delivers it to the transport. */
@@ -1470,6 +1505,7 @@ var CrossTabDataBus = class _CrossTabDataBus {
     this.trace.event({ type: "lifecycle", action: "stop" });
     this.trace.stop();
     this.topicHandlers.clear();
+    this.replayBuffers?.clear();
     this.cluster.stop();
     try {
       await this.startPromise?.catch(() => void 0);
@@ -1518,6 +1554,61 @@ var CrossTabDataBus = class _CrossTabDataBus {
         this.invokeHandlers(handlers, (handler) => handler(message));
       }
     }
+    this.recordReplay(message);
+  }
+  /** Append a dispatched publication to the topic's replay ring buffer.
+   * No-op when replay is disabled. */
+  recordReplay(message) {
+    if (!this.replayBuffers) return;
+    let buffer = this.replayBuffers.get(message.topic);
+    if (!buffer) {
+      buffer = [];
+      this.replayBuffers.set(message.topic, buffer);
+    }
+    buffer.push(message);
+    if (buffer.length > this.replayMaxPerTopic) buffer.shift();
+    if (this.replayPersistence) {
+      void this.replayPersistence.append(message).catch((error) => this.reportError(error));
+    }
+  }
+  async hydrateReplay() {
+    if (!this.replayBuffers || !this.replayPersistence) {
+      return;
+    }
+    try {
+      for (const message of await this.replayPersistence.load()) {
+        let buffer = this.replayBuffers.get(message.topic);
+        if (!buffer) {
+          buffer = [];
+          this.replayBuffers.set(message.topic, buffer);
+        }
+        buffer.push(message);
+        if (buffer.length > this.replayMaxPerTopic) buffer.shift();
+      }
+    } catch (error) {
+      this.reportError(error);
+    }
+  }
+  /** 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
+   * order). Replay deliveries are marked `replayed: true` and are not
+   * counted into trace metrics. */
+  deliverReplay(topic, limit, handler) {
+    if (!this.replayBuffers || limit <= 0) return;
+    const deliver = (buffer2) => {
+      for (const message of buffer2.slice(-limit)) {
+        this.invokeHandlers([handler], (h) => h({ ...message, replayed: true }));
+      }
+    };
+    if (isWildcardTopic(topic)) {
+      for (const [bufferedTopic, buffer2] of this.replayBuffers) {
+        if (topicMatchesPattern(topic, bufferedTopic)) deliver(buffer2);
+      }
+      return;
+    }
+    const buffer = this.replayBuffers.get(topic);
+    if (buffer) deliver(buffer);
   }
   /**
    * Propagate a status change to the cluster, trace, and all registered
@@ -1691,6 +1782,54 @@ function formatRouteTrace(route) {
   return `${route.topicKey}@${route.workerId}|confirmed=${route.confirmedAt !== void 0}`;
 }
 
+// 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 {