Add IANA timezone string support to all date manipulation functions

- Move isUTC helper from zone.ts to datetime.ts and add dtfToParts helper
- Refactor getTimezoneOffset and createTimezoneDate in zone.ts to accept
  IANA timezone name strings (e.g., 'America/Los_Angeles') in addition to
  TimeZone objects
- Update ParserPluginOptions.timeZone type to TimeZone | string in parser.ts;
  integrate ignoreCase logic into find function and add validateToken
- Update day-of-week plugin to use new find signature with options parameter
- Change timeZone argument type to TimeZone | string in addDays, addMonths,
  addYears, parse, and preparse
- Add test cases for IANA string timezones and historical timezone changes
  (Metlakatla, Manila); expand boundary values to -1601/+1601

Author: knowledgecode

src/addDays.ts

@@ -1,32 +1,34 @@
-import { toParts, fromParts } from './datetime.ts';
-import { isTimeZone, isUTC, createTimezoneDate } from './zone.ts';
+import { toParts, fromParts, isUTC } from './datetime.ts';
+import { isTimeZone, createTimezoneDate } from './zone.ts';
 import type { TimeZone } from './zone.ts';
 
 /**
  * Adds the specified number of days to a Date object.
  * @param dateObj - The Date object to modify
  * @param days - The number of days to add
- * @param [timeZone] - Optional time zone object or 'UTC'
+ * @param [timeZone] - Optional time zone object, an IANA timezone name or 'UTC' to use Coordinated Universal Time.
  * @returns A new Date object with the specified number of days added
  */
-export function addDays(dateObj: Date, days: number, timeZone?: TimeZone | 'UTC') {
-  // Handle timezone-specific calculation
-  if (isTimeZone(timeZone)) {
-    const parts = toParts(dateObj, timeZone.zone_name);
+export function addDays(dateObj: Date, days: number, timeZone?: TimeZone | string) {
+  const zoneName = isTimeZone(timeZone) ? timeZone.zone_name : timeZone ?? undefined;
 
-    parts.day += days;
-    parts.timezoneOffset = 0;
+  if (!zoneName || isUTC(zoneName)) {
+    const d = new Date(dateObj.getTime());
 
-    return createTimezoneDate(fromParts(parts), timeZone);
+    // Handle UTC calculation
+    if (isUTC(timeZone)) {
+      d.setUTCDate(d.getUTCDate() + days);
+      return d;
+    }
+    // Handle local time calculation
+    d.setDate(d.getDate() + days);
+    return d;
   }
+  // Handle timezone-specific calculation
+  const parts = toParts(dateObj, zoneName);
 
-  const d = new Date(dateObj.getTime());
+  parts.day += days;
+  parts.timezoneOffset = 0;
 
-  // Handle UTC calculation
-  if (isUTC(timeZone)) {
-    d.setUTCDate(d.getUTCDate() + days);
-    return d;
-  }
-  d.setDate(d.getDate() + days);
-  return d;
+  return createTimezoneDate(fromParts(parts), zoneName);
 }

src/addMonths.ts

@@ -1,56 +1,58 @@
-import { toParts, fromParts } from './datetime.ts';
-import { isTimeZone, isUTC, createTimezoneDate } from './zone.ts';
+import { toParts, fromParts, isUTC } from './datetime.ts';
+import { isTimeZone, createTimezoneDate } from './zone.ts';
 import type { TimeZone } from './zone.ts';
 
 /**
  * Adds the specified number of months to a Date object.
  * @param dateObj - The Date object to modify
  * @param months - The number of months to add
- * @param [timeZone] - Optional time zone object or 'UTC'
+ * @param [timeZone] - Optional time zone object, an IANA timezone name or 'UTC' to use Coordinated Universal Time.
  * @returns A new Date object with the specified number of months added
  */
-export function addMonths(dateObj: Date, months: number, timeZone?: TimeZone | 'UTC') {
-  // Handle timezone-specific calculation
-  if (isTimeZone(timeZone)) {
-    const parts = toParts(dateObj, timeZone.zone_name);
-
-    parts.month += months;
-    parts.timezoneOffset = 0;
+export function addMonths(dateObj: Date, months: number, timeZone?: TimeZone | string) {
+  const zoneName = isTimeZone(timeZone) ? timeZone.zone_name : timeZone ?? undefined;
 
-    const d = new Date(fromParts(parts));
+  if (!zoneName || isUTC(zoneName)) {
+    const d = new Date(dateObj.getTime());
 
-    if (d.getUTCDate() < parts.day) {
-      d.setUTCDate(0);
+    // Handle UTC calculation
+    if (isUTC(timeZone)) {
+      d.setUTCMonth(d.getUTCMonth() + months);
+      // Adjust to last day of month if new month has fewer days
+      if (d.getUTCDate() < dateObj.getUTCDate()) {
+        d.setUTCDate(0);
+        return d;
+      }
+      return d;
     }
-
-    return createTimezoneDate(
-      fromParts({
-        ...parts,
-        year: d.getUTCFullYear(),
-        month: d.getUTCMonth() + 1,
-        day: d.getUTCDate()
-      }),
-      timeZone
-    );
-  }
-
-  const d = new Date(dateObj.getTime());
-
-  // Handle UTC calculation
-  if (isUTC(timeZone)) {
-    d.setUTCMonth(d.getUTCMonth() + months);
+    // Handle local time calculation
+    d.setMonth(d.getMonth() + months);
     // Adjust to last day of month if new month has fewer days
-    if (d.getUTCDate() < dateObj.getUTCDate()) {
-      d.setUTCDate(0);
+    if (d.getDate() < dateObj.getDate()) {
+      d.setDate(0);
       return d;
     }
     return d;
   }
-  d.setMonth(d.getMonth() + months);
-  // Adjust to last day of month if new month has fewer days
-  if (d.getDate() < dateObj.getDate()) {
-    d.setDate(0);
-    return d;
+  // Handle timezone-specific calculation
+  const parts = toParts(dateObj, zoneName);
+
+  parts.month += months;
+  parts.timezoneOffset = 0;
+
+  const d = new Date(fromParts(parts));
+
+  if (d.getUTCDate() < parts.day) {
+    d.setUTCDate(0);
   }
-  return d;
+
+  return createTimezoneDate(
+    fromParts({
+      ...parts,
+      year: d.getUTCFullYear(),
+      month: d.getUTCMonth() + 1,
+      day: d.getUTCDate()
+    }),
+    zoneName
+  );
 }

src/addYears.ts

@@ -5,9 +5,9 @@ import type { TimeZone } from './zone.ts';
  * Adds the specified number of years to a Date object.
  * @param dateObj - The Date object to modify
  * @param years - The number of years to add
- * @param [timeZone] - Optional time zone object or 'UTC'
+ * @param [timeZone] - Optional time zone object, an IANA timezone name or 'UTC' to use Coordinated Universal Time.
  * @returns A new Date object with the specified number of years added
  */
-export function addYears(dateObj: Date, years: number, timeZone?: TimeZone | 'UTC') {
+export function addYears(dateObj: Date, years: number, timeZone?: TimeZone | string) {
   return addMonths(dateObj, years * 12, timeZone);
 }

src/datetime.ts

@@ -1,5 +1,4 @@
 import { getDateTimeFormat } from './dtf.ts';
-import { isUTC } from './zone.ts';
 
 export interface DateTimeParts {
   weekday: number;
@@ -13,23 +12,20 @@ export interface DateTimeParts {
   timezoneOffset: number;
 }
 
-export const toParts = (dateObj: Date, zoneName: string): DateTimeParts => {
-  if (isUTC(zoneName)) {
-    return {
-      weekday: dateObj.getUTCDay(),
-      year: dateObj.getUTCFullYear(),
-      month: dateObj.getUTCMonth() + 1,
-      day: dateObj.getUTCDate(),
-      hour: dateObj.getUTCHours(),
-      minute: dateObj.getUTCMinutes(),
-      second: dateObj.getUTCSeconds(),
-      fractionalSecond: dateObj.getUTCMilliseconds(),
-      timezoneOffset: 0
-    };
-  }
+export const fromParts = (parts: DateTimeParts) => {
+  return Date.UTC(
+    parts.year,
+    parts.month - (parts.year < 100 ? 1900 * 12 + 1 : 1),
+    parts.day,
+    parts.hour,
+    parts.minute,
+    parts.second,
+    parts.fractionalSecond + parts.timezoneOffset * 60000
+  );
+};
 
-  const values = getDateTimeFormat(zoneName)
-    .formatToParts(dateObj)
+export const dtfToParts = (dtf: Intl.DateTimeFormat, time: number): DateTimeParts => {
+  return dtf.formatToParts(time)
     .reduce((parts, { type, value }) => {
       switch (type) {
       case 'weekday':
@@ -52,25 +48,32 @@ export const toParts = (dateObj: Date, zoneName: string): DateTimeParts => {
       hour: 0, minute: 0, second: 0, fractionalSecond: 0,
       timezoneOffset: 0
     });
+};
 
-  values.timezoneOffset = (dateObj.getTime() - Date.UTC(
-    values.year,
-    values.month - (values.year < 100 ? 1900 * 12 + 1 : 1),
-    values.day,
-    values.hour,
-    values.minute,
-    values.second,
-    values.fractionalSecond
-  )) / 60000;
-
-  return values;
+export const isUTC = (timeZone: unknown): timeZone is 'UTC' => {
+  return typeof timeZone === 'string' && timeZone.toUpperCase() === 'UTC';
 };
 
-export const fromParts = (parts: DateTimeParts) => {
-  return Date.UTC(
-    parts.year, parts.month - (parts.year < 100 ? 1900 * 12 + 1 : 1), parts.day,
-    parts.hour, parts.minute, parts.second, parts.fractionalSecond + parts.timezoneOffset * 60000
-  );
+export const toParts = (dateObj: Date, zoneName: string): DateTimeParts => {
+  if (isUTC(zoneName)) {
+    return {
+      weekday: dateObj.getUTCDay(),
+      year: dateObj.getUTCFullYear(),
+      month: dateObj.getUTCMonth() + 1,
+      day: dateObj.getUTCDate(),
+      hour: dateObj.getUTCHours(),
+      minute: dateObj.getUTCMinutes(),
+      second: dateObj.getUTCSeconds(),
+      fractionalSecond: dateObj.getUTCMilliseconds(),
+      timezoneOffset: 0
+    };
+  }
+
+  const time = dateObj.getTime();
+  const parts = dtfToParts(getDateTimeFormat(zoneName), time);
+
+  parts.timezoneOffset = (time - fromParts(parts)) / 60000;
+  return parts;
 };
 
 export interface DateLike {

src/parse.ts

@@ -1,6 +1,7 @@
-import { isTimeZone, isUTC, createTimezoneDate } from './zone.ts';
-import { validatePreparseResult } from './isValid.ts';
+import { createTimezoneDate } from './zone.ts';
+import { isUTC } from './datetime.ts';
 import { preparse } from './preparse.ts';
+import { validatePreparseResult } from './isValid.ts';
 import type { CompiledObject } from './compile.ts';
 import type { ParserOptions } from './parser.ts';
 
@@ -26,14 +27,14 @@ export function parse(dateString: string, arg: string | CompiledObject, options?
   pr.s ??= 0;
   pr.S ??= 0;
 
-  if (isTimeZone(options?.timeZone)) {
-    // Handle timezone-specific calculation
-    return createTimezoneDate(Date.UTC(pr.Y, pr.M, pr.D, pr.H, pr.m, pr.s, pr.S), options.timeZone);
-  }
+  // If the preparse result contains a timezone offset (Z), use it to create the date.
   if (isUTC(options?.timeZone) || 'Z' in pr) {
-    // Handle UTC calculation or when 'Z' token is present
     return new Date(Date.UTC(pr.Y, pr.M, pr.D, pr.H, pr.m + (pr.Z ?? 0), pr.s, pr.S));
   }
-  // Handle local timezone calculation
+  // If a specific time zone is provided in the options, use it to create the date.
+  if (options?.timeZone) {
+    return createTimezoneDate(Date.UTC(pr.Y, pr.M, pr.D, pr.H, pr.m, pr.s, pr.S), options.timeZone);
+  }
+  // If no time zone information is available, create the date in the local time zone.
   return new Date(pr.Y, pr.M, pr.D, pr.H, pr.m, pr.s, pr.S);
 }