@fluxbase/sdk-react 0.1.0-rc.1 → 2026.1.1-rc.10

package/src/use-graphql.ts

@@ -0,0 +1,392 @@
+/**
+ * GraphQL hooks for Fluxbase React SDK
+ *
+ * Provides React Query integration for GraphQL queries and mutations.
+ *
+ * @example
+ * ```tsx
+ * import { useGraphQLQuery, useGraphQLMutation } from '@fluxbase/sdk-react'
+ *
+ * function UsersList() {
+ *   const { data, isLoading, error } = useGraphQLQuery<UsersQuery>(
+ *     'users-list',
+ *     `query { users { id email } }`
+ *   )
+ *
+ *   if (isLoading) return <div>Loading...</div>
+ *   if (error) return <div>Error: {error.message}</div>
+ *
+ *   return (
+ *     <ul>
+ *       {data?.users.map(user => (
+ *         <li key={user.id}>{user.email}</li>
+ *       ))}
+ *     </ul>
+ *   )
+ * }
+ * ```
+ */
+
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { useFluxbaseClient } from "./context";
+import type {
+  GraphQLResponse,
+  GraphQLError,
+  GraphQLRequestOptions,
+} from "@fluxbase/sdk";
+
+/**
+ * Options for useGraphQLQuery hook
+ */
+export interface UseGraphQLQueryOptions<T> {
+  /**
+   * Variables to pass to the GraphQL query
+   */
+  variables?: Record<string, unknown>;
+
+  /**
+   * Operation name when the document contains multiple operations
+   */
+  operationName?: string;
+
+  /**
+   * Additional request options
+   */
+  requestOptions?: GraphQLRequestOptions;
+
+  /**
+   * Whether the query is enabled
+   * @default true
+   */
+  enabled?: boolean;
+
+  /**
+   * Time in milliseconds after which the query is considered stale
+   * @default 0 (considered stale immediately)
+   */
+  staleTime?: number;
+
+  /**
+   * Time in milliseconds after which inactive query data is garbage collected
+   * @default 5 minutes
+   */
+  gcTime?: number;
+
+  /**
+   * Whether to refetch on window focus
+   * @default true
+   */
+  refetchOnWindowFocus?: boolean;
+
+  /**
+   * Transform function to process the response data
+   */
+  select?: (data: T | undefined) => T | undefined;
+}
+
+/**
+ * Options for useGraphQLMutation hook
+ */
+export interface UseGraphQLMutationOptions<T, V> {
+  /**
+   * Operation name when the document contains multiple operations
+   */
+  operationName?: string;
+
+  /**
+   * Additional request options
+   */
+  requestOptions?: GraphQLRequestOptions;
+
+  /**
+   * Callback when mutation succeeds
+   */
+  onSuccess?: (data: T, variables: V) => void;
+
+  /**
+   * Callback when mutation fails
+   */
+  onError?: (error: GraphQLError, variables: V) => void;
+
+  /**
+   * Query keys to invalidate on success
+   */
+  invalidateQueries?: string[];
+}
+
+/**
+ * Hook to execute GraphQL queries with React Query caching
+ *
+ * @typeParam T - The expected response data type
+ * @param queryKey - Unique key for caching (string or array)
+ * @param query - The GraphQL query string
+ * @param options - Query options including variables
+ * @returns React Query result object
+ *
+ * @example
+ * ```tsx
+ * interface UsersQuery {
+ *   users: Array<{ id: string; email: string }>
+ * }
+ *
+ * function UsersList() {
+ *   const { data, isLoading } = useGraphQLQuery<UsersQuery>(
+ *     'users',
+ *     `query { users { id email } }`
+ *   )
+ *
+ *   return <div>{data?.users.length} users</div>
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With variables
+ * const { data } = useGraphQLQuery<UserQuery>(
+ *   ['user', userId],
+ *   `query GetUser($id: ID!) { user(id: $id) { id email } }`,
+ *   { variables: { id: userId } }
+ * )
+ * ```
+ */
+export function useGraphQLQuery<T = unknown>(
+  queryKey: string | readonly unknown[],
+  query: string,
+  options?: UseGraphQLQueryOptions<T>
+) {
+  const client = useFluxbaseClient();
+  const normalizedKey = Array.isArray(queryKey)
+    ? ["fluxbase", "graphql", ...queryKey]
+    : ["fluxbase", "graphql", queryKey];
+
+  return useQuery<T | undefined, GraphQLError>({
+    queryKey: normalizedKey,
+    queryFn: async () => {
+      const response: GraphQLResponse<T> = await client.graphql.execute(
+        query,
+        options?.variables,
+        options?.operationName,
+        options?.requestOptions
+      );
+
+      if (response.errors && response.errors.length > 0) {
+        throw response.errors[0];
+      }
+
+      return response.data;
+    },
+    enabled: options?.enabled ?? true,
+    staleTime: options?.staleTime ?? 0,
+    gcTime: options?.gcTime,
+    refetchOnWindowFocus: options?.refetchOnWindowFocus ?? true,
+    select: options?.select,
+  });
+}
+
+/**
+ * Hook to execute GraphQL mutations
+ *
+ * @typeParam T - The expected response data type
+ * @typeParam V - The variables type
+ * @param mutation - The GraphQL mutation string
+ * @param options - Mutation options
+ * @returns React Query mutation result object
+ *
+ * @example
+ * ```tsx
+ * interface CreateUserMutation {
+ *   insertUser: { id: string; email: string }
+ * }
+ *
+ * interface CreateUserVariables {
+ *   data: { email: string }
+ * }
+ *
+ * function CreateUserForm() {
+ *   const mutation = useGraphQLMutation<CreateUserMutation, CreateUserVariables>(
+ *     `mutation CreateUser($data: UserInput!) {
+ *       insertUser(data: $data) { id email }
+ *     }`,
+ *     {
+ *       onSuccess: (data) => console.log('Created:', data.insertUser),
+ *       invalidateQueries: ['users']
+ *     }
+ *   )
+ *
+ *   const handleSubmit = (email: string) => {
+ *     mutation.mutate({ data: { email } })
+ *   }
+ *
+ *   return (
+ *     <button
+ *       onClick={() => handleSubmit('new@example.com')}
+ *       disabled={mutation.isPending}
+ *     >
+ *       Create User
+ *     </button>
+ *   )
+ * }
+ * ```
+ */
+export function useGraphQLMutation<
+  T = unknown,
+  V extends Record<string, unknown> = Record<string, unknown>,
+>(mutation: string, options?: UseGraphQLMutationOptions<T, V>) {
+  const client = useFluxbaseClient();
+  const queryClient = useQueryClient();
+
+  return useMutation<T | undefined, GraphQLError, V>({
+    mutationFn: async (variables: V) => {
+      const response: GraphQLResponse<T> = await client.graphql.execute(
+        mutation,
+        variables,
+        options?.operationName,
+        options?.requestOptions
+      );
+
+      if (response.errors && response.errors.length > 0) {
+        throw response.errors[0];
+      }
+
+      return response.data;
+    },
+    onSuccess: (data, variables) => {
+      // Invalidate specified queries
+      if (options?.invalidateQueries) {
+        for (const key of options.invalidateQueries) {
+          queryClient.invalidateQueries({
+            queryKey: ["fluxbase", "graphql", key],
+          });
+        }
+      }
+
+      // Call user's onSuccess callback
+      if (options?.onSuccess && data !== undefined) {
+        options.onSuccess(data, variables);
+      }
+    },
+    onError: (error, variables) => {
+      if (options?.onError) {
+        options.onError(error, variables);
+      }
+    },
+  });
+}
+
+/**
+ * Hook to fetch the GraphQL schema via introspection
+ *
+ * @param options - Query options
+ * @returns React Query result with schema introspection data
+ *
+ * @example
+ * ```tsx
+ * function SchemaExplorer() {
+ *   const { data, isLoading } = useGraphQLIntrospection()
+ *
+ *   if (isLoading) return <div>Loading schema...</div>
+ *
+ *   return (
+ *     <div>
+ *       <p>Query type: {data?.__schema.queryType.name}</p>
+ *       <p>Types: {data?.__schema.types.length}</p>
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+export function useGraphQLIntrospection(options?: {
+  enabled?: boolean;
+  staleTime?: number;
+  requestOptions?: GraphQLRequestOptions;
+}) {
+  const client = useFluxbaseClient();
+
+  return useQuery({
+    queryKey: ["fluxbase", "graphql", "__introspection"],
+    queryFn: async () => {
+      const response = await client.graphql.introspect(options?.requestOptions);
+
+      if (response.errors && response.errors.length > 0) {
+        throw response.errors[0];
+      }
+
+      return response.data;
+    },
+    enabled: options?.enabled ?? true,
+    staleTime: options?.staleTime ?? 1000 * 60 * 5, // 5 minutes - schema doesn't change often
+  });
+}
+
+/**
+ * Hook to execute raw GraphQL operations (query or mutation)
+ *
+ * This is a lower-level hook that doesn't use React Query caching.
+ * Useful for one-off operations or when you need full control.
+ *
+ * @returns Functions to execute queries and mutations
+ *
+ * @example
+ * ```tsx
+ * function AdminPanel() {
+ *   const { executeQuery, executeMutation } = useGraphQL()
+ *
+ *   const handleExport = async () => {
+ *     const result = await executeQuery<ExportData>(
+ *       `query { exportAllData { url } }`
+ *     )
+ *     if (result.data) {
+ *       window.open(result.data.exportAllData.url)
+ *     }
+ *   }
+ *
+ *   return <button onClick={handleExport}>Export Data</button>
+ * }
+ * ```
+ */
+export function useGraphQL() {
+  const client = useFluxbaseClient();
+
+  return {
+    /**
+     * Execute a GraphQL query
+     */
+    executeQuery: <T = unknown>(
+      query: string,
+      variables?: Record<string, unknown>,
+      options?: GraphQLRequestOptions
+    ): Promise<GraphQLResponse<T>> => {
+      return client.graphql.query<T>(query, variables, options);
+    },
+
+    /**
+     * Execute a GraphQL mutation
+     */
+    executeMutation: <T = unknown>(
+      mutation: string,
+      variables?: Record<string, unknown>,
+      options?: GraphQLRequestOptions
+    ): Promise<GraphQLResponse<T>> => {
+      return client.graphql.mutation<T>(mutation, variables, options);
+    },
+
+    /**
+     * Execute a GraphQL operation with an explicit operation name
+     */
+    execute: <T = unknown>(
+      document: string,
+      variables?: Record<string, unknown>,
+      operationName?: string,
+      options?: GraphQLRequestOptions
+    ): Promise<GraphQLResponse<T>> => {
+      return client.graphql.execute<T>(document, variables, operationName, options);
+    },
+
+    /**
+     * Fetch the GraphQL schema via introspection
+     */
+    introspect: (options?: GraphQLRequestOptions) => {
+      return client.graphql.introspect(options);
+    },
+  };
+}

package/src/use-realtime.ts

@@ -2,99 +2,113 @@
  * Realtime subscription hooks for Fluxbase SDK
  */
 
-import { useEffect, useRef } from 'react'
-import { useQueryClient } from '@tanstack/react-query'
-import { useFluxbaseClient } from './context'
-import type { RealtimeCallback, RealtimeChangePayload } from '@fluxbase/sdk'
+import { useEffect, useRef } from "react";
+import { useQueryClient } from "@tanstack/react-query";
+import { useFluxbaseClient } from "./context";
+import type {
+  RealtimeCallback,
+  RealtimePostgresChangesPayload,
+} from "@fluxbase/sdk";
 
 export interface UseRealtimeOptions {
   /**
    * The channel name (e.g., 'table:public.products')
    */
-  channel: string
+  channel: string;
 
   /**
    * Event type to listen for ('INSERT', 'UPDATE', 'DELETE', or '*' for all)
    */
-  event?: 'INSERT' | 'UPDATE' | 'DELETE' | '*'
+  event?: "INSERT" | "UPDATE" | "DELETE" | "*";
 
   /**
    * Callback function when an event is received
    */
-  callback?: RealtimeCallback
+  callback?: RealtimeCallback;
 
   /**
    * Whether to automatically invalidate queries for the table
    * Default: true
    */
-  autoInvalidate?: boolean
+  autoInvalidate?: boolean;
 
   /**
    * Custom query key to invalidate (if autoInvalidate is true)
    * Default: ['fluxbase', 'table', tableName]
    */
-  invalidateKey?: unknown[]
+  invalidateKey?: unknown[];
 
   /**
    * Whether the subscription is enabled
    * Default: true
    */
-  enabled?: boolean
+  enabled?: boolean;
 }
 
 /**
  * Hook to subscribe to realtime changes for a channel
  */
 export function useRealtime(options: UseRealtimeOptions) {
-  const client = useFluxbaseClient()
-  const queryClient = useQueryClient()
-  const channelRef = useRef<ReturnType<typeof client.realtime.channel> | null>(null)
+  const client = useFluxbaseClient();
+  const queryClient = useQueryClient();
+  const channelRef = useRef<ReturnType<typeof client.realtime.channel> | null>(
+    null,
+  );
 
   const {
     channel: channelName,
-    event = '*',
+    event = "*",
     callback,
     autoInvalidate = true,
     invalidateKey,
     enabled = true,
-  } = options
+  } = options;
 
   useEffect(() => {
     if (!enabled) {
-      return
+      return;
     }
 
     // Create channel and subscribe
-    const channel = client.realtime.channel(channelName)
-    channelRef.current = channel
+    const channel = client.realtime.channel(channelName);
+    channelRef.current = channel;
 
-    const handleChange = (payload: RealtimeChangePayload) => {
+    const handleChange = (payload: RealtimePostgresChangesPayload) => {
       // Call user callback
       if (callback) {
-        callback(payload)
+        callback(payload);
       }
 
       // Auto-invalidate queries if enabled
       if (autoInvalidate) {
         // Extract table name from channel (e.g., 'table:public.products' -> 'public.products')
-        const tableName = channelName.replace(/^table:/, '')
+        const tableName = channelName.replace(/^table:/, "");
 
-        const key = invalidateKey || ['fluxbase', 'table', tableName]
-        queryClient.invalidateQueries({ queryKey: key })
+        const key = invalidateKey || ["fluxbase", "table", tableName];
+        queryClient.invalidateQueries({ queryKey: key });
       }
-    }
+    };
 
-    channel.on(event, handleChange).subscribe()
+    channel.on(event, handleChange).subscribe();
 
     return () => {
-      channel.unsubscribe()
-      channelRef.current = null
-    }
-  }, [client, channelName, event, callback, autoInvalidate, invalidateKey, queryClient, enabled])
+      channel.unsubscribe();
+      channelRef.current = null;
+    };
+  }, [
+    client,
+    channelName,
+    event,
+    callback,
+    autoInvalidate,
+    invalidateKey,
+    queryClient,
+    enabled,
+  ]);
 
   return {
     channel: channelRef.current,
-  }
+  };
 }
 
 /**
@@ -104,12 +118,12 @@ export function useRealtime(options: UseRealtimeOptions) {
  */
 export function useTableSubscription(
   table: string,
-  options?: Omit<UseRealtimeOptions, 'channel'>
+  options?: Omit<UseRealtimeOptions, "channel">,
 ) {
   return useRealtime({
     ...options,
     channel: `table:${table}`,
-  })
+  });
 }
 
 /**
@@ -117,15 +131,15 @@ export function useTableSubscription(
  */
 export function useTableInserts(
   table: string,
-  callback: (payload: RealtimeChangePayload) => void,
-  options?: Omit<UseRealtimeOptions, 'channel' | 'event' | 'callback'>
+  callback: (payload: RealtimePostgresChangesPayload) => void,
+  options?: Omit<UseRealtimeOptions, "channel" | "event" | "callback">,
 ) {
   return useRealtime({
     ...options,
     channel: `table:${table}`,
-    event: 'INSERT',
+    event: "INSERT",
     callback,
-  })
+  });
 }
 
 /**
@@ -133,15 +147,15 @@ export function useTableInserts(
  */
 export function useTableUpdates(
   table: string,
-  callback: (payload: RealtimeChangePayload) => void,
-  options?: Omit<UseRealtimeOptions, 'channel' | 'event' | 'callback'>
+  callback: (payload: RealtimePostgresChangesPayload) => void,
+  options?: Omit<UseRealtimeOptions, "channel" | "event" | "callback">,
 ) {
   return useRealtime({
     ...options,
     channel: `table:${table}`,
-    event: 'UPDATE',
+    event: "UPDATE",
     callback,
-  })
+  });
 }
 
 /**
@@ -149,13 +163,13 @@ export function useTableUpdates(
  */
 export function useTableDeletes(
   table: string,
-  callback: (payload: RealtimeChangePayload) => void,
-  options?: Omit<UseRealtimeOptions, 'channel' | 'event' | 'callback'>
+  callback: (payload: RealtimePostgresChangesPayload) => void,
+  options?: Omit<UseRealtimeOptions, "channel" | "event" | "callback">,
 ) {
   return useRealtime({
     ...options,
     channel: `table:${table}`,
-    event: 'DELETE',
+    event: "DELETE",
     callback,
-  })
+  });
 }