@jmruthers/pace-core 0.5.184 → 0.5.186

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