cross-tab-worker-databus 0.3.0 → 0.5.0

package/dist/cjs/centrifuge.cjs

@@ -160,6 +160,9 @@ function selectActiveWorkers(workers, maxActiveWorkers = DEFAULT_MAX_ACTIVE_WORK
     (left, right) => left.registeredAt - right.registeredAt || (left.workerId < right.workerId ? -1 : left.workerId > right.workerId ? 1 : 0)
   ).slice(0, maxActiveWorkers);
 }
+function isWildcardTopic(pattern) {
+  return pattern === "*" || pattern.endsWith(".*");
+}
 function topicMatchesPattern(pattern, topic) {
   if (!pattern || !topic) return false;
   if (pattern === topic) return true;
@@ -1183,6 +1186,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;
@@ -1193,6 +1197,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;
@@ -1221,6 +1231,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;
@@ -1377,13 +1400,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`.
@@ -1397,6 +1433,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. */
@@ -1443,6 +1480,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);
@@ -1491,6 +1529,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
@@ -2081,7 +2174,15 @@ function createDefaultWorker() {
   if (typeof Worker === "undefined") {
     throw new Error("CentrifugeWorkerTransport requires a browser Worker implementation.");
   }
-  return new Worker(new URL("./centrifuge.worker.js", import_meta.url), {
+  let workerUrl;
+  try {
+    workerUrl = new URL("./centrifuge.worker.js", import_meta.url);
+  } catch {
+    throw new Error(
+      "The default Centrifuge Worker URL is unavailable in this module format; provide workerFactory explicitly."
+    );
+  }
+  return new Worker(workerUrl, {
     name: "cross-tab-worker-databus",
     type: "module"
   });
@@ -2090,7 +2191,15 @@ function createDefaultSharedWorker() {
   if (typeof SharedWorker === "undefined") {
     throw new Error("CentrifugeWorkerTransport requires a browser SharedWorker implementation.");
   }
-  return new SharedWorker(new URL("./centrifuge.shared.worker.js", import_meta.url), {
+  let workerUrl;
+  try {
+    workerUrl = new URL("./centrifuge.shared.worker.js", import_meta.url);
+  } catch {
+    throw new Error(
+      "The default Centrifuge SharedWorker URL is unavailable in this module format; provide sharedWorkerFactory explicitly."
+    );
+  }
+  return new SharedWorker(workerUrl, {
     name: "cross-tab-worker-databus-shared",
     type: "module"
   });