@jmruthers/pace-core 0.6.9 → 0.6.11

package/src/components/FileDisplay/useFileDisplay.ts

@@ -0,0 +1,515 @@
+/**
+ * @file File Display Hook (Authenticated)
+ * @package @jmruthers/pace-core
+ * @module Hooks
+ *
+ * A React hook for accessing file references in authenticated contexts.
+ * Can handle both public and private files using the core_file_references system.
+ *
+ * Features:
+ * - Works in authenticated contexts
+ * - Supports both public and private files
+ * - Automatic signed URL generation for private files
+ * - Caching for performance
+ * - Error handling and loading states
+ * - Supports both single file (category) and multiple files
+ *
+ * @example
+ * ```tsx
+ * import { useFileDisplay } from '@jmruthers/pace-core';
+ *
+ * function FileView() {
+ *   const { fileUrl, fileReference, isLoading, error } = useFileDisplay(
+ *     'core_events',
+ *     eventId,
+ *     organisationId,
+ *     FileCategory.EVENT_LOGOS
+ *   );
+ *
+ *   if (isLoading) return <p>Loading...</p>;
+ *   if (error) return <p>Error: {error.message}</p>;
+ *
+ *   return fileUrl ? <img src={fileUrl} alt="File" /> : null;
+ * }
+ * ```
+ */
+
+import { useState, useEffect, useCallback, useRef } from 'react';
+import type { SupabaseClient } from '@supabase/supabase-js';
+import { FileReference, FileCategory } from '../../types/file-reference';
+import { getPublicUrl, getSignedUrl, generateFileUrlsBatch } from '../../utils/storage/helpers';
+import { fetchFileDisplayData } from './fetchFileDisplayData';
+import { logger } from '../../utils/core/logger';
+
+// Cache data structure
+interface CacheData {
+  fileUrl: string | null;
+  fileReference: FileReference | null;
+  fileReferences: FileReference[];
+  fileUrls: Map<string, string>;
+  fileCount: number;
+}
+
+// Simple in-memory cache for authenticated file data
+const authenticatedFileCache = new Map<string, { data: CacheData; timestamp: number; ttl: number }>();
+
+// Cache size limit to prevent memory leaks
+const MAX_CACHE_SIZE = 100;
+
+// Helper function to clean up expired entries and enforce size limit
+function cleanupCache() {
+  const now = Date.now();
+  const entries = Array.from(authenticatedFileCache.entries());
+
+  // Remove expired entries
+  const expiredKeys: string[] = [];
+  entries.forEach(([key, value]) => {
+    if (now - value.timestamp >= value.ttl) {
+      expiredKeys.push(key);
+    }
+  });
+  expiredKeys.forEach(key => authenticatedFileCache.delete(key));
+
+  // If still over limit, remove oldest entries
+  if (authenticatedFileCache.size > MAX_CACHE_SIZE) {
+    const sorted = entries
+      .filter(([key]) => !expiredKeys.includes(key))
+      .sort((a, b) => a[1].timestamp - b[1].timestamp);
+    const toRemove = sorted.slice(0, authenticatedFileCache.size - MAX_CACHE_SIZE);
+    toRemove.forEach(([key]) => authenticatedFileCache.delete(key));
+  }
+}
+
+function getFileDisplayCacheKey(
+  table_name: string,
+  record_id: string,
+  organisation_id: string | undefined,
+  category: FileCategory | undefined
+): string {
+  return `file_${table_name}_${record_id}_${organisation_id === undefined ? 'undefined' : (organisation_id ?? 'null')}_${category || 'all'}`;
+}
+
+type SafeSetStateFn = <T>(setter: (value: T) => void, value: T) => void;
+
+async function tryApplyCacheHit(
+  cacheKey: string,
+  enableCache: boolean,
+  cacheTtl: number,
+  supabase: SupabaseClient | null,
+  organisation_id: string | undefined,
+  record_id: string,
+  safeSetState: SafeSetStateFn,
+  setters: {
+    setFileUrl: (v: string | null) => void;
+    setFileReference: (v: FileReference | null) => void;
+    setFileReferences: (v: FileReference[]) => void;
+    setFileUrls: (v: Map<string, string>) => void;
+    setFileCount: (v: number) => void;
+    setIsLoading: (v: boolean) => void;
+    setError: (v: Error | null) => void;
+  }
+): Promise<boolean> {
+  if (!enableCache || !supabase) return false;
+  const cached = authenticatedFileCache.get(cacheKey);
+  if (!cached || Date.now() - cached.timestamp >= cached.ttl) return false;
+  const cachedData = cached.data;
+
+  if (
+    cachedData.fileReference &&
+    !cachedData.fileUrl &&
+    cachedData.fileReference.is_public === false &&
+    supabase
+  ) {
+    try {
+      const signedUrlResult = await getSignedUrl(supabase, cachedData.fileReference.file_path, {
+        appName: 'pace-core',
+        orgId: organisation_id,
+        userId: organisation_id ? undefined : record_id,
+        expiresIn: 3600
+      });
+      const regeneratedUrl = signedUrlResult.ok ? signedUrlResult.data.url : null;
+      safeSetState(setters.setFileUrl, regeneratedUrl);
+      safeSetState(setters.setFileReference, cachedData.fileReference);
+      safeSetState(setters.setFileReferences, cachedData.fileReferences || []);
+      safeSetState(setters.setFileUrls, cachedData.fileUrls || new Map());
+      safeSetState(setters.setFileCount, cachedData.fileCount || 0);
+      safeSetState(setters.setIsLoading, false);
+      safeSetState(setters.setError, null);
+      return true;
+    } catch (err) {
+      logger.warn('useFileDisplay', 'Failed to regenerate signed URL from cache, falling back to fetch:', err);
+    }
+  }
+
+  safeSetState(setters.setFileUrl, cachedData.fileUrl || null);
+  safeSetState(setters.setFileReference, cachedData.fileReference || null);
+  safeSetState(setters.setFileReferences, cachedData.fileReferences || []);
+  safeSetState(setters.setFileUrls, cachedData.fileUrls || new Map());
+  safeSetState(setters.setFileCount, cachedData.fileCount || 0);
+  safeSetState(setters.setIsLoading, false);
+  safeSetState(setters.setError, null);
+  return true;
+}
+
+async function applyFetchedFilesAndCache(
+  files: FileReference[],
+  category: FileCategory | undefined,
+  table_name: string,
+  record_id: string,
+  organisation_id: string | undefined,
+  supabase: SupabaseClient,
+  cacheKey: string,
+  enableCache: boolean,
+  cacheTtl: number,
+  safeSetState: SafeSetStateFn,
+  setters: {
+    setFileUrl: (v: string | null) => void;
+    setFileReference: (v: FileReference | null) => void;
+    setFileReferences: (v: FileReference[]) => void;
+    setFileUrls: (v: Map<string, string>) => void;
+    setFileCount: (v: number) => void;
+  }
+): Promise<void> {
+  safeSetState(setters.setFileReferences, files);
+  safeSetState(setters.setFileCount, files.length);
+
+  if (category && files.length > 0) {
+    const firstFile = files[0];
+    safeSetState(setters.setFileReference, firstFile);
+    let url: string | null = null;
+    if (firstFile.is_public) {
+      url = getPublicUrl(supabase, firstFile.file_path, true);
+    } else {
+      const signedUrlResult = await getSignedUrl(supabase, firstFile.file_path, {
+        appName: 'pace-core',
+        orgId: organisation_id,
+        userId: organisation_id ? undefined : record_id,
+        expiresIn: 3600
+      });
+      url = signedUrlResult.ok ? signedUrlResult.data.url : null;
+      if (!url) {
+        logger.warn('useFileDisplay', 'Failed to generate signed URL for file:', {
+          file_path: firstFile.file_path,
+          record_id,
+          table_name
+        });
+      }
+    }
+    safeSetState(setters.setFileUrl, url);
+  } else {
+    const urlResult = await generateFileUrlsBatch(supabase, files, {
+      appName: 'pace-core',
+      orgId: organisation_id,
+      userId: organisation_id ? undefined : record_id,
+      expiresIn: 3600
+    });
+    const urlMap = urlResult.ok ? urlResult.data : new Map<string, string>();
+    safeSetState(setters.setFileUrls, urlMap);
+    safeSetState(setters.setFileReference, null);
+    safeSetState(setters.setFileUrl, null);
+  }
+
+  if (enableCache) {
+    const cacheData: CacheData = {
+      fileUrl: null,
+      fileReference: category && files.length > 0 ? files[0] : null,
+      fileReferences: files,
+      fileUrls: new Map(),
+      fileCount: files.length
+    };
+    if (category && files.length > 0) {
+      const firstFile = files[0];
+      cacheData.fileUrl = firstFile.is_public
+        ? getPublicUrl(supabase, firstFile.file_path, true)
+        : null;
+    } else {
+      const urlMap = new Map<string, string>();
+      for (const fileRef of files) {
+        if (fileRef.is_public) {
+          const url = getPublicUrl(supabase, fileRef.file_path, true);
+          if (url) urlMap.set(fileRef.id, url);
+        }
+      }
+      cacheData.fileUrls = urlMap;
+    }
+    authenticatedFileCache.set(cacheKey, {
+      data: cacheData,
+      timestamp: Date.now(),
+      ttl: cacheTtl
+    });
+    cleanupCache();
+  }
+}
+
+/**
+ * Return value of the useFileDisplay hook.
+ * Provides file URLs, references, loading state, error, and refetch function.
+ */
+export interface UseFileDisplayReturn {
+  /** Single file URL if category is provided and file found, null otherwise */
+  fileUrl: string | null;
+  /** Single file reference if category is provided and file found, null otherwise */
+  fileReference: FileReference | null;
+  /** Array of all file references for the record (when category not provided or for multiple files) */
+  fileReferences: FileReference[];
+  /** Map of file IDs to URLs for multiple files */
+  fileUrls: Map<string, string>;
+  /** Total count of files for the record */
+  fileCount: number;
+  /** Whether the data is currently loading */
+  isLoading: boolean;
+  /** Any error that occurred during loading */
+  error: Error | null;
+  /** Function to manually refetch the data */
+  refetch: () => Promise<void>;
+}
+
+export interface UseFileDisplayOptions {
+  /** Cache TTL in milliseconds (default: 30 minutes) */
+  cacheTtl?: number;
+  /** Whether to enable caching (default: true) */
+  enableCache?: boolean;
+  /** Supabase client instance (required) */
+  supabase: SupabaseClient | null;
+}
+
+/**
+ * Hook for accessing file references in authenticated contexts
+ *
+ * This hook provides access to file references for authenticated users.
+ * It supports both public and private files, generating appropriate URLs
+ * (public URLs for public files, signed URLs for private files).
+ *
+ * @param table_name - The table name containing the file reference
+ * @param record_id - The record ID that owns the file(s)
+ * @param organisation_id - The organisation ID for storage path
+ * @param category - Optional file category to filter by (for single file mode)
+ * @param options - Configuration options for caching and behavior
+ * @returns Object containing file data, loading state, error, and refetch function
+ */
+export function useFileDisplay(
+  table_name: string | undefined,
+  record_id: string | undefined,
+  organisation_id: string | undefined,
+  category: FileCategory | undefined,
+  options: UseFileDisplayOptions
+): UseFileDisplayReturn {
+  const {
+    cacheTtl = 30 * 60 * 1000, // 30 minutes
+    enableCache = true,
+    supabase
+  } = options;
+
+  const [fileUrl, setFileUrl] = useState<string | null>(null);
+  const [fileReference, setFileReference] = useState<FileReference | null>(null);
+  const [fileReferences, setFileReferences] = useState<FileReference[]>([]);
+  const [fileUrls, setFileUrls] = useState<Map<string, string>>(new Map());
+  const [fileCount, setFileCount] = useState<number>(0);
+  const [isLoading, setIsLoading] = useState<boolean>(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  // Ref to track if component is mounted and effect is active
+  // This prevents state updates from stale async operations
+  const isMountedRef = useRef(true);
+
+  // Helper to safely set state only if component is still mounted
+  const safeSetState = <T,>(setter: (value: T) => void, value: T) => {
+    if (isMountedRef.current) {
+      setter(value);
+    }
+  };
+
+  const fetchFiles = useCallback(async (): Promise<void> => {
+    if (!table_name || !record_id || !supabase) {
+      safeSetState(setFileUrl, null);
+      safeSetState(setFileReference, null);
+      safeSetState(setFileReferences, []);
+      safeSetState(setFileUrls, new Map());
+      safeSetState(setFileCount, 0);
+      safeSetState(setIsLoading, false);
+      return;
+    }
+
+    // Validate UUID format for organisationId to prevent database errors (only if provided)
+    if (organisation_id) {
+      const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+      if (!uuidRegex.test(organisation_id)) {
+        logger.warn('useFileDisplay', 'Invalid organisationId format (not a valid UUID):', organisation_id);
+      }
+    }
+
+    safeSetState(setIsLoading, true);
+    safeSetState(setError, null);
+
+    const cacheKey = getFileDisplayCacheKey(table_name, record_id, organisation_id, category);
+    const applied = await tryApplyCacheHit(
+      cacheKey,
+      enableCache,
+      cacheTtl,
+      supabase,
+      organisation_id,
+      record_id,
+      safeSetState,
+      {
+        setFileUrl,
+        setFileReference,
+        setFileReferences,
+        setFileUrls,
+        setFileCount,
+        setIsLoading,
+        setError
+      }
+    );
+    if (applied) return;
+
+    try {
+      const files = await fetchFileDisplayData({
+        table_name,
+        record_id,
+        organisation_id,
+        category,
+        supabase
+      });
+
+      if (files.length === 0) {
+        safeSetState(setFileUrl, null);
+        safeSetState(setFileReference, null);
+        safeSetState(setFileReferences, []);
+        safeSetState(setFileUrls, new Map());
+        safeSetState(setFileCount, 0);
+        if (enableCache) {
+          authenticatedFileCache.set(cacheKey, {
+            data: { fileUrl: null, fileReference: null, fileReferences: [], fileUrls: new Map(), fileCount: 0 },
+            timestamp: Date.now(),
+            ttl: cacheTtl
+          });
+          cleanupCache();
+        }
+        return;
+      }
+
+      await applyFetchedFilesAndCache(
+        files,
+        category,
+        table_name,
+        record_id,
+        organisation_id,
+        supabase,
+        cacheKey,
+        enableCache,
+        cacheTtl,
+        safeSetState,
+        { setFileUrl, setFileReference, setFileReferences, setFileUrls, setFileCount }
+      );
+    } catch (err) {
+      logger.error('useFileDisplay', 'Error fetching files:', err);
+      const error = err instanceof Error ? err : new Error('Unknown error occurred');
+      safeSetState(setError, error);
+      safeSetState(setFileUrl, null);
+      safeSetState(setFileReference, null);
+      safeSetState(setFileReferences, []);
+      safeSetState(setFileUrls, new Map());
+      safeSetState(setFileCount, 0);
+    } finally {
+      safeSetState(setIsLoading, false);
+    }
+  }, [table_name, record_id, organisation_id, category, supabase, cacheTtl, enableCache]);
+
+  // Fetch files when parameters change
+  useEffect(() => {
+    // Mark as mounted when effect runs
+    isMountedRef.current = true;
+
+    if (table_name && record_id && supabase) {
+      // Call fetchFiles - it will check isMountedRef before setting state
+      fetchFiles().catch((err) => {
+        // Only set error if component is still mounted
+        if (isMountedRef.current) {
+          safeSetState(setError, err instanceof Error ? err : new Error('Unknown error'));
+        }
+      });
+    } else {
+      // Only update state if component is still mounted
+      safeSetState(setFileUrl, null);
+      safeSetState(setFileReference, null);
+      safeSetState(setFileReferences, []);
+      safeSetState(setFileUrls, new Map());
+      safeSetState(setFileCount, 0);
+      safeSetState(setIsLoading, false);
+      safeSetState(setError, null);
+    }
+
+    // Cleanup: mark as unmounted when dependencies change or component unmounts
+    // This prevents state updates from stale requests
+    return () => {
+      isMountedRef.current = false;
+    };
+    // fetchFiles is memoized; we only need to re-run when parameters change
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [table_name, record_id, organisation_id, supabase]);
+
+  const refetch = useCallback(async (): Promise<void> => {
+    if (!table_name || !record_id || !supabase) return;
+
+    if (enableCache) {
+      authenticatedFileCache.delete(getFileDisplayCacheKey(table_name, record_id, organisation_id, category));
+    }
+    await fetchFiles();
+  }, [fetchFiles, table_name, record_id, organisation_id, category, supabase, enableCache]);
+
+  return {
+    fileUrl,
+    fileReference,
+    fileReferences,
+    fileUrls,
+    fileCount,
+    isLoading,
+    error,
+    refetch
+  };
+}
+
+/**
+ * Clear all cached authenticated file data
+ * Useful for testing or when you need to force refresh all data
+ */
+export function clearFileDisplayCache(): void {
+  for (const [key] of authenticatedFileCache) {
+    if (key.startsWith('file_')) {
+      authenticatedFileCache.delete(key);
+    }
+  }
+}
+
+/**
+ * Get cache statistics for debugging
+ */
+export function getFileDisplayCacheStats(): { size: number; keys: string[] } {
+  const keys = Array.from(authenticatedFileCache.keys()).filter(key => key.startsWith('file_'));
+  return {
+    size: keys.length,
+    keys
+  };
+}
+
+/**
+ * Invalidate cache for a specific file display entry
+ * Useful for clearing cache after file uploads or updates
+ *
+ * @param table_name - The table name containing the file reference
+ * @param record_id - The record ID that owns the file(s)
+ * @param organisation_id - The organisation ID for storage path
+ * @param category - Optional file category to invalidate (if provided, also invalidates 'all' category)
+ */
+export function invalidateFileDisplayCache(
+  table_name: string,
+  record_id: string,
+  organisation_id: string | null | undefined,
+  category?: FileCategory
+): void {
+  const orgId = organisation_id ?? undefined;
+  authenticatedFileCache.delete(getFileDisplayCacheKey(table_name, record_id, orgId, category));
+  if (category) {
+    authenticatedFileCache.delete(getFileDisplayCacheKey(table_name, record_id, orgId, undefined));
+  }
+}