Project Title

A brief description of what this project does and who it's for

Time Zone Utilities Library

A lightweight library for handling time zone conversions, formatting, and validations using the powerful Luxon library.

Features

• Convert date and time between time zones.
• Get the current time in a specific time zone.
• Fetch the UTC offset for a given time zone.
• Check if Daylight Saving Time (DST) is active for a time zone.
• Validate time zone strings.
• Format dates in a specific time zone.

Installation

Install the library via npm:

npm install timezone-utils-ts

Usage

Import the required functions from the library:

import {
  convertTimeZone,
  getCurrentTime,
  getUtcOffset,
  isDstActive,
  isValidTimeZone,
  formatDate,
} from 'timezone-utils-ts';

API Documentation

1) convertTimeZone

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

Parameters

date (string | Date): The input date (ISO string or JavaScript Date object).

fromTimeZone (string): The source time zone.

toTimeZone (string): The target time zone.

Returns

A string representing the converted date in ISO format.

Example

convertTimeZone('2025-01-13T12:00:00', 'America/New_York', 'Asia/Kolkata');
// Output: '2025-01-13T22:30:00.000+05:30'

2. getCurrentTime

Fetches the current time in a specified time zone.

Parameters

timeZone (string): The desired time zone. Returns A string representing the current date and time in ISO format.

Example

getCurrentTime('Europe/London');
// Output: '2025-01-13T18:00:00.000Z'

3. getUtcOffset

Gets the UTC offset for a specific time zone.

Parameters

timeZone (string): The desired time zone. Returns A string representing the UTC offset (e.g., UTC+05:30).

Example

getUtcOffset('Asia/Tokyo');
// Output: 'UTC+09:00'

4. isDstActive

Checks if Daylight Saving Time (DST) is active for a time zone at a given date.

Parameters timeZone (string): The time zone to check. date (Date): The date to evaluate. Returns A boolean indicating if DST is active.

Example

isDstActive('America/New_York', new Date('2025-07-04'));
// Output: true

5. isValidTimeZone

Validates if a given string is a valid IANA time zone.

Parameters

timeZone (string): The time zone string to validate. Returns A boolean indicating if the time zone is valid.

Example

isValidTimeZone('Asia/Kolkata');
// Output: true

6. formatDate

Formats a date in a specified time zone.

Parameters

date (string | Date): The input date (ISO string or JavaScript Date object).

timeZone (string): The desired time zone.

format (string): The output format (default: yyyy-MM-dd HH:mm:ss).

Returns A formatted string representing the date.

Example

formatDate('2025-01-13T12:00:00', 'Asia/Kolkata', 'dd/MM/yyyy HH:mm:ss');
// Output: '13/01/2025 17:30:00'