@nimbleflux/fluxbase-sdk-react 2026.3.6-rc.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

@@ -0,0 +1,180 @@
+/**
+ * Realtime subscription hooks for 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;
+
+  /**
+   * 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
+ *
+ * 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();
+  const queryClient = useQueryClient();
+  const channelRef = useRef<ReturnType<typeof client.realtime.channel> | null>(
+    null,
+  );
+
+  const {
+    channel: channelName,
+    event = "*",
+    callback,
+    autoInvalidate = true,
+    invalidateKey,
+    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;
+    }
+
+    // Create channel and subscribe
+    const channel = client.realtime.channel(channelName);
+    channelRef.current = channel;
+
+    const handleChange = (payload: RealtimePostgresChangesPayload) => {
+      // Call user callback (using ref for latest value)
+      if (callbackRef.current) {
+        callbackRef.current(payload);
+      }
+
+      // Auto-invalidate queries if enabled
+      if (autoInvalidateRef.current) {
+        // Extract table name from channel (e.g., 'table:public.products' -> 'public.products')
+        const tableName = channelName.replace(/^table:/, "");
+
+        const key = invalidateKeyRef.current || ["fluxbase", "table", tableName];
+        queryClient.invalidateQueries({ queryKey: key });
+      }
+    };
+
+    channel.on(event, handleChange).subscribe();
+
+    return () => {
+      channel.unsubscribe();
+      channelRef.current = null;
+    };
+  }, [client, channelName, event, 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: RealtimePostgresChangesPayload) => 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: RealtimePostgresChangesPayload) => 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: RealtimePostgresChangesPayload) => void,
+  options?: Omit<UseRealtimeOptions, "channel" | "event" | "callback">,
+) {
+  return useRealtime({
+    ...options,
+    channel: `table:${table}`,
+    event: "DELETE",
+    callback,
+  });
+}