@catbee/utils 2.0.1 → 2.0.3

package/date/index.d.ts

@@ -22,12 +22,31 @@
  * SOFTWARE.
  */
 
+/**
+ * Named date format presets
+ *
+ * | Preset        | Equivalent                            | Example (en-US)                                    |
+ * |---------------|---------------------------------------|----------------------------------------------------|
+ * | 'short'       | 'M/d/yy, h:mm a'                      | 6/15/15, 9:03 AM                                   |
+ * | 'medium'      | 'MMM d, y, h:mm:ss a'                 | Jun 15, 2015, 9:03:01 AM                           |
+ * | 'long'        | 'MMMM d, y, h:mm:ss a z'              | June 15, 2015 at 9:03:01 AM GMT+1                  |
+ * | 'full'        | 'EEEE, MMMM d, y, h:mm:ss a zzzz'     | Monday, June 15, 2015 at 9:03:01 AM GMT+01:00      |
+ * | 'shortDate'   | 'M/d/yy'                              | 6/15/15                                            |
+ * | 'mediumDate'  | 'MMM d, y'                            | Jun 15, 2015                                       |
+ * | 'longDate'    | 'MMMM d, y'                           | June 15, 2015                                      |
+ * | 'fullDate'    | 'EEEE, MMMM d, y'                     | Monday, June 15, 2015                              |
+ * | 'shortTime'   | 'h:mm a'                              | 9:03 AM                                            |
+ * | 'mediumTime'  | 'h:mm:ss a'                           | 9:03:01 AM                                         |
+ * | 'longTime'    | 'h:mm:ss a z'                         | 9:03:01 AM GMT+1                                   |
+ * | 'fullTime'    | 'h:mm:ss a zzzz'                      | 9:03:01 AM GMT+01:00                               |
+ */
+type DateFormatPreset = 'short' | 'medium' | 'long' | 'full' | 'shortDate' | 'mediumDate' | 'longDate' | 'fullDate' | 'shortTime' | 'mediumTime' | 'longTime' | 'fullTime';
 /**
  * Format options for the formatDate function
  */
 interface DateFormatOptions {
-    /** Date format pattern (default: 'yyyy-MM-dd') */
-    format?: string;
+    /** Date format pattern, named preset, or 'relative' (default: 'yyyy-MM-dd') */
+    format?: DateFormatPreset | string;
     /** Locale to use for formatting (default: system locale) */
     locale?: string | string[];
     /** Time zone to use (default: system time zone) */
@@ -65,13 +84,20 @@ declare function formatRelativeTime(date: Date | number, now?: Date | number, lo
 /**
  * Parse a date string or timestamp into a Date object.
  *
+ * **Timezone Behavior:**
+ * - Date-only strings (e.g., '2023-05-15') are parsed as **local midnight**,
+ *   not UTC midnight (differs from `new Date()` native behavior)
+ * - ISO strings with timezone (e.g., '2023-05-15T10:30:00Z') use the specified timezone
+ * - This follows Luxon's "local time first" philosophy
+ *
  * @param input - Date string or timestamp to parse
  * @param fallback - Fallback date if parsing fails
  * @returns Parsed Date object or fallback
  *
  * @example
  * ```typescript
- * parseDate('2023-05-15'); // Date object for May 15, 2023
+ * parseDate('2023-05-15'); // Local midnight on May 15, 2023
+ * parseDate('2023-05-15T10:30:00Z'); // 10:30 AM UTC on May 15, 2023
  * parseDate('invalid', new Date()); // Returns current date as fallback
  * ```
  */
@@ -94,6 +120,26 @@ declare function parseDate(input: string | number, fallback?: Date): Date | null
  * ```
  */
 declare function dateDiff(date1: Date | number, date2?: Date | number, unit?: 'milliseconds' | 'seconds' | 'minutes' | 'hours' | 'days' | 'months' | 'years'): number;
+/**
+ * Calculate the difference in calendar days between two dates as observed in a specific timezone.
+ * Both dates are converted to calendar year/month/day values in the supplied IANA timezone, and
+ * the difference between those calendar dates is returned.
+ *
+ * JavaScript `Date` instances do not retain timezone identity, so this function does not detect
+ * whether the input dates originated from different timezones.
+ *
+ * @param d1 - First date
+ * @param d2 - Second date
+ * @param tz - IANA timezone identifier used to interpret both dates (e.g., 'America/New_York')
+ * @return Number of calendar days difference between the two dates in the specified timezone
+ * @throws {RangeError} If `tz` is not a valid IANA timezone identifier, as thrown by the underlying `Intl` APIs
+ * @example
+ * ```typescript
+ * // Calculate days difference in New York timezone
+ * dateDiffDaysTZ(new Date('2023-05-15T00:00:00'), new Date('2023-05-14T23:00:00'), 'America/New_York'); // 1
+ * ```
+ */
+declare function dateDiffDaysTZ(d1: Date, d2: Date, tz: string): number;
 /**
  * Add a specified amount of time to a date.
  *
@@ -111,7 +157,9 @@ declare function dateDiff(date1: Date | number, date2?: Date | number, unit?: 'm
  * addToDate(new Date('2023-05-15T10:00:00'), -2, 'hours'); // Date for May 15, 2023 08:00:00
  * ```
  */
-declare function addToDate(date: Date | number, amount: number, unit: 'milliseconds' | 'seconds' | 'minutes' | 'hours' | 'days' | 'months' | 'years'): Date;
+declare function addToDate(date: Date | number, amount: number, unit: 'milliseconds' | 'seconds' | 'minutes' | 'hours' | 'days' | 'months' | 'years', options?: {
+    timeZone?: string;
+}): Date;
 /**
  * Get the start of a time period containing the specified date.
  *
@@ -303,6 +351,96 @@ declare function quarterOf(date: Date | number): 1 | 2 | 3 | 4;
  * weekOfYear(new Date('2024-01-15')); // 3
  */
 declare function weekOfYear(date: Date | number): number;
+/**
+ * Get the UTC offset in minutes for a specific IANA timezone at a given instant.
+ * Positive values mean ahead of UTC (e.g., +120 for UTC+2), negative behind.
+ *
+ * @param timeZone - IANA timezone identifier (e.g., 'America/New_York')
+ * @param date - Point in time to evaluate (default: now)
+ * @returns Offset in minutes from UTC
+ *
+ * @example
+ * ```typescript
+ * getTimezoneOffset('America/New_York'); // -300 (EST) or -240 (EDT)
+ * getTimezoneOffset('Europe/Berlin');    // +60 (CET) or +120 (CEST)
+ * ```
+ */
+declare function getTimezoneOffset(timeZone: string, date?: Date | number): number;
+/**
+ * Convert a Date to the wall-clock components in a specific timezone.
+ * Returns an object with year, month (1-12), day, hour, minute, second, millisecond.
+ *
+ * @param date - Date to convert
+ * @param timeZone - IANA timezone identifier
+ * @returns Date components in the target timezone
+ *
+ * @example
+ * ```typescript
+ * const utcNoon = new Date('2024-06-15T12:00:00Z');
+ * toTimeZone(utcNoon, 'America/New_York');
+ * // { year: 2024, month: 6, day: 15, hour: 8, minute: 0, second: 0, millisecond: 0 }
+ * ```
+ */
+declare function toTimeZone(date: Date | number, timeZone: string): {
+    year: number;
+    month: number;
+    day: number;
+    hour: number;
+    minute: number;
+    second: number;
+    millisecond: number;
+};
+/**
+ * Format a Date in a specific timezone using common format patterns.
+ * Supports 'yyyy-MM-dd', 'yyyy-MM-dd HH:mm:ss', and Intl-based formatting.
+ *
+ * @param date - Date to format
+ * @param timeZone - IANA timezone identifier
+ * @param format - Format pattern (default: 'yyyy-MM-dd HH:mm:ss')
+ * @param locale - Locale for Intl formatting
+ * @returns Formatted date string in the target timezone
+ *
+ * @example
+ * ```typescript
+ * const utcDate = new Date('2024-06-15T18:30:00Z');
+ * formatDateInTimeZone(utcDate, 'America/New_York', 'yyyy-MM-dd HH:mm:ss');
+ * // '2024-06-15 14:30:00'
+ *
+ * formatDateInTimeZone(utcDate, 'Asia/Tokyo', 'yyyy-MM-dd');
+ * // '2024-06-16'
+ * ```
+ */
+declare function formatDateInTimeZone(date: Date | number, timeZone: string, format?: string, locale?: string | string[]): string;
+/**
+ * Check if a given IANA timezone is currently observing DST.
+ *
+ * @param timeZone - IANA timezone identifier
+ * @param date - Point in time to check (default: now)
+ * @returns True if the timezone is in DST at the given moment
+ *
+ * @example
+ * ```typescript
+ * isDST('America/New_York', new Date('2024-07-01')); // true  (EDT)
+ * isDST('America/New_York', new Date('2024-01-01')); // false (EST)
+ * isDST('Asia/Tokyo');                               // false (no DST)
+ * ```
+ */
+declare function isDST(timeZone: string, date?: Date | number): boolean;
+/**
+ * Get the IANA timezone abbreviation (e.g., "EST", "EDT", "CET") for a date.
+ *
+ * @param timeZone - IANA timezone identifier
+ * @param date - Point in time (default: now)
+ * @param locale - Locale for formatting (default: 'en-US')
+ * @returns Timezone abbreviation string
+ *
+ * @example
+ * ```typescript
+ * getTimezoneAbbreviation('America/New_York', new Date('2024-01-15')); // 'EST'
+ * getTimezoneAbbreviation('America/New_York', new Date('2024-07-15')); // 'EDT'
+ * ```
+ */
+declare function getTimezoneAbbreviation(timeZone: string, date?: Date | number, locale?: string): string;
 
 /**
  * DateBuilder class for fluent date manipulation and building.
@@ -693,7 +831,41 @@ declare class DateBuilder {
      * Convert to string.
      */
     toString(): string;
+    /**
+     * Format the date in a specific timezone.
+     * @param timeZone - IANA timezone identifier (e.g., 'America/New_York')
+     * @param format - Format pattern (default: 'yyyy-MM-dd HH:mm:ss')
+     */
+    formatInTimeZone(timeZone: string, format?: string): string;
+    /**
+     * Get the wall-clock components in a specific timezone.
+     * @param timeZone - IANA timezone identifier
+     */
+    toTimeZone(timeZone: string): {
+        year: number;
+        month: number;
+        day: number;
+        hour: number;
+        minute: number;
+        second: number;
+        millisecond: number;
+    };
+    /**
+     * Get the UTC offset in minutes for a specific timezone at this date's instant.
+     * @param timeZone - IANA timezone identifier
+     */
+    getTimezoneOffset(timeZone: string): number;
+    /**
+     * Check if the specified timezone is observing DST at this date's instant.
+     * @param timeZone - IANA timezone identifier
+     */
+    isDST(timeZone: string): boolean;
+    /**
+     * Get the timezone abbreviation (e.g., 'EST', 'EDT') for a specific timezone.
+     * @param timeZone - IANA timezone identifier
+     */
+    getTimezoneAbbreviation(timeZone: string): string;
 }
 
-export { DateBuilder, addDays, addMonths, addToDate, addYears, dateDiff, daysInMonth, endOf, formatDate, formatDuration, formatRelativeTime, getDateFromDuration, isBetween, isFuture, isLeapYear, isPast, isToday, isWeekend, parseDate, parseDuration, quarterOf, startOf, weekOfYear };
-export type { DateFormatOptions };
+export { DateBuilder, addDays, addMonths, addToDate, addYears, dateDiff, dateDiffDaysTZ, daysInMonth, endOf, formatDate, formatDateInTimeZone, formatDuration, formatRelativeTime, getDateFromDuration, getTimezoneAbbreviation, getTimezoneOffset, isBetween, isDST, isFuture, isLeapYear, isPast, isToday, isWeekend, parseDate, parseDuration, quarterOf, startOf, toTimeZone, weekOfYear };
+export type { DateFormatOptions, DateFormatPreset };