@jmruthers/pace-core 0.5.186 → 0.5.187

package/src/hooks/useAddressAutocomplete.ts

@@ -0,0 +1,268 @@
+/**
+ * @file Address Autocomplete Hook
+ * @package @jmruthers/pace-core
+ * @module Hooks/AddressAutocomplete
+ * @since 0.1.0
+ *
+ * Hook for managing Google Places API autocomplete functionality.
+ * Provides debounced input, caching, and address selection.
+ */
+
+import { useState, useEffect, useCallback, useRef, useMemo } from 'react';
+import { useDebounce } from './useDebounce';
+import { useQueryCache } from './useQueryCache';
+import {
+  fetchPlaceAutocomplete,
+  fetchPlaceDetails,
+  createAddressFromPlaceResult,
+  getAddressByPlaceId,
+} from '../utils/google-places';
+import type {
+  GooglePlaceAutocompletePrediction,
+  ParsedAddress,
+  AutocompleteOptions,
+} from '../utils/google-places';
+
+export interface UseAddressAutocompleteOptions {
+  /** Google Places API options */
+  autocompleteOptions?: AutocompleteOptions;
+  /** Debounce delay in milliseconds (default: 300) */
+  debounceDelay?: number;
+  /** Enable caching (default: true) */
+  cacheEnabled?: boolean;
+  /** Cache TTL configuration */
+  cacheTTL?: {
+    /** Autocomplete cache TTL in seconds (default: 3600 = 1 hour) */
+    autocomplete?: number;
+    /** Place details cache TTL in seconds (default: 86400 = 24 hours) */
+    placeDetails?: number;
+  };
+}
+
+export interface UseAddressAutocompleteReturn {
+  /** Array of autocomplete suggestions */
+  suggestions: GooglePlaceAutocompletePrediction[];
+  /** Loading state */
+  isLoading: boolean;
+  /** Error state */
+  error: Error | null;
+  /** Select an address by place_id */
+  selectAddress: (placeId: string) => Promise<ParsedAddress | null>;
+  /** Get address by place_id (uses cache) */
+  getAddressByPlaceId: (placeId: string) => Promise<ParsedAddress | null>;
+  /** Clear suggestions */
+  clearSuggestions: () => void;
+}
+
+/**
+ * Hook for Google Places API autocomplete with caching
+ *
+ * @param apiKey - Google Places API key
+ * @param inputValue - Current input value
+ * @param options - Hook configuration options
+ * @returns Autocomplete state and functions
+ *
+ * @example
+ * ```tsx
+ * const { suggestions, isLoading, selectAddress } = useAddressAutocomplete(
+ *   apiKey,
+ *   inputValue,
+ *   { debounceDelay: 300, cacheEnabled: true }
+ * );
+ * ```
+ */
+export function useAddressAutocomplete(
+  apiKey: string,
+  inputValue: string,
+  options: UseAddressAutocompleteOptions = {}
+): UseAddressAutocompleteReturn {
+  const {
+    debounceDelay = 300,
+    cacheEnabled = true,
+    cacheTTL = {
+      autocomplete: 3600, // 1 hour
+      placeDetails: 86400, // 24 hours
+    },
+    autocompleteOptions,
+  } = options;
+
+  const [suggestions, setSuggestions] = useState<GooglePlaceAutocompletePrediction[]>([]);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const debouncedInput = useDebounce(inputValue, debounceDelay);
+  const { getCachedQuery } = useQueryCache();
+  const abortControllerRef = useRef<AbortController | null>(null);
+
+  // Memoize autocompleteOptions to prevent unnecessary re-renders
+  const memoizedAutocompleteOptions = useMemo(
+    () => autocompleteOptions,
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [JSON.stringify(autocompleteOptions)]
+  );
+
+  // Fetch autocomplete suggestions
+  useEffect(() => {
+    // Cancel previous request if still in flight
+    if (abortControllerRef.current) {
+      abortControllerRef.current.abort();
+    }
+
+    // Reset state if input is empty
+    if (!debouncedInput.trim()) {
+      setSuggestions([]);
+      setIsLoading(false);
+      setError(null);
+      return;
+    }
+
+    // Don't fetch if no API key
+    if (!apiKey) {
+      setError(new Error('Google Places API key is required'));
+      return;
+    }
+
+    setIsLoading(true);
+    setError(null);
+
+    const fetchSuggestions = async () => {
+      try {
+        let predictions: GooglePlaceAutocompletePrediction[];
+
+        if (cacheEnabled) {
+          // Use cached query with TTL
+          predictions = await getCachedQuery(
+            'google-places-autocomplete',
+            'query',
+            debouncedInput,
+            async () => {
+              return fetchPlaceAutocomplete(debouncedInput, apiKey, memoizedAutocompleteOptions);
+            },
+            { ttl: cacheTTL.autocomplete, enabled: true }
+          );
+        } else {
+          // Direct fetch without cache
+          predictions = await fetchPlaceAutocomplete(debouncedInput, apiKey, memoizedAutocompleteOptions);
+        }
+
+        setSuggestions(predictions);
+        setIsLoading(false);
+      } catch (err) {
+        // Ignore aborted requests
+        if (err instanceof Error && err.name === 'AbortError') {
+          return;
+        }
+
+        const error = err instanceof Error ? err : new Error('Failed to fetch autocomplete suggestions');
+        setError(error);
+        setSuggestions([]);
+        setIsLoading(false);
+      }
+    };
+
+    fetchSuggestions();
+
+    // Cleanup function to cancel in-flight requests
+    return () => {
+      if (abortControllerRef.current) {
+        abortControllerRef.current.abort();
+      }
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [debouncedInput, apiKey, cacheEnabled, cacheTTL.autocomplete]);
+
+  // Select address by place_id
+  const selectAddress = useCallback(
+    async (placeId: string): Promise<ParsedAddress | null> => {
+      if (!placeId || !apiKey) {
+        return null;
+      }
+
+      setIsLoading(true);
+      setError(null);
+
+      try {
+        let placeDetails;
+
+        if (cacheEnabled) {
+          // Use cached query with TTL
+          placeDetails = await getCachedQuery(
+            'google-places-details',
+            'place_id',
+            placeId,
+            async () => {
+              return fetchPlaceDetails(placeId, apiKey);
+            },
+            { ttl: cacheTTL.placeDetails, enabled: true }
+          );
+        } else {
+          // Direct fetch without cache
+          placeDetails = await fetchPlaceDetails(placeId, apiKey);
+        }
+
+        const parsedAddress = createAddressFromPlaceResult(placeDetails);
+        setIsLoading(false);
+        return parsedAddress;
+      } catch (err) {
+        const error = err instanceof Error ? err : new Error('Failed to fetch place details');
+        setError(error);
+        setIsLoading(false);
+        return null;
+      }
+    },
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [apiKey, cacheEnabled, cacheTTL.placeDetails]
+  );
+
+  // Get address by place_id (utility function)
+  const getAddressByPlaceIdFn = useCallback(
+    async (placeId: string): Promise<ParsedAddress | null> => {
+      if (!placeId || !apiKey) {
+        return null;
+      }
+
+      try {
+        if (cacheEnabled) {
+          // Use cached query with TTL
+          return await getCachedQuery(
+            'google-places-details',
+            'place_id',
+            placeId,
+            async () => {
+              const result = await getAddressByPlaceId(placeId, apiKey);
+              if (!result) {
+                throw new Error('Failed to fetch address');
+              }
+              return result;
+            },
+            { ttl: cacheTTL.placeDetails, enabled: true }
+          );
+        } else {
+          return await getAddressByPlaceId(placeId, apiKey);
+        }
+      } catch (err) {
+        const error = err instanceof Error ? err : new Error('Failed to get address by place_id');
+        setError(error);
+        return null;
+      }
+    },
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [apiKey, cacheEnabled, cacheTTL.placeDetails]
+  );
+
+  // Clear suggestions
+  const clearSuggestions = useCallback(() => {
+    setSuggestions([]);
+    setError(null);
+  }, []);
+
+  return {
+    suggestions,
+    isLoading,
+    error,
+    selectAddress,
+    getAddressByPlaceId: getAddressByPlaceIdFn,
+    clearSuggestions,
+  };
+}
+

package/src/hooks/useFileDisplay.ts

@@ -37,7 +37,7 @@
 import { useState, useEffect, useCallback } from 'react';
 import type { SupabaseClient } from '@supabase/supabase-js';
 import { FileReference, FileCategory } from '../types/file-reference';
-import { getPublicUrl, getSignedUrl } from '../utils/storage/helpers';
+import { getPublicUrl, getSignedUrl, generateFileUrlsBatch } from '../utils/storage/helpers';
 import { createFileReferenceService } from '../utils/file-reference';
 import { logger } from '../utils/core/logger';
 
@@ -279,24 +279,12 @@ export function useFileDisplay(
         logger.debug('useFileDisplay', 'Setting file URL:', url ? 'URL set' : 'URL is null');
         setFileUrl(url);
       } else {
-        // Multiple files mode - generate URLs for all files
-        const urlMap = new Map<string, string>();
-        for (const fileRef of files) {
-          let url: string | null = null;
-          if (fileRef.is_public) {
-            url = getPublicUrl(supabase, fileRef.file_path, true);
-          } else {
-            const signedUrlResult = await getSignedUrl(supabase, fileRef.file_path, {
+        // Multiple files mode - generate URLs for all files in batch
+        const urlMap = await generateFileUrlsBatch(supabase, files, {
               appName: 'pace-core',
               orgId: organisation_id,
               expiresIn: 3600
             });
-            url = signedUrlResult?.url || null;
-          }
-          if (url) {
-            urlMap.set(fileRef.id, url);
-          }
-        }
         setFileUrls(urlMap);
         setFileReference(null);
         setFileUrl(null);

package/src/hooks/useFileReference.test.ts

@@ -18,6 +18,7 @@ let serviceMock: any;
 const mockUploadFileWithReference = vi.fn();
 const mockGetPublicUrl = vi.fn();
 const mockGetSignedUrl = vi.fn();
+const mockGenerateFileUrlsBatch = vi.fn();
 
 // Setup mocks
 beforeEach(() => {
@@ -47,12 +48,25 @@ beforeEach(() => {
     url: 'https://example.com/signed-file.jpg', 
     expiresAt: new Date(Date.now() + 3600 * 1000).toISOString() 
   });
+  // Mock batch URL generation to return URLs for all files
+  mockGenerateFileUrlsBatch.mockImplementation(async (supabase, files) => {
+    const urlMap = new Map<string, string>();
+    for (const file of files) {
+      if (file.is_public) {
+        urlMap.set(file.id, `https://example.com/${file.file_path}`);
+      } else {
+        urlMap.set(file.id, `https://example.com/signed/${file.file_path}`);
+      }
+    }
+    return urlMap;
+  });
   
   // Apply mocks
   vi.spyOn(fileReferenceUtils, 'createFileReferenceService').mockImplementation(mockCreateFileReferenceService as any);
   vi.spyOn(fileReferenceUtils, 'uploadFileWithReference').mockImplementation(mockUploadFileWithReference as any);
   vi.spyOn(storageHelpers, 'getPublicUrl').mockImplementation(mockGetPublicUrl as any);
   vi.spyOn(storageHelpers, 'getSignedUrl').mockImplementation(mockGetSignedUrl as any);
+  vi.spyOn(storageHelpers, 'generateFileUrlsBatch').mockImplementation(mockGenerateFileUrlsBatch as any);
 });
 
 afterEach(() => {
@@ -505,16 +519,19 @@ describe('[hook] useFilesByCategory', () => {
     );
     
     await waitFor(() => {
-      expect(mockGetPublicUrl).toHaveBeenCalledWith(mockSupabase, publicFile.file_path, true);
-      expect(mockGetSignedUrl).toHaveBeenCalledWith(
+      // Verify batch URL generation was called with both files
+      expect(mockGenerateFileUrlsBatch).toHaveBeenCalledWith(
         mockSupabase,
-        privateFile.file_path,
+        [publicFile, privateFile],
         expect.objectContaining({
           appName: 'file-reference',
           orgId: 'test-org-123',
           expiresIn: 3600
         })
       );
+      // Verify URLs were generated
+      expect(result.current.fileUrls.get(publicFile.id)).toBeDefined();
+      expect(result.current.fileUrls.get(privateFile.id)).toBeDefined();
     });
   });
 });

package/src/hooks/useFileReference.ts

@@ -11,7 +11,7 @@ import {
   FileCategory
 } from '../types/file-reference';
 import { createFileReferenceService, uploadFileWithReference } from '../utils/file-reference';
-import { getPublicUrl, getSignedUrl } from '../utils/storage/helpers';
+import { getPublicUrl, getSignedUrl, generateFileUrlsBatch } from '../utils/storage/helpers';
 import { createLogger } from '../utils/core/logger';
 
 const log = createLogger('useFileReference');
@@ -401,33 +401,12 @@ export function useFilesByCategory(
     const files = await getFilesByCategory(table_name, record_id, category, organisation_id);
     setFileReferences(files);
 
-    // Load URLs for all files
-    const urlMap = new Map<string, string>();
-    
-    for (const fileRef of files) {
-      try {
-        let url: string | null = null;
-
-        if (fileRef.is_public) {
-          // Public files: generate public URL
-          url = getPublicUrl(supabase, fileRef.file_path, true);
-        } else {
-          // Private files: generate signed URL
-          const signedUrlResult = await getSignedUrl(supabase, fileRef.file_path, {
+    // Load URLs for all files in batch
+    const urlMap = await generateFileUrlsBatch(supabase, files, {
             appName: 'file-reference',
             orgId: organisation_id,
             expiresIn: 3600
           });
-          url = signedUrlResult?.url || null;
-        }
-
-        if (url) {
-          urlMap.set(fileRef.id, url);
-        }
-      } catch (err) {
-        log.error(`Failed to load URL for file ${fileRef.id}:`, err);
-      }
-    }
     
     setFileUrls(urlMap);
     return files;

package/src/hooks/useFileUrlCache.ts

@@ -0,0 +1,246 @@
+/**
+ * @file File URL Cache Hook
+ * @package @jmruthers/pace-core
+ * @module Hooks
+ *
+ * Centralized caching hook for file URLs to prevent duplicate requests
+ * and improve performance across components.
+ *
+ * Features:
+ * - TTL-based caching matching signed URL expiration (3600s)
+ * - Automatic cache cleanup
+ * - Supports both public and signed URLs
+ * - Thread-safe cache operations
+ *
+ * @example
+ * ```tsx
+ * import { useFileUrlCache } from '@jmruthers/pace-core';
+ *
+ * function MyComponent() {
+ *   const { getUrl, setUrl, clearCache } = useFileUrlCache();
+ *
+ *   const url = await getUrl(fileReference, supabase, organisationId);
+ *   return <img src={url} alt="File" />;
+ * }
+ * ```
+ */
+
+import { useRef, useCallback } from 'react';
+import type { SupabaseClient } from '@supabase/supabase-js';
+import { FileReference } from '../types/file-reference';
+import { getPublicUrl, getSignedUrl } from '../utils/storage/helpers';
+
+interface CachedUrl {
+  url: string;
+  expiresAt: number; // Timestamp in milliseconds
+}
+
+// Global cache shared across all hook instances
+const globalUrlCache = new Map<string, CachedUrl>();
+
+// Cache size limit to prevent memory leaks
+const MAX_CACHE_SIZE = 500;
+
+// Default TTL matches signed URL expiration (3600 seconds = 1 hour)
+const DEFAULT_TTL_MS = 3600 * 1000;
+
+/**
+ * Generate cache key from file reference
+ */
+function getCacheKey(fileReference: FileReference): string {
+  return `file-url:${fileReference.id}:${fileReference.is_public ? 'public' : 'private'}`;
+}
+
+/**
+ * Clean up expired entries and enforce size limit
+ */
+function cleanupCache(): void {
+  const now = Date.now();
+  
+  // Remove expired entries
+  for (const [key, value] of globalUrlCache.entries()) {
+    if (value.expiresAt < now) {
+      globalUrlCache.delete(key);
+    }
+  }
+  
+  // Enforce size limit by removing oldest entries
+  if (globalUrlCache.size > MAX_CACHE_SIZE) {
+    const entries = Array.from(globalUrlCache.entries());
+    // Sort by expiration time (oldest first)
+    entries.sort((a, b) => a[1].expiresAt - b[1].expiresAt);
+    
+    // Remove oldest 20% of entries
+    const toRemove = Math.floor(MAX_CACHE_SIZE * 0.2);
+    for (let i = 0; i < toRemove && i < entries.length; i++) {
+      globalUrlCache.delete(entries[i][0]);
+    }
+  }
+}
+
+export interface UseFileUrlCacheReturn {
+  /**
+   * Get URL for a file reference, using cache if available
+   * @param fileReference - File reference to get URL for
+   * @param supabase - Supabase client instance
+   * @param organisationId - Organisation ID for signed URLs
+   * @param ttl - Time to live in milliseconds (default: 3600000 = 1 hour)
+   * @returns Promise resolving to URL string or null
+   */
+  getUrl: (
+    fileReference: FileReference,
+    supabase: SupabaseClient,
+    organisationId: string,
+    ttl?: number
+  ) => Promise<string | null>;
+  
+  /**
+   * Set URL in cache
+   * @param fileReference - File reference
+   * @param url - URL to cache
+   * @param ttl - Time to live in milliseconds (default: 3600000 = 1 hour)
+   */
+  setUrl: (fileReference: FileReference, url: string, ttl?: number) => void;
+  
+  /**
+   * Get URL from cache without generating if missing
+   * @param fileReference - File reference
+   * @returns Cached URL or null if not in cache or expired
+   */
+  getCachedUrl: (fileReference: FileReference) => string | null;
+  
+  /**
+   * Clear cache for a specific file reference
+   * @param fileReference - File reference to clear
+   */
+  clearFile: (fileReference: FileReference) => void;
+  
+  /**
+   * Clear all cached URLs
+   */
+  clearCache: () => void;
+  
+  /**
+   * Get cache statistics
+   */
+  getCacheStats: () => { size: number; maxSize: number };
+}
+
+/**
+ * Hook for centralized file URL caching
+ * 
+ * This hook provides a shared cache for file URLs across all components,
+ * preventing duplicate requests for the same file.
+ * 
+ * @returns Cache operations and utilities
+ */
+export function useFileUrlCache(): UseFileUrlCacheReturn {
+  // Use ref to ensure stable reference across renders
+  const cleanupIntervalRef = useRef<number | null>(null);
+  
+  // Set up periodic cleanup (every 5 minutes)
+  if (cleanupIntervalRef.current === null && typeof window !== 'undefined') {
+    cleanupIntervalRef.current = window.setInterval(() => {
+      cleanupCache();
+    }, 5 * 60 * 1000); // 5 minutes
+  }
+  
+  const getUrl = useCallback(async (
+    fileReference: FileReference,
+    supabase: SupabaseClient,
+    organisationId: string,
+    ttl: number = DEFAULT_TTL_MS
+  ): Promise<string | null> => {
+    const cacheKey = getCacheKey(fileReference);
+    const cached = globalUrlCache.get(cacheKey);
+    const now = Date.now();
+    
+    // Return cached URL if still valid
+    if (cached && cached.expiresAt > now) {
+      return cached.url;
+    }
+    
+    // Generate new URL
+    let url: string | null = null;
+    
+    try {
+      if (fileReference.is_public) {
+        // Public files: generate public URL (synchronous)
+        url = getPublicUrl(supabase, fileReference.file_path, true);
+      } else {
+        // Private files: generate signed URL (async)
+        const signedUrlResult = await getSignedUrl(supabase, fileReference.file_path, {
+          appName: 'pace-core',
+          orgId: organisationId,
+          expiresIn: Math.floor(ttl / 1000) // Convert ms to seconds
+        });
+        url = signedUrlResult?.url || null;
+      }
+      
+      // Cache the URL if generated successfully
+      if (url) {
+        globalUrlCache.set(cacheKey, {
+          url,
+          expiresAt: now + ttl
+        });
+        cleanupCache(); // Clean up after adding
+      }
+      
+      return url;
+    } catch (error) {
+      console.error('Failed to generate file URL:', error);
+      return null;
+    }
+  }, []);
+  
+  const setUrl = useCallback((
+    fileReference: FileReference,
+    url: string,
+    ttl: number = DEFAULT_TTL_MS
+  ): void => {
+    const cacheKey = getCacheKey(fileReference);
+    globalUrlCache.set(cacheKey, {
+      url,
+      expiresAt: Date.now() + ttl
+    });
+    cleanupCache();
+  }, []);
+  
+  const getCachedUrl = useCallback((fileReference: FileReference): string | null => {
+    const cacheKey = getCacheKey(fileReference);
+    const cached = globalUrlCache.get(cacheKey);
+    const now = Date.now();
+    
+    if (cached && cached.expiresAt > now) {
+      return cached.url;
+    }
+    
+    return null;
+  }, []);
+  
+  const clearFile = useCallback((fileReference: FileReference): void => {
+    const cacheKey = getCacheKey(fileReference);
+    globalUrlCache.delete(cacheKey);
+  }, []);
+  
+  const clearCache = useCallback((): void => {
+    globalUrlCache.clear();
+  }, []);
+  
+  const getCacheStats = useCallback(() => {
+    return {
+      size: globalUrlCache.size,
+      maxSize: MAX_CACHE_SIZE
+    };
+  }, []);
+  
+  return {
+    getUrl,
+    setUrl,
+    getCachedUrl,
+    clearFile,
+    clearCache,
+    getCacheStats
+  };
+}
+