timezone-utility/dist/index.d.ts

A versatile timezone management package designed for CommonJS, ES Module (ESM), JavaScript, and TypeScript projects.

/**
 * Timezone Utility
 *
 * A versatile timezone management package designed for CommonJS, ES Module (ESM), JavaScript, and TypeScript projects.
 * It offers a range of features, including timezone listing, retrieving labels and values, region-based filtering, and converting between UTC and other timezones.
 * @packageDocumentation
 */
interface TimeZoneEntry {
    label: string;
    value: string;
    country: string;
    phoneCode: string;
    utcOffset: string;
}
interface ConvertOptions {
    returnISO?: boolean;
    is24Hour?: boolean;
    dateSeparator?: string;
    timeSeparator?: string;
}
type TimeZoneNames = "Africa/Abidjan" | "Africa/Accra" | "Africa/Addis_Ababa" | "Africa/Algiers" | "Africa/Asmera" | "Africa/Bamako" | "Africa/Bangui" | "Africa/Banjul" | "Africa/Bissau" | "Africa/Blantyre" | "Africa/Brazzaville" | "Africa/Bujumbura" | "Africa/Cairo" | "Africa/Casablanca" | "Africa/Ceuta" | "Africa/Conakry" | "Africa/Dakar" | "Africa/Dar_es_Salaam" | "Africa/Djibouti" | "Africa/Douala" | "Africa/El_Aaiun" | "Africa/Freetown" | "Africa/Gaborone" | "Africa/Harare" | "Africa/Johannesburg" | "Africa/Juba" | "Africa/Kampala" | "Africa/Khartoum" | "Africa/Kigali" | "Africa/Kinshasa" | "Africa/Lagos" | "Africa/Libreville" | "Africa/Lome" | "Africa/Luanda" | "Africa/Lubumbashi" | "Africa/Lusaka" | "Africa/Malabo" | "Africa/Maputo" | "Africa/Maseru" | "Africa/Mbabane" | "Africa/Mogadishu" | "Africa/Monrovia" | "Africa/Nairobi" | "Africa/Ndjamena" | "Africa/Niamey" | "Africa/Nouakchott" | "Africa/Ouagadougou" | "Africa/Porto-Novo" | "Africa/Sao_Tome" | "Africa/Tripoli" | "Africa/Tunis" | "Africa/Windhoek" | "America/Adak" | "America/Anchorage" | "America/Anguilla" | "America/Antigua" | "America/Araguaina" | "America/Argentina/La_Rioja" | "America/Argentina/Rio_Gallegos" | "America/Argentina/Salta" | "America/Argentina/San_Juan" | "America/Argentina/San_Luis" | "America/Argentina/Tucuman" | "America/Argentina/Ushuaia" | "America/Aruba" | "America/Asuncion" | "America/Bahia" | "America/Bahia_Banderas" | "America/Barbados" | "America/Belem" | "America/Belize" | "America/Blanc-Sablon" | "America/Boa_Vista" | "America/Bogota" | "America/Boise" | "America/Buenos_Aires" | "America/Cambridge_Bay" | "America/Campo_Grande" | "America/Cancun" | "America/Caracas" | "America/Catamarca" | "America/Cayenne" | "America/Cayman" | "America/Chicago" | "America/Chihuahua" | "America/Ciudad_Juarez" | "America/Coral_Harbour" | "America/Cordoba" | "America/Costa_Rica" | "America/Coyhaique" | "America/Creston" | "America/Cuiaba" | "America/Curacao" | "America/Danmarkshavn" | "America/Dawson" | "America/Dawson_Creek" | "America/Denver" | "America/Detroit" | "America/Dominica" | "America/Edmonton" | "America/Eirunepe" | "America/El_Salvador" | "America/Fort_Nelson" | "America/Fortaleza" | "America/Glace_Bay" | "America/Godthab" | "America/Goose_Bay" | "America/Grand_Turk" | "America/Grenada" | "America/Guadeloupe" | "America/Guatemala" | "America/Guayaquil" | "America/Guyana" | "America/Halifax" | "America/Havana" | "America/Hermosillo" | "America/Indiana/Knox" | "America/Indiana/Marengo" | "America/Indiana/Petersburg" | "America/Indiana/Tell_City" | "America/Indiana/Vevay" | "America/Indiana/Vincennes" | "America/Indiana/Winamac" | "America/Indianapolis" | "America/Inuvik" | "America/Iqaluit" | "America/Jamaica" | "America/Jujuy" | "America/Juneau" | "America/Kentucky/Monticello" | "America/Kralendijk" | "America/La_Paz" | "America/Lima" | "America/Los_Angeles" | "America/Louisville" | "America/Lower_Princes" | "America/Maceio" | "America/Managua" | "America/Manaus" | "America/Marigot" | "America/Martinique" | "America/Matamoros" | "America/Mazatlan" | "America/Mendoza" | "America/Menominee" | "America/Merida" | "America/Metlakatla" | "America/Mexico_City" | "America/Miquelon" | "America/Moncton" | "America/Monterrey" | "America/Montevideo" | "America/Montserrat" | "America/Nassau" | "America/New_York" | "America/Nome" | "America/Noronha" | "America/North_Dakota/Beulah" | "America/North_Dakota/Center" | "America/North_Dakota/New_Salem" | "America/Ojinaga" | "America/Panama" | "America/Paramaribo" | "America/Phoenix" | "America/Port-au-Prince" | "America/Port_of_Spain" | "America/Porto_Velho" | "America/Puerto_Rico" | "America/Punta_Arenas" | "America/Rankin_Inlet" | "America/Recife" | "America/Regina" | "America/Resolute" | "America/Rio_Branco" | "America/Santarem" | "America/Santiago" | "America/Santo_Domingo" | "America/Sao_Paulo" | "America/Scoresbysund" | "America/Sitka" | "America/St_Barthelemy" | "America/St_Johns" | "America/St_Kitts" | "America/St_Lucia" | "America/St_Thomas" | "America/St_Vincent" | "America/Swift_Current" | "America/Tegucigalpa" | "America/Thule" | "America/Tijuana" | "America/Toronto" | "America/Tortola" | "America/Vancouver" | "America/Whitehorse" | "America/Winnipeg" | "America/Yakutat" | "Antarctica/Casey" | "Antarctica/Davis" | "Antarctica/DumontDUrville" | "Antarctica/Macquarie" | "Antarctica/Mawson" | "Antarctica/McMurdo" | "Antarctica/Palmer" | "Antarctica/Rothera" | "Antarctica/Syowa" | "Antarctica/Troll" | "Antarctica/Vostok" | "Arctic/Longyearbyen" | "Asia/Aden" | "Asia/Almaty" | "Asia/Amman" | "Asia/Anadyr" | "Asia/Aqtau" | "Asia/Aqtobe" | "Asia/Ashgabat" | "Asia/Atyrau" | "Asia/Baghdad" | "Asia/Bahrain" | "Asia/Baku" | "Asia/Bangkok" | "Asia/Barnaul" | "Asia/Beirut" | "Asia/Bishkek" | "Asia/Brunei" | "Asia/Calcutta" | "Asia/Chita" | "Asia/Colombo" | "Asia/Damascus" | "Asia/Dhaka" | "Asia/Dili" | "Asia/Dubai" | "Asia/Dushanbe" | "Asia/Famagusta" | "Asia/Gaza" | "Asia/Hebron" | "Asia/Hong_Kong" | "Asia/Hovd" | "Asia/Irkutsk" | "Asia/Jakarta" | "Asia/Jayapura" | "Asia/Jerusalem" | "Asia/Kabul" | "Asia/Kamchatka" | "Asia/Karachi" | "Asia/Katmandu" | "Asia/Khandyga" | "Asia/Krasnoyarsk" | "Asia/Kuala_Lumpur" | "Asia/Kuching" | "Asia/Kuwait" | "Asia/Macau" | "Asia/Magadan" | "Asia/Makassar" | "Asia/Manila" | "Asia/Muscat" | "Asia/Nicosia" | "Asia/Novokuznetsk" | "Asia/Novosibirsk" | "Asia/Omsk" | "Asia/Oral" | "Asia/Phnom_Penh" | "Asia/Pontianak" | "Asia/Pyongyang" | "Asia/Qatar" | "Asia/Qostanay" | "Asia/Qyzylorda" | "Asia/Rangoon" | "Asia/Riyadh" | "Asia/Saigon" | "Asia/Sakhalin" | "Asia/Samarkand" | "Asia/Seoul" | "Asia/Shanghai" | "Asia/Singapore" | "Asia/Srednekolymsk" | "Asia/Taipei" | "Asia/Tashkent" | "Asia/Tbilisi" | "Asia/Tehran" | "Asia/Thimphu" | "Asia/Tokyo" | "Asia/Tomsk" | "Asia/Ulaanbaatar" | "Asia/Urumqi" | "Asia/Ust-Nera" | "Asia/Vientiane" | "Asia/Vladivostok" | "Asia/Yakutsk" | "Asia/Yekaterinburg" | "Asia/Yerevan" | "Atlantic/Azores" | "Atlantic/Bermuda" | "Atlantic/Canary" | "Atlantic/Cape_Verde" | "Atlantic/Faeroe" | "Atlantic/Madeira" | "Atlantic/Reykjavik" | "Atlantic/South_Georgia" | "Atlantic/St_Helena" | "Atlantic/Stanley" | "Australia/Adelaide" | "Australia/Brisbane" | "Australia/Broken_Hill" | "Australia/Darwin" | "Australia/Eucla" | "Australia/Hobart" | "Australia/Lindeman" | "Australia/Lord_Howe" | "Australia/Melbourne" | "Australia/Perth" | "Australia/Sydney" | "Europe/Amsterdam" | "Europe/Andorra" | "Europe/Astrakhan" | "Europe/Athens" | "Europe/Belgrade" | "Europe/Berlin" | "Europe/Bratislava" | "Europe/Brussels" | "Europe/Bucharest" | "Europe/Budapest" | "Europe/Busingen" | "Europe/Chisinau" | "Europe/Copenhagen" | "Europe/Dublin" | "Europe/Gibraltar" | "Europe/Guernsey" | "Europe/Helsinki" | "Europe/Isle_of_Man" | "Europe/Istanbul" | "Europe/Jersey" | "Europe/Kaliningrad" | "Europe/Kiev" | "Europe/Kirov" | "Europe/Lisbon" | "Europe/Ljubljana" | "Europe/London" | "Europe/Luxembourg" | "Europe/Madrid" | "Europe/Malta" | "Europe/Mariehamn" | "Europe/Minsk" | "Europe/Monaco" | "Europe/Moscow" | "Europe/Oslo" | "Europe/Paris" | "Europe/Podgorica" | "Europe/Prague" | "Europe/Riga" | "Europe/Rome" | "Europe/Samara" | "Europe/San_Marino" | "Europe/Sarajevo" | "Europe/Saratov" | "Europe/Simferopol" | "Europe/Skopje" | "Europe/Sofia" | "Europe/Stockholm" | "Europe/Tallinn" | "Europe/Tirane" | "Europe/Ulyanovsk" | "Europe/Vaduz" | "Europe/Vatican" | "Europe/Vienna" | "Europe/Vilnius" | "Europe/Volgograd" | "Europe/Warsaw" | "Europe/Zagreb" | "Europe/Zurich" | "Indian/Antananarivo" | "Indian/Chagos" | "Indian/Christmas" | "Indian/Cocos" | "Indian/Comoro" | "Indian/Kerguelen" | "Indian/Mahe" | "Indian/Maldives" | "Indian/Mauritius" | "Indian/Mayotte" | "Indian/Reunion" | "Pacific/Apia" | "Pacific/Auckland" | "Pacific/Bougainville" | "Pacific/Chatham" | "Pacific/Easter" | "Pacific/Efate" | "Pacific/Enderbury" | "Pacific/Fakaofo" | "Pacific/Fiji" | "Pacific/Funafuti" | "Pacific/Galapagos" | "Pacific/Gambier" | "Pacific/Guadalcanal" | "Pacific/Guam" | "Pacific/Honolulu" | "Pacific/Kiritimati" | "Pacific/Kosrae" | "Pacific/Kwajalein" | "Pacific/Majuro" | "Pacific/Marquesas" | "Pacific/Midway" | "Pacific/Nauru" | "Pacific/Niue" | "Pacific/Norfolk" | "Pacific/Noumea" | "Pacific/Pago_Pago" | "Pacific/Palau" | "Pacific/Pitcairn" | "Pacific/Ponape" | "Pacific/Port_Moresby" | "Pacific/Rarotonga" | "Pacific/Saipan" | "Pacific/Tahiti" | "Pacific/Tarawa" | "Pacific/Tongatapu" | "Pacific/Truk" | "Pacific/Wake" | "Pacific/Wallis" | "UTC";
/**
 * TimeZone class providing static methods for time zone operations.
 */
declare class TimeZone {
    static readonly timezones: TimeZoneEntry[];
    static readonly regions: string[];
    private static timezoneCache;
    /**
     * Checks if a given string is a valid ISO date-time format.
     * @param dateTime - The date-time string to validate.
     * @returns True if the string is a valid ISO date-time, false otherwise.
     */
    static isISODateTime(dateTime: string): boolean;
    /**
     * Validates if a given string is a valid time zone.
     * @param timeZone - The time zone string to validate.
     * @returns True if the time zone is valid, false otherwise.
     */
    static isValidTimeZone(timeZone: string): boolean;
    /**
     * Converts a date-time from one time zone to another.
     * @param dateTime - The date-time to convert (Date object or ISO string).
     * @param sourceTimeZone - The source time zone.
     * @param targetTimeZone - The target time zone.
     * @param returnISO - Whether to return ISO format (default: true).
     * @returns Converted date-time string in ISO format or Error if conversion fails.
     */
    static convertDateTime(dateTime: Date | string, sourceTimeZone: TimeZoneNames, targetTimeZone: TimeZoneNames, returnISO?: boolean): string | Error;
    /**
     * Returns a list of all available time zones.
     * @returns Array of TimeZoneEntry objects.
     */
    static list(): TimeZoneEntry[];
    /**
     * Returns a list of all time zone values.
     * @returns Array of time zone values.
     */
    static listWithOnlyValue(): TimeZoneNames[];
    /**
     * Returns a list of all time zone labels.
     * @returns Array of time zone labels.
     */
    static listWithOnlyLabel(): string[];
    /**
     * Lists time zones for a specific region.
     * @param region - The region to filter time zones.
     * @returns Array of TimeZoneEntry objects for the specified region.
     */
    static listByRegion(region: string): TimeZoneEntry[];
    /**
     * Lists time zones for a specific country.
     * @param country - The country to filter time zones.
     * @returns Array of TimeZoneEntry objects for the specified country.
     */
    static listByCountry(country: string): TimeZoneEntry[];
    /**
     * Gets the details for a given time zone value.
     * @param value - The time zone value.
     * @returns The corresponding details or null if not found.
     */
    static getDetailsUsingTimeZoneValue(value: TimeZoneNames): TimeZoneEntry | null;
    /**
     * Returns a list of all available regions.
     * @returns Array of region strings.
     */
    static getRegions(): string[];
    /**
     * Converts a UTC date to a specified time zone.
     * @param utcDate - The UTC date (Date object or ISO string).
     * @param targetTimeZone - The target time zone.
     * @param options - Conversion options (optional).
     * @returns ISO formatted date-time string in the target time zone or error message.
     */
    static convertUTCToTimeZone(utcDate: Date | string, targetTimeZone: TimeZoneNames, options?: ConvertOptions): string | null;
    /**
     * Converts a date-time from a specified time zone to UTC.
     * @param dateTime - The date-time to convert (Date object or ISO string).
     * @param sourceTimeZone - The source time zone.
     * @param options - Conversion options (optional).
     * @returns ISO formatted UTC date-time string or error message.
     */
    static convertToUTC(date: Date | string, timeZone: TimeZoneNames, options?: ConvertOptions): string | Error;
    /**
     * Converts a date-time between two specified time zones.
     * @param date - The date-time string to convert.
     * @param fromTimeZone - The source time zone.
     * @param toTimeZone - The target time zone.
     * @param options - Conversion options (optional).
     * @returns ISO formatted date-time string in the target time zone or error message.
     */
    static convertBetweenTimeZones(date: string, fromTimeZone: TimeZoneNames, toTimeZone: TimeZoneNames, options?: ConvertOptions): string | null;
    /**
     * Gets the current time in a specified time zone.
     * @param targetTimeZone - The target time zone.
     * @param options - Formatting options (optional).
     * @returns ISO formatted current date-time string in the target time zone or error message.
     */
    static getCurrentTimeInTimeZone(targetTimeZone: TimeZoneNames, options?: ConvertOptions): string | null;
    /**
     * Calculates the time difference between two time zones for a given date.
     * @param date - The date string to use for calculation.
     * @param fromTimeZone - The source time zone.
     * @param toTimeZone - The target time zone.
     * @returns Formatted time difference string or error message.
     */
    static getTimeDifferenceBetweenTimeZones(date: string, fromTimeZone: TimeZoneNames, toTimeZone: TimeZoneNames): string | null;
    /**
     * Convert UTC date-time to Local date-time and return local ISO string
     * @param dateTimeString - The date-time string to convert.
     * @returns Local formatted date-time string or null if conversion fails.
     */
    static convertUTCToLocal(dateTimeString: string): string | null;
    /**
     * Format an ISO date-time string using a custom format pattern
     * @param isoDateTimeString - The ISO date-time string to format
     * @param format - The format pattern (simplified version)
     * @param timezone - Optional timezone to convert to before formatting (default: UTC)
     * @returns Formatted date-time string or null if formatting fails
     */
    static formatDateTime(isoDateTimeString: string, format: string, timezone?: TimeZoneNames): string | null;
    /**
     * Get the user's local timezone
     * @returns The IANA timezone identifier string for the user's local timezone
     */
    static getLocalTimeZone(): string;
}
export { TimeZone };
export default TimeZone;