cross-tab-worker-databus 0.3.0 → 0.4.0

package/dist/cjs/index.cjs

@@ -1210,6 +1210,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 +1221,10 @@ 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;
   initialConfig;
   hasInitialConfig;
   trace;
@@ -1248,6 +1253,17 @@ 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;
     const { autoStart, initialConfig, trace, transport, ...clusterOptions } = options;
     this.transport = transport;
     this.initialConfig = initialConfig;
@@ -1404,13 +1420,20 @@ 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
+      );
+      this.deliverReplay(topic, limit, handler);
+    }
     return () => this.unsubscribe(topic, handler);
   }
   /** Remove a specific handler, or all handlers for `topic`.
@@ -1424,6 +1447,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 +1494,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 +1543,40 @@ 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();
+  }
+  /** 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