tab-bridge 0.2.0 → 0.4.0

package/dist/zustand/index.cjs

@@ -0,0 +1,80 @@
+'use strict';
+
+var chunkTGEXRVAL_cjs = require('../chunk-TGEXRVAL.cjs');
+
+// src/zustand/middleware.ts
+function shouldSyncKey(key, value, options) {
+  if (typeof value === "function") return false;
+  if (options?.include) return options.include.includes(key);
+  if (options?.exclude) return !options.exclude.includes(key);
+  return true;
+}
+function extractSyncableState(state, options) {
+  const result = {};
+  for (const [key, value] of Object.entries(state)) {
+    if (shouldSyncKey(key, value, options)) {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+function validateOptions(options) {
+  if (options?.include && options?.exclude) {
+    throw new Error(
+      "[tab-bridge/zustand] `include` and `exclude` are mutually exclusive"
+    );
+  }
+}
+var tabSyncImpl = (initializer, options) => (set, get, api) => {
+  validateOptions(options);
+  let sync_instance = null;
+  let is_remote_update = false;
+  const initial_state = initializer(set, get, api);
+  const syncable_initial = extractSyncableState(initial_state, options);
+  sync_instance = chunkTGEXRVAL_cjs.createTabSync({
+    initial: syncable_initial,
+    channel: options?.channel ?? "tab-sync-zustand",
+    debug: options?.debug,
+    transport: options?.transport,
+    merge: options?.merge,
+    onError: options?.onError
+  });
+  api.subscribe((next_state, prev_state) => {
+    if (is_remote_update || !sync_instance) return;
+    const next = next_state;
+    const prev = prev_state;
+    const diff = {};
+    let has_diff = false;
+    for (const key of Object.keys(next)) {
+      if (shouldSyncKey(key, next[key], options) && !Object.is(prev[key], next[key])) {
+        diff[key] = next[key];
+        has_diff = true;
+      }
+    }
+    if (has_diff) {
+      sync_instance.patch(diff);
+    }
+  });
+  sync_instance.onChange((remote_state, changed_keys, meta) => {
+    if (meta.isLocal) return;
+    is_remote_update = true;
+    try {
+      const patch = {};
+      let has_patch = false;
+      for (const key of changed_keys) {
+        patch[key] = remote_state[key];
+        has_patch = true;
+      }
+      if (has_patch) {
+        api.setState(patch);
+      }
+    } finally {
+      is_remote_update = false;
+    }
+  });
+  options?.onSyncReady?.(sync_instance);
+  return initial_state;
+};
+var tabSync = tabSyncImpl;
+
+exports.tabSync = tabSync;

package/dist/zustand/index.d.cts

@@ -0,0 +1,87 @@
+import { StoreMutatorIdentifier, StateCreator } from 'zustand/vanilla';
+import { T as TabSyncInstance } from '../instance-hvEUHx6i.cjs';
+
+/**
+ * Options for the `tabSync` Zustand middleware.
+ *
+ * @example
+ * ```ts
+ * import { create } from 'zustand';
+ * import { tabSync } from 'tab-bridge/zustand';
+ *
+ * const useStore = create(
+ *   tabSync(
+ *     (set) => ({
+ *       count: 0,
+ *       inc: () => set((s) => ({ count: s.count + 1 })),
+ *     }),
+ *     { channel: 'my-app', exclude: ['localOnly'] }
+ *   )
+ * );
+ * ```
+ */
+interface TabSyncZustandOptions<T = Record<string, unknown>> {
+    /** Channel name for cross-tab communication. @default 'tab-sync-zustand' */
+    channel?: string;
+    /**
+     * Only sync these keys. Functions are always excluded.
+     * Mutually exclusive with `exclude`.
+     */
+    include?: readonly (keyof T & string)[];
+    /**
+     * Exclude these keys from syncing. Functions are always excluded.
+     * Mutually exclusive with `include`.
+     */
+    exclude?: readonly (keyof T & string)[];
+    /**
+     * Custom conflict resolution.
+     * Called when the same key is updated on two tabs simultaneously.
+     * @default Last-write-wins (LWW)
+     */
+    merge?: (localValue: unknown, remoteValue: unknown, key: string) => unknown;
+    /** 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.
+     * Use this to access advanced features (RPC, leader election, etc.)
+     * or to store a reference for manual cleanup via `instance.destroy()`.
+     */
+    onSyncReady?: (instance: TabSyncInstance<Record<string, unknown>>) => void;
+}
+
+type TabSyncMiddleware = <T, Mps extends [StoreMutatorIdentifier, unknown][] = [], Mcs extends [StoreMutatorIdentifier, unknown][] = []>(initializer: StateCreator<T, Mps, Mcs>, options?: TabSyncZustandOptions<T>) => StateCreator<T, Mps, Mcs>;
+/**
+ * Zustand middleware that synchronizes store state across browser tabs
+ * via tab-bridge's BroadcastChannel/localStorage transport.
+ *
+ * Functions (actions) are automatically excluded from synchronization.
+ * Use `include` or `exclude` options to further filter which keys are synced.
+ *
+ * @param initializer - Zustand StateCreator function.
+ * @param options - Synchronization options.
+ * @returns A wrapped StateCreator that synchronizes state across tabs.
+ *
+ * @example
+ * ```ts
+ * import { create } from 'zustand';
+ * import { tabSync } from 'tab-bridge/zustand';
+ *
+ * const useStore = create(
+ *   tabSync(
+ *     (set) => ({
+ *       count: 0,
+ *       inc: () => set((s) => ({ count: s.count + 1 })),
+ *     }),
+ *     { channel: 'my-app' }
+ *   )
+ * );
+ * // All tabs sharing channel 'my-app' will have synchronized state.
+ * ```
+ */
+declare const tabSync: TabSyncMiddleware;
+
+export { type TabSyncZustandOptions, tabSync };

package/dist/zustand/index.d.ts

@@ -0,0 +1,87 @@
+import { StoreMutatorIdentifier, StateCreator } from 'zustand/vanilla';
+import { T as TabSyncInstance } from '../instance-hvEUHx6i.js';
+
+/**
+ * Options for the `tabSync` Zustand middleware.
+ *
+ * @example
+ * ```ts
+ * import { create } from 'zustand';
+ * import { tabSync } from 'tab-bridge/zustand';
+ *
+ * const useStore = create(
+ *   tabSync(
+ *     (set) => ({
+ *       count: 0,
+ *       inc: () => set((s) => ({ count: s.count + 1 })),
+ *     }),
+ *     { channel: 'my-app', exclude: ['localOnly'] }
+ *   )
+ * );
+ * ```
+ */
+interface TabSyncZustandOptions<T = Record<string, unknown>> {
+    /** Channel name for cross-tab communication. @default 'tab-sync-zustand' */
+    channel?: string;
+    /**
+     * Only sync these keys. Functions are always excluded.
+     * Mutually exclusive with `exclude`.
+     */
+    include?: readonly (keyof T & string)[];
+    /**
+     * Exclude these keys from syncing. Functions are always excluded.
+     * Mutually exclusive with `include`.
+     */
+    exclude?: readonly (keyof T & string)[];
+    /**
+     * Custom conflict resolution.
+     * Called when the same key is updated on two tabs simultaneously.
+     * @default Last-write-wins (LWW)
+     */
+    merge?: (localValue: unknown, remoteValue: unknown, key: string) => unknown;
+    /** 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.
+     * Use this to access advanced features (RPC, leader election, etc.)
+     * or to store a reference for manual cleanup via `instance.destroy()`.
+     */
+    onSyncReady?: (instance: TabSyncInstance<Record<string, unknown>>) => void;
+}
+
+type TabSyncMiddleware = <T, Mps extends [StoreMutatorIdentifier, unknown][] = [], Mcs extends [StoreMutatorIdentifier, unknown][] = []>(initializer: StateCreator<T, Mps, Mcs>, options?: TabSyncZustandOptions<T>) => StateCreator<T, Mps, Mcs>;
+/**
+ * Zustand middleware that synchronizes store state across browser tabs
+ * via tab-bridge's BroadcastChannel/localStorage transport.
+ *
+ * Functions (actions) are automatically excluded from synchronization.
+ * Use `include` or `exclude` options to further filter which keys are synced.
+ *
+ * @param initializer - Zustand StateCreator function.
+ * @param options - Synchronization options.
+ * @returns A wrapped StateCreator that synchronizes state across tabs.
+ *
+ * @example
+ * ```ts
+ * import { create } from 'zustand';
+ * import { tabSync } from 'tab-bridge/zustand';
+ *
+ * const useStore = create(
+ *   tabSync(
+ *     (set) => ({
+ *       count: 0,
+ *       inc: () => set((s) => ({ count: s.count + 1 })),
+ *     }),
+ *     { channel: 'my-app' }
+ *   )
+ * );
+ * // All tabs sharing channel 'my-app' will have synchronized state.
+ * ```
+ */
+declare const tabSync: TabSyncMiddleware;
+
+export { type TabSyncZustandOptions, tabSync };

package/dist/zustand/index.js

@@ -0,0 +1,78 @@
+import { createTabSync } from '../chunk-4JDWAUYM.js';
+
+// src/zustand/middleware.ts
+function shouldSyncKey(key, value, options) {
+  if (typeof value === "function") return false;
+  if (options?.include) return options.include.includes(key);
+  if (options?.exclude) return !options.exclude.includes(key);
+  return true;
+}
+function extractSyncableState(state, options) {
+  const result = {};
+  for (const [key, value] of Object.entries(state)) {
+    if (shouldSyncKey(key, value, options)) {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+function validateOptions(options) {
+  if (options?.include && options?.exclude) {
+    throw new Error(
+      "[tab-bridge/zustand] `include` and `exclude` are mutually exclusive"
+    );
+  }
+}
+var tabSyncImpl = (initializer, options) => (set, get, api) => {
+  validateOptions(options);
+  let sync_instance = null;
+  let is_remote_update = false;
+  const initial_state = initializer(set, get, api);
+  const syncable_initial = extractSyncableState(initial_state, options);
+  sync_instance = createTabSync({
+    initial: syncable_initial,
+    channel: options?.channel ?? "tab-sync-zustand",
+    debug: options?.debug,
+    transport: options?.transport,
+    merge: options?.merge,
+    onError: options?.onError
+  });
+  api.subscribe((next_state, prev_state) => {
+    if (is_remote_update || !sync_instance) return;
+    const next = next_state;
+    const prev = prev_state;
+    const diff = {};
+    let has_diff = false;
+    for (const key of Object.keys(next)) {
+      if (shouldSyncKey(key, next[key], options) && !Object.is(prev[key], next[key])) {
+        diff[key] = next[key];
+        has_diff = true;
+      }
+    }
+    if (has_diff) {
+      sync_instance.patch(diff);
+    }
+  });
+  sync_instance.onChange((remote_state, changed_keys, meta) => {
+    if (meta.isLocal) return;
+    is_remote_update = true;
+    try {
+      const patch = {};
+      let has_patch = false;
+      for (const key of changed_keys) {
+        patch[key] = remote_state[key];
+        has_patch = true;
+      }
+      if (has_patch) {
+        api.setState(patch);
+      }
+    } finally {
+      is_remote_update = false;
+    }
+  });
+  options?.onSyncReady?.(sync_instance);
+  return initial_state;
+};
+var tabSync = tabSyncImpl;
+
+export { tabSync };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tab-bridge",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Zero-dependency TypeScript library for real-time state synchronization across browser tabs, with leader election and cross-tab RPC",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -26,6 +26,36 @@
         "types": "./dist/react/index.d.cts",
         "default": "./dist/react/index.cjs"
       }
+    },
+    "./zustand": {
+      "import": {
+        "types": "./dist/zustand/index.d.ts",
+        "default": "./dist/zustand/index.js"
+      },
+      "require": {
+        "types": "./dist/zustand/index.d.cts",
+        "default": "./dist/zustand/index.cjs"
+      }
+    },
+    "./jotai": {
+      "import": {
+        "types": "./dist/jotai/index.d.ts",
+        "default": "./dist/jotai/index.js"
+      },
+      "require": {
+        "types": "./dist/jotai/index.d.cts",
+        "default": "./dist/jotai/index.cjs"
+      }
+    },
+    "./redux": {
+      "import": {
+        "types": "./dist/redux/index.d.ts",
+        "default": "./dist/redux/index.js"
+      },
+      "require": {
+        "types": "./dist/redux/index.d.cts",
+        "default": "./dist/redux/index.cjs"
+      }
     }
   },
   "files": [
@@ -38,6 +68,7 @@
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit",
     "prepublishOnly": "npm run typecheck && npm test && npm run build",
+    "test:e2e": "playwright test",
     "demo": "npm run build && npx serve ."
   },
   "keywords": [
@@ -70,22 +101,40 @@
   },
   "sideEffects": false,
   "peerDependencies": {
-    "react": ">=18.0.0"
+    "jotai": ">=2.0.0",
+    "react": ">=18.0.0",
+    "redux": ">=4.0.0",
+    "zustand": ">=4.0.0"
   },
   "peerDependenciesMeta": {
     "react": {
       "optional": true
+    },
+    "zustand": {
+      "optional": true
+    },
+    "jotai": {
+      "optional": true
+    },
+    "redux": {
+      "optional": true
     }
   },
   "devDependencies": {
+    "@playwright/test": "^1.58.2",
+    "@reduxjs/toolkit": "^2.11.2",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "@vitest/coverage-v8": "^2.1.9",
+    "jotai": "^2.18.0",
     "jsdom": "^25.0.1",
     "react": "^19.2.4",
     "react-dom": "^19.2.4",
+    "redux": "^5.0.1",
+    "serve": "^14.2.6",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
-    "vitest": "^2.1.9"
+    "vitest": "^2.1.9",
+    "zustand": "^5.0.11"
   }
 }