cross-tab-worker-databus 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+本项目遵循 [Semantic Versioning](https://semver.org/)；变更记录格式参考 [Keep a Changelog](https://keepachangelog.com/)。
+
+## [Unreleased]
+
+## [0.1.0] - 2026-08-24
+
+首次公开发布。
+
+### Added
+
+- 框架无关的跨标签页发布/订阅数据总线，通过 BroadcastChannel 在同源标签页间分发消息
+- Dedicated Worker / Shared Worker / 本地线程三档 transport 后端，`auto` 模式自动降级
+- 基于 localStorage + BroadcastChannel 的 Worker 集群协调：粘性 Topic owner 路由、新 Topic 负载均衡、owner 崩溃 failover、`pagehide` 优雅交接
+- 内置 Centrifuge WebSocket transport，连接、订阅、token 刷新、二进制数据均在 Worker 内处理，不阻塞主线程
+- ArrayBuffer Transferable 支持，零拷贝传输二进制 publication
+- 本地 handler 引用计数与订阅排队：连接期间订阅不丢失，去重 transport subscribe 调用
+- 可选结构化 trace：生命周期、连接状态、协调快照、订阅事件，以及分桶延迟直方图（P50/P95/Max）与吞吐聚合指标
+- localStorage 写入合并与指数退避重试，协调元数据写入移出热路径
+- 连接 URL 与 Topic 通过 128 位非加密哈希转为不透明 key，明文不落入 localStorage 键名
+- SharedWorker 端口回收器：主线程 PING 心跳 + 静默超时回收，崩溃 Tab 未发 STOP 也不泄漏 session
+- 优雅降级：localStorage/BroadcastChannel 不可用时退化为本地单 Tab 模式
+
+### Documentation
+
+- 英文与中文文档：架构、API 参考、配置、快速上手、能力矩阵
+- 多标签页浏览器演示页，可视化数据流、延迟指标与集群路由状态

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sun1090
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,185 @@
+# cross-tab-worker-databus
+
+> [中文](./README.zh.md) | English
+
+Framework-agnostic browser cross-tab data bus.
+
+By default each tab holds its own Dedicated Worker; when configured with `workerMode: 'shared'` or `'auto'`, same-origin tabs can reuse a single SharedWorker. In `auto` mode it degrades automatically through SharedWorker → Dedicated Worker → main-thread WebSocket. Same-origin tabs form a logical Worker cluster over BroadcastChannel; the SDK automatically coordinates sticky Topic owners, subscription reuse, new-Topic load distribution, failover, and page lifecycle, so the application only needs to subscribe to Topics and process data.
+
+## Features
+
+- Subscribable immediately after creation; subscriptions auto-queue while the connection is pending
+- Subscriptions within the same tab are deduplicated by handler reference counting
+- Topic owners are reused across same-origin tabs, reducing duplicate real-time subscriptions
+- In SharedWorker mode, same-origin tabs reuse a single SharedWorker; each tab's port maintains its own independent connection, so refreshing or stopping one tab does not affect others
+- `workerMode` supports `dedicated` / `shared` / `auto`; `auto` degrades via SharedWorker → Dedicated Worker → main-thread WebSocket, while explicit `dedicated` degrades via Dedicated Worker → SharedWorker → main-thread WebSocket
+- With `transferable: true`, ArrayBuffer messages are transmitted via Transferable while the object-message API stays unchanged
+- localStorage coordination writes are merged and flushed in batches; heartbeat and route confirmation use exponential backoff
+- Existing Topic owners remain stable while alive; visibility changes do not move established subscriptions
+- New Topics are assigned to the least-loaded eligible Worker
+- `pagehide` releases resources automatically; `pageshow` rebuilds the Worker and connection automatically
+- Transport reconnect automatically restores the current owner's Topics
+- After a tab exits abnormally, automatic migration happens via heartbeat TTL
+- Automatically degrades to local mode when BroadcastChannel or localStorage is unavailable
+- The persistence layer does not store connection addresses, raw Topic text, or message content
+
+See the [Capabilities Matrix](./docs/capabilities.md) for the full list of implemented, unimplemented, and planned capabilities.
+
+## Installation
+
+```bash
+pnpm add cross-tab-worker-databus
+```
+
+## Getting Started
+
+```ts
+import { createCentrifugeDataBus } from 'cross-tab-worker-databus/centrifuge';
+
+interface ResourceEvent {
+  id: string;
+  version: number;
+  content: unknown;
+}
+
+const bus = createCentrifugeDataBus<ResourceEvent>({
+  connection: {
+    url: getConnectionUrl(),
+    options: getConnectionOptions()
+  }
+});
+
+const unsubscribe = bus.subscribe('resource.changed', ({ data }) => {
+  applyResourceEvent(data);
+});
+
+await bus.ready();
+
+unsubscribe();
+await bus.stop();
+```
+
+The application does not need to handle Tab owner, Worker migration, page recovery, or re-subscription after reconnection.
+
+## Browser Demo
+
+The repository includes runnable multi-tab demo pages that showcase real-time data flow between publishing, receiving, cluster routing, Worker sessions, and the server:
+
+```bash
+pnpm install
+pnpm build
+pnpm examples
+```
+
+Then open `http://localhost:4173/examples/demo/` in multiple tabs at the same time to see cross-tab data flowing. The demo page uses the public Centrifugo demo endpoint `wss://faye.centrifugal.dev/connection/websocket` by default; the address, Worker mode, and Topics can all be modified in-page. You can also switch to "local broadcast" mode, which does not depend on an external server and demonstrates multi-tab coordination purely through BroadcastChannel.
+
+The demo page includes data-flow animations, an event stream, receive/dispatch latency metrics, and cluster Worker routing status.
+
+## Docs
+
+- [Docs Index](./docs/README.md)
+- [Getting Started](./docs/getting-started.md)
+- [Configuration](./docs/configuration.md)
+- [API Reference](./docs/api.md)
+- [Architecture](./docs/architecture.md)
+- [Capabilities Matrix](./docs/capabilities.md)
+- [Changelog](./CHANGELOG.md)
+
+## API Examples
+
+### Subscribe with lifecycle handling
+
+```ts
+const bus = createCentrifugeDataBus<ResourceEvent>({
+  connection: { url: 'wss://example.com/ws', options: {} }
+});
+
+// Subscribe before connection — queued until ready
+const unsub = bus.subscribe('events.created', ({ data }) => {
+  console.log('event received:', data);
+});
+
+// Monitor connection status
+const unsubStatus = bus.onStatus(status => {
+  console.log('transport status:', status);
+});
+
+// Handle errors
+const unsubError = bus.onError(error => {
+  console.error('transport error:', error);
+});
+
+await bus.ready();
+
+// Later: clean up
+unsub();
+unsubStatus();
+unsubError();
+await bus.stop();
+```
+
+### Multi-tab cluster with SharedWorker
+
+```ts
+import { createCentrifugeDataBus } from 'cross-tab-worker-databus/centrifuge';
+
+const bus = createCentrifugeDataBus<ResourceEvent>({
+  connection: {
+    url: 'wss://example.com/connection/websocket',
+    options: {}
+  },
+  workerMode: 'auto'  // SharedWorker → Dedicated Worker → local fallback
+});
+
+bus.subscribe('resource.changed', ({ data }) => {
+  // Data arrives from any tab's owner Worker
+  apply(data);
+});
+```
+
+### Publish and receive
+
+```ts
+const publisher = createCentrifugeDataBus<ResourceEvent>({
+  connection: { url: getUrl(), options: {} }
+});
+const receiver = createCentrifugeDataBus<ResourceEvent>({
+  connection: { url: getUrl(), options: {} }
+});
+
+receiver.subscribe('resource.updated', ({ data }) => {
+  console.log('got update:', data);
+});
+
+await publisher.ready();
+publisher.publish('resource.updated', { id: 'abc', version: 2, content: { title: 'hello' } });
+```
+
+### Diagnostics
+
+```ts
+const bus = createCentrifugeDataBus<ResourceEvent>({
+  connection: { url: getUrl(), options: {} },
+  trace: {
+    enabled: true,
+    sink: event => console.log('trace:', event.type, event)
+  }
+});
+
+// Snapshot
+const snapshot = bus.getClusterSnapshot();
+console.log(snapshot.workers, snapshot.routes, snapshot.assignedTopics);
+```
+
+## Development
+
+```bash
+pnpm install
+pnpm check          # typecheck + unit tests + build
+pnpm test:e2e       # Playwright multi-tab browser tests (requires Google Chrome)
+pnpm pack --pack-destination /tmp
+```
+
+## License
+
+[MIT](./LICENSE)

package/README.zh.md

@@ -0,0 +1,98 @@
+# cross-tab-worker-databus
+
+> 中文 | [English](./README.md)
+
+框架无关的浏览器跨 Tab 数据总线。
+
+默认每个 Tab 使用独立的 Dedicated Worker；配置 `workerMode: 'shared'` 或 `'auto'` 后，同源 Tab 可复用同一个 SharedWorker。`auto` 模式自动从 SharedWorker → Dedicated Worker → 主线程 WebSocket 降级。同源 Tab 通过 BroadcastChannel 形成逻辑 Worker 集群；SDK 自动协调粘性 Topic owner、订阅复用、新 Topic 负载分配、故障转移和页面生命周期，业务只需订阅 Topic 和处理数据。
+
+## 特性
+
+- 创建后可立即订阅；连接未就绪时订阅自动排队
+- 同一 Tab 内同 Topic 多 handler 通过引用计数去重
+- 同源 Tab 复用 Topic owner，减少重复实时订阅
+- SharedWorker 模式同源 Tab 复用同一个 SharedWorker；每个 Tab 的 port 各自维护独立的连接，单个 Tab 刷新或停止不影响其他 Tab
+- `workerMode` 支持 `dedicated` / `shared` / `auto`；`auto` 按 SharedWorker → Dedicated Worker → 主线程 WebSocket 降级，`dedicated` 按 Dedicated Worker → SharedWorker → 主线程 WebSocket 降级
+- 开启 `transferable: true` 后，ArrayBuffer 消息通过 Transferable 传输，对象消息 API 不变
+- localStorage 协调写入合并批量 flush；心跳和路由确认使用指数退避
+- 已有 Topic 的 owner 存活时保持稳定，前后台切换不迁移已有订阅
+- 新 Topic 分配给负载最低的候选 Worker
+- `pagehide` 自动释放资源；`pageshow` 自动重建 Worker 和连接
+- Transport 重连自动恢复当前 owner 的 Topic
+- Tab 异常退出后通过心跳 TTL 自动迁移
+- BroadcastChannel 或 localStorage 不可用时自动降级为本地模式
+- 持久层不存储连接地址、原始 Topic 文本和消息内容
+
+完整能力清单见 [能力矩阵](./docs/zh/capabilities.md)。
+
+## 安装
+
+```bash
+pnpm add cross-tab-worker-databus
+```
+
+## 快速接入
+
+```ts
+import { createCentrifugeDataBus } from 'cross-tab-worker-databus/centrifuge';
+
+interface ResourceEvent {
+  id: string;
+  version: number;
+  content: unknown;
+}
+
+const bus = createCentrifugeDataBus<ResourceEvent>({
+  connection: {
+    url: getConnectionUrl(),
+    options: getConnectionOptions()
+  }
+});
+
+const unsubscribe = bus.subscribe('resource.changed', ({ data }) => {
+  applyResourceEvent(data);
+});
+
+await bus.ready();
+
+unsubscribe();
+await bus.stop();
+```
+
+业务无需处理 Tab owner、Worker 迁移、页面恢复或重连后的重新订阅。
+
+## 浏览器演示
+
+仓库包含可运行的多标签演示页面，展示发布、接收、集群路由、Worker 会话和服务器之间的实时数据流：
+
+```bash
+pnpm install
+pnpm build
+pnpm examples
+```
+
+然后在多个浏览器标签页中同时打开 `http://localhost:4173/examples/demo/` 即可观察跨 Tab 数据流转。演示页默认使用公共 Centrifugo 演示地址 `wss://faye.centrifugal.dev/connection/websocket`；地址、Worker 模式和 Topic 都可在页面内修改。也可以切换到"本地广播"模式，不依赖外部服务器，仅通过 BroadcastChannel 演示多标签协同。
+
+演示页包含数据流动画、事件流、接收/分发延迟指标和集群 Worker 路由状态。
+
+## 文档
+
+- [文档索引](./docs/zh/README.md)
+- [快速接入](./docs/zh/getting-started.md)
+- [配置说明](./docs/zh/configuration.md)
+- [API 参考](./docs/zh/api.md)
+- [架构说明](./docs/zh/architecture.md)
+- [能力矩阵](./docs/zh/capabilities.md)
+- [变更日志](./CHANGELOG.md)
+
+## 开发
+
+```bash
+pnpm install
+pnpm check
+pnpm pack --pack-destination /tmp
+```
+
+## 许可证
+
+[MIT](./LICENSE)

package/dist/centrifuge-protocol.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Worker-thread protocol for Centrifuge WebSocket transport.
+ *
+ * Defines the message types exchanged between the main thread and a Web Worker
+ * (dedicated or shared) that runs a centrifuge client. The worker is isolated
+ * from the main thread so that WebSocket lifecycle, token refresh, and binary
+ * data handling never block the UI.
+ */
+import type { Options } from 'centrifuge';
+import type { WorkerStatus } from './core/types';
+/**
+ * Default interval between main-thread PING heartbeats to a SharedWorker. The
+ * SharedWorker reaps a silent port after `SESSION_TIMEOUT_MULTIPLIER` intervals.
+ * Shared here so the main thread (heartbeat sender) and the SharedWorker (reaper)
+ * always agree on the cadence.
+ */
+export declare const DEFAULT_HEARTBEAT_INTERVAL_MS = 10000;
+/** SharedWorker per-port session timeout, expressed as a multiple of that port's
+ * heartbeat interval. A live port PINGs every heartbeat interval, so a timeout of
+ * several intervals tolerates throttled tabs without reaping healthy sessions. */
+export declare const DEFAULT_SESSION_TIMEOUT_MULTIPLIER = 3;
+type WorkerUnsafeOption = 'eventsource' | 'fetch' | 'getData' | 'getToken' | 'networkEventTarget' | 'readableStream' | 'sockjs' | 'websocket';
+/** Centrifuge options safe to pass into a Worker; unsafe options are explicitly excluded. */
+export type CentrifugeWorkerConfig = Omit<Partial<Options>, WorkerUnsafeOption> & {
+    [Key in WorkerUnsafeOption]?: never;
+};
+/** Messages sent from the main thread to the Worker. */
+export type CentrifugeWorkerInput = {
+    type: 'INIT';
+    url: string;
+    config: CentrifugeWorkerConfig;
+    transferable?: boolean;
+    heartbeatIntervalMs?: number;
+} | {
+    type: 'SUBSCRIBE';
+    topic: string;
+} | {
+    type: 'UNSUBSCRIBE';
+    topic: string;
+} | {
+    type: 'PUBLISH';
+    topic: string;
+    data: unknown;
+} | {
+    type: 'PUBLISH_BIN';
+    topic: string;
+    data: ArrayBuffer;
+} | {
+    type: 'PING';
+} | {
+    type: 'STOP';
+};
+/** Messages sent from the Worker back to the main thread. */
+export type CentrifugeWorkerOutput<TData = unknown> = {
+    type: 'STATUS';
+    status: WorkerStatus;
+} | {
+    type: 'MESSAGE';
+    topic: string;
+    data: TData;
+} | {
+    type: 'MESSAGE_BIN';
+    topic: string;
+    data: ArrayBuffer;
+} | {
+    type: 'ERROR';
+    error: SerializedWorkerError;
+};
+/** Error object serialized for cross-thread transfer (Error instances cannot be cloned via postMessage). */
+export interface SerializedWorkerError {
+    name: string;
+    message: string;
+    stack?: string;
+    context?: unknown;
+}
+export {};
+//# sourceMappingURL=centrifuge-protocol.d.ts.map

package/dist/centrifuge-protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"centrifuge-protocol.d.ts","sourceRoot":"","sources":["../src/centrifuge-protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjD;;;;;GAKG;AACH,eAAO,MAAM,6BAA6B,QAAS,CAAC;AACpD;;kFAEkF;AAClF,eAAO,MAAM,kCAAkC,IAAI,CAAC;AAIpD,KAAK,kBAAkB,GACnB,aAAa,GACb,OAAO,GACP,SAAS,GACT,UAAU,GACV,oBAAoB,GACpB,gBAAgB,GAChB,QAAQ,GACR,WAAW,CAAC;AAEhB,6FAA6F;AAC7F,MAAM,MAAM,sBAAsB,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,kBAAkB,CAAC,GAAG;KAC/E,GAAG,IAAI,kBAAkB,CAAC,CAAC,EAAE,KAAK;CACpC,CAAC;AAEF,wDAAwD;AACxD,MAAM,MAAM,qBAAqB,GAC7B;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,sBAAsB,CAAC;IAAC,YAAY,CAAC,EAAE,OAAO,CAAC;IAAC,mBAAmB,CAAC,EAAE,MAAM,CAAA;CAAE,GACnH;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACpC;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACtC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GACjD;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,WAAW,CAAA;CAAE,GACzD;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAErB,6DAA6D;AAC7D,MAAM,MAAM,sBAAsB,CAAC,KAAK,GAAG,OAAO,IAC9C;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,YAAY,CAAA;CAAE,GACxC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,KAAK,CAAA;CAAE,GAC/C;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,WAAW,CAAA;CAAE,GACzD;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,qBAAqB,CAAA;CAAE,CAAC;AAEpD,4GAA4G;AAC5G,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB"}

package/dist/centrifuge-session.d.ts

@@ -0,0 +1,39 @@
+import type { CentrifugeWorkerInput, CentrifugeWorkerOutput } from './centrifuge-protocol';
+/** Callback interface for posting messages back to the transport layer. */
+export interface CentrifugeSessionSink<TData = unknown> {
+    post(message: CentrifugeWorkerOutput<TData>, transfer?: ArrayBuffer[]): void;
+}
+/**
+ * Stateful Centrifuge client wrapper shared by Dedicated Worker, SharedWorker
+ * ports and the main-thread local fallback. Each session owns one connection.
+ */
+export declare class CentrifugeSession<TData = unknown> {
+    private readonly sink;
+    private client;
+    private readonly subscriptions;
+    private transferable;
+    constructor(sink: CentrifugeSessionSink<TData>);
+    /** Dispatch an incoming Worker message to the matching operation. */
+    handle(message: CentrifugeWorkerInput): void;
+    /** Create the Centrifuge client, wire up lifecycle listeners, and connect. */
+    private initialize;
+    /** Subscribe to a Centrifuge channel. Reuses an existing subscription if one exists. */
+    private subscribe;
+    /** Unsubscribe from a Centrifuge channel and clean up the local reference. */
+    private unsubscribe;
+    /** Publish a message to the Centrifuge channel. */
+    private publish;
+    /** Forward a publication to the transport, using Transferable for binary data when enabled. */
+    private postPublication;
+    /** Disconnect the client and clear all subscriptions. */
+    private stop;
+    /** Forward a message to the sink (the transport layer). */
+    private post;
+    /** Serialise and report an error. The Centrifuge client handles reconnection
+     * internally, so a transient error should not trigger a `STATUS: error` that
+     * would cause `selectActiveWorkers()` to exclude this worker from routing.
+     * Fatal errors are distinguished by the client eventually emitting
+     * `disconnected` without a subsequent `connected`. */
+    private postError;
+}
+//# sourceMappingURL=centrifuge-session.d.ts.map

package/dist/centrifuge-session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"centrifuge-session.d.ts","sourceRoot":"","sources":["../src/centrifuge-session.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAEV,qBAAqB,EACrB,sBAAsB,EAEvB,MAAM,uBAAuB,CAAC;AAE/B,2EAA2E;AAC3E,MAAM,WAAW,qBAAqB,CAAC,KAAK,GAAG,OAAO;IACpD,IAAI,CAAC,OAAO,EAAE,sBAAsB,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC,EAAE,WAAW,EAAE,GAAG,IAAI,CAAC;CAC9E;AAED;;;GAGG;AACH,qBAAa,iBAAiB,CAAC,KAAK,GAAG,OAAO;IAKhC,OAAO,CAAC,QAAQ,CAAC,IAAI;IAJjC,OAAO,CAAC,MAAM,CAA2B;IACzC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAmC;IACjE,OAAO,CAAC,YAAY,CAAS;gBAEA,IAAI,EAAE,qBAAqB,CAAC,KAAK,CAAC;IAE/D,qEAAqE;IACrE,MAAM,CAAC,OAAO,EAAE,qBAAqB,GAAG,IAAI;IAS5C,8EAA8E;IAC9E,OAAO,CAAC,UAAU;IAelB,wFAAwF;IACxF,OAAO,CAAC,SAAS;IAmBjB,8EAA8E;IAC9E,OAAO,CAAC,WAAW;IAOnB,mDAAmD;IACnD,OAAO,CAAC,OAAO;IAKf,+FAA+F;IAC/F,OAAO,CAAC,eAAe;IASvB,yDAAyD;IACzD,OAAO,CAAC,IAAI;IAOZ,2DAA2D;IAC3D,OAAO,CAAC,IAAI;IAIZ;;;;0DAIsD;IACtD,OAAO,CAAC,SAAS;CAGlB"}

package/dist/centrifuge.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Centrifuge WebSocket transport that runs inside a Web Worker.
+ *
+ * Supports three backends, selected in order of preference:
+ * 1. SharedWorker — one WebSocket per tab session, hosted in a shared process
+ * 2. Dedicated Worker — one WebSocket per tab
+ * 3. In-process (local) — Centrifuge runs on the main thread (fallback when
+ *    neither Worker type is available, e.g. in non-browser environments)
+ *
+ * Binary data (ArrayBuffer) can be transferred via Transferable when the
+ * `transferable` option is enabled, avoiding structured-clone overhead.
+ */
+import { CrossTabDataBus } from './core/data-bus';
+import type { CrossTabDataBusOptions } from './core/data-bus';
+import type { DataBusTransport, DataBusTransportHandlers } from './core/types';
+import type { WorkerMode } from './worker-mode';
+import type { CentrifugeWorkerConfig } from './centrifuge-protocol';
+export type { CentrifugeWorkerConfig, SerializedWorkerError } from './centrifuge-protocol';
+export type { WorkerBackend, WorkerMode } from './worker-mode';
+/** WebSocket connection parameters passed to the Centrifuge Worker. */
+export interface CentrifugeDataBusConfig {
+    /** Centrifuge server WebSocket URL. */
+    url: string;
+    /** Centrifuge client options (token, channel params, etc.). */
+    options?: CentrifugeWorkerConfig;
+}
+/** Options for configuring the Worker backend (dedicated, shared, or local). */
+export interface CentrifugeWorkerTransportOptions {
+    /** Custom dedicated Worker factory. Used for testing or bundler integration. */
+    workerFactory?: () => Worker;
+    /** Custom SharedWorker factory. */
+    sharedWorkerFactory?: () => SharedWorker;
+    /** Preferred Worker mode: 'dedicated', 'shared', or 'auto'. */
+    workerMode?: WorkerMode;
+    /** Enable transferable (ArrayBuffer) support for binary data. */
+    transferable?: boolean;
+    /** Interval (ms) between PING heartbeats sent to the SharedWorker. The
+     * SharedWorker reaps a silent port after `DEFAULT_SESSION_TIMEOUT_MULTIPLIER`
+     * × this interval. Pass `Infinity` to disable heartbeats entirely. Defaults
+     * to `DEFAULT_HEARTBEAT_INTERVAL_MS`. */
+    heartbeatIntervalMs?: number;
+}
+/** Options for creating a fully-configured CrossTabDataBus with a Centrifuge transport. */
+export interface CreateCentrifugeDataBusOptions<TData = unknown> extends Omit<CrossTabDataBusOptions<CentrifugeDataBusConfig, TData>, 'autoStart' | 'clusterKey' | 'initialConfig' | 'transport'>, CentrifugeWorkerTransportOptions {
+    /** Centrifuge connection configuration. */
+    connection: CentrifugeDataBusConfig;
+    /** Cluster key for cross-tab coordination. Defaults to the connection URL. */
+    clusterKey?: string;
+}
+/**
+ * Transport layer that runs a Centrifuge WebSocket client inside a Web Worker.
+ *
+ * Delegates the actual WebSocket connection to a Worker (dedicated or shared)
+ * or falls back to an in-process CentrifugeSession. The Worker is isolated from
+ * the main thread so that WebSocket lifecycle, token refresh, and binary data
+ * handling never block the UI.
+ */
+export declare class CentrifugeWorkerTransport<TData = unknown> implements DataBusTransport<CentrifugeDataBusConfig, TData> {
+    private readonly workerMode;
+    private readonly transferable;
+    private readonly heartbeatIntervalMs;
+    private readonly workerFactory;
+    private readonly sharedWorkerFactory;
+    private backend;
+    private worker;
+    private sharedWorker;
+    private port;
+    private heartbeatHandle;
+    private localSession;
+    private handlers;
+    private generation;
+    private backendGeneration;
+    constructor(options?: CentrifugeWorkerTransportOptions);
+    /**
+     * Start the transport: select a backend, initialise the Worker (or local
+     * session), and send the INIT message with connection parameters.
+     */
+    start(config: CentrifugeDataBusConfig, handlers: DataBusTransportHandlers<TData>): void;
+    subscribe(topic: string): void;
+    unsubscribe(topic: string): void;
+    /**
+     * Publish data to `topic`. Binary data (ArrayBuffer) is sent via Transferable
+     * when `transferable` is enabled, avoiding a structured-clone cycle.
+     */
+    publish(topic: string, data: unknown): void;
+    /**
+     * Gracefully stop the transport: send STOP, clean up event listeners, and
+     * terminate the Worker (or close the SharedWorker port).
+     */
+    stop(): void;
+    /** Create and initialise a dedicated Worker, then send the INIT message. */
+    private startDedicatedWorker;
+    /** Create and initialise a SharedWorker, open the MessagePort, and send the INIT message. */
+    private startSharedWorker;
+    /** Handle a message event from the Worker (dedicated or shared). */
+    private readonly handleMessage;
+    /** Handle a message from the in-process CentrifugeSession (local fallback). */
+    private readonly handleSessionOutput;
+    /** Route a Worker output message to the appropriate handler callback. */
+    private handleOutput;
+    /** Handle a Worker-level failure (crash, message decode error). Discards the
+     * dead backend so a later start()/reopen can rebuild from scratch, and
+     * signals an error status so the DataBus can trigger recovery. */
+    private onWorkerFailed;
+    /** Remove every listener attached to the current SharedWorker and its port. */
+    private detachSharedWorkerListeners;
+    /** Periodically ping the SharedWorker so its session reaper can detect a dead tab. */
+    private startHeartbeat;
+    private clearHeartbeat;
+    private readonly handleWorkerError;
+    private readonly handlePortError;
+    private readonly handleSharedWorkerError;
+    /** Clear the Worker/port/backend references after a failure or stop. */
+    private resetBackend;
+    /**
+     * Post a message to the active backend. Accepts optional Transferable buffers
+     * for zero-copy ArrayBuffer transfer.
+     */
+    private post;
+}
+/**
+ * Create a fully-configured CrossTabDataBus with a Centrifuge WebSocket transport.
+ *
+ * This is the primary entry point for consumers. It wires up the transport,
+ * cluster coordination, and lifecycle management:
+ *
+ * ```ts
+ * const bus = createCentrifugeDataBus({
+ *   connection: { url: 'wss://example.com/connection/websocket', options: { token: '…' } },
+ *   trace: { enabled: true, sink: event => console.log(event) },
+ * });
+ * ```
+ */
+export declare function createCentrifugeDataBus<TData = unknown>(options: CreateCentrifugeDataBusOptions<TData>): CrossTabDataBus<CentrifugeDataBusConfig, TData>;
+//# sourceMappingURL=centrifuge.d.ts.map

package/dist/centrifuge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"centrifuge.d.ts","sourceRoot":"","sources":["../src/centrifuge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AAC9D,OAAO,KAAK,EAAE,gBAAgB,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AAG/E,OAAO,KAAK,EAAiB,UAAU,EAAE,MAAM,eAAe,CAAC;AAC/D,OAAO,KAAK,EACV,sBAAsB,EAIvB,MAAM,uBAAuB,CAAC;AAG/B,YAAY,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC3F,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAE/D,uEAAuE;AACvE,MAAM,WAAW,uBAAuB;IACtC,uCAAuC;IACvC,GAAG,EAAE,MAAM,CAAC;IACZ,+DAA+D;IAC/D,OAAO,CAAC,EAAE,sBAAsB,CAAC;CAClC;AAED,gFAAgF;AAChF,MAAM,WAAW,gCAAgC;IAC/C,gFAAgF;IAChF,aAAa,CAAC,EAAE,MAAM,MAAM,CAAC;IAC7B,mCAAmC;IACnC,mBAAmB,CAAC,EAAE,MAAM,YAAY,CAAC;IACzC,+DAA+D;IAC/D,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,iEAAiE;IACjE,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;6CAGyC;IACzC,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,2FAA2F;AAC3F,MAAM,WAAW,8BAA8B,CAAC,KAAK,GAAG,OAAO,CAC7D,SAAQ,IAAI,CACR,sBAAsB,CAAC,uBAAuB,EAAE,KAAK,CAAC,EACtD,WAAW,GAAG,YAAY,GAAG,eAAe,GAAG,WAAW,CAC3D,EACD,gCAAgC;IAClC,2CAA2C;IAC3C,UAAU,EAAE,uBAAuB,CAAC;IACpC,8EAA8E;IAC9E,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,qBAAa,yBAAyB,CAAC,KAAK,GAAG,OAAO,CACpD,YAAW,gBAAgB,CAAC,uBAAuB,EAAE,KAAK,CAAC;IAE3D,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAa;IACxC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAU;IACvC,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAS;IAC7C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA6B;IAC3D,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAmC;IACvE,OAAO,CAAC,OAAO,CAA8B;IAC7C,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,YAAY,CAA6B;IACjD,OAAO,CAAC,IAAI,CAA4B;IACxC,OAAO,CAAC,eAAe,CAA+C;IACtE,OAAO,CAAC,YAAY,CAAyC;IAC7D,OAAO,CAAC,QAAQ,CAAgD;IAGhE,OAAO,CAAC,UAAU,CAAK;IAGvB,OAAO,CAAC,iBAAiB,CAAK;gBAElB,OAAO,GAAE,gCAAqC;IAS1D;;;OAGG;IACH,KAAK,CAAC,MAAM,EAAE,uBAAuB,EAAE,QAAQ,EAAE,wBAAwB,CAAC,KAAK,CAAC,GAAG,IAAI;IAgCvF,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAI9B,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAIhC;;;OAGG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI;IAQ3C;;;OAGG;IACH,IAAI,IAAI,IAAI;IAkBZ,4EAA4E;IAC5E,OAAO,CAAC,oBAAoB;IAS5B,6FAA6F;IAC7F,OAAO,CAAC,iBAAiB;IAczB,oEAAoE;IACpE,OAAO,CAAC,QAAQ,CAAC,aAAa,CAE5B;IAEF,+EAA+E;IAC/E,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAElC;IAEF,yEAAyE;IACzE,OAAO,CAAC,YAAY;IAOpB;;sEAEkE;IAClE,OAAO,CAAC,cAAc;IAetB,+EAA+E;IAC/E,OAAO,CAAC,2BAA2B;IAMnC,sFAAsF;IACtF,OAAO,CAAC,cAAc;IAUtB,OAAO,CAAC,cAAc;IAKtB,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAGhC;IAEF,OAAO,CAAC,QAAQ,CAAC,eAAe,CAG9B;IAEF,OAAO,CAAC,QAAQ,CAAC,uBAAuB,CAGtC;IAEF,wEAAwE;IACxE,OAAO,CAAC,YAAY;IAQpB;;;OAGG;IACH,OAAO,CAAC,IAAI;CAiBb;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,GAAG,OAAO,EACrD,OAAO,EAAE,8BAA8B,CAAC,KAAK,CAAC,GAC7C,eAAe,CAAC,uBAAuB,EAAE,KAAK,CAAC,CAwBjD"}