@fluxbase/sdk-react 2026.1.22 → 2026.2.1

package/dist/index.d.mts

@@ -1,7 +1,7 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode } from 'react';
 import * as _fluxbase_sdk from '@fluxbase/sdk';
-import { FluxbaseClient, User, AuthSession, SignInCredentials, SignUpCredentials, CaptchaConfig, CaptchaProvider, AuthConfig, SAMLProvider, SAMLLoginOptions, GraphQLRequestOptions, GraphQLError, GraphQLResponse, QueryBuilder, RealtimeCallback, RealtimePostgresChangesPayload, ListOptions, UploadOptions, UploadProgress, TransformOptions, SignedUrlOptions, AdminAuthResponse, ListUsersOptions, EnrichedUser, ClientKey, CreateClientKeyRequest, Webhook, CreateWebhookRequest, UpdateWebhookRequest, AppSettings, UpdateAppSettingsRequest, SystemSetting, UpdateSystemSettingRequest } from '@fluxbase/sdk';
+import { FluxbaseClient, User, AuthSession, SignInCredentials, SignUpCredentials, CaptchaConfig, CaptchaProvider, AuthConfig, SAMLLoginOptions, SAMLProvider, GraphQLRequestOptions, GraphQLError, GraphQLResponse, QueryBuilder, RealtimeCallback, RealtimePostgresChangesPayload, ListOptions, SignedUrlOptions, TransformOptions, UploadOptions, UploadProgress, AdminAuthResponse, ListUsersOptions, EnrichedUser, ClientKey, CreateClientKeyRequest, AppSettings, UpdateAppSettingsRequest, SystemSetting, UpdateSystemSettingRequest, Webhook, CreateWebhookRequest, UpdateWebhookRequest } from '@fluxbase/sdk';
 export { APIKey, AdminUser, AppSettings, AuthSession, CaptchaConfig, CaptchaProvider, ClientKey, EnrichedUser, FluxbaseClient, GraphQLError, GraphQLErrorLocation, GraphQLRequestOptions, GraphQLResponse, ImageFitMode, ImageFormat, PostgrestResponse, RealtimeChangePayload, SAMLLoginOptions, SAMLLoginResponse, SAMLProvider, SAMLProvidersResponse, SAMLSession, SignInCredentials, SignUpCredentials, SignedUrlOptions, StorageObject, SystemSetting, TransformOptions, User, Webhook } from '@fluxbase/sdk';
 import * as _tanstack_react_query from '@tanstack/react-query';
 import { UseQueryOptions } from '@tanstack/react-query';
@@ -634,12 +634,40 @@ interface UseFluxbaseQueryOptions<T> extends Omit<UseQueryOptions<T[], Error>, '
  * Hook to execute a database query
  * @param buildQuery - Function that builds and returns the query
  * @param options - React Query options
+ *
+ * IMPORTANT: You must provide a stable `queryKey` in options for proper caching.
+ * Without a custom queryKey, each render may create a new cache entry.
+ *
+ * @example
+ * ```tsx
+ * // Always provide a queryKey for stable caching
+ * useFluxbaseQuery(
+ *   (client) => client.from('users').select('*'),
+ *   { queryKey: ['users', 'all'] }
+ * )
+ * ```
  */
 declare function useFluxbaseQuery<T = any>(buildQuery: (client: ReturnType<typeof useFluxbaseClient>) => QueryBuilder<T>, options?: UseFluxbaseQueryOptions<T>): _tanstack_react_query.UseQueryResult<T[], Error>;
 /**
  * Hook for table queries with a simpler API
  * @param table - Table name
- * @param buildQuery - Function to build the query
+ * @param buildQuery - Optional function to build the query (e.g., add filters)
+ * @param options - Query options including a stable queryKey
+ *
+ * NOTE: When using buildQuery with filters, provide a custom queryKey that includes
+ * the filter values to ensure proper caching.
+ *
+ * @example
+ * ```tsx
+ * // Simple query - queryKey is auto-generated from table name
+ * useTable('users')
+ *
+ * // With filters - provide queryKey including filter values
+ * useTable('users',
+ *   (q) => q.eq('status', 'active'),
+ *   { queryKey: ['users', 'active'] }
+ * )
+ * ```
  */
 declare function useTable<T = any>(table: string, buildQuery?: (query: QueryBuilder<T>) => QueryBuilder<T>, options?: UseFluxbaseQueryOptions<T>): _tanstack_react_query.UseQueryResult<T[], Error>;
 /**
@@ -693,6 +721,9 @@ interface UseRealtimeOptions {
 }
 /**
  * Hook to subscribe to realtime changes for a channel
+ *
+ * NOTE: The callback and invalidateKey are stored in refs to prevent
+ * subscription recreation on every render when inline functions/arrays are used.
  */
 declare function useRealtime(options: UseRealtimeOptions): {
     channel: _fluxbase_sdk.RealtimeChannel | null;

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode } from 'react';
 import * as _fluxbase_sdk from '@fluxbase/sdk';
-import { FluxbaseClient, User, AuthSession, SignInCredentials, SignUpCredentials, CaptchaConfig, CaptchaProvider, AuthConfig, SAMLProvider, SAMLLoginOptions, GraphQLRequestOptions, GraphQLError, GraphQLResponse, QueryBuilder, RealtimeCallback, RealtimePostgresChangesPayload, ListOptions, UploadOptions, UploadProgress, TransformOptions, SignedUrlOptions, AdminAuthResponse, ListUsersOptions, EnrichedUser, ClientKey, CreateClientKeyRequest, Webhook, CreateWebhookRequest, UpdateWebhookRequest, AppSettings, UpdateAppSettingsRequest, SystemSetting, UpdateSystemSettingRequest } from '@fluxbase/sdk';
+import { FluxbaseClient, User, AuthSession, SignInCredentials, SignUpCredentials, CaptchaConfig, CaptchaProvider, AuthConfig, SAMLLoginOptions, SAMLProvider, GraphQLRequestOptions, GraphQLError, GraphQLResponse, QueryBuilder, RealtimeCallback, RealtimePostgresChangesPayload, ListOptions, SignedUrlOptions, TransformOptions, UploadOptions, UploadProgress, AdminAuthResponse, ListUsersOptions, EnrichedUser, ClientKey, CreateClientKeyRequest, AppSettings, UpdateAppSettingsRequest, SystemSetting, UpdateSystemSettingRequest, Webhook, CreateWebhookRequest, UpdateWebhookRequest } from '@fluxbase/sdk';
 export { APIKey, AdminUser, AppSettings, AuthSession, CaptchaConfig, CaptchaProvider, ClientKey, EnrichedUser, FluxbaseClient, GraphQLError, GraphQLErrorLocation, GraphQLRequestOptions, GraphQLResponse, ImageFitMode, ImageFormat, PostgrestResponse, RealtimeChangePayload, SAMLLoginOptions, SAMLLoginResponse, SAMLProvider, SAMLProvidersResponse, SAMLSession, SignInCredentials, SignUpCredentials, SignedUrlOptions, StorageObject, SystemSetting, TransformOptions, User, Webhook } from '@fluxbase/sdk';
 import * as _tanstack_react_query from '@tanstack/react-query';
 import { UseQueryOptions } from '@tanstack/react-query';
@@ -634,12 +634,40 @@ interface UseFluxbaseQueryOptions<T> extends Omit<UseQueryOptions<T[], Error>, '
  * Hook to execute a database query
  * @param buildQuery - Function that builds and returns the query
  * @param options - React Query options
+ *
+ * IMPORTANT: You must provide a stable `queryKey` in options for proper caching.
+ * Without a custom queryKey, each render may create a new cache entry.
+ *
+ * @example
+ * ```tsx
+ * // Always provide a queryKey for stable caching
+ * useFluxbaseQuery(
+ *   (client) => client.from('users').select('*'),
+ *   { queryKey: ['users', 'all'] }
+ * )
+ * ```
  */
 declare function useFluxbaseQuery<T = any>(buildQuery: (client: ReturnType<typeof useFluxbaseClient>) => QueryBuilder<T>, options?: UseFluxbaseQueryOptions<T>): _tanstack_react_query.UseQueryResult<T[], Error>;
 /**
  * Hook for table queries with a simpler API
  * @param table - Table name
- * @param buildQuery - Function to build the query
+ * @param buildQuery - Optional function to build the query (e.g., add filters)
+ * @param options - Query options including a stable queryKey
+ *
+ * NOTE: When using buildQuery with filters, provide a custom queryKey that includes
+ * the filter values to ensure proper caching.
+ *
+ * @example
+ * ```tsx
+ * // Simple query - queryKey is auto-generated from table name
+ * useTable('users')
+ *
+ * // With filters - provide queryKey including filter values
+ * useTable('users',
+ *   (q) => q.eq('status', 'active'),
+ *   { queryKey: ['users', 'active'] }
+ * )
+ * ```
  */
 declare function useTable<T = any>(table: string, buildQuery?: (query: QueryBuilder<T>) => QueryBuilder<T>, options?: UseFluxbaseQueryOptions<T>): _tanstack_react_query.UseQueryResult<T[], Error>;
 /**
@@ -693,6 +721,9 @@ interface UseRealtimeOptions {
 }
 /**
  * Hook to subscribe to realtime changes for a channel
+ *
+ * NOTE: The callback and invalidateKey are stored in refs to prevent
+ * subscription recreation on every render when inline functions/arrays are used.
  */
 declare function useRealtime(options: UseRealtimeOptions): {
     channel: _fluxbase_sdk.RealtimeChannel | null;

package/dist/index.js

@@ -135,7 +135,7 @@ function useSignIn() {
     },
     onSuccess: (session) => {
       queryClient.setQueryData(["fluxbase", "auth", "session"], session);
-      if ("user" in session) {
+      if (session && "user" in session && session.user) {
         queryClient.setQueryData(["fluxbase", "auth", "user"], session.user);
       }
     }
@@ -506,7 +506,12 @@ function useGraphQL() {
 var import_react_query6 = require("@tanstack/react-query");
 function useFluxbaseQuery(buildQuery, options) {
   const client = useFluxbaseClient();
-  const queryKey = options?.queryKey || ["fluxbase", "query", buildQuery.toString()];
+  if (!options?.queryKey) {
+    console.warn(
+      "[useFluxbaseQuery] No queryKey provided. This may cause cache misses. Please provide a stable queryKey in options."
+    );
+  }
+  const queryKey = options?.queryKey || ["fluxbase", "query", "unstable"];
   return (0, import_react_query6.useQuery)({
     queryKey,
     queryFn: async () => {
@@ -522,6 +527,11 @@ function useFluxbaseQuery(buildQuery, options) {
 }
 function useTable(table, buildQuery, options) {
   const client = useFluxbaseClient();
+  if (buildQuery && !options?.queryKey) {
+    console.warn(
+      `[useTable] Using buildQuery without a custom queryKey for table "${table}". This may cause cache misses. Provide a queryKey that includes your filter values.`
+    );
+  }
   return useFluxbaseQuery(
     (client2) => {
       const query = client2.from(table);
@@ -529,7 +539,8 @@ function useTable(table, buildQuery, options) {
     },
     {
       ...options,
-      queryKey: options?.queryKey || ["fluxbase", "table", table, buildQuery?.toString()]
+      // Use table name as base key, or custom key if provided
+      queryKey: options?.queryKey || ["fluxbase", "table", table]
     }
   );
 }
@@ -620,6 +631,12 @@ function useRealtime(options) {
     invalidateKey,
     enabled = true
   } = options;
+  const callbackRef = (0, import_react3.useRef)(callback);
+  const invalidateKeyRef = (0, import_react3.useRef)(invalidateKey);
+  const autoInvalidateRef = (0, import_react3.useRef)(autoInvalidate);
+  callbackRef.current = callback;
+  invalidateKeyRef.current = invalidateKey;
+  autoInvalidateRef.current = autoInvalidate;
   (0, import_react3.useEffect)(() => {
     if (!enabled) {
       return;
@@ -627,12 +644,12 @@ function useRealtime(options) {
     const channel = client.realtime.channel(channelName);
     channelRef.current = channel;
     const handleChange = (payload) => {
-      if (callback) {
-        callback(payload);
+      if (callbackRef.current) {
+        callbackRef.current(payload);
       }
-      if (autoInvalidate) {
+      if (autoInvalidateRef.current) {
         const tableName = channelName.replace(/^table:/, "");
-        const key = invalidateKey || ["fluxbase", "table", tableName];
+        const key = invalidateKeyRef.current || ["fluxbase", "table", tableName];
         queryClient.invalidateQueries({ queryKey: key });
       }
     };
@@ -641,16 +658,7 @@ function useRealtime(options) {
       channel.unsubscribe();
       channelRef.current = null;
     };
-  }, [
-    client,
-    channelName,
-    event,
-    callback,
-    autoInvalidate,
-    invalidateKey,
-    queryClient,
-    enabled
-  ]);
+  }, [client, channelName, event, queryClient, enabled]);
   return {
     channel: channelRef.current
   };
@@ -827,8 +835,10 @@ function useStorageSignedUrl(bucket, path, expiresIn) {
       return data?.signedUrl || null;
     },
     enabled: !!path,
-    staleTime: expiresIn ? expiresIn * 1e3 - 6e4 : 1e3 * 60 * 50
-    // Refresh 1 minute before expiry
+    // Refresh 1 minute before expiry, but ensure staleTime is never negative
+    // For very short expirations (<60s), use half the expiration time
+    staleTime: expiresIn ? Math.max(expiresIn * 500, expiresIn * 1e3 - 6e4) : 1e3 * 60 * 50
+    // 50 minutes default
   });
 }
 function useStorageSignedUrlWithOptions(bucket, path, options) {
@@ -856,8 +866,10 @@ function useStorageSignedUrlWithOptions(bucket, path, options) {
       return data?.signedUrl || null;
     },
     enabled: !!path,
-    staleTime: expiresIn ? expiresIn * 1e3 - 6e4 : 1e3 * 60 * 50
-    // Refresh 1 minute before expiry
+    // Refresh 1 minute before expiry, but ensure staleTime is never negative
+    // For very short expirations (<60s), use half the expiration time
+    staleTime: expiresIn ? Math.max(expiresIn * 500, expiresIn * 1e3 - 6e4) : 1e3 * 60 * 50
+    // 50 minutes default
   });
 }
 function useStorageMove(bucket) {