A versatile timezone management package with zero dependencies, designed for CommonJS, ES Module (ESM), JavaScript, and TypeScript projects. It offers a range of features, including timezone listing, retrieving labels and values, region-based filtering, and converting between UTC and other timezones.
- ⚙️ Installation
- 📖 Usage
- 📦 Importing the Package
- 🌍 Get All Timezones (Label-Value Pair)
- 🕑 et All Timezone Values (Without Label)
- 🏷️ Get All Timezone Labels (Without Value)
- 🌐 Get Timezones by Region
- 🔖 Get Timezone Label from Value
- 🎯 Get Timezone Value from Label
- 🌏 Get List of Regions
- ⏰ Convert UTC Time to Specific Timezone
- 🔄 Convert Datetime From One Timezone to Another
- 🌐🕓 Convert any Date-Time String to UTC Format
- 🕰️ Get the Current Date-Time in a Specific Timezone
- ➕➖ Add or Subtract Time (hours, minutes, or days) From a Date
- 🕒➡️🕕 Get the Time Difference Between Two Timezones
- 📋 Methods Overview
- 📜 License
- 🤝 Contributing
Install the package using npm:
npm install timezone-utility
// For ES Module (ESM)
import { TimeZone } from "timezone-utility";
// For CommonJS
const { TimeZone } = require("timezone-utility");
Retrieve a list of all available timezones with both label and value.
const allTimezones = TimeZone.list();
console.log(allTimezones);
Output Example:
[
{ "label": "(UTC+00:00) Africa/Abidjan", "value": "Africa/Abidjan" },
{ "label": "(UTC-05:00) America/New_York", "value": "America/New_York" },
...
]
Get a list of timezone values (useful for APIs or forms where only the value is needed).
const timezoneValues = TimeZone.listWithoutLabel();
console.log(timezoneValues);
Output Example:
[
"Africa/Abidjan",
"America/New_York",
...
]
Retrieve a list of timezone labels.
const timezoneLabels = TimeZone.listWithoutValue();
console.log(timezoneLabels);
Output Example:
[
"(UTC+00:00) Africa/Abidjan",
"(UTC-05:00) America/New_York",
...
]
Retrieve timezones for a specific region (e.g., America, Europe, Asia).
const americanTimezones = TimeZone.listByRegion("America");
console.log(americanTimezones);
Output Example:
[
{ "label": "(UTC-05:00) America/New_York", "value": "America/New_York" },
{ "label": "(UTC-06:00) America/Chicago", "value": "America/Chicago" },
...
]
Parameters:
region: string
: The region to filter by (e.g., "America", "Europe").
Retrieve the label (human-readable name) for a given timezone value.
const labelFromValue = TimeZone.getLabelFromValue("America/New_York");
console.log(labelFromValue);
Output Example:
"(UTC-05:00) America/New_York"
Parameters:
value: string
: The timezone value to convert to a label.
Retrieve the timezone value from a label.
const valueFromLabel = TimeZone.getValueFromLabel("(UTC-05:00) America/New_York");
console.log(valueFromLabel);
Output Example:
"America/New_York"
Parameters:
label: string
: The timezone label to convert to a value.
Retrieve a list of all available regions.
const regions = TimeZone.getRegions();
console.log(regions);
Output Example:
[
"Africa",
"America",
"Asia",
"Atlantic",
"Australia",
"Europe",
"Indian",
"Pacific"
]
Convert a UTC/GMT time to a specific timezone and format it in either 12-hour or 24-hour format. You can also specify a custom date separator. By default, the function uses a 24-hour format (is24Hour = true
) and the date separator is /
.
const utcDate = "2024-10-15T14:00:00Z";
const convertedTime = TimeZone.convertUTCToTimeZone(utcDate, 'America/New_York', {is24Hour: false, dateSeparator: '/', timeSeparator: ':'});
console.log(convertedTime);
Output Example:
"10/15/2024, 10:00:00 AM"
Parameters:
dateTimeString: string
: The date-time string to convert.toTimeZone: TimeZoneNames
: The target timezone.options: ConvertOptions (optional)
: Object containing optional formatting options:is24Hour: boolean
: Whether to use 24-hour format (defaulttrue
).dateSeparator: string
: The date separator (default/
).timeSeparator: string
: The time separator (default:
).
Convert a datetime from one timezone to another and format it in either 12-hour or 24-hour format. You can also specify a custom date separator. By default, the function uses a 24-hour format (is24Hour = true
) and the date separator is /
.
const originalDate = "2024-10-15T14:00:00Z";
const convertedTime = TimeZone.convertBetweenTimeZones(originalDate, 'America/New_York', 'Asia/Dhaka', {is24Hour: false, dateSeparator: '/', timeSeparator: ':'});
console.log(convertedTime);
Output Example:
"10/15/2024, 12:00:00"
Parameters:
dateTimeString: string
: The date-time string to convert.fromTimeZone: TimeZoneNames
: The source timezone.toTimeZone: TimeZoneNames
: The target timezone.options: ConvertOptions (optional)
: Object containing optional formatting options:is24Hour: boolean
: Whether to use 24-hour format (defaulttrue
).dateSeparator: string
: The date separator (default/
).timeSeparator: string
: The time separator (default:
).
Converts any date-time string into a UTC format (ISO 8601). This method also validates the input and provides a clear error message if the date is invalid.
const utcDate1 = TimeZone.convertToUTC('October 15, 2024 12:34:56');
console.log(utcDate1);
const utcDate2 = TimeZone.convertToUTC('2024-10-15T12:34:56');
console.log(utcDate2);
Output Example:
"2024-10-15T12:34:56.000Z"
"2024-10-15T12:34:56.000Z"
Parameters:
dateTimeString: string
: The date-time string to convert to UTC.format: string
: The format of the date-time string (e.g., 'MM-dd-yyyy HH:mm:ss AM/PM', 'yyyy-MM-ddTHH:mm:ss').
Returns the current date and time in the specified timezone. The method allows formatting options such as 24-hour or 12-hour format and custom date and time separators.
const currentTimeInNY = TimeZone.getCurrentTimeInTimeZone('America/New_York', { is24Hour: false, dateSeparator: '-', timeSeparator: ':' });
console.log(currentTimeInNY);
Output Example:
"10-15-2024 08:34:56 AM"
Parameters:
targetTimeZone: TimeZoneNames
: The target timezone in which you want the current time.options: ConvertOptions (optional)
: Object containing optional formatting options:is24Hour: boolean
: Whether to use 24-hour format (defaulttrue
).dateSeparator: string
: The date separator (default/
).timeSeparator: string
: The time separator (default:
).
Adds or subtracts time (hours, minutes, or days) to a given date and returns the resulting date in UTC format.
const newDate = TimeZone.addTimeToDate('2024-10-15T12:00:00', 3, 'hours');
console.log(newDate);
Output Example:
"2024-10-15T15:00:00.000Z"
Parameters:
date: Date | string
: The base date (as aDate
object or string) from which to add/subtract time.amount: number
: The amount of time to add (positive) or subtract (negative).unit: 'hours' | 'minutes' | 'days'
: The unit of time to add or subtract.
Calculates the time difference between two timezones in hours and minutes for a specific date.
const timeDiff = TimeZone.getTimeDifferenceBetweenTimeZones('2024-10-15T12:00:00', 'America/New_York', 'Asia/Tokyo');
console.log(timeDiff);
Output Example:
"+13 hours 0 minutes"
Parameters:
date: string
: The base date-time string to calculate the difference from.fromTimeZone: TimeZoneNames
: The source timezone.toTimeZone: TimeZoneNames
: The target timezone.
Method Name | Description |
---|---|
TimeZone.list() | Get a list of all timezones (label-value pairs). |
TimeZone.listWithoutLabel() | Get a list of all timezone values. |
TimeZone.listWithoutValue() | Get a list of all timezone labels. |
TimeZone.listByRegion(region) | Get timezones by a specific region (e.g., "America", "Europe"). |
TimeZone.getLabelFromValue(value) | Get the timezone label for a specific value. |
TimeZone.getValueFromLabel(label) | Get the timezone value for a specific label. |
TimeZone.getRegions() | Get a list of all regions. |
TimeZone.convertUTCToTimeZone() | Convert a UTC date/time string to a specific timezone, with support for 12-hour or 24-hour format (default 24-hour) and customizable date and time separators. |
TimeZone.convertBetweenTimeZones() | Convert a date from one timezone to another with support for 12-hour or 24-hour format (default 24-hour) and customizable date and time separators. |
TimeZone.convertToUTC() | Convert any date-time string into a UTC format (ISO 8601). |
TimeZone.getCurrentTimeInTimeZone() | Get the current date and time in a specific timezone, with options for 12-hour or 24-hour format (default 24-hour) and customizable date and time separators. |
TimeZone.addTimeToDate() | Add or subtract time (hours, minutes, or days) from a given date and return the result in UTC format. |
TimeZone.getTimeDifferenceBetweenTimeZones() | Get the time difference between two timezones in hours and minutes for a specific date. |
This project is licensed under the MIT License.
We welcome contributions to this package! If you find any issues or have suggestions for improvements, please open an issue or submit a pull request.
- The
README.md
provides clear instructions for installation, usage, and examples for each method. - Each method is documented with a brief description, input/output, and examples.
- The
convertUTCToTimeZone
method now includes an option for the 12-hour/24-hour format, as requested.