cross-tab-worker-databus 0.2.1 → 0.4.0

package/docs/api.md

@@ -19,6 +19,17 @@ import {
   CentrifugeWorkerTransport,
   createCentrifugeDataBus
 } from 'cross-tab-worker-databus/centrifuge';
+
+import {
+  WebSocketTransport,
+  createWebSocketDataBus
+} from 'cross-tab-worker-databus';
+
+import {
+  useCrossTabDataBus,
+  useCrossTabStatus,
+  useCrossTabSubscription
+} from 'cross-tab-worker-databus/hooks';
 ```
 
 Business integration should prefer `CrossTabDataBus` or `createCentrifugeDataBus`. `WorkerClusterRuntime` is an advanced coordination API.
@@ -68,6 +79,8 @@ Registers a local subscription and returns a cleanup function.
 - The first handler in the current tab registers a cluster subscription.
 - The current tab only leaves the topic after the last handler is released.
 - Subscriptions are automatically queued when the transport is not yet ready.
+- Wildcard subscriptions: a topic ending in `.*` (`chat.*`) matches any remainder, and `*` matches everything. The pattern is routed, owned, and transport-subscribed as a literal channel; publications tagged with a matching concrete topic (or with the pattern itself) are delivered to wildcard handlers. See `topicMatchesPattern` below.
+- Replay (opt-in): construct the bus with `replay: { maxPerTopic }` and pass `{ replay: true | n }` as the third `subscribe()` argument. `maxPerTopic` must be a positive safe integer. The new handler immediately receives the buffered history (up to `n`, capped by `maxPerTopic`, default 100) with `message.replayed: true`, so late joiners do not miss earlier publications. Only dispatched publications are buffered (a topic with no local subscriber drops them as unowned); buffers are in-memory and cleared when the last handler for the topic unsubscribes. Wildcard subscriptions replay across every buffered topic matching the pattern.
 
 ### `unsubscribe(topic, handler?)`
 
@@ -216,6 +229,66 @@ Available options:
 - `workerFactory`: custom Dedicated Worker loading method
 - `sharedWorkerFactory`: custom SharedWorker loading method
 
+## WebSocket Transport Backend
+
+A dependency-free transport over a plain WebSocket. Any server speaking the JSON frame protocol below can back the same cross-tab clustering stack (owner dedup, sticky routes, failover) as the Centrifuge backend.
+
+### `createWebSocketDataBus<TData>(options)`
+
+```ts
+createWebSocketDataBus<TData>(options): CrossTabDataBus<WebSocketDataBusConfig, TData>
+```
+
+Creates an auto-starting WebSocket DataBus. Defaults: `clusterKey = connection.url`.
+
+```ts
+const bus = createWebSocketDataBus({
+  connection: { url: 'wss://example.test/ws' },
+  trace: { enabled: true, sink: event => console.log(event) }
+});
+```
+
+### `WebSocketTransport<TData>`
+
+```ts
+new WebSocketTransport<TData>(connection: WebSocketDataBusConfig)
+```
+
+Implements `DataBusTransport`. Connection lifecycle maps to the DataBus status vocabulary: socket `open` → `connected`, `close` → `disconnected`, `error` → `error` (which triggers DataBus auto-recovery). Subscriptions are re-asserted when a socket reopens in place. Frames dropped while the socket is not open are reported via `handlers.onError`; reopening re-sends subscribe frames.
+
+`WebSocketDataBusConfig` fields:
+
+- `url` — WebSocket endpoint.
+- `protocols` — optional subprotocol(s) for the handshake.
+- `webSocketFactory` — optional factory `(url, protocols) => WebSocketLike` for tests and non-browser runtimes (defaults to the global `WebSocket`).
+
+### Wire protocol
+
+JSON text frames:
+
+- client → server: `{"op":"subscribe"|"unsubscribe"|"publish","topic":"...","data":...}`
+- server → client: `{"topic":"...","data":...}` for publications. Frames without a string `topic` field are ignored; malformed JSON surfaces via `handlers.onError` without throwing.
+
+A pattern-aware server may deliver publications tagged with the concrete topic (recommended); publications tagged with the pattern itself are delivered through the exact-match path.
+
+## React Hooks (`cross-tab-worker-databus/hooks`)
+
+React (>= 18) is an optional peer dependency; this entry is separate so non-React consumers never load it.
+
+### `useCrossTabDataBus(create, deps?)`
+
+Creates a bus for the component's lifetime: created on mount, stopped on unmount. StrictMode-safe — the double-invoked effect exercises the same stop/recreate path as BFCache suspend/resume. Returns the active bus or `null` before the first effect (SSR / initial render).
+
+Pass a fresh bus per effect run (an inline factory); key recreation through `deps`.
+
+### `useCrossTabSubscription(bus, topic, handler)`
+
+Attaches a message handler with automatic cleanup. The handler is read through a ref on each delivery, so inline closures do not cause resubscription across re-renders. Queues while `bus` is `null` or the transport is not ready.
+
+### `useCrossTabStatus(bus)`
+
+Mirrors `bus.onStatus()` into React state and reads the current value synchronously whenever the bus identity changes. Returns `'connecting' | 'connected' | 'disconnected' | 'error'`.
+
 ## `WorkerClusterRuntime`
 
 Advanced API responsible for Worker registration, heartbeat, visibility, routing, BroadcastChannel protocol, and migration. Business modules should not operate on it directly.
@@ -257,5 +330,7 @@ Selects the actual backend based on `WorkerMode` and capability detection, retur
 - `selectLeastLoadedWorker`
 - `selectRebalanceTarget`
 - `hasActiveOwner`
+- `isWildcardTopic(pattern)`
+- `topicMatchesPattern(pattern, topic)` — wildcard matching used by subscriptions: `chat.*` matches `chat.room.1` (segment-boundary prefix), `*` matches everything
 
 These pure functions are primarily used for testing, diagnostics, and custom coordination strategies.

package/docs/getting-started.md

@@ -14,6 +14,8 @@ The package provides the following entry points:
 - `cross-tab-worker-databus/centrifuge`: the built-in Centrifuge Worker transport
 - `cross-tab-worker-databus/centrifuge.worker`: the Dedicated Worker build artifact, loaded by default by the built-in factory; typically no need to reference it directly
 - `cross-tab-worker-databus/centrifuge.shared.worker`: the SharedWorker build artifact, loaded by default by the built-in factory; typically no need to reference it directly
+- `cross-tab-worker-databus/hooks`: optional React hooks adapter (`useCrossTabDataBus`, `useCrossTabSubscription`, `useCrossTabStatus`); React (>= 18) is an optional peer dependency
+- `cross-tab-worker-databus` also exports a zero-dependency native `WebSocketTransport` / `createWebSocketDataBus` for servers that speak plain WebSockets
 
 The `cross-tab-worker-databus/centrifuge` entry point relies on the optional peer dependency `centrifuge` (^5.5.3). Install it alongside this package when using the built-in Centrifuge transport: `pnpm add centrifuge`.
 
@@ -21,6 +23,10 @@ The `cross-tab-worker-databus/centrifuge` entry point relies on the optional pee
 
 It is recommended to create an instance in the application's infrastructure layer and have other modules import it directly. This way, business modules within the same Tab share the Worker, connection, and Topic references.
 
+Both module formats are published: ESM (`import`) and CommonJS (`require` / `dist/cjs`), so CJS bundler configurations and `require()` callers work out of the box.
+
+When consuming the Centrifuge entry as CommonJS in a browser, provide an explicit `workerFactory` (or `sharedWorkerFactory`) if your bundler does not preserve `import.meta.url`; the default module-relative Worker URL is only available in ESM output.
+
 ```ts
 import { createCentrifugeDataBus } from 'cross-tab-worker-databus/centrifuge';
 

package/docs/transports.md

@@ -125,8 +125,35 @@ opt in:
 }
 ```
 
+## Built-in: native WebSocket backend
+
+The package ships a second real backend, `WebSocketTransport`, proving the
+contract above with zero dependencies. Use it when your server already speaks
+WebSockets and you do not need Centrifugo features.
+
+```ts
+import { createWebSocketDataBus } from 'cross-tab-worker-databus';
+
+const bus = createWebSocketDataBus({
+  connection: { url: 'wss://example.test/ws' }
+});
+```
+
+Wire protocol (JSON text frames):
+
+- client → server: `{"op":"subscribe"|"unsubscribe"|"publish","topic":"...","data":...}`
+- server → client: publications are `{"topic":"...","data":...}`. Frames
+  without a string `topic` are ignored; malformed JSON is reported through
+  `handlers.onError` without throwing.
+
+Lifecycle mapping: `open` → `connected`, `close` → `disconnected`,
+`error` → `error` (DataBus auto-recovery). Subscribe frames are re-sent when
+the socket reopens in place. A pattern-aware server may tag publications with
+the concrete topic — see wildcard subscriptions in [api.md](./api.md).
+
 ## 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

package/docs/zh/api.md

@@ -19,6 +19,17 @@ import {
   CentrifugeWorkerTransport,
   createCentrifugeDataBus
 } from 'cross-tab-worker-databus/centrifuge';
+
+import {
+  WebSocketTransport,
+  createWebSocketDataBus
+} from 'cross-tab-worker-databus';
+
+import {
+  useCrossTabDataBus,
+  useCrossTabStatus,
+  useCrossTabSubscription
+} from 'cross-tab-worker-databus/hooks';
 ```
 
 业务接入优先使用 `CrossTabDataBus` 或 `createCentrifugeDataBus`。`WorkerClusterRuntime` 属于高级协调 API。
@@ -68,6 +79,8 @@ subscribe(
 - 当前 Tab 第一个 handler 会登记集群订阅。
 - 最后一个 handler 释放后，当前 Tab 才退出该 Topic。
 - transport 尚未 ready 时订阅自动排队。
+- 通配符订阅：以 `.*` 结尾的 Topic（如 `chat.*`）匹配任意后缀，`*` 匹配全部。pattern 以字面量参与路由、归属与传输订阅；携带匹配的具体 topic（或 pattern 本身）的发布都会投递给通配 handler。匹配规则见下方 `topicMatchesPattern`。
+- 重放（可选）：构造 bus 时传 `replay: { maxPerTopic }` 开启缓冲，`maxPerTopic` 必须是正安全整数；`subscribe()` 第三个参数传 `{ replay: true | n }` 后，新 handler 会立即收到缓冲历史（最多 `n` 条，受 `maxPerTopic` 上限约束，默认 100），消息带 `message.replayed: true` 标记——晚加入的 handler 不会错过更早的发布。只有被分发过的消息才入缓冲（无本地订阅者的 topic 会被 owner 丢弃）；缓冲仅存内存，该 topic 最后一个 handler 退订时清空。通配订阅会对所有匹配 pattern 的已缓冲 topic 做回放。
 
 ### `unsubscribe(topic, handler?)`
 
@@ -216,6 +229,66 @@ const transport = new CentrifugeWorkerTransport({
 - `workerFactory`：自定义 Dedicated Worker 加载方式
 - `sharedWorkerFactory`：自定义 SharedWorker 加载方式
 
+## WebSocket 传输后端
+
+基于原生 WebSocket 的零依赖传输。任何实现下列 JSON 帧协议的服务器都能驱动与 Centrifuge 后端相同的跨 Tab 集群栈（owner 去重、粘性路由、故障转移）。
+
+### `createWebSocketDataBus<TData>(options)`
+
+```ts
+createWebSocketDataBus<TData>(options): CrossTabDataBus<WebSocketDataBusConfig, TData>
+```
+
+创建自动启动的 WebSocket DataBus。默认值：`clusterKey = connection.url`。
+
+```ts
+const bus = createWebSocketDataBus({
+  connection: { url: 'wss://example.test/ws' },
+  trace: { enabled: true, sink: event => console.log(event) }
+});
+```
+
+### `WebSocketTransport<TData>`
+
+```ts
+new WebSocketTransport<TData>(connection: WebSocketDataBusConfig)
+```
+
+实现 `DataBusTransport`。连接生命周期直接映射 DataBus 状态：socket `open` → `connected`，`close` → `disconnected`，`error` → `error`（触发 DataBus 自动恢复）。socket 原地重连时会自动重发订阅；socket 未打开期间被丢弃的帧通过 `handlers.onError` 上报，重开后自动补发订阅帧。
+
+`WebSocketDataBusConfig` 字段：
+
+- `url` — WebSocket 端点。
+- `protocols` — 可选的握手子协议。
+- `webSocketFactory` — 可选工厂 `(url, protocols) => WebSocketLike`，用于测试与非浏览器运行时（默认使用全局 `WebSocket`）。
+
+### 线协议
+
+JSON 文本帧：
+
+- client → server：`{"op":"subscribe"|"unsubscribe"|"publish","topic":"...","data":...}`
+- server → client：发布为 `{"topic":"...","data":...}`。没有字符串 `topic` 字段的帧被忽略；非法 JSON 通过 `handlers.onError` 上报而不会抛出。
+
+支持 pattern 的服务器建议以具体 topic 标注发布；以 pattern 本身标注的发布走精确匹配路径投递。
+
+## React Hooks（`cross-tab-worker-databus/hooks`）
+
+React（>= 18）是可选 peer 依赖；独立入口保证非 React 消费者不会加载它。
+
+### `useCrossTabDataBus(create, deps?)`
+
+创建随组件生命周期存活的 bus：挂载时创建，卸载时停止。StrictMode 安全——effect 双调用走的是与 BFCache 挂起/恢复相同的停止/重建路径。返回当前 bus；首次 effect 之前（SSR / 初始渲染）为 `null`。
+
+每次 effect 返回一个全新 bus（内联工厂即可）；需要重建时通过 `deps` 控制。
+
+### `useCrossTabSubscription(bus, topic, handler)`
+
+登记消息 handler 并自动清理。handler 经由 ref 在每次投递时读取，因此内联闭包不会导致重渲染时的重订阅。`bus` 为 `null` 或 transport 未 ready 时自动排队。
+
+### `useCrossTabStatus(bus)`
+
+把 `bus.onStatus()` 镜像为 React 状态，bus 身份变化时同步读取当前值。返回 `'connecting' | 'connected' | 'disconnected' | 'error'`。
+
 ## `WorkerClusterRuntime`
 
 高级 API，负责 Worker 注册、心跳、可见性、路由、BroadcastChannel 协议和迁移。业务模块不应直接操作它。
@@ -257,5 +330,7 @@ const transport = new CentrifugeWorkerTransport({
 - `selectLeastLoadedWorker`
 - `selectRebalanceTarget`
 - `hasActiveOwner`
+- `isWildcardTopic(pattern)`
+- `topicMatchesPattern(pattern, topic)` — 订阅使用的通配匹配：`chat.*` 匹配 `chat.room.1`（按段前缀），`*` 匹配全部
 
 这些纯函数主要用于测试、诊断和自定义协调策略。

package/docs/zh/getting-started.md

@@ -14,6 +14,8 @@ pnpm add cross-tab-worker-databus
 - `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/hooks`：可选的 React hooks 适配层（`useCrossTabDataBus`、`useCrossTabSubscription`、`useCrossTabStatus`）；React（>= 18）为可选 peer 依赖
+- `cross-tab-worker-databus` 同时导出零依赖的原生 `WebSocketTransport` / `createWebSocketDataBus`，适用于本身使用 WebSocket 的服务器
 
 `cross-tab-worker-databus/centrifuge` 入口依赖可选 peer dependency `centrifuge`（^5.5.3）。使用内置 Centrifuge transport 时请一并安装：`pnpm add centrifuge`。
 
@@ -21,6 +23,10 @@ pnpm add cross-tab-worker-databus
 
 建议在应用基础设施层创建一个实例，其他模块直接导入。这样同一 Tab 内的业务模块会共享 Worker、连接和 Topic 引用。
 
+包同时发布 ESM 与 CommonJS 双格式：`import` 与 `require()`（`dist/cjs`）均可直接使用，CJS bundler 配置无需额外处理。
+
+在浏览器中以 CommonJS 使用 Centrifuge 入口时，如果 bundler 不保留 `import.meta.url`，请显式提供 `workerFactory`（或 `sharedWorkerFactory`）；默认的模块相对 Worker URL 仅在 ESM 产物中可用。
+
 ```ts
 import { createCentrifugeDataBus } from 'cross-tab-worker-databus/centrifuge';
 

package/docs/zh/transports.md

@@ -114,8 +114,32 @@ shared worker）：
 }
 ```
 
+## 内置：原生 WebSocket 后端
+
+包内自带第二个真实后端 `WebSocketTransport`，以零依赖验证了上述契约。当你的
+服务器本身使用 WebSocket、且不需要 Centrifugo 特性时可以直接使用。
+
+```ts
+import { createWebSocketDataBus } from 'cross-tab-worker-databus';
+
+const bus = createWebSocketDataBus({
+  connection: { url: 'wss://example.test/ws' }
+});
+```
+
+线协议（JSON 文本帧）：
+
+- client → server：`{"op":"subscribe"|"unsubscribe"|"publish","topic":"...","data":...}`
+- server → client：发布为 `{"topic":"...","data":...}`。没有字符串 `topic` 的帧
+  会被忽略；非法 JSON 通过 `handlers.onError` 上报而不会抛出。
+
+生命周期映射：`open` → `connected`，`close` → `disconnected`，`error` → `error`
+（触发 DataBus 自动恢复）。socket 原地重连时自动重发订阅帧。支持 pattern 的
+服务器可以以具体 topic 标注发布——见 [api.md](../api.md) 中的通配符订阅。
+
 ## 工厂入口
 
+
 提供一个 `create<Backend>DataBus(options)` 工厂，把 transport 接入
 `CrossTabDataBus`，与 `createCentrifugeDataBus` 对称。这是大多数消费者使用的
 界面；它应接受连接配置、cluster key（默认为连接 URL），并把 trace /

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "cross-tab-worker-databus",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "description": "Framework-agnostic cross-tab data bus with Dedicated/Shared Worker clustering and Centrifuge support.",
   "type": "module",
   "license": "MIT",
   "author": "Sun1090",
   "repository": {
     "type": "git",
-    "url": "https://github.com/Sun1090/cross-tab-worker-databus.git"
+    "url": "git+https://github.com/Sun1090/cross-tab-worker-databus.git"
   },
   "homepage": "https://github.com/Sun1090/cross-tab-worker-databus#readme",
   "bugs": {
@@ -29,17 +29,19 @@
     "README.md",
     "LICENSE"
   ],
-  "main": "./dist/index.js",
+  "main": "./dist/cjs/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "import": "./dist/index.js",
+      "require": "./dist/cjs/index.cjs"
     },
     "./centrifuge": {
       "types": "./dist/centrifuge.d.ts",
-      "import": "./dist/centrifuge.js"
+      "import": "./dist/centrifuge.js",
+      "require": "./dist/cjs/centrifuge.cjs"
     },
     "./centrifuge.worker": {
       "types": "./dist/workers/centrifuge.worker.d.ts",
@@ -49,6 +51,11 @@
       "types": "./dist/workers/centrifuge.shared.worker.d.ts",
       "default": "./dist/centrifuge.shared.worker.js"
     },
+    "./hooks": {
+      "types": "./dist/hooks.d.ts",
+      "import": "./dist/hooks.js",
+      "require": "./dist/cjs/hooks.cjs"
+    },
     "./package.json": "./package.json"
   },
   "sideEffects": [
@@ -57,32 +64,42 @@
   ],
   "scripts": {
     "build": "node scripts/build.mjs",
-    "check": "pnpm typecheck && pnpm test && pnpm build",
+    "check": "pnpm typecheck && pnpm build && pnpm test",
     "examples": "node scripts/serve-examples.mjs",
     "lint": "eslint .",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
+    "bench": "vitest bench --run",
     "test:e2e": "pnpm build && playwright test",
     "typecheck": "tsc --noEmit",
     "prepublishOnly": "pnpm check"
   },
   "peerDependencies": {
-    "centrifuge": "^5.5.3"
+    "centrifuge": "^5.5.3",
+    "react": ">=18"
   },
   "peerDependenciesMeta": {
     "centrifuge": {
       "optional": true
+    },
+    "react": {
+      "optional": true
     }
   },
   "devDependencies": {
     "@eslint/js": "^9.39.5",
     "@playwright/test": "^1.62.1",
+    "@testing-library/react": "^16.3.3",
     "@types/node": "^24.0.0",
+    "@types/react": "^18.3.31",
     "@vitest/coverage-v8": "^3.2.7",
     "esbuild": "^0.25.0",
     "eslint": "^9.39.4",
     "globals": "^17.11.0",
+    "jsdom": "^25.0.1",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
     "typescript": "^5.9.0",
     "typescript-eslint": "^8.68.0",
     "vitest": "^3.2.0"