@multiplatform.one/frappe 6.0.0

package/src/frappeReact.ts

@@ -0,0 +1,598 @@
+import type { Collection } from "@tanstack/db";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { createFrappeCollection, type FrappeCollectionOptionsConfig } from "./collection";
+import { HttpClient } from "./core/http";
+import type { AuthConfig } from "./core/types";
+import { DbModule } from "./db";
+import { FixtureDbModule } from "./fixtureDb";
+import { RealtimeModule } from "./realtime";
+import { SyncModule } from "./sync";
+import { isBrowser } from "./util";
+
+/**
+ * Configuration for creating a Frappe collection with connection details.
+ */
+export interface UseFrappeCollectionConfig {
+  /** The base URL of the Frappe server */
+  baseURL: string;
+  /**
+   * Override the port used for the Socket.IO realtime connection.
+   * In dev, set to `FRAPPE_SOCKETIO_PORT` (e.g. 9000).  Omit in production
+   * behind a reverse proxy so the base URL port is used.
+   */
+  socketPort?: number;
+  /** Authentication configuration */
+  auth?: {
+    useToken?: boolean;
+    token?: string;
+    type?: string;
+  };
+  /** Sync options for the SyncModule */
+  syncOptions?: import("./sync/types").SyncOptions;
+  /** Fixture provider for testing (used by frappe-ui in development) */
+  fixtures?: import("./fixtures").FixtureProvider;
+}
+
+// Shared SyncModule instances keyed by baseURL to avoid duplicates (live mode)
+const syncModuleCache = new Map<string, SyncModule>();
+// Fixture-mode SyncModules keyed by the FixtureProvider instance so each unique
+// fixture set gets its own SyncModule (prevents cross-test cache pollution).
+const fixtureSyncModuleCache = new WeakMap<import("./fixtures").FixtureProvider, SyncModule>();
+
+/**
+ * Returns the first active SyncModule, or undefined if none exist.
+ * Intended for devtools integration — not part of the public API.
+ */
+export function __getActiveSyncModule(): SyncModule | undefined {
+  for (const sync of syncModuleCache.values()) return sync;
+  return undefined;
+}
+
+/**
+ * Gets or creates a shared SyncModule for the given config.
+ * SyncModules are cached by baseURL to prevent duplicate connections.
+ *
+ * When `config.fixtures` is set, creates a SyncModule backed by
+ * FixtureDbModule so the full pipeline (virtual pagination, progressive
+ * cache, mutation journal, devtools) works identically with mock data.
+ * Fixture-mode SyncModules are keyed by the FixtureProvider instance so
+ * different fixture sets never share cached state (important in tests).
+ *
+ * Returns `undefined` during SSR (Node.js) because the SyncModule relies
+ * on browser-only APIs (localStorage, BroadcastChannel, window events).
+ */
+function getSyncModule(config: UseFrappeCollectionConfig): SyncModule | undefined {
+  if (!isBrowser()) return undefined;
+
+  if (config.fixtures) {
+    let sync = fixtureSyncModuleCache.get(config.fixtures);
+    if (!sync) {
+      const db = new FixtureDbModule(config.fixtures) as unknown as DbModule;
+      sync = new SyncModule(db, undefined, config.syncOptions);
+      fixtureSyncModuleCache.set(config.fixtures, sync);
+    }
+    return sync;
+  }
+
+  const key = config.baseURL;
+  let sync = syncModuleCache.get(key);
+  if (!sync) {
+    const authConfig: AuthConfig | undefined = config.auth
+      ? {
+          useToken: config.auth.useToken,
+          token: config.auth.token,
+          type: config.auth.type as AuthConfig["type"],
+        }
+      : undefined;
+    const http = new HttpClient(config.baseURL, authConfig);
+    const db = new DbModule(http, { appName: "live.live" });
+    const realtimeConfig = {
+      baseURL: config.baseURL,
+      socketPort: config.socketPort,
+      auth: authConfig,
+    };
+    sync = new SyncModule(db, new RealtimeModule(realtimeConfig), config.syncOptions);
+    syncModuleCache.set(key, sync);
+  }
+  return sync;
+}
+
+/**
+ * React hook that creates and memoizes a TanStack DB Collection backed by a Frappe doctype.
+ *
+ * The collection is created once and stable across re-renders. It can be used with
+ * `useLiveQuery` for reactive queries and has `.insert()`, `.update()`, `.delete()`
+ * methods for mutations.
+ *
+ * @typeParam TDoc - The Frappe document type
+ * @param config - Connection configuration (baseURL, auth)
+ * @param doctype - The Frappe doctype name
+ * @param options - Optional collection configuration (fields, filters, etc.)
+ * @returns A stable TanStack DB Collection instance, or undefined if config is not provided
+ *
+ * @example
+ * ```tsx
+ * function PokemonList() {
+ *   const config = useFrappeConfig();
+ *   const collection = useFrappeCollection<Pokemon>(
+ *     config ? { baseURL: config.baseURL, auth: config.auth } : undefined,
+ *     "Pokemon",
+ *     { fields: ["name", "pokemon_name", "poke_id"] }
+ *   );
+ *
+ *   const { data, isLoading } = useLiveQuery(
+ *     (q) => collection ? q.from({ pokemon: collection }) : null,
+ *     [collection]
+ *   );
+ *
+ *   if (isLoading) return <Spinner />;
+ *   return data?.map(p => <div key={p.name}>{p.pokemon_name}</div>);
+ * }
+ * ```
+ */
+export function useFrappeCollection<TDoc extends object & { name: string; doctype: string }>(
+  config: UseFrappeCollectionConfig | undefined,
+  doctype: string,
+  options?: Omit<FrappeCollectionOptionsConfig<TDoc>, "sync">,
+): Collection<TDoc, string> | undefined {
+  const collectionRef = useRef<Collection<TDoc, string> | undefined>(undefined);
+  const configKeyRef = useRef<string>("");
+
+  // Compute a stable key for the config (include fixtures flag so fixture vs live collections differ)
+  const configKey = config
+    ? `${config.baseURL}:${config.fixtures ? "fixture" : "live"}:${doctype}:${JSON.stringify(options?.fields)}:${JSON.stringify(options?.filters)}`
+    : "";
+
+  // Re-create the collection when config changes, OR when the collection is
+  // still undefined on the client (can happen after SSR where SyncModule is
+  // unavailable – the configKey was stored during SSR but the collection was
+  // never actually created).
+  const needsCollection = config && (configKey !== configKeyRef.current || !collectionRef.current);
+  if (needsCollection) {
+    const syncModule = getSyncModule(config);
+    // During SSR, getSyncModule returns undefined – leave the collection
+    // as undefined so the component renders a loading state.  The client
+    // hydration pass will create the real collection.
+    if (syncModule) {
+      collectionRef.current = createFrappeCollection<TDoc>(doctype, {
+        ...options,
+        sync: syncModule,
+      });
+      configKeyRef.current = configKey;
+    }
+    // NOTE: configKeyRef is NOT set when syncModule is undefined (SSR),
+    // so on client hydration the hook will retry and create the collection.
+  }
+
+  if (!config) {
+    collectionRef.current = undefined;
+    configKeyRef.current = "";
+  }
+
+  return collectionRef.current;
+}
+
+// ---------------------------------------------------------------------------
+// Infinite Scroll Hook
+// ---------------------------------------------------------------------------
+
+/**
+ * Configuration for the useInfiniteScroll hook
+ */
+export interface UseInfiniteScrollConfig {
+  /** Whether more data is available to load */
+  hasMore: boolean;
+  /** Whether data is currently being loaded */
+  isLoading: boolean;
+  /** Function to call when more data should be loaded */
+  onLoadMore: () => void | Promise<void>;
+  /** Root element for intersection (default: viewport) */
+  root?: Element | null;
+  /** Margin around the root (default: "100px") */
+  rootMargin?: string;
+  /** Visibility threshold 0-1 (default: 0.1) */
+  threshold?: number;
+  /** Debounce delay in ms (default: 100) */
+  debounceMs?: number;
+  /** Enable/disable the hook (default: true) */
+  enabled?: boolean;
+}
+
+/**
+ * Result from the useInfiniteScroll hook
+ */
+export interface UseInfiniteScrollResult {
+  /** Ref to attach to the sentinel element */
+  sentinelRef: React.RefCallback<Element | null>;
+  /** Whether the sentinel is currently visible */
+  isVisible: boolean;
+  /** Whether load more is in progress */
+  isLoadingMore: boolean;
+}
+
+/**
+ * React hook for automatic infinite scroll loading.
+ *
+ * Uses IntersectionObserver to detect when a sentinel element becomes visible
+ * and automatically triggers loading of more data. Includes debouncing to prevent
+ * rapid-fire requests.
+ *
+ * @param config - Configuration options
+ * @returns Object with sentinelRef to attach to your loading indicator element
+ *
+ * @example
+ * ```tsx
+ * function PokemonList() {
+ *   const [page, setPage] = useState(1);
+ *   const { data, hasMore, isLoading } = usePokemonList(page);
+ *
+ *   const { sentinelRef, isLoadingMore } = useInfiniteScroll({
+ *     hasMore,
+ *     isLoading,
+ *     onLoadMore: () => setPage(p => p + 1),
+ *   });
+ *
+ *   return (
+ *     <div>
+ *       {data.map(pokemon => <PokemonCard key={pokemon.name} {...pokemon} />)}
+ *       <div ref={sentinelRef}>
+ *         {isLoadingMore ? <Spinner /> : hasMore ? "Scroll for more" : "No more items"}
+ *       </div>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function useInfiniteScroll(config: UseInfiniteScrollConfig): UseInfiniteScrollResult {
+  const {
+    hasMore,
+    isLoading,
+    onLoadMore,
+    root = null,
+    rootMargin = "100px",
+    threshold = 0.1,
+    debounceMs = 100,
+    enabled = true,
+  } = config;
+
+  const [isVisible, setIsVisible] = useState(false);
+  const [isLoadingMore, setIsLoadingMore] = useState(false);
+  const observerRef = useRef<IntersectionObserver | null>(null);
+  const sentinelNodeRef = useRef<Element | null>(null);
+  const debounceTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const lastLoadTimeRef = useRef<number>(0);
+
+  // Stable callback for loading more
+  const loadMore = useCallback(async () => {
+    if (!hasMore || isLoading || isLoadingMore) return;
+
+    // Debounce rapid calls
+    const now = Date.now();
+    if (now - lastLoadTimeRef.current < debounceMs) return;
+    lastLoadTimeRef.current = now;
+
+    setIsLoadingMore(true);
+    try {
+      await onLoadMore();
+    } finally {
+      setIsLoadingMore(false);
+    }
+  }, [hasMore, isLoading, isLoadingMore, onLoadMore, debounceMs]);
+
+  // Set up IntersectionObserver
+  useEffect(() => {
+    if (!isBrowser() || !enabled) return;
+
+    const node = sentinelNodeRef.current;
+    if (!node) return;
+
+    // Clean up previous observer
+    if (observerRef.current) {
+      observerRef.current.disconnect();
+    }
+
+    observerRef.current = new IntersectionObserver(
+      (entries) => {
+        const entry = entries[0];
+        const visible = entry?.isIntersecting ?? false;
+        setIsVisible(visible);
+
+        if (visible && hasMore && !isLoading && !isLoadingMore) {
+          // Clear any pending debounce timer
+          if (debounceTimerRef.current) {
+            clearTimeout(debounceTimerRef.current);
+          }
+          // Schedule load with debounce
+          debounceTimerRef.current = setTimeout(() => {
+            loadMore();
+          }, debounceMs);
+        }
+      },
+      {
+        root,
+        rootMargin,
+        threshold,
+      },
+    );
+
+    observerRef.current.observe(node);
+
+    return () => {
+      if (observerRef.current) {
+        observerRef.current.disconnect();
+        observerRef.current = null;
+      }
+      if (debounceTimerRef.current) {
+        clearTimeout(debounceTimerRef.current);
+        debounceTimerRef.current = null;
+      }
+    };
+  }, [
+    enabled,
+    root,
+    rootMargin,
+    threshold,
+    hasMore,
+    isLoading,
+    isLoadingMore,
+    loadMore,
+    debounceMs,
+  ]);
+
+  // Ref callback to capture the sentinel element
+  const sentinelRef = useCallback((node: Element | null) => {
+    sentinelNodeRef.current = node;
+
+    // Re-observe when node changes
+    if (observerRef.current && node) {
+      observerRef.current.disconnect();
+      observerRef.current.observe(node);
+    }
+  }, []);
+
+  return {
+    sentinelRef,
+    isVisible,
+    isLoadingMore,
+  };
+}
+
+/**
+ * Options for the useFrappeInfiniteList hook
+ */
+export interface UseFrappeInfiniteListConfig<TDoc> {
+  /** Frappe connection configuration */
+  config: UseFrappeCollectionConfig | undefined;
+  /** DocType to query */
+  doctype: string;
+  /** Fields to fetch */
+  fields?: string[];
+  /** Filters to apply */
+  filters?: Array<[string, string, unknown]> | Record<string, unknown>;
+  /** Order by specification */
+  orderBy?: import("./sync/types").OrderBy;
+  /** Page size (default: 20) */
+  pageSize?: number;
+  /** Transform function for items */
+  transform?: (doc: TDoc) => TDoc;
+}
+
+/**
+ * Result from useFrappeInfiniteList hook
+ */
+export interface UseFrappeInfiniteListResult<TDoc> {
+  /** All loaded items */
+  items: TDoc[];
+  /** Whether more items are available */
+  hasMore: boolean;
+  /** Whether initial load is in progress */
+  isLoading: boolean;
+  /** Whether loading more is in progress */
+  isLoadingMore: boolean;
+  /** Any error that occurred */
+  error: Error | null;
+  /** Ref to attach to sentinel element */
+  sentinelRef: React.RefCallback<Element | null>;
+  /** Manually trigger loading more */
+  loadMore: () => Promise<void>;
+  /** Refresh the list from the beginning */
+  refresh: () => Promise<void>;
+  /** Total number of loaded items */
+  totalLoaded: number;
+}
+
+/**
+ * React hook for infinite scrolling through a Frappe doctype list.
+ *
+ * Uses SyncModule with progressive subscriptions so that infinite-scroll
+ * lists automatically receive realtime updates, optimistic mutations,
+ * offline support, and CDC backfill -- all features that were previously
+ * only available to `useFrappeCollection` consumers.
+ *
+ * @typeParam TDoc - The document type
+ * @param options - Configuration options
+ * @returns Object with items, loading states, and sentinelRef
+ *
+ * @example
+ * ```tsx
+ * function PokemonList() {
+ *   const config = useFrappeConfig();
+ *   const {
+ *     items,
+ *     hasMore,
+ *     isLoading,
+ *     sentinelRef,
+ *   } = useFrappeInfiniteList<Pokemon>({
+ *     config,
+ *     doctype: "Pokemon",
+ *     fields: ["name", "pokemon_name", "poke_id"],
+ *     pageSize: 20,
+ *   });
+ *
+ *   if (isLoading && items.length === 0) return <Spinner />;
+ *
+ *   return (
+ *     <div>
+ *       {items.map(pokemon => <PokemonCard key={pokemon.name} {...pokemon} />)}
+ *       <div ref={sentinelRef}>
+ *         {hasMore ? <Spinner /> : "No more pokemon"}
+ *       </div>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function useFrappeInfiniteList<TDoc extends object & { name: string; doctype: string }>(
+  options: UseFrappeInfiniteListConfig<TDoc>,
+): UseFrappeInfiniteListResult<TDoc> {
+  const { config, doctype, fields, filters, orderBy, pageSize = 20, transform } = options;
+
+  const [items, setItems] = useState<TDoc[]>([]);
+  const [hasMore, setHasMore] = useState(true);
+  const [isLoading, setIsLoading] = useState(true);
+  const [isLoadingMore, setIsLoadingMore] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const subscriptionIdRef = useRef<string | undefined>(undefined);
+  const syncModuleRef = useRef<SyncModule | undefined>(undefined);
+
+  // Stable serialised key for filters so we can depend on it in useEffect
+  const filtersKey = JSON.stringify(filters);
+
+  // Subscribe via SyncModule with progressive: true
+  useEffect(() => {
+    if (!config || !isBrowser()) return;
+
+    const syncModule = getSyncModule(config);
+    if (!syncModule) return;
+    syncModuleRef.current = syncModule;
+
+    let cancelled = false;
+    setIsLoading(true);
+    setError(null);
+
+    (async () => {
+      try {
+        const result = await syncModule.subscribe({
+          doctype,
+          fields,
+          filters,
+          orderBy,
+          limit: pageSize,
+          progressive: true,
+        });
+        if (cancelled) {
+          syncModule.unsubscribe(result.subscriptionId);
+          return;
+        }
+        subscriptionIdRef.current = result.subscriptionId;
+
+        const docs = syncModule.getDocsForSubscription<TDoc>(result.subscriptionId);
+        const pageInfo = syncModule.getPageInfo(result.subscriptionId);
+        setItems(transform ? docs.map(transform) : docs);
+        setHasMore(pageInfo.hasMore);
+      } catch (err) {
+        if (!cancelled) {
+          setError(err instanceof Error ? err : new Error(String(err)));
+          setItems([]);
+          setHasMore(false);
+        }
+      } finally {
+        if (!cancelled) setIsLoading(false);
+      }
+    })();
+
+    // Listen for realtime / backfill changes
+    const unsubStore = syncModule.subscribeStore(() => {
+      const subId = subscriptionIdRef.current;
+      if (!subId) return;
+      const docs = syncModule.getDocsForSubscription<TDoc>(subId);
+      const pageInfo = syncModule.getPageInfo(subId);
+      setItems(transform ? docs.map(transform) : docs);
+      setHasMore(pageInfo.hasMore);
+    });
+
+    return () => {
+      cancelled = true;
+      unsubStore();
+      if (subscriptionIdRef.current) {
+        syncModule.unsubscribe(subscriptionIdRef.current);
+        subscriptionIdRef.current = undefined;
+      }
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [config?.baseURL, config?.auth?.token, doctype, filtersKey, pageSize]);
+
+  const loadMore = useCallback(async () => {
+    const syncModule = syncModuleRef.current;
+    const subId = subscriptionIdRef.current;
+    if (!syncModule || !subId || !hasMore || isLoadingMore) return;
+
+    setIsLoadingMore(true);
+    setError(null);
+
+    try {
+      const currentDocs = syncModule.getDocsForSubscription<TDoc>(subId);
+      const lastDoc = currentDocs[currentDocs.length - 1];
+      if (!lastDoc) return;
+
+      await syncModule.getNextBatch(subId, lastDoc.name, pageSize);
+      // Store listener handles items update via emit()
+    } catch (err) {
+      setError(err instanceof Error ? err : new Error(String(err)));
+    } finally {
+      setIsLoadingMore(false);
+    }
+  }, [hasMore, isLoadingMore, pageSize]);
+
+  const refresh = useCallback(async () => {
+    const syncModule = syncModuleRef.current;
+    if (!syncModule || !subscriptionIdRef.current) return;
+
+    // Unsubscribe and re-subscribe to reset
+    syncModule.unsubscribe(subscriptionIdRef.current);
+    subscriptionIdRef.current = undefined;
+    setItems([]);
+    setHasMore(true);
+    setIsLoading(true);
+    setError(null);
+
+    try {
+      const result = await syncModule.subscribe({
+        doctype,
+        fields,
+        filters,
+        orderBy,
+        limit: pageSize,
+        progressive: true,
+      });
+      subscriptionIdRef.current = result.subscriptionId;
+      const docs = syncModule.getDocsForSubscription<TDoc>(result.subscriptionId);
+      const pageInfo = syncModule.getPageInfo(result.subscriptionId);
+      setItems(transform ? docs.map(transform) : docs);
+      setHasMore(pageInfo.hasMore);
+    } catch (err) {
+      setError(err instanceof Error ? err : new Error(String(err)));
+    } finally {
+      setIsLoading(false);
+    }
+  }, [doctype, fields, filters, orderBy, pageSize, transform]);
+
+  const { sentinelRef, isVisible: _isVisible } = useInfiniteScroll({
+    hasMore,
+    isLoading: isLoading || isLoadingMore,
+    onLoadMore: loadMore,
+  });
+
+  return {
+    items,
+    hasMore,
+    isLoading,
+    isLoadingMore,
+    error,
+    sentinelRef,
+    loadMore,
+    refresh,
+    totalLoaded: items.length,
+  };
+}