Timezone Plugin

Import & Usage

import { Chronos, chronos } from "chronos-date";
import { timeZonePlugin } from 'chronos-date/plugins/timeZonePlugin';

// Register the plugin globally
Chronos.use(timeZonePlugin);
// or
chronos.use(timeZonePlugin);
// or
Chronos.register(timeZonePlugin);
// or
chronos.register(timeZonePlugin);

const c = new Chronos();
const timeZoned = c.timeZone("Asia/Kathmandu");
console.log(timeZoned.getTimeZoneNameShort()); // Get timezone name abbreviation
console.log(timeZoned.getTimeZoneName()); // Get full timezone name
console.log(timeZoned.format()); // Format date in current timezone

Example Usage

Overview

The timeZonePlugin adds comprehensive time zone functionality to Chronos, enabling:

• Time zone conversion and management
• Date-time formatting with current time zone
• Access to time zone names and abbreviations
• Support for different time zone formats (identifier, abbreviation, UTC offset)

Methods Added by the Plugin

API Reference

timeZone()

Creates a new instance of Chronos for the specified time zone identifier, abbreviated time zone name or UTC offset.

Signature

timeZone(tzId: TimeZoneIdentifier): Chronos;
timeZone(zone: TimeZone): Chronos;
timeZone(utc: UTCOffset): Chronos;
timeZone(utc: TimeZoneIdentifier | TimeZone | UTCOffset): Chronos;

Parameters

• tzId: IANA timezone identifier (e.g., 'Africa/Harare', 'America/New_York')
• zone: Standard timezone abbreviation (e.g., 'EST', 'IST', 'UTC')
• utc: UTC offset in UTC±HH:mm format for fictional/unlisted timezones (e.g., 'UTC+06:15')

Return Type

Chronos - New instance configured with the specified timezone context

Overloads

Timezone Identifier

Creates a new instance using an IANA timezone identifier. This is the recommended approach for accurate timezone handling.

new Chronos('2025-01-15').timeZone('Asia/Dhaka');
new Chronos('2025-01-15').timeZone('America/Los_Angeles');

Timezone Abbreviation

Creates a new instance using a standard timezone abbreviation. Use when timezone identifiers are not available.

new Chronos('2025-01-15').timeZone('EST'); // Eastern Standard Time
new Chronos('2025-01-15').timeZone('IST'); // Indian Standard Time

UTC Offset

Creates a new instance using a UTC offset for fictional or unlisted timezones.

new Chronos('2025-01-15').timeZone('UTC+08:00'); // 8 hours ahead of UTC
new Chronos('2025-01-15').timeZone('UTC-05:30'); // 5 hours 30 minutes behind UTC

Example

import { Chronos } from 'chronos-date';
import { timeZonePlugin } from 'chronos-date/plugins/timeZonePlugin';

// Register plugin
Chronos.use(timeZonePlugin);

// Using IANA identifier (recommended)
const dhakaTime = new Chronos('2025-01-15').timeZone('Asia/Dhaka');

// Using timezone abbreviation
const easternTime = new Chronos('2025-01-15').timeZone('EST');

// Using UTC offset
const customOffset = new Chronos('2025-01-15').timeZone('UTC+06:30');

Remarks

• Timezone identifiers provide the most accurate timezone handling and are recommended for production use
• Timezone abbreviations should be used only when identifiers are not available, as they may have ambiguous interpretations
• UTC offsets are suitable for fictional timezones or regions not covered by the IANA database
• Invalid input automatically falls back to UTC timezone
• Returns a new Chronos instance - the original instance remains unchanged

getTimeZoneName()

Get full time zone name or UTC offset

Signature

getTimeZoneName(utc?: UTCOffset): LooseLiteral<TimeZoneName | UTCOffset>

Parameters

• utc? — (Optional) A UTC offset string in the format "UTC+06:00", "UTC-04:30", etc.
  • If provided, it bypasses the instance's current offset and returns the name mapped to this offset instead.

Return Value

• LooseLiteral<UTCOffset> — The current time zone name as a full descriptive string (e.g. "Bangladesh Standard Time") or the fallback UTC offset (UTCOffset).

Example Usage

getTimeZoneNameShort()

Get abbreviated time zone name or UTC offset

Signature

getTimeZoneNameShort(utc?: UTCOffset): TimeZone | UTCOffset

Parameters

• utc? — (Optional) A UTC offset string in the format "UTC+06:00", "UTC-04:30", etc.
  • If provided, it bypasses the instance's current offset and returns the name mapped to this offset instead.

Return Value

• TimeZone | UTCOffset — The current time zone abbreviation (e.g. "BST" for Bangladesh Standard Time).

Example Usage

ALias

Also available as getTimeZoneNameAbbr() alias.