@jmruthers/pace-core 0.5.185 → 0.5.187

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
+  };
+}
+

package/src/hooks/useInactivityTracker.ts

@@ -155,6 +155,7 @@ export function useInactivityTracker({
   const countdownIntervalRef = useRef<NodeJS.Timeout | null>(null);
   const lastActivityRef = useRef<number>(Date.now());
   const channelRef = useRef<BroadcastChannel | null>(null);
+  const throttledResetActivityRef = useRef<((event: Event) => void) | null>(null);
 
   // Clear all timers
   const clearTimers = useCallback(() => {
@@ -294,47 +295,56 @@ export function useInactivityTracker({
       logger.warn('useInactivityTracker', 'Failed to check persisted activity time:', error);
     }
 
-    // Set up throttled activity handler
-    const throttledResetActivity = throttle((event) => {
-      resetActivity();
-    }, 100);
-
-    // Add event listeners
-    const addEventListeners = () => {
+    // Clean up any existing throttled handler and event listeners first
+    if (throttledResetActivityRef.current) {
       ACTIVITY_EVENTS.forEach(event => {
-        document.addEventListener(event, throttledResetActivity, { passive: true });
+        document.removeEventListener(event, throttledResetActivityRef.current!);
       });
-    };
+    }
 
-    // Remove event listeners
-    const removeEventListeners = () => {
-      ACTIVITY_EVENTS.forEach(event => {
-        document.removeEventListener(event, throttledResetActivity);
-      });
-    };
+    // Set up throttled activity handler - store in ref for proper cleanup
+    throttledResetActivityRef.current = throttle((event) => {
+      resetActivity();
+    }, 100);
 
-    // Add listeners
-    addEventListeners();
+    // Add event listeners
+    ACTIVITY_EVENTS.forEach(event => {
+      document.addEventListener(event, throttledResetActivityRef.current!, { passive: true });
+    });
 
     // Start the timer (skip activity callback for initial setup)
     resetActivity(true);
 
     // Cleanup function
     return () => {
-      removeEventListeners();
+      // Remove event listeners using the stored ref
+      if (throttledResetActivityRef.current) {
+        ACTIVITY_EVENTS.forEach(event => {
+          document.removeEventListener(event, throttledResetActivityRef.current!);
+        });
+        throttledResetActivityRef.current = null;
+      }
       clearTimers();
       if (channelRef.current) {
         channelRef.current.close();
         channelRef.current = null;
       }
     };
-  }, [enabled, isTracking, channelName, storageKey, idleTimeoutMs, warnBeforeMs, onIdle, onWarning]);
+  }, [enabled, isTracking, channelName, storageKey, idleTimeoutMs, warnBeforeMs, onIdle, onWarning, onActivity, resetActivity]);
 
   // Stop tracking
   const stopTracking = useCallback(() => {
     setIsTracking(false);
     clearTimers();
     
+    // Remove event listeners
+    if (throttledResetActivityRef.current) {
+      ACTIVITY_EVENTS.forEach(event => {
+        document.removeEventListener(event, throttledResetActivityRef.current!);
+      });
+      throttledResetActivityRef.current = null;
+    }
+    
     if (channelRef.current) {
       channelRef.current.close();
       channelRef.current = null;
@@ -348,8 +358,9 @@ export function useInactivityTracker({
       return cleanup;
     } else {
       stopTracking();
+      return undefined;
     }
-  }, [enabled, idleTimeoutMs, warnBeforeMs]);
+  }, [enabled, idleTimeoutMs, warnBeforeMs, startTracking, stopTracking]);
 
   // Cleanup on unmount
   useEffect(() => {

package/src/hooks/useOrganisationSecurity.test.ts

@@ -26,6 +26,7 @@ vi.mock('./useOrganisations', () => ({
 // Mock the RBAC API
 vi.mock('../rbac/api', () => ({
   isPermitted: vi.fn(),
+  isPermittedCached: vi.fn(),
   isSuperAdmin: vi.fn(),
   getPermissionMap: vi.fn()
 }));
@@ -35,13 +36,14 @@ vi.mock('../rbac/audit', () => ({
   emitAuditEvent: vi.fn()
 }));
 
-import { isPermitted, isSuperAdmin, getPermissionMap } from '../rbac/api';
+import { isPermitted, isPermittedCached, isSuperAdmin, getPermissionMap } from '../rbac/api';
 import { emitAuditEvent } from '../rbac/audit';
 
 describe('useOrganisationSecurity', () => {
   const mockUseUnifiedAuth = vi.mocked(useUnifiedAuth);
   const mockUseOrganisations = vi.mocked(useOrganisations);
   const mockIsPermitted = vi.mocked(isPermitted);
+  const mockIsPermittedCached = vi.mocked(isPermittedCached);
   const mockIsSuperAdmin = vi.mocked(isSuperAdmin);
   const mockGetPermissionMap = vi.mocked(getPermissionMap);
   const mockEmitAuditEvent = vi.mocked(emitAuditEvent);
@@ -99,6 +101,7 @@ describe('useOrganisationSecurity', () => {
     mockUseUnifiedAuth.mockClear();
     mockUseOrganisations.mockClear();
     mockIsPermitted.mockClear();
+    mockIsPermittedCached.mockClear();
     mockIsSuperAdmin.mockClear();
     mockGetPermissionMap.mockClear();
     mockEmitAuditEvent.mockClear();
@@ -508,13 +511,13 @@ describe('useOrganisationSecurity', () => {
         signOut: vi.fn(),
       } as any);
 
-      mockIsPermitted.mockResolvedValue(true);
+      mockIsPermittedCached.mockResolvedValue(true);
 
       const { result } = renderHook(() => useOrganisationSecurity());
 
       const hasPermission = await result.current.hasPermission('read:users');
       expect(hasPermission).toBe(true);
-      expect(mockIsPermitted).toHaveBeenCalledWith({
+      expect(mockIsPermittedCached).toHaveBeenCalledWith({
         userId: 'user-123',
         scope: {
           organisationId: 'org-123',
@@ -527,13 +530,13 @@ describe('useOrganisationSecurity', () => {
 
     it('checks permissions for specific organisation', async () => {
       mockIsSuperAdmin.mockResolvedValue(false);
-      mockIsPermitted.mockResolvedValue(true);
+      mockIsPermittedCached.mockResolvedValue(true);
 
       const { result } = renderHook(() => useOrganisationSecurity());
 
       const hasPermission = await result.current.hasPermission('read:users', 'org-456');
       expect(hasPermission).toBe(true);
-      expect(mockIsPermitted).toHaveBeenCalledWith({
+      expect(mockIsPermittedCached).toHaveBeenCalledWith({
         userId: 'user-123',
         scope: {
           organisationId: 'org-456',
@@ -546,7 +549,7 @@ describe('useOrganisationSecurity', () => {
 
     it('handles permission check errors gracefully', async () => {
       mockIsSuperAdmin.mockResolvedValue(false);
-      mockIsPermitted.mockRejectedValue(new Error('Permission check failed'));
+      mockIsPermittedCached.mockRejectedValue(new Error('Permission check failed'));
 
       const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
 
@@ -622,7 +625,7 @@ describe('useOrganisationSecurity', () => {
 
     it('handles permission retrieval errors gracefully', async () => {
       mockIsSuperAdmin.mockResolvedValue(false);
-      mockIsPermitted.mockRejectedValue(new Error('Permission retrieval failed'));
+      mockIsPermittedCached.mockRejectedValue(new Error('Permission retrieval failed'));
 
       const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
 

package/src/hooks/useOrganisationSecurity.ts

@@ -163,8 +163,8 @@ export const useOrganisationSecurity = (): OrganisationSecurityHook => {
     if (!targetOrgId || !user) return false;
 
     try {
-      // Use the new RBAC system
-      const { isPermitted } = await import('../rbac/api');
+      // Use the new RBAC system with caching
+      const { isPermittedCached } = await import('../rbac/api');
       
       const scope = {
         organisationId: targetOrgId,
@@ -172,7 +172,7 @@ export const useOrganisationSecurity = (): OrganisationSecurityHook => {
         appId: user.user_metadata?.appId || user.app_metadata?.appId,
       };
 
-      return await isPermitted({
+      return await isPermittedCached({
         userId: user.id,
         scope,
         permission: permission as Permission

package/src/hooks/usePreventTabReload.ts

@@ -0,0 +1,106 @@
+/**
+ * @file usePreventTabReload Hook
+ * @package @jmruthers/pace-core
+ * @module Hooks
+ * @since 0.6.0
+ *
+ * Prevents full page reloads when switching browser tabs.
+ * Handles browser back-forward cache (bfcache) restoration and tab visibility changes.
+ */
+
+import { useEffect, useRef } from 'react';
+
+export interface UsePreventTabReloadOptions {
+  /**
+   * Whether to enable the prevention logic
+   * @default true
+   */
+  enabled?: boolean;
+
+  /**
+   * Grace period in milliseconds to wait after tab becomes visible
+   * before allowing any potential reloads
+   * @default 2000
+   */
+  gracePeriodMs?: number;
+}
+
+/**
+ * Hook to prevent full page reloads when switching browser tabs.
+ * 
+ * This hook handles:
+ * - Browser back-forward cache (bfcache) restoration
+ * - Tab visibility changes
+ * - Prevents unwanted page reloads when returning to a tab
+ * 
+ * @param options - Configuration options
+ * 
+ * @example
+ * ```tsx
+ * import { usePreventTabReload } from '@jmruthers/pace-core';
+ * 
+ * function MyComponent() {
+ *   usePreventTabReload();
+ *   // Component code...
+ * }
+ * ```
+ */
+export function usePreventTabReload(options: UsePreventTabReloadOptions = {}): void {
+  const { enabled = true, gracePeriodMs = 2000 } = options;
+  const isRestoringFromCacheRef = useRef(false);
+  const gracePeriodTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  useEffect(() => {
+    if (!enabled || typeof window === 'undefined') return;
+
+    // Handle pageshow event - detects when page is restored from bfcache
+    const handlePageShow = (event: PageTransitionEvent) => {
+      // If page was restored from bfcache, prevent any reload behavior
+      if (event.persisted) {
+        isRestoringFromCacheRef.current = true;
+        
+        // Clear any existing timeout
+        if (gracePeriodTimeoutRef.current) {
+          clearTimeout(gracePeriodTimeoutRef.current);
+        }
+        
+        // Set grace period to prevent reloads
+        gracePeriodTimeoutRef.current = setTimeout(() => {
+          isRestoringFromCacheRef.current = false;
+        }, gracePeriodMs);
+      }
+    };
+
+    // Handle visibility changes - when tab becomes visible
+    const handleVisibilityChange = () => {
+      if (!document.hidden) {
+        // Tab just became visible - set flag to prevent reloads
+        isRestoringFromCacheRef.current = true;
+        
+        // Clear any existing timeout
+        if (gracePeriodTimeoutRef.current) {
+          clearTimeout(gracePeriodTimeoutRef.current);
+        }
+        
+        // Set grace period
+        gracePeriodTimeoutRef.current = setTimeout(() => {
+          isRestoringFromCacheRef.current = false;
+        }, gracePeriodMs);
+      }
+    };
+
+    // Add event listeners
+    window.addEventListener('pageshow', handlePageShow);
+    document.addEventListener('visibilitychange', handleVisibilityChange);
+
+    return () => {
+      window.removeEventListener('pageshow', handlePageShow);
+      document.removeEventListener('visibilitychange', handleVisibilityChange);
+      
+      if (gracePeriodTimeoutRef.current) {
+        clearTimeout(gracePeriodTimeoutRef.current);
+      }
+    };
+  }, [enabled, gracePeriodMs]);
+}
+