@jmruthers/pace-core 0.5.183 → 0.5.185

package/src/utils/formatting/formatting.ts

@@ -2,6 +2,9 @@
  * Utility functions for formatting data in the application
  */
 
+import { parseISO, isValid } from 'date-fns';
+import { formatInTimeZone, getTimezoneAbbreviation } from '../timezone';
+
 /**
  * Format a date as a readable string in "dd mmm yyyy" format (e.g., "15 Jun 2024")
  */
@@ -168,3 +171,179 @@ export function formatFileSize(bytes: number): string {
   
   return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + ' ' + sizes[i];
 }
+
+/**
+ * Options for formatting date/time with timezone
+ */
+export interface DateTimeFormatOptions {
+  /**
+   * Include timezone abbreviation (default: true)
+   */
+  includeTimezone?: boolean;
+  /**
+   * Custom format string (default: 'MMM dd, yyyy HH:mm')
+   */
+  format?: string;
+}
+
+/**
+ * Format a UTC date for display in a specific timezone
+ *
+ * @param utcDate - UTC date (ISO string, Date object, or undefined)
+ * @param timezone - IANA timezone string (e.g., 'America/New_York')
+ * @param options - Formatting options
+ * @returns Formatted date string or empty string if invalid
+ *
+ * @example
+ * ```ts
+ * formatDateTimeForDisplay('2024-01-15T10:00:00Z', 'America/New_York');
+ * // "Jan 15, 2024 05:00 (EST)"
+ *
+ * formatDateTimeForDisplay('2024-01-15T10:00:00Z', 'America/New_York', { includeTimezone: false });
+ * // "Jan 15, 2024 05:00"
+ * ```
+ */
+export function formatDateTimeForDisplay(
+  utcDate: string | Date | undefined,
+  timezone: string | undefined,
+  options: DateTimeFormatOptions = {}
+): string {
+  if (!utcDate) {
+    return '';
+  }
+
+  if (!timezone) {
+    return '';
+  }
+
+  try {
+    const { includeTimezone = true, format: formatStr = 'MMM dd, yyyy HH:mm' } = options;
+
+    let dateObj: Date;
+    if (typeof utcDate === 'string') {
+      dateObj = parseISO(utcDate);
+    } else {
+      dateObj = utcDate;
+    }
+
+    if (!isValid(dateObj)) {
+      return '';
+    }
+
+    const formatted = formatInTimeZone(dateObj, timezone, formatStr);
+
+    if (includeTimezone) {
+      const tzAbbr = getTimezoneAbbreviation(dateObj, timezone);
+      return `${formatted} (${tzAbbr})`;
+    }
+
+    return formatted;
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * Format a UTC date for display (date only, no time)
+ *
+ * @param utcDate - UTC date (ISO string, Date object, or undefined)
+ * @returns Formatted date string or empty string if invalid
+ *
+ * @example
+ * ```ts
+ * formatDateOnlyForDisplay('2024-01-15T10:00:00Z');
+ * // "15 January 2024"
+ * ```
+ */
+export function formatDateOnlyForDisplay(utcDate: string | Date | undefined): string {
+  if (!utcDate) {
+    return '';
+  }
+
+  try {
+    let dateObj: Date;
+    if (typeof utcDate === 'string') {
+      dateObj = parseISO(utcDate);
+    } else {
+      dateObj = utcDate;
+    }
+
+    if (!isValid(dateObj)) {
+      return '';
+    }
+
+    // Use 'en-GB' locale for "dd mmm yyyy" format
+    return dateObj.toLocaleDateString('en-GB', {
+      year: 'numeric',
+      month: 'long',
+      day: 'numeric'
+    });
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * Format a UTC date for table display (compact format with timezone)
+ *
+ * @param utcDate - UTC date (ISO string, Date object, or undefined)
+ * @param timezone - IANA timezone string
+ * @returns Formatted date string or empty string if invalid
+ *
+ * @example
+ * ```ts
+ * formatDateTimeForTable('2024-01-15T10:00:00Z', 'America/New_York');
+ * // "Jan 15, 2024 05:00 (EST)"
+ * ```
+ */
+export function formatDateTimeForTable(
+  utcDate: string | Date | undefined,
+  timezone: string | undefined
+): string {
+  return formatDateTimeForDisplay(utcDate, timezone, {
+    includeTimezone: true,
+    format: 'MMM dd, yyyy HH:mm'
+  });
+}
+
+/**
+ * Format a UTC date for map display (compact format)
+ *
+ * @param utcDate - UTC date (ISO string, Date object, or undefined)
+ * @param timezone - IANA timezone string
+ * @returns Formatted date string or empty string if invalid
+ *
+ * @example
+ * ```ts
+ * formatDateTimeForMap('2024-01-15T10:00:00Z', 'America/New_York');
+ * // "Jan 15, 05:00 EST"
+ * ```
+ */
+export function formatDateTimeForMap(
+  utcDate: string | Date | undefined,
+  timezone: string | undefined
+): string {
+  if (!utcDate || !timezone) {
+    return '';
+  }
+
+  try {
+    let dateObj: Date;
+    if (typeof utcDate === 'string') {
+      dateObj = parseISO(utcDate);
+    } else {
+      dateObj = utcDate;
+    }
+
+    if (!isValid(dateObj)) {
+      return '';
+    }
+
+    const formatted = formatInTimeZone(dateObj, timezone, 'MMM dd, HH:mm');
+    const tzAbbr = getTimezoneAbbreviation(dateObj, timezone);
+
+    return `${formatted} ${tzAbbr}`;
+  } catch {
+    return '';
+  }
+}

package/src/utils/index.ts

@@ -120,8 +120,13 @@ export {
   formatNumber,
   formatPercent,
   formatCompactNumber,
-  formatFileSize
+  formatFileSize,
+  formatDateTimeForDisplay,
+  formatDateOnlyForDisplay,
+  formatDateTimeForTable,
+  formatDateTimeForMap
 } from './formatting/formatting';
+export type { DateTimeFormatOptions } from './formatting/formatting';
 
 // Organisation context utilities
 export { 
@@ -130,3 +135,24 @@ export {
   getOrganisationContext, 
   isOrganisationContextAvailable 
 } from './context/organisationContext';
+
+// Timezone utilities
+export {
+  formatInTimeZone,
+  getTimezoneAbbreviation,
+  formatTimeInTimeZone,
+  getUserTimeZone,
+  toZonedTime,
+  fromZonedTime,
+  roundToNearestMinutes,
+  getTimeZoneDifference
+} from './timezone';
+
+// Location utilities
+export {
+  formatCoordinates,
+  hasValidCoordinates,
+  areCoordinatesEqual,
+  getGoogleMapsUrl
+} from './location';
+export type { Coordinates } from './location';

package/src/utils/location/index.ts

@@ -0,0 +1,16 @@
+/**
+ * @file Location Utilities Exports
+ * @package @jmruthers/pace-core
+ * @module Utils/Location
+ * @since 0.1.0
+ */
+
+export {
+  formatCoordinates,
+  hasValidCoordinates,
+  areCoordinatesEqual,
+  getGoogleMapsUrl
+} from './location';
+
+export type { Coordinates } from './location';
+

package/src/utils/location/location.test.ts

@@ -0,0 +1,286 @@
+/**
+ * @file Location Utilities Tests
+ * @package @jmruthers/pace-core
+ * @module Utils/Location/__tests__
+ * @since 0.1.0
+ *
+ * Comprehensive tests for location utility functions.
+ * Tests cover all major functionality, edge cases, and error handling.
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  formatCoordinates,
+  hasValidCoordinates,
+  areCoordinatesEqual,
+  getGoogleMapsUrl,
+  type Coordinates
+} from './location';
+
+describe('Location Utilities', () => {
+  describe('formatCoordinates', () => {
+    it('formats valid coordinates with 6 decimal places', () => {
+      const coords: Coordinates = { lat: -37.8136, lng: 144.9631 };
+      const result = formatCoordinates(coords);
+      expect(result).toBe('-37.813600, 144.963100');
+    });
+
+    it('formats coordinates with fewer decimal places', () => {
+      const coords: Coordinates = { lat: 0, lng: 0 };
+      const result = formatCoordinates(coords);
+      expect(result).toBe('0.000000, 0.000000');
+    });
+
+    it('formats coordinates with many decimal places', () => {
+      const coords: Coordinates = { lat: -37.813612345, lng: 144.963198765 };
+      const result = formatCoordinates(coords);
+      expect(result).toBe('-37.813612, 144.963199');
+    });
+
+    it('returns "N/A" for undefined', () => {
+      const result = formatCoordinates(undefined);
+      expect(result).toBe('N/A');
+    });
+
+    it('returns "N/A" for null', () => {
+      // @ts-expect-error - Testing null input
+      const result = formatCoordinates(null);
+      expect(result).toBe('N/A');
+    });
+
+    it('returns "N/A" for missing lat', () => {
+      // @ts-expect-error - Testing invalid input
+      const result = formatCoordinates({ lng: 144.9631 });
+      expect(result).toBe('N/A');
+    });
+
+    it('returns "N/A" for missing lng', () => {
+      // @ts-expect-error - Testing invalid input
+      const result = formatCoordinates({ lat: -37.8136 });
+      expect(result).toBe('N/A');
+    });
+
+    it('returns "N/A" for NaN values', () => {
+      const coords: Coordinates = { lat: NaN, lng: 144.9631 };
+      const result = formatCoordinates(coords);
+      expect(result).toBe('N/A');
+    });
+
+    it('returns "N/A" for Infinity values', () => {
+      const coords: Coordinates = { lat: Infinity, lng: 144.9631 };
+      const result = formatCoordinates(coords);
+      expect(result).toBe('N/A');
+    });
+
+    it('returns "N/A" for non-number lat', () => {
+      // @ts-expect-error - Testing invalid input
+      const result = formatCoordinates({ lat: 'invalid', lng: 144.9631 });
+      expect(result).toBe('N/A');
+    });
+
+    it('returns "N/A" for non-number lng', () => {
+      // @ts-expect-error - Testing invalid input
+      const result = formatCoordinates({ lat: -37.8136, lng: 'invalid' });
+      expect(result).toBe('N/A');
+    });
+  });
+
+  describe('hasValidCoordinates', () => {
+    it('returns true for valid coordinates', () => {
+      const coords: Coordinates = { lat: -37.8136, lng: 144.9631 };
+      expect(hasValidCoordinates(coords)).toBe(true);
+    });
+
+    it('returns true for coordinates at boundaries', () => {
+      expect(hasValidCoordinates({ lat: -90, lng: -180 })).toBe(true);
+      expect(hasValidCoordinates({ lat: 90, lng: 180 })).toBe(true);
+      expect(hasValidCoordinates({ lat: 0, lng: 0 })).toBe(true);
+    });
+
+    it('returns false for lat out of range (too low)', () => {
+      expect(hasValidCoordinates({ lat: -91, lng: 0 })).toBe(false);
+    });
+
+    it('returns false for lat out of range (too high)', () => {
+      expect(hasValidCoordinates({ lat: 91, lng: 0 })).toBe(false);
+    });
+
+    it('returns false for lng out of range (too low)', () => {
+      expect(hasValidCoordinates({ lat: 0, lng: -181 })).toBe(false);
+    });
+
+    it('returns false for lng out of range (too high)', () => {
+      expect(hasValidCoordinates({ lat: 0, lng: 181 })).toBe(false);
+    });
+
+    it('returns false for undefined', () => {
+      expect(hasValidCoordinates(undefined)).toBe(false);
+    });
+
+    it('returns false for null', () => {
+      // @ts-expect-error - Testing null input
+      expect(hasValidCoordinates(null)).toBe(false);
+    });
+
+    it('returns false for missing lat', () => {
+      expect(hasValidCoordinates({ lng: 144.9631 })).toBe(false);
+    });
+
+    it('returns false for missing lng', () => {
+      expect(hasValidCoordinates({ lat: -37.8136 })).toBe(false);
+    });
+
+    it('returns false for NaN lat', () => {
+      expect(hasValidCoordinates({ lat: NaN, lng: 144.9631 })).toBe(false);
+    });
+
+    it('returns false for NaN lng', () => {
+      expect(hasValidCoordinates({ lat: -37.8136, lng: NaN })).toBe(false);
+    });
+
+    it('returns false for Infinity lat', () => {
+      expect(hasValidCoordinates({ lat: Infinity, lng: 144.9631 })).toBe(false);
+    });
+
+    it('returns false for Infinity lng', () => {
+      expect(hasValidCoordinates({ lat: -37.8136, lng: Infinity })).toBe(false);
+    });
+
+    it('returns false for non-number lat', () => {
+      // @ts-expect-error - Testing invalid input
+      expect(hasValidCoordinates({ lat: 'invalid', lng: 144.9631 })).toBe(false);
+    });
+
+    it('returns false for non-number lng', () => {
+      // @ts-expect-error - Testing invalid input
+      expect(hasValidCoordinates({ lat: -37.8136, lng: 'invalid' })).toBe(false);
+    });
+  });
+
+  describe('areCoordinatesEqual', () => {
+    it('returns true for identical coordinates', () => {
+      const coords1: Coordinates = { lat: -37.8136, lng: 144.9631 };
+      const coords2: Coordinates = { lat: -37.8136, lng: 144.9631 };
+      expect(areCoordinatesEqual(coords1, coords2)).toBe(true);
+    });
+
+    it('returns true for coordinates within default tolerance', () => {
+      const coords1: Coordinates = { lat: -37.8136, lng: 144.9631 };
+      const coords2: Coordinates = { lat: -37.8137, lng: 144.9632 };
+      expect(areCoordinatesEqual(coords1, coords2)).toBe(true);
+    });
+
+    it('returns false for coordinates outside default tolerance', () => {
+      const coords1: Coordinates = { lat: -37.8136, lng: 144.9631 };
+      const coords2: Coordinates = { lat: -37.8150, lng: 144.9650 };
+      expect(areCoordinatesEqual(coords1, coords2)).toBe(false);
+    });
+
+    it('returns true for coordinates within custom tolerance', () => {
+      const coords1: Coordinates = { lat: -37.8136, lng: 144.9631 };
+      const coords2: Coordinates = { lat: -37.8137, lng: 144.9632 };
+      expect(areCoordinatesEqual(coords1, coords2, 0.001)).toBe(true);
+    });
+
+    it('returns false for coordinates outside custom tolerance', () => {
+      const coords1: Coordinates = { lat: -37.8136, lng: 144.9631 };
+      const coords2: Coordinates = { lat: -37.8137, lng: 144.9632 };
+      expect(areCoordinatesEqual(coords1, coords2, 0.00001)).toBe(false);
+    });
+
+    it('returns true when both are null', () => {
+      expect(areCoordinatesEqual(null, null)).toBe(true);
+    });
+
+    it('returns true when both are undefined', () => {
+      expect(areCoordinatesEqual(undefined, undefined)).toBe(true);
+    });
+
+    it('returns false when one is null and other is valid', () => {
+      const coords: Coordinates = { lat: -37.8136, lng: 144.9631 };
+      expect(areCoordinatesEqual(null, coords)).toBe(false);
+      expect(areCoordinatesEqual(coords, null)).toBe(false);
+    });
+
+    it('returns false when one is undefined and other is valid', () => {
+      const coords: Coordinates = { lat: -37.8136, lng: 144.9631 };
+      expect(areCoordinatesEqual(undefined, coords)).toBe(false);
+      expect(areCoordinatesEqual(coords, undefined)).toBe(false);
+    });
+
+    it('returns false for invalid coordinates', () => {
+      const coords1: Coordinates = { lat: -37.8136, lng: 144.9631 };
+      // @ts-expect-error - Testing invalid input
+      const coords2 = { lat: 91, lng: 0 };
+      expect(areCoordinatesEqual(coords1, coords2)).toBe(false);
+    });
+
+    it('handles edge case: exactly at tolerance boundary', () => {
+      const coords1: Coordinates = { lat: -37.8136, lng: 144.9631 };
+      const coords2: Coordinates = { lat: -37.8136 + 0.0001, lng: 144.9631 };
+      expect(areCoordinatesEqual(coords1, coords2, 0.0001)).toBe(true);
+    });
+  });
+
+  describe('getGoogleMapsUrl', () => {
+    it('generates URL for valid coordinates', () => {
+      const coords: Coordinates = { lat: -37.8136, lng: 144.9631 };
+      const result = getGoogleMapsUrl(coords);
+      expect(result).toBe('https://www.google.com/maps/search/?api=1&query=-37.8136,144.9631');
+    });
+
+    it('generates URL with negative coordinates', () => {
+      const coords: Coordinates = { lat: -90, lng: -180 };
+      const result = getGoogleMapsUrl(coords);
+      expect(result).toBe('https://www.google.com/maps/search/?api=1&query=-90,-180');
+    });
+
+    it('generates URL with positive coordinates', () => {
+      const coords: Coordinates = { lat: 90, lng: 180 };
+      const result = getGoogleMapsUrl(coords);
+      expect(result).toBe('https://www.google.com/maps/search/?api=1&query=90,180');
+    });
+
+    it('returns empty string for undefined', () => {
+      const result = getGoogleMapsUrl(undefined);
+      expect(result).toBe('');
+    });
+
+    it('returns empty string for null', () => {
+      // @ts-expect-error - Testing null input
+      const result = getGoogleMapsUrl(null);
+      expect(result).toBe('');
+    });
+
+    it('returns empty string for invalid coordinates', () => {
+      // @ts-expect-error - Testing invalid input
+      const result = getGoogleMapsUrl({ lat: 91, lng: 0 });
+      expect(result).toBe('');
+    });
+
+    it('returns empty string for missing lat', () => {
+      // @ts-expect-error - Testing invalid input
+      const result = getGoogleMapsUrl({ lng: 144.9631 });
+      expect(result).toBe('');
+    });
+
+    it('returns empty string for missing lng', () => {
+      // @ts-expect-error - Testing invalid input
+      const result = getGoogleMapsUrl({ lat: -37.8136 });
+      expect(result).toBe('');
+    });
+
+    it('returns empty string for NaN values', () => {
+      const coords: Coordinates = { lat: NaN, lng: 144.9631 };
+      const result = getGoogleMapsUrl(coords);
+      expect(result).toBe('');
+    });
+
+    it('returns empty string for Infinity values', () => {
+      const coords: Coordinates = { lat: Infinity, lng: 144.9631 };
+      const result = getGoogleMapsUrl(coords);
+      expect(result).toBe('');
+    });
+  });
+});
+

package/src/utils/location/location.ts

@@ -0,0 +1,175 @@
+/**
+ * @file Location Utilities
+ * @package @jmruthers/pace-core
+ * @module Utils/Location
+ * @since 0.1.0
+ *
+ * Utility functions for working with geographic coordinates.
+ * Provides functions for formatting, validating, comparing, and generating URLs for coordinates.
+ *
+ * Features:
+ * - Format coordinates for display
+ * - Validate coordinate objects
+ * - Compare coordinates with tolerance
+ * - Generate Google Maps URLs
+ *
+ * @example
+ * ```ts
+ * import { formatCoordinates, hasValidCoordinates, areCoordinatesEqual, getGoogleMapsUrl } from '@jmruthers/pace-core/utils/location';
+ *
+ * const coords = { lat: -37.8136, lng: 144.9631 };
+ *
+ * // Format for display
+ * formatCoordinates(coords); // "-37.813600, 144.963100"
+ *
+ * // Validate
+ * hasValidCoordinates(coords); // true
+ *
+ * // Compare
+ * areCoordinatesEqual(coords, { lat: -37.8137, lng: 144.9632 }); // true (within tolerance)
+ *
+ * // Generate Google Maps URL
+ * getGoogleMapsUrl(coords); // "https://www.google.com/maps/search/?api=1&query=-37.8136,144.9631"
+ * ```
+ */
+
+/**
+ * Coordinate interface for latitude and longitude
+ */
+export interface Coordinates {
+  lat: number;
+  lng: number;
+}
+
+/**
+ * Format coordinates as a string with 6 decimal places
+ *
+ * @param coords - Coordinate object with lat and lng
+ * @returns Formatted string "lat, lng" or "N/A" if invalid
+ *
+ * @example
+ * ```ts
+ * formatCoordinates({ lat: -37.8136, lng: 144.9631 });
+ * // "-37.813600, 144.963100"
+ *
+ * formatCoordinates(undefined);
+ * // "N/A"
+ * ```
+ */
+export function formatCoordinates(coords?: Coordinates): string {
+  if (!coords || typeof coords.lat !== 'number' || typeof coords.lng !== 'number') {
+    return 'N/A';
+  }
+
+  if (!isFinite(coords.lat) || !isFinite(coords.lng)) {
+    return 'N/A';
+  }
+
+  return `${coords.lat.toFixed(6)}, ${coords.lng.toFixed(6)}`;
+}
+
+/**
+ * Check if coordinates are valid
+ *
+ * @param coords - Coordinate object to validate
+ * @returns true if coordinates are valid, false otherwise
+ *
+ * @example
+ * ```ts
+ * hasValidCoordinates({ lat: -37.8136, lng: 144.9631 }); // true
+ * hasValidCoordinates({ lat: 91, lng: 0 }); // false (lat out of range)
+ * hasValidCoordinates(undefined); // false
+ * ```
+ */
+export function hasValidCoordinates(coords?: { lat?: number; lng?: number }): boolean {
+  if (!coords) {
+    return false;
+  }
+
+  const { lat, lng } = coords;
+
+  if (typeof lat !== 'number' || typeof lng !== 'number') {
+    return false;
+  }
+
+  if (!isFinite(lat) || !isFinite(lng)) {
+    return false;
+  }
+
+  // Latitude must be between -90 and 90
+  if (lat < -90 || lat > 90) {
+    return false;
+  }
+
+  // Longitude must be between -180 and 180
+  if (lng < -180 || lng > 180) {
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * Check if two coordinates are equal within a tolerance
+ *
+ * @param coords1 - First coordinate object
+ * @param coords2 - Second coordinate object
+ * @param tolerance - Tolerance in degrees (default: 0.0001° ≈ 11 meters)
+ * @returns true if coordinates are within tolerance, false otherwise
+ *
+ * @example
+ * ```ts
+ * const coords1 = { lat: -37.8136, lng: 144.9631 };
+ * const coords2 = { lat: -37.8137, lng: 144.9632 };
+ * areCoordinatesEqual(coords1, coords2); // true (within default tolerance)
+ * areCoordinatesEqual(coords1, coords2, 0.00001); // false (stricter tolerance)
+ * ```
+ */
+export function areCoordinatesEqual(
+  coords1: Coordinates | null | undefined,
+  coords2: Coordinates | null | undefined,
+  tolerance: number = 0.0001
+): boolean {
+  // Both null/undefined are considered equal
+  if (!coords1 && !coords2) {
+    return true;
+  }
+
+  // One null/undefined and one not are not equal
+  if (!coords1 || !coords2) {
+    return false;
+  }
+
+  // Validate both coordinates
+  if (!hasValidCoordinates(coords1) || !hasValidCoordinates(coords2)) {
+    return false;
+  }
+
+  // Check if within tolerance (with small epsilon for floating point precision)
+  const epsilon = 1e-10;
+  const latDiff = Math.abs(coords1.lat - coords2.lat);
+  const lngDiff = Math.abs(coords1.lng - coords2.lng);
+
+  return latDiff <= tolerance + epsilon && lngDiff <= tolerance + epsilon;
+}
+
+/**
+ * Generate a Google Maps search URL for coordinates
+ *
+ * @param coords - Coordinate object with lat and lng
+ * @returns Google Maps search URL or empty string if invalid
+ *
+ * @example
+ * ```ts
+ * getGoogleMapsUrl({ lat: -37.8136, lng: 144.9631 });
+ * // "https://www.google.com/maps/search/?api=1&query=-37.8136,144.9631"
+ * ```
+ */
+export function getGoogleMapsUrl(coords?: Coordinates): string {
+  if (!coords || !hasValidCoordinates(coords)) {
+    return '';
+  }
+
+  return `https://www.google.com/maps/search/?api=1&query=${coords.lat},${coords.lng}`;
+}
+