Merge pull request #116 from knowledgecode/develop

v4.2.0: Add timezone features and improve code organization

Author: knowledgecode

docs/api/format.md

@@ -134,24 +134,33 @@ For a complete list of all supported locales with import examples, see [Supporte
 
 ### timeZone
 
-**Type**: `TimeZone | "UTC"`  
+**Type**: `TimeZone | string`
 **Default**: `undefined` (local timezone)
 
-Converts the date to the specified timezone before formatting.
+Converts the date to the specified timezone before formatting. You can specify a timezone in three ways:
 
 ```typescript
 import { format } from 'date-and-time';
+
+// Method 1: Individual timezone import
 import Tokyo from 'date-and-time/timezones/Asia/Tokyo';
 import New_York from 'date-and-time/timezones/America/New_York';
 
+// Method 2: Consolidated timezone import
+import { Tokyo as TokyoTZ, New_York as NY } from 'date-and-time/timezone';
+
 const date = new Date();
 
-// Format in Tokyo timezone
+// Using TimeZone object (individual import)
 format(date, 'YYYY-MM-DD HH:mm:ss [JST]', { timeZone: Tokyo });
 // => 2025-08-23 23:30:45 JST
 
-// Format in New York timezone  
-format(date, 'YYYY-MM-DD HH:mm:ss [EST]', { timeZone: New_York });
+// Using TimeZone object (consolidated import)
+format(date, 'YYYY-MM-DD HH:mm:ss [EST]', { timeZone: NY });
+// => 2025-08-23 09:30:45 EST
+
+// Using IANA timezone name string (format only)
+format(date, 'YYYY-MM-DD HH:mm:ss [EST]', { timeZone: 'America/New_York' });
 // => 2025-08-23 09:30:45 EST
 
 // Format in UTC
@@ -314,16 +323,35 @@ format(date, '\\[YYYY-MM-DD HH:mm:ss\\]');
 ```typescript
 import { format } from 'date-and-time';
 import ja from 'date-and-time/locales/ja';
+
+// Method 1: Individual timezone import
 import Tokyo from 'date-and-time/timezones/Asia/Tokyo';
 
+// Method 2: Consolidated timezone import (alternative)
+import { Tokyo as TokyoTZ } from 'date-and-time/timezone';
+
 const date = new Date();
 
-// Japanese with timezone
+// Japanese with timezone (using individual import)
 format(date, 'YYYY年MMMM月D日dddd Ah:mm:ss [GMT]Z', {
   timeZone: Tokyo,
   locale: ja
 });
 // => 2025年8月23日土曜日 午後11:30:45 GMT+0900
+
+// Or using consolidated import
+format(date, 'YYYY年MMMM月D日dddd Ah:mm:ss [GMT]Z', {
+  timeZone: TokyoTZ,
+  locale: ja
+});
+// => 2025年8月23日土曜日 午後11:30:45 GMT+0900
+
+// Or using IANA timezone name string
+format(date, 'YYYY年MMMM月D日dddd Ah:mm:ss [GMT]Z', {
+  timeZone: 'Asia/Tokyo',
+  locale: ja
+});
+// => 2025年8月23日土曜日 午後11:30:45 GMT+0900
 ```
 
 ### Business and Technical Formats
@@ -342,7 +370,7 @@ format(date, 'ddd, DD MMM YYYY HH:mm:ss ZZ');
 // => Sat, 23 Aug 2025 14:30:45 +09:00
 
 // Log timestamp
-format(date, '[YYYY-MM-DD HH:mm:ss.SSS]');
+format(date, '\\[YYYY-MM-DD HH:mm:ss.SSS]\\');
 // => [2025-08-23 14:30:45.123]
 
 // File naming

docs/api/parse.md

@@ -170,6 +170,10 @@ parse('2025-08-23T14:30:00 +05:00', 'YYYY-MM-DD[T]HH:mm:ss ZZ', { timeZone: New_
 // => Fri Aug 23 2025 14:30:00 GMT+0500 (New_York timeZone is ignored)
 ```
 
+:::warning Important Difference from format()
+The `parse()` function only accepts TimeZone objects and the "UTC" string for the `timeZone` option. Unlike `format()`, which supports both TimeZone objects and IANA timezone name strings, `parse()` does not support string type timezone names.
+:::
+
 For a complete list of all supported timezones with import examples, see [Supported Timezones](../timezones).
 
 ### numeral

docs/guide/quick-start.md

@@ -83,23 +83,47 @@ For a complete list of all supported locales with import examples, see [Supporte
 
 ```typescript
 import { format, parse } from 'date-and-time';
+
+// Method 1: Individual timezone imports
 import Tokyo from 'date-and-time/timezones/Asia/Tokyo';
 import New_York from 'date-and-time/timezones/America/New_York';
 
+// Method 2: Consolidated timezone imports (alternative)
+import { Los_Angeles, London } from 'date-and-time/timezone';
+
 const date = new Date();
 
-// Format in different timezones
+// Using TimeZone objects (Method 1 - individual import)
 format(date, 'YYYY-MM-DD HH:mm:ss [JST]', { timeZone: Tokyo });
 // => 2025-08-23 23:30:45 JST
 
-format(date, 'YYYY-MM-DD HH:mm:ss [EST]', { timeZone: New_York });
+// Using TimeZone objects (Method 2 - consolidated import)
+format(date, 'YYYY-MM-DD HH:mm:ss [PST]', { timeZone: Los_Angeles });
+// => 2025-08-23 06:30:45 PST
+
+// Using IANA timezone name strings (simplest approach)
+format(date, 'YYYY-MM-DD HH:mm:ss [EST]', { timeZone: 'America/New_York' });
 // => 2025-08-23 09:30:45 EST
 
 // UTC formatting
 format(date, 'YYYY-MM-DD HH:mm:ss [UTC]', { timeZone: 'UTC' });
 // => 2025-08-23 14:30:45 UTC
+
+// Parsing in timezone (TimeZone objects only)
+parse('2025-08-23 23:30:45', 'YYYY-MM-DD HH:mm:ss', { timeZone: Tokyo });
+// => Fri Aug 23 2025 23:30:45 GMT+0900
 ```
 
+### Three Ways to Specify Timezones
+
+The `format()` function supports three methods for specifying timezones:
+
+1. **TimeZone objects via individual imports** - Type-safe but requires multiple import statements
+2. **TimeZone objects via consolidated imports** - Type-safe with better code organization
+3. **IANA timezone name strings** - Simplest approach, no imports needed for timezone modules
+
+The `parse()` function only supports TimeZone objects and the "UTC" string for timezone specification.
+
 For a complete list of all supported timezones with import examples, see [Supported Timezones](../timezones).
 
 ## Date Arithmetic

docs/index.md

@@ -50,7 +50,7 @@ features:
 ```typescript
 import { format, parse, addDays } from 'date-and-time';
 import ja from 'date-and-time/locales/ja';
-import Tokyo from 'date-and-time/timezones/Asia/Tokyo';
+import { Tokyo } from 'date-and-time/timezone';
 
 const now = new Date();
 
@@ -62,10 +62,14 @@ format(now, 'YYYY/MM/DD HH:mm:ss');
 format(now, 'YYYY年M月D日(ddd)', { locale: ja });
 // => 2025年8月23日(金)
 
-// Timezone-aware formatting
+// Timezone-aware formatting (using TimeZone object)
 format(now, 'YYYY-MM-DD HH:mm:ss [JST]', { timeZone: Tokyo });
 // => 2025-08-23 23:30:45 JST
 
+// Timezone-aware formatting (using IANA timezone name string)
+format(now, 'YYYY-MM-DD HH:mm:ss [EST]', { timeZone: 'America/New_York' });
+// => 2025-08-23 09:30:45 EST
+
 // Parsing
 const date = parse('2025/08/23 14:30:45', 'YYYY/MM/DD HH:mm:ss');
 console.log(date)

docs/migration.md

@@ -37,7 +37,7 @@ format(new Date(), 'ddd, MMM DD YYYY hh:mm A [GMT]Z', { timeZone: 'UTC' });
 // => Fri, Jan 02 2015 07:14 AM GMT+0000
 ```
 
-Additionally, since the `timezone` plugin has been integrated into the main library, the `formatTZ` function is now obsolete. Timezones are now imported as modules rather than using `IANA time zone names` (except for UTC timezone).
+Additionally, since the `timezone` plugin has been integrated into the main library, the `formatTZ` function is now obsolete. In v4.0/4.1, timezones must be imported as TimeZone objects from timezone modules. IANA timezone name strings are not supported in this version (except for UTC timezone).
 
 ```typescript
 import { format } from 'date-and-time';
@@ -47,6 +47,57 @@ format(now, 'dddd, MMMM D, YYYY [at] H:mm:ss.SSS [GMT]ZZ', { timeZone: New_York
 // => Wednesday, July 23, 2025 at 3:28:27.443 GMT-04:00
 ```
 
+#### New in v4.2.0: Enhanced Timezone Support
+
+In addition to TimeZone objects, the `format()` function now supports specifying timezones using IANA timezone name strings. This provides flexibility in how you work with timezones:
+
+```typescript
+import { format } from 'date-and-time';
+
+const now = new Date();
+
+// Using IANA timezone name string (simplest)
+format(now, 'YYYY-MM-DD HH:mm:ss [EST]', { timeZone: 'America/New_York' });
+// => 2025-08-23 09:30:45 EST
+
+// Using TimeZone object (recommended for type safety)
+import New_York from 'date-and-time/timezones/America/New_York';
+format(now, 'YYYY-MM-DD HH:mm:ss [EST]', { timeZone: New_York });
+// => 2025-08-23 09:30:45 EST
+
+// Using consolidated import (recommended for multiple timezones)
+import { New_York as NY } from 'date-and-time/timezone';
+format(now, 'YYYY-MM-DD HH:mm:ss [EST]', { timeZone: NY });
+// => 2025-08-23 09:30:45 EST
+```
+
+**Note**: The `parse()` function does not support string type timezone names. Only TimeZone objects and the "UTC" string are supported for parsing.
+
+##### Consolidated Import
+
+For better code organization when working with multiple timezones, you can import all timezones from a single `date-and-time/timezone` module:
+
+```typescript
+// Consolidated import (recommended for multiple timezones)
+import { Tokyo, New_York, London, Sydney } from 'date-and-time/timezone';
+
+const now = new Date();
+
+format(now, 'YYYY-MM-DD HH:mm', { timeZone: Tokyo });    // JST
+format(now, 'YYYY-MM-DD HH:mm', { timeZone: New_York }); // EST/EDT
+format(now, 'YYYY-MM-DD HH:mm', { timeZone: London });   // GMT/BST
+format(now, 'YYYY-MM-DD HH:mm', { timeZone: Sydney });   // AEDT/AEST
+```
+
+Alternatively, you can still import individual timezone modules directly:
+
+```typescript
+import Tokyo from 'date-and-time/timezones/Asia/Tokyo';
+import New_York from 'date-and-time/timezones/America/New_York';
+import London from 'date-and-time/timezones/Europe/London';
+import Sydney from 'date-and-time/timezones/Australia/Sydney';
+```
+
 ### parse
 
 The third argument has been changed from `boolean` to `ParserOptions`. With `ParserOptions`, you can now specify timezone and locale settings. If you previously set the third argument to `true` to parse input in UTC timezone, you can achieve the same output as follows:

docs/timezones.md

@@ -1,5 +1,67 @@
 # Supported Timezones
 
+## Import Methods
+
+There are three ways to import and use timezones with the date-and-time library:
+
+### Method 1: Individual Import
+
+Import each timezone you need directly from its module path. This approach is useful when you only need a few specific timezones.
+
+```typescript
+import { format } from 'date-and-time';
+import Tokyo from 'date-and-time/timezones/Asia/Tokyo';
+import New_York from 'date-and-time/timezones/America/New_York';
+
+const date = new Date();
+
+format(date, 'YYYY-MM-DD HH:mm:ss', { timeZone: Tokyo });
+// => 2025-08-23 23:30:45
+
+format(date, 'YYYY-MM-DD HH:mm:ss', { timeZone: New_York });
+// => 2025-08-23 09:30:45
+```
+
+### Method 2: Consolidated Import
+
+Import multiple timezones from a single module using named imports. This approach is recommended when working with multiple timezones as it provides better code organization.
+
+```typescript
+import { format } from 'date-and-time';
+import { Tokyo, New_York, London, Sydney } from 'date-and-time/timezone';
+
+const date = new Date();
+
+format(date, 'YYYY-MM-DD HH:mm:ss', { timeZone: Tokyo });    // JST
+format(date, 'YYYY-MM-DD HH:mm:ss', { timeZone: New_York }); // EST/EDT
+format(date, 'YYYY-MM-DD HH:mm:ss', { timeZone: London });   // GMT/BST
+format(date, 'YYYY-MM-DD HH:mm:ss', { timeZone: Sydney });   // AEDT/AEST
+```
+
+Both Method 1 and Method 2 provide the same functionality - they differ only in code organization.
+
+### Method 3: IANA Timezone Name String
+
+Functions that accept `FormatterOptions` (such as `format()` and `transform()`) allow you to specify timezones using IANA timezone name strings directly. This is the simplest approach.
+
+```typescript
+import { format } from 'date-and-time';
+
+const date = new Date();
+
+// Using IANA timezone name strings
+format(date, 'YYYY-MM-DD HH:mm:ss', { timeZone: 'Asia/Tokyo' });
+// => 2025-08-23 23:30:45
+
+format(date, 'YYYY-MM-DD HH:mm:ss', { timeZone: 'America/New_York' });
+// => 2025-08-23 09:30:45
+
+format(date, 'YYYY-MM-DD HH:mm:ss', { timeZone: 'Europe/London' });
+// => 2025-08-23 14:30:45
+```
+
+**Important Note**: The `parse()` function does not support string type timezone names because it uses `ParserOptions` instead of `FormatterOptions`. Only TimeZone objects and the "UTC" string are supported for parsing.
+
 ## Regions
 
 1. [Africa](#africa)