@adnanghani07/iana-timezone-utils

A lightweight, zero-dependency utility library for working with IANA timezones. It provides canonicalization of legacy timezone names, DST detection, and timezone abbreviations using native Intl APIs.

Features

• 🌍 Canonicalization: Convert legacy or alias timezones (e.g., Asia/Calcutta) to their modern IANA canonical map (e.g., Asia/Kolkata).
• 🕒 DST Detection: robustly check if a specific date is currently in Daylight Saving Time for any given timezone.
• 📝 Abbreviations: Extract standard timezone abbreviations (e.g., EST, IST, GMT+5) using native browser APIs.
• 📋 Listing: Get a complete list of all distinct canonical timezones supported by the library.
• ⚡ Zero Dependencies: Built on top of Intl and standard generic data.
• 🔷 TypeScript: First-class type definitions included.

Installation

npm install @adnanghani07/iana-timezone-utils
# or
yarn add @adnanghani07/iana-timezone-utils
# or
pnpm add @adnanghani07/iana-timezone-utils

Usage

1. Canonicalize Timezones

Normalize legacy or aliased timezone identifiers to their primary IANA canonical ID.

import { canonicalizeTimezone } from "@adnanghani07/iana-timezone-utils";

console.log(canonicalizeTimezone("Asia/Calcutta")); // "Asia/Kolkata"
console.log(canonicalizeTimezone("US/Eastern")); // "America/New_York"
console.log(canonicalizeTimezone("UTC")); // "Etc/UTC"

2. Check for Daylight Saving Time (DST)

Determine if a specific timezone is observing Daylight Saving Time for a given date.

import { isDST } from "@adnanghani07/iana-timezone-utils";

// Check for current time
const isNewYorkDST = isDST("America/New_York");
console.log(`Is New York in DST? ${isNewYorkDST}`);

// Check for a specific date (e.g., Winter in NY)
const winterDate = new Date("2023-01-15T12:00:00Z");
console.log(isDST("America/New_York", winterDate)); // false

// Check for a specific date (e.g., Summer in NY)
const summerDate = new Date("2023-07-15T12:00:00Z");
console.log(isDST("America/New_York", summerDate)); // true

3. Get Timezone Abbreviation

Get the display abbreviation for a timezone at a specific point in time.

import { getTimezoneAbbreviation } from "@adnanghani07/iana-timezone-utils";

const abbr = getTimezoneAbbreviation("America/Los_Angeles");
console.log(abbr); // e.g., "PST" or "PDT" depending on current date

4. List All Canonical Timezones

Retrieve an array of all unique canonical timezone identifiers derived from the IANA database aliases.

import { listCanonicalTimezones } from "@adnanghani07/iana-timezone-utils";

const allZones = listCanonicalTimezones();
console.log(allZones);
// ["Africa/Abidjan", "Africa/Algiers", ..., "America/New_York", ...]

API Reference

canonicalizeTimezone(tz: string): string

Returns the canonical IANA ID for the given timezone string. If the timezone is already canonical or not found in the alias map, it returns the input key.

isDST(timezone: string, date?: Date): boolean

Returns true if the timezone is in Daylight Saving Time for the provided date. Defaults to new Date() if no date is provided.

getTimezoneAbbreviation(timezone: string, date?: Date): string

Returns the short abbreviation (e.g., "EST", "GMT+5:30") for the timezone at the given date.

listCanonicalTimezones(): string[]

Returns a sorted array of all canonical string identifiers.

License

MIT © Adnan Ghani