@jmruthers/pace-core 0.5.186 → 0.5.188

package/src/utils/google-places/types.ts

@@ -0,0 +1,94 @@
+/**
+ * @file Google Places API Types
+ * @package @jmruthers/pace-core
+ * @module Utils/GooglePlaces
+ * @since 0.1.0
+ */
+
+/**
+ * Google Places Autocomplete API response prediction
+ */
+export interface GooglePlaceAutocompletePrediction {
+  description: string;
+  place_id: string;
+  structured_formatting?: {
+    main_text: string;
+    secondary_text: string;
+  };
+  types?: string[];
+}
+
+/**
+ * Google Places Autocomplete API response
+ */
+export interface GooglePlaceAutocompleteResponse {
+  predictions: GooglePlaceAutocompletePrediction[];
+  status: string;
+  error_message?: string;
+}
+
+/**
+ * Google Places Details API address component
+ */
+export interface GoogleAddressComponent {
+  long_name: string;
+  short_name: string;
+  types: string[];
+}
+
+/**
+ * Google Places Details API geometry
+ */
+export interface GoogleGeometry {
+  location: {
+    lat: number;
+    lng: number;
+  };
+}
+
+/**
+ * Google Places Details API response
+ */
+export interface GooglePlaceDetailsResponse {
+  result: {
+    place_id: string;
+    formatted_address: string;
+    address_components: GoogleAddressComponent[];
+    geometry: GoogleGeometry;
+  };
+  status: string;
+  error_message?: string;
+}
+
+/**
+ * Parsed address matching pace_address table structure
+ */
+export interface ParsedAddress {
+  place_id: string;
+  full_address: string | null;
+  street_number: string | null;
+  route: string | null;
+  suburb: string | null;
+  state: string | null;
+  postcode: string | null;
+  country: string | null;
+  lat: number | null;
+  lng: number | null;
+}
+
+/**
+ * Options for Google Places Autocomplete API
+ */
+export interface AutocompleteOptions {
+  /** Restrict results to specific countries (ISO 3166-1 Alpha-2 country codes) */
+  components?: string;
+  /** Location bias (lat,lng) */
+  location?: string;
+  /** Radius in meters for location bias */
+  radius?: number;
+  /** Restrict results to specific place types */
+  types?: string;
+  /** Language code for results */
+  language?: string;
+}
+

package/src/utils/index.ts

@@ -156,3 +156,26 @@ export {
   getGoogleMapsUrl
 } from './location';
 export type { Coordinates } from './location';
+
+// Google Places utilities
+export {
+  fetchPlaceAutocomplete,
+  fetchPlaceDetails,
+  parseAddressComponents,
+  createAddressFromPlaceResult,
+  getAddressByPlaceId,
+} from './google-places';
+export type {
+  GooglePlaceAutocompletePrediction,
+  ParsedAddress,
+  AutocompleteOptions,
+} from './google-places';
+
+// Request deduplication utilities
+export {
+  generateRequestKey,
+  getOrCreateRequest,
+  clearInFlightRequests,
+  getInFlightRequestStats,
+  deduplicatedQuery
+} from './request-deduplication';

package/src/utils/request-deduplication.ts

@@ -0,0 +1,165 @@
+/**
+ * Request Deduplication Utility
+ * @package @jmruthers/pace-core
+ * @module Utils/RequestDeduplication
+ * @since 2.0.0
+ * 
+ * Provides request deduplication to prevent duplicate in-flight requests.
+ * When multiple components request the same data simultaneously, only one
+ * request is made and all callers share the same promise.
+ */
+
+import { createLogger } from './core/logger';
+
+const log = createLogger('request-deduplication');
+
+/**
+ * In-flight request cache
+ * Key: request identifier (e.g., "GET:table:filter:value")
+ * Value: Promise that resolves to the request result
+ */
+const inFlightRequests = new Map<string, Promise<any>>();
+
+/**
+ * Generate a request key from request parameters
+ * 
+ * @param method - HTTP method (GET, POST, etc.)
+ * @param table - Table name
+ * @param filters - Filter object
+ * @param select - Select columns
+ * @returns Request key string
+ */
+export function generateRequestKey(
+  method: string,
+  table: string,
+  filters?: Record<string, any>,
+  select?: string
+): string {
+  const filterStr = filters ? JSON.stringify(filters) : '';
+  const selectStr = select || '*';
+  return `${method}:${table}:${filterStr}:${selectStr}`;
+}
+
+/**
+ * Get or create a request
+ * 
+ * If a request with the same key is already in-flight, returns the existing promise.
+ * Otherwise, creates a new request and stores it for deduplication.
+ * 
+ * @param key - Request key
+ * @param requestFn - Function that performs the actual request
+ * @returns Promise that resolves to the request result
+ * 
+ * @example
+ * ```ts
+ * const data = await getOrCreateRequest(
+ *   'GET:pace_person:{"user_id":"123"}',
+ *   async () => {
+ *     const { data } = await supabase
+ *       .from('pace_person')
+ *       .select('id, first_name')
+ *       .eq('user_id', '123')
+ *       .single();
+ *     return data;
+ *   }
+ * );
+ * ```
+ */
+export async function getOrCreateRequest<T>(
+  key: string,
+  requestFn: () => Promise<T>
+): Promise<T> {
+  // Check if request is already in-flight
+  const existingRequest = inFlightRequests.get(key);
+  if (existingRequest) {
+    log.debug(`Request deduplication: reusing in-flight request for ${key}`);
+    return existingRequest as Promise<T>;
+  }
+  
+  // Create new request
+  log.debug(`Creating new request for ${key}`);
+  const requestPromise = requestFn()
+    .then((result) => {
+      // Remove from in-flight cache after completion
+      inFlightRequests.delete(key);
+      return result;
+    })
+    .catch((error) => {
+      // Remove from in-flight cache on error
+      inFlightRequests.delete(key);
+      throw error;
+    });
+  
+  // Store in-flight request
+  inFlightRequests.set(key, requestPromise);
+  
+  return requestPromise;
+}
+
+/**
+ * Clear all in-flight requests
+ * 
+ * Useful for cleanup or testing.
+ */
+export function clearInFlightRequests(): void {
+  const count = inFlightRequests.size;
+  inFlightRequests.clear();
+  log.debug(`Cleared ${count} in-flight requests`);
+}
+
+/**
+ * Get statistics about in-flight requests
+ * 
+ * @returns Statistics object
+ */
+export function getInFlightRequestStats(): {
+  count: number;
+  keys: string[];
+} {
+  return {
+    count: inFlightRequests.size,
+    keys: Array.from(inFlightRequests.keys()),
+  };
+}
+
+/**
+ * Supabase query wrapper with automatic deduplication
+ * 
+ * Wraps a Supabase query to automatically deduplicate identical requests.
+ * 
+ * @param supabase - Supabase client
+ * @param table - Table name
+ * @param filters - Filter object (e.g., { user_id: '123' })
+ * @param select - Select columns (default: '*')
+ * @param requestFn - Function that performs the query
+ * @returns Promise that resolves to query result
+ * 
+ * @example
+ * ```ts
+ * const person = await deduplicatedQuery(
+ *   supabase,
+ *   'pace_person',
+ *   { user_id: userId },
+ *   'id, first_name, last_name',
+ *   async () => {
+ *     const { data } = await supabase
+ *       .from('pace_person')
+ *       .select('id, first_name, last_name')
+ *       .eq('user_id', userId)
+ *       .single();
+ *     return data;
+ *   }
+ * );
+ * ```
+ */
+export async function deduplicatedQuery<T>(
+  supabase: any,
+  table: string,
+  filters: Record<string, any>,
+  select: string,
+  requestFn: () => Promise<T>
+): Promise<T> {
+  const key = generateRequestKey('GET', table, filters, select);
+  return getOrCreateRequest(key, requestFn);
+}
+

package/src/utils/storage/helpers.ts

@@ -30,21 +30,21 @@ export function generateFilePath(options: StorageUploadOptions, fileName: string
   }
   
   if (isPublic) {
-    // Public files go to {orgId}/{category}/filename
+    // Public files go to {orgId}/{folder}/filename
     if (customPath) {
       return `${orgId}/${customPath}/${fileName}`;
     }
     return `${orgId}/public/${fileName}`;
   }
   
-  // Organization-first structure: {orgId}/{category}/filename
+  // Organization-first structure: {orgId}/{folder}/filename
   if (customPath) {
     return `${orgId}/${customPath}/${fileName}`;
   }
   
   // Use customPath if available, otherwise default to files
-  const pathCategory = customPath || 'files';
-  return `${orgId}/${pathCategory}/${fileName}`;
+  const pathFolder = customPath || 'files';
+  return `${orgId}/${pathFolder}/${fileName}`;
 }
 
 /**
@@ -420,6 +420,145 @@ export async function getSignedUrl(
   }
 }
 
+// Global URL cache for batch operations (shared with useFileUrlCache)
+const globalUrlCache = new Map<string, { url: string; expiresAt: number }>();
+const MAX_CACHE_SIZE = 500;
+const DEFAULT_TTL_MS = 3600 * 1000;
+
+function getCacheKey(fileId: string, filePath: string, isPublic: boolean): string {
+  return `file-url:${fileId}:${isPublic ? 'public' : 'private'}`;
+}
+
+function cleanupUrlCache(): 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());
+    entries.sort((a, b) => a[1].expiresAt - b[1].expiresAt);
+    
+    const toRemove = Math.floor(MAX_CACHE_SIZE * 0.2);
+    for (let i = 0; i < toRemove && i < entries.length; i++) {
+      globalUrlCache.delete(entries[i][0]);
+    }
+  }
+}
+
+/**
+ * Generate URLs for multiple file references in parallel
+ * This batches URL generation to reduce sequential requests and uses caching
+ * @param supabase - Supabase client instance
+ * @param fileReferences - Array of file references to generate URLs for
+ * @param options - URL options including expiry time and organisation ID
+ * @returns Map of file ID to URL string (only includes successful URL generations)
+ */
+export async function generateFileUrlsBatch(
+  supabase: SupabaseClient,
+  fileReferences: Array<{ id: string; file_path: string; is_public: boolean }>,
+  options: StorageUrlOptions & { orgId?: string }
+): Promise<Map<string, string>> {
+  const urlMap = new Map<string, string>();
+  
+  if (fileReferences.length === 0) {
+    return urlMap;
+  }
+
+  const now = Date.now();
+  const ttl = (options.expiresIn || 3600) * 1000; // Convert seconds to milliseconds
+  
+  // Separate files into cached, public, and private
+  const publicFiles: Array<{ id: string; file_path: string }> = [];
+  const privateFiles: Array<{ id: string; file_path: string }> = [];
+  const uncachedFiles: Array<{ id: string; file_path: string; is_public: boolean }> = [];
+
+  for (const fileRef of fileReferences) {
+    const cacheKey = getCacheKey(fileRef.id, fileRef.file_path, fileRef.is_public);
+    const cached = globalUrlCache.get(cacheKey);
+    
+    // Use cached URL if still valid
+    if (cached && cached.expiresAt > now) {
+      urlMap.set(fileRef.id, cached.url);
+      continue;
+    }
+    
+    // Add to processing queue
+    if (fileRef.is_public) {
+      publicFiles.push({ id: fileRef.id, file_path: fileRef.file_path });
+    } else {
+      privateFiles.push({ id: fileRef.id, file_path: fileRef.file_path });
+    }
+    uncachedFiles.push(fileRef);
+  }
+
+  // Generate public URLs synchronously (they're just string concatenation)
+  for (const file of publicFiles) {
+    try {
+      const url = getPublicUrl(supabase, file.file_path, true);
+      if (url) {
+        urlMap.set(file.id, url);
+        // Cache the URL
+        const cacheKey = getCacheKey(file.id, file.file_path, true);
+        globalUrlCache.set(cacheKey, {
+          url,
+          expiresAt: now + ttl
+        });
+      }
+    } catch (err) {
+      log.error(`Failed to generate public URL for file ${file.id}:`, err);
+    }
+  }
+
+  // Generate signed URLs in parallel using Promise.all
+  if (privateFiles.length > 0) {
+    const signedUrlPromises = privateFiles.map(async (file) => {
+      try {
+        const signedUrlResult = await getSignedUrl(supabase, file.file_path, {
+          appName: options.appName || 'pace-core',
+          orgId: options.orgId,
+          expiresIn: options.expiresIn || 3600
+        });
+        const url = signedUrlResult?.url || null;
+        
+        // Cache the URL if generated successfully
+        if (url) {
+          const cacheKey = getCacheKey(file.id, file.file_path, false);
+          globalUrlCache.set(cacheKey, {
+            url,
+            expiresAt: now + ttl
+          });
+        }
+        
+        return { id: file.id, url };
+      } catch (err) {
+        log.error(`Failed to generate signed URL for file ${file.id}:`, err);
+        return { id: file.id, url: null };
+      }
+    });
+
+    const signedUrlResults = await Promise.all(signedUrlPromises);
+    
+    for (const result of signedUrlResults) {
+      if (result.url) {
+        urlMap.set(result.id, result.url);
+      }
+    }
+  }
+
+  // Clean up cache after adding new entries
+  if (uncachedFiles.length > 0) {
+    cleanupUrlCache();
+  }
+
+  return urlMap;
+}
+
 /**
  * Delete a file from storage
  * @param supabase - Supabase client instance