shared-state-bridge 1.0.0

package/dist/sync.d.cts

@@ -0,0 +1,154 @@
+/** State must be a plain object */
+type State = Record<string, unknown>;
+/** Full-state change listener */
+type Listener<T extends State> = (state: T, previousState: T) => void;
+/** Selector-based change listener */
+type SelectorListener<_T extends State, U> = (slice: U, previousSlice: U) => void;
+/** setState accepts partial updates or an updater function */
+interface SetState<T extends State> {
+    (partial: Partial<T> | ((state: T) => Partial<T>)): void;
+    (state: T | ((state: T) => T), replace: true): void;
+}
+/** Subscribe overloads: full-state or selector-based */
+interface Subscribe<T extends State> {
+    (listener: Listener<T>): () => void;
+    <U>(selector: (state: T) => U, listener: SelectorListener<T, U>, options?: SubscribeOptions<U>): () => void;
+}
+interface SubscribeOptions<U> {
+    equalityFn?: (a: U, b: U) => boolean;
+    fireImmediately?: boolean;
+}
+/** Plugin lifecycle hooks */
+interface BridgePlugin<T extends State> {
+    name: string;
+    onInit?: (bridge: BridgeApi<T>) => void;
+    onStateChange?: (state: T, previousState: T) => void;
+    onDestroy?: () => void;
+}
+/** The bridge instance API */
+interface BridgeApi<T extends State> {
+    getState: () => T;
+    setState: SetState<T>;
+    subscribe: Subscribe<T>;
+    getInitialState: () => T;
+    destroy: () => void;
+    getName: () => string;
+}
+
+/** Configuration for the sync plugin */
+interface SyncOptions<T extends State> {
+    /** WebSocket server URL (e.g. 'wss://your-server.com/sync') */
+    url: string;
+    /** Channel/room name — clients on the same channel sync state */
+    channel: string;
+    /** Only sync these keys */
+    pick?: (keyof T)[];
+    /** Exclude these keys from sync */
+    omit?: (keyof T)[];
+    /** Throttle outbound messages in ms (default: 50) */
+    throttleMs?: number;
+    /** Auto-reconnect on disconnect (default: true) */
+    reconnect?: boolean;
+    /** Max reconnect attempts (default: Infinity) */
+    maxReconnectAttempts?: number;
+    /** Base reconnect interval in ms, doubles each attempt (default: 1000) */
+    reconnectInterval?: number;
+    /** Max reconnect interval cap in ms (default: 30000) */
+    maxReconnectInterval?: number;
+    /** Called when WebSocket connects */
+    onConnect?: () => void;
+    /** Called when WebSocket disconnects */
+    onDisconnect?: () => void;
+    /** Called on WebSocket or protocol error */
+    onError?: (error: unknown) => void;
+    /** Custom conflict resolver: receives local and remote state, returns merged */
+    resolve?: (localState: T, remoteState: Partial<T>) => Partial<T>;
+}
+/** Client -> Server: join a channel */
+interface JoinMessage {
+    type: 'join';
+    channel: string;
+    clientId: string;
+}
+/** Client -> Server: broadcast state change */
+interface StateMessage {
+    type: 'state';
+    channel: string;
+    clientId: string;
+    state: Record<string, unknown>;
+    timestamp: number;
+}
+/** Server -> Client: full state snapshot (sent on join if server supports it) */
+interface FullStateMessage {
+    type: 'full_state';
+    channel: string;
+    state: Record<string, unknown>;
+    timestamp: number;
+}
+/** All outbound message types */
+type OutboundMessage = JoinMessage | StateMessage;
+/** All inbound message types */
+type InboundMessage = StateMessage | FullStateMessage;
+
+/**
+ * Create a sync plugin that synchronizes bridge state across apps
+ * via WebSocket in real-time.
+ *
+ * @example
+ * ```ts
+ * import { createBridge } from 'shared-state-bridge'
+ * import { sync } from 'shared-state-bridge/sync'
+ *
+ * const bridge = createBridge({
+ *   name: 'app',
+ *   initialState: { theme: 'light', count: 0 },
+ *   plugins: [
+ *     sync({
+ *       url: 'wss://your-server.com/sync',
+ *       channel: 'my-room',
+ *       pick: ['theme'],
+ *     }),
+ *   ],
+ * })
+ * ```
+ */
+declare function sync<T extends State>(options: SyncOptions<T>): BridgePlugin<T>;
+
+interface ConnectionOptions {
+    url: string;
+    reconnect: boolean;
+    maxReconnectAttempts: number;
+    reconnectInterval: number;
+    maxReconnectInterval: number;
+    onMessage: (message: InboundMessage) => void;
+    onConnect: () => void;
+    onDisconnect: () => void;
+    onError: (error: unknown) => void;
+}
+/**
+ * WebSocket connection manager with auto-reconnect and message buffering.
+ *
+ * - Connects to the WebSocket server
+ * - Buffers outbound messages while disconnected
+ * - Flushes buffer on reconnect
+ * - Exponential backoff reconnection (1s, 2s, 4s, 8s... capped)
+ */
+declare class SyncConnection {
+    private ws;
+    private options;
+    private buffer;
+    private reconnectAttempts;
+    private reconnectTimer;
+    private destroyed;
+    private _connected;
+    constructor(options: ConnectionOptions);
+    get connected(): boolean;
+    connect(): void;
+    send(message: OutboundMessage): void;
+    destroy(): void;
+    private createSocket;
+    private flushBuffer;
+    private scheduleReconnect;
+}
+
+export { type FullStateMessage, type InboundMessage, type JoinMessage, type OutboundMessage, type StateMessage, SyncConnection, type SyncOptions, sync };

package/dist/sync.d.ts

@@ -0,0 +1,154 @@
+/** State must be a plain object */
+type State = Record<string, unknown>;
+/** Full-state change listener */
+type Listener<T extends State> = (state: T, previousState: T) => void;
+/** Selector-based change listener */
+type SelectorListener<_T extends State, U> = (slice: U, previousSlice: U) => void;
+/** setState accepts partial updates or an updater function */
+interface SetState<T extends State> {
+    (partial: Partial<T> | ((state: T) => Partial<T>)): void;
+    (state: T | ((state: T) => T), replace: true): void;
+}
+/** Subscribe overloads: full-state or selector-based */
+interface Subscribe<T extends State> {
+    (listener: Listener<T>): () => void;
+    <U>(selector: (state: T) => U, listener: SelectorListener<T, U>, options?: SubscribeOptions<U>): () => void;
+}
+interface SubscribeOptions<U> {
+    equalityFn?: (a: U, b: U) => boolean;
+    fireImmediately?: boolean;
+}
+/** Plugin lifecycle hooks */
+interface BridgePlugin<T extends State> {
+    name: string;
+    onInit?: (bridge: BridgeApi<T>) => void;
+    onStateChange?: (state: T, previousState: T) => void;
+    onDestroy?: () => void;
+}
+/** The bridge instance API */
+interface BridgeApi<T extends State> {
+    getState: () => T;
+    setState: SetState<T>;
+    subscribe: Subscribe<T>;
+    getInitialState: () => T;
+    destroy: () => void;
+    getName: () => string;
+}
+
+/** Configuration for the sync plugin */
+interface SyncOptions<T extends State> {
+    /** WebSocket server URL (e.g. 'wss://your-server.com/sync') */
+    url: string;
+    /** Channel/room name — clients on the same channel sync state */
+    channel: string;
+    /** Only sync these keys */
+    pick?: (keyof T)[];
+    /** Exclude these keys from sync */
+    omit?: (keyof T)[];
+    /** Throttle outbound messages in ms (default: 50) */
+    throttleMs?: number;
+    /** Auto-reconnect on disconnect (default: true) */
+    reconnect?: boolean;
+    /** Max reconnect attempts (default: Infinity) */
+    maxReconnectAttempts?: number;
+    /** Base reconnect interval in ms, doubles each attempt (default: 1000) */
+    reconnectInterval?: number;
+    /** Max reconnect interval cap in ms (default: 30000) */
+    maxReconnectInterval?: number;
+    /** Called when WebSocket connects */
+    onConnect?: () => void;
+    /** Called when WebSocket disconnects */
+    onDisconnect?: () => void;
+    /** Called on WebSocket or protocol error */
+    onError?: (error: unknown) => void;
+    /** Custom conflict resolver: receives local and remote state, returns merged */
+    resolve?: (localState: T, remoteState: Partial<T>) => Partial<T>;
+}
+/** Client -> Server: join a channel */
+interface JoinMessage {
+    type: 'join';
+    channel: string;
+    clientId: string;
+}
+/** Client -> Server: broadcast state change */
+interface StateMessage {
+    type: 'state';
+    channel: string;
+    clientId: string;
+    state: Record<string, unknown>;
+    timestamp: number;
+}
+/** Server -> Client: full state snapshot (sent on join if server supports it) */
+interface FullStateMessage {
+    type: 'full_state';
+    channel: string;
+    state: Record<string, unknown>;
+    timestamp: number;
+}
+/** All outbound message types */
+type OutboundMessage = JoinMessage | StateMessage;
+/** All inbound message types */
+type InboundMessage = StateMessage | FullStateMessage;
+
+/**
+ * Create a sync plugin that synchronizes bridge state across apps
+ * via WebSocket in real-time.
+ *
+ * @example
+ * ```ts
+ * import { createBridge } from 'shared-state-bridge'
+ * import { sync } from 'shared-state-bridge/sync'
+ *
+ * const bridge = createBridge({
+ *   name: 'app',
+ *   initialState: { theme: 'light', count: 0 },
+ *   plugins: [
+ *     sync({
+ *       url: 'wss://your-server.com/sync',
+ *       channel: 'my-room',
+ *       pick: ['theme'],
+ *     }),
+ *   ],
+ * })
+ * ```
+ */
+declare function sync<T extends State>(options: SyncOptions<T>): BridgePlugin<T>;
+
+interface ConnectionOptions {
+    url: string;
+    reconnect: boolean;
+    maxReconnectAttempts: number;
+    reconnectInterval: number;
+    maxReconnectInterval: number;
+    onMessage: (message: InboundMessage) => void;
+    onConnect: () => void;
+    onDisconnect: () => void;
+    onError: (error: unknown) => void;
+}
+/**
+ * WebSocket connection manager with auto-reconnect and message buffering.
+ *
+ * - Connects to the WebSocket server
+ * - Buffers outbound messages while disconnected
+ * - Flushes buffer on reconnect
+ * - Exponential backoff reconnection (1s, 2s, 4s, 8s... capped)
+ */
+declare class SyncConnection {
+    private ws;
+    private options;
+    private buffer;
+    private reconnectAttempts;
+    private reconnectTimer;
+    private destroyed;
+    private _connected;
+    constructor(options: ConnectionOptions);
+    get connected(): boolean;
+    connect(): void;
+    send(message: OutboundMessage): void;
+    destroy(): void;
+    private createSocket;
+    private flushBuffer;
+    private scheduleReconnect;
+}
+
+export { type FullStateMessage, type InboundMessage, type JoinMessage, type OutboundMessage, type StateMessage, SyncConnection, type SyncOptions, sync };

package/dist/sync.js

@@ -0,0 +1,246 @@
+// src/sync/connection.ts
+var SyncConnection = class {
+  constructor(options) {
+    this.ws = null;
+    this.buffer = [];
+    this.reconnectAttempts = 0;
+    this.reconnectTimer = null;
+    this.destroyed = false;
+    this._connected = false;
+    this.options = options;
+  }
+  get connected() {
+    return this._connected;
+  }
+  connect() {
+    if (this.destroyed) return;
+    this.createSocket();
+  }
+  send(message) {
+    const data = JSON.stringify(message);
+    if (this._connected && this.ws?.readyState === WebSocket.OPEN) {
+      this.ws.send(data);
+    } else {
+      this.buffer.push(data);
+    }
+  }
+  destroy() {
+    this.destroyed = true;
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    if (this.ws) {
+      this.ws.onopen = null;
+      this.ws.onclose = null;
+      this.ws.onmessage = null;
+      this.ws.onerror = null;
+      this.ws.close();
+      this.ws = null;
+    }
+    this.buffer = [];
+    this._connected = false;
+  }
+  createSocket() {
+    try {
+      this.ws = new WebSocket(this.options.url);
+    } catch (err) {
+      this.options.onError(err);
+      this.scheduleReconnect();
+      return;
+    }
+    this.ws.onopen = () => {
+      this._connected = true;
+      this.reconnectAttempts = 0;
+      this.flushBuffer();
+      this.options.onConnect();
+    };
+    this.ws.onclose = () => {
+      const wasConnected = this._connected;
+      this._connected = false;
+      if (wasConnected) {
+        this.options.onDisconnect();
+      }
+      this.scheduleReconnect();
+    };
+    this.ws.onerror = (event) => {
+      this.options.onError(event);
+    };
+    this.ws.onmessage = (event) => {
+      try {
+        const message = JSON.parse(
+          typeof event.data === "string" ? event.data : String(event.data)
+        );
+        this.options.onMessage(message);
+      } catch {
+      }
+    };
+  }
+  flushBuffer() {
+    if (!this.ws || this.ws.readyState !== WebSocket.OPEN) return;
+    const messages = this.buffer.splice(0);
+    for (const data of messages) {
+      this.ws.send(data);
+    }
+  }
+  scheduleReconnect() {
+    if (this.destroyed) return;
+    if (!this.options.reconnect) return;
+    if (this.reconnectAttempts >= this.options.maxReconnectAttempts) return;
+    const delay = Math.min(
+      this.options.reconnectInterval * Math.pow(2, this.reconnectAttempts),
+      this.options.maxReconnectInterval
+    );
+    this.reconnectAttempts++;
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null;
+      if (!this.destroyed) {
+        this.createSocket();
+      }
+    }, delay);
+  }
+};
+
+// src/core/utils.ts
+function throttle(fn, intervalMs) {
+  let lastCall = 0;
+  let timeoutId = null;
+  let latestArgs;
+  return (...args) => {
+    latestArgs = args;
+    const now = Date.now();
+    const remaining = intervalMs - (now - lastCall);
+    if (remaining <= 0) {
+      if (timeoutId) {
+        clearTimeout(timeoutId);
+        timeoutId = null;
+      }
+      lastCall = now;
+      fn(...latestArgs);
+    } else if (!timeoutId) {
+      timeoutId = setTimeout(() => {
+        lastCall = Date.now();
+        timeoutId = null;
+        fn(...latestArgs);
+      }, remaining);
+    }
+  };
+}
+
+// src/sync/plugin.ts
+function generateClientId() {
+  return Math.random().toString(36).slice(2) + Date.now().toString(36);
+}
+function sync(options) {
+  const {
+    url,
+    channel,
+    pick,
+    omit,
+    throttleMs = 50,
+    reconnect = true,
+    maxReconnectAttempts = Infinity,
+    reconnectInterval = 1e3,
+    maxReconnectInterval = 3e4,
+    onConnect,
+    onDisconnect,
+    onError,
+    resolve
+  } = options;
+  const clientId = generateClientId();
+  let connection = null;
+  let bridge = null;
+  let sendState = null;
+  let isApplyingRemote = false;
+  function filterState(state) {
+    if (pick) {
+      const filtered = {};
+      for (const k of pick) {
+        if (k in state) {
+          filtered[k] = state[k];
+        }
+      }
+      return filtered;
+    }
+    if (omit) {
+      const filtered = { ...state };
+      for (const k of omit) {
+        delete filtered[k];
+      }
+      return filtered;
+    }
+    return state;
+  }
+  return {
+    name: "sync",
+    onInit: (bridgeApi) => {
+      bridge = bridgeApi;
+      sendState = throttle((state) => {
+        if (!connection) return;
+        const filtered = filterState(state);
+        connection.send({
+          type: "state",
+          channel,
+          clientId,
+          state: filtered,
+          timestamp: Date.now()
+        });
+      }, throttleMs);
+      connection = new SyncConnection({
+        url,
+        reconnect,
+        maxReconnectAttempts,
+        reconnectInterval,
+        maxReconnectInterval,
+        onConnect: () => {
+          connection.send({
+            type: "join",
+            channel,
+            clientId
+          });
+          onConnect?.();
+        },
+        onDisconnect: () => {
+          onDisconnect?.();
+        },
+        onError: (err) => {
+          onError?.(err);
+        },
+        onMessage: (message) => {
+          if (!bridge) return;
+          if ("clientId" in message && message.clientId === clientId) return;
+          if (message.type === "state" || message.type === "full_state") {
+            const remoteState = message.state;
+            let stateToApply;
+            if (resolve) {
+              stateToApply = resolve(bridge.getState(), remoteState);
+            } else {
+              stateToApply = remoteState;
+            }
+            isApplyingRemote = true;
+            try {
+              bridge.setState(stateToApply);
+            } finally {
+              isApplyingRemote = false;
+            }
+          }
+        }
+      });
+      connection.connect();
+    },
+    onStateChange: (state) => {
+      if (isApplyingRemote) return;
+      sendState?.(state);
+    },
+    onDestroy: () => {
+      connection?.destroy();
+      connection = null;
+      bridge = null;
+      sendState = null;
+    }
+  };
+}
+
+export { SyncConnection, sync };
+//# sourceMappingURL=sync.js.map
+//# sourceMappingURL=sync.js.map

package/dist/sync.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/sync/connection.ts","../src/core/utils.ts","../src/sync/plugin.ts"],"names":[],"mappings":"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","file":"sync.js","sourcesContent":["import type { OutboundMessage, InboundMessage } from './types'\n\nexport interface ConnectionOptions {\n  url: string\n  reconnect: boolean\n  maxReconnectAttempts: number\n  reconnectInterval: number\n  maxReconnectInterval: number\n  onMessage: (message: InboundMessage) => void\n  onConnect: () => void\n  onDisconnect: () => void\n  onError: (error: unknown) => void\n}\n\n/**\n * WebSocket connection manager with auto-reconnect and message buffering.\n *\n * - Connects to the WebSocket server\n * - Buffers outbound messages while disconnected\n * - Flushes buffer on reconnect\n * - Exponential backoff reconnection (1s, 2s, 4s, 8s... capped)\n */\nexport class SyncConnection {\n  private ws: WebSocket | null = null\n  private options: ConnectionOptions\n  private buffer: string[] = []\n  private reconnectAttempts = 0\n  private reconnectTimer: ReturnType<typeof setTimeout> | null = null\n  private destroyed = false\n  private _connected = false\n\n  constructor(options: ConnectionOptions) {\n    this.options = options\n  }\n\n  get connected(): boolean {\n    return this._connected\n  }\n\n  connect(): void {\n    if (this.destroyed) return\n    this.createSocket()\n  }\n\n  send(message: OutboundMessage): void {\n    const data = JSON.stringify(message)\n    if (this._connected && this.ws?.readyState === WebSocket.OPEN) {\n      this.ws.send(data)\n    } else {\n      this.buffer.push(data)\n    }\n  }\n\n  destroy(): void {\n    this.destroyed = true\n    if (this.reconnectTimer) {\n      clearTimeout(this.reconnectTimer)\n      this.reconnectTimer = null\n    }\n    if (this.ws) {\n      this.ws.onopen = null\n      this.ws.onclose = null\n      this.ws.onmessage = null\n      this.ws.onerror = null\n      this.ws.close()\n      this.ws = null\n    }\n    this.buffer = []\n    this._connected = false\n  }\n\n  private createSocket(): void {\n    try {\n      this.ws = new WebSocket(this.options.url)\n    } catch (err) {\n      this.options.onError(err)\n      this.scheduleReconnect()\n      return\n    }\n\n    this.ws.onopen = () => {\n      this._connected = true\n      this.reconnectAttempts = 0\n      this.flushBuffer()\n      this.options.onConnect()\n    }\n\n    this.ws.onclose = () => {\n      const wasConnected = this._connected\n      this._connected = false\n      if (wasConnected) {\n        this.options.onDisconnect()\n      }\n      this.scheduleReconnect()\n    }\n\n    this.ws.onerror = (event) => {\n      this.options.onError(event)\n    }\n\n    this.ws.onmessage = (event) => {\n      try {\n        const message = JSON.parse(\n          typeof event.data === 'string' ? event.data : String(event.data),\n        ) as InboundMessage\n        this.options.onMessage(message)\n      } catch {\n        // Ignore malformed messages\n      }\n    }\n  }\n\n  private flushBuffer(): void {\n    if (!this.ws || this.ws.readyState !== WebSocket.OPEN) return\n    const messages = this.buffer.splice(0)\n    for (const data of messages) {\n      this.ws.send(data)\n    }\n  }\n\n  private scheduleReconnect(): void {\n    if (this.destroyed) return\n    if (!this.options.reconnect) return\n    if (this.reconnectAttempts >= this.options.maxReconnectAttempts) return\n\n    const delay = Math.min(\n      this.options.reconnectInterval * Math.pow(2, this.reconnectAttempts),\n      this.options.maxReconnectInterval,\n    )\n    this.reconnectAttempts++\n\n    this.reconnectTimer = setTimeout(() => {\n      this.reconnectTimer = null\n      if (!this.destroyed) {\n        this.createSocket()\n      }\n    }, delay)\n  }\n}\n","/**\n * Shallow equality comparison for objects.\n * Returns true if both arguments have the same keys with Object.is-equal values.\n */\nexport function shallowEqual<T>(a: T, b: T): boolean {\n  if (Object.is(a, b)) return true\n  if (typeof a !== 'object' || typeof b !== 'object') return false\n  if (a === null || b === null) return false\n\n  const keysA = Object.keys(a as object)\n  const keysB = Object.keys(b as object)\n\n  if (keysA.length !== keysB.length) return false\n\n  for (const key of keysA) {\n    if (\n      !Object.prototype.hasOwnProperty.call(b, key) ||\n      !Object.is(\n        (a as Record<string, unknown>)[key],\n        (b as Record<string, unknown>)[key],\n      )\n    ) {\n      return false\n    }\n  }\n\n  return true\n}\n\n/** Type guard for functions */\nexport function isFunction(value: unknown): value is (...args: unknown[]) => unknown {\n  return typeof value === 'function'\n}\n\n/**\n * Throttle function execution. Executes at most once per intervalMs.\n * Trailing calls are preserved (the last call during a throttle window\n * will fire after the interval).\n */\nexport function throttle<T extends (...args: never[]) => void>(\n  fn: T,\n  intervalMs: number,\n): ((...args: Parameters<T>) => void) {\n  let lastCall = 0\n  let timeoutId: ReturnType<typeof setTimeout> | null = null\n  let latestArgs: Parameters<T>\n\n  return (...args: Parameters<T>) => {\n    latestArgs = args\n    const now = Date.now()\n    const remaining = intervalMs - (now - lastCall)\n\n    if (remaining <= 0) {\n      if (timeoutId) {\n        clearTimeout(timeoutId)\n        timeoutId = null\n      }\n      lastCall = now\n      fn(...latestArgs)\n    } else if (!timeoutId) {\n      timeoutId = setTimeout(() => {\n        lastCall = Date.now()\n        timeoutId = null\n        fn(...latestArgs)\n      }, remaining)\n    }\n  }\n}\n","import type { State, BridgePlugin, BridgeApi } from '../core/types'\nimport type { SyncOptions } from './types'\nimport { SyncConnection } from './connection'\nimport { throttle } from '../core/utils'\n\n/**\n * Generate a random client ID for echo prevention.\n */\nfunction generateClientId(): string {\n  return Math.random().toString(36).slice(2) + Date.now().toString(36)\n}\n\n/**\n * Create a sync plugin that synchronizes bridge state across apps\n * via WebSocket in real-time.\n *\n * @example\n * ```ts\n * import { createBridge } from 'shared-state-bridge'\n * import { sync } from 'shared-state-bridge/sync'\n *\n * const bridge = createBridge({\n *   name: 'app',\n *   initialState: { theme: 'light', count: 0 },\n *   plugins: [\n *     sync({\n *       url: 'wss://your-server.com/sync',\n *       channel: 'my-room',\n *       pick: ['theme'],\n *     }),\n *   ],\n * })\n * ```\n */\nexport function sync<T extends State>(options: SyncOptions<T>): BridgePlugin<T> {\n  const {\n    url,\n    channel,\n    pick,\n    omit,\n    throttleMs = 50,\n    reconnect = true,\n    maxReconnectAttempts = Infinity,\n    reconnectInterval = 1000,\n    maxReconnectInterval = 30000,\n    onConnect,\n    onDisconnect,\n    onError,\n    resolve,\n  } = options\n\n  const clientId = generateClientId()\n  let connection: SyncConnection | null = null\n  let bridge: BridgeApi<T> | null = null\n  let sendState: ((state: T) => void) | null = null\n\n  // Guard: when true, we are applying a remote state update.\n  // onStateChange should NOT broadcast while this is true (echo prevention).\n  let isApplyingRemote = false\n\n  /**\n   * Filter state keys based on pick/omit options.\n   * Same pattern as the persist plugin.\n   */\n  function filterState(state: T): Partial<T> {\n    if (pick) {\n      const filtered: Partial<T> = {}\n      for (const k of pick) {\n        if (k in state) {\n          filtered[k] = state[k]\n        }\n      }\n      return filtered\n    }\n    if (omit) {\n      const filtered = { ...state }\n      for (const k of omit) {\n        delete filtered[k]\n      }\n      return filtered\n    }\n    return state\n  }\n\n  return {\n    name: 'sync',\n\n    onInit: (bridgeApi: BridgeApi<T>) => {\n      bridge = bridgeApi\n\n      // Set up throttled send function\n      sendState = throttle((state: T) => {\n        if (!connection) return\n        const filtered = filterState(state)\n        connection.send({\n          type: 'state',\n          channel,\n          clientId,\n          state: filtered as Record<string, unknown>,\n          timestamp: Date.now(),\n        })\n      }, throttleMs)\n\n      // Create WebSocket connection\n      connection = new SyncConnection({\n        url,\n        reconnect,\n        maxReconnectAttempts,\n        reconnectInterval,\n        maxReconnectInterval,\n\n        onConnect: () => {\n          // Join the channel\n          connection!.send({\n            type: 'join',\n            channel,\n            clientId,\n          })\n          onConnect?.()\n        },\n\n        onDisconnect: () => {\n          onDisconnect?.()\n        },\n\n        onError: (err) => {\n          onError?.(err)\n        },\n\n        onMessage: (message) => {\n          if (!bridge) return\n\n          // Echo prevention: skip messages from ourselves\n          if ('clientId' in message && message.clientId === clientId) return\n\n          if (message.type === 'state' || message.type === 'full_state') {\n            const remoteState = message.state as Partial<T>\n\n            let stateToApply: Partial<T>\n\n            if (resolve) {\n              // Custom conflict resolution\n              stateToApply = resolve(bridge.getState(), remoteState)\n            } else {\n              // Default: last-write-wins — just merge remote state\n              stateToApply = remoteState\n            }\n\n            // Apply remote state with echo guard\n            isApplyingRemote = true\n            try {\n              bridge.setState(stateToApply)\n            } finally {\n              isApplyingRemote = false\n            }\n          }\n        },\n      })\n\n      connection.connect()\n    },\n\n    onStateChange: (state: T) => {\n      // Don't broadcast if we're applying a remote update (echo prevention)\n      if (isApplyingRemote) return\n      sendState?.(state)\n    },\n\n    onDestroy: () => {\n      connection?.destroy()\n      connection = null\n      bridge = null\n      sendState = null\n    },\n  }\n}\n"]}

package/package.json

@@ -0,0 +1,103 @@
+{
+  "name": "shared-state-bridge",
+  "version": "1.0.0",
+  "description": "Lightweight shared state bridge for monorepo apps — sync state across packages with TypeScript, React hooks, and optional persistence",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./react": {
+      "import": {
+        "types": "./dist/react.d.ts",
+        "default": "./dist/react.js"
+      },
+      "require": {
+        "types": "./dist/react.d.cts",
+        "default": "./dist/react.cjs"
+      }
+    },
+    "./persist": {
+      "import": {
+        "types": "./dist/persist.d.ts",
+        "default": "./dist/persist.js"
+      },
+      "require": {
+        "types": "./dist/persist.d.cts",
+        "default": "./dist/persist.cjs"
+      }
+    },
+    "./sync": {
+      "import": {
+        "types": "./dist/sync.d.ts",
+        "default": "./dist/sync.js"
+      },
+      "require": {
+        "types": "./dist/sync.d.cts",
+        "default": "./dist/sync.cjs"
+      }
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.1.0",
+    "@types/node": "^25.2.3",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "jsdom": "^25.0.1",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  },
+  "keywords": [
+    "state-management",
+    "monorepo",
+    "shared-state",
+    "react",
+    "react-native",
+    "turborepo",
+    "nx",
+    "cross-package",
+    "typescript",
+    "hooks",
+    "state-bridge",
+    "websocket",
+    "real-time",
+    "sync"
+  ]
+}