cross-tab-worker-databus 0.1.2 → 0.2.1

package/docs/transports.md

@@ -0,0 +1,145 @@
+# Transport Backends
+
+> [中文](./zh/transports.md) | English
+
+The core package (`cross-tab-worker-databus`) is transport-agnostic. It defines a
+`DataBusTransport` contract; the built-in Centrifuge backend is one implementation
+of that contract, exposed as the optional `./centrifuge` subpath. This document
+describes the contract and how to wire up a third-party backend (native WebSocket,
+socket.io, SSE, etc.).
+
+## The `DataBusTransport` contract
+
+Every backend implements five methods. `subscribe` / `unsubscribe` MUST be
+idempotent — the DataBus may call them repeatedly and replays them on reconnect.
+
+```ts
+interface DataBusTransport<TConfig = unknown, TData = unknown> {
+  start(config: TConfig, handlers: DataBusTransportHandlers<TData>): MaybePromise<void>;
+  subscribe(topic: string): MaybePromise<void>;
+  unsubscribe(topic: string): MaybePromise<void>;
+  publish(topic: string, data: unknown): MaybePromise<void>;
+  stop(): MaybePromise<void>;
+}
+
+interface DataBusTransportHandlers<TData = unknown> {
+  onMessage: (message: DataBusMessage<TData>) => void;
+  onStatus: (status: WorkerStatus) => void;   // 'connecting' | 'connected' | 'disconnected' | 'error'
+  onError: (error: unknown) => void;
+}
+```
+
+`start()` receives the user-supplied connection config (untyped `TConfig` — the
+backend owns its shape) and the three callbacks. Call `onStatus` whenever the
+connection state changes; call `onMessage` for each inbound publication; call
+`onError` for non-fatal errors (the DataBus applies a recovery cooldown so a
+flapping connection does not retry-loop).
+
+## Architectural layers
+
+```
+CrossTabDataBus  ──►  DataBusTransport (your backend)
+                          │
+                  ┌───────┴────────┐
+                  │ Worker protocol │   (your backend's main-thread ↔ worker messages)
+                  └───────┬────────┘
+                          │
+                     Session layer   (the actual client: WebSocket / centrifuge / …)
+                          │
+                        Server
+```
+
+The DataBus layer handles cross-tab coordination (BroadcastChannel control
+plane, localStorage routes, owner selection, failover, page lifecycle). Your
+transport only owns the I/O path: connect, subscribe, publish, disconnect.
+
+## Implementing a backend
+
+### 1. Define your Worker protocol
+
+Mirror the Centrifuge backend's `centrifuge-protocol.ts`: a discriminated union
+of messages the main thread sends to the Worker (`INIT` / `SUBSCRIBE` /
+`UNSUBSCRIBE` / `PUBLISH` / `PUBLISH_BIN` / `PING` / `STOP`) and a union the
+Worker posts back (`STATUS` / `MESSAGE` / `MESSAGE_BIN` / `ERROR`). Keep it
+structured-cloneable (no functions,
+no class instances — `Error` must be serialised).
+
+### 2. Implement the session
+
+A session class owns one connection and lives inside the Worker (or, as a
+fallback, on the main thread). It receives protocol messages via a `handle()`
+method and posts outputs back through a sink. See
+[`centrifuge-session.ts`](../src/centrifuge-session.ts) for the reference shape:
+
+- `handle(message)` dispatches by `message.type`.
+- `subscribe(topic)` is idempotent — re-subscribing an existing topic is a no-op.
+- `unsubscribe(topic)` removes listeners before disconnecting, to avoid a late
+  event resurrecting a re-subscribed topic.
+- `stop()` disconnects, clears all subscriptions, and emits `disconnected`.
+
+### 3. Implement the transport
+
+The transport selects a backend (SharedWorker / Dedicated Worker / local),
+posts protocol messages to it, and routes Worker outputs back to the
+`DataBusTransportHandlers`. See [`centrifuge.ts`](../src/centrifuge.ts) for the
+reference shape, including:
+
+- **Backend selection**: reuse `selectWorkerBackend` from `worker-mode.ts` so
+  your backend degrades consistently with the rest of the SDK.
+- **Generation guard**: bump a monotonic counter when a backend is created;
+  error handlers check it so late errors from a superseded Worker cannot
+  corrupt the fresh session.
+- **SharedWorker heartbeat**: if you use a SharedWorker, send periodic PINGs
+  so a `PortReaper` can reclaim dead-tab sessions.
+
+### 4. Expose as a subpath
+
+Add `exports` entries in `package.json` (one per entry point — the main bundle,
+the dedicated worker, the shared worker):
+
+```json
+{
+  "exports": {
+    "./your-backend": {
+      "types": "./dist/your-backend.d.ts",
+      "import": "./dist/your-backend.js"
+    },
+    "./your-backend.worker": "./dist/your-backend.worker.js",
+    "./your-backend.shared.worker": "./dist/your-backend.shared.worker.js"
+  }
+}
+```
+
+This keeps the core package zero-dependency: users who do not import
+`./your-backend` never pull your client library into their bundle.
+
+### 5. Register the peer dependency
+
+Declare your client library as an optional peer dependency so consumers
+opt in:
+
+```json
+{
+  "peerDependencies": { "your-client-lib": "^x.y.z" },
+  "peerDependenciesMeta": { "your-client-lib": { "optional": true } }
+}
+```
+
+## Factory entry point
+
+Provide a `create<Backend>DataBus(options)` factory that wires the transport
+into a `CrossTabDataBus`, mirroring `createCentrifugeDataBus`. This is the
+surface most consumers use; it should accept the connection config, cluster
+key (defaulting to the connection URL), and forward trace / worker-mode
+options to the DataBus.
+
+## What the transport does NOT own
+
+- **Cross-tab routing**: the `WorkerClusterRuntime` decides which tab owns a
+  topic. Your transport just subscribes when told.
+- **Reconnect replay**: the DataBus replays the current owner's topics on
+  reconnect; your transport's `subscribe` must be safe to call again.
+- **Publication fan-out**: the owner broadcasts publications over
+  BroadcastChannel; your transport only receives and reports them.
+- **Page lifecycle**: the DataBus suspends/resumes the transport on
+  `pagehide` / `pageshow`; your transport's `stop()` must be clean.

package/docs/zh/README.md

@@ -8,6 +8,7 @@
 |---|---|
 | [快速接入](./getting-started.md) | 安装、创建实例、订阅、发布和销毁 |
 | [配置说明](./configuration.md) | 核心配置、Centrifuge 配置、默认值和约束 |
+| [Transport 后端](./transports.md) | `DataBusTransport` 契约、Worker 协议与第三方后端接入指南 |
 | [API 参考](./api.md) | 公共入口、类型、方法、返回值和行为 |
 | [架构说明](./architecture.md) | Worker 集群、路由、存储、迁移和降级设计 |
 | [能力矩阵](./capabilities.md) | 已实现、未实现和计划待实现的能力矩阵 |

package/docs/zh/architecture.md

@@ -10,23 +10,33 @@ graph TB
     subgraph TabA["Tab A"]
       AppA["业务模块"] --> BusA["CrossTabDataBus"]
       BusA --> RuntimeA["WorkerClusterRuntime"]
-      BusA --> WorkerA["Dedicated / Shared Worker A"]
+      BusA --> TransportA["CentrifugeWorkerTransport"]
+      TransportA --> WorkerA["Dedicated / Shared Worker A"]
     end
     subgraph TabB["Tab B"]
       AppB["业务模块"] --> BusB["CrossTabDataBus"]
       BusB --> RuntimeB["WorkerClusterRuntime"]
-      BusB --> WorkerB["Dedicated / Shared Worker B"]
+      BusB --> TransportB["CentrifugeWorkerTransport"]
+      TransportB --> WorkerB["Dedicated / Shared Worker B"]
     end
   end
 
   RuntimeA <--> Channel["BroadcastChannel 控制面"]
   RuntimeB <--> Channel
-  RuntimeA <--> Registry["localStorage Worker 注册表"]
-  RuntimeB <--> Registry
-  RuntimeA <--> Routes["localStorage Topic 路由表"]
-  RuntimeB <--> Routes
-  WorkerA --> Server["Centrifuge / 实时服务器"]
-  WorkerB --> Server
+  RuntimeA --> BatchA["BatchingStorageWriter"]
+  RuntimeB --> BatchB["BatchingStorageWriter"]
+  BatchA <--> Registry["localStorage Worker 注册表"]
+  BatchB <--> Registry
+  BatchA <--> Routes["localStorage Topic 路由表"]
+  BatchB <--> Routes
+  WorkerA --> SessionA["CentrifugeSession"]
+  WorkerB --> SessionB["CentrifugeSession"]
+  SessionA --> Server["Centrifuge / 实时服务器"]
+  SessionB --> Server
+  subgraph SW["SharedWorker 进程（backend = shared 时）"]
+    Reaper["PortReaper"] -.-> SessionA
+    Reaper -.-> SessionB
+  end
 ```
 
 默认 `workerMode: 'dedicated'` 时，每个 Tab 使用独立的 transport Worker。配置为 `shared` 或 `auto` 且浏览器支持 SharedWorker 时，同源 Tab 复用同一个 SharedWorker；SharedWorker 内每个连接 port 各自维护独立的 `CentrifugeSession`，一个 Tab 刷新或停止不会影响其他 Tab。`auto` 模式按 **SharedWorker → Dedicated Worker → 主线程 WebSocket** 降级，`dedicated` 模式按 **Dedicated Worker → SharedWorker → 主线程 WebSocket** 降级。`BroadcastChannel` 只负责控制消息和实时 publication 转发；localStorage 只负责最终一致的协调元数据。

package/docs/zh/getting-started.md

@@ -12,8 +12,11 @@ pnpm add cross-tab-worker-databus
 
 - `cross-tab-worker-databus`：核心 DataBus 和 transport 接口
 - `cross-tab-worker-databus/centrifuge`：内置 Centrifuge Worker transport
+- `cross-tab-worker-databus/centrifuge.worker`：Dedicated Worker 构建产物，默认由内置 factory 加载，通常无需直接引用
 - `cross-tab-worker-databus/centrifuge.shared.worker`：SharedWorker 构建产物，默认由内置 factory 加载，通常无需直接引用
 
+`cross-tab-worker-databus/centrifuge` 入口依赖可选 peer dependency `centrifuge`（^5.5.3）。使用内置 Centrifuge transport 时请一并安装：`pnpm add centrifuge`。
+
 ## 2. 创建实例
 
 建议在应用基础设施层创建一个实例，其他模块直接导入。这样同一 Tab 内的业务模块会共享 Worker、连接和 Topic 引用。

package/docs/zh/transports.md

@@ -0,0 +1,133 @@
+# Transport 后端
+
+> 中文 | [English](../transports.md)
+
+核心包（`cross-tab-worker-databus`）与 transport 无关。它定义了一个
+`DataBusTransport` 契约；内置的 Centrifuge 后端是该契约的一个实现，作为可选的
+`./centrifuge` subpath 暴露。本文档描述该契约以及如何接入第三方后端（原生
+WebSocket、socket.io、SSE 等）。
+
+## `DataBusTransport` 契约
+
+每个后端实现 5 个方法。`subscribe` / `unsubscribe` 必须幂等——DataBus 可能重复
+调用，并在重连时回放。
+
+```ts
+interface DataBusTransport<TConfig = unknown, TData = unknown> {
+  start(config: TConfig, handlers: DataBusTransportHandlers<TData>): MaybePromise<void>;
+  subscribe(topic: string): MaybePromise<void>;
+  unsubscribe(topic: string): MaybePromise<void>;
+  publish(topic: string, data: unknown): MaybePromise<void>;
+  stop(): MaybePromise<void>;
+}
+
+interface DataBusTransportHandlers<TData = unknown> {
+  onMessage: (message: DataBusMessage<TData>) => void;
+  onStatus: (status: WorkerStatus) => void;   // 'connecting' | 'connected' | 'disconnected' | 'error'
+  onError: (error: unknown) => void;
+}
+```
+
+`start()` 接收用户提供的连接配置（无类型 `TConfig`——后端自行定义其形状）和
+三个回调。连接状态变化时调 `onStatus`；收到 publication 时调 `onMessage`；
+非致命错误调 `onError`（DataBus 有恢复冷却窗口，避免抖动连接死循环重试）。
+
+## 架构分层
+
+```
+CrossTabDataBus  ──►  DataBusTransport（你的后端）
+                          │
+                  ┌───────┴────────┐
+                  │ Worker 协议     │   （你的后端的主线程 ↔ worker 消息）
+                  └───────┬────────┘
+                          │
+                     Session 层    （真正的客户端：WebSocket / centrifuge / …）
+                          │
+                        服务端
+```
+
+DataBus 层负责跨 Tab 协调（BroadcastChannel 控制面、localStorage 路由、owner 选举、
+故障转移、页面生命周期）。你的 transport 只负责 I/O 路径：连接、订阅、发布、断开。
+
+## 实现一个后端
+
+### 1. 定义你的 Worker 协议
+
+参照 Centrifuge 后端的 `centrifuge-protocol.ts`：一个主线程发给 Worker 的
+判别联合（`INIT` / `SUBSCRIBE` / `UNSUBSCRIBE` / `PUBLISH` / `PUBLISH_BIN` /
+`PING` / `STOP`）和一个 Worker 回传的联合（`STATUS` / `MESSAGE` / `MESSAGE_BIN` /
+`ERROR`）。保持结构化克隆安全
+（无函数、无类实例——`Error` 必须序列化）。
+
+### 2. 实现 session
+
+一个 session 类持有一个连接，运行在 Worker 内（或作为降级运行在主线程）。
+它通过 `handle()` 方法接收协议消息，通过 sink 回传输出。参见
+[`centrifuge-session.ts`](../../src/centrifuge-session.ts) 的参考形状：
+
+- `handle(message)` 按 `message.type` 分派。
+- `subscribe(topic)` 幂等——对已存在 topic 重复订阅是 no-op。
+- `unsubscribe(topic)` 先移除监听器再断开，避免迟到事件复活已重订阅的 topic。
+- `stop()` 断开、清理所有订阅、emit `disconnected`。
+
+### 3. 实现 transport
+
+transport 选择后端（SharedWorker / Dedicated Worker / 本地），向它发送协议
+消息，并把 Worker 输出路由回 `DataBusTransportHandlers`。参见
+[`centrifuge.ts`](../../src/centrifuge.ts) 的参考形状，包括：
+
+- **后端选举**：复用 `worker-mode.ts` 的 `selectWorkerBackend`，使你的后端与
+  SDK 其余部分降级行为一致。
+- **generation 守卫**：创建后端时递增单调计数器；错误处理检查它，使被取代的
+  Worker 的迟到错误不会污染新 session。
+- **SharedWorker 心跳**：若用 SharedWorker，定期发 PING，让 `PortReaper` 能
+  回收死 tab 的 session。
+
+### 4. 作为 subpath 暴露
+
+在 `package.json` 加 `exports` 条目（每个入口一个——主 bundle、dedicated worker、
+shared worker）：
+
+```json
+{
+  "exports": {
+    "./your-backend": {
+      "types": "./dist/your-backend.d.ts",
+      "import": "./dist/your-backend.js"
+    },
+    "./your-backend.worker": "./dist/your-backend.worker.js",
+    "./your-backend.shared.worker": "./dist/your-backend.shared.worker.js"
+  }
+}
+```
+
+这保持核心包零依赖：不导入 `./your-backend` 的用户不会把你的客户端库打进 bundle。
+
+### 5. 声明 peer 依赖
+
+将你的客户端库声明为可选 peer 依赖，让消费者自行选择：
+
+```json
+{
+  "peerDependencies": { "your-client-lib": "^x.y.z" },
+  "peerDependenciesMeta": { "your-client-lib": { "optional": true } }
+}
+```
+
+## 工厂入口
+
+提供一个 `create<Backend>DataBus(options)` 工厂，把 transport 接入
+`CrossTabDataBus`，与 `createCentrifugeDataBus` 对称。这是大多数消费者使用的
+界面；它应接受连接配置、cluster key（默认为连接 URL），并把 trace /
+worker-mode 选项转发给 DataBus。
+
+## transport 不负责的事
+
+- **跨 Tab 路由**：`WorkerClusterRuntime` 决定哪个 tab 拥有 topic。你的 transport
+  只在被通知时订阅。
+- **重连回放**：DataBus 在重连时回放当前 owner 的 topic；你的 transport 的
+  `subscribe` 必须可安全重复调用。
+- **publication 扇出**：owner 通过 BroadcastChannel 广播 publication；你的
+  transport 只接收并上报。
+- **页面生命周期**：DataBus 在 `pagehide` / `pageshow` 时挂起/恢复 transport；
+  你的 transport 的 `stop()` 必须干净。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cross-tab-worker-databus",
-  "version": "0.1.2",
+  "version": "0.2.1",
   "description": "Framework-agnostic cross-tab data bus with Dedicated/Shared Worker clustering and Centrifuge support.",
   "type": "module",
   "license": "MIT",
@@ -41,31 +41,54 @@
       "types": "./dist/centrifuge.d.ts",
       "import": "./dist/centrifuge.js"
     },
-    "./centrifuge.worker": "./dist/centrifuge.worker.js",
-    "./centrifuge.shared.worker": "./dist/centrifuge.shared.worker.js",
+    "./centrifuge.worker": {
+      "types": "./dist/workers/centrifuge.worker.d.ts",
+      "default": "./dist/centrifuge.worker.js"
+    },
+    "./centrifuge.shared.worker": {
+      "types": "./dist/workers/centrifuge.shared.worker.d.ts",
+      "default": "./dist/centrifuge.shared.worker.js"
+    },
     "./package.json": "./package.json"
   },
+  "sideEffects": [
+    "./dist/centrifuge.worker.js",
+    "./dist/centrifuge.shared.worker.js"
+  ],
   "scripts": {
     "build": "node scripts/build.mjs",
     "check": "pnpm typecheck && pnpm test && pnpm build",
     "examples": "node scripts/serve-examples.mjs",
+    "lint": "eslint .",
     "test": "vitest run",
     "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
     "test:e2e": "pnpm build && playwright test",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "pnpm check"
   },
-  "dependencies": {
+  "peerDependencies": {
     "centrifuge": "^5.5.3"
   },
+  "peerDependenciesMeta": {
+    "centrifuge": {
+      "optional": true
+    }
+  },
   "devDependencies": {
+    "@eslint/js": "^9.39.5",
     "@playwright/test": "^1.62.1",
     "@types/node": "^24.0.0",
+    "@vitest/coverage-v8": "^3.2.7",
     "esbuild": "^0.25.0",
+    "eslint": "^9.39.4",
+    "globals": "^17.11.0",
     "typescript": "^5.9.0",
+    "typescript-eslint": "^8.68.0",
     "vitest": "^3.2.0"
   },
   "engines": {
     "node": ">=18.0.0"
   },
   "packageManager": "pnpm@10.14.0"
-}
+}