Update documentation for v4.3.0 IANA timezone string support

knowledgecode · knowledgecode · commit 1556efaf14fb · 2026-02-23T18:41:58.000+09:00
- Update type signatures from TimeZone | 'UTC' to TimeZone | string across
  all API docs (addDays, addMonths, addYears, format, parse, subtract, etc.)
- Document IANA timezone string usage for all date manipulation functions
- Add v4.3.0 new features section to migration.md
- Promote Method 3 (IANA string) as the recommended approach in timezones.md
- Fix minor grammar and punctuation issues
diff --git a/docs/api/addDays.md b/docs/api/addDays.md
@@ -14,7 +14,7 @@ addDays(dateObj, days[, timeZone])
 |-----------|------|----------|-------------|
 | `dateObj` | `Date` | Yes | The base Date object |
 | `days` | `number` | Yes | Number of days to add (positive) or subtract (negative) |
-| `timeZone` | `TimeZone \| 'UTC'` | No | Timezone for the calculation |
+| `timeZone` | `TimeZone \| string` | No | Timezone for the calculation |
 
 ### Returns
 
@@ -56,6 +56,20 @@ const futureUTC = addDays(nyDate, 30, 'UTC');
 console.log(futureUTC); // April 9, 2024 05:00 UTC (same time, no DST adjustment)
 ```
 
+### Using IANA Timezone Name Strings
+
+As of v4.3.0, you can use IANA timezone name strings directly instead of importing TimeZone objects:
+
+```typescript
+import { addDays } from 'date-and-time';
+
+const nyDate = new Date('2024-03-10T05:00:00Z'); // March 10, 2024 05:00 UTC
+
+// Using IANA timezone name string (New in v4.3.0)
+const futureNY = addDays(nyDate, 30, 'America/New_York');
+console.log(futureNY); // April 9, 2024 04:00 UTC (EDT, DST adjusted)
+```
+
 ## Use Cases
 
 ### Work Day Calculations
diff --git a/docs/api/addMonths.md b/docs/api/addMonths.md
@@ -14,7 +14,7 @@ addMonths(dateObj, months[, timeZone])
 |-----------|------|----------|-------------|
 | `dateObj` | `Date` | Yes | The base Date object |
 | `months` | `number` | Yes | Number of months to add (positive) or subtract (negative) |
-| `timeZone` | `TimeZone \| 'UTC'` | No | Timezone for the calculation |
+| `timeZone` | `TimeZone \| string` | No | Timezone for the calculation |
 
 ### Returns
 
@@ -56,6 +56,20 @@ const futureUTC = addMonths(nyDate, 6, 'UTC');
 console.log(futureUTC); // September 10, 2024 05:00 UTC (same time, no DST adjustment)
 ```
 
+### Using IANA Timezone Name Strings
+
+As of v4.3.0, you can use IANA timezone name strings directly instead of importing TimeZone objects:
+
+```typescript
+import { addMonths } from 'date-and-time';
+
+const nyDate = new Date('2024-03-10T05:00:00Z'); // March 10, 2024 05:00 UTC
+
+// Using IANA timezone name string (New in v4.3.0)
+const futureNY = addMonths(nyDate, 6, 'America/New_York');
+console.log(futureNY); // September 10, 2024 04:00 UTC (EDT, DST adjusted)
+```
+
 ## Use Cases
 
 ### Payment Due Dates
diff --git a/docs/api/addYears.md b/docs/api/addYears.md
@@ -14,7 +14,7 @@ addYears(dateObj, years[, timeZone])
 |-----------|------|----------|-------------|
 | `dateObj` | `Date` | Yes | The base Date object |
 | `years` | `number` | Yes | Number of years to add (positive) or subtract (negative) |
-| `timeZone` | `TimeZone \| 'UTC'` | No | Timezone for the calculation |
+| `timeZone` | `TimeZone \| string` | No | Timezone for the calculation |
 
 ### Returns
 
@@ -56,6 +56,20 @@ const futureUTC = addYears(nyDate, 1, 'UTC');
 console.log(futureUTC); // March 10, 2025 05:00 UTC (same time, no DST adjustment)
 ```
 
+### Using IANA Timezone Name Strings
+
+As of v4.3.0, you can use IANA timezone name strings directly instead of importing TimeZone objects:
+
+```typescript
+import { addYears } from 'date-and-time';
+
+const nyDate = new Date('2024-03-10T05:00:00Z'); // March 10, 2024 05:00 UTC
+
+// Using IANA timezone name string (New in v4.3.0)
+const futureNY = addYears(nyDate, 1, 'America/New_York');
+console.log(futureNY); // March 10, 2025 04:00 UTC (EST, DST adjusted)
+```
+
 ## Use Cases
 
 ### Age Calculation
diff --git a/docs/api/format.md b/docs/api/format.md
@@ -66,9 +66,9 @@ format(now, 'hh:mm A [GMT]Z');
 | Token | Description | Output Examples |
 |-------|-------------|-----------------|
 | `HH` | Hour in 24-hour format | 23, 08 |
-| `H` | Hour in 24-hour format (no padding) | 23, 8 |
+| `H` | Hour in 24-hour format without zero padding | 23, 8 |
 | `hh` | Hour in 12-hour format | 11, 08 |
-| `h` | Hour in 12-hour format (no padding) | 11, 8 |
+| `h` | Hour in 12-hour format without zero padding | 11, 8 |
 | `mm` | Minutes | 14, 07 |
 | `m` | Minutes without zero padding | 14, 7 |
 | `ss` | Seconds | 05, 10 |
@@ -159,7 +159,7 @@ format(date, 'YYYY-MM-DD HH:mm:ss [JST]', { timeZone: Tokyo });
 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)
+// Using IANA timezone name string
 format(date, 'YYYY-MM-DD HH:mm:ss [EST]', { timeZone: 'America/New_York' });
 // => 2025-08-23 09:30:45 EST
 
diff --git a/docs/api/index.md b/docs/api/index.md
@@ -78,7 +78,7 @@ format(new Date(), 'YYYY年M月D日(ddd) HH:mm', {
 ```typescript
 interface FormatterOptions {
   locale?: Locale;                    // Locale object for localized formatting
-  timeZone?: TimeZone | 'UTC';        // Timezone object or UTC string
+  timeZone?: TimeZone | string;       // Timezone object or IANA timezone name string
   numeral?: Numeral;                  // Numeral system for number formatting
   calendar?: 'gregory' | 'buddhist';  // Calendar system
   hour12?: 'h11' | 'h12';             // 12-hour format type
@@ -91,7 +91,7 @@ interface FormatterOptions {
 ```typescript
 interface ParserOptions {
   locale?: Locale;                    // Locale object for localized parsing
-  timeZone?: TimeZone | 'UTC';        // Timezone object or UTC string
+  timeZone?: TimeZone | string;       // Timezone object or IANA timezone name string
   numeral?: Numeral;                  // Numeral system for number parsing
   calendar?: 'gregory' | 'buddhist';  // Calendar system
   hour12?: 'h11' | 'h12';             // 12-hour format type
diff --git a/docs/api/isLeapYear.md b/docs/api/isLeapYear.md
@@ -1,6 +1,6 @@
 # isLeapYear()
 
-Determine if a given year is a leap year according to the Gregorian calendar rules.
+Determines if a given year is a leap year according to the Gregorian calendar rules.
 
 ## Syntax
 
diff --git a/docs/api/isSameDay.md b/docs/api/isSameDay.md
@@ -1,6 +1,6 @@
 # isSameDay()
 
-Check if two Date objects represent the same calendar day, regardless of time.
+Checks if two Date objects represent the same calendar day, regardless of time.
 
 ## Syntax
 
diff --git a/docs/api/parse.md b/docs/api/parse.md
@@ -67,9 +67,9 @@ parse('2025-08-23 14:30:45', 'YYYY-MM-DD HH:mm:ss');
 | Token | Description | Input Examples |
 |-------|-------------|----------------|
 | `HH` | Hour in 24-hour format | 23, 08 |
-| `H` | Hour in 24-hour format (no padding) | 23, 8 |
+| `H` | Hour in 24-hour format without zero padding | 23, 8 |
 | `hh` | Hour in 12-hour format | 11, 08 |
-| `h` | Hour in 12-hour format (no padding) | 11, 8 |
+| `h` | Hour in 12-hour format without zero padding | 11, 8 |
 | `mm` | Minutes | 14, 07 |
 | `m` | Minutes without zero padding | 14, 7 |
 | `ss` | Seconds | 05, 10 |
@@ -140,10 +140,12 @@ For a complete list of all supported locales with import examples, see [Supporte
 
 ### timeZone
 
-**Type**: `TimeZone | "UTC"`  
+**Type**: `TimeZone | string`
 **Default**: `undefined` (local timezone)
 
-Interprets the parsed date in the specified timezone. **Note**: If the input string contains a timezone offset (e.g., `Z` or `ZZ` tokens), that offset takes precedence and the `timeZone` option is ignored.
+Interprets the parsed date in the specified timezone.
+
+**Note**: If the input string contains a timezone offset (e.g., `Z` or `ZZ` tokens), that offset takes precedence and the `timeZone` option is ignored.
 
 ```typescript
 import { parse } from 'date-and-time';
@@ -158,6 +160,10 @@ parse('2025-08-23 14:30:00', 'YYYY-MM-DD HH:mm:ss', { timeZone: Tokyo });
 parse('2025-08-23 14:30:00', 'YYYY-MM-DD HH:mm:ss', { timeZone: New_York });
 // => Fri Aug 23 2025 14:30:00 GMT-0400
 
+// Parse using an IANA timezone name string (no import needed)
+parse('2025-08-23 14:30:00', 'YYYY-MM-DD HH:mm:ss', { timeZone: 'Asia/Tokyo' });
+// => Fri Aug 23 2025 14:30:00 GMT+0900
+
 // Parse in UTC
 parse('2025-08-23 14:30:00', 'YYYY-MM-DD HH:mm:ss', { timeZone: 'UTC' });
 // => Fri Aug 23 2025 14:30:00 GMT+0000
@@ -170,8 +176,8 @@ 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.
+:::tip
+Like `format()`, `parse()` accepts TimeZone objects, IANA timezone name strings (e.g., `'America/New_York'`), and the `"UTC"` string for the `timeZone` option. If the input string contains a timezone offset token (`Z` or `ZZ`), that offset takes precedence over the `timeZone` option.
 :::
 
 For a complete list of all supported timezones with import examples, see [Supported Timezones](../timezones).
@@ -370,12 +376,12 @@ parse('Jan 1 0000', 'MMM D YYYY');
 
 ### UTC Input Parsing
 
-If the input string doesn't contain a timezone offset and no `timeZone` option is specified, the function treats the input as local timezone. To parse input as UTC, set `timeZone: 'UTC'` in the options.
+If the input string doesn't contain a timezone offset and no `timeZone` option is specified, the function treats the input as the local timezone. To parse input as UTC, set `timeZone: 'UTC'` in the options.
 
 ```typescript
 import { parse } from 'date-and-time';
 
-// Parsed as local timezone
+// Parsed as the local timezone
 parse('14:30:45', 'HH:mm:ss');
 // => Thu Jan 01 1970 14:30:45 GMT-0800
 
diff --git a/docs/api/subtract.md b/docs/api/subtract.md
@@ -1,6 +1,6 @@
 # subtract()
 
-Calculates the difference between two Date objects and return a rich Duration object with multiple time units and formatting options.
+Calculates the difference between two Date objects and returns a rich Duration object with multiple time units and formatting options.
 
 ## Syntax
 
diff --git a/docs/guide/index.md b/docs/guide/index.md
@@ -98,6 +98,8 @@ const localized = format(date, 'YYYY年M月D日', { locale: ja });
 
 // Timezone-aware operations
 const tokyoTime = format(date, 'YYYY-MM-DD HH:mm:ss', { timeZone: Tokyo });
+// Or using IANA timezone name string (New in v4.2.0)
+const tokyoTime2 = format(date, 'YYYY-MM-DD HH:mm:ss', { timeZone: 'Asia/Tokyo' });
 ```
 
 ## Browser and Environment Support
diff --git a/docs/guide/quick-start.md b/docs/guide/quick-start.md
@@ -109,9 +109,13 @@ format(date, 'YYYY-MM-DD HH:mm:ss [EST]', { timeZone: 'America/New_York' });
 format(date, 'YYYY-MM-DD HH:mm:ss [UTC]', { timeZone: 'UTC' });
 // => 2025-08-23 14:30:45 UTC
 
-// Parsing in timezone (TimeZone objects only)
+// Parsing in timezone (TimeZone object)
 parse('2025-08-23 23:30:45', 'YYYY-MM-DD HH:mm:ss', { timeZone: Tokyo });
 // => Fri Aug 23 2025 23:30:45 GMT+0900
+
+// Parsing in timezone (IANA timezone name string)
+parse('2025-08-23 23:30:45', 'YYYY-MM-DD HH:mm:ss', { timeZone: 'Asia/Tokyo' });
+// => Fri Aug 23 2025 23:30:45 GMT+0900
 ```
 
 ### Three Ways to Specify Timezones
@@ -122,7 +126,7 @@ The `format()` function supports three methods for specifying timezones:
 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.
+The `parse()` function supports the same timezone formats as `format()`: TimeZone objects, IANA timezone name strings, and the `"UTC"` string.
 
 For a complete list of all supported timezones with import examples, see [Supported Timezones](../timezones).
 
diff --git a/docs/migration.md b/docs/migration.md
@@ -2,11 +2,11 @@
 
 Version `4.x` has been completely rewritten in TypeScript and some features from `3.x` are no longer compatible. This section explains the changes to each feature and the migration methods.
 
-## Install
+## Installation
 
-Version `4.x` adopts a modern development style and no longer supports older browsers. Module imports are only supported in `ESModules` or `CommonJS` style. Additionally, since functions can now be imported directly, there is a higher possibility of reducing the final module size through bundler tree shaking.
+Version `4.x` adopts a modern development style and no longer supports older browsers. Module imports are only supported in ES Modules or CommonJS style. Additionally, since functions can now be imported directly, it is more likely to reduce the final module size through bundler tree shaking.
 
-- ESModules:
+- ES Modules:
 
 ```typescript
 import { format } from 'date-and-time';
@@ -71,8 +71,6 @@ 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:
@@ -98,6 +96,8 @@ import London from 'date-and-time/timezones/Europe/London';
 import Sydney from 'date-and-time/timezones/Australia/Sydney';
 ```
 
+> **Note**: The TimeZone module import approach (individual imports and consolidated imports) may be deprecated in a future version in favor of IANA timezone name strings. Using IANA timezone name strings is recommended for new projects.
+
 ### 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:
@@ -109,7 +109,7 @@ parse('11:14:05 PM', 'h:mm:ss A', { timeZone: 'UTC' });
 // => Jan 02 1970 23:14:05 GMT+0000
 ```
 
-Additionally, since the `timezone` plugin has been integrated into the main library, the `parseTZ` 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 `parseTZ` function is now obsolete. Timezones can now be specified as TimeZone module imports, IANA timezone name strings, or the `"UTC"` string.
 
 ```typescript
 import { parse } from 'date-and-time';
@@ -123,6 +123,21 @@ parse(
 // => Jan 02 2015 23:14:05 GMT+0100
 ```
 
+#### New in v4.3.0: Enhanced Timezone Support
+
+The `parse()` function now also supports IANA timezone name strings (e.g., `'America/New_York'`), in addition to TimeZone objects and the `"UTC"` string.
+
+```typescript
+import { parse } from 'date-and-time';
+import fr from 'date-and-time/locales/fr';
+
+parse(
+  '02 janv. 2015, 11:14:05 PM', 'DD MMM YYYY, h:mm:ss A',
+  { timeZone: 'Europe/Paris', locale: fr }
+);
+// => Jan 02 2015 23:14:05 GMT+0100
+```
+
 ### preparse
 
 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:
@@ -184,6 +199,25 @@ transform(
 // => 3/8/2020 10:05 AM
 ```
 
+#### New in v4.3.0: Enhanced Timezone Support
+
+The `transform()` function now supports IANA timezone name strings for both `parserOptions` and `formatterOptions`. Using IANA timezone name strings is recommended over importing TimeZone modules.
+
+```typescript
+import { transform } from 'date-and-time';
+
+// Convert 24-hour format to 12-hour format
+transform('13:05', 'HH:mm', 'hh:mm A', { timeZone: 'UTC' }, { timeZone: 'UTC' });
+// => 01:05 PM
+
+// Convert East Coast time to West Coast time using IANA timezone name strings
+transform(
+  '3/8/2020 1:05 PM', 'D/M/YYYY h:mm A', 'D/M/YYYY h:mm A',
+  { timeZone: 'America/New_York' }, { timeZone: 'America/Los_Angeles' }
+);
+// => 3/8/2020 10:05 AM
+```
+
 ### addYears
 
 The third argument has been changed from `boolean` to `TimeZone | UTC`. If you previously set the third argument to `true` to calculate in UTC timezone, you can achieve the same output as follows:
@@ -198,7 +232,7 @@ addYears(now, 1, 'UTC');
 // => Mar 11 2025 01:00:00 GMT+0000
 ```
 
-Additionally, since the `timezone` plugin has been integrated into the main library, the `addYearsTZ` 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 `addYearsTZ` function is now obsolete. Timezones are now imported as modules rather than using `IANA timezone names` (except for the UTC timezone).
 
 ```typescript
 import Los_Angeles from 'date-and-time/timezones/America/Los_Angeles';
@@ -210,6 +244,20 @@ addYears(now, 1, Los_Angeles);
 // => Mar 11 2025 01:00:00 GMT-07:00
 ```
 
+#### New in v4.3.0: Enhanced Timezone Support
+
+The `addYears()`, `addMonths()`, and `addDays()` functions now support IANA timezone name strings. Using IANA timezone name strings is recommended over importing TimeZone modules.
+
+```typescript
+import { addYears } from 'date-and-time';
+
+const now = new Date(2024, 2, 11, 1);
+// => Mar 11 2024 01:00:00 GMT-07:00
+
+addYears(now, 1, 'America/Los_Angeles');
+// => Mar 11 2025 01:00:00 GMT-07:00
+```
+
 ### addMonths
 
 The changes are the same as for the `addYears` function.
@@ -238,7 +286,7 @@ subtract(yesterday, today).toMilliseconds().value; // => 86400000
 
 ### timeSpan
 
-The `timespan` plugin is now obsolete as it has been integrated into the main library's `subtract` function. Please note that the argument order of the `subtract` function has changed. You can achieve the same output as before as follows:
+The `timeSpan` plugin is now obsolete as it has been integrated into the main library's `subtract` function. Please note that the argument order of the `subtract` function has changed. You can achieve the same output as before as follows:
 
 ```typescript
 import { subtract } from 'date-and-time';
@@ -275,3 +323,5 @@ The following plugins are now obsolete as they have been integrated into the mai
 - `meridiem`
 - `timespan`
 - `timezone`
+
+The custom plugin feature that existed up to 3.x is not yet supported at this time.
diff --git a/docs/plugins.md b/docs/plugins.md
diff --git a/docs/timezones.md b/docs/timezones.md
