Refactor: Separate TimeZone type definition into zone.ts

knowledgecode · knowledgecode · commit c3fe15165076 · 2026-01-18T17:41:03.000+09:00
Move TimeZone interface and helper functions from timezone.ts to a new
zone.ts file to improve code organization and prepare for adding
consolidated timezone imports feature.

This change does not affect the external API or functionality.
diff --git a/src/addDays.ts b/src/addDays.ts
@@ -1,6 +1,6 @@
 import { toParts, fromParts } from './datetime.ts';
-import { isTimeZone, isUTC, createTimezoneDate } from './timezone.ts';
-import type { TimeZone } from './timezone.ts';
+import { isTimeZone, isUTC, createTimezoneDate } from './zone.ts';
+import type { TimeZone } from './zone.ts';
 
 /**
  * Adds the specified number of days to a Date object.
diff --git a/src/addMonths.ts b/src/addMonths.ts
@@ -1,6 +1,6 @@
 import { toParts, fromParts } from './datetime.ts';
-import { isTimeZone, isUTC, createTimezoneDate } from './timezone.ts';
-import type { TimeZone } from './timezone.ts';
+import { isTimeZone, isUTC, createTimezoneDate } from './zone.ts';
+import type { TimeZone } from './zone.ts';
 
 /**
  * Adds the specified number of months to a Date object.
diff --git a/src/addYears.ts b/src/addYears.ts
@@ -1,5 +1,5 @@
 import { addMonths } from './addMonths.ts';
-import type { TimeZone } from './timezone.ts';
+import type { TimeZone } from './zone.ts';
 
 /**
  * Adds the specified number of years to a Date object.
diff --git a/src/datetime.ts b/src/datetime.ts
@@ -1,4 +1,5 @@
 import { getDateTimeFormat } from './dtf.ts';
+import { isUTC } from './zone.ts';
 
 export interface DateTimeParts {
   weekday: number;
@@ -13,7 +14,7 @@ export interface DateTimeParts {
 }
 
 export const toParts = (dateObj: Date, zoneName: string): DateTimeParts => {
-  if (zoneName.toUpperCase() === 'UTC') {
+  if (isUTC(zoneName)) {
     return {
       weekday: dateObj.getUTCDay(),
       year: dateObj.getUTCFullYear(),
@@ -102,11 +103,11 @@ export interface DateLike {
    */
   getMilliseconds(): number;
   /**
-   * Returns the day of the week (0-6; where 0 is Sunday).
+   * Returns the day of the week (0-6, where 0 is Sunday).
    */
   getDay(): number;
   /**
-   * Returns the time value in milliseconds since the Unix epoch (January 1; 1970).
+   * Returns the time value in milliseconds since the Unix epoch (January 1, 1970).
    */
   getTime(): number;
   /**
diff --git a/src/format.ts b/src/format.ts
@@ -3,7 +3,7 @@ import { DateTime } from './datetime.ts';
 import { formatter as defaultFormatter } from './formatter.ts';
 import en from './locales/en.ts';
 import latn from './numerals/latn.ts';
-import { isTimeZone, isUTC } from './timezone.ts';
+import { isTimeZone } from './zone.ts';
 import type { CompiledObject } from './compile.ts';
 import type { FormatterOptions } from './formatter.ts';
 
@@ -18,15 +18,14 @@ const comment = /^\[(.*)\]$/;
  */
 export function format(dateObj: Date, arg: string | CompiledObject, options?: FormatterOptions) {
   const pattern = (typeof arg === 'string' ? compile(arg) : arg).slice(1);
-  const timeZone = isTimeZone(options?.timeZone) || isUTC(options?.timeZone) ? options.timeZone : undefined;
-  const zoneName = typeof timeZone === 'string' ? timeZone : timeZone?.zone_name ?? '';
+  const zoneName = isTimeZone(options?.timeZone) ? options.timeZone.zone_name : options?.timeZone;
   const dateTime = zoneName ? new DateTime(dateObj, zoneName) : dateObj;
   const formatterOptions = {
     hour12: options?.hour12 ?? 'h12',
     hour24: options?.hour24 ?? 'h23',
     numeral: options?.numeral ?? latn,
     calendar: options?.calendar ?? 'gregory',
-    timeZone,
+    timeZone: options?.timeZone,
     locale: options?.locale ?? en
   };
   const formatters = [...options?.plugins ?? [], defaultFormatter];
diff --git a/src/formatter.ts b/src/formatter.ts
@@ -2,7 +2,7 @@ import type { CompiledObject } from './compile.ts';
 import type { DateLike } from './datetime.ts';
 import type { Locale } from './locale.ts';
 import type { Numeral } from './numeral.ts';
-import type { TimeZone } from './timezone.ts';
+import type { TimeZone } from './zone.ts';
 
 export interface FormatterPluginOptions {
   /**
@@ -31,12 +31,12 @@ export interface FormatterPluginOptions {
    */
   calendar: 'buddhist' | 'gregory';
 
-  /**
-   * The time zone to use for formatting dates and times.
-   * This can be a specific time zone object or 'UTC' to use Coordinated Universal Time.
-   * If not specified, it defaults to undefined, which means the local time zone will be used.
-   */
-  timeZone: TimeZone | 'UTC' | undefined;
+/**
+  * The time zone to use for formatting dates and times.
+  * This can be a specific time zone object, an IANA time zone name, or 'UTC' to use Coordinated Universal Time.
+  * If not specified, it defaults to undefined, which means the local time zone will be used.
+  */
+  timeZone: TimeZone | string | undefined;
 
   /**
    * The locale to use for formatting dates and times.
@@ -72,12 +72,12 @@ class DefaultFormatter extends FormatterPlugin {
 
   MMMM (d: DateLike, options: FormatterPluginOptions, compiledObj: CompiledObject) {
     const list = options.locale.getMonthList({ style: 'long', compiledObj });
-    return list[d.getMonth()] || '';
+    return list[d.getMonth()] ?? '';
   }
 
   MMM (d: DateLike, options: FormatterPluginOptions, compiledObj: CompiledObject) {
     const list = options.locale.getMonthList({ style: 'short', compiledObj });
-    return list[d.getMonth()] || '';
+    return list[d.getMonth()] ?? '';
   }
 
   MM (d: DateLike) {
@@ -106,22 +106,22 @@ class DefaultFormatter extends FormatterPlugin {
 
   AA (d: DateLike, options: FormatterPluginOptions, compiledObj: CompiledObject) {
     const list = options.locale.getMeridiemList({ style: 'long', compiledObj, case: 'uppercase' });
-    return list[+(d.getHours() > 11)] || '';
+    return list[+(d.getHours() > 11)] ?? '';
   }
 
   A (d: DateLike, options: FormatterPluginOptions, compiledObj: CompiledObject) {
     const list = options.locale.getMeridiemList({ style: 'short', compiledObj, case: 'uppercase' });
-    return list[+(d.getHours() > 11)] || '';
+    return list[+(d.getHours() > 11)] ?? '';
   }
 
   aa (d: DateLike, options: FormatterPluginOptions, compiledObj: CompiledObject) {
     const list = options.locale.getMeridiemList({ style: 'long', compiledObj, case: 'lowercase' });
-    return list[+(d.getHours() > 11)] || '';
+    return list[+(d.getHours() > 11)] ?? '';
   }
 
   a (d: DateLike, options: FormatterPluginOptions, compiledObj: CompiledObject) {
     const list = options.locale.getMeridiemList({ style: 'short', compiledObj, case: 'lowercase' });
-    return list[+(d.getHours() > 11)] || '';
+    return list[+(d.getHours() > 11)] ?? '';
   }
 
   hh (d: DateLike, options: FormatterPluginOptions) {
@@ -162,17 +162,17 @@ class DefaultFormatter extends FormatterPlugin {
 
   dddd (d: DateLike, options: FormatterPluginOptions, compiledObj: CompiledObject) {
     const list = options.locale.getDayOfWeekList({ style: 'long', compiledObj });
-    return list[d.getDay()] || '';
+    return list[d.getDay()] ?? '';
   }
 
   ddd (d: DateLike, options: FormatterPluginOptions, compiledObj: CompiledObject) {
     const list = options.locale.getDayOfWeekList({ style: 'short', compiledObj });
-    return list[d.getDay()] || '';
+    return list[d.getDay()] ?? '';
   }
 
   dd (d: DateLike, options: FormatterPluginOptions, compiledObj: CompiledObject) {
     const list = options.locale.getDayOfWeekList({ style: 'narrow', compiledObj });
-    return list[d.getDay()] || '';
+    return list[d.getDay()] ?? '';
   }
 
   Z (d: DateLike) {
diff --git a/src/parse.ts b/src/parse.ts
@@ -1,4 +1,4 @@
-import { isTimeZone, isUTC, createTimezoneDate } from './timezone.ts';
+import { isTimeZone, isUTC, createTimezoneDate } from './zone.ts';
 import { validatePreparseResult } from './isValid.ts';
 import { preparse } from './preparse.ts';
 import type { CompiledObject } from './compile.ts';
diff --git a/src/parser.ts b/src/parser.ts
@@ -1,7 +1,7 @@
 import type { CompiledObject } from './compile.ts';
 import type { Locale } from './locale.ts';
 import type { Numeral } from './numeral.ts';
-import type { TimeZone } from './timezone.ts';
+import type { TimeZone } from './zone.ts';
 
 type ParserToken = 'Y' | 'M' | 'D' | 'H' | 'A' | 'h' | 'm' | 's' | 'S' | 'Z';
 
diff --git a/src/plugin.ts b/src/plugin.ts
@@ -6,4 +6,4 @@ export type { CompiledObject } from './compile.ts';
 export type { DateLike } from './datetime.ts';
 export type { Locale } from './locale.ts';
 export type { Numeral } from './numeral.ts';
-export type { TimeZone } from './timezone.ts';
+export type { TimeZone } from './zone.ts';
diff --git a/src/plugins/zonename.ts b/src/plugins/zonename.ts
@@ -1,5 +1,6 @@
 import timeZoneNames from '@/zonenames.ts';
 import { FormatterPlugin } from '@/plugin.ts';
+import { isTimeZone } from '@/zone.ts';
 import type { FormatterPluginOptions, DateLike } from '@/plugin.ts';
 
 const getLongTimezoneName = (time: number, zoneName?: string) => {
@@ -16,12 +17,12 @@ const getShortTimezoneName = (time: number, zoneName?: string) => {
 
 class Formatter extends FormatterPlugin {
   z (d: DateLike, options: FormatterPluginOptions) {
-    const zoneName = options.timeZone === 'UTC' ? 'UTC' : options.timeZone?.zone_name;
+    const zoneName = isTimeZone(options.timeZone) ? options.timeZone.zone_name : options.timeZone;
     return getShortTimezoneName(d.getTime(), zoneName);
   }
 
   zz (d: DateLike, options: FormatterPluginOptions) {
-    const zoneName = options.timeZone === 'UTC' ? 'UTC' : options.timeZone?.zone_name;
+    const zoneName = isTimeZone(options.timeZone) ? options.timeZone.zone_name : options.timeZone;
     return getLongTimezoneName(d.getTime(), zoneName);
   }
 }
diff --git a/src/preparse.ts b/src/preparse.ts
@@ -1,5 +1,5 @@
 import { compile } from './compile.ts';
-import { isTimeZone, isUTC } from './timezone.ts';
+import { isTimeZone, isUTC } from './zone.ts';
 import { parser as defaultParser } from './parser.ts';
 import en from './locales/en.ts';
 import latn from './numerals/latn.ts';
diff --git a/src/tzutils.ts b/src/tzutils.ts
@@ -0,0 +1,34 @@
+import { getDateTimeFormat } from './dtf.ts';
+
+export interface TimeZone {
+  zone_name: string;
+  gmt_offset: number[];
+}
+
+export const isTimeZone = (timeZone?: TimeZone | 'UTC'): timeZone is TimeZone => {
+  return typeof timeZone === 'object' && 'zone_name' in timeZone && 'gmt_offset' in timeZone;
+};
+
+export const isUTC = (timeZone?: TimeZone | 'UTC'): timeZone is 'UTC' => {
+  return timeZone === 'UTC';
+};
+
+const getTimezoneOffset = (utcTime: number, timeZone: TimeZone): number => {
+  const utc = getDateTimeFormat('UTC');
+  const tz = getDateTimeFormat(timeZone.zone_name);
+  const offset = timeZone.gmt_offset;
+
+  // Try to find the correct offset by checking the current and previous days.
+  for (let i = 0; i < 2; i++) {
+    const targetString = utc.format(utcTime - i * 86400 * 1000);
+
+    for (let j = 0, len = offset.length; j < len; j++) {
+      if (tz.format(utcTime - (offset[j] + i * 86400) * 1000) === targetString) {
+        return offset[j];
+      }
+    }
+  }
+  return NaN;
+};
+
+export const createTimezoneDate = (utcTime: number, timeZone: TimeZone) => new Date(utcTime - getTimezoneOffset(utcTime, timeZone) * 1000);
diff --git a/src/zone.ts b/src/zone.ts
@@ -0,0 +1,34 @@
+import { getDateTimeFormat } from './dtf.ts';
+
+export interface TimeZone {
+  zone_name: string;
+  gmt_offset: number[];
+}
+
+export const isTimeZone = (timeZone: unknown): timeZone is TimeZone => {
+  return !!timeZone && typeof timeZone === 'object' && 'zone_name' in timeZone && 'gmt_offset' in timeZone;
+};
+
+export const isUTC = (timeZone: unknown): timeZone is 'UTC' => {
+  return typeof timeZone === 'string' && timeZone.toUpperCase() === 'UTC';
+};
+
+const getTimezoneOffset = (utcTime: number, timeZone: TimeZone): number => {
+  const utc = getDateTimeFormat('UTC');
+  const tz = getDateTimeFormat(timeZone.zone_name);
+  const offset = timeZone.gmt_offset;
+
+  // Try to find the correct offset by checking the current and previous days.
+  for (let i = 0; i < 2; i++) {
+    const targetString = utc.format(utcTime - i * 86400 * 1000);
+
+    for (let j = 0, len = offset.length; j < len; j++) {
+      if (tz.format(utcTime - (offset[j] + i * 86400) * 1000) === targetString) {
+        return offset[j];
+      }
+    }
+  }
+  return NaN;
+};
+
+export const createTimezoneDate = (utcTime: number, timeZone: TimeZone) => new Date(utcTime - getTimezoneOffset(utcTime, timeZone) * 1000);
diff --git a/tests/timezones/timezones.spec.ts b/tests/timezones/timezones.spec.ts
@@ -1,7 +1,7 @@
 import { expect, test, describe } from 'vitest';
 import { readdir } from 'node:fs/promises';
 import { join } from 'node:path';
-import type { TimeZone } from '@/timezone.ts';
+import type { TimeZone } from '@/zone.ts';
 
 const importModules = async (path: string) => {
   const items = await readdir(path, { recursive: true, withFileTypes: true });
diff --git a/tools/timezone.ts b/tools/timezone.ts
@@ -1,14 +1,13 @@
 /**
  * @description
- * This script extracts GMT offset values from a CSV file obtained from timezonedb.com,
- * creates subdirectories for each timezone under the src/timezones directory,
- * and outputs timezone data as TypeScript files.
+ * This script generates timezone data files from a CSV file obtained from timezonedb.com,
+ * creates individual timezone files, and an integrated timezone file for easier imports.
  */
 
 import { readFile, mkdir, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import prettier from 'prettier';
-import type { TimeZone } from '@/timezone.ts';
+import type { TimeZone } from '@/zone.ts';
 
 const createTimeZones = (csv: string) => {
   const map = new Map<string, TimeZone>();
@@ -35,7 +34,7 @@ const getPath = (timezone: TimeZone) => {
   const re = /[^/]+$/;
   return {
     dir: join('src', 'timezones', timezone.zone_name.replace(re, '')),
-    name: `${re.exec(timezone.zone_name)?.[0] ?? ''}.ts`
+    name: re.exec(timezone.zone_name)?.[0] ?? ''
   };
 };
 
@@ -47,6 +46,26 @@ const format = (timezone: TimeZone) => {
   return prettier.format(code, { parser: 'typescript', singleQuote: true, trailingComma: 'none' });
 };
 
+const sortMap = (map: Map<string, TimeZone>) => {
+  return Array.from(map.values()).sort((a, b) => getPath(a).name.localeCompare(getPath(b).name));
+};
+
+const formatAll = (map: Map<string, TimeZone>) => {
+  const code = [];
+
+  code.push('import { TimeZone } from \'@/zone.ts\';');
+
+  for (const timezone of sortMap(map)) {
+    const name = getPath(timezone).name.replace(/-/g, '_');
+
+    code.push(`export const ${name}: TimeZone = {
+      zone_name: '${timezone.zone_name}',
+      gmt_offset: ${JSON.stringify(timezone.gmt_offset.sort((a, b) => b - a))}
+    };`);
+  }
+  return prettier.format(code.join('\n\n'), { parser: 'typescript', singleQuote: true, trailingComma: 'none' });
+};
+
 const path = process.argv[2];
 
 if (!path) {
@@ -57,9 +76,13 @@ if (!path) {
 const csv = await readFile(path, 'utf8');
 const map = createTimeZones(csv);
 
+// Generate individual timezone files
 for (const timezone of map.values()) {
   const { dir, name } = getPath(timezone);
 
   await mkdir(dir, { recursive: true });
-  await writeFile(join(dir, name), await format(timezone));
+  await writeFile(join(dir, `${name}.ts`), await format(timezone));
 }
+
+// Generate integrated timezone file
+await writeFile(join('src', 'timezone.ts'), await formatAll(map));

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-import { isTimeZone, isUTC, createTimezoneDate } from './timezone.ts';`
	`1`	`+import { isTimeZone, isUTC, createTimezoneDate } from './zone.ts';`
`2`	`2`	`import { validatePreparseResult } from './isValid.ts';`
`3`	`3`	`import { preparse } from './preparse.ts';`
`4`	`4`	`import type { CompiledObject } from './compile.ts';`
Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,6 @@`
`1`	`1`	`import timeZoneNames from '@/zonenames.ts';`
`2`	`2`	`import { FormatterPlugin } from '@/plugin.ts';`
	`3`	`+import { isTimeZone } from '@/zone.ts';`
`3`	`4`	`import type { FormatterPluginOptions, DateLike } from '@/plugin.ts';`
`4`	`5`
`5`	`6`	`const getLongTimezoneName = (time: number, zoneName?: string) => {`
`@@ -16,12 +17,12 @@ const getShortTimezoneName = (time: number, zoneName?: string) => {`
`16`	`17`
`17`	`18`	`class Formatter extends FormatterPlugin {`
`18`	`19`	`z (d: DateLike, options: FormatterPluginOptions) {`
`19`		`- const zoneName = options.timeZone === 'UTC' ? 'UTC' : options.timeZone?.zone_name;`
	`20`	`+ const zoneName = isTimeZone(options.timeZone) ? options.timeZone.zone_name : options.timeZone;`
`20`	`21`	`return getShortTimezoneName(d.getTime(), zoneName);`
`21`	`22`	`}`
`22`	`23`
`23`	`24`	`zz (d: DateLike, options: FormatterPluginOptions) {`
`24`		`- const zoneName = options.timeZone === 'UTC' ? 'UTC' : options.timeZone?.zone_name;`
	`25`	`+ const zoneName = isTimeZone(options.timeZone) ? options.timeZone.zone_name : options.timeZone;`
`25`	`26`	`return getLongTimezoneName(d.getTime(), zoneName);`
`26`	`27`	`}`
`27`	`28`	`}`