Skip to main content

Get Time Zone Details

getTimeZoneDetails​

Retrieves comprehensive time zone information using the Internationalization API (Intl): time zone identifiers, localized names, and GMT offset information.

Function Signature​

getTimeZoneDetails(tzId?: $TimeZoneIdentifier, date?: Date): TimeZoneDetails

Parameters​

ParameterTypeRequiredDefaultDescription
tzId$TimeZoneIdentifierNoSystem timezoneIANA time zone identifier (e.g., "America/New_York")
dateDateNoCurrent dateSpecific date for time zone resolution

Return Value​

Returns a TimeZoneDetails object containing:

PropertyTypeDescription
tzIdentifierLooseLiteral<$TimeZoneIdentifier>IANA time zone identifier
tzNameLongMaybe<LooseLiteral<TimeZoneName>>Long localized form of full time zone name
tzNameLongGenericMaybe<LooseLiteral<TimeZoneName>>Long generic non-location format of time zone name
tzNameLongOffsetMaybe<LooseLiteral<$GMTOffset>>GMT offset representation of time zone name

Example Usage​

Basic Usage​

import { getTimeZoneDetails } from 'nhb-toolbox';

// Get details for current system timezone
const systemTZ = getTimeZoneDetails();
console.log(systemTZ);
// {
//   tzIdentifier: 'America/New_York',
//   tzNameLong: 'Eastern Standard Time',
//   tzNameLongGeneric: 'Eastern Time',
//   tzNameLongOffset: 'GMT-05:00'
// }

Specific Time Zone​

// Get details for London timezone
const londonTZ = getTimeZoneDetails('Europe/London');
console.log(londonTZ);
// {
//   tzIdentifier: 'Europe/London',
//   tzNameLong: 'Greenwich Mean Time',
//   tzNameLongGeneric: 'United Kingdom Time',
//   tzNameLongOffset: 'GMT'
// }

International Time Zones​

// Various international time zones
const timeZones = (
 ['Asia/Tokyo', 'Australia/Sydney', 'Europe/Paris', 'Pacific/Honolulu'] as const
).map((tz) => getTimeZoneDetails(tz));

timeZones.forEach(tz => {
  console.log(`${tz.tzIdentifier}: ${tz.tzNameLong} (${tz.tzNameLongOffset})`);
});
// Asia/Tokyo: Japan Standard Time (GMT+09:00)
// Australia/Sydney: Australian Eastern Daylight Time (GMT+11:00)
// Europe/Paris: Central European Standard Time (GMT+01:00)
// Pacific/Honolulu: Hawaii-Aleutian Standard Time (GMT-10:00)

Type Definitions​

interface TimeZoneDetails {
 /** IANA time zone identifier */
 tzIdentifier: $TimeZoneIdentifier;
 /** Long localized form (e.g., `'Pacific Standard Time'`, `'Nordamerikanische Westküsten-Normalzeit'`) */
 tzNameLong: Maybe<LooseLiteral<TimeZoneName>>;
 /** Long generic non-location format (e.g.: `'Pacific Time'`, `'Nordamerikanische Westküstenzeit'`) */
 tzNameLongGeneric: Maybe<LooseLiteral<TimeZoneName>>;
 /** Long localized GMT format, prefixed with `"GMT"` (e.g., `"GMT-08:00"`) */
 tzNameLongOffset: Maybe<LooseLiteral<$GMTOffset>>;
}

Implementation Details​

Internationalization API Usage​

The function leverages the Intl.DateTimeFormat API with specific configuration:

const formatter = new Intl.DateTimeFormat('en', {
  timeZone: tzId,
  timeZoneName: type // 'long' | 'longGeneric' | 'longOffset'
});

Time Zone Name Types​

TypeDescriptionExample
longComplete time zone name"Eastern Daylight Time"
longGenericLocation-agnostic name"Eastern Time"
longOffsetGMT offset format"GMT+06:00"

getNativeTimeZoneId​

Retrieves the current system's IANA time zone identifier using the Internationalization API (Intl.DateTimeFormat).

Function Signature​

getNativeTimeZoneId(): TimeZoneIdNative

Return Value​

Returns a TimeZoneIdNative string representing the system's current IANA time zone identifier.

Example Usage​

import { getNativeTimeZoneId } from 'nhb-toolbox';

const currentTimeZone = getNativeTimeZoneId();
console.log(currentTimeZone);
// 'America/New_York'

Implementation Details​

The function uses Intl.DateTimeFormat().resolvedOptions().timeZone to retrieve the system's time zone identifier. This is a lightweight and native way to obtain the current time zone without additional configuration.

Notes​

  • The returned identifier is in the IANA time zone format (e.g., "America/New_York", "Europe/London").
  • This function does not accept parameters and always returns the current system time zone.

getTimeZoneIds​

Resolves all IANA time zone identifiers that match a given UTC offset.

Function Signature​

getTimeZoneIds(offset: UTCOffset): TimeZoneIdNative[]

Parameters​

ParameterTypeRequiredDescription
offsetUTCOffsetYesUTC offset in "UTC±HH:MM" format (e.g., "UTC+05:30", "UTC-08:00")

Return Value​

Returns an array of TimeZoneIdNative strings representing all IANA time zone identifiers that match the given UTC offset. Returns an empty array if the offset is invalid or no matches are found.

Example Usage​

import { getTimeZoneIds } from 'nhb-toolbox';

const zonesForUTCPlus5 = getTimeZoneIds('UTC+05:00');
console.log(zonesForUTCPlus5);
// ['Asia/Karachi', 'Asia/Tashkent', 'Asia/Yekaterinburg', ...]

const zonesForUTCMinus8 = getTimeZoneIds('UTC-08:00');
console.log(zonesForUTCMinus8);
// ['America/Los_Angeles', 'America/Tijuana', 'Pacific/Pitcairn', ...]

const invalid = getTimeZoneIds('UTC+25:00');
console.log(invalid);
// []

Implementation Details​

  • Uses an internal in-memory cache (TZ_MAP) that persists for the lifetime of the running application.
  • The cache is lazily populated: offset-to-time-zone mapping is computed only once per offset.
  • Offset validation is performed via isValidUTCOffset.
  • Time zone detection uses Intl.DateTimeFormat with timeZoneName: 'longOffset' to resolve GMT offsets.

Caching Behavior​

  • First call for a given offset populates the cache for all known time zones.
  • Subsequent calls for the same offset return cached results instantly.
  • The cache is shared across the entire application session.

Notes​

  • Offset must be in the exact format "UTC±HH:MM".
  • Returns an empty array for invalid offsets or if no matching time zones exist.
  • Useful for scenarios where you need to map a UTC offset to possible time zones (e.g., in scheduling or internationalization contexts).

See Also​

  • Refer to Chronos class for methods like these.