supabase-edge-function-continuous-stream 1.0.0

package/dist/react-BgnmZ7M3.d.ts

@@ -0,0 +1,75 @@
+type EdgeFunctionRawMessage = Record<string, unknown> & {
+    type: string;
+};
+interface EdgeFunctionMessageContext<TResponse extends Record<string, unknown>> {
+    resolve: (value: TResponse) => void;
+    reject: (reason: Error) => void;
+    closeSocket: () => void;
+    clearOverallTimeout: () => void;
+    isResolved: () => boolean;
+}
+type EdgeStreamConfig = {
+    functionPath: string;
+};
+/** Callbacks a caller can wire up for side-effects during streaming. */
+interface StandardAiCallbacks {
+    onServerAction?: (type: string, data: unknown) => void;
+    toUserMessage?: (error: unknown) => string | null;
+}
+type WarmupOptions = {
+    onServerAction?: (type: string, data: unknown) => void;
+};
+type StartStreamOptions<TResponse extends Record<string, unknown>> = {
+    /** Optional: Use a custom message handler. If omitted, it uses the Standard AI Protocol handler. */
+    onMessage?: (message: EdgeFunctionRawMessage, ctx: EdgeFunctionMessageContext<TResponse>) => void;
+    /** Optional: Defaults to seed the response object if not sent by the server. */
+    defaults?: Partial<TResponse>;
+    /** Optional: Listener for server actions (status, complete, etc.) */
+    onServerAction?: (type: string, data: unknown) => void;
+    /** Optional: Tags to invalidate on completion. */
+    invalidateTags?: {
+        tags: Array<string | {
+            type: string;
+            id?: string | number;
+        }>;
+        condition?: (response?: TResponse) => boolean;
+    };
+    /** Optional: Edge worker expiry from server checkpoint metadata */
+    getWorkerExpiresAt?: () => number | null;
+};
+/** Mutable ref bag used by connectEdgeSocket without React */
+type Ref<T> = {
+    current: T;
+};
+
+/** Client-side edge worker timing configuration */
+type EdgeWorkerLimits = {
+    edgeWorkerTtlMs: number;
+    edgeRotateThresholdMs: number;
+    overallTimeoutMs: number;
+};
+/** Default limits aligned with short-lived edge workers (~2.5 min TTL) */
+declare const DEFAULT_EDGE_WORKER_LIMITS: EdgeWorkerLimits;
+
+type EdgeStreamCoreDeps = {
+    getAccessToken: () => Promise<string>;
+    getSupabaseUrl: () => string;
+    workerLimits: EdgeWorkerLimits;
+    toUserMessage?: (error: unknown) => string | null;
+    invalidateTags?: (tags: Array<string | {
+        type: string;
+        id?: string | number;
+    }>) => void;
+};
+/** Factory for a WebSocket streaming hook wired to a host app */
+declare function createUseEdgeStream(deps: EdgeStreamCoreDeps): <TPayload, TResponse extends Record<string, unknown>>(config: EdgeStreamConfig) => {
+    warmup: (payload: TPayload, options?: WarmupOptions) => Promise<void>;
+    send: (payload: TPayload, options: StartStreamOptions<TResponse>) => Promise<TResponse>;
+    abort: () => void;
+    isLoading: boolean;
+    error: Error | null;
+    data: TResponse | undefined;
+    isConnected: boolean;
+};
+
+export { DEFAULT_EDGE_WORKER_LIMITS as D, type EdgeFunctionRawMessage as E, type Ref as R, type StandardAiCallbacks as S, type WarmupOptions as W, type EdgeFunctionMessageContext as a, type EdgeStreamConfig as b, type EdgeStreamCoreDeps as c, type EdgeWorkerLimits as d, type StartStreamOptions as e, createUseEdgeStream as f };

package/dist/react.cjs

@@ -0,0 +1,485 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/react.ts
+var react_exports = {};
+__export(react_exports, {
+  createUseEdgeStream: () => createUseEdgeStream
+});
+module.exports = __toCommonJS(react_exports);
+
+// src/createUseEdgeStream.ts
+var import_react = require("react");
+
+// src/constants.ts
+var MAX_RETRIES = 200;
+var INITIAL_RETRY_DELAY_MS = 1e3;
+var CONNECTION_TIMEOUT_MS = 1e4;
+
+// src/connection.ts
+async function connectEdgeSocket(deps) {
+  const {
+    functionPath,
+    getAccessToken,
+    getSupabaseUrl,
+    wsRef,
+    isExplicitDisconnectRef,
+    isConnectingRef,
+    retryCountRef,
+    socketOpenedAtRef,
+    isWarmupReadyRef,
+    warmupWaitersRef,
+    passiveOnServerActionRef,
+    activeRequestRef,
+    lastWarmupPayloadRef,
+    setIsConnected,
+    closeSocket,
+    sendWarmupPayload,
+    settleWarmupWaiters
+  } = deps;
+  if (wsRef.current?.readyState === WebSocket.OPEN) return Promise.resolve();
+  if (isConnectingRef.current) {
+    return new Promise((resolve, reject) => {
+      const checkInterval = setInterval(() => {
+        if (wsRef.current?.readyState === WebSocket.OPEN) {
+          clearInterval(checkInterval);
+          resolve();
+        } else if (wsRef.current?.readyState === WebSocket.CLOSED) {
+          clearInterval(checkInterval);
+          reject(new Error("Connection closed during check"));
+        }
+      }, 100);
+    });
+  }
+  isConnectingRef.current = true;
+  isExplicitDisconnectRef.current = false;
+  try {
+    const accessToken = await getAccessToken();
+    const supabaseUrl = getSupabaseUrl();
+    if (!supabaseUrl) throw new Error("Missing Supabase URL");
+    const wsUrl = supabaseUrl.replace(
+      /^https?:\/\//,
+      (m) => m === "https://" ? "wss://" : "ws://"
+    );
+    const functionUrl = `${wsUrl}/functions/v1/${functionPath}`;
+    return await new Promise((resolveConnection, rejectConnection) => {
+      let connectionTimeout = null;
+      if (wsRef.current) {
+        try {
+          wsRef.current.onopen = null;
+          wsRef.current.onmessage = null;
+          wsRef.current.onerror = null;
+          wsRef.current.onclose = null;
+          if (wsRef.current.readyState === WebSocket.OPEN || wsRef.current.readyState === WebSocket.CONNECTING) {
+            wsRef.current.close();
+          }
+        } catch {
+        }
+      }
+      const urlWithToken = new URL(functionUrl);
+      urlWithToken.searchParams.set("jwt", accessToken);
+      wsRef.current = new WebSocket(urlWithToken.toString());
+      if (retryCountRef.current === 0) {
+        connectionTimeout = setTimeout(() => {
+          if (wsRef.current && wsRef.current.readyState !== WebSocket.OPEN) {
+            isExplicitDisconnectRef.current = false;
+            closeSocket();
+          }
+        }, CONNECTION_TIMEOUT_MS);
+      }
+      wsRef.current.onopen = () => {
+        if (connectionTimeout) clearTimeout(connectionTimeout);
+        retryCountRef.current = 0;
+        isConnectingRef.current = false;
+        setIsConnected(true);
+        socketOpenedAtRef.current = Date.now();
+        if (lastWarmupPayloadRef.current) {
+          sendWarmupPayload();
+        }
+        resolveConnection();
+      };
+      wsRef.current.onerror = () => {
+      };
+      const retryConnect = () => {
+        connectEdgeSocket(deps).then(resolveConnection).catch(rejectConnection);
+      };
+      wsRef.current.onclose = () => {
+        if (connectionTimeout) clearTimeout(connectionTimeout);
+        isConnectingRef.current = false;
+        setIsConnected(false);
+        isWarmupReadyRef.current = false;
+        const willRetry = !isExplicitDisconnectRef.current && retryCountRef.current < MAX_RETRIES;
+        if (!willRetry) {
+          settleWarmupWaiters(new Error("WebSocket closed"));
+        }
+        if (isExplicitDisconnectRef.current) {
+          rejectConnection(
+            new Error("WebSocket closed by server or aborted")
+          );
+        } else if (retryCountRef.current < MAX_RETRIES) {
+          retryCountRef.current++;
+          const delay = INITIAL_RETRY_DELAY_MS * Math.pow(2, retryCountRef.current - 1);
+          setTimeout(retryConnect, delay);
+        } else {
+          rejectConnection(
+            new Error(
+              `WebSocket connection failed after ${retryCountRef.current} retries`
+            )
+          );
+        }
+      };
+      wsRef.current.onmessage = (event) => {
+        try {
+          const message = JSON.parse(event.data);
+          if (message.type === "status" && message.data === "ready") {
+            isWarmupReadyRef.current = true;
+            settleWarmupWaiters();
+          }
+          if (message.type === "error" && warmupWaitersRef.current.length > 0 && !isWarmupReadyRef.current) {
+            isWarmupReadyRef.current = false;
+            settleWarmupWaiters(
+              new Error(String(message.data ?? "Warmup failed"))
+            );
+          }
+          const passive = passiveOnServerActionRef.current;
+          if (passive && !activeRequestRef.current) {
+            const isWarmupControl = message.type === "status" && (message.data === "ready" || message.data === "context");
+            if (!isWarmupControl) {
+              passive(message.type, message.data);
+            }
+          }
+          if (!activeRequestRef.current) return;
+          const { ctx, handler } = activeRequestRef.current;
+          handler(message, ctx);
+        } catch (error) {
+          if (!activeRequestRef.current) return;
+          const ctx = activeRequestRef.current.ctx;
+          ctx.reject(
+            new Error(
+              `Failed to parse WebSocket message: ${error instanceof Error ? error.message : String(error)}`
+            )
+          );
+        }
+      };
+    });
+  } catch (err) {
+    isConnectingRef.current = false;
+    throw err;
+  }
+}
+
+// src/handler.ts
+function createStandardAiMessageHandler(defaults = {}, callbacks) {
+  const state = {};
+  const buildResponse = (overrides) => ({
+    ...defaults,
+    ...state,
+    ...overrides
+  });
+  return (message, ctx) => {
+    if (message.type === "response_text" && typeof message.data === "string") {
+      state.reply = message.data;
+    }
+    if (typeof message.data === "object" && message.data !== null && message.type !== "error") {
+      Object.assign(state, message.data);
+    }
+    if (message.type === "error") {
+      const raw = message.data ?? "Server error";
+      const userMsg = callbacks?.toUserMessage?.(raw);
+      if (userMsg) callbacks?.onServerAction?.("error", userMsg);
+      ctx.reject(new Error(raw));
+      return;
+    }
+    if (message.type === "complete") {
+      ctx.clearOverallTimeout();
+      callbacks?.onServerAction?.("complete", message.data);
+      if (!ctx.isResolved()) {
+        ctx.resolve(buildResponse(message.data));
+      }
+      return;
+    }
+    callbacks?.onServerAction?.(message.type, message.data);
+  };
+}
+
+// src/createUseEdgeStream.ts
+function createUseEdgeStream(deps) {
+  const {
+    getAccessToken,
+    getSupabaseUrl,
+    workerLimits,
+    toUserMessage,
+    invalidateTags
+  } = deps;
+  const { edgeWorkerTtlMs, edgeRotateThresholdMs, overallTimeoutMs } = workerLimits;
+  return function useEdgeStream(config) {
+    const [isLoading, setIsLoading] = (0, import_react.useState)(false);
+    const [error, setError] = (0, import_react.useState)(null);
+    const [data, setData] = (0, import_react.useState)(void 0);
+    const wsRef = (0, import_react.useRef)(null);
+    const isExplicitDisconnectRef = (0, import_react.useRef)(false);
+    const [isConnected, setIsConnected] = (0, import_react.useState)(false);
+    const isConnectingRef = (0, import_react.useRef)(false);
+    const lastWarmupPayloadRef = (0, import_react.useRef)(null);
+    const isWarmupReadyRef = (0, import_react.useRef)(false);
+    const warmupWaitersRef = (0, import_react.useRef)([]);
+    const retryCountRef = (0, import_react.useRef)(0);
+    const passiveOnServerActionRef = (0, import_react.useRef)(null);
+    const socketOpenedAtRef = (0, import_react.useRef)(null);
+    const settleWarmupWaiters = (0, import_react.useCallback)((warmupError) => {
+      const waiters = warmupWaitersRef.current;
+      warmupWaitersRef.current = [];
+      if (warmupError) {
+        waiters.forEach((w) => w.reject(warmupError));
+        return;
+      }
+      waiters.forEach((w) => w.resolve());
+    }, []);
+    const waitForWarmupReady = (0, import_react.useCallback)(() => {
+      if (isWarmupReadyRef.current) return Promise.resolve();
+      return new Promise((resolve, reject) => {
+        warmupWaitersRef.current.push({ resolve, reject });
+      });
+    }, []);
+    const sendWarmupPayload = (0, import_react.useCallback)(() => {
+      if (!wsRef.current || wsRef.current.readyState !== WebSocket.OPEN) {
+        return;
+      }
+      if (!lastWarmupPayloadRef.current) return;
+      isWarmupReadyRef.current = false;
+      wsRef.current.send(
+        JSON.stringify({
+          type: "client_warmup",
+          data: lastWarmupPayloadRef.current
+        })
+      );
+    }, []);
+    const activeRequestRef = (0, import_react.useRef)(null);
+    (0, import_react.useEffect)(() => {
+      return () => {
+        isExplicitDisconnectRef.current = true;
+        if (wsRef.current) {
+          try {
+            wsRef.current.close();
+          } catch {
+          }
+        }
+      };
+    }, []);
+    const closeSocket = (0, import_react.useCallback)(() => {
+      if (!wsRef.current) return;
+      try {
+        wsRef.current.close();
+      } catch {
+      }
+      socketOpenedAtRef.current = null;
+    }, []);
+    const abort = (0, import_react.useCallback)(() => {
+      isExplicitDisconnectRef.current = true;
+      closeSocket();
+      setIsLoading(false);
+      if (activeRequestRef.current) {
+        activeRequestRef.current.reject(new Error("Request aborted"));
+        if (activeRequestRef.current.overallTimeout) {
+          clearTimeout(activeRequestRef.current.overallTimeout);
+        }
+        activeRequestRef.current = null;
+      }
+    }, [closeSocket]);
+    const connectWebSocket = (0, import_react.useCallback)(
+      () => connectEdgeSocket({
+        functionPath: config.functionPath,
+        getAccessToken,
+        getSupabaseUrl,
+        wsRef,
+        isExplicitDisconnectRef,
+        isConnectingRef,
+        retryCountRef,
+        socketOpenedAtRef,
+        isWarmupReadyRef,
+        warmupWaitersRef,
+        passiveOnServerActionRef,
+        activeRequestRef,
+        lastWarmupPayloadRef,
+        setIsConnected,
+        closeSocket,
+        sendWarmupPayload,
+        settleWarmupWaiters
+      }),
+      [
+        config.functionPath,
+        closeSocket,
+        sendWarmupPayload,
+        settleWarmupWaiters
+      ]
+    );
+    const rotateConnectionIfNeeded = (0, import_react.useCallback)(
+      async (getExpiresAt) => {
+        const fallbackExpires = socketOpenedAtRef.current ? socketOpenedAtRef.current + edgeWorkerTtlMs : null;
+        const expiresAt = getExpiresAt?.() ?? fallbackExpires;
+        if (!expiresAt) return;
+        if (expiresAt - Date.now() >= edgeRotateThresholdMs) return;
+        isExplicitDisconnectRef.current = false;
+        closeSocket();
+        isWarmupReadyRef.current = false;
+        await connectWebSocket();
+      },
+      [closeSocket, connectWebSocket, edgeRotateThresholdMs, edgeWorkerTtlMs]
+    );
+    const warmup = (0, import_react.useCallback)(
+      async (payload, options) => {
+        if (options?.onServerAction) {
+          passiveOnServerActionRef.current = options.onServerAction;
+        }
+        lastWarmupPayloadRef.current = payload;
+        isWarmupReadyRef.current = false;
+        const wasOpen = wsRef.current?.readyState === WebSocket.OPEN;
+        await connectWebSocket();
+        if (!isWarmupReadyRef.current) {
+          if (wasOpen) sendWarmupPayload();
+          await waitForWarmupReady();
+        }
+      },
+      [connectWebSocket, sendWarmupPayload, waitForWarmupReady]
+    );
+    const send = (0, import_react.useCallback)(
+      async (payload, options) => {
+        if (!isLoading) {
+          await rotateConnectionIfNeeded(options.getWorkerExpiresAt);
+        }
+        setIsLoading(true);
+        setError(null);
+        setData(void 0);
+        isExplicitDisconnectRef.current = false;
+        let resolved = false;
+        const ctx = {
+          resolve: (value) => {
+            resolved = true;
+            setData(value);
+            setIsLoading(false);
+            if (options.invalidateTags && invalidateTags) {
+              const shouldInvalidate = options.invalidateTags.condition ? options.invalidateTags.condition(value) : true;
+              if (shouldInvalidate) {
+                invalidateTags(options.invalidateTags.tags);
+              }
+            }
+            if (activeRequestRef.current?.overallTimeout) {
+              clearTimeout(activeRequestRef.current.overallTimeout);
+            }
+            if (activeRequestRef.current?.resolve) {
+              activeRequestRef.current.resolve(value);
+            }
+            activeRequestRef.current = null;
+          },
+          reject: (err) => {
+            resolved = true;
+            setError(err);
+            setIsLoading(false);
+            if (activeRequestRef.current?.overallTimeout) {
+              clearTimeout(activeRequestRef.current.overallTimeout);
+            }
+            if (activeRequestRef.current?.reject) {
+              activeRequestRef.current.reject(err);
+            }
+            activeRequestRef.current = null;
+          },
+          closeSocket,
+          clearOverallTimeout: () => {
+            if (activeRequestRef.current?.overallTimeout) {
+              clearTimeout(activeRequestRef.current.overallTimeout);
+            }
+          },
+          isResolved: () => resolved
+        };
+        return new Promise((resolvePromise, rejectPromise) => {
+          const overallTimeout = setTimeout(() => {
+            if (!resolved) {
+              const err = new Error("WebSocket request timeout");
+              setError(err);
+              setIsLoading(false);
+              rejectPromise(err);
+              activeRequestRef.current = null;
+            }
+          }, overallTimeoutMs);
+          const handler = options.onMessage || createStandardAiMessageHandler(options.defaults || {}, {
+            onServerAction: options.onServerAction,
+            toUserMessage
+          });
+          activeRequestRef.current = {
+            payload,
+            options,
+            ctx,
+            resolve: resolvePromise,
+            reject: rejectPromise,
+            overallTimeout,
+            handler
+          };
+          connectWebSocket().then(async () => {
+            if (!activeRequestRef.current || activeRequestRef.current.sent) {
+              return;
+            }
+            if (!lastWarmupPayloadRef.current) {
+              throw new Error("Warmup required");
+            }
+            if (!isWarmupReadyRef.current) {
+              sendWarmupPayload();
+              await waitForWarmupReady();
+            }
+            if (wsRef.current?.readyState === WebSocket.OPEN && activeRequestRef.current && !activeRequestRef.current.sent) {
+              activeRequestRef.current.sent = true;
+              wsRef.current.send(
+                JSON.stringify({ type: "client_message", data: payload })
+              );
+            }
+          }).catch((err) => {
+            clearTimeout(overallTimeout);
+            setError(err);
+            setIsLoading(false);
+            rejectPromise(err);
+            activeRequestRef.current = null;
+          });
+        });
+      },
+      [
+        connectWebSocket,
+        closeSocket,
+        sendWarmupPayload,
+        waitForWarmupReady,
+        rotateConnectionIfNeeded,
+        isLoading,
+        overallTimeoutMs,
+        toUserMessage,
+        invalidateTags
+      ]
+    );
+    return {
+      warmup,
+      send,
+      abort,
+      isLoading,
+      error,
+      data,
+      isConnected
+    };
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createUseEdgeStream
+});

package/dist/react.d.cts

@@ -0,0 +1 @@
+export { a as EdgeFunctionMessageContext, E as EdgeFunctionRawMessage, b as EdgeStreamConfig, c as EdgeStreamCoreDeps, S as StandardAiCallbacks, e as StartStreamOptions, W as WarmupOptions, f as createUseEdgeStream } from './react-BgnmZ7M3.cjs';

package/dist/react.d.ts

@@ -0,0 +1 @@
+export { a as EdgeFunctionMessageContext, E as EdgeFunctionRawMessage, b as EdgeStreamConfig, c as EdgeStreamCoreDeps, S as StandardAiCallbacks, e as StartStreamOptions, W as WarmupOptions, f as createUseEdgeStream } from './react-BgnmZ7M3.js';

package/dist/react.js

@@ -0,0 +1,6 @@
+import {
+  createUseEdgeStream
+} from "./chunk-GP2SEFBH.js";
+export {
+  createUseEdgeStream
+};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "supabase-edge-function-continuous-stream",
+  "version": "1.0.0",
+  "description": "Continuous WebSocket streaming for Supabase edge functions",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./react.js",
+      "require": "./dist/react.cjs",
+      "default": "./react.js"
+    }
+  },
+  "files": [
+    "dist",
+    "react.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/react": "^19",
+    "react": "^19",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.0",
+    "vitest": "^3.2.4"
+  },
+  "keywords": [
+    "supabase",
+    "edge-functions",
+    "websocket",
+    "streaming",
+    "react"
+  ]
+}

package/react.js

@@ -0,0 +1 @@
+export * from "./dist/react.js";