tab-bridge 0.1.1 → 0.3.0

package/dist/instance-hvEUHx6i.d.cts

@@ -0,0 +1,194 @@
+interface TabInfo {
+    id: string;
+    createdAt: number;
+    lastSeen: number;
+    isLeader: boolean;
+    isActive: boolean;
+    url: string;
+    title?: string;
+}
+interface ChangeMeta {
+    readonly sourceTabId: string;
+    readonly isLocal: boolean;
+    readonly timestamp: number;
+}
+
+/**
+ * Define your RPC contract for full type inference:
+ *
+ * ```ts
+ * interface MyRPC {
+ *   getTime: { args: void; result: { iso: string } };
+ *   add:     { args: { a: number; b: number }; result: number };
+ * }
+ *
+ * const sync = createTabSync<State, MyRPC>({ ... });
+ * const { iso } = await sync.call('leader', 'getTime');  // fully typed
+ * ```
+ */
+type RPCMap = Record<string, {
+    args: unknown;
+    result: unknown;
+}>;
+interface RPCCallAllResult<T = unknown> {
+    tabId: string;
+    result?: T;
+    error?: string;
+}
+/** Resolve args type for a method. Falls back to `unknown` for unregistered methods. */
+type RPCArgs<TMap extends RPCMap, M extends string> = M extends keyof TMap ? TMap[M]['args'] : unknown;
+/** Resolve result type for a method. Falls back to `unknown` for unregistered methods. */
+type RPCResult<TMap extends RPCMap, M extends string> = M extends keyof TMap ? TMap[M]['result'] : unknown;
+
+interface TabSyncInstance<TState extends Record<string, unknown>, TRPCMap extends RPCMap = RPCMap> {
+    /** Read a single value by key. */
+    get<K extends keyof TState>(key: K): TState[K];
+    /**
+     * Read the entire state as a frozen snapshot.
+     * Returns the same reference until state changes (safe for React).
+     */
+    getAll(): Readonly<TState>;
+    /** Update a single key. Synced to all tabs. */
+    set<K extends keyof TState>(key: K, value: TState[K]): void;
+    /** Update multiple keys in a single broadcast. */
+    patch(partial: Partial<TState>): void;
+    /**
+     * Atomically update multiple keys based on the current state.
+     * Return `null` to abort the transaction.
+     *
+     * ```ts
+     * sync.transaction((state) => {
+     *   if (state.balance >= amount) {
+     *     return { balance: state.balance - amount, history: [...state.history, tx] };
+     *   }
+     *   return null; // abort
+     * });
+     * ```
+     */
+    transaction(fn: (state: Readonly<TState>) => Partial<TState> | null): void;
+    /**
+     * Subscribe to changes for a specific key.
+     * @returns Unsubscribe function.
+     *
+     * ```ts
+     * const off = sync.on('theme', (value, meta) => {
+     *   console.log(value, meta.isLocal ? 'local' : 'remote');
+     * });
+     * off(); // unsubscribe
+     * ```
+     */
+    on<K extends keyof TState>(key: K, callback: (value: TState[K], meta: ChangeMeta) => void): () => void;
+    /**
+     * Subscribe to a specific key, but fire only once then auto-unsubscribe.
+     *
+     * ```ts
+     * sync.once('theme', (value) => console.log('First change:', value));
+     * ```
+     */
+    once<K extends keyof TState>(key: K, callback: (value: TState[K], meta: ChangeMeta) => void): () => void;
+    /**
+     * Subscribe to all state changes.
+     * @returns Unsubscribe function.
+     */
+    onChange(callback: (state: Readonly<TState>, changedKeys: (keyof TState)[], meta: ChangeMeta) => void): () => void;
+    /**
+     * Subscribe to a **derived value**. The callback only fires when the
+     * selector's return value actually changes (compared via `isEqual`,
+     * default `Object.is`).
+     *
+     * ```ts
+     * sync.select(
+     *   (s) => s.items.filter(i => i.done).length,
+     *   (doneCount) => badge.textContent = doneCount,
+     * );
+     * ```
+     *
+     * @returns Unsubscribe function.
+     */
+    select<TResult>(selector: (state: Readonly<TState>) => TResult, callback: (result: TResult, meta: ChangeMeta) => void, options?: {
+        isEqual?: (a: TResult, b: TResult) => boolean;
+        debounce?: number;
+    }): () => void;
+    /** Whether this tab is currently the leader. */
+    isLeader(): boolean;
+    /**
+     * Register a callback that fires when this tab becomes leader.
+     * Optionally return a cleanup function that runs when leadership is lost.
+     *
+     * ```ts
+     * sync.onLeader(() => {
+     *   const ws = new WebSocket('...');
+     *   return () => ws.close(); // cleanup on resign
+     * });
+     * ```
+     */
+    onLeader(callback: () => void | (() => void)): () => void;
+    /** Get info about the current leader tab, or `null` if no leader yet. */
+    getLeader(): TabInfo | null;
+    /**
+     * Returns a promise that resolves with the leader's `TabInfo`
+     * as soon as a leader is elected. Resolves immediately if a leader
+     * already exists.
+     *
+     * ```ts
+     * const leader = await sync.waitForLeader();
+     * const result = await sync.call('leader', 'getData');
+     * ```
+     */
+    waitForLeader(): Promise<TabInfo>;
+    /** Unique ID of this tab (UUID v4). */
+    readonly id: string;
+    /** List of all currently active tabs. */
+    getTabs(): TabInfo[];
+    /** Number of currently active tabs. */
+    getTabCount(): number;
+    /**
+     * Subscribe to tab presence changes (join, leave, leader change).
+     * @returns Unsubscribe function.
+     */
+    onTabChange(callback: (tabs: TabInfo[]) => void): () => void;
+    /**
+     * Call a remote procedure on another tab.
+     *
+     * ```ts
+     * const result = await sync.call('leader', 'getTime');
+     * const sum    = await sync.call(tabId, 'add', { a: 1, b: 2 });
+     * ```
+     *
+     * @param target - Tab ID or `'leader'` to auto-resolve.
+     * @param method - Method name (typed if `TRPCMap` is provided).
+     * @param args   - Arguments to pass to the handler.
+     * @param timeout - Timeout in ms. Default: `5000`.
+     */
+    call<M extends string>(target: string | 'leader', method: M, args?: RPCArgs<TRPCMap, M>, timeout?: number): Promise<RPCResult<TRPCMap, M>>;
+    /**
+     * Call a method on **all other tabs** (fan-out).
+     * Returns an array of per-tab results, including errors.
+     *
+     * ```ts
+     * const results = await sync.callAll('getStatus');
+     * for (const { tabId, result, error } of results) { ... }
+     * ```
+     */
+    callAll<M extends string>(method: M, args?: RPCArgs<TRPCMap, M>, timeout?: number): Promise<RPCCallAllResult<RPCResult<TRPCMap, M>>[]>;
+    /**
+     * Register an RPC handler that other tabs can call.
+     *
+     * ```ts
+     * sync.handle('add', ({ a, b }) => a + b);
+     * ```
+     *
+     * @returns Unsubscribe function to remove the handler.
+     */
+    handle<M extends string>(method: M, handler: (args: RPCArgs<TRPCMap, M>, callerTabId: string) => RPCResult<TRPCMap, M> | Promise<RPCResult<TRPCMap, M>>): () => void;
+    /**
+     * Destroy this instance. Sends goodbye to other tabs,
+     * cancels all timers, and flushes pending state.
+     * Safe to call multiple times.
+     */
+    destroy(): void;
+    /** `false` after `destroy()` has been called. */
+    readonly ready: boolean;
+}
+
+export type { ChangeMeta as C, RPCMap as R, TabSyncInstance as T, TabInfo as a, RPCCallAllResult as b, RPCArgs as c, RPCResult as d };

package/dist/instance-hvEUHx6i.d.ts

@@ -0,0 +1,194 @@
+interface TabInfo {
+    id: string;
+    createdAt: number;
+    lastSeen: number;
+    isLeader: boolean;
+    isActive: boolean;
+    url: string;
+    title?: string;
+}
+interface ChangeMeta {
+    readonly sourceTabId: string;
+    readonly isLocal: boolean;
+    readonly timestamp: number;
+}
+
+/**
+ * Define your RPC contract for full type inference:
+ *
+ * ```ts
+ * interface MyRPC {
+ *   getTime: { args: void; result: { iso: string } };
+ *   add:     { args: { a: number; b: number }; result: number };
+ * }
+ *
+ * const sync = createTabSync<State, MyRPC>({ ... });
+ * const { iso } = await sync.call('leader', 'getTime');  // fully typed
+ * ```
+ */
+type RPCMap = Record<string, {
+    args: unknown;
+    result: unknown;
+}>;
+interface RPCCallAllResult<T = unknown> {
+    tabId: string;
+    result?: T;
+    error?: string;
+}
+/** Resolve args type for a method. Falls back to `unknown` for unregistered methods. */
+type RPCArgs<TMap extends RPCMap, M extends string> = M extends keyof TMap ? TMap[M]['args'] : unknown;
+/** Resolve result type for a method. Falls back to `unknown` for unregistered methods. */
+type RPCResult<TMap extends RPCMap, M extends string> = M extends keyof TMap ? TMap[M]['result'] : unknown;
+
+interface TabSyncInstance<TState extends Record<string, unknown>, TRPCMap extends RPCMap = RPCMap> {
+    /** Read a single value by key. */
+    get<K extends keyof TState>(key: K): TState[K];
+    /**
+     * Read the entire state as a frozen snapshot.
+     * Returns the same reference until state changes (safe for React).
+     */
+    getAll(): Readonly<TState>;
+    /** Update a single key. Synced to all tabs. */
+    set<K extends keyof TState>(key: K, value: TState[K]): void;
+    /** Update multiple keys in a single broadcast. */
+    patch(partial: Partial<TState>): void;
+    /**
+     * Atomically update multiple keys based on the current state.
+     * Return `null` to abort the transaction.
+     *
+     * ```ts
+     * sync.transaction((state) => {
+     *   if (state.balance >= amount) {
+     *     return { balance: state.balance - amount, history: [...state.history, tx] };
+     *   }
+     *   return null; // abort
+     * });
+     * ```
+     */
+    transaction(fn: (state: Readonly<TState>) => Partial<TState> | null): void;
+    /**
+     * Subscribe to changes for a specific key.
+     * @returns Unsubscribe function.
+     *
+     * ```ts
+     * const off = sync.on('theme', (value, meta) => {
+     *   console.log(value, meta.isLocal ? 'local' : 'remote');
+     * });
+     * off(); // unsubscribe
+     * ```
+     */
+    on<K extends keyof TState>(key: K, callback: (value: TState[K], meta: ChangeMeta) => void): () => void;
+    /**
+     * Subscribe to a specific key, but fire only once then auto-unsubscribe.
+     *
+     * ```ts
+     * sync.once('theme', (value) => console.log('First change:', value));
+     * ```
+     */
+    once<K extends keyof TState>(key: K, callback: (value: TState[K], meta: ChangeMeta) => void): () => void;
+    /**
+     * Subscribe to all state changes.
+     * @returns Unsubscribe function.
+     */
+    onChange(callback: (state: Readonly<TState>, changedKeys: (keyof TState)[], meta: ChangeMeta) => void): () => void;
+    /**
+     * Subscribe to a **derived value**. The callback only fires when the
+     * selector's return value actually changes (compared via `isEqual`,
+     * default `Object.is`).
+     *
+     * ```ts
+     * sync.select(
+     *   (s) => s.items.filter(i => i.done).length,
+     *   (doneCount) => badge.textContent = doneCount,
+     * );
+     * ```
+     *
+     * @returns Unsubscribe function.
+     */
+    select<TResult>(selector: (state: Readonly<TState>) => TResult, callback: (result: TResult, meta: ChangeMeta) => void, options?: {
+        isEqual?: (a: TResult, b: TResult) => boolean;
+        debounce?: number;
+    }): () => void;
+    /** Whether this tab is currently the leader. */
+    isLeader(): boolean;
+    /**
+     * Register a callback that fires when this tab becomes leader.
+     * Optionally return a cleanup function that runs when leadership is lost.
+     *
+     * ```ts
+     * sync.onLeader(() => {
+     *   const ws = new WebSocket('...');
+     *   return () => ws.close(); // cleanup on resign
+     * });
+     * ```
+     */
+    onLeader(callback: () => void | (() => void)): () => void;
+    /** Get info about the current leader tab, or `null` if no leader yet. */
+    getLeader(): TabInfo | null;
+    /**
+     * Returns a promise that resolves with the leader's `TabInfo`
+     * as soon as a leader is elected. Resolves immediately if a leader
+     * already exists.
+     *
+     * ```ts
+     * const leader = await sync.waitForLeader();
+     * const result = await sync.call('leader', 'getData');
+     * ```
+     */
+    waitForLeader(): Promise<TabInfo>;
+    /** Unique ID of this tab (UUID v4). */
+    readonly id: string;
+    /** List of all currently active tabs. */
+    getTabs(): TabInfo[];
+    /** Number of currently active tabs. */
+    getTabCount(): number;
+    /**
+     * Subscribe to tab presence changes (join, leave, leader change).
+     * @returns Unsubscribe function.
+     */
+    onTabChange(callback: (tabs: TabInfo[]) => void): () => void;
+    /**
+     * Call a remote procedure on another tab.
+     *
+     * ```ts
+     * const result = await sync.call('leader', 'getTime');
+     * const sum    = await sync.call(tabId, 'add', { a: 1, b: 2 });
+     * ```
+     *
+     * @param target - Tab ID or `'leader'` to auto-resolve.
+     * @param method - Method name (typed if `TRPCMap` is provided).
+     * @param args   - Arguments to pass to the handler.
+     * @param timeout - Timeout in ms. Default: `5000`.
+     */
+    call<M extends string>(target: string | 'leader', method: M, args?: RPCArgs<TRPCMap, M>, timeout?: number): Promise<RPCResult<TRPCMap, M>>;
+    /**
+     * Call a method on **all other tabs** (fan-out).
+     * Returns an array of per-tab results, including errors.
+     *
+     * ```ts
+     * const results = await sync.callAll('getStatus');
+     * for (const { tabId, result, error } of results) { ... }
+     * ```
+     */
+    callAll<M extends string>(method: M, args?: RPCArgs<TRPCMap, M>, timeout?: number): Promise<RPCCallAllResult<RPCResult<TRPCMap, M>>[]>;
+    /**
+     * Register an RPC handler that other tabs can call.
+     *
+     * ```ts
+     * sync.handle('add', ({ a, b }) => a + b);
+     * ```
+     *
+     * @returns Unsubscribe function to remove the handler.
+     */
+    handle<M extends string>(method: M, handler: (args: RPCArgs<TRPCMap, M>, callerTabId: string) => RPCResult<TRPCMap, M> | Promise<RPCResult<TRPCMap, M>>): () => void;
+    /**
+     * Destroy this instance. Sends goodbye to other tabs,
+     * cancels all timers, and flushes pending state.
+     * Safe to call multiple times.
+     */
+    destroy(): void;
+    /** `false` after `destroy()` has been called. */
+    readonly ready: boolean;
+}
+
+export type { ChangeMeta as C, RPCMap as R, TabSyncInstance as T, TabInfo as a, RPCCallAllResult as b, RPCArgs as c, RPCResult as d };

package/dist/options-DmHyGTL0.d.cts

@@ -0,0 +1,93 @@
+import { C as ChangeMeta } from './instance-hvEUHx6i.cjs';
+
+interface MiddlewareContext<TState extends Record<string, unknown>> {
+    readonly key: keyof TState;
+    readonly value: unknown;
+    readonly previousValue: unknown;
+    readonly meta: ChangeMeta;
+}
+/**
+ * Return `false` to reject the change, `{ value }` to transform it,
+ * or `void`/`undefined` to pass through unchanged.
+ */
+type MiddlewareResult = {
+    value: unknown;
+} | false;
+interface Middleware<TState extends Record<string, unknown> = Record<string, unknown>> {
+    readonly name: string;
+    /** Intercept local `set` / `patch` calls before they are applied. */
+    onSet?: (ctx: MiddlewareContext<TState>) => MiddlewareResult | void;
+    /** Called after any state change (local or remote) has been committed. */
+    afterChange?: (key: keyof TState, value: unknown, meta: ChangeMeta) => void;
+    /** Cleanup when the instance is destroyed. */
+    onDestroy?: () => void;
+}
+
+interface PersistOptions<TState extends Record<string, unknown> = Record<string, unknown>> {
+    /** Storage key. Default: `'tab-sync:state'` */
+    key?: string;
+    /** Only persist these keys (whitelist). */
+    include?: (keyof TState)[];
+    /** Exclude these keys from persistence (blacklist). */
+    exclude?: (keyof TState)[];
+    /** Custom serializer. Default: `JSON.stringify` */
+    serialize?: (state: Partial<TState>) => string;
+    /** Custom deserializer. Default: `JSON.parse` */
+    deserialize?: (raw: string) => Partial<TState>;
+    /** Debounce persistence writes in ms. Default: `100` */
+    debounce?: number;
+    /** Custom storage backend. Default: `localStorage` */
+    storage?: Pick<Storage, 'getItem' | 'setItem' | 'removeItem'>;
+    /**
+     * Schema version for state migration. When the persisted version
+     * differs from this value, `migrate` is called.
+     */
+    version?: number;
+    /**
+     * Migration function called when persisted version differs from current.
+     *
+     * ```ts
+     * persist: {
+     *   version: 2,
+     *   migrate: (oldState, oldVersion) => ({
+     *     ...oldState,
+     *     newField: oldVersion < 2 ? 'default' : oldState.newField,
+     *   }),
+     * }
+     * ```
+     */
+    migrate?: (oldState: Partial<TState>, oldVersion: number) => Partial<TState>;
+}
+
+interface LeaderOptions {
+    /** Heartbeat interval in ms. Default: `2000` */
+    heartbeatInterval?: number;
+    /** Leader timeout in ms. Default: `6000` */
+    leaderTimeout?: number;
+}
+interface TabSyncOptions<TState extends Record<string, unknown> = Record<string, unknown>> {
+    /** Initial state used before sync completes. */
+    initial?: TState;
+    /** Channel name — only tabs sharing the same name communicate. Default: `'tab-sync'` */
+    channel?: string;
+    /** Force a specific transport layer. Default: auto-detect. */
+    transport?: 'broadcast-channel' | 'local-storage';
+    /** Custom merge function for LWW conflict resolution. */
+    merge?: (localValue: unknown, remoteValue: unknown, key: keyof TState) => unknown;
+    /** Enable leader election. Default: `true` */
+    leader?: boolean | LeaderOptions;
+    /** Heartbeat interval in ms. Default: `2000` */
+    heartbeatInterval?: number;
+    /** Leader timeout in ms. Default: `6000` */
+    leaderTimeout?: number;
+    /** Enable debug logging. Default: `false` */
+    debug?: boolean;
+    /** Persist state across page reloads. `true` uses defaults, or pass options. */
+    persist?: PersistOptions<TState> | boolean;
+    /** Middleware pipeline for intercepting state changes. */
+    middlewares?: Middleware<TState>[];
+    /** Error callback for non-fatal errors (storage, channel, etc.). */
+    onError?: (error: Error) => void;
+}
+
+export type { LeaderOptions as L, Middleware as M, PersistOptions as P, TabSyncOptions as T, MiddlewareContext as a, MiddlewareResult as b };

package/dist/options-iN7Rnvwj.d.ts

@@ -0,0 +1,93 @@
+import { C as ChangeMeta } from './instance-hvEUHx6i.js';
+
+interface MiddlewareContext<TState extends Record<string, unknown>> {
+    readonly key: keyof TState;
+    readonly value: unknown;
+    readonly previousValue: unknown;
+    readonly meta: ChangeMeta;
+}
+/**
+ * Return `false` to reject the change, `{ value }` to transform it,
+ * or `void`/`undefined` to pass through unchanged.
+ */
+type MiddlewareResult = {
+    value: unknown;
+} | false;
+interface Middleware<TState extends Record<string, unknown> = Record<string, unknown>> {
+    readonly name: string;
+    /** Intercept local `set` / `patch` calls before they are applied. */
+    onSet?: (ctx: MiddlewareContext<TState>) => MiddlewareResult | void;
+    /** Called after any state change (local or remote) has been committed. */
+    afterChange?: (key: keyof TState, value: unknown, meta: ChangeMeta) => void;
+    /** Cleanup when the instance is destroyed. */
+    onDestroy?: () => void;
+}
+
+interface PersistOptions<TState extends Record<string, unknown> = Record<string, unknown>> {
+    /** Storage key. Default: `'tab-sync:state'` */
+    key?: string;
+    /** Only persist these keys (whitelist). */
+    include?: (keyof TState)[];
+    /** Exclude these keys from persistence (blacklist). */
+    exclude?: (keyof TState)[];
+    /** Custom serializer. Default: `JSON.stringify` */
+    serialize?: (state: Partial<TState>) => string;
+    /** Custom deserializer. Default: `JSON.parse` */
+    deserialize?: (raw: string) => Partial<TState>;
+    /** Debounce persistence writes in ms. Default: `100` */
+    debounce?: number;
+    /** Custom storage backend. Default: `localStorage` */
+    storage?: Pick<Storage, 'getItem' | 'setItem' | 'removeItem'>;
+    /**
+     * Schema version for state migration. When the persisted version
+     * differs from this value, `migrate` is called.
+     */
+    version?: number;
+    /**
+     * Migration function called when persisted version differs from current.
+     *
+     * ```ts
+     * persist: {
+     *   version: 2,
+     *   migrate: (oldState, oldVersion) => ({
+     *     ...oldState,
+     *     newField: oldVersion < 2 ? 'default' : oldState.newField,
+     *   }),
+     * }
+     * ```
+     */
+    migrate?: (oldState: Partial<TState>, oldVersion: number) => Partial<TState>;
+}
+
+interface LeaderOptions {
+    /** Heartbeat interval in ms. Default: `2000` */
+    heartbeatInterval?: number;
+    /** Leader timeout in ms. Default: `6000` */
+    leaderTimeout?: number;
+}
+interface TabSyncOptions<TState extends Record<string, unknown> = Record<string, unknown>> {
+    /** Initial state used before sync completes. */
+    initial?: TState;
+    /** Channel name — only tabs sharing the same name communicate. Default: `'tab-sync'` */
+    channel?: string;
+    /** Force a specific transport layer. Default: auto-detect. */
+    transport?: 'broadcast-channel' | 'local-storage';
+    /** Custom merge function for LWW conflict resolution. */
+    merge?: (localValue: unknown, remoteValue: unknown, key: keyof TState) => unknown;
+    /** Enable leader election. Default: `true` */
+    leader?: boolean | LeaderOptions;
+    /** Heartbeat interval in ms. Default: `2000` */
+    heartbeatInterval?: number;
+    /** Leader timeout in ms. Default: `6000` */
+    leaderTimeout?: number;
+    /** Enable debug logging. Default: `false` */
+    debug?: boolean;
+    /** Persist state across page reloads. `true` uses defaults, or pass options. */
+    persist?: PersistOptions<TState> | boolean;
+    /** Middleware pipeline for intercepting state changes. */
+    middlewares?: Middleware<TState>[];
+    /** Error callback for non-fatal errors (storage, channel, etc.). */
+    onError?: (error: Error) => void;
+}
+
+export type { LeaderOptions as L, Middleware as M, PersistOptions as P, TabSyncOptions as T, MiddlewareContext as a, MiddlewareResult as b };