tab-bridge 0.2.0 → 0.4.0

package/dist/jotai/index.d.cts

@@ -0,0 +1,68 @@
+import { WritableAtom } from 'jotai/vanilla';
+import { T as TabSyncInstance } from '../instance-hvEUHx6i.cjs';
+
+/**
+ * Options for `atomWithTabSync`.
+ *
+ * All atoms sharing the same `channel` reuse a single `createTabSync`
+ * instance internally. Channel-level options (`transport`, `debug`,
+ * `onError`) are taken from the **first** atom that creates the
+ * instance on that channel.
+ *
+ * @example
+ * ```ts
+ * import { atomWithTabSync } from 'tab-bridge/jotai';
+ *
+ * const countAtom = atomWithTabSync('count', 0, {
+ *   channel: 'my-app',
+ *   debug: true,
+ * });
+ * ```
+ */
+interface AtomWithTabSyncOptions {
+    /** Channel name for cross-tab communication. @default 'tab-sync-jotai' */
+    channel?: string;
+    /** Force a specific transport layer. @default auto-detect */
+    transport?: 'broadcast-channel' | 'local-storage';
+    /** Enable debug logging. @default false */
+    debug?: boolean;
+    /** Error callback for non-fatal errors (channel failures, etc.). */
+    onError?: (error: Error) => void;
+    /**
+     * Callback invoked when the underlying `TabSyncInstance` is ready.
+     * Useful for accessing advanced features (RPC, leader election, etc.).
+     * Called once per shared instance — only the first atom to trigger
+     * instance creation will have its callback invoked.
+     */
+    onSyncReady?: (instance: TabSyncInstance<Record<string, unknown>>) => void;
+}
+
+type SetStateAction<T> = T | ((prev: T) => T);
+/**
+ * Creates a Jotai atom whose value is automatically synchronised across
+ * browser tabs via `tab-bridge`.
+ *
+ * Each atom creates its own `createTabSync` instance scoped to the channel
+ * `${channel}:${key}`. The instance is created when the atom is first
+ * subscribed to (React component mount / `store.sub`) and destroyed on
+ * the last unsubscription (unmount).
+ *
+ * The atom behaves like a normal writable atom — use `useAtom` in React
+ * or `store.get` / `store.set` with Jotai's vanilla store.
+ *
+ * @param key - Unique key identifying this piece of state within the channel.
+ * @param initialValue - Default value used when no synced state exists yet.
+ * @param options - Channel and transport configuration.
+ * @returns A writable Jotai atom.
+ *
+ * @example
+ * ```ts
+ * import { atomWithTabSync } from 'tab-bridge/jotai';
+ *
+ * const countAtom = atomWithTabSync('count', 0, { channel: 'my-app' });
+ * const themeAtom = atomWithTabSync('theme', 'light', { channel: 'my-app' });
+ * ```
+ */
+declare function atomWithTabSync<T>(key: string, initialValue: T, options?: AtomWithTabSyncOptions): WritableAtom<T, [SetStateAction<T>], void>;
+
+export { type AtomWithTabSyncOptions, atomWithTabSync };

package/dist/jotai/index.d.ts

@@ -0,0 +1,68 @@
+import { WritableAtom } from 'jotai/vanilla';
+import { T as TabSyncInstance } from '../instance-hvEUHx6i.js';
+
+/**
+ * Options for `atomWithTabSync`.
+ *
+ * All atoms sharing the same `channel` reuse a single `createTabSync`
+ * instance internally. Channel-level options (`transport`, `debug`,
+ * `onError`) are taken from the **first** atom that creates the
+ * instance on that channel.
+ *
+ * @example
+ * ```ts
+ * import { atomWithTabSync } from 'tab-bridge/jotai';
+ *
+ * const countAtom = atomWithTabSync('count', 0, {
+ *   channel: 'my-app',
+ *   debug: true,
+ * });
+ * ```
+ */
+interface AtomWithTabSyncOptions {
+    /** Channel name for cross-tab communication. @default 'tab-sync-jotai' */
+    channel?: string;
+    /** Force a specific transport layer. @default auto-detect */
+    transport?: 'broadcast-channel' | 'local-storage';
+    /** Enable debug logging. @default false */
+    debug?: boolean;
+    /** Error callback for non-fatal errors (channel failures, etc.). */
+    onError?: (error: Error) => void;
+    /**
+     * Callback invoked when the underlying `TabSyncInstance` is ready.
+     * Useful for accessing advanced features (RPC, leader election, etc.).
+     * Called once per shared instance — only the first atom to trigger
+     * instance creation will have its callback invoked.
+     */
+    onSyncReady?: (instance: TabSyncInstance<Record<string, unknown>>) => void;
+}
+
+type SetStateAction<T> = T | ((prev: T) => T);
+/**
+ * Creates a Jotai atom whose value is automatically synchronised across
+ * browser tabs via `tab-bridge`.
+ *
+ * Each atom creates its own `createTabSync` instance scoped to the channel
+ * `${channel}:${key}`. The instance is created when the atom is first
+ * subscribed to (React component mount / `store.sub`) and destroyed on
+ * the last unsubscription (unmount).
+ *
+ * The atom behaves like a normal writable atom — use `useAtom` in React
+ * or `store.get` / `store.set` with Jotai's vanilla store.
+ *
+ * @param key - Unique key identifying this piece of state within the channel.
+ * @param initialValue - Default value used when no synced state exists yet.
+ * @param options - Channel and transport configuration.
+ * @returns A writable Jotai atom.
+ *
+ * @example
+ * ```ts
+ * import { atomWithTabSync } from 'tab-bridge/jotai';
+ *
+ * const countAtom = atomWithTabSync('count', 0, { channel: 'my-app' });
+ * const themeAtom = atomWithTabSync('theme', 'light', { channel: 'my-app' });
+ * ```
+ */
+declare function atomWithTabSync<T>(key: string, initialValue: T, options?: AtomWithTabSyncOptions): WritableAtom<T, [SetStateAction<T>], void>;
+
+export { type AtomWithTabSyncOptions, atomWithTabSync };

package/dist/jotai/index.js

@@ -0,0 +1,42 @@
+import { isBrowser, createTabSync } from '../chunk-4JDWAUYM.js';
+import { atom } from 'jotai/vanilla';
+
+function atomWithTabSync(key, initialValue, options) {
+  const base_channel = options?.channel ?? "tab-sync-jotai";
+  const instance_channel = `${base_channel}:${key}`;
+  let sync_instance = null;
+  const base_atom = atom(initialValue);
+  base_atom.onMount = (setAtom) => {
+    if (!isBrowser) return;
+    const instance = createTabSync({
+      channel: instance_channel,
+      initial: { value: initialValue },
+      transport: options?.transport,
+      debug: options?.debug,
+      onError: options?.onError
+    });
+    sync_instance = instance;
+    options?.onSyncReady?.(instance);
+    const unsub = instance.on("value", (remote_value, meta) => {
+      if (!meta.isLocal) {
+        setAtom(remote_value);
+      }
+    });
+    return () => {
+      unsub();
+      instance.destroy();
+      sync_instance = null;
+    };
+  };
+  const sync_atom = atom(
+    (get) => get(base_atom),
+    (get, set, update) => {
+      const next_value = typeof update === "function" ? update(get(base_atom)) : update;
+      set(base_atom, next_value);
+      sync_instance?.set("value", next_value);
+    }
+  );
+  return sync_atom;
+}
+
+export { atomWithTabSync };

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 };