timezone-utility

Timezone Utilities

A comprehensive TypeScript utility for managing time zones. This package provides functionalities to list time zones, retrieve labels and values, filter by region, and convert between UTC and various time zones.

Table of Contents

• Installation
• Usage
  • Importing the Package
  • Get All Timezones (Label-Value Pair)
  • Get 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
• Options
• Methods Overview
• License
• Contributing

Installation

Install the package using npm:

npm install timezone-utilities

Usage

Importing the Package

import TimeZone from "timezone-utilities";

1 Get All Timezones (Label-Value Pair)

Retrieve a list of all available timezones with both label and value.

const allTimezones = TimeZone.list();
console.log(allTimezones);

Output Example:

[
  { "label": "Africa/Abidjan", "value": "Africa/Abidjan" },
  { "label": "America/New_York", "value": "America/New_York" },
  ...
]

2. Get All Timezone Values (Without Label)

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",
  ...
]

3. Get All Timezone Labels (Without Value)

Retrieve a list of timezone labels.

const timezoneLabels = TimeZone.listWithoutValue();
console.log(timezoneLabels);

Output Example:

[
  "Africa/Abidjan",
  "America/New_York",
  ...
]

4. Get Timezones by Region

Retrieve timezones for a specific region (e.g., America, Europe, Asia).

const americanTimezones = TimeZone.listByRegion("America");
console.log(americanTimezones);

Output Example:

[
  { "label": "America/New_York", "value": "America/New_York" },
  { "label": "America/Chicago", "value": "America/Chicago" },
  ...
]

5. Get Timezone Label from Value

Retrieve the label (human-readable name) for a given timezone value.

const labelFromValue = TimeZone.getLabelFromValue("America/New_York");
console.log(labelFromValue);

Output Example:

"Eastern Standard Time"

6. Get Timezone Value from Label

Retrieve the timezone value from a label.

const valueFromLabel = TimeZone.getValueFromLabel("Eastern Standard Time");
console.log(valueFromLabel);

Output Example:

"America/New_York"

7. Get List of Regions

Retrieve a list of all available regions.

const regions = TimeZone.getRegions();
console.log(regions);

Output Example:

[
  "Africa",
  "America",
  "Asia",
  "Atlantic",
  "Australia",
  "Europe",
  "Indian",
  "Pacific"
]

8. Convert UTC Time to Specific Timezone

Convert a UTC/GMT time to a specific timezone and format it in 12-hour or 24-hour format.

const utcDate = "2024-10-15T14:00:00Z";
const convertedTime = TimeZone.convertUTCToTimeZone(utcDate, 'America/New_York', { hour12: false });
console.log(convertedTime);

Output Example:

"10/15/2024, 10:00:00"

9. Convert Datetime From One Timezone to Another

Convert a UTC/GMT time to a specific timezone and format it in 24-hour format.

const originalDate = "2024-10-15T14:00:00Z";
const convertedTime = TimeZone.convertBetweenTimeZones(originalDate, 'America/New_York', 'Asia/Dhaka', { hour12: true });
console.log(convertedTime); 

Output Example:

"10/15/2024, 12:00:00 AM"

Options

For time conversion, you can pass an options object:

• hour12: boolean – Specify whether to return the time in 12-hour or 24-hour format. Default is 24-hour.

TimeZone.convertUTCToTimeZone(utcDate, 'America/New_York', { hour12: true });

Methods Overview

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 and 24-hour formats.
TimeZone.convertBetweenTimeZones()	Convert a date from one timezone to another and return the result in the target timezone format.

License

This project is licensed under the MIT License.

Contributing

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.

Key Points:

• 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.