Check Timezone Identifiers

isValidTimeZoneId()

Validates whether the provided value is a recognized IANA timezone identifier from the TZ database.

See isNativeTimeZoneId for lightweight native JS solution.

Signature

isValidTimeZoneId(value: unknown): value is $TimeZoneIdentifier

Parameters

• value - The value to validate as a timezone identifier

Return Type

• value is $TimeZoneIdentifier - Type predicate that returns true if the value is a valid IANA timezone identifier

Example

Remarks

• Comprehensive IANA TZ Database coverage - validates against all 597 identifiers including both modern canonical names and legacy aliases
• Includes both canonical and alias names - recognizes modern names like Asia/Kolkata alongside legacy names like Asia/Calcutta
• Type predicate function - when returns true, TypeScript narrows the type to $TimeZoneIdentifier
• Case-sensitive - identifiers must match exactly (e.g., 'America/New_York', not 'america/new_york')
• Larger bundle size - includes a comprehensive array of all IANA identifiers (597 entries, ~10.7 kilobytes after minification)

import { IANA_TZ_IDS, TIME_ZONE_IDS } from 'toolbox-x/constants';

{
  'Asia/Dhaka': { tzName: 'Bangladesh Standard Time', offset: 'UTC+06:00' },
  // ...
}

When to Use

• Future-proof applications that want to use modern canonical names
• Data validation where you need to accept both canonical and alias timezone identifiers
• Applications requiring maximum timezone coverage including modern naming conventions
• Backend systems where bundle size is less critical

Typical Use Cases

// Validate user input preferring modern names
const userInput = 'Asia/Kolkata'; // Modern systems should use this
if (isValidTimeZoneId(userInput)) {
    const ch = new Chronos().timeZone(userInput); // Type-safe usage
}

// Filter valid timezone identifiers including modern names
const potentialZones = ['Asia/Dhaka', 'EST', 'Asia/Kolkata', 'UTC+06:00'];
const validZones = potentialZones.filter(isValidTimeZoneId);
// → ['Asia/Dhaka', 'EST', 'Asia/Kolkata']

// Configuration validation for modern systems
const config = { timezone: 'Asia/Kolkata' }; // Modern configuration
if (!isValidTimeZoneId(config.timezone)) {
    throw new Error('Invalid timezone identifier in configuration');
}

isNativeTimeZoneId()

Validates whether the provided value is a supported time zone identifier using the native JavaScript API (Intl.supportedValuesOf('timeZone')).

See isValidTimeZoneId for full 597 time zone identifier support.

Signature

isNativeTimeZoneId(value: unknown): value is TimeZoneIdNative

Parameters

• value - The value to validate as a timezone identifier

Return Type

• value is TimeZoneIdNative - Type predicate that returns true if the value is a valid native JS-supported time zone identifier, otherwise false.

Example

Remarks

• Native JavaScript validation - uses Intl.supportedValuesOf('timeZone') for validation
• Legacy-focused identifiers - many JS engines still use legacy names like Asia/Calcutta instead of modern Asia/Kolkata
• Small bundle footprint - relies on built-in browser/Node.js APIs, no additional data (only ~700 bytes after minification)
• Type predicate function - when returns true, TypeScript narrows the type to TimeZoneIdNative
• Case-sensitive - identifiers must match exactly (e.g., 'America/New_York', not 'america/new_york')
• Optimal performance - leverages native browser optimizations
• Note: Some JS engines accept modern names in DateTimeFormat but don't include them in supportedValuesOf()

import { TIME_ZONES_NATIVE } from 'toolbox-x/constants';

{
  'Asia/Dhaka': { tzName: 'Bangladesh Standard Time', offset: 'UTC+06:00' },
  // ...
}

When to Use

• Frontend applications where bundle size is critical
• Compatibility with older JS engines that use legacy timezone names
• Performance-sensitive code that benefits from native API speed
• Validation that must match exactly what the JS engine considers "supported"

Typical Use Cases

Practical Example