tab-bridge 0.1.0

package/dist/index.cjs

@@ -0,0 +1,149 @@
+'use strict';
+
+var chunkBQCNBNBT_cjs = require('./chunk-BQCNBNBT.cjs');
+
+// src/utils/message.ts
+function createMessage(type, senderId, payload, targetId) {
+  return {
+    type,
+    senderId,
+    targetId,
+    timestamp: chunkBQCNBNBT_cjs.monotonic(),
+    version: chunkBQCNBNBT_cjs.PROTOCOL_VERSION,
+    payload
+  };
+}
+
+// src/utils/emitter.ts
+var Emitter = class {
+  constructor() {
+    this._handlers = /* @__PURE__ */ new Map();
+  }
+  on(event, handler) {
+    let set = this._handlers.get(event);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      this._handlers.set(event, set);
+    }
+    set.add(handler);
+    return () => {
+      set.delete(handler);
+    };
+  }
+  once(event, handler) {
+    const off = this.on(event, ((...args) => {
+      off();
+      handler(...args);
+    }));
+    return off;
+  }
+  emit(...args) {
+    const [event, data] = args;
+    const set = this._handlers.get(event);
+    if (!set) return;
+    for (const handler of set) {
+      handler(data);
+    }
+  }
+  listenerCount(event) {
+    return this._handlers.get(event)?.size ?? 0;
+  }
+  removeAll(event) {
+    if (event) {
+      this._handlers.delete(event);
+    } else {
+      this._handlers.clear();
+    }
+  }
+};
+
+Object.defineProperty(exports, "BroadcastChannelTransport", {
+  enumerable: true,
+  get: function () { return chunkBQCNBNBT_cjs.BroadcastChannelTransport; }
+});
+Object.defineProperty(exports, "ErrorCode", {
+  enumerable: true,
+  get: function () { return chunkBQCNBNBT_cjs.ErrorCode; }
+});
+Object.defineProperty(exports, "LeaderElection", {
+  enumerable: true,
+  get: function () { return chunkBQCNBNBT_cjs.LeaderElection; }
+});
+Object.defineProperty(exports, "PROTOCOL_VERSION", {
+  enumerable: true,
+  get: function () { return chunkBQCNBNBT_cjs.PROTOCOL_VERSION; }
+});
+Object.defineProperty(exports, "RPCHandler", {
+  enumerable: true,
+  get: function () { return chunkBQCNBNBT_cjs.RPCHandler; }
+});
+Object.defineProperty(exports, "StateManager", {
+  enumerable: true,
+  get: function () { return chunkBQCNBNBT_cjs.StateManager; }
+});
+Object.defineProperty(exports, "StorageChannel", {
+  enumerable: true,
+  get: function () { return chunkBQCNBNBT_cjs.StorageChannel; }
+});
+Object.defineProperty(exports, "TabRegistry", {
+  enumerable: true,
+  get: function () { return chunkBQCNBNBT_cjs.TabRegistry; }
+});
+Object.defineProperty(exports, "TabSyncError", {
+  enumerable: true,
+  get: function () { return chunkBQCNBNBT_cjs.TabSyncError; }
+});
+Object.defineProperty(exports, "createBatcher", {
+  enumerable: true,
+  get: function () { return chunkBQCNBNBT_cjs.createBatcher; }
+});
+Object.defineProperty(exports, "createChannel", {
+  enumerable: true,
+  get: function () { return chunkBQCNBNBT_cjs.createChannel; }
+});
+Object.defineProperty(exports, "createTabSync", {
+  enumerable: true,
+  get: function () { return chunkBQCNBNBT_cjs.createTabSync; }
+});
+Object.defineProperty(exports, "destroyMiddleware", {
+  enumerable: true,
+  get: function () { return chunkBQCNBNBT_cjs.destroyMiddleware; }
+});
+Object.defineProperty(exports, "generateTabId", {
+  enumerable: true,
+  get: function () { return chunkBQCNBNBT_cjs.generateTabId; }
+});
+Object.defineProperty(exports, "hasBroadcastChannel", {
+  enumerable: true,
+  get: function () { return chunkBQCNBNBT_cjs.hasBroadcastChannel; }
+});
+Object.defineProperty(exports, "hasCrypto", {
+  enumerable: true,
+  get: function () { return chunkBQCNBNBT_cjs.hasCrypto; }
+});
+Object.defineProperty(exports, "hasDocument", {
+  enumerable: true,
+  get: function () { return chunkBQCNBNBT_cjs.hasDocument; }
+});
+Object.defineProperty(exports, "hasLocalStorage", {
+  enumerable: true,
+  get: function () { return chunkBQCNBNBT_cjs.hasLocalStorage; }
+});
+Object.defineProperty(exports, "isBrowser", {
+  enumerable: true,
+  get: function () { return chunkBQCNBNBT_cjs.isBrowser; }
+});
+Object.defineProperty(exports, "monotonic", {
+  enumerable: true,
+  get: function () { return chunkBQCNBNBT_cjs.monotonic; }
+});
+Object.defineProperty(exports, "notifyMiddleware", {
+  enumerable: true,
+  get: function () { return chunkBQCNBNBT_cjs.notifyMiddleware; }
+});
+Object.defineProperty(exports, "runMiddleware", {
+  enumerable: true,
+  get: function () { return chunkBQCNBNBT_cjs.runMiddleware; }
+});
+exports.Emitter = Emitter;
+exports.createMessage = createMessage;

package/dist/index.d.cts

@@ -0,0 +1,304 @@
+import { R as RPCMap, T as TabSyncOptions, a as TabSyncInstance, b as TabMessage, S as SendFn, C as ChangeMeta, c as TabInfo, M as Middleware, d as MiddlewareContext, e as MessageType, f as MessagePayloadMap, g as MessageOf } from './types-BtK4ixKz.cjs';
+export { L as LeaderClaimPayload, h as LeaderOptions, i as MiddlewareResult, P as PROTOCOL_VERSION, j as PersistOptions, k as RPCArgs, l as RPCResult, m as RpcRequestPayload, n as RpcResponsePayload, o as StateSyncResponsePayload, p as StateUpdatePayload, q as TabAnnouncePayload } from './types-BtK4ixKz.cjs';
+
+declare function createTabSync<TState extends Record<string, unknown> = Record<string, unknown>, TRPCMap extends RPCMap = RPCMap>(options?: TabSyncOptions<TState>): TabSyncInstance<TState, TRPCMap>;
+
+interface Channel {
+    postMessage(message: TabMessage): void;
+    onMessage(callback: (message: TabMessage) => void): () => void;
+    close(): void;
+}
+declare function createChannel(channelName: string, transport?: 'broadcast-channel' | 'local-storage'): Channel;
+
+declare class BroadcastChannelTransport implements Channel {
+    private bc;
+    private closed;
+    constructor(channelName: string);
+    postMessage(message: TabMessage): void;
+    onMessage(callback: (message: TabMessage) => void): () => void;
+    close(): void;
+}
+
+/**
+ * Fallback transport using `localStorage` `storage` events.
+ *
+ * Limitations vs BroadcastChannel:
+ * - Values must be JSON-serializable
+ * - `storage` event only fires on OTHER tabs (same-tab is not needed since
+ *   the originating tab already handles the change locally)
+ * - Slightly slower due to serialization overhead
+ */
+declare class StorageChannel implements Channel {
+    private readonly key;
+    private readonly listeners;
+    private closed;
+    private seq;
+    constructor(channelName: string);
+    postMessage(message: TabMessage): void;
+    onMessage(callback: (message: TabMessage) => void): () => void;
+    close(): void;
+}
+
+interface StateManagerOptions<TState extends Record<string, unknown>> {
+    send: SendFn;
+    tabId: string;
+    initial?: TState;
+    merge?: (localValue: unknown, remoteValue: unknown, key: keyof TState) => unknown;
+    /**
+     * Hook called before a remote value is applied.
+     * Return `false` to reject, `{ value }` to transform, or `void` to accept.
+     */
+    interceptRemote?: (key: keyof TState, value: unknown, previousValue: unknown, meta: ChangeMeta) => {
+        value: unknown;
+    } | false | void;
+    /** Hook called after any remote change is committed. */
+    afterRemoteChange?: (key: keyof TState, value: unknown, meta: ChangeMeta) => void;
+}
+declare class StateManager<TState extends Record<string, unknown>> {
+    private readonly state;
+    private readonly keyListeners;
+    private readonly changeListeners;
+    private readonly send;
+    private readonly tabId;
+    private readonly mergeFn?;
+    private readonly interceptRemote?;
+    private readonly afterRemoteChange?;
+    private readonly batcher;
+    private snapshotCache;
+    constructor(options: StateManagerOptions<TState>);
+    get<K extends keyof TState>(key: K): TState[K];
+    /**
+     * Returns a cached snapshot. The same reference is returned until state
+     * changes, making this safe for React's `useSyncExternalStore`.
+     */
+    getAll(): Readonly<TState>;
+    set<K extends keyof TState>(key: K, value: TState[K]): void;
+    patch(partial: Partial<TState>): void;
+    on<K extends keyof TState>(key: K, callback: (value: TState[K], meta: ChangeMeta) => void): () => void;
+    onChange(callback: (state: Readonly<TState>, changedKeys: (keyof TState)[], meta: ChangeMeta) => void): () => void;
+    handleMessage(message: TabMessage): void;
+    requestSync(): void;
+    respondToSync(targetId: string): void;
+    flush(): void;
+    destroy(): void;
+    private applyRemoteUpdate;
+    /** LWW: accept remote if newer timestamp, or same timestamp with higher senderId. */
+    private shouldAcceptRemote;
+    private applySyncResponse;
+    private notifyKey;
+    private notifyChange;
+}
+
+interface TabRegistryOptions {
+    send: SendFn;
+    tabId: string;
+    tabCreatedAt: number;
+    /** Interval (ms) to check for dead tabs. Default: `2000` */
+    heartbeatInterval?: number;
+    /** How long (ms) before a tab is considered dead. Default: `6000` */
+    tabTimeout?: number;
+}
+declare class TabRegistry {
+    private readonly tabs;
+    private readonly tabChangeListeners;
+    private readonly send;
+    private readonly tabId;
+    private readonly tabCreatedAt;
+    private readonly heartbeatInterval;
+    private readonly tabTimeout;
+    private heartbeatTimer;
+    private pruneTimer;
+    private visibilityHandler;
+    private unloadHandler;
+    constructor(options: TabRegistryOptions);
+    getTabs(): TabInfo[];
+    getTabCount(): number;
+    getTab(id: string): TabInfo | undefined;
+    onTabChange(callback: (tabs: TabInfo[]) => void): () => void;
+    announce(): void;
+    handleMessage(message: TabMessage): void;
+    setLeader(tabId: string | null): void;
+    destroy(): void;
+    private registerSelf;
+    private buildAnnouncePayload;
+    private startHeartbeat;
+    private startPruning;
+    private listenVisibility;
+    private listenUnload;
+    private sendGoodbye;
+    private handleAnnounce;
+    private handleGoodbye;
+    private touchTab;
+    private touchSelf;
+    private pruneDeadTabs;
+    private notifyChange;
+}
+
+interface LeaderElectionOptions {
+    send: SendFn;
+    tabId: string;
+    tabCreatedAt: number;
+    /** Time (ms) to wait for a higher-priority claim before becoming leader. Default: `300` */
+    electionTimeout?: number;
+    /** Heartbeat interval (ms). Default: `2000` */
+    heartbeatInterval?: number;
+    /** How many missed heartbeats before declaring leader dead. Default: `3` */
+    missedHeartbeatsLimit?: number;
+}
+declare class LeaderElection {
+    private readonly send;
+    private readonly tabId;
+    private readonly tabCreatedAt;
+    private readonly electionTimeout;
+    private readonly heartbeatInterval;
+    private readonly leaderTimeout;
+    private leaderId;
+    private electionTimer;
+    private heartbeatTimer;
+    private leaderWatchTimer;
+    private lastLeaderHeartbeat;
+    private electing;
+    private readonly leaderCallbacks;
+    private readonly leaderCleanups;
+    constructor(options: LeaderElectionOptions);
+    isLeader(): boolean;
+    getLeaderId(): string | null;
+    onLeader(callback: () => void | (() => void)): () => void;
+    start(): void;
+    handleMessage(message: TabMessage): void;
+    destroy(): void;
+    private startElection;
+    private handleClaim;
+    private handleAck;
+    private handleHeartbeat;
+    private handleResign;
+    private becomeLeader;
+    private setLeader;
+    /**
+     * Priority: oldest tab (smaller `createdAt`) wins.
+     * Tiebreak: lower `tabId` wins (deterministic).
+     */
+    private hasPriority;
+    private startHeartbeat;
+    private clearHeartbeat;
+    private startLeaderWatch;
+    private clearLeaderWatch;
+    private clearElectionTimer;
+    private runCleanups;
+}
+
+interface RPCHandlerOptions {
+    send: SendFn;
+    tabId: string;
+    resolveLeaderId?: () => string | null;
+    onError?: (error: Error) => void;
+}
+declare class RPCHandler {
+    private readonly send;
+    private readonly tabId;
+    private readonly resolveLeaderId;
+    private readonly onError;
+    private readonly handlers;
+    private readonly pending;
+    constructor(options: RPCHandlerOptions);
+    call<TResult>(targetTabId: string | 'leader', method: string, args?: unknown, timeout?: number): Promise<TResult>;
+    handle<TArgs = unknown, TResult = unknown>(method: string, handler: (args: TArgs, callerTabId: string) => TResult | Promise<TResult>): () => void;
+    handleMessage(message: TabMessage): void;
+    destroy(): void;
+    private handleRequest;
+    private handleResponse;
+    private sendResponse;
+}
+
+/**
+ * Runs the middleware pipeline for a given hook (`onSet`).
+ * Returns the (possibly transformed) value and whether the change was rejected.
+ */
+declare function runMiddleware<TState extends Record<string, unknown>>(middlewares: readonly Middleware<TState>[], ctx: MiddlewareContext<TState>): {
+    value: unknown;
+    rejected: boolean;
+};
+/** Notify all middlewares that a state change has been committed. */
+declare function notifyMiddleware<TState extends Record<string, unknown>>(middlewares: readonly Middleware<TState>[], key: keyof TState, value: unknown, meta: ChangeMeta): void;
+/** Destroy all middlewares. */
+declare function destroyMiddleware<TState extends Record<string, unknown>>(middlewares: readonly Middleware<TState>[]): void;
+
+declare function generateTabId(): string;
+
+declare function monotonic(): number;
+
+interface Batcher<T> {
+    /** Queue a key-value pair. Resets the flush timer if not already running. */
+    add(key: string, value: T): void;
+    /** Immediately flush all pending entries. */
+    flush(): void;
+    /** Cancel pending flush and discard all entries. */
+    destroy(): void;
+}
+/**
+ * Batches rapid writes into a single flush callback.
+ * Within the `delay` window, only the last value per key is kept.
+ */
+declare function createBatcher<T>(onFlush: (entries: Map<string, T>) => void, delay?: number): Batcher<T>;
+
+/**
+ * Type-safe message factory. Guarantees every message has a correct
+ * structure, protocol version, and monotonically increasing timestamp.
+ *
+ * ```ts
+ * const msg = createMessage('STATE_UPDATE', tabId, { entries: { ... } });
+ * //    ^? MessageOf<'STATE_UPDATE'>  — payload is StateUpdatePayload
+ * ```
+ */
+declare function createMessage<T extends MessageType>(type: T, senderId: string, payload: MessagePayloadMap[T], targetId?: string): MessageOf<T>;
+
+type Handler<T = void> = T extends void ? () => void : (data: T) => void;
+/**
+ * Minimal, fully typed event emitter.
+ *
+ * ```ts
+ * const bus = new Emitter<{ click: { x: number }; close: void }>();
+ * bus.on('click', ({ x }) => console.log(x));
+ * bus.emit('click', { x: 42 });
+ * ```
+ */
+declare class Emitter<TEvents extends Record<string, unknown>> {
+    private readonly _handlers;
+    on<K extends keyof TEvents>(event: K, handler: Handler<TEvents[K]>): () => void;
+    once<K extends keyof TEvents>(event: K, handler: Handler<TEvents[K]>): () => void;
+    emit<K extends keyof TEvents>(...args: TEvents[K] extends void ? [event: K] : [event: K, data: TEvents[K]]): void;
+    listenerCount<K extends keyof TEvents>(event: K): number;
+    removeAll(event?: keyof TEvents): void;
+}
+
+declare const ErrorCode: {
+    readonly CHANNEL_CLOSED: "CHANNEL_CLOSED";
+    readonly CHANNEL_SEND_FAILED: "CHANNEL_SEND_FAILED";
+    readonly RPC_TIMEOUT: "RPC_TIMEOUT";
+    readonly RPC_NO_HANDLER: "RPC_NO_HANDLER";
+    readonly RPC_NO_LEADER: "RPC_NO_LEADER";
+    readonly RPC_HANDLER_ERROR: "RPC_HANDLER_ERROR";
+    readonly RPC_DESTROYED: "RPC_DESTROYED";
+    readonly STORAGE_QUOTA_EXCEEDED: "STORAGE_QUOTA_EXCEEDED";
+    readonly MIDDLEWARE_REJECTED: "MIDDLEWARE_REJECTED";
+    readonly ALREADY_DESTROYED: "ALREADY_DESTROYED";
+};
+type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
+declare class TabSyncError extends Error {
+    readonly code: ErrorCode;
+    readonly name = "TabSyncError";
+    readonly cause?: unknown;
+    constructor(message: string, code: ErrorCode, cause?: unknown);
+    static timeout(method: string, ms: number): TabSyncError;
+    static noLeader(): TabSyncError;
+    static noHandler(method: string): TabSyncError;
+    static destroyed(): TabSyncError;
+}
+
+declare const isBrowser: boolean;
+declare const hasDocument: boolean;
+declare const hasLocalStorage: boolean;
+declare const hasBroadcastChannel: boolean;
+declare const hasCrypto: boolean;
+
+export { type Batcher, BroadcastChannelTransport, ChangeMeta, type Channel, Emitter, ErrorCode, LeaderElection, type LeaderElectionOptions, MessageOf, MessagePayloadMap, MessageType, Middleware, MiddlewareContext, RPCHandler, type RPCHandlerOptions, RPCMap, SendFn, StateManager, type StateManagerOptions, StorageChannel, TabInfo, TabMessage, TabRegistry, type TabRegistryOptions, TabSyncError, TabSyncInstance, TabSyncOptions, createBatcher, createChannel, createMessage, createTabSync, destroyMiddleware, generateTabId, hasBroadcastChannel, hasCrypto, hasDocument, hasLocalStorage, isBrowser, monotonic, notifyMiddleware, runMiddleware };