timezone-utility

Timezone Utility

A versatile timezone management package 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.

Table of Contents

• Installation
• Usage
• Methods Overview
• Methods
  • isISODateTime
  • isValidTimeZone
  • convertDateTime
  • list
  • listWithOnlyValue
  • listWithOnlyLabel
  • listByRegion
  • listByCountry
  • getDetailsUsingTimeZoneValue
  • getRegions
  • convertUTCToTimeZone
  • convertToUTC
  • convertBetweenTimeZones
  • getCurrentTimeInTimeZone
  • getTimeDifferenceBetweenTimeZones
  • convertUTCToLocal
  • formatDateTime
  • getLocalTimeZone
• TypeScript Support
• Error Handling
• License
• Contributing

Installation

Install the package using npm:

npm install timezone-utility

Usage

// For ES Module (ESM)
import { TimeZone } from "timezone-utility";

// For CommonJS
const { TimeZone } = require("timezone-utility");

Methods Overview

Method Name	Description
isISODateTime	Validates if a string is a valid ISO date-time format.
isValidTimeZone	Validates if a given string is a valid time zone.
convertDateTime	Converts a date-time from one time zone to another.
list	Returns a list of all available time zones.
listWithOnlyValue	Returns a list of all time zone values.
listWithOnlyLabel	Returns a list of all time zone labels.
listByRegion	Lists time zones for a specific region.
listByCountry	Lists time zones for a specific country.
getDetailsUsingTimeZoneValue	Gets the details for a given time zone value.
getRegions	Returns a list of all available regions.
convertUTCToTimeZone	Converts a UTC date to a specified time zone.
convertToUTC	Converts a date-time from a specified time zone to UTC.
convertBetweenTimeZones	Converts a date-time between two specified time zones.
getCurrentTimeInTimeZone	Gets the current time in a specified time zone.
getTimeDifferenceBetweenTimeZones	Calculates the time difference between two time zones.
convertUTCToLocal	Converts UTC date-time to Local date-time.
formatDateTime	Format an ISO date-time string using a custom format pattern.
getLocalTimeZone	Get the user's local timezone.

Methods

isISODateTime

Validates if a string is a valid ISO date-time format.

const isValid1 = TimeZone.isISODateTime('2023-10-10T10:00:00');
console.log(isValid1); // true

const isValid2 = TimeZone.isISODateTime('invalid-date');
console.log(isValid2); // false

Parameters:

• dateTime: string: The date-time string to validate.

Returns:

• boolean: True if the string is a valid ISO date-time, false otherwise.

isValidTimeZone

Validates if a given string is a valid time zone.

const isValid1 = TimeZone.isValidTimeZone('UTC');
console.log(isValid1); // true

const isValid2 = TimeZone.isValidTimeZone('Invalid/Zone');
console.log(isValid2); // false

Parameters:

• timeZone: string: The time zone string to validate.

Returns:

• boolean: True if the time zone is valid, false otherwise.

convertDateTime

Converts a date-time from one time zone to another.

// Using string input
const converted1 = TimeZone.convertDateTime(
  '2023-10-10T10:00:00', 
  'UTC', 
  'America/New_York', 
  true
);
console.log(converted1); // "2023-10-10T06:00:00"

// Using Date object input
const dateTime = new Date('2023-10-10T10:00:00Z');
const converted2 = TimeZone.convertDateTime(
  dateTime, 
  'UTC', 
  'America/New_York', 
  true
);
console.log(converted2); // "2023-10-10T06:00:00"

Parameters:

• dateTime: Date | string: The date-time to convert.
• sourceTimeZone: string: The source time zone.
• targetTimeZone: string: The target time zone.
• returnISO: boolean: Whether to return ISO format (default: true).

Returns:

• string | Error: Converted date-time string or Error if conversion fails.

list

Returns a list of all available time zones.

const timeZones = TimeZone.list();
console.log(timeZones);
/* OUTPUT:
[
  {
    "label": "(UTC-05:00) America/New_York",
    "value": "America/New_York",
    "country": "United States",
    "phoneCode": "+1",
    "utcOffset": "-05:00"
  },
  ...
]
*/

Returns:

• Array<TimeZoneEntry>: Array of TimeZoneEntry objects.

listWithOnlyValue

Returns a list of all time zone values without labels.

const timeZoneValues = TimeZone.listWithOnlyValue();
console.log(timeZoneValues);
/* OUTPUT:
["Africa/Abidjan", "Africa/Accra", "America/New_York", "Europe/London", "Asia/Tokyo", ...]
*/

Returns:

• Array<string>: Array of time zone values.

listWithOnlyLabel

Returns a list of all time zone labels without values.

const timeZoneLabels = TimeZone.listWithOnlyLabel();
console.log(timeZoneLabels);
/* OUTPUT:
["(UTC-05:00) America/New_York", "(UTC+00:00) London", ...]
*/

Returns:

• Array<string>: Array of time zone labels.

listByRegion

Lists time zones for a specific region.

const timeZonesInAmerica = TimeZone.listByRegion('America');
console.log(timeZonesInAmerica);
/* OUTPUT:
[
  {
    "label": "(UTC-05:00) America/New_York",
    "value": "America/New_York",
    "country": "United States",
    "phoneCode": "+1",
    "utcOffset": "-05:00"
  },
  ...
]
*/

Parameters:

• region: string: The region to filter time zones.

Returns:

• Array<TimeZoneEntry>: Array of TimeZoneEntry objects for the specified region.

listByCountry

Lists time zones for a specific country.

const timeZonesInUS = TimeZone.listByCountry('United States');
console.log(timeZonesInUS);
/* OUTPUT:
[
  {
    "label": "(UTC-05:00) America/New_York",
    "value": "America/New_York",
    "country": "United States",
    "phoneCode": "+1",
    "utcOffset": "-05:00"
  },
  ...
]
*/

Parameters:

• country: string: The country to filter time zones.

Returns:

• Array<TimeZoneEntry>: Array of TimeZoneEntry objects for the specified country.

getDetailsUsingTimeZoneValue

Gets the details for a given time zone value.

const tzDetails = TimeZone.getDetailsUsingTimeZoneValue('America/New_York');
console.log(tzDetails);
/* OUTPUT:
{
  "label": "(UTC-05:00) America/New_York",
  "value": "America/New_York",
  "country": "United States",
  "phoneCode": "+1",
  "utcOffset": "-05:00"
}
*/

Parameters:

• value: string: The time zone value.

Returns:

• TimeZoneEntry | null: The corresponding details or null if not found.

getRegions

Returns a list of all available regions.

const regions = TimeZone.getRegions();
console.log(regions);
/* OUTPUT:
["Africa", "America", "Asia", "Atlantic", "Australia", "Europe", "Indian", "Pacific"]
*/

Returns:

• Array<string>: Array of region strings.

convertUTCToTimeZone

Converts a UTC date to a specified time zone.

// Using ISO string with default options (ISO format)
const converted1 = TimeZone.convertUTCToTimeZone('2024-03-15T10:00:00Z', 'America/New_York');
console.log(converted1); // "2024-03-15T06:00:00"

// Using Date object with custom formatting
const date = new Date('2024-03-15T10:00:00Z');
const converted2 = TimeZone.convertUTCToTimeZone(date, 'America/New_York', {
  returnISO: false,
  is24Hour: false,
  dateSeparator: '/',
  timeSeparator: ':'
});
console.log(converted2); // "2024/03/15 6:00:00 AM"

Parameters:

• utcDate: Date | string: The UTC date.
• targetTimeZone: string: The target time zone.
• options: ConvertOptions (optional): Object containing optional formatting options:
  • returnISO: boolean: Whether to return ISO format (default true).
  • is24Hour: boolean: Whether to use 24-hour format (default true).
  • dateSeparator: string: The date separator (default -).
  • timeSeparator: string: The time separator (default :).

Returns:

• string | null: ISO formatted date-time string in the target time zone or error message.

convertToUTC

Converts a date-time from a specified time zone to UTC.

// Using ISO string with default options (ISO format)
const utc1 = TimeZone.convertToUTC('2024-03-15T06:00:00', 'America/New_York');
console.log(utc1); // "2024-03-15T10:00:00.000Z"

// Using Date object with custom formatting
const localDate = new Date('2024-03-15T06:00:00');
const utc2 = TimeZone.convertToUTC(localDate, 'America/New_York', {
  returnISO: false,
  is24Hour: false,
  dateSeparator: '/',
  timeSeparator: ':'
});
console.log(utc2); // "2024/03/15 10:00:00 AM"

Parameters:

• date: Date | string: The date-time to convert.
• timeZone: string: The source time zone.
• options: ConvertOptions (optional): Object containing optional formatting options:
  • returnISO: boolean: Whether to return ISO format (default true).
  • is24Hour: boolean: Whether to use 24-hour format (default true).
  • dateSeparator: string: The date separator (default -).
  • timeSeparator: string: The time separator (default :).

Returns:

• string | Error: ISO formatted UTC date-time string or error message.

convertBetweenTimeZones

Converts a date-time between two specified time zones.

// Using ISO format
const converted1 = TimeZone.convertBetweenTimeZones(
  '2024-03-15T10:00:00',
  'America/New_York',
  'Asia/Tokyo',
  { returnISO: true }
);
console.log(converted1); // "2024-03-15T23:00:00"

// Using custom formatting
const converted2 = TimeZone.convertBetweenTimeZones(
  '2024-03-15T10:00:00',
  'America/New_York',
  'Asia/Tokyo',
  {
    returnISO: false,
    is24Hour: false,
    dateSeparator: '/',
    timeSeparator: ':'
  }
);
console.log(converted2); // "2024/03/15 11:00:00 PM"

Parameters:

• date: string: The date-time string to convert.
• fromTimeZone: string: The source timezone.
• toTimeZone: string: The target timezone.
• options: ConvertOptions (optional): Object containing optional formatting options:
  • returnISO: boolean: Whether to return ISO format (default true).
  • is24Hour: boolean: Whether to use 24-hour format (default true).
  • dateSeparator: string: The date separator (default -).
  • timeSeparator: string: The time separator (default :).

Returns:

• string | null: ISO formatted date-time string in the target time zone or error message.

getCurrentTimeInTimeZone

Gets the current time in a specified time zone.

// Get current time in ISO format
const currentTime1 = TimeZone.getCurrentTimeInTimeZone('America/New_York', { returnISO: true });
console.log(currentTime1); // "2024-03-15T06:00:00"

// Get current time with custom formatting
const currentTime2 = TimeZone.getCurrentTimeInTimeZone('America/New_York', {
  returnISO: false,
  is24Hour: false,
  dateSeparator: '/',
  timeSeparator: ':'
});
console.log(currentTime2); // "2024/03/15 6:00:00 AM"

Parameters:

• targetTimeZone: string: The target timezone.
• options: ConvertOptions (optional): Object containing optional formatting options:
  • returnISO: boolean: Whether to return ISO format (default true).
  • is24Hour: boolean: Whether to use 24-hour format (default true).
  • dateSeparator: string: The date separator (default -).
  • timeSeparator: string: The time separator (default :).

Returns:

• string | null: ISO formatted current date-time string in the target time zone or error message.

getTimeDifferenceBetweenTimeZones

Calculates the time difference between two time zones for a specific date.

const difference = TimeZone.getTimeDifferenceBetweenTimeZones(
  '2024-03-15T10:00:00',
  'America/New_York',
  'Asia/Tokyo'
);
console.log(difference); // "+13 hours 0 minutes"

Parameters:

• date: string: The date string to use for calculation.
• fromTimeZone: string: The source time zone.
• toTimeZone: string: The target time zone.

Returns:

• string | null: Formatted time difference string or error message.

convertUTCToLocal

Converts UTC date-time to Local date-time and returns local ISO string.

const localTime = TimeZone.convertUTCToLocal('2024-03-15T10:00:00Z');
console.log(localTime); // "2024-03-15T10:00:00.000Z" (returns ISO string)

Parameters:

• dateTimeString: string: The UTC date-time string to convert.

Returns:

• string | null: Local formatted date-time string or null if conversion fails.

formatDateTime

Format an ISO date-time string using a custom format pattern.

// Format with default timezone (UTC)
const formatted1 = TimeZone.formatDateTime(
  '2024-03-15T10:00:00Z',
  'yyyy-MM-dd HH:mm:ss'
);
console.log(formatted1); // "2024-03-15 10:00:00"

// Format with specific timezone
const formatted2 = TimeZone.formatDateTime(
  '2024-03-15T10:00:00Z',
  'yyyy-MM-dd HH:mm:ss',
  'America/New_York'
);
console.log(formatted2); // "2024-03-15 06:00:00"

Parameters:

• isoDateTimeString: string: The ISO date-time string to format.
• format: string: The format pattern using supported tokens (see below).
• timezone: string: Optional timezone to convert to before formatting (default: 'UTC').

Returns:

• string | null: Formatted date-time string or null/error message if formatting fails.

Supported Format Tokens:

Token	Example	Description
yyyy	2024	Full year (4 digits)
MM	03	Month number (01-12)
dd	15	Day of month (01-31)
HH	14	24-hour hour (00-23)
mm	30	Minute (00-59)
ss	45	Second (00-59)

getLocalTimeZone

Get the user's local timezone.

const localTZ = TimeZone.getLocalTimeZone();
console.log(localTZ); // "America/New_York" (example output)

Returns:

• string: The IANA timezone identifier string for the user's local timezone.

TypeScript Support

This package includes comprehensive TypeScript support with type definitions. The main types include:

• TimeZoneNames: Union type of all supported timezone values
• TimeZoneEntry: Interface for timezone objects with label, value, country, phoneCode, and utcOffset
• ConvertOptions: Interface for formatting options used in conversion methods

import { TimeZone } from "timezone-utility";

// TypeScript will provide intellisense and type checking
const timeZone: TimeZoneNames = 'America/New_York';
const isValid: boolean = TimeZone.isValidTimeZone(timeZone);

Error Handling

Most methods return appropriate error messages or null values when operations fail:

• Invalid timezone names return error messages like "Invalid timezone provided."
• Invalid date formats return error messages like "Invalid date format."
• Failed conversions return null or Error objects
• Validation methods return boolean values

Always check return values for error conditions:

const result = TimeZone.convertToUTC('invalid-date', 'America/New_York');
if (result === 'Invalid date format.') {
  // Handle error
  console.error('Date conversion failed');
}

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.