pg-sse 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kenrick Tandrian
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,209 @@
+# pg-sse
+
+Real-Time PostgreSQL Subscriptions for Next.js & React via Server-Sent Events (SSE). Zero external dependencies. Zero vendor lock-in.
+
+## Features
+
+- **Zero SaaS Dependencies:** Runs entirely in-process on your standard PostgreSQL and Next.js / Node.js backend. No Pusher, Ably, or Supabase lock-in required.
+- **Database Pool Protection:** Multiplexes all incoming client streams into exactly **one** PostgreSQL connection per Node.js process using `LISTEN`/`NOTIFY`.
+- **Browser Tab Multiplexing:** Restricts active event streams to exactly **one** socket connection per browser, sharing events across sibling tabs using `BroadcastChannel` with automated leader election.
+- **Resilient Reconnection:** Native retry mechanism featuring exponential backoff and randomized jitter to prevent thundering herd scenarios when backend instances recycle.
+- **Type-Safe:** Written in 100% type-safe TypeScript.
+
+## Installation
+
+```bash
+pnpm add pg-sse pg
+# or
+npm install pg-sse pg
+# or
+yarn add pg-sse pg
+```
+
+Make sure you have standard peer dependencies installed (`pg`, `react`, and `react-dom`).
+
+## Step-by-Step Setup Guide
+
+### 1. Database Setup: PostgreSQL Triggers
+
+Add a trigger function to your PostgreSQL database to dispatch notify payloads whenever records change.
+
+```sql
+-- Create trigger function that serializes table actions to JSON
+CREATE OR REPLACE FUNCTION notify_table_update()
+RETURNS trigger AS $$
+BEGIN
+  PERFORM pg_notify(
+    'db_changes',
+    json_build_object(
+      'table', TG_TABLE_NAME,
+      'action', TG_OP,
+      'id', COALESCE(NEW.id, OLD.id)
+    )::text
+  );
+  RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+-- Attach the trigger to your tables (e.g. users)
+CREATE TRIGGER users_update_trigger
+AFTER INSERT OR UPDATE OR DELETE ON users
+FOR EACH ROW EXECUTE FUNCTION notify_table_update();
+```
+
+### 2. Server Setup: PostgreSQL Listener
+
+Initialize the `PostgresSseListener` instance exactly **once** in your Node.js server to start listening to PostgreSQL events.
+
+```typescript
+// lib/pg-listener.ts
+import { PostgresSseListener } from "pg-sse/server";
+
+// Ensure a single persistent instance in Next.js development hot-reloads
+const globalForPgSse = globalThis as unknown as {
+  pgListener?: PostgresSseListener;
+};
+
+export const pgListener =
+  globalForPgSse.pgListener ??
+  new PostgresSseListener(
+    {
+      connectionString: process.env.DATABASE_URL,
+    },
+    "db_changes",
+  );
+
+if (process.env.NODE_ENV !== "production") {
+  globalForPgSse.pgListener = pgListener;
+}
+
+// Start listening (returns promise, handles auto-reconnections internally)
+pgListener.connect();
+```
+
+### 3. Server Setup: Next.js API Route Handler
+
+Create a Next.js App Router Route Handler to stream events. Pass the `pgListener` and the incoming `Request` to the helper.
+
+```typescript
+// app/api/sse/route.ts
+import { createSseHandler } from "pg-sse/server";
+import { pgListener } from "@/lib/pg-listener";
+
+export async function GET(req: Request) {
+  // Option: Execute authentication or access validation here before streaming
+
+  return createSseHandler(pgListener, req);
+}
+```
+
+### 4. Client Setup: React Provider
+
+Wrap your application in the `SseProvider` to establish connection state.
+
+```tsx
+// app/layout.tsx
+import { SseProvider } from "pg-sse/client";
+
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <html lang="en">
+      <body>
+        <SseProvider endpoint="/api/sse">{children}</SseProvider>
+      </body>
+    </html>
+  );
+}
+```
+
+### 5. Client Setup: Component Subscriptions
+
+Use the `useSubscription` hook in Client Components to bind event handlers to database updates.
+
+```tsx
+// app/components/UserList.tsx
+"use client";
+
+import { useState } from "react";
+import { useSubscription } from "pg-sse/client";
+import { useRouter } from "next/navigation";
+
+interface UserUpdatePayload {
+  table: string;
+  action: "INSERT" | "UPDATE" | "DELETE";
+  id: number;
+}
+
+export function UserList() {
+  const router = useRouter();
+
+  // Listen to PostgreSQL updates on the "users" table
+  useSubscription<UserUpdatePayload>("users", (payload) => {
+    console.log(
+      `Database updated on table ${payload.table} (ID: ${payload.id})`,
+    );
+
+    // Automatically trigger Server Component page data revalidation
+    router.refresh();
+  });
+
+  return (
+    <div>
+      <h3>Live Users Directory</h3>
+      {/* Directory content rendered server-side */}
+    </div>
+  );
+}
+```
+
+## 🔒 Security Best Practice: The Thin Event Pattern
+
+PostgreSQL notification payloads have a standard size limit of **8000 bytes**. To guarantee security and scalability, you should use the **Thin Event** pattern:
+
+1. **Do not** serialize sensitive rows or rich columns (like emails, password hashes, or messages) directly into the PostgreSQL notification trigger.
+2. **Do** only serialize identifiers and actions:
+   ```json
+   { "table": "users", "action": "UPDATE", "id": 123 }
+   ```
+3. When the client receives the update notification, query the actual data details through standard, authenticated server endpoints (such as Next.js Server Actions or API routes) where access control lists (ACLs) are strictly enforced.
+
+## API Reference
+
+### Server Side (`pg-sse/server`)
+
+#### `PostgresSseListener(config, channels)`
+
+Initializes a new DB event listener.
+
+- `config`: A `pg.ClientConfig` object or connection string.
+- `channels` (optional): Channel string or array of channel strings. Defaults to `"db_changes"`.
+
+#### `createSseHandler(listener, request)`
+
+Generates an SSE stream Response compatible with standard edge and Node.js runtimes.
+
+- `listener`: The active `PostgresSseListener` instance.
+- `request` (optional): Incoming Fetch `Request` object. When provided, registers abort listeners to unregister client registry entries instantly on connection loss.
+
+### Client Side (`pg-sse/client`)
+
+#### `<SseProvider endpoint="...">`
+
+Creates the context state and initiates leader election for tab multiplexing.
+
+- `endpoint`: The string API route endpoint URL.
+
+#### `useSubscription<T>(table, callback)`
+
+Registers a component callback for real-time table notifications.
+
+- `table`: The string table name to subscribe to.
+- `callback`: `(payload: T) => void` triggered when a matching database notification fires.
+
+## License
+
+MIT

package/dist/chunk-GFLW4AMU.mjs

@@ -0,0 +1,323 @@
+"use client";
+
+// src/client/provider.tsx
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useRef,
+  useState
+} from "react";
+
+// src/client/multiplexer.ts
+var TabMultiplexer = class {
+  constructor(endpoint, onEvent, onStatusChange) {
+    this.endpoint = endpoint;
+    this.onEvent = onEvent;
+    this.onStatusChange = onStatusChange;
+    this.tabId = Math.random().toString(36).substring(2, 11);
+    if (typeof window !== "undefined" && typeof BroadcastChannel !== "undefined") {
+      this.channel = new BroadcastChannel("pg-sse-multiplexer-channel");
+      this.channel.onmessage = (event) => this.handleChannelMessage(event.data);
+      window.addEventListener("beforeunload", () => this.destroy());
+      this.resetWatchdog(1500);
+      this.broadcast({ type: "query_leader", senderId: this.tabId });
+    } else {
+      this.startDirectConnection();
+    }
+  }
+  endpoint;
+  onEvent;
+  onStatusChange;
+  channel = null;
+  tabId;
+  isLeader = false;
+  leaderId = null;
+  status = "disconnected";
+  heartbeatInterval = null;
+  watchdogTimeout = null;
+  electionTimeout = null;
+  eventSource = null;
+  claimInProgress = false;
+  destroy() {
+    const wasLeader = this.isLeader;
+    this.isLeader = false;
+    if (wasLeader) {
+      this.broadcast({ type: "release", senderId: this.tabId });
+    }
+    if (this.heartbeatInterval) clearInterval(this.heartbeatInterval);
+    if (this.watchdogTimeout) clearTimeout(this.watchdogTimeout);
+    if (this.electionTimeout) clearTimeout(this.electionTimeout);
+    this.stopEventSource();
+    if (this.channel) {
+      this.channel.close();
+      this.channel = null;
+    }
+  }
+  broadcast(msg) {
+    if (this.channel) {
+      try {
+        this.channel.postMessage(msg);
+      } catch (e) {
+      }
+    }
+  }
+  handleChannelMessage(msg) {
+    if (msg.senderId === this.tabId) return;
+    switch (msg.type) {
+      case "query_leader":
+        if (this.isLeader) {
+          this.sendHeartbeat();
+        }
+        break;
+      case "heartbeat":
+        this.claimInProgress = false;
+        if (this.electionTimeout) {
+          clearTimeout(this.electionTimeout);
+          this.electionTimeout = null;
+        }
+        this.leaderId = msg.senderId;
+        this.resetWatchdog(5e3);
+        break;
+      case "claim":
+        if (this.isLeader) {
+          this.sendHeartbeat();
+        } else if (this.claimInProgress) {
+          if (msg.senderId < this.tabId) {
+            this.claimInProgress = false;
+            if (this.electionTimeout) {
+              clearTimeout(this.electionTimeout);
+              this.electionTimeout = null;
+            }
+          }
+        }
+        break;
+      case "release":
+        if (this.leaderId === msg.senderId) {
+          this.leaderId = null;
+          this.attemptLeadershipClaim();
+        }
+        break;
+      case "status":
+        if (!this.isLeader && this.leaderId === msg.senderId) {
+          const payloadObj = msg.payload;
+          this.status = payloadObj.status;
+          this.onStatusChange(this.status, payloadObj.activeConnections);
+        }
+        break;
+      case "event":
+        if (!this.isLeader && this.leaderId === msg.senderId) {
+          const payloadObj = msg.payload;
+          this.onEvent(payloadObj.event, payloadObj.data);
+        }
+        break;
+    }
+  }
+  resetWatchdog(ms) {
+    if (this.watchdogTimeout) clearTimeout(this.watchdogTimeout);
+    this.watchdogTimeout = setTimeout(() => {
+      this.attemptLeadershipClaim();
+    }, ms);
+  }
+  attemptLeadershipClaim() {
+    if (this.isLeader || this.claimInProgress) return;
+    this.claimInProgress = true;
+    this.broadcast({ type: "claim", senderId: this.tabId });
+    this.electionTimeout = setTimeout(() => {
+      this.electionTimeout = null;
+      if (this.claimInProgress) {
+        this.claimInProgress = false;
+        this.becomeLeader();
+      }
+    }, 500);
+  }
+  becomeLeader() {
+    this.isLeader = true;
+    this.leaderId = this.tabId;
+    if (this.watchdogTimeout) {
+      clearTimeout(this.watchdogTimeout);
+      this.watchdogTimeout = null;
+    }
+    this.sendHeartbeat();
+    this.heartbeatInterval = setInterval(() => this.sendHeartbeat(), 2e3);
+    this.startEventSource();
+  }
+  sendHeartbeat() {
+    this.broadcast({ type: "heartbeat", senderId: this.tabId });
+  }
+  updateStatus(newStatus, activeConnections = 0) {
+    this.status = newStatus;
+    this.onStatusChange(newStatus, activeConnections);
+    if (this.isLeader) {
+      this.broadcast({
+        type: "status",
+        senderId: this.tabId,
+        payload: { status: newStatus, activeConnections }
+      });
+    }
+  }
+  startEventSource() {
+    this.stopEventSource();
+    this.updateStatus("connecting");
+    try {
+      this.eventSource = new EventSource(this.endpoint);
+      this.eventSource.addEventListener("handshake", (e) => {
+        try {
+          const data = JSON.parse(e.data);
+          this.updateStatus("connected", data.activeConnections || 1);
+        } catch (err) {
+          this.updateStatus("connected", 1);
+        }
+      });
+      this.eventSource.addEventListener("notification", (e) => {
+        try {
+          const data = JSON.parse(e.data);
+          this.onEvent("notification", data);
+          this.broadcast({
+            type: "event",
+            senderId: this.tabId,
+            payload: { event: "notification", data }
+          });
+        } catch (err) {
+        }
+      });
+      this.eventSource.onerror = () => {
+        this.updateStatus("connecting");
+      };
+    } catch (err) {
+      this.updateStatus("disconnected");
+    }
+  }
+  startDirectConnection() {
+    this.startEventSource();
+  }
+  stopEventSource() {
+    if (this.eventSource) {
+      this.eventSource.close();
+      this.eventSource = null;
+    }
+  }
+};
+
+// src/client/provider.tsx
+import { jsx } from "react/jsx-runtime";
+var SseContext = createContext(null);
+var SseProvider = ({ children, endpoint }) => {
+  const [status, setStatus] = useState("disconnected");
+  const [eventCount, setEventCount] = useState(0);
+  const [activeConnections, setActiveConnections] = useState(0);
+  const subscriptions = useRef(
+    /* @__PURE__ */ new Map()
+  );
+  const handleStatusChange = useCallback(
+    (newStatus, activeCount) => {
+      setActiveConnections(activeCount);
+      setStatus((prev) => {
+        if (newStatus === "connecting") {
+          if (prev === "connected") {
+            console.warn(`[pg-sse] Stream connection lost. Reconnecting...`);
+          } else if (prev === "disconnected") {
+            console.log(`[pg-sse] Connecting to stream...`);
+          }
+        } else if (newStatus === "connected" && prev !== "connected") {
+          console.log(
+            `[pg-sse] Stream connected. Active client count: ${activeCount}`
+          );
+        }
+        return newStatus;
+      });
+    },
+    []
+  );
+  const handleEvent = useCallback((event, payload) => {
+    if (event === "notification") {
+      setEventCount((prev) => prev + 1);
+      const table = payload?.table;
+      if (table) {
+        const callbacks = subscriptions.current.get(table);
+        if (callbacks) {
+          callbacks.forEach((cb) => {
+            try {
+              cb(payload);
+            } catch (err) {
+              console.error(
+                `[pg-sse] Callback for table "${table}" failed:`,
+                err
+              );
+            }
+          });
+        }
+      }
+    }
+  }, []);
+  useEffect(() => {
+    const multiplexer = new TabMultiplexer(
+      endpoint,
+      handleEvent,
+      handleStatusChange
+    );
+    return () => {
+      multiplexer.destroy();
+    };
+  }, [endpoint, handleEvent, handleStatusChange]);
+  const subscribe = useCallback(
+    (table, callback) => {
+      let callbacks = subscriptions.current.get(table);
+      if (!callbacks) {
+        callbacks = /* @__PURE__ */ new Set();
+        subscriptions.current.set(table, callbacks);
+      }
+      callbacks.add(callback);
+      return () => {
+        const callbacks2 = subscriptions.current.get(table);
+        if (callbacks2) {
+          callbacks2.delete(callback);
+          if (callbacks2.size === 0) {
+            subscriptions.current.delete(table);
+          }
+        }
+      };
+    },
+    []
+  );
+  return /* @__PURE__ */ jsx(
+    SseContext.Provider,
+    {
+      value: { subscribe, status, eventCount, activeConnections },
+      children
+    }
+  );
+};
+function useSubscription(table, callback) {
+  const context = useContext(SseContext);
+  if (!context) {
+    throw new Error("useSubscription must be used within an SseProvider");
+  }
+  const { subscribe } = context;
+  const callbackRef = useRef(callback);
+  useEffect(() => {
+    callbackRef.current = callback;
+  }, [callback]);
+  useEffect(() => {
+    const unsubscribe = subscribe(table, (payload) => {
+      callbackRef.current(payload);
+    });
+    return unsubscribe;
+  }, [table, subscribe]);
+}
+function useSseStatus() {
+  const context = useContext(SseContext);
+  if (!context) {
+    throw new Error("useSseStatus must be used within an SseProvider");
+  }
+  const { status, eventCount, activeConnections } = context;
+  return { status, eventCount, activeConnections };
+}
+
+export {
+  SseProvider,
+  useSubscription,
+  useSseStatus
+};
+//# sourceMappingURL=chunk-GFLW4AMU.mjs.map

package/dist/chunk-GFLW4AMU.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/client/provider.tsx","../src/client/multiplexer.ts"],"sourcesContent":["\"use client\";\n\nimport React, {\n  createContext,\n  useCallback,\n  useContext,\n  useEffect,\n  useRef,\n  useState,\n} from \"react\";\nimport { ConnectionStatus, TabMultiplexer } from \"./multiplexer\";\n\nexport interface SseContextType {\n  subscribe: <T = unknown>(\n    table: string,\n    callback: (payload: T) => void,\n  ) => () => void;\n  status: ConnectionStatus;\n  eventCount: number;\n  activeConnections: number;\n}\n\nconst SseContext = createContext<SseContextType | null>(null);\n\nexport const SseProvider: React.FC<{\n  children: React.ReactNode;\n  endpoint: string;\n}> = ({ children, endpoint }) => {\n  const [status, setStatus] = useState<ConnectionStatus>(\"disconnected\");\n  const [eventCount, setEventCount] = useState(0);\n  const [activeConnections, setActiveConnections] = useState(0);\n\n  // Keep subscriptions in a ref to avoid triggering re-renders on subscription updates\n  const subscriptions = useRef<Map<string, Set<(payload: unknown) => void>>>(\n    new Map(),\n  );\n\n  // Handle status and active connection count updates\n  const handleStatusChange = useCallback(\n    (newStatus: ConnectionStatus, activeCount: number) => {\n      setActiveConnections(activeCount);\n      setStatus((prev) => {\n        if (newStatus === \"connecting\") {\n          if (prev === \"connected\") {\n            console.warn(`[pg-sse] Stream connection lost. Reconnecting...`);\n          } else if (prev === \"disconnected\") {\n            console.log(`[pg-sse] Connecting to stream...`);\n          }\n        } else if (newStatus === \"connected\" && prev !== \"connected\") {\n          console.log(\n            `[pg-sse] Stream connected. Active client count: ${activeCount}`,\n          );\n        }\n        return newStatus;\n      });\n    },\n    [],\n  );\n\n  // Dispatch events to matching subscribers\n  const handleEvent = useCallback((event: string, payload: unknown) => {\n    if (event === \"notification\") {\n      setEventCount((prev) => prev + 1);\n\n      const table = (payload as Record<string, unknown> | null)?.table as\n        | string\n        | undefined;\n      if (table) {\n        const callbacks = subscriptions.current.get(table);\n        if (callbacks) {\n          callbacks.forEach((cb) => {\n            try {\n              cb(payload);\n            } catch (err) {\n              console.error(\n                `[pg-sse] Callback for table \"${table}\" failed:`,\n                err,\n              );\n            }\n          });\n        }\n      }\n    }\n  }, []);\n\n  useEffect(() => {\n    const multiplexer = new TabMultiplexer(\n      endpoint,\n      handleEvent,\n      handleStatusChange,\n    );\n\n    return () => {\n      multiplexer.destroy();\n    };\n  }, [endpoint, handleEvent, handleStatusChange]);\n\n  const subscribe = useCallback(\n    <T = unknown,>(table: string, callback: (payload: T) => void) => {\n      let callbacks = subscriptions.current.get(table);\n      if (!callbacks) {\n        callbacks = new Set();\n        subscriptions.current.set(table, callbacks);\n      }\n      callbacks.add(callback as (payload: unknown) => void);\n\n      return () => {\n        const callbacks = subscriptions.current.get(table);\n        if (callbacks) {\n          callbacks.delete(callback as (payload: unknown) => void);\n          if (callbacks.size === 0) {\n            subscriptions.current.delete(table);\n          }\n        }\n      };\n    },\n    [],\n  );\n\n  return (\n    <SseContext.Provider\n      value={{ subscribe, status, eventCount, activeConnections }}\n    >\n      {children}\n    </SseContext.Provider>\n  );\n};\n\nexport function useSubscription<T = unknown>(\n  table: string,\n  callback: (payload: T) => void,\n): void {\n  const context = useContext(SseContext);\n  if (!context) {\n    throw new Error(\"useSubscription must be used within an SseProvider\");\n  }\n\n  const { subscribe } = context;\n  const callbackRef = useRef(callback);\n\n  // Keep callback ref updated so subscription doesn't re-subscribe on every callback changes\n  useEffect(() => {\n    callbackRef.current = callback;\n  }, [callback]);\n\n  useEffect(() => {\n    const unsubscribe = subscribe<T>(table, (payload) => {\n      callbackRef.current(payload);\n    });\n    return unsubscribe;\n  }, [table, subscribe]);\n}\n\nexport function useSseStatus(): {\n  status: ConnectionStatus;\n  eventCount: number;\n  activeConnections: number;\n} {\n  const context = useContext(SseContext);\n  if (!context) {\n    throw new Error(\"useSseStatus must be used within an SseProvider\");\n  }\n  const { status, eventCount, activeConnections } = context;\n  return { status, eventCount, activeConnections };\n}\n","export type ConnectionStatus = \"connecting\" | \"connected\" | \"disconnected\";\n\nexport interface MultiplexerMessage {\n  type: \"query_leader\" | \"heartbeat\" | \"claim\" | \"release\" | \"status\" | \"event\";\n  senderId: string;\n  payload?: unknown;\n}\n\nexport class TabMultiplexer {\n  private channel: BroadcastChannel | null = null;\n  private tabId: string;\n  private isLeader = false;\n  private leaderId: string | null = null;\n  private status: ConnectionStatus = \"disconnected\";\n\n  private heartbeatInterval: NodeJS.Timeout | null = null;\n  private watchdogTimeout: NodeJS.Timeout | null = null;\n  private electionTimeout: NodeJS.Timeout | null = null;\n  private eventSource: EventSource | null = null;\n\n  private claimInProgress = false;\n\n  constructor(\n    private endpoint: string,\n    private onEvent: (event: string, payload: unknown) => void,\n    private onStatusChange: (\n      status: ConnectionStatus,\n      activeConnections: number,\n    ) => void,\n  ) {\n    this.tabId = Math.random().toString(36).substring(2, 11);\n\n    if (\n      typeof window !== \"undefined\" &&\n      typeof BroadcastChannel !== \"undefined\"\n    ) {\n      this.channel = new BroadcastChannel(\"pg-sse-multiplexer-channel\");\n      this.channel.onmessage = (event) => this.handleChannelMessage(event.data);\n\n      // Hook window unload to release leadership if we close\n      window.addEventListener(\"beforeunload\", () => this.destroy());\n\n      // Start a watchdog to claim leadership if no leader responds in 1.5 seconds\n      this.resetWatchdog(1500);\n\n      // Query if there is an existing leader\n      this.broadcast({ type: \"query_leader\", senderId: this.tabId });\n    } else {\n      // Fallback for non-browser or environments without BroadcastChannel\n      this.startDirectConnection();\n    }\n  }\n\n  public destroy(): void {\n    const wasLeader = this.isLeader;\n    this.isLeader = false;\n\n    if (wasLeader) {\n      this.broadcast({ type: \"release\", senderId: this.tabId });\n    }\n\n    if (this.heartbeatInterval) clearInterval(this.heartbeatInterval);\n    if (this.watchdogTimeout) clearTimeout(this.watchdogTimeout);\n    if (this.electionTimeout) clearTimeout(this.electionTimeout);\n\n    this.stopEventSource();\n\n    if (this.channel) {\n      this.channel.close();\n      this.channel = null;\n    }\n  }\n\n  private broadcast(msg: MultiplexerMessage): void {\n    if (this.channel) {\n      try {\n        this.channel.postMessage(msg);\n      } catch (e) {\n        // Broadcast channel might be closed\n      }\n    }\n  }\n\n  private handleChannelMessage(msg: MultiplexerMessage): void {\n    if (msg.senderId === this.tabId) return;\n\n    switch (msg.type) {\n      case \"query_leader\":\n        if (this.isLeader) {\n          this.sendHeartbeat();\n        }\n        break;\n\n      case \"heartbeat\":\n        this.claimInProgress = false;\n        if (this.electionTimeout) {\n          clearTimeout(this.electionTimeout);\n          this.electionTimeout = null;\n        }\n        this.leaderId = msg.senderId;\n        this.resetWatchdog(5000); // 5s watchdog\n        break;\n\n      case \"claim\":\n        // Another tab wants to claim leadership.\n        if (this.isLeader) {\n          // Assert dominance immediately\n          this.sendHeartbeat();\n        } else if (this.claimInProgress) {\n          // If we also want to claim, the one with lower lexicographical tabId wins\n          if (msg.senderId < this.tabId) {\n            // We lose the election, abort our claim\n            this.claimInProgress = false;\n            if (this.electionTimeout) {\n              clearTimeout(this.electionTimeout);\n              this.electionTimeout = null;\n            }\n          }\n        }\n        break;\n\n      case \"release\":\n        if (this.leaderId === msg.senderId) {\n          this.leaderId = null;\n          // Trigger immediate election\n          this.attemptLeadershipClaim();\n        }\n        break;\n\n      case \"status\":\n        if (!this.isLeader && this.leaderId === msg.senderId) {\n          const payloadObj = msg.payload as {\n            status: ConnectionStatus;\n            activeConnections: number;\n          };\n          this.status = payloadObj.status;\n          this.onStatusChange(this.status, payloadObj.activeConnections);\n        }\n        break;\n\n      case \"event\":\n        if (!this.isLeader && this.leaderId === msg.senderId) {\n          const payloadObj = msg.payload as { event: string; data: unknown };\n          this.onEvent(payloadObj.event, payloadObj.data);\n        }\n        break;\n    }\n  }\n\n  private resetWatchdog(ms: number): void {\n    if (this.watchdogTimeout) clearTimeout(this.watchdogTimeout);\n    this.watchdogTimeout = setTimeout(() => {\n      this.attemptLeadershipClaim();\n    }, ms);\n  }\n\n  private attemptLeadershipClaim(): void {\n    if (this.isLeader || this.claimInProgress) return;\n\n    this.claimInProgress = true;\n    this.broadcast({ type: \"claim\", senderId: this.tabId });\n\n    // Wait 500ms for objection (heartbeat or higher priority claim)\n    this.electionTimeout = setTimeout(() => {\n      this.electionTimeout = null;\n      if (this.claimInProgress) {\n        this.claimInProgress = false;\n        this.becomeLeader();\n      }\n    }, 500);\n  }\n\n  private becomeLeader(): void {\n    this.isLeader = true;\n    this.leaderId = this.tabId;\n    if (this.watchdogTimeout) {\n      clearTimeout(this.watchdogTimeout);\n      this.watchdogTimeout = null;\n    }\n\n    // Start heartbeat broadcasts\n    this.sendHeartbeat();\n    this.heartbeatInterval = setInterval(() => this.sendHeartbeat(), 2000);\n\n    // Establish SSE EventSource\n    this.startEventSource();\n  }\n\n  private sendHeartbeat(): void {\n    this.broadcast({ type: \"heartbeat\", senderId: this.tabId });\n  }\n\n  private updateStatus(\n    newStatus: ConnectionStatus,\n    activeConnections = 0,\n  ): void {\n    this.status = newStatus;\n    this.onStatusChange(newStatus, activeConnections);\n    if (this.isLeader) {\n      this.broadcast({\n        type: \"status\",\n        senderId: this.tabId,\n        payload: { status: newStatus, activeConnections },\n      });\n    }\n  }\n\n  private startEventSource(): void {\n    this.stopEventSource();\n    this.updateStatus(\"connecting\");\n\n    try {\n      this.eventSource = new EventSource(this.endpoint);\n\n      this.eventSource.addEventListener(\"handshake\", (e) => {\n        try {\n          const data = JSON.parse(e.data);\n          this.updateStatus(\"connected\", data.activeConnections || 1);\n        } catch (err) {\n          this.updateStatus(\"connected\", 1);\n        }\n      });\n\n      this.eventSource.addEventListener(\"notification\", (e) => {\n        try {\n          const data = JSON.parse(e.data);\n          this.onEvent(\"notification\", data);\n          this.broadcast({\n            type: \"event\",\n            senderId: this.tabId,\n            payload: { event: \"notification\", data },\n          });\n        } catch (err) {\n          // Parse error\n        }\n      });\n\n      this.eventSource.onerror = () => {\n        this.updateStatus(\"connecting\");\n      };\n    } catch (err) {\n      this.updateStatus(\"disconnected\");\n    }\n  }\n\n  private startDirectConnection(): void {\n    // Non-browser fallback or single-tab mode\n    this.startEventSource();\n  }\n\n  private stopEventSource(): void {\n    if (this.eventSource) {\n      this.eventSource.close();\n      this.eventSource = null;\n    }\n  }\n}\n"],"mappings":"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","names":["callbacks"]}

package/dist/client.d.mts

@@ -0,0 +1,22 @@
+import React from 'react';
+
+type ConnectionStatus = "connecting" | "connected" | "disconnected";
+
+interface SseContextType {
+    subscribe: <T = unknown>(table: string, callback: (payload: T) => void) => () => void;
+    status: ConnectionStatus;
+    eventCount: number;
+    activeConnections: number;
+}
+declare const SseProvider: React.FC<{
+    children: React.ReactNode;
+    endpoint: string;
+}>;
+declare function useSubscription<T = unknown>(table: string, callback: (payload: T) => void): void;
+declare function useSseStatus(): {
+    status: ConnectionStatus;
+    eventCount: number;
+    activeConnections: number;
+};
+
+export { type ConnectionStatus, type SseContextType, SseProvider, useSseStatus, useSubscription };

package/dist/client.d.ts

@@ -0,0 +1,22 @@
+import React from 'react';
+
+type ConnectionStatus = "connecting" | "connected" | "disconnected";
+
+interface SseContextType {
+    subscribe: <T = unknown>(table: string, callback: (payload: T) => void) => () => void;
+    status: ConnectionStatus;
+    eventCount: number;
+    activeConnections: number;
+}
+declare const SseProvider: React.FC<{
+    children: React.ReactNode;
+    endpoint: string;
+}>;
+declare function useSubscription<T = unknown>(table: string, callback: (payload: T) => void): void;
+declare function useSseStatus(): {
+    status: ConnectionStatus;
+    eventCount: number;
+    activeConnections: number;
+};
+
+export { type ConnectionStatus, type SseContextType, SseProvider, useSseStatus, useSubscription };