@fluxbase/sdk-react 2026.1.22 → 2026.2.1

package/src/use-realtime.test.ts

@@ -0,0 +1,359 @@
+/**
+ * Tests for realtime subscription hooks
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { renderHook, waitFor, act } from '@testing-library/react';
+import {
+  useRealtime,
+  useTableSubscription,
+  useTableInserts,
+  useTableUpdates,
+  useTableDeletes,
+} from './use-realtime';
+import { createMockClient, createWrapper, createTestQueryClient } from './test-utils';
+
+describe('useRealtime', () => {
+  it('should create channel and subscribe', () => {
+    const onMock = vi.fn().mockReturnThis();
+    const subscribeMock = vi.fn().mockReturnThis();
+    const unsubscribeMock = vi.fn();
+    const channelMock = vi.fn().mockReturnValue({
+      on: onMock,
+      subscribe: subscribeMock,
+      unsubscribe: unsubscribeMock,
+    });
+
+    const client = createMockClient({
+      realtime: { channel: channelMock },
+    } as any);
+
+    renderHook(
+      () => useRealtime({ channel: 'table:products' }),
+      { wrapper: createWrapper(client) }
+    );
+
+    expect(channelMock).toHaveBeenCalledWith('table:products');
+    expect(onMock).toHaveBeenCalledWith('*', expect.any(Function));
+    expect(subscribeMock).toHaveBeenCalled();
+  });
+
+  it('should unsubscribe on unmount', () => {
+    const onMock = vi.fn().mockReturnThis();
+    const subscribeMock = vi.fn().mockReturnThis();
+    const unsubscribeMock = vi.fn();
+    const channelMock = vi.fn().mockReturnValue({
+      on: onMock,
+      subscribe: subscribeMock,
+      unsubscribe: unsubscribeMock,
+    });
+
+    const client = createMockClient({
+      realtime: { channel: channelMock },
+    } as any);
+
+    const { unmount } = renderHook(
+      () => useRealtime({ channel: 'table:products' }),
+      { wrapper: createWrapper(client) }
+    );
+
+    unmount();
+
+    expect(unsubscribeMock).toHaveBeenCalled();
+  });
+
+  it('should not subscribe when disabled', () => {
+    const channelMock = vi.fn();
+    const client = createMockClient({
+      realtime: { channel: channelMock },
+    } as any);
+
+    renderHook(
+      () => useRealtime({ channel: 'table:products', enabled: false }),
+      { wrapper: createWrapper(client) }
+    );
+
+    expect(channelMock).not.toHaveBeenCalled();
+  });
+
+  it('should subscribe to specific event type', () => {
+    const onMock = vi.fn().mockReturnThis();
+    const subscribeMock = vi.fn().mockReturnThis();
+    const channelMock = vi.fn().mockReturnValue({
+      on: onMock,
+      subscribe: subscribeMock,
+      unsubscribe: vi.fn(),
+    });
+
+    const client = createMockClient({
+      realtime: { channel: channelMock },
+    } as any);
+
+    renderHook(
+      () => useRealtime({ channel: 'table:products', event: 'INSERT' }),
+      { wrapper: createWrapper(client) }
+    );
+
+    expect(onMock).toHaveBeenCalledWith('INSERT', expect.any(Function));
+  });
+
+  it('should call callback on change', () => {
+    const callback = vi.fn();
+    let changeHandler: Function;
+    const onMock = vi.fn().mockImplementation((event, handler) => {
+      changeHandler = handler;
+      return { subscribe: vi.fn().mockReturnThis(), unsubscribe: vi.fn() };
+    });
+    const channelMock = vi.fn().mockReturnValue({
+      on: onMock,
+      subscribe: vi.fn().mockReturnThis(),
+      unsubscribe: vi.fn(),
+    });
+
+    const client = createMockClient({
+      realtime: { channel: channelMock },
+    } as any);
+
+    renderHook(
+      () => useRealtime({ channel: 'table:products', callback }),
+      { wrapper: createWrapper(client) }
+    );
+
+    const payload = { eventType: 'INSERT', new: { id: 1 }, old: null };
+    changeHandler!(payload);
+
+    expect(callback).toHaveBeenCalledWith(payload);
+  });
+
+  it('should auto-invalidate queries when enabled', () => {
+    let changeHandler: Function;
+    const onMock = vi.fn().mockImplementation((event, handler) => {
+      changeHandler = handler;
+      return { subscribe: vi.fn().mockReturnThis(), unsubscribe: vi.fn() };
+    });
+    const channelMock = vi.fn().mockReturnValue({
+      on: onMock,
+      subscribe: vi.fn().mockReturnThis(),
+      unsubscribe: vi.fn(),
+    });
+
+    const client = createMockClient({
+      realtime: { channel: channelMock },
+    } as any);
+
+    const queryClient = createTestQueryClient();
+    const invalidateSpy = vi.spyOn(queryClient, 'invalidateQueries');
+
+    renderHook(
+      () => useRealtime({ channel: 'table:public.products', autoInvalidate: true }),
+      { wrapper: createWrapper(client, queryClient) }
+    );
+
+    const payload = { eventType: 'INSERT', new: { id: 1 }, old: null };
+    changeHandler!(payload);
+
+    expect(invalidateSpy).toHaveBeenCalledWith({ queryKey: ['fluxbase', 'table', 'public.products'] });
+  });
+
+  it('should use custom invalidate key', () => {
+    let changeHandler: Function;
+    const onMock = vi.fn().mockImplementation((event, handler) => {
+      changeHandler = handler;
+      return { subscribe: vi.fn().mockReturnThis(), unsubscribe: vi.fn() };
+    });
+    const channelMock = vi.fn().mockReturnValue({
+      on: onMock,
+      subscribe: vi.fn().mockReturnThis(),
+      unsubscribe: vi.fn(),
+    });
+
+    const client = createMockClient({
+      realtime: { channel: channelMock },
+    } as any);
+
+    const queryClient = createTestQueryClient();
+    const invalidateSpy = vi.spyOn(queryClient, 'invalidateQueries');
+
+    renderHook(
+      () => useRealtime({
+        channel: 'table:products',
+        autoInvalidate: true,
+        invalidateKey: ['custom', 'key'],
+      }),
+      { wrapper: createWrapper(client, queryClient) }
+    );
+
+    const payload = { eventType: 'INSERT', new: { id: 1 }, old: null };
+    changeHandler!(payload);
+
+    expect(invalidateSpy).toHaveBeenCalledWith({ queryKey: ['custom', 'key'] });
+  });
+
+  it('should not auto-invalidate when disabled', () => {
+    let changeHandler: Function;
+    const onMock = vi.fn().mockImplementation((event, handler) => {
+      changeHandler = handler;
+      return { subscribe: vi.fn().mockReturnThis(), unsubscribe: vi.fn() };
+    });
+    const channelMock = vi.fn().mockReturnValue({
+      on: onMock,
+      subscribe: vi.fn().mockReturnThis(),
+      unsubscribe: vi.fn(),
+    });
+
+    const client = createMockClient({
+      realtime: { channel: channelMock },
+    } as any);
+
+    const queryClient = createTestQueryClient();
+    const invalidateSpy = vi.spyOn(queryClient, 'invalidateQueries');
+
+    renderHook(
+      () => useRealtime({ channel: 'table:products', autoInvalidate: false }),
+      { wrapper: createWrapper(client, queryClient) }
+    );
+
+    const payload = { eventType: 'INSERT', new: { id: 1 }, old: null };
+    changeHandler!(payload);
+
+    expect(invalidateSpy).not.toHaveBeenCalled();
+  });
+
+  it('should return channel property', () => {
+    const mockChannel = {
+      on: vi.fn().mockReturnThis(),
+      subscribe: vi.fn().mockReturnThis(),
+      unsubscribe: vi.fn(),
+    };
+    const channelMock = vi.fn().mockReturnValue(mockChannel);
+
+    const client = createMockClient({
+      realtime: { channel: channelMock },
+    } as any);
+
+    const { result } = renderHook(
+      () => useRealtime({ channel: 'table:products' }),
+      { wrapper: createWrapper(client) }
+    );
+
+    // The hook returns a channel property (may be null initially, but is set by useEffect)
+    expect(result.current).toHaveProperty('channel');
+    // Verify the channel was created
+    expect(channelMock).toHaveBeenCalledWith('table:products');
+  });
+});
+
+describe('useTableSubscription', () => {
+  it('should subscribe to table with correct channel name', () => {
+    const onMock = vi.fn().mockReturnThis();
+    const channelMock = vi.fn().mockReturnValue({
+      on: onMock,
+      subscribe: vi.fn().mockReturnThis(),
+      unsubscribe: vi.fn(),
+    });
+
+    const client = createMockClient({
+      realtime: { channel: channelMock },
+    } as any);
+
+    renderHook(
+      () => useTableSubscription('products'),
+      { wrapper: createWrapper(client) }
+    );
+
+    expect(channelMock).toHaveBeenCalledWith('table:products');
+  });
+
+  it('should pass options through', () => {
+    const callback = vi.fn();
+    const onMock = vi.fn().mockReturnThis();
+    const channelMock = vi.fn().mockReturnValue({
+      on: onMock,
+      subscribe: vi.fn().mockReturnThis(),
+      unsubscribe: vi.fn(),
+    });
+
+    const client = createMockClient({
+      realtime: { channel: channelMock },
+    } as any);
+
+    renderHook(
+      () => useTableSubscription('products', { callback, autoInvalidate: false }),
+      { wrapper: createWrapper(client) }
+    );
+
+    expect(channelMock).toHaveBeenCalledWith('table:products');
+  });
+});
+
+describe('useTableInserts', () => {
+  it('should subscribe to INSERT events', () => {
+    const onMock = vi.fn().mockReturnThis();
+    const channelMock = vi.fn().mockReturnValue({
+      on: onMock,
+      subscribe: vi.fn().mockReturnThis(),
+      unsubscribe: vi.fn(),
+    });
+
+    const client = createMockClient({
+      realtime: { channel: channelMock },
+    } as any);
+
+    const callback = vi.fn();
+    renderHook(
+      () => useTableInserts('products', callback),
+      { wrapper: createWrapper(client) }
+    );
+
+    expect(channelMock).toHaveBeenCalledWith('table:products');
+    expect(onMock).toHaveBeenCalledWith('INSERT', expect.any(Function));
+  });
+});
+
+describe('useTableUpdates', () => {
+  it('should subscribe to UPDATE events', () => {
+    const onMock = vi.fn().mockReturnThis();
+    const channelMock = vi.fn().mockReturnValue({
+      on: onMock,
+      subscribe: vi.fn().mockReturnThis(),
+      unsubscribe: vi.fn(),
+    });
+
+    const client = createMockClient({
+      realtime: { channel: channelMock },
+    } as any);
+
+    const callback = vi.fn();
+    renderHook(
+      () => useTableUpdates('products', callback),
+      { wrapper: createWrapper(client) }
+    );
+
+    expect(channelMock).toHaveBeenCalledWith('table:products');
+    expect(onMock).toHaveBeenCalledWith('UPDATE', expect.any(Function));
+  });
+});
+
+describe('useTableDeletes', () => {
+  it('should subscribe to DELETE events', () => {
+    const onMock = vi.fn().mockReturnThis();
+    const channelMock = vi.fn().mockReturnValue({
+      on: onMock,
+      subscribe: vi.fn().mockReturnThis(),
+      unsubscribe: vi.fn(),
+    });
+
+    const client = createMockClient({
+      realtime: { channel: channelMock },
+    } as any);
+
+    const callback = vi.fn();
+    renderHook(
+      () => useTableDeletes('products', callback),
+      { wrapper: createWrapper(client) }
+    );
+
+    expect(channelMock).toHaveBeenCalledWith('table:products');
+    expect(onMock).toHaveBeenCalledWith('DELETE', expect.any(Function));
+  });
+});

package/src/use-realtime.ts

@@ -47,6 +47,9 @@ export 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.
  */
 export function useRealtime(options: UseRealtimeOptions) {
   const client = useFluxbaseClient();
@@ -64,6 +67,17 @@ export function useRealtime(options: UseRealtimeOptions) {
     enabled = true,
   } = options;
 
+  // Store callback and invalidateKey in refs to avoid subscription recreation
+  // when inline functions/arrays are passed
+  const callbackRef = useRef(callback);
+  const invalidateKeyRef = useRef(invalidateKey);
+  const autoInvalidateRef = useRef(autoInvalidate);
+
+  // Keep refs up to date
+  callbackRef.current = callback;
+  invalidateKeyRef.current = invalidateKey;
+  autoInvalidateRef.current = autoInvalidate;
+
   useEffect(() => {
     if (!enabled) {
       return;
@@ -74,17 +88,17 @@ export function useRealtime(options: UseRealtimeOptions) {
     channelRef.current = channel;
 
     const handleChange = (payload: RealtimePostgresChangesPayload) => {
-      // Call user callback
-      if (callback) {
-        callback(payload);
+      // Call user callback (using ref for latest value)
+      if (callbackRef.current) {
+        callbackRef.current(payload);
       }
 
       // Auto-invalidate queries if enabled
-      if (autoInvalidate) {
+      if (autoInvalidateRef.current) {
         // Extract table name from channel (e.g., 'table:public.products' -> 'public.products')
         const tableName = channelName.replace(/^table:/, "");
 
-        const key = invalidateKey || ["fluxbase", "table", tableName];
+        const key = invalidateKeyRef.current || ["fluxbase", "table", tableName];
         queryClient.invalidateQueries({ queryKey: key });
       }
     };
@@ -95,16 +109,7 @@ export function useRealtime(options: UseRealtimeOptions) {
       channel.unsubscribe();
       channelRef.current = null;
     };
-  }, [
-    client,
-    channelName,
-    event,
-    callback,
-    autoInvalidate,
-    invalidateKey,
-    queryClient,
-    enabled,
-  ]);
+  }, [client, channelName, event, queryClient, enabled]);
 
   return {
     channel: channelRef.current,

package/src/use-saml.test.ts

@@ -0,0 +1,269 @@
+/**
+ * Tests for SAML SSO hooks
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { renderHook, waitFor, act } from '@testing-library/react';
+import {
+  useSAMLProviders,
+  useGetSAMLLoginUrl,
+  useSignInWithSAML,
+  useHandleSAMLCallback,
+  useSAMLMetadataUrl,
+} from './use-saml';
+import { createMockClient, createWrapper, createTestQueryClient } from './test-utils';
+
+describe('useSAMLProviders', () => {
+  it('should fetch SAML providers', async () => {
+    const mockProviders = [
+      { id: '1', name: 'okta', display_name: 'Okta' },
+      { id: '2', name: 'azure', display_name: 'Azure AD' },
+    ];
+    const getSAMLProvidersMock = vi.fn().mockResolvedValue({
+      data: { providers: mockProviders },
+      error: null,
+    });
+
+    const client = createMockClient({
+      auth: { getSAMLProviders: getSAMLProvidersMock },
+    } as any);
+
+    const { result } = renderHook(
+      () => useSAMLProviders(),
+      { wrapper: createWrapper(client) }
+    );
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+    expect(result.current.data).toEqual(mockProviders);
+  });
+
+  it('should throw error on fetch failure', async () => {
+    const error = new Error('Failed to fetch');
+    const getSAMLProvidersMock = vi.fn().mockResolvedValue({ data: null, error });
+
+    const client = createMockClient({
+      auth: { getSAMLProviders: getSAMLProvidersMock },
+    } as any);
+
+    const { result } = renderHook(
+      () => useSAMLProviders(),
+      { wrapper: createWrapper(client) }
+    );
+
+    await waitFor(() => expect(result.current.isError).toBe(true));
+    expect(result.current.error).toBe(error);
+  });
+});
+
+describe('useGetSAMLLoginUrl', () => {
+  it('should get SAML login URL', async () => {
+    const mockUrl = 'https://idp.example.com/sso/saml?SAMLRequest=...';
+    const getSAMLLoginUrlMock = vi.fn().mockResolvedValue({
+      data: { url: mockUrl },
+      error: null,
+    });
+
+    const client = createMockClient({
+      auth: { getSAMLLoginUrl: getSAMLLoginUrlMock },
+    } as any);
+
+    const { result } = renderHook(
+      () => useGetSAMLLoginUrl(),
+      { wrapper: createWrapper(client) }
+    );
+
+    await act(async () => {
+      await result.current.mutateAsync({
+        provider: 'okta',
+        options: { redirectUrl: 'https://app.example.com/callback' },
+      });
+    });
+
+    expect(getSAMLLoginUrlMock).toHaveBeenCalledWith('okta', {
+      redirectUrl: 'https://app.example.com/callback',
+    });
+  });
+
+  it('should get SAML login URL without options', async () => {
+    const getSAMLLoginUrlMock = vi.fn().mockResolvedValue({
+      data: { url: 'https://idp.example.com/sso' },
+      error: null,
+    });
+
+    const client = createMockClient({
+      auth: { getSAMLLoginUrl: getSAMLLoginUrlMock },
+    } as any);
+
+    const { result } = renderHook(
+      () => useGetSAMLLoginUrl(),
+      { wrapper: createWrapper(client) }
+    );
+
+    await act(async () => {
+      await result.current.mutateAsync({ provider: 'okta' });
+    });
+
+    expect(getSAMLLoginUrlMock).toHaveBeenCalledWith('okta', undefined);
+  });
+});
+
+describe('useSignInWithSAML', () => {
+  it('should initiate SAML sign in', async () => {
+    const signInWithSAMLMock = vi.fn().mockResolvedValue({ data: null, error: null });
+
+    const client = createMockClient({
+      auth: { signInWithSAML: signInWithSAMLMock },
+    } as any);
+
+    const { result } = renderHook(
+      () => useSignInWithSAML(),
+      { wrapper: createWrapper(client) }
+    );
+
+    await act(async () => {
+      await result.current.mutateAsync({ provider: 'okta' });
+    });
+
+    expect(signInWithSAMLMock).toHaveBeenCalledWith('okta', undefined);
+  });
+
+  it('should pass options to sign in', async () => {
+    const signInWithSAMLMock = vi.fn().mockResolvedValue({ data: null, error: null });
+
+    const client = createMockClient({
+      auth: { signInWithSAML: signInWithSAMLMock },
+    } as any);
+
+    const { result } = renderHook(
+      () => useSignInWithSAML(),
+      { wrapper: createWrapper(client) }
+    );
+
+    await act(async () => {
+      await result.current.mutateAsync({
+        provider: 'okta',
+        options: { redirectUrl: 'https://app.example.com' },
+      });
+    });
+
+    expect(signInWithSAMLMock).toHaveBeenCalledWith('okta', {
+      redirectUrl: 'https://app.example.com',
+    });
+  });
+});
+
+describe('useHandleSAMLCallback', () => {
+  it('should handle SAML callback successfully', async () => {
+    const mockResult = {
+      data: {
+        user: { id: '1', email: 'user@example.com' },
+        session: { access_token: 'token' },
+      },
+      error: null,
+    };
+    const handleSAMLCallbackMock = vi.fn().mockResolvedValue(mockResult);
+
+    const client = createMockClient({
+      auth: { handleSAMLCallback: handleSAMLCallbackMock },
+    } as any);
+
+    const { result } = renderHook(
+      () => useHandleSAMLCallback(),
+      { wrapper: createWrapper(client) }
+    );
+
+    let response;
+    await act(async () => {
+      response = await result.current.mutateAsync({ samlResponse: 'base64-response' });
+    });
+
+    expect(handleSAMLCallbackMock).toHaveBeenCalledWith('base64-response', undefined);
+    expect(response).toEqual(mockResult);
+    expect(result.current.isSuccess).toBe(true);
+  });
+
+  it('should pass provider to callback handler', async () => {
+    const handleSAMLCallbackMock = vi.fn().mockResolvedValue({
+      data: { user: {}, session: {} },
+      error: null,
+    });
+
+    const client = createMockClient({
+      auth: { handleSAMLCallback: handleSAMLCallbackMock },
+    } as any);
+
+    const { result } = renderHook(
+      () => useHandleSAMLCallback(),
+      { wrapper: createWrapper(client) }
+    );
+
+    await act(async () => {
+      await result.current.mutateAsync({
+        samlResponse: 'base64-response',
+        provider: 'okta',
+      });
+    });
+
+    expect(handleSAMLCallbackMock).toHaveBeenCalledWith('base64-response', 'okta');
+  });
+
+  it('should not update cache when no data', async () => {
+    const handleSAMLCallbackMock = vi.fn().mockResolvedValue({
+      data: null,
+      error: null,
+    });
+
+    const client = createMockClient({
+      auth: { handleSAMLCallback: handleSAMLCallbackMock },
+    } as any);
+
+    const queryClient = createTestQueryClient();
+    const { result } = renderHook(
+      () => useHandleSAMLCallback(),
+      { wrapper: createWrapper(client, queryClient) }
+    );
+
+    await act(async () => {
+      await result.current.mutateAsync({ samlResponse: 'base64-response' });
+    });
+
+    // Cache should not be updated
+    expect(queryClient.getQueryData(['fluxbase', 'auth', 'session'])).toBeUndefined();
+  });
+});
+
+describe('useSAMLMetadataUrl', () => {
+  it('should return metadata URL generator function', () => {
+    const getSAMLMetadataUrlMock = vi.fn().mockReturnValue('https://api.example.com/saml/metadata/okta');
+
+    const client = createMockClient({
+      auth: { getSAMLMetadataUrl: getSAMLMetadataUrlMock },
+    } as any);
+
+    const { result } = renderHook(
+      () => useSAMLMetadataUrl(),
+      { wrapper: createWrapper(client) }
+    );
+
+    const url = result.current('okta');
+
+    expect(getSAMLMetadataUrlMock).toHaveBeenCalledWith('okta');
+    expect(url).toBe('https://api.example.com/saml/metadata/okta');
+  });
+
+  it('should work with different providers', () => {
+    const getSAMLMetadataUrlMock = vi.fn().mockImplementation((provider) => `https://api.example.com/saml/metadata/${provider}`);
+
+    const client = createMockClient({
+      auth: { getSAMLMetadataUrl: getSAMLMetadataUrlMock },
+    } as any);
+
+    const { result } = renderHook(
+      () => useSAMLMetadataUrl(),
+      { wrapper: createWrapper(client) }
+    );
+
+    expect(result.current('okta')).toBe('https://api.example.com/saml/metadata/okta');
+    expect(result.current('azure')).toBe('https://api.example.com/saml/metadata/azure');
+  });
+});