cross-tab-worker-databus 0.2.0 → 0.3.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,7 @@ 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.
 
 ### `unsubscribe(topic, handler?)`
 
@@ -216,6 +228,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 +329,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

@@ -12,12 +12,19 @@ The package provides the following entry points:
 
 - `cross-tab-worker-databus`: the core DataBus and transport interfaces
 - `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`.
 
 ## 2. Creating an Instance
 
 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.
+
 ```ts
 import { createCentrifugeDataBus } from 'cross-tab-worker-databus/centrifuge';
 

package/docs/transports.md

@@ -59,8 +59,9 @@ transport only owns the I/O path: connect, subscribe, publish, disconnect.
 
 Mirror the Centrifuge backend's `centrifuge-protocol.ts`: a discriminated union
 of messages the main thread sends to the Worker (`INIT` / `SUBSCRIBE` /
-`UNSUBSCRIBE` / `PUBLISH` / `STOP`) and a union the Worker posts back
-(`STATUS` / `MESSAGE` / `ERROR`). Keep it structured-cloneable (no functions,
+`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
@@ -124,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/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/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,7 @@ subscribe(
 - 当前 Tab 第一个 handler 会登记集群订阅。
 - 最后一个 handler 释放后，当前 Tab 才退出该 Topic。
 - transport 尚未 ready 时订阅自动排队。
+- 通配符订阅：以 `.*` 结尾的 Topic（如 `chat.*`）匹配任意后缀，`*` 匹配全部。pattern 以字面量参与路由、归属与传输订阅；携带匹配的具体 topic（或 pattern 本身）的发布都会投递给通配 handler。匹配规则见下方 `topicMatchesPattern`。
 
 ### `unsubscribe(topic, handler?)`
 
@@ -216,6 +228,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 +329,7 @@ const transport = new CentrifugeWorkerTransport({
 - `selectLeastLoadedWorker`
 - `selectRebalanceTarget`
 - `hasActiveOwner`
+- `isWildcardTopic(pattern)`
+- `topicMatchesPattern(pattern, topic)` — 订阅使用的通配匹配：`chat.*` 匹配 `chat.room.1`（按段前缀），`*` 匹配全部
 
 这些纯函数主要用于测试、诊断和自定义协调策略。

package/docs/zh/getting-started.md

@@ -12,12 +12,19 @@ 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/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`。
 
 ## 2. 创建实例
 
 建议在应用基础设施层创建一个实例，其他模块直接导入。这样同一 Tab 内的业务模块会共享 Worker、连接和 Topic 引用。
 
+包同时发布 ESM 与 CommonJS 双格式：`import` 与 `require()`（`dist/cjs`）均可直接使用，CJS bundler 配置无需额外处理。
+
 ```ts
 import { createCentrifugeDataBus } from 'cross-tab-worker-databus/centrifuge';
 

package/docs/zh/transports.md

@@ -54,8 +54,9 @@ DataBus 层负责跨 Tab 协调（BroadcastChannel 控制面、localStorage 路
 ### 1. 定义你的 Worker 协议
 
 参照 Centrifuge 后端的 `centrifuge-protocol.ts`：一个主线程发给 Worker 的
-判别联合（`INIT` / `SUBSCRIBE` / `UNSUBSCRIBE` / `PUBLISH` / `STOP`）和一个
-Worker 回传的联合（`STATUS` / `MESSAGE` / `ERROR`）。保持结构化克隆安全
+判别联合（`INIT` / `SUBSCRIBE` / `UNSUBSCRIBE` / `PUBLISH` / `PUBLISH_BIN` /
+`PING` / `STOP`）和一个 Worker 回传的联合（`STATUS` / `MESSAGE` / `MESSAGE_BIN` /
+`ERROR`）。保持结构化克隆安全
 （无函数、无类实例——`Error` 必须序列化）。
 
 ### 2. 实现 session
@@ -113,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,6 +1,6 @@
 {
   "name": "cross-tab-worker-databus",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Framework-agnostic cross-tab data bus with Dedicated/Shared Worker clustering and Centrifuge support.",
   "type": "module",
   "license": "MIT",
@@ -29,48 +29,82 @@
     "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",
+      "default": "./dist/centrifuge.worker.js"
+    },
+    "./centrifuge.shared.worker": {
+      "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"
     },
-    "./centrifuge.worker": "./dist/centrifuge.worker.js",
-    "./centrifuge.shared.worker": "./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",
+    "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",
     "test:e2e": "pnpm build && playwright test",
-    "typecheck": "tsc --noEmit"
+    "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"
   },
   "engines": {
     "node": ">=18.0.0"
   },
   "packageManager": "pnpm@10.14.0"
-}
+}