@jmruthers/pace-core 0.5.183 → 0.5.185

package/src/utils/timezone/index.ts

@@ -0,0 +1,17 @@
+/**
+ * @file Timezone Utilities Exports
+ * @package @jmruthers/pace-core
+ * @module Utils/Timezone
+ * @since 0.1.0
+ */
+
+export {
+  formatInTimeZone,
+  getTimezoneAbbreviation,
+  formatTimeInTimeZone,
+  getUserTimeZone,
+  toZonedTime,
+  fromZonedTime,
+  roundToNearestMinutes,
+  getTimeZoneDifference
+} from './timezone';

package/src/utils/timezone/timezone.test.ts

@@ -0,0 +1,349 @@
+/**
+ * @file Timezone Utilities Tests
+ * @package @jmruthers/pace-core
+ * @module Utils/Timezone/__tests__
+ * @since 0.1.0
+ *
+ * Comprehensive tests for timezone utility functions.
+ * Tests cover all major functionality, edge cases, and error handling.
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import {
+  formatInTimeZone,
+  getTimezoneAbbreviation,
+  formatTimeInTimeZone,
+  getUserTimeZone,
+  toZonedTime,
+  fromZonedTime,
+  roundToNearestMinutes,
+  getTimeZoneDifference
+} from './timezone';
+
+describe('Timezone Utilities', () => {
+  describe('formatInTimeZone', () => {
+    it('formats a Date object in a specific timezone', () => {
+      const date = new Date('2024-01-15T10:00:00Z');
+      const result = formatInTimeZone(date, 'America/New_York', 'MMM dd, yyyy HH:mm');
+      expect(result).toMatch(/Jan 15, 2024/);
+      expect(result).toMatch(/\d{2}:\d{2}/);
+    });
+
+    it('formats an ISO string in a specific timezone', () => {
+      const result = formatInTimeZone('2024-01-15T10:00:00Z', 'America/New_York', 'MMM dd, yyyy');
+      expect(result).toMatch(/Jan 15, 2024/);
+    });
+
+    it('formats a timestamp in a specific timezone', () => {
+      const timestamp = new Date('2024-01-15T10:00:00Z').getTime();
+      const result = formatInTimeZone(timestamp, 'America/New_York', 'yyyy-MM-dd');
+      expect(result).toBe('2024-01-15');
+    });
+
+    it('returns "Invalid date" for invalid date input', () => {
+      const result = formatInTimeZone(new Date('invalid'), 'America/New_York', 'MMM dd, yyyy');
+      expect(result).toBe('Invalid date');
+    });
+
+    it('returns "Invalid date" for invalid timezone', () => {
+      const date = new Date('2024-01-15T10:00:00Z');
+      const result = formatInTimeZone(date, '', 'MMM dd, yyyy');
+      expect(result).toBe('Invalid date');
+    });
+
+    it('returns "Invalid date" for non-string timezone', () => {
+      const date = new Date('2024-01-15T10:00:00Z');
+      // @ts-expect-error - Testing invalid input
+      const result = formatInTimeZone(date, null, 'MMM dd, yyyy');
+      expect(result).toBe('Invalid date');
+    });
+
+    it('handles different timezones correctly', () => {
+      const date = new Date('2024-01-15T10:00:00Z');
+      const ny = formatInTimeZone(date, 'America/New_York', 'HH:mm');
+      const la = formatInTimeZone(date, 'America/Los_Angeles', 'HH:mm');
+      expect(ny).not.toBe(la);
+    });
+  });
+
+  describe('getTimezoneAbbreviation', () => {
+    it('returns timezone abbreviation for valid date and timezone', () => {
+      const date = new Date('2024-01-15T10:00:00Z');
+      const result = getTimezoneAbbreviation(date, 'America/New_York');
+      expect(typeof result).toBe('string');
+      expect(result.length).toBeGreaterThan(0);
+    });
+
+    it('returns timezone name as fallback when abbreviation unavailable', () => {
+      const date = new Date('2024-01-15T10:00:00Z');
+      const result = getTimezoneAbbreviation(date, 'America/New_York');
+      expect(result).toBeTruthy();
+    });
+
+    it('returns timezone string for invalid date', () => {
+      const result = getTimezoneAbbreviation(new Date('invalid'), 'America/New_York');
+      expect(result).toBe('America/New_York');
+    });
+
+    it('returns "UTC" for empty timezone', () => {
+      const date = new Date('2024-01-15T10:00:00Z');
+      const result = getTimezoneAbbreviation(date, '');
+      expect(result).toBe('UTC');
+    });
+
+    it('handles invalid timezone gracefully', () => {
+      const date = new Date('2024-01-15T10:00:00Z');
+      const result = getTimezoneAbbreviation(date, 'Invalid/Timezone');
+      expect(typeof result).toBe('string');
+    });
+  });
+
+  describe('formatTimeInTimeZone', () => {
+    it('formats time only in specific timezone', () => {
+      const date = new Date('2024-01-15T10:00:00Z');
+      const result = formatTimeInTimeZone(date, 'America/New_York');
+      expect(result).toMatch(/^\d{2}:\d{2}$/);
+    });
+
+    it('formats ISO string time in timezone', () => {
+      const result = formatTimeInTimeZone('2024-01-15T10:00:00Z', 'America/New_York');
+      expect(result).toMatch(/^\d{2}:\d{2}$/);
+    });
+
+    it('returns "Invalid date" for invalid input', () => {
+      const result = formatTimeInTimeZone(new Date('invalid'), 'America/New_York');
+      expect(result).toBe('Invalid date');
+    });
+  });
+
+  describe('getUserTimeZone', () => {
+    it('returns IANA timezone string', () => {
+      const result = getUserTimeZone();
+      expect(typeof result).toBe('string');
+      expect(result.length).toBeGreaterThan(0);
+    });
+
+    it('returns "UTC" as fallback when Intl is unavailable', () => {
+      const originalIntl = global.Intl;
+      // @ts-expect-error - Testing fallback behavior
+      global.Intl = undefined;
+      const result = getUserTimeZone();
+      expect(result).toBe('UTC');
+      global.Intl = originalIntl;
+    });
+
+    it('returns "UTC" on error', () => {
+      const originalDateTimeFormat = Intl.DateTimeFormat;
+      // @ts-expect-error - Testing error handling
+      Intl.DateTimeFormat = () => {
+        throw new Error('Test error');
+      };
+      const result = getUserTimeZone();
+      expect(result).toBe('UTC');
+      Intl.DateTimeFormat = originalDateTimeFormat;
+    });
+  });
+
+  describe('toZonedTime', () => {
+    it('converts UTC date to timezone local time', () => {
+      const utcDate = new Date('2024-01-15T10:00:00Z');
+      const result = toZonedTime(utcDate, 'America/New_York');
+      expect(result).toBeInstanceOf(Date);
+      expect(result.getTime()).not.toBe(utcDate.getTime());
+    });
+
+    it('returns original date for invalid timezone', () => {
+      const date = new Date('2024-01-15T10:00:00Z');
+      const result = toZonedTime(date, '');
+      expect(result).toBe(date);
+    });
+
+    it('returns original date for invalid date', () => {
+      const invalidDate = new Date('invalid');
+      const result = toZonedTime(invalidDate, 'America/New_York');
+      expect(result).toBe(invalidDate);
+    });
+
+    it('handles different timezones correctly', () => {
+      const utcDate = new Date('2024-01-15T10:00:00Z');
+      const ny = toZonedTime(utcDate, 'America/New_York');
+      const la = toZonedTime(utcDate, 'America/Los_Angeles');
+      expect(ny.getTime()).not.toBe(la.getTime());
+    });
+
+    it('returns original date on error', () => {
+      const date = new Date('2024-01-15T10:00:00Z');
+      // @ts-expect-error - Testing error handling
+      const result = toZonedTime(date, null);
+      expect(result).toBe(date);
+    });
+  });
+
+  describe('fromZonedTime', () => {
+    it('converts local time in timezone to UTC', () => {
+      const localDate = new Date(2024, 0, 15, 10, 0); // Jan 15, 2024 10:00 AM local
+      const result = fromZonedTime(localDate, 'America/New_York');
+      expect(result).toBeInstanceOf(Date);
+    });
+
+    it('returns original date for invalid timezone', () => {
+      const date = new Date(2024, 0, 15, 10, 0);
+      const result = fromZonedTime(date, '');
+      expect(result).toBe(date);
+    });
+
+    it('returns original date for invalid date', () => {
+      const invalidDate = new Date('invalid');
+      const result = fromZonedTime(invalidDate, 'America/New_York');
+      expect(result).toBe(invalidDate);
+    });
+
+    it('handles round-trip conversion', () => {
+      const utcDate = new Date('2024-01-15T10:00:00Z');
+      const zoned = toZonedTime(utcDate, 'America/New_York');
+      const backToUtc = fromZonedTime(zoned, 'America/New_York');
+      // Should be close to original (within a few milliseconds due to DST handling)
+      expect(Math.abs(backToUtc.getTime() - utcDate.getTime())).toBeLessThan(1000);
+    });
+
+    it('returns original date on error', () => {
+      const date = new Date(2024, 0, 15, 10, 0);
+      // @ts-expect-error - Testing error handling
+      const result = fromZonedTime(date, null);
+      expect(result).toBe(date);
+    });
+  });
+
+  describe('roundToNearestMinutes', () => {
+    it('rounds to nearest 5 minutes by default', () => {
+      const date = new Date('2024-01-15T10:23:00Z');
+      const result = roundToNearestMinutes(date);
+      expect(result.getMinutes() % 5).toBe(0);
+    });
+
+    it('rounds to nearest specified minutes', () => {
+      const date = new Date('2024-01-15T10:23:00Z');
+      const result = roundToNearestMinutes(date, 10);
+      expect(result.getMinutes() % 10).toBe(0);
+    });
+
+    it('rounds up when closer to next interval', () => {
+      const date = new Date('2024-01-15T10:28:00Z');
+      const result = roundToNearestMinutes(date, 5);
+      expect(result.getMinutes()).toBe(30);
+    });
+
+    it('rounds down when closer to previous interval', () => {
+      const date = new Date('2024-01-15T10:22:00Z');
+      const result = roundToNearestMinutes(date, 5);
+      expect(result.getMinutes()).toBe(20);
+    });
+
+    it('returns original date for invalid date', () => {
+      const invalidDate = new Date('invalid');
+      const result = roundToNearestMinutes(invalidDate, 5);
+      expect(result).toBe(invalidDate);
+    });
+
+    it('returns original date for invalid minutesStep', () => {
+      const date = new Date('2024-01-15T10:23:00Z');
+      const result = roundToNearestMinutes(date, 0);
+      expect(date).toBe(date);
+    });
+
+    it('returns original date for negative minutesStep', () => {
+      const date = new Date('2024-01-15T10:23:00Z');
+      const result = roundToNearestMinutes(date, -5);
+      expect(result).toBe(date);
+    });
+
+    it('returns original date for non-integer minutesStep', () => {
+      const date = new Date('2024-01-15T10:23:00Z');
+      const result = roundToNearestMinutes(date, 5.5);
+      expect(result).toBe(date);
+    });
+
+    it('handles edge case of exact minute', () => {
+      const date = new Date('2024-01-15T10:25:00Z');
+      const result = roundToNearestMinutes(date, 5);
+      expect(result.getMinutes()).toBe(25);
+    });
+  });
+
+  describe('getTimeZoneDifference', () => {
+    it('calculates difference between two timezones', () => {
+      const result = getTimeZoneDifference('America/New_York', 'America/Los_Angeles');
+      expect(typeof result).toBe('number');
+      // Los Angeles is typically 3 hours behind New York
+      expect(result).toBeLessThan(0);
+    });
+
+    it('returns 0 for same timezone', () => {
+      const result = getTimeZoneDifference('America/New_York', 'America/New_York');
+      expect(result).toBe(0);
+    });
+
+    it('returns 0 for invalid timezones', () => {
+      const result = getTimeZoneDifference('', 'America/New_York');
+      expect(result).toBe(0);
+    });
+
+    it('returns 0 for non-string timezones', () => {
+      // @ts-expect-error - Testing invalid input
+      const result = getTimeZoneDifference(null, 'America/New_York');
+      expect(result).toBe(0);
+    });
+
+    it('handles DST correctly', () => {
+      // Test in summer (EDT vs PDT = 3 hours)
+      const summerDate = new Date('2024-07-15T10:00:00Z');
+      const result = getTimeZoneDifference('America/New_York', 'America/Los_Angeles');
+      // Should be negative (LA behind NY)
+      expect(result).toBeLessThan(0);
+    });
+
+    it('returns 0 on error', () => {
+      // This test verifies error handling path
+      const result = getTimeZoneDifference('Invalid/Timezone1', 'Invalid/Timezone2');
+      expect(result).toBe(0);
+    });
+  });
+
+  describe('Edge Cases', () => {
+    it('handles null and undefined inputs gracefully', () => {
+      // @ts-expect-error - Testing edge cases
+      expect(formatInTimeZone(null, 'America/New_York', 'yyyy-MM-dd')).toBe('Invalid date');
+      // @ts-expect-error - Testing edge cases
+      expect(formatInTimeZone(undefined, 'America/New_York', 'yyyy-MM-dd')).toBe('Invalid date');
+    });
+
+    it('handles extreme dates', () => {
+      const farFuture = new Date('2099-12-31T23:59:59Z');
+      const result = formatInTimeZone(farFuture, 'America/New_York', 'yyyy-MM-dd');
+      expect(result).toMatch(/2099-12-31/);
+
+      const farPast = new Date('1900-01-01T00:00:00Z');
+      const result2 = formatInTimeZone(farPast, 'America/New_York', 'yyyy-MM-dd');
+      // Timezone conversion may shift the date to previous day due to timezone offset
+      // Accept either 1900-01-01 or 1899-12-31 depending on timezone offset
+      expect(result2).toMatch(/1899-12-31|1900-01-01/);
+    });
+
+    it('handles various timezone formats', () => {
+      const date = new Date('2024-01-15T10:00:00Z');
+      const timezones = [
+        'America/New_York',
+        'Europe/London',
+        'Asia/Tokyo',
+        'Australia/Sydney',
+        'UTC'
+      ];
+
+      timezones.forEach(tz => {
+        const result = formatInTimeZone(date, tz, 'yyyy-MM-dd');
+        expect(result).toBe('2024-01-15');
+      });
+    });
+  });
+});
+

package/src/utils/timezone/timezone.ts

@@ -0,0 +1,281 @@
+/**
+ * @file Timezone Utilities
+ * @package @jmruthers/pace-core
+ * @module Utils/Timezone
+ * @since 0.1.0
+ *
+ * Comprehensive timezone conversion and formatting utilities using date-fns-tz and native Intl APIs.
+ * Provides functions for timezone-aware date operations, conversions, and formatting.
+ *
+ * Features:
+ * - Format dates in specific timezones
+ * - Get timezone abbreviations
+ * - Convert between UTC and timezone local times
+ * - Round dates to nearest minutes
+ * - Calculate timezone differences
+ * - Get user's browser timezone
+ *
+ * @example
+ * ```ts
+ * import { toZonedTime, fromZonedTime, formatInTimeZone, getUserTimeZone } from '@jmruthers/pace-core/utils/timezone';
+ *
+ * // Convert UTC to local timezone
+ * const utcDate = new Date('2024-01-15T10:00:00Z');
+ * const localDate = toZonedTime(utcDate, 'America/New_York');
+ *
+ * // Convert local time to UTC
+ * const localInput = new Date(2024, 0, 15, 10, 0);
+ * const utcDate = fromZonedTime(localInput, 'America/New_York');
+ *
+ * // Format with timezone
+ * const formatted = formatInTimeZone(utcDate, 'America/New_York', 'MMM dd, yyyy HH:mm');
+ * ```
+ */
+
+import { format, parseISO, addMinutes, differenceInHours, isValid } from 'date-fns';
+import { formatInTimeZone as fnsFormatInTimeZone, toZonedTime as fnsToZonedTime, fromZonedTime as fnsFromZonedTime } from 'date-fns-tz';
+
+/**
+ * Format a date in a specific timezone using date-fns format strings
+ *
+ * @param date - Date to format (Date object, ISO string, or timestamp)
+ * @param timeZone - IANA timezone string (e.g., 'America/New_York')
+ * @param formatStr - date-fns format string (e.g., 'MMM dd, yyyy HH:mm')
+ * @returns Formatted date string or 'Invalid date' on error
+ *
+ * @example
+ * ```ts
+ * formatInTimeZone(new Date('2024-01-15T10:00:00Z'), 'America/New_York', 'MMM dd, yyyy HH:mm');
+ * // "Jan 15, 2024 05:00"
+ * ```
+ */
+export function formatInTimeZone(
+  date: Date | string | number,
+  timeZone: string,
+  formatStr: string
+): string {
+  try {
+    if (!timeZone || typeof timeZone !== 'string') {
+      return 'Invalid date';
+    }
+
+    let dateObj: Date;
+    if (typeof date === 'string') {
+      dateObj = parseISO(date);
+    } else if (typeof date === 'number') {
+      dateObj = new Date(date);
+    } else {
+      dateObj = date;
+    }
+
+    if (!isValid(dateObj)) {
+      return 'Invalid date';
+    }
+
+    return fnsFormatInTimeZone(dateObj, timeZone, formatStr);
+  } catch {
+    return 'Invalid date';
+  }
+}
+
+/**
+ * Get the timezone abbreviation (EST, PST, etc.) for a date in a specific timezone
+ *
+ * @param date - Date to get abbreviation for
+ * @param timeZone - IANA timezone string
+ * @returns Timezone abbreviation or timezone name on error
+ *
+ * @example
+ * ```ts
+ * getTimezoneAbbreviation(new Date(), 'America/New_York');
+ * // "EST" or "EDT" depending on date
+ * ```
+ */
+export function getTimezoneAbbreviation(date: Date, timeZone: string): string {
+  try {
+    if (!timeZone || typeof timeZone !== 'string') {
+      return timeZone || 'UTC';
+    }
+
+    if (!isValid(date)) {
+      return timeZone;
+    }
+
+    const formatter = new Intl.DateTimeFormat('en-US', {
+      timeZone,
+      timeZoneName: 'short'
+    });
+
+    const parts = formatter.formatToParts(date);
+    const timeZoneName = parts.find(part => part.type === 'timeZoneName');
+
+    return timeZoneName?.value || timeZone;
+  } catch {
+    return timeZone || 'UTC';
+  }
+}
+
+/**
+ * Format time only in a specific timezone
+ *
+ * @param date - Date to format
+ * @param timeZone - IANA timezone string
+ * @returns Formatted time string (HH:mm format) or 'Invalid date' on error
+ *
+ * @example
+ * ```ts
+ * formatTimeInTimeZone(new Date('2024-01-15T10:00:00Z'), 'America/New_York');
+ * // "05:00"
+ * ```
+ */
+export function formatTimeInTimeZone(date: Date | string, timeZone: string): string {
+  return formatInTimeZone(date, timeZone, 'HH:mm');
+}
+
+/**
+ * Get the user's local timezone from the browser
+ *
+ * @returns IANA timezone string (e.g., 'America/New_York')
+ *
+ * @example
+ * ```ts
+ * const userTz = getUserTimeZone();
+ * // "America/New_York" or user's actual timezone
+ * ```
+ */
+export function getUserTimeZone(): string {
+  try {
+    if (typeof Intl !== 'undefined' && Intl.DateTimeFormat) {
+      return Intl.DateTimeFormat().resolvedOptions().timeZone;
+    }
+    return 'UTC';
+  } catch {
+    return 'UTC';
+  }
+}
+
+/**
+ * Convert a UTC date to a specific timezone's local time representation
+ *
+ * @param date - UTC date to convert
+ * @param timezone - IANA timezone string
+ * @returns Date object representing local time in the timezone
+ *
+ * @example
+ * ```ts
+ * const utcDate = new Date('2024-01-15T10:00:00Z');
+ * const localDate = toZonedTime(utcDate, 'America/New_York');
+ * // Returns Date object representing 5:00 AM in New York
+ * ```
+ */
+export function toZonedTime(date: Date, timezone: string): Date {
+  try {
+    if (!timezone || typeof timezone !== 'string') {
+      return date;
+    }
+
+    if (!isValid(date)) {
+      return date;
+    }
+
+    return fnsToZonedTime(date, timezone);
+  } catch {
+    return date;
+  }
+}
+
+/**
+ * Convert a local time in a specific timezone to UTC
+ *
+ * @param localDate - Local date in the timezone
+ * @param timezone - IANA timezone string
+ * @returns Date object in UTC
+ *
+ * @example
+ * ```ts
+ * const localDate = new Date(2024, 0, 15, 10, 0); // Jan 15, 2024 10:00 AM local
+ * const utcDate = fromZonedTime(localDate, 'America/New_York');
+ * // Returns Date object representing 3:00 PM UTC (if EST) or 2:00 PM UTC (if EDT)
+ * ```
+ */
+export function fromZonedTime(localDate: Date, timezone: string): Date {
+  try {
+    if (!timezone || typeof timezone !== 'string') {
+      return localDate;
+    }
+
+    if (!isValid(localDate)) {
+      return localDate;
+    }
+
+    return fnsFromZonedTime(localDate, timezone);
+  } catch {
+    return localDate;
+  }
+}
+
+/**
+ * Round a date to the nearest X minutes
+ *
+ * @param date - Date to round
+ * @param minutesStep - Number of minutes to round to (default: 5)
+ * @returns Rounded date
+ *
+ * @example
+ * ```ts
+ * const date = new Date('2024-01-15T10:23:00Z');
+ * roundToNearestMinutes(date, 5);
+ * // Returns Date object for 10:25:00
+ * ```
+ */
+export function roundToNearestMinutes(date: Date, minutesStep: number = 5): Date {
+  try {
+    if (!isValid(date)) {
+      return date;
+    }
+
+    if (minutesStep <= 0 || !Number.isInteger(minutesStep)) {
+      return date;
+    }
+
+    const minutes = date.getMinutes();
+    const roundedMinutes = Math.round(minutes / minutesStep) * minutesStep;
+    const diff = roundedMinutes - minutes;
+
+    return addMinutes(date, diff);
+  } catch {
+    return date;
+  }
+}
+
+/**
+ * Calculate the time difference between two timezones in hours
+ *
+ * @param fromTimeZone - Source timezone (IANA string)
+ * @param toTimeZone - Target timezone (IANA string)
+ * @returns Difference in hours (positive if toTimeZone is ahead)
+ *
+ * @example
+ * ```ts
+ * getTimeZoneDifference('America/New_York', 'America/Los_Angeles');
+ * // -3 (Los Angeles is 3 hours behind New York)
+ * ```
+ */
+export function getTimeZoneDifference(fromTimeZone: string, toTimeZone: string): number {
+  try {
+    if (!fromTimeZone || !toTimeZone || typeof fromTimeZone !== 'string' || typeof toTimeZone !== 'string') {
+      return 0;
+    }
+
+    const now = new Date();
+    const fromDate = toZonedTime(now, fromTimeZone);
+    const toDate = toZonedTime(now, toTimeZone);
+
+    const diff = differenceInHours(toDate, fromDate);
+    // Handle NaN case (differenceInHours can return NaN for invalid dates)
+    return isNaN(diff) ? 0 : diff;
+  } catch {
+    return 0;
+  }
+}
+