@fluxbase/sdk-react 0.0.1-rc.2

package/src/use-query.ts

@@ -0,0 +1,165 @@
+/**
+ * Database query hooks for Fluxbase SDK
+ */
+
+import { useQuery, useMutation, useQueryClient, type UseQueryOptions } from '@tanstack/react-query'
+import { useFluxbaseClient } from './context'
+import type { QueryBuilder } from '@fluxbase/sdk'
+
+export interface UseFluxbaseQueryOptions<T> extends Omit<UseQueryOptions<T[], Error>, 'queryKey' | 'queryFn'> {
+  /**
+   * Custom query key. If not provided, will use table name and filters.
+   */
+  queryKey?: unknown[]
+}
+
+/**
+ * Hook to execute a database query
+ * @param buildQuery - Function that builds and returns the query
+ * @param options - React Query options
+ */
+export function useFluxbaseQuery<T = any>(
+  buildQuery: (client: ReturnType<typeof useFluxbaseClient>) => QueryBuilder<T>,
+  options?: UseFluxbaseQueryOptions<T>
+) {
+  const client = useFluxbaseClient()
+
+  // Build a stable query key
+  const queryKey = options?.queryKey || ['fluxbase', 'query', buildQuery.toString()]
+
+  return useQuery({
+    queryKey,
+    queryFn: async () => {
+      const query = buildQuery(client)
+      const { data, error } = await query.execute()
+
+      if (error) {
+        throw error
+      }
+
+      return (Array.isArray(data) ? data : data ? [data] : []) as T[]
+    },
+    ...options,
+  })
+}
+
+/**
+ * Hook for table queries with a simpler API
+ * @param table - Table name
+ * @param buildQuery - Function to build the query
+ */
+export function useTable<T = any>(
+  table: string,
+  buildQuery?: (query: QueryBuilder<T>) => QueryBuilder<T>,
+  options?: UseFluxbaseQueryOptions<T>
+) {
+  const client = useFluxbaseClient()
+
+  return useFluxbaseQuery(
+    (client) => {
+      const query = client.from<T>(table)
+      return buildQuery ? buildQuery(query) : query
+    },
+    {
+      ...options,
+      queryKey: options?.queryKey || ['fluxbase', 'table', table, buildQuery?.toString()],
+    }
+  )
+}
+
+/**
+ * Hook to insert data into a table
+ */
+export function useInsert<T = any>(table: string) {
+  const client = useFluxbaseClient()
+  const queryClient = useQueryClient()
+
+  return useMutation({
+    mutationFn: async (data: Partial<T> | Partial<T>[]) => {
+      const query = client.from<T>(table)
+      const { data: result, error } = await query.insert(data as Partial<T>)
+
+      if (error) {
+        throw error
+      }
+
+      return result
+    },
+    onSuccess: () => {
+      // Invalidate all queries for this table
+      queryClient.invalidateQueries({ queryKey: ['fluxbase', 'table', table] })
+    },
+  })
+}
+
+/**
+ * Hook to update data in a table
+ */
+export function useUpdate<T = any>(table: string) {
+  const client = useFluxbaseClient()
+  const queryClient = useQueryClient()
+
+  return useMutation({
+    mutationFn: async (params: { data: Partial<T>; buildQuery: (query: QueryBuilder<T>) => QueryBuilder<T> }) => {
+      const query = client.from<T>(table)
+      const builtQuery = params.buildQuery(query)
+      const { data: result, error } = await builtQuery.update(params.data)
+
+      if (error) {
+        throw error
+      }
+
+      return result
+    },
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['fluxbase', 'table', table] })
+    },
+  })
+}
+
+/**
+ * Hook to upsert data into a table
+ */
+export function useUpsert<T = any>(table: string) {
+  const client = useFluxbaseClient()
+  const queryClient = useQueryClient()
+
+  return useMutation({
+    mutationFn: async (data: Partial<T> | Partial<T>[]) => {
+      const query = client.from<T>(table)
+      const { data: result, error } = await query.upsert(data as Partial<T>)
+
+      if (error) {
+        throw error
+      }
+
+      return result
+    },
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['fluxbase', 'table', table] })
+    },
+  })
+}
+
+/**
+ * Hook to delete data from a table
+ */
+export function useDelete<T = any>(table: string) {
+  const client = useFluxbaseClient()
+  const queryClient = useQueryClient()
+
+  return useMutation({
+    mutationFn: async (buildQuery: (query: QueryBuilder<T>) => QueryBuilder<T>) => {
+      const query = client.from<T>(table)
+      const builtQuery = buildQuery(query)
+      const { error } = await builtQuery.delete()
+
+      if (error) {
+        throw error
+      }
+    },
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['fluxbase', 'table', table] })
+    },
+  })
+}

package/src/use-realtime.ts

@@ -0,0 +1,161 @@
+/**
+ * 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'
+
+export interface UseRealtimeOptions {
+  /**
+   * The channel name (e.g., 'table:public.products')
+   */
+  channel: string
+
+  /**
+   * Event type to listen for ('INSERT', 'UPDATE', 'DELETE', or '*' for all)
+   */
+  event?: 'INSERT' | 'UPDATE' | 'DELETE' | '*'
+
+  /**
+   * Callback function when an event is received
+   */
+  callback?: RealtimeCallback
+
+  /**
+   * Whether to automatically invalidate queries for the table
+   * Default: true
+   */
+  autoInvalidate?: boolean
+
+  /**
+   * Custom query key to invalidate (if autoInvalidate is true)
+   * Default: ['fluxbase', 'table', tableName]
+   */
+  invalidateKey?: unknown[]
+
+  /**
+   * Whether the subscription is enabled
+   * Default: true
+   */
+  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 {
+    channel: channelName,
+    event = '*',
+    callback,
+    autoInvalidate = true,
+    invalidateKey,
+    enabled = true,
+  } = options
+
+  useEffect(() => {
+    if (!enabled) {
+      return
+    }
+
+    // Create channel and subscribe
+    const channel = client.realtime.channel(channelName)
+    channelRef.current = channel
+
+    const handleChange = (payload: RealtimeChangePayload) => {
+      // Call user callback
+      if (callback) {
+        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 key = invalidateKey || ['fluxbase', 'table', tableName]
+        queryClient.invalidateQueries({ queryKey: key })
+      }
+    }
+
+    channel.on(event, handleChange).subscribe()
+
+    return () => {
+      channel.unsubscribe()
+      channelRef.current = null
+    }
+  }, [client, channelName, event, callback, autoInvalidate, invalidateKey, queryClient, enabled])
+
+  return {
+    channel: channelRef.current,
+  }
+}
+
+/**
+ * Hook to subscribe to a table's changes
+ * @param table - Table name (with optional schema, e.g., 'public.products')
+ * @param options - Subscription options
+ */
+export function useTableSubscription(
+  table: string,
+  options?: Omit<UseRealtimeOptions, 'channel'>
+) {
+  return useRealtime({
+    ...options,
+    channel: `table:${table}`,
+  })
+}
+
+/**
+ * Hook to subscribe to INSERT events on a table
+ */
+export function useTableInserts(
+  table: string,
+  callback: (payload: RealtimeChangePayload) => void,
+  options?: Omit<UseRealtimeOptions, 'channel' | 'event' | 'callback'>
+) {
+  return useRealtime({
+    ...options,
+    channel: `table:${table}`,
+    event: 'INSERT',
+    callback,
+  })
+}
+
+/**
+ * Hook to subscribe to UPDATE events on a table
+ */
+export function useTableUpdates(
+  table: string,
+  callback: (payload: RealtimeChangePayload) => void,
+  options?: Omit<UseRealtimeOptions, 'channel' | 'event' | 'callback'>
+) {
+  return useRealtime({
+    ...options,
+    channel: `table:${table}`,
+    event: 'UPDATE',
+    callback,
+  })
+}
+
+/**
+ * Hook to subscribe to DELETE events on a table
+ */
+export function useTableDeletes(
+  table: string,
+  callback: (payload: RealtimeChangePayload) => void,
+  options?: Omit<UseRealtimeOptions, 'channel' | 'event' | 'callback'>
+) {
+  return useRealtime({
+    ...options,
+    channel: `table:${table}`,
+    event: 'DELETE',
+    callback,
+  })
+}

package/src/use-rpc.ts

@@ -0,0 +1,109 @@
+/**
+ * React hooks for RPC (Remote Procedure Calls)
+ * Call PostgreSQL functions with React Query integration
+ */
+
+import { useQuery, useMutation, useQueryClient, type UseQueryOptions, type UseMutationOptions } from '@tanstack/react-query'
+import { useFluxbaseClient } from './context'
+import type { PostgrestResponse } from '@fluxbase/sdk'
+
+/**
+ * Hook to call a PostgreSQL function and cache the result
+ *
+ * @example
+ * ```tsx
+ * const { data, isLoading, error } = useRPC(
+ *   'calculate_total',
+ *   { order_id: 123 },
+ *   { enabled: !!orderId }
+ * )
+ * ```
+ */
+export function useRPC<TData = unknown, TParams extends Record<string, unknown> = Record<string, unknown>>(
+  functionName: string,
+  params?: TParams,
+  options?: Omit<UseQueryOptions<TData, Error>, 'queryKey' | 'queryFn'>
+) {
+  const client = useFluxbaseClient()
+
+  return useQuery<TData, Error>({
+    queryKey: ['rpc', functionName, params],
+    queryFn: async () => {
+      const { data, error } = await client.rpc<TData>(functionName, params)
+      if (error) {
+        throw new Error(error.message)
+      }
+      return data as TData
+    },
+    ...options,
+  })
+}
+
+/**
+ * Hook to create a mutation for calling PostgreSQL functions
+ * Useful for functions that modify data
+ *
+ * @example
+ * ```tsx
+ * const createOrder = useRPCMutation('create_order')
+ *
+ * const handleSubmit = async () => {
+ *   await createOrder.mutateAsync({
+ *     user_id: 123,
+ *     items: [{ product_id: 1, quantity: 2 }]
+ *   })
+ * }
+ * ```
+ */
+export function useRPCMutation<TData = unknown, TParams extends Record<string, unknown> = Record<string, unknown>>(
+  functionName: string,
+  options?: Omit<UseMutationOptions<TData, Error, TParams>, 'mutationFn'>
+) {
+  const client = useFluxbaseClient()
+
+  return useMutation<TData, Error, TParams>({
+    mutationFn: async (params: TParams) => {
+      const { data, error } = await client.rpc<TData>(functionName, params)
+      if (error) {
+        throw new Error(error.message)
+      }
+      return data as TData
+    },
+    ...options,
+  })
+}
+
+/**
+ * Hook to call multiple RPC functions in parallel
+ *
+ * @example
+ * ```tsx
+ * const { data, isLoading } = useRPCBatch([
+ *   { name: 'get_user_stats', params: { user_id: 123 } },
+ *   { name: 'get_recent_orders', params: { limit: 10 } },
+ * ])
+ * ```
+ */
+export function useRPCBatch<TData = unknown>(
+  calls: Array<{ name: string; params?: Record<string, unknown> }>,
+  options?: Omit<UseQueryOptions<TData[], Error, TData[], readonly unknown[]>, 'queryKey' | 'queryFn'>
+) {
+  const client = useFluxbaseClient()
+
+  return useQuery({
+    queryKey: ['rpc-batch', calls] as const,
+    queryFn: async () => {
+      const results = await Promise.all(
+        calls.map(async ({ name, params }) => {
+          const { data, error } = await client.rpc<TData>(name, params)
+          if (error) {
+            throw new Error(`${name}: ${error.message}`)
+          }
+          return data
+        })
+      )
+      return results as TData[]
+    },
+    ...options,
+  })
+}

package/src/use-storage.ts

@@ -0,0 +1,257 @@
+/**
+ * Storage hooks for Fluxbase SDK
+ */
+
+import { useMutation, useQuery, useQueryClient, type UseQueryOptions } from '@tanstack/react-query'
+import { useFluxbaseClient } from './context'
+import type { ListOptions, UploadOptions } from '@fluxbase/sdk'
+
+/**
+ * Hook to list files in a bucket
+ */
+export function useStorageList(
+  bucket: string,
+  options?: ListOptions & Omit<UseQueryOptions<any[], Error>, 'queryKey' | 'queryFn'>
+) {
+  const client = useFluxbaseClient()
+  const { prefix, limit, offset, ...queryOptions } = options || {}
+
+  return useQuery({
+    queryKey: ['fluxbase', 'storage', bucket, 'list', { prefix, limit, offset }],
+    queryFn: async () => {
+      const { data, error } = await client.storage.from(bucket).list({ prefix, limit, offset })
+
+      if (error) {
+        throw error
+      }
+
+      return data || []
+    },
+    ...queryOptions,
+  })
+}
+
+/**
+ * Hook to upload a file to a bucket
+ */
+export function useStorageUpload(bucket: string) {
+  const client = useFluxbaseClient()
+  const queryClient = useQueryClient()
+
+  return useMutation({
+    mutationFn: async (params: {
+      path: string
+      file: File | Blob | ArrayBuffer
+      options?: UploadOptions
+    }) => {
+      const { path, file, options } = params
+      const { data, error } = await client.storage.from(bucket).upload(path, file, options)
+
+      if (error) {
+        throw error
+      }
+
+      return data
+    },
+    onSuccess: () => {
+      // Invalidate list queries for this bucket
+      queryClient.invalidateQueries({ queryKey: ['fluxbase', 'storage', bucket, 'list'] })
+    },
+  })
+}
+
+/**
+ * Hook to download a file from a bucket
+ */
+export function useStorageDownload(bucket: string, path: string | null, enabled = true) {
+  const client = useFluxbaseClient()
+
+  return useQuery({
+    queryKey: ['fluxbase', 'storage', bucket, 'download', path],
+    queryFn: async () => {
+      if (!path) {
+        return null
+      }
+
+      const { data, error } = await client.storage.from(bucket).download(path)
+
+      if (error) {
+        throw error
+      }
+
+      return data
+    },
+    enabled: enabled && !!path,
+  })
+}
+
+/**
+ * Hook to delete files from a bucket
+ */
+export function useStorageDelete(bucket: string) {
+  const client = useFluxbaseClient()
+  const queryClient = useQueryClient()
+
+  return useMutation({
+    mutationFn: async (paths: string[]) => {
+      const { error } = await client.storage.from(bucket).remove(paths)
+
+      if (error) {
+        throw error
+      }
+    },
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['fluxbase', 'storage', bucket, 'list'] })
+    },
+  })
+}
+
+/**
+ * Hook to get a public URL for a file
+ */
+export function useStoragePublicUrl(bucket: string, path: string | null) {
+  const client = useFluxbaseClient()
+
+  if (!path) {
+    return null
+  }
+
+  const { data } = client.storage.from(bucket).getPublicUrl(path)
+  return data.publicUrl
+}
+
+/**
+ * Hook to create a signed URL
+ */
+export function useStorageSignedUrl(bucket: string, path: string | null, expiresIn?: number) {
+  const client = useFluxbaseClient()
+
+  return useQuery({
+    queryKey: ['fluxbase', 'storage', bucket, 'signed-url', path, expiresIn],
+    queryFn: async () => {
+      if (!path) {
+        return null
+      }
+
+      const { data, error } = await client.storage.from(bucket).createSignedUrl(path, { expiresIn })
+
+      if (error) {
+        throw error
+      }
+
+      return data?.signedUrl || null
+    },
+    enabled: !!path,
+    staleTime: expiresIn ? expiresIn * 1000 - 60000 : 1000 * 60 * 50, // Refresh 1 minute before expiry
+  })
+}
+
+/**
+ * Hook to move a file
+ */
+export function useStorageMove(bucket: string) {
+  const client = useFluxbaseClient()
+  const queryClient = useQueryClient()
+
+  return useMutation({
+    mutationFn: async (params: { fromPath: string; toPath: string }) => {
+      const { fromPath, toPath } = params
+      const { data, error } = await client.storage.from(bucket).move(fromPath, toPath)
+
+      if (error) {
+        throw error
+      }
+
+      return data
+    },
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['fluxbase', 'storage', bucket, 'list'] })
+    },
+  })
+}
+
+/**
+ * Hook to copy a file
+ */
+export function useStorageCopy(bucket: string) {
+  const client = useFluxbaseClient()
+  const queryClient = useQueryClient()
+
+  return useMutation({
+    mutationFn: async (params: { fromPath: string; toPath: string }) => {
+      const { fromPath, toPath } = params
+      const { data, error } = await client.storage.from(bucket).copy(fromPath, toPath)
+
+      if (error) {
+        throw error
+      }
+
+      return data
+    },
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['fluxbase', 'storage', bucket, 'list'] })
+    },
+  })
+}
+
+/**
+ * Hook to manage buckets
+ */
+export function useStorageBuckets() {
+  const client = useFluxbaseClient()
+
+  return useQuery({
+    queryKey: ['fluxbase', 'storage', 'buckets'],
+    queryFn: async () => {
+      const { data, error } = await client.storage.listBuckets()
+
+      if (error) {
+        throw error
+      }
+
+      return data || []
+    },
+  })
+}
+
+/**
+ * Hook to create a bucket
+ */
+export function useCreateBucket() {
+  const client = useFluxbaseClient()
+  const queryClient = useQueryClient()
+
+  return useMutation({
+    mutationFn: async (bucketName: string) => {
+      const { error } = await client.storage.createBucket(bucketName)
+
+      if (error) {
+        throw error
+      }
+    },
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['fluxbase', 'storage', 'buckets'] })
+    },
+  })
+}
+
+/**
+ * Hook to delete a bucket
+ */
+export function useDeleteBucket() {
+  const client = useFluxbaseClient()
+  const queryClient = useQueryClient()
+
+  return useMutation({
+    mutationFn: async (bucketName: string) => {
+      const { error } = await client.storage.deleteBucket(bucketName)
+
+      if (error) {
+        throw error
+      }
+    },
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['fluxbase', 'storage', 'buckets'] })
+    },
+  })
+}