@jmruthers/pace-core 0.6.10 → 0.6.11

package/src/utils/{__tests__/formatDate.unit.test.ts → formatDate.unit.test.ts}

@@ -67,13 +67,13 @@ describe('formatDate', () => {
   });
 
   it('returns empty string for null input', () => {
-    // @ts-ignore - Testing invalid input
+    // @ts-expect-error - Testing invalid input (null)
     const result = formatDate(null);
     expect(result).toBe('');
   });
 
   it('returns empty string for undefined input', () => {
-    // @ts-ignore - Testing invalid input
+    // @ts-expect-error - Testing invalid input (undefined)
     const result = formatDate(undefined);
     expect(result).toBe('');
   });

package/src/utils/formatting/formatDateTimeTimezone.test.ts

@@ -1,7 +1,7 @@
 /**
  * @file Timezone-Aware Date Formatting Tests
  * @package @jmruthers/pace-core
- * @module Utils/Formatting/__tests__
+ * @module Utils/Formatting
  * @since 0.1.0
  *
  * Comprehensive tests for timezone-aware date formatting functions.

package/src/utils/formatting/formatNumber.test.ts

@@ -1,7 +1,7 @@
 /**
  * @file Number Formatting Utility Tests
  * @package @jmruthers/pace-core
- * @module Utils/Formatting/__tests__
+ * @module Utils/Formatting
  * @since 1.0.0
  */
 

package/src/utils/{__tests__/formatting.unit.test.ts → formatting.unit.test.ts}

@@ -5,7 +5,7 @@ import {
   formatPercent,
   formatCompactNumber,
   formatFileSize
-} from '../formatting/formatting';
+} from './formatting/formatting';
 
 describe('formatting utilities', () => {
   describe('formatDate', () => {

package/src/utils/google-places/googlePlacesUtils.test.ts

@@ -1,7 +1,7 @@
 /**
  * @file Google Places API Utilities Tests
  * @package @jmruthers/pace-core
- * @module Utils/GooglePlaces/__tests__
+ * @module Utils/GooglePlaces
  * @since 0.1.0
  */
 
@@ -47,7 +47,7 @@ vi.mock('./loadGoogleMapsScript', () => {
   }
 
   return {
-    loadGoogleMapsScript: vi.fn().mockResolvedValue(undefined),
+    loadGoogleMapsScript: vi.fn().mockResolvedValue({ ok: true, data: undefined }),
     isGoogleMapsLoaded: vi.fn(() => {
       const win = typeof window !== 'undefined' ? window : (global as any).window;
       return !!(win?.google?.maps?.places);
@@ -154,24 +154,29 @@ describe('Google Places API Utilities', () => {
 
       const result = await fetchPlaceAutocomplete('123 Main', mockApiKey);
 
-      expect(result).toHaveLength(1);
-      expect(result[0].place_id).toBe('ChIJ123');
-      expect(result[0].description).toBe('123 Main St, Melbourne VIC, Australia');
+      expect(result.ok).toBe(true);
+      expect(result.data).toHaveLength(1);
+      expect(result.data[0].place_id).toBe('ChIJ123');
+      expect(result.data[0].description).toBe('123 Main St, Melbourne VIC, Australia');
       expect(mockAutocompleteService.getPlacePredictions).toHaveBeenCalled();
     });
 
-    it('returns empty array for empty query', async () => {
+    it('returns ok with empty array for empty query', async () => {
       const result = await fetchPlaceAutocomplete('', mockApiKey);
-      expect(result).toEqual([]);
+      expect(result.ok).toBe(true);
+      expect(result.data).toEqual([]);
     });
 
-    it('returns empty array for whitespace-only query', async () => {
+    it('returns ok with empty array for whitespace-only query', async () => {
       const result = await fetchPlaceAutocomplete('   ', mockApiKey);
-      expect(result).toEqual([]);
+      expect(result.ok).toBe(true);
+      expect(result.data).toEqual([]);
     });
 
-    it('throws error when API key is missing', async () => {
-      await expect(fetchPlaceAutocomplete('123 Main', '')).rejects.toThrow('API key is required');
+    it('returns err when API key is missing', async () => {
+      const result = await fetchPlaceAutocomplete('123 Main', '');
+      expect(result.ok).toBe(false);
+      expect(result.error.message).toContain('API key is required');
     });
 
     it('handles ZERO_RESULTS status', { timeout: 5000 }, async () => {
@@ -180,7 +185,8 @@ describe('Google Places API Utilities', () => {
       });
 
       const result = await fetchPlaceAutocomplete('nonexistent', mockApiKey);
-      expect(result).toEqual([]);
+      expect(result.ok).toBe(true);
+      expect(result.data).toEqual([]);
     });
 
     it('handles REQUEST_DENIED status', { timeout: 5000 }, async () => {
@@ -188,7 +194,9 @@ describe('Google Places API Utilities', () => {
         callback(null, 'REQUEST_DENIED');
       });
 
-      await expect(fetchPlaceAutocomplete('123 Main', mockApiKey)).rejects.toThrow('REQUEST_DENIED');
+      const result = await fetchPlaceAutocomplete('123 Main', mockApiKey);
+      expect(result.ok).toBe(false);
+      expect(result.error.message).toContain('REQUEST_DENIED');
     });
 
     it('handles errors', { timeout: 5000 }, async () => {
@@ -196,7 +204,9 @@ describe('Google Places API Utilities', () => {
         callback(null, 'INVALID_REQUEST');
       });
 
-      await expect(fetchPlaceAutocomplete('123 Main', mockApiKey)).rejects.toThrow();
+      const result = await fetchPlaceAutocomplete('123 Main', mockApiKey);
+      expect(result.ok).toBe(false);
+      expect(result.error.message).toContain('INVALID_REQUEST');
     });
 
     it('includes optional parameters in request', { timeout: 5000 }, async () => {
@@ -244,7 +254,8 @@ describe('Google Places API Utilities', () => {
       const result = await fetchPlaceAutocomplete('Main', mockApiKey);
 
       expect(fetchMock).toHaveBeenCalledWith({ input: 'Main' });
-      expect(result).toEqual([
+      expect(result.ok).toBe(true);
+      expect(result.data).toEqual([
         {
           description: 'Main St',
           place_id: 'place-new',
@@ -261,9 +272,9 @@ describe('Google Places API Utilities', () => {
       (window as any).google.maps.places.AutocompleteSuggestion = mockAutocompleteSuggestion as any;
       mockAutocompleteSuggestion.fetchAutocompleteSuggestions.mockRejectedValue(new Error('network down'));
 
-      await expect(fetchPlaceAutocomplete('Main', mockApiKey)).rejects.toThrow(
-        'Failed to fetch autocomplete predictions: network down'
-      );
+      const result = await fetchPlaceAutocomplete('Main', mockApiKey);
+      expect(result.ok).toBe(false);
+      expect(result.error.message).toContain('network down');
     });
 
     it('builds a new API request with location bias and region codes', async () => {
@@ -290,22 +301,24 @@ describe('Google Places API Utilities', () => {
       });
     });
 
-    it('returns empty array when new API suggestions are empty', async () => {
+    it('returns ok with empty array when new API suggestions are empty', async () => {
       (window as any).google.maps.places.AutocompleteSuggestion = mockAutocompleteSuggestion as any;
       mockAutocompleteSuggestion.fetchAutocompleteSuggestions.mockResolvedValue({ suggestions: [] });
 
       const result = await fetchPlaceAutocomplete('Main', mockApiKey);
 
-      expect(result).toEqual([]);
+      expect(result.ok).toBe(true);
+      expect(result.data).toEqual([]);
     });
 
-    it('throws when Google Places library is unavailable', async () => {
+    it('returns err when Google Places library is unavailable', async () => {
       const originalPlaces = (window as any).google.maps.places;
       (window as any).google.maps.places = undefined;
+      vi.mocked(loadGoogleMapsScript).mockResolvedValueOnce({ ok: true, data: undefined });
 
-      await expect(fetchPlaceAutocomplete('123 Main', mockApiKey)).rejects.toThrow(
-        'Google Maps Places library not available'
-      );
+      const result = await fetchPlaceAutocomplete('123 Main', mockApiKey);
+      expect(result.ok).toBe(false);
+      expect(result.error.message).toContain('Places library not available');
 
       (window as any).google.maps.places = originalPlaces;
     });
@@ -315,7 +328,7 @@ describe('Google Places API Utilities', () => {
       const mockedIsLoaded = vi.mocked(isGoogleMapsLoaded);
 
       mockedIsLoaded.mockReturnValueOnce(false);
-      mockedLoadScript.mockResolvedValueOnce();
+      mockedLoadScript.mockResolvedValueOnce({ ok: true, data: undefined });
 
       (window as any).google.maps.places.AutocompleteSuggestion = mockAutocompleteSuggestion as any;
       mockAutocompleteSuggestion.fetchAutocompleteSuggestions.mockResolvedValue({ suggestions: [] });
@@ -351,7 +364,9 @@ describe('Google Places API Utilities', () => {
       const [result1, result2] = await Promise.all([promise1, promise2]);
 
       expect(mockAutocompleteService.getPlacePredictions).toHaveBeenCalledTimes(1);
-      expect(result1).toEqual(result2);
+      expect(result1.ok).toBe(true);
+      expect(result2.ok).toBe(true);
+      expect(result1.data).toEqual(result2.data);
 
       vi.useRealTimers();
     });
@@ -384,18 +399,23 @@ describe('Google Places API Utilities', () => {
 
       const result = await fetchPlaceDetails('ChIJ123', mockApiKey);
 
-      expect(result.place_id).toBe('ChIJ123');
-      expect(result.formatted_address).toBe('123 Main St, Melbourne VIC 3000, Australia');
-      expect(result.geometry?.location?.lat()).toBe(-37.8136);
+      expect(result.ok).toBe(true);
+      expect(result.data.place_id).toBe('ChIJ123');
+      expect(result.data.formatted_address).toBe('123 Main St, Melbourne VIC 3000, Australia');
+      expect(result.data.geometry?.location?.lat()).toBe(-37.8136);
       expect(mockPlacesService.getDetails).toHaveBeenCalled();
     });
 
-    it('throws error when place_id is missing', async () => {
-      await expect(fetchPlaceDetails('', mockApiKey)).rejects.toThrow('Place ID is required');
+    it('returns err when place_id is missing', async () => {
+      const result = await fetchPlaceDetails('', mockApiKey);
+      expect(result.ok).toBe(false);
+      expect(result.error.message).toContain('Place ID is required');
     });
 
-    it('throws error when API key is missing', async () => {
-      await expect(fetchPlaceDetails('ChIJ123', '')).rejects.toThrow('API key is required');
+    it('returns err when API key is missing', async () => {
+      const result = await fetchPlaceDetails('ChIJ123', '');
+      expect(result.ok).toBe(false);
+      expect(result.error.message).toContain('API key is required');
     });
 
     it('handles NOT_FOUND status', { timeout: 5000 }, async () => {
@@ -403,17 +423,19 @@ describe('Google Places API Utilities', () => {
         callback(null, 'NOT_FOUND');
       });
 
-      await expect(fetchPlaceDetails('invalid', mockApiKey)).rejects.toThrow('Place not found');
+      const result = await fetchPlaceDetails('invalid', mockApiKey);
+      expect(result.ok).toBe(false);
+      expect(result.error.message).toContain('Place not found');
     });
 
-    it('rejects when Places Service returns an error status', { timeout: 5000 }, async () => {
+    it('returns err when Places Service returns an error status', { timeout: 5000 }, async () => {
       mockPlacesService.getDetails.mockImplementation((request, callback) => {
         callback(null, 'OVER_QUERY_LIMIT');
       });
 
-      await expect(fetchPlaceDetails('ChIJ123', mockApiKey)).rejects.toThrow(
-        'Failed to fetch place details: OVER_QUERY_LIMIT'
-      );
+      const result = await fetchPlaceDetails('ChIJ123', mockApiKey);
+      expect(result.ok).toBe(false);
+      expect(result.error.message).toContain('OVER_QUERY_LIMIT');
     });
   });
 
@@ -550,33 +572,33 @@ describe('Google Places API Utilities', () => {
 
       const result = await getAddressByPlaceId('ChIJ123', mockApiKey);
 
-      expect(result).not.toBeNull();
-      expect(result?.place_id).toBe('ChIJ123');
-      expect(result?.full_address).toBe('123 Main St, Melbourne VIC 3000, Australia');
+      expect(result.ok).toBe(true);
+      expect(result.data).not.toBeNull();
+      expect(result.data?.place_id).toBe('ChIJ123');
+      expect(result.data?.full_address).toBe('123 Main St, Melbourne VIC 3000, Australia');
     });
 
-    it('returns null on error', { timeout: 5000 }, async () => {
+    it('returns err on error', { timeout: 5000 }, async () => {
       mockPlacesService.getDetails.mockImplementation((request, callback) => {
         callback(null, 'NOT_FOUND');
       });
 
       const result = await getAddressByPlaceId('ChIJ123', mockApiKey);
-      expect(result).toBeNull();
+      expect(result.ok).toBe(false);
+      expect(result.error.message).toContain('Place not found');
     });
 
-    it('returns null when fetchPlaceDetails throws', { timeout: 10000 }, async () => {
-      // Clear any cached requests first
+    it('returns err when fetchPlaceDetails returns err', { timeout: 10000 }, async () => {
       clearInFlightRequests();
       
-      // Mock the PlacesService to throw an error
       mockPlacesService.getDetails.mockImplementation((request, callback) => {
-        // Simulate an error by calling callback with error status
         callback(null, 'INVALID_REQUEST');
       });
 
       const result = await googlePlacesUtils.getAddressByPlaceId('ChIJ123', mockApiKey);
 
-      expect(result).toBeNull();
+      expect(result.ok).toBe(false);
+      expect(result.error.message).toContain('INVALID_REQUEST');
     });
   });
 });

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

@@ -16,6 +16,7 @@
  */
 
 import { getOrCreateRequest } from '../request-deduplication';
+import { ok, err, type ApiResult, type ApiError } from '../../types/api-result';
 import { createLogger } from '../core/logger';
 import { loadGoogleMapsScript, isGoogleMapsLoaded } from './loadGoogleMapsScript';
 import type {
@@ -26,6 +27,14 @@ import type {
 
 const log = createLogger('google-places');
 
+function toApiError(error: unknown): ApiError {
+  const message = error instanceof Error ? error.message : 'Unknown error';
+  const code = error instanceof Error && (error as Error & { code?: string }).code
+    ? (error as Error & { code: string }).code
+    : 'GOOGLE_PLACES_ERROR';
+  return { code, message };
+}
+
 // Google Maps types are defined in loadGoogleMapsScript.ts
 
 /**
@@ -34,33 +43,36 @@ const log = createLogger('google-places');
  * @param query - Search query string
  * @param apiKey - Google Places API key
  * @param options - Optional autocomplete options
- * @returns Promise resolving to array of predictions
+ * @returns Promise resolving to ApiResult with array of predictions
  *
  * @example
  * ```ts
- * const predictions = await fetchPlaceAutocomplete(
+ * const result = await fetchPlaceAutocomplete(
  *   '123 Main St',
  *   'your-api-key',
  *   { components: 'country:au' }
  * );
+ * if (result.ok) console.log(result.data);
  * ```
  */
 export async function fetchPlaceAutocomplete(
   query: string,
   apiKey: string,
   options?: AutocompleteOptions
-): Promise<GooglePlaceAutocompletePrediction[]> {
+): Promise<ApiResult<GooglePlaceAutocompletePrediction[]>> {
   if (!query.trim()) {
-    return [];
+    return ok([]);
   }
 
   if (!apiKey) {
-    throw new Error('Google Places API key is required');
+    return err({ code: 'VALIDATION_ERROR', message: 'Google Places API key is required' });
   }
 
-  // Ensure Google Maps script is loaded
   if (!isGoogleMapsLoaded()) {
-    await loadGoogleMapsScript(apiKey, 'places');
+    const loadResult = await loadGoogleMapsScript(apiKey, 'places');
+    if (!loadResult.ok) {
+      return err(loadResult.error);
+    }
   }
 
   const requestKey = `google-places-autocomplete:${query}:${JSON.stringify(options || {})}`;
@@ -125,11 +137,11 @@ export async function fetchPlaceAutocomplete(
         }
 
         // Call new API
-        return new Promise<GooglePlaceAutocompletePrediction[]>((resolve, reject) => {
+        return new Promise<ApiResult<GooglePlaceAutocompletePrediction[]>>((resolve) => {
           window.google!.maps.places.AutocompleteSuggestion.fetchAutocompleteSuggestions(request)
             .then((response) => {
               if (response.suggestions && response.suggestions.length > 0) {
-                const result: GooglePlaceAutocompletePrediction[] = response.suggestions
+                const data: GooglePlaceAutocompletePrediction[] = response.suggestions
                   .filter(s => s.placePrediction)
                   .map((s) => ({
                     description: s.placePrediction!.text.text,
@@ -139,16 +151,16 @@ export async function fetchPlaceAutocomplete(
                       secondary_text: s.placePrediction!.structuredFormat?.secondaryText?.text || '',
                     },
                   }));
-                log.debug(`Received ${result.length} predictions (new API)`);
-                resolve(result);
+                log.debug(`Received ${data.length} predictions (new API)`);
+                resolve(ok(data));
               } else {
                 log.debug('No results found (new API)');
-                resolve([]);
+                resolve(ok([]));
               }
             })
             .catch((error) => {
               log.error('Autocomplete fetch failed (new API):', error);
-              reject(new Error(`Failed to fetch autocomplete predictions: ${error.message || 'Unknown error'}`));
+              resolve(err({ code: 'AUTOCOMPLETE_ERROR', message: error.message || 'Unknown error' }));
             });
         });
       }
@@ -206,12 +218,11 @@ export async function fetchPlaceAutocomplete(
       }
 
       // Call AutocompleteService
-      return new Promise<GooglePlaceAutocompletePrediction[]>((resolve, reject) => {
+      return new Promise<ApiResult<GooglePlaceAutocompletePrediction[]>>((resolve) => {
         autocompleteService.getPlacePredictions(request, (predictions, status) => {
           if (status === 'OK' && predictions) {
             log.debug(`Received ${predictions.length} predictions`);
-            // Convert to our format
-            const result: GooglePlaceAutocompletePrediction[] = predictions.map((pred) => ({
+            const data: GooglePlaceAutocompletePrediction[] = predictions.map((pred) => ({
               description: pred.description,
               place_id: pred.place_id,
               structured_formatting: {
@@ -219,44 +230,26 @@ export async function fetchPlaceAutocomplete(
                 secondary_text: pred.structured_formatting.secondary_text,
               },
             }));
-            resolve(result);
+            resolve(ok(data));
           } else if (status === 'ZERO_RESULTS') {
             log.debug('No results found');
-            resolve([]);
+            resolve(ok([]));
           } else {
             const errorMsg = `Google Places API error: ${status}`;
             log.error('Autocomplete fetch failed:', errorMsg);
-            reject(new Error(errorMsg));
+            resolve(err({ code: 'AUTOCOMPLETE_ERROR', message: errorMsg }));
           }
         });
       });
-    } catch (error) {
-      if (error instanceof Error) {
-        log.error('Autocomplete fetch failed:', error.message);
-        throw error;
-      }
-      log.error('Autocomplete fetch failed: Unknown error');
-      throw new Error('Failed to fetch autocomplete predictions');
+    } catch (e) {
+      log.error('Autocomplete fetch failed:', e);
+      return err(toApiError(e));
     }
   });
 }
 
-/**
- * Fetch place details from Google Places API
- *
- * @param placeId - Google Place ID
- * @param apiKey - Google Places API key
- * @returns Promise resolving to place details
- *
- * @example
- * ```ts
- * const place = await fetchPlaceDetails('ChIJ...', 'your-api-key');
- * ```
- */
-export async function fetchPlaceDetails(
-  placeId: string,
-  apiKey: string
-): Promise<{
+/** Place details shape from Google Places API */
+type PlaceDetails = {
   place_id: string;
   formatted_address?: string;
   address_components?: Array<{
@@ -270,18 +263,29 @@ export async function fetchPlaceDetails(
       lng: () => number;
     };
   };
-}> {
+};
+
+/**
+ * Fetch place details from Google Places API.
+ * @returns Promise resolving to ApiResult with place details
+ */
+export async function fetchPlaceDetails(
+  placeId: string,
+  apiKey: string
+): Promise<ApiResult<PlaceDetails>> {
   if (!placeId) {
-    throw new Error('Place ID is required');
+    return err({ code: 'VALIDATION_ERROR', message: 'Place ID is required' });
   }
 
   if (!apiKey) {
-    throw new Error('Google Places API key is required');
+    return err({ code: 'VALIDATION_ERROR', message: 'Google Places API key is required' });
   }
 
-  // Ensure Google Maps script is loaded
   if (!isGoogleMapsLoaded()) {
-    await loadGoogleMapsScript(apiKey, 'places');
+    const loadResult = await loadGoogleMapsScript(apiKey, 'places');
+    if (!loadResult.ok) {
+      return err(loadResult.error);
+    }
   }
 
   const requestKey = `google-places-details:${placeId}`;
@@ -291,29 +295,13 @@ export async function fetchPlaceDetails(
       log.debug(`Fetching place details for place_id: ${placeId}`);
 
       if (!window.google?.maps?.places) {
-        throw new Error('Google Maps Places library not available');
+        return err({ code: 'PLACES_UNAVAILABLE', message: 'Google Maps Places library not available' });
       }
 
-      // Create a dummy element for PlacesService (it needs an element but we don't use it)
       const dummyElement = document.createElement('div');
       const placesService = new window.google.maps.places.PlacesService(dummyElement);
 
-      // Call getDetails
-      return new Promise<{
-        place_id: string;
-        formatted_address?: string;
-        address_components?: Array<{
-          long_name: string;
-          short_name: string;
-          types: string[];
-        }>;
-        geometry?: {
-          location?: {
-            lat: () => number;
-            lng: () => number;
-          };
-        };
-      }>((resolve, reject) => {
+      return new Promise<ApiResult<PlaceDetails>>((resolve) => {
         placesService.getDetails(
           {
             placeId: placeId,
@@ -322,39 +310,21 @@ export async function fetchPlaceDetails(
           (place, status) => {
             if (status === 'OK' && place) {
               log.debug('Place details fetched successfully');
-              resolve(place as {
-                place_id: string;
-                formatted_address?: string;
-                address_components?: Array<{
-                  long_name: string;
-                  short_name: string;
-                  types: string[];
-                }>;
-                geometry?: {
-                  location?: {
-                    lat: () => number;
-                    lng: () => number;
-                  };
-                };
-              });
+              resolve(ok(place as PlaceDetails));
             } else if (status === 'NOT_FOUND') {
               log.error('Place not found:', placeId);
-              reject(new Error('Place not found'));
+              resolve(err({ code: 'NOT_FOUND', message: 'Place not found' }));
             } else {
               const errorMsg = `Failed to fetch place details: ${status}`;
               log.error('Place details fetch failed:', errorMsg);
-              reject(new Error(errorMsg));
+              resolve(err({ code: 'PLACE_DETAILS_ERROR', message: errorMsg }));
             }
           }
         );
       });
-    } catch (error) {
-      if (error instanceof Error) {
-        log.error('Place details fetch failed:', error.message);
-        throw error;
-      }
-      log.error('Place details fetch failed: Unknown error');
-      throw new Error('Failed to fetch place details');
+    } catch (e) {
+      log.error('Place details fetch failed:', e);
+      return err(toApiError(e));
     }
   });
 }
@@ -465,24 +435,22 @@ export function createAddressFromPlaceResult(
  *
  * @param placeId - Google Place ID
  * @param apiKey - Google Places API key
- * @returns Promise resolving to parsed address
+ * @returns Promise resolving to ApiResult with parsed address
  *
  * @example
  * ```ts
- * const address = await getAddressByPlaceId('ChIJ...', 'your-api-key');
- * // Returns: { place_id: 'ChIJ...', full_address: '...', ... }
+ * const result = await getAddressByPlaceId('ChIJ...', 'your-api-key');
+ * if (result.ok) console.log(result.data);
  * ```
  */
 export async function getAddressByPlaceId(
   placeId: string,
   apiKey: string
-): Promise<ParsedAddress | null> {
-  try {
-    const place = await fetchPlaceDetails(placeId, apiKey);
-    return createAddressFromPlaceResult(place);
-  } catch (error) {
-    log.error('Failed to get address by place_id:', error);
-    return null;
+): Promise<ApiResult<ParsedAddress | null>> {
+  const placeResult = await fetchPlaceDetails(placeId, apiKey);
+  if (!placeResult.ok) {
+    return placeResult;
   }
+  return ok(createAddressFromPlaceResult(placeResult.data));
 }