cross-tab-worker-databus 0.10.0 → 0.11.0

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 本项目遵循 [Semantic Versioning](https://semver.org/)；变更记录格式参考 [Keep a Changelog](https://keepachangelog.com/)。
 
+## [0.11.0] - 2026-09-01
+
+### Added
+
+- Automatic durable replay retention via `replay.retentionMs` when a persistence adapter supports `clearBefore`.
+- Deduplication accepted/suppressed counters in periodic `message_metrics` trace snapshots.
+- Service Worker runtime boundary documented as intentionally deferred pending stable browser lifetime semantics.
+
+### Compatibility
+
+- Existing replay adapters remain valid; `retentionMs` is ignored when an adapter does not implement `clearBefore`.
+- Existing trace consumers can continue reading the original metrics fields; dedup counters are additive.
+
 ## [0.10.0] - 2026-09-01
 
 ### Added

package/README.md

@@ -22,6 +22,7 @@ By default each tab holds its own Dedicated Worker; when configured with `worker
 - New Topics are assigned to the least-loaded eligible Worker
 - Wildcard subscriptions: `chat.*` and `*` patterns match concrete topics at dispatch
 - Transport-neutral publication metadata (`messageId`, `timestamp`) with canonical WebSocket/Centrifuge envelopes and legacy frame compatibility
+- Optional durable replay retention (`replay.retentionMs`) and deduplication outcome metrics in trace snapshots
 - Built-in zero-dependency native WebSocket transport (`createWebSocketDataBus`) for plain-WebSocket servers
 - Optional React hooks adapter (`cross-tab-worker-databus/hooks`): StrictMode-safe bus lifecycle, auto-cleanup subscriptions
 - Optional Vue 3 composables adapter (`cross-tab-worker-databus/vue`): lifecycle-safe bus, subscription, and status composables

package/README.zh.md

@@ -22,6 +22,7 @@
 - 新 Topic 分配给负载最低的候选 Worker
 - 通配符订阅：`chat.*` 与 `*` pattern 在分发侧匹配具体 Topic
 - 传输无关的 publication 元数据（`messageId`、`timestamp`），支持标准 WebSocket/Centrifuge envelope，并兼容旧帧格式
+- 可选的 durable replay retention（`replay.retentionMs`），以及 trace snapshot 中的去重结果指标
 - 内置零依赖的原生 WebSocket 传输（`createWebSocketDataBus`），适配普通 WebSocket 服务器
 - 可选的 React hooks 适配层（`cross-tab-worker-databus/hooks`）：StrictMode 安全的 bus 生命周期与自动清理订阅
 - 可选的 Vue 3 composables 适配层（`cross-tab-worker-databus/vue`）：安全管理 bus 生命周期、订阅和状态

package/dist/centrifuge.js

@@ -2,7 +2,7 @@ import {
   CrossTabDataBus,
   parseDataBusPublication,
   selectWorkerBackend
-} from "./chunk-ZOPNTR4E.js";
+} from "./chunk-NX76TAV3.js";
 
 // src/centrifuge-session.ts
 import { Centrifuge } from "centrifuge";

package/dist/{chunk-ZOPNTR4E.js → chunk-NX76TAV3.js}

@@ -1050,6 +1050,8 @@ var DataBusTraceReporter = class {
   // Bucketed histogram: bucket index = floor(delayMs / 50), capped at 19.
   latencyBuckets = new Array(LATENCY_BUCKET_COUNT).fill(0);
   latencySumMs = 0;
+  dedupAccepted = 0;
+  dedupSuppressed = 0;
   constructor(options, now = Date.now) {
     this.enabled = options?.enabled ?? false;
     this.mode = options?.mode ?? "all";
@@ -1125,6 +1127,13 @@ var DataBusTraceReporter = class {
     this.latencyBuckets[bucketIndex] = (this.latencyBuckets[bucketIndex] ?? 0) + 1;
     this.latencySumMs += delayMs;
   }
+  /** Record deduplication outcomes for the next metrics window. */
+  recordDedupAccepted() {
+    if (this.metricsActive) this.dedupAccepted += 1;
+  }
+  recordDedupSuppressed() {
+    if (this.metricsActive) this.dedupSuppressed += 1;
+  }
   /** True when metrics recording is active: enabled and mode includes metrics.
    * Extracted so the four record / flush methods share one guard expression
    * instead of repeating `!this.enabled || this.mode === 'events'` at each. */
@@ -1138,7 +1147,7 @@ var DataBusTraceReporter = class {
   }
   flushNow() {
     const timestamp = this.now();
-    if (this.received > 0 || this.dispatched > 0) {
+    if (this.received > 0 || this.dispatched > 0 || this.dedupAccepted > 0 || this.dedupSuppressed > 0) {
       const samples = this.latencySamples;
       this.emit({
         type: "message_metrics",
@@ -1152,6 +1161,8 @@ var DataBusTraceReporter = class {
         dispatchP50Ms: roundMs(percentileMs(this.latencyBuckets, samples, 0.5)),
         dispatchP95Ms: roundMs(percentileMs(this.latencyBuckets, samples, 0.95)),
         dispatchMaxMs: roundMs(percentileMs(this.latencyBuckets, samples, 1)),
+        dedupAccepted: this.dedupAccepted,
+        dedupSuppressed: this.dedupSuppressed,
         timestamp
       });
       this.resetMetrics();
@@ -1166,6 +1177,8 @@ var DataBusTraceReporter = class {
     this.receivedAt.clear();
     this.latencyBuckets.fill(0);
     this.latencySumMs = 0;
+    this.dedupAccepted = 0;
+    this.dedupSuppressed = 0;
   }
   emit(event) {
     try {
@@ -1216,6 +1229,7 @@ var CrossTabDataBus = class _CrossTabDataBus {
   replayBuffers;
   replayMaxPerTopic;
   replayPersistence;
+  replayRetentionMs;
   replayHydration;
   initialConfig;
   hasInitialConfig;
@@ -1263,6 +1277,10 @@ var CrossTabDataBus = class _CrossTabDataBus {
     this.replayMaxPerTopic = replay?.maxPerTopic ?? DEFAULT_REPLAY_MAX_PER_TOPIC;
     this.replayBuffers = replay ? /* @__PURE__ */ new Map() : null;
     this.replayPersistence = replay?.persistence ?? null;
+    this.replayRetentionMs = replay?.retentionMs;
+    if (this.replayRetentionMs !== void 0 && (!Number.isFinite(this.replayRetentionMs) || this.replayRetentionMs <= 0)) {
+      throw new TypeError("replay.retentionMs must be a positive finite number.");
+    }
     this.replayHydration = this.hydrateReplay();
     const { autoStart, initialConfig, trace, transport, dedup, ...clusterOptions } = options;
     this.transport = transport;
@@ -1622,10 +1640,12 @@ var CrossTabDataBus = class _CrossTabDataBus {
     if (this.seenMessageIds.has(message.messageId)) {
       this.trace.event({ type: "reliability", operation: "dedup_suppressed", topic: message.topic });
       this.dedupSuppressed += 1;
+      this.trace.recordDedupSuppressed();
       return true;
     }
     this.seenMessageIds.set(message.messageId, now);
     this.dedupAccepted += 1;
+    this.trace.recordDedupAccepted();
     while (this.seenMessageIds.size > this.dedupMaxEntries) {
       const oldest = this.seenMessageIds.keys().next().value;
       if (oldest === void 0) break;
@@ -1660,6 +1680,9 @@ var CrossTabDataBus = class _CrossTabDataBus {
     if (buffer.length > this.replayMaxPerTopic) buffer.shift();
     if (this.replayPersistence) {
       void this.replayPersistence.append(storedMessage).catch((error) => this.reportError(error));
+      if (this.replayRetentionMs !== void 0 && this.replayPersistence.clearBefore) {
+        void this.replayPersistence.clearBefore(Date.now() - this.replayRetentionMs).catch((error) => this.reportError(error));
+      }
     }
   }
   async hydrateReplay() {
@@ -1667,6 +1690,9 @@ var CrossTabDataBus = class _CrossTabDataBus {
       return;
     }
     try {
+      if (this.replayRetentionMs !== void 0 && this.replayPersistence.clearBefore) {
+        await this.replayPersistence.clearBefore(Date.now() - this.replayRetentionMs);
+      }
       for (const message of await this.replayPersistence.load()) {
         let buffer = this.replayBuffers.get(message.topic);
         if (!buffer) {
@@ -1920,4 +1946,4 @@ export {
   parseDataBusPublication,
   selectWorkerBackend
 };
-//# sourceMappingURL=chunk-ZOPNTR4E.js.map
+//# sourceMappingURL=chunk-NX76TAV3.js.map