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

!GitHub license
!npm version
!TypeScript

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

``bash
npm install @adnanghani07/iana-timezone-utils

or

yarn add @adnanghani07/iana-timezone-utils

or

pnpm add @adnanghani07/iana-timezone-utils
`

Usage

$3

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

`typescript
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"
`

$3

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

`typescript
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 the display abbreviation for a timezone at a specific point in time.

`typescript
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
`

$3

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

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

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

API Reference

$3

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.

$3

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

$3

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

$3

Returns a sorted array of all canonical string identifiers.

License

MIT © Adnan Ghani