npm - next-supa-utils - Versions diffs - 0.1.4 → 0.1.6 - Mend

next-supa-utils 0.1.4 → 0.1.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (17) hide show

package/dist/client/index.d.cts CHANGED Viewed

@@ -1,5 +1,55 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
 import { SupabaseClient } from '@supabase/supabase-js';
+interface SupaContextValue {
+    /**
+     * Explicit Supabase Project URL.
+     * If omitted, the context falls back to `process.env.NEXT_PUBLIC_SUPABASE_URL`.
+     */
+    supabaseUrl?: string;
+    /**
+     * Explicit Supabase Anon Key.
+     * If omitted, the context falls back to `process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY`.
+     */
+    supabaseAnonKey?: string;
+}
+/**
+ * `<SupaProvider>` allows you to inject explicit Supabase credentials
+ * (URL and Anon Key) into all `next-supa-utils/client` hooks.
+ *
+ * It is completely **optional** if you are using the standard environment
+ * variables (`NEXT_PUBLIC_SUPABASE_URL` and `NEXT_PUBLIC_SUPABASE_ANON_KEY`).
+ *
+ * @example
+ * ```tsx
+ * // app/layout.tsx
+ * import { SupaProvider } from "next-supa-utils/client";
+ *
+ * export default function RootLayout({ children }) {
+ *   return (
+ *     <html>
+ *       <body>
+ *         <SupaProvider supabaseUrl="https://..." supabaseAnonKey="ey...">
+ *           {children}
+ *         </SupaProvider>
+ *       </body>
+ *     </html>
+ *   );
+ * }
+ * ```
+ */
+declare function SupaProvider({ children, supabaseUrl, supabaseAnonKey, }: {
+    children: ReactNode;
+} & SupaContextValue): react_jsx_runtime.JSX.Element;
+/**
+ * Internal hook to retrieve the Supabase configuration from Context or Environment Variables.
+ */
+declare function useSupaConfig(): {
+    url: string;
+    key: string;
+};
 /** Standardized error shape returned by all next-supa-utils helpers. */
 interface SupaError {
     message: string;
@@ -16,6 +66,72 @@ interface UseSupaSessionReturn {
     loading: boolean;
     error: SupaError | null;
 }
+/** Options passed to the `upload` function from `useSupaUpload`. */
+interface UploadOptions {
+    /**
+     * The storage path (including filename) where the file will be saved.
+     * If omitted, defaults to `file.name`.
+     *
+     * @example "avatars/user-123.png"
+     */
+    path?: string;
+    /**
+     * Whether to overwrite an existing file at the same path.
+     * @default false
+     */
+    upsert?: boolean;
+    /**
+     * Cache-Control header value for the uploaded file.
+     * @default "3600"
+     */
+    cacheControl?: string;
+    /**
+     * MIME type of the file. Defaults to the File's own type.
+     */
+    contentType?: string;
+}
+/** Return type of the `useSupaUpload` hook. */
+interface UseSupaUploadReturn {
+    /** Upload a file to the configured bucket. */
+    upload: (file: File, options?: UploadOptions) => Promise<void>;
+    /** `true` while an upload is in progress. */
+    isUploading: boolean;
+    /**
+     * Upload progress percentage (0–100).
+     * Updates in real-time as bytes are sent via `XMLHttpRequest`.
+     */
+    progress: number;
+    /** Upload result data on success, or `null`. */
+    data: {
+        path: string;
+        fullPath: string;
+    } | null;
+    /** Error details on failure, or `null`. */
+    error: SupaError | null;
+    /** Reset all state (isUploading, progress, data, error) to initial values. */
+    reset: () => void;
+    /** Abort the current in-flight upload. */
+    cancel: () => void;
+}
+/** Postgres change event types supported by Supabase Realtime. */
+type RealtimeEvent = "INSERT" | "UPDATE" | "DELETE" | "*";
+/** Payload received from a Supabase Realtime postgres_changes event. */
+interface RealtimePayload<T extends Record<string, unknown> = Record<string, unknown>> {
+    /** The type of event that triggered the change. */
+    eventType: "INSERT" | "UPDATE" | "DELETE";
+    /** The new row data (present on INSERT and UPDATE). */
+    new: T;
+    /** The old row data (present on UPDATE and DELETE). */
+    old: Partial<T>;
+    /** The database schema (e.g. "public"). */
+    schema: string;
+    /** The table name. */
+    table: string;
+    /** Timestamp of the change. */
+    commit_timestamp: string;
+    /** Any additional errors from the event. */
+    errors: string[] | null;
+}
 /**
  * React hook that provides the current Supabase user and
@@ -65,4 +181,77 @@ declare function useSupaUser(): UseSupaUserReturn;
  */
 declare function useSupaSession(): UseSupaSessionReturn;
-export { type SupaError, type UseSupaSessionReturn, type UseSupaUserReturn, useSupaSession, useSupaUser };
+/**
+ * React hook that simplifies uploading files to Supabase Storage
+ * with **real-time progress tracking**.
+ *
+ * Uses `XMLHttpRequest` against the Supabase Storage REST API so that
+ * `progress` updates smoothly from 0 → 100 as bytes are sent, without
+ * requiring `tus-js-client` or any extra dependencies.
+ *
+ * @param bucketName - The name of the Supabase Storage bucket to upload to.
+ *
+ * @example
+ * ```tsx
+ * "use client";
+ * import { useSupaUpload } from "next-supa-utils/client";
+ *
+ * export default function AvatarUploader() {
+ *   const { upload, isUploading, progress, data, error } = useSupaUpload("avatars");
+ *
+ *   const handleChange = async (e: React.ChangeEvent<HTMLInputElement>) => {
+ *     const file = e.target.files?.[0];
+ *     if (!file) return;
+ *     await upload(file, { path: `users/${file.name}`, upsert: true });
+ *   };
+ *
+ *   return (
+ *     <div>
+ *       <input type="file" onChange={handleChange} disabled={isUploading} />
+ *       {isUploading && <progress value={progress} max={100} />}
+ *       {isUploading && <p>{progress}%</p>}
+ *       {error && <p>Error: {error.message}</p>}
+ *       {data && <p>Uploaded to: {data.path}</p>}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useSupaUpload(bucketName: string): UseSupaUploadReturn;
+/**
+ * React hook that subscribes to Supabase Realtime postgres_changes
+ * events and **safely cleans up** on unmount to prevent memory leaks.
+ *
+ * @param table    - The database table to listen to.
+ * @param event    - The event type: `"INSERT"`, `"UPDATE"`, `"DELETE"`, or `"*"` for all.
+ * @param callback - Function called with the realtime payload on each event.
+ * @param schema   - The database schema (defaults to `"public"`).
+ *
+ * @example
+ * ```tsx
+ * "use client";
+ * import { useSupaRealtime } from "next-supa-utils/client";
+ *
+ * export default function LiveMessages() {
+ *   const [messages, setMessages] = useState<Message[]>([]);
+ *
+ *   useSupaRealtime("messages", "INSERT", (payload) => {
+ *     setMessages((prev) => [...prev, payload.new as Message]);
+ *   });
+ *
+ *   return <ul>{messages.map((m) => <li key={m.id}>{m.text}</li>)}</ul>;
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Listen to all events with a custom schema
+ * useSupaRealtime("orders", "*", (payload) => {
+ *   console.log(payload.eventType, payload.new, payload.old);
+ * }, "inventory");
+ * ```
+ */
+declare function useSupaRealtime<T extends Record<string, unknown> = Record<string, unknown>>(table: string, event: RealtimeEvent, callback: (payload: RealtimePayload<T>) => void, schema?: string): void;
+export { type RealtimeEvent, type RealtimePayload, type SupaError, SupaProvider, type UploadOptions, type UseSupaSessionReturn, type UseSupaUploadReturn, type UseSupaUserReturn, useSupaConfig, useSupaRealtime, useSupaSession, useSupaUpload, useSupaUser };

package/dist/client/index.d.ts CHANGED Viewed

@@ -1,5 +1,55 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
 import { SupabaseClient } from '@supabase/supabase-js';
+interface SupaContextValue {
+    /**
+     * Explicit Supabase Project URL.
+     * If omitted, the context falls back to `process.env.NEXT_PUBLIC_SUPABASE_URL`.
+     */
+    supabaseUrl?: string;
+    /**
+     * Explicit Supabase Anon Key.
+     * If omitted, the context falls back to `process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY`.
+     */
+    supabaseAnonKey?: string;
+}
+/**
+ * `<SupaProvider>` allows you to inject explicit Supabase credentials
+ * (URL and Anon Key) into all `next-supa-utils/client` hooks.
+ *
+ * It is completely **optional** if you are using the standard environment
+ * variables (`NEXT_PUBLIC_SUPABASE_URL` and `NEXT_PUBLIC_SUPABASE_ANON_KEY`).
+ *
+ * @example
+ * ```tsx
+ * // app/layout.tsx
+ * import { SupaProvider } from "next-supa-utils/client";
+ *
+ * export default function RootLayout({ children }) {
+ *   return (
+ *     <html>
+ *       <body>
+ *         <SupaProvider supabaseUrl="https://..." supabaseAnonKey="ey...">
+ *           {children}
+ *         </SupaProvider>
+ *       </body>
+ *     </html>
+ *   );
+ * }
+ * ```
+ */
+declare function SupaProvider({ children, supabaseUrl, supabaseAnonKey, }: {
+    children: ReactNode;
+} & SupaContextValue): react_jsx_runtime.JSX.Element;
+/**
+ * Internal hook to retrieve the Supabase configuration from Context or Environment Variables.
+ */
+declare function useSupaConfig(): {
+    url: string;
+    key: string;
+};
 /** Standardized error shape returned by all next-supa-utils helpers. */
 interface SupaError {
     message: string;
@@ -16,6 +66,72 @@ interface UseSupaSessionReturn {
     loading: boolean;
     error: SupaError | null;
 }
+/** Options passed to the `upload` function from `useSupaUpload`. */
+interface UploadOptions {
+    /**
+     * The storage path (including filename) where the file will be saved.
+     * If omitted, defaults to `file.name`.
+     *
+     * @example "avatars/user-123.png"
+     */
+    path?: string;
+    /**
+     * Whether to overwrite an existing file at the same path.
+     * @default false
+     */
+    upsert?: boolean;
+    /**
+     * Cache-Control header value for the uploaded file.
+     * @default "3600"
+     */
+    cacheControl?: string;
+    /**
+     * MIME type of the file. Defaults to the File's own type.
+     */
+    contentType?: string;
+}
+/** Return type of the `useSupaUpload` hook. */
+interface UseSupaUploadReturn {
+    /** Upload a file to the configured bucket. */
+    upload: (file: File, options?: UploadOptions) => Promise<void>;
+    /** `true` while an upload is in progress. */
+    isUploading: boolean;
+    /**
+     * Upload progress percentage (0–100).
+     * Updates in real-time as bytes are sent via `XMLHttpRequest`.
+     */
+    progress: number;
+    /** Upload result data on success, or `null`. */
+    data: {
+        path: string;
+        fullPath: string;
+    } | null;
+    /** Error details on failure, or `null`. */
+    error: SupaError | null;
+    /** Reset all state (isUploading, progress, data, error) to initial values. */
+    reset: () => void;
+    /** Abort the current in-flight upload. */
+    cancel: () => void;
+}
+/** Postgres change event types supported by Supabase Realtime. */
+type RealtimeEvent = "INSERT" | "UPDATE" | "DELETE" | "*";
+/** Payload received from a Supabase Realtime postgres_changes event. */
+interface RealtimePayload<T extends Record<string, unknown> = Record<string, unknown>> {
+    /** The type of event that triggered the change. */
+    eventType: "INSERT" | "UPDATE" | "DELETE";
+    /** The new row data (present on INSERT and UPDATE). */
+    new: T;
+    /** The old row data (present on UPDATE and DELETE). */
+    old: Partial<T>;
+    /** The database schema (e.g. "public"). */
+    schema: string;
+    /** The table name. */
+    table: string;
+    /** Timestamp of the change. */
+    commit_timestamp: string;
+    /** Any additional errors from the event. */
+    errors: string[] | null;
+}
 /**
  * React hook that provides the current Supabase user and
@@ -65,4 +181,77 @@ declare function useSupaUser(): UseSupaUserReturn;
  */
 declare function useSupaSession(): UseSupaSessionReturn;
-export { type SupaError, type UseSupaSessionReturn, type UseSupaUserReturn, useSupaSession, useSupaUser };
+/**
+ * React hook that simplifies uploading files to Supabase Storage
+ * with **real-time progress tracking**.
+ *
+ * Uses `XMLHttpRequest` against the Supabase Storage REST API so that
+ * `progress` updates smoothly from 0 → 100 as bytes are sent, without
+ * requiring `tus-js-client` or any extra dependencies.
+ *
+ * @param bucketName - The name of the Supabase Storage bucket to upload to.
+ *
+ * @example
+ * ```tsx
+ * "use client";
+ * import { useSupaUpload } from "next-supa-utils/client";
+ *
+ * export default function AvatarUploader() {
+ *   const { upload, isUploading, progress, data, error } = useSupaUpload("avatars");
+ *
+ *   const handleChange = async (e: React.ChangeEvent<HTMLInputElement>) => {
+ *     const file = e.target.files?.[0];
+ *     if (!file) return;
+ *     await upload(file, { path: `users/${file.name}`, upsert: true });
+ *   };
+ *
+ *   return (
+ *     <div>
+ *       <input type="file" onChange={handleChange} disabled={isUploading} />
+ *       {isUploading && <progress value={progress} max={100} />}
+ *       {isUploading && <p>{progress}%</p>}
+ *       {error && <p>Error: {error.message}</p>}
+ *       {data && <p>Uploaded to: {data.path}</p>}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useSupaUpload(bucketName: string): UseSupaUploadReturn;
+/**
+ * React hook that subscribes to Supabase Realtime postgres_changes
+ * events and **safely cleans up** on unmount to prevent memory leaks.
+ *
+ * @param table    - The database table to listen to.
+ * @param event    - The event type: `"INSERT"`, `"UPDATE"`, `"DELETE"`, or `"*"` for all.
+ * @param callback - Function called with the realtime payload on each event.
+ * @param schema   - The database schema (defaults to `"public"`).
+ *
+ * @example
+ * ```tsx
+ * "use client";
+ * import { useSupaRealtime } from "next-supa-utils/client";
+ *
+ * export default function LiveMessages() {
+ *   const [messages, setMessages] = useState<Message[]>([]);
+ *
+ *   useSupaRealtime("messages", "INSERT", (payload) => {
+ *     setMessages((prev) => [...prev, payload.new as Message]);
+ *   });
+ *
+ *   return <ul>{messages.map((m) => <li key={m.id}>{m.text}</li>)}</ul>;
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Listen to all events with a custom schema
+ * useSupaRealtime("orders", "*", (payload) => {
+ *   console.log(payload.eventType, payload.new, payload.old);
+ * }, "inventory");
+ * ```
+ */
+declare function useSupaRealtime<T extends Record<string, unknown> = Record<string, unknown>>(table: string, event: RealtimeEvent, callback: (payload: RealtimePayload<T>) => void, schema?: string): void;
+export { type RealtimeEvent, type RealtimePayload, type SupaError, SupaProvider, type UploadOptions, type UseSupaSessionReturn, type UseSupaUploadReturn, type UseSupaUserReturn, useSupaConfig, useSupaRealtime, useSupaSession, useSupaUpload, useSupaUser };

package/dist/client/index.js CHANGED Viewed

@@ -1,6 +1,29 @@
 "use client";
 "use client";
+// src/client/SupaProvider.tsx
+import { createContext, useContext } from "react";
+import { jsx } from "react/jsx-runtime";
+var SupaContext = createContext(void 0);
+function SupaProvider({
+  children,
+  supabaseUrl,
+  supabaseAnonKey
+}) {
+  return /* @__PURE__ */ jsx(SupaContext.Provider, { value: { supabaseUrl, supabaseAnonKey }, children });
+}
+function useSupaConfig() {
+  const context = useContext(SupaContext);
+  const url = context?.supabaseUrl ?? process.env.NEXT_PUBLIC_SUPABASE_URL;
+  const key = context?.supabaseAnonKey ?? process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY;
+  if (!url || !key) {
+    throw new Error(
+      "[next-supa-utils] Missing Supabase configuration. Provide NEXT_PUBLIC_SUPABASE_URL and NEXT_PUBLIC_SUPABASE_ANON_KEY environment variables, or wrap your tree in <SupaProvider supabaseUrl={...} supabaseAnonKey={...}>."
+    );
+  }
+  return { url, key };
+}
 // src/client/hooks/useSupaUser.ts
 import { useEffect, useState } from "react";
 import { createBrowserClient } from "@supabase/ssr";
@@ -36,20 +59,8 @@ function useSupaUser() {
     loading: true,
     error: null
   });
+  const { url: supabaseUrl, key: supabaseAnonKey } = useSupaConfig();
   useEffect(() => {
-    const supabaseUrl = process.env.NEXT_PUBLIC_SUPABASE_URL;
-    const supabaseAnonKey = process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY;
-    if (!supabaseUrl || !supabaseAnonKey) {
-      setState({
-        user: null,
-        loading: false,
-        error: {
-          message: "Missing NEXT_PUBLIC_SUPABASE_URL or NEXT_PUBLIC_SUPABASE_ANON_KEY environment variables.",
-          code: "CONFIG_ERROR"
-        }
-      });
-      return;
-    }
     const supabase = createBrowserClient(supabaseUrl, supabaseAnonKey);
     supabase.auth.getUser().then(({ data, error }) => {
       setState({
@@ -83,20 +94,8 @@ function useSupaSession() {
     loading: true,
     error: null
   });
+  const { url: supabaseUrl, key: supabaseAnonKey } = useSupaConfig();
   useEffect2(() => {
-    const supabaseUrl = process.env.NEXT_PUBLIC_SUPABASE_URL;
-    const supabaseAnonKey = process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY;
-    if (!supabaseUrl || !supabaseAnonKey) {
-      setState({
-        session: null,
-        loading: false,
-        error: {
-          message: "Missing NEXT_PUBLIC_SUPABASE_URL or NEXT_PUBLIC_SUPABASE_ANON_KEY environment variables.",
-          code: "CONFIG_ERROR"
-        }
-      });
-      return;
-    }
     const supabase = createBrowserClient2(supabaseUrl, supabaseAnonKey);
     supabase.auth.getSession().then(({ data, error }) => {
       setState({
@@ -120,8 +119,160 @@ function useSupaSession() {
   }, []);
   return state;
 }
+// src/client/hooks/useSupaUpload.ts
+import { useCallback, useRef, useState as useState3 } from "react";
+import { createBrowserClient as createBrowserClient3 } from "@supabase/ssr";
+function useSupaUpload(bucketName) {
+  const [isUploading, setIsUploading] = useState3(false);
+  const [progress, setProgress] = useState3(0);
+  const [data, setData] = useState3(null);
+  const [error, setError] = useState3(null);
+  const xhrRef = useRef(null);
+  const supabaseRef = useRef(null);
+  const { url: supabaseUrl, key: supabaseAnonKey } = useSupaConfig();
+  function getClient() {
+    if (supabaseRef.current) return supabaseRef.current;
+    supabaseRef.current = createBrowserClient3(supabaseUrl, supabaseAnonKey);
+    return supabaseRef.current;
+  }
+  const upload = useCallback(
+    async (file, options) => {
+      setIsUploading(true);
+      setProgress(0);
+      setData(null);
+      setError(null);
+      try {
+        const supabase = getClient();
+        const {
+          data: { session }
+        } = await supabase.auth.getSession();
+        const accessToken = session?.access_token ?? supabaseAnonKey;
+        const filePath = options?.path ?? file.name;
+        const uploadUrl = `${supabaseUrl}/storage/v1/object/${bucketName}/${filePath}`;
+        await new Promise((resolve, reject) => {
+          const xhr = new XMLHttpRequest();
+          xhrRef.current = xhr;
+          xhr.upload.addEventListener("progress", (e) => {
+            if (e.lengthComputable) {
+              const pct = Math.round(e.loaded / e.total * 100);
+              setProgress(pct);
+            }
+          });
+          xhr.addEventListener("load", () => {
+            xhrRef.current = null;
+            if (xhr.status >= 200 && xhr.status < 300) {
+              try {
+                const response = JSON.parse(xhr.responseText);
+                const fullPath = response.Key ?? `${bucketName}/${filePath}`;
+                setData({ path: filePath, fullPath });
+                setProgress(100);
+                resolve();
+              } catch {
+                setData({ path: filePath, fullPath: `${bucketName}/${filePath}` });
+                setProgress(100);
+                resolve();
+              }
+            } else {
+              try {
+                const errBody = JSON.parse(xhr.responseText);
+                reject(
+                  new Error(
+                    errBody.message ?? errBody.error ?? `Upload failed with status ${xhr.status}`
+                  )
+                );
+              } catch {
+                reject(new Error(`Upload failed with status ${xhr.status}`));
+              }
+            }
+          });
+          xhr.addEventListener("error", () => {
+            xhrRef.current = null;
+            reject(new Error("Network error during upload"));
+          });
+          xhr.addEventListener("abort", () => {
+            xhrRef.current = null;
+            reject(new Error("Upload cancelled"));
+          });
+          xhr.open("POST", uploadUrl, true);
+          xhr.setRequestHeader("Authorization", `Bearer ${accessToken}`);
+          xhr.setRequestHeader("apikey", supabaseAnonKey);
+          xhr.setRequestHeader(
+            "Content-Type",
+            options?.contentType ?? (file.type || "application/octet-stream")
+          );
+          xhr.setRequestHeader(
+            "cache-control",
+            options?.cacheControl ?? "3600"
+          );
+          xhr.setRequestHeader(
+            "x-upsert",
+            String(options?.upsert ?? false)
+          );
+          xhr.send(file);
+        });
+      } catch (caught) {
+        setError(handleSupaError(caught));
+        setProgress(0);
+      } finally {
+        setIsUploading(false);
+      }
+    },
+    [bucketName]
+  );
+  const cancel = useCallback(() => {
+    if (xhrRef.current) {
+      xhrRef.current.abort();
+      xhrRef.current = null;
+    }
+  }, []);
+  const reset = useCallback(() => {
+    cancel();
+    setIsUploading(false);
+    setProgress(0);
+    setData(null);
+    setError(null);
+  }, [cancel]);
+  return { upload, isUploading, progress, data, error, reset, cancel };
+}
+// src/client/hooks/useSupaRealtime.ts
+import { useEffect as useEffect3, useRef as useRef2 } from "react";
+import { createBrowserClient as createBrowserClient4 } from "@supabase/ssr";
+function useSupaRealtime(table, event, callback, schema = "public") {
+  const callbackRef = useRef2(callback);
+  callbackRef.current = callback;
+  const channelRef = useRef2(null);
+  const { url: supabaseUrl, key: supabaseAnonKey } = useSupaConfig();
+  useEffect3(() => {
+    const supabase = createBrowserClient4(supabaseUrl, supabaseAnonKey);
+    const channelName = `realtime:${schema}:${table}:${event}:${Date.now()}`;
+    const channel = supabase.channel(channelName).on(
+      "postgres_changes",
+      {
+        event: event === "*" ? "*" : event,
+        schema,
+        table
+      },
+      (payload) => {
+        callbackRef.current(payload);
+      }
+    ).subscribe();
+    channelRef.current = channel;
+    return () => {
+      if (channelRef.current) {
+        supabase.removeChannel(channelRef.current);
+        channelRef.current = null;
+      }
+    };
+  }, [table, event, schema]);
+}
 export {
+  SupaProvider,
+  useSupaConfig,
+  useSupaRealtime,
   useSupaSession,
+  useSupaUpload,
   useSupaUser
 };
 //# sourceMappingURL=index.js.map