TZIntl.js — International Date-Time Conversion

This is a demo widget for the use of TZIntl.js and TZProvider.js. Use mouse, cursor keys and/or initial letter keys to navigate.
You may set an initial time zone by supplying a URL parameter (or hash fragment) "tz" as in "?tz=Europe/London".

The Libraries

`TZIntl`

TZIntl is a lightweight and compatible abstraction of the Intl.DateTimeFormat interface for converting JS-dates to localized date-time objects. TZIntl provides the following static methods:

TZIntl.getDateTime(timeZoneString, date)

Returns an object representing a converted date for the given time zone.

Arguments
- timeZoneString (optional): A string holding the target IANA time zone name. Defaults to local time.
- date (optionl): The date to convert, any of
  - a Date object,
  - a valid JS date string,
  - a value or array of arguments to construct a Date object.
  Defaults to current time (new Date()).
Return Value (object)

TZIntl.getDateTime() returns an object with numeric properties for the converted date and time, as well as some other useful properies:
```
{
    year:           number,
    month:          number,   // 1 .. 12
    day:            number,   // 1 .. 31
    hour:           number,   // 0 .. 23
    minute:         number,   // 0 .. 59
    second:         number,   // 0 .. 59
    weekday:        number,   // index of localized weekday (0..6: Sun - Sat)
    timeZoneName:   string,   // short name computed by browser (may vary)
    offsetMinutes:  number,   // offset to UTC in minutes
    offsetString:   string,   // +/-hh:mm       (e.g., "+00:00", "-05:00", "+13:45")
    GMTOffsetName:  string,   // GMT[+/-h[:mm]] (e.g., "GMT", "GMT-5", "GMT+13:45")
    toISOString:    function  // returns "YYYY-MM-DDThh:mm:ss<offset>"
                              // where  <offset> is either "Z" or offsetString
}
```
Mind that month is, unlike the value returned by Date.prototype.getMonth(), the ordinal (1-based) value of the month. Method toISOString() returns a string similar to the one returned by the homonymous method of a Date object, but as a localized timestamp without milliseconds.

On error returns a property error in an otherwise empty object:
```
{
    "error":         string
}
```
where the string provides any of the following error reasons:
- "time zone name not implemented"
- "invalid date string"
- "invalid date value"
- "invalid date arguments"
Returns null if no implementation of Intl.DateTimeFormat could be found.
TZIntl.isSupported()

Returns a boolean value for the support of Intl.DateTimeFormat in the browser:

Arguments

None.

Return Value (boolean)
- true: Intl.DateTimeFormat is implemented.
- false: No implementention of Intl.DateTimeFormat could be found.
Note:
Intl.DateTimeFormat is supported by all modern browsers, but is missing or only partly implemented on MSIE. You may consider using a polyfill, if support for MSIE is required.
TZIntl.isSupportedTimeZone(candidateString)

Checks if the provided string is a valid IANA time zone name supported by the browser.

Argument
- candidateString: A string to be tested as a time zone name.
Return Value (boolean)
- true: the provided string evaluates as a supported time zone name.
- false: the provided string failed to evaluate as a valid time zone name.
TZIntl.dd(number)

A utility function to transform a number to a zero-padded double-digit string.

Argument
- number: The number to transform.
  (Caution: No type checks are performed! This is just an exposed internal utility that may be useful for common tasks related to the composition of date-time related strings.)
Return Value (string)
- string: zero-padded double-digit string

Example

function getTimeFor(tzString, date) {
    const tzDate = TZIntl.getDateTime(tzString, date);  // get date-time object
    const dd = TZIntl.dd;                               // returns a double-digit string
    const weekdays = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
    let s = tzString || "Local Time";
    if (tzDate && !tzDate.error) {
        s += " ("
           + tzDate.GMTOffsetName                  // evaluted GMT-based time zone
           + ", "
           + tzDate.offsetString                   // evaluted offset to UTC: +/-hh:mm
           + ")\n" 
           + weekdays[tzDate.weekday]
           +  ", "
           + tzDate.year
           + "-"
           + dd(tzDate.month)
           + "-"
           + dd(tzDate.day)
           + " "
           + dd(tzDate.hour)
           + ":"
           + dd(tzDate.minute)
           + ":"
           + dd(tzDate.second)
           + " "
           + tzDate.timeZoneName                   // short name computed by browser
           + "\nISO: " + tzDate.toISOString();
    }
    else {
        s += ": " + (tzDate? tzDate.error : "[not implemented]");
    }
    return s;
}

const date = new Date("24 Dec 2021 04:30:20 UTC");

console.log( date.toUTCString() );
console.log( getTimeFor("America/New_York", date) );
console.log( getTimeFor("Asia/Tokyo", date) );
console.log( getTimeFor("Europe/London", date) );
console.log( getTimeFor("UTC", date) );

/*
Fri, 24 Dec 2021 04:30:20 GMT

America/New_York (GMT-5, -05:00)
Thu, 2021-12-23 23:30:20 EST
ISO: 2021-12-23T23:30:20-05:00

Asia/Tokyo (GMT+9, +09:00)
Fri, 2021-12-24 13:30:20 GMT+9
ISO: 2021-12-24T13:30:20+09:00

Europe/London (GMT, +00:00)
Fri, 2021-12-24 04:30:20 GMT
ISO: 2021-12-24T04:30:20Z

UTC (GMT, +00:00)
Fri, 2021-12-24 04:30:20 UTC
ISO: 2021-12-24T04:30:20Z
*/

console.log( getTimeFor("America/New_York") );
// current time in New York (default current time)

console.log( getTimeFor(null, date) );
// date as local time (default time zone)

`TZProvider`

However, which time zone names are there, and which ones are actually supported by the browser? Notably, support may vary and only "UTC" is guaranteed to work. While there is an experimental method Intl.supportedValuesOf("timeZone") to enumerate supported time zone names, this is currently (as of Dec. 2021) supported solely by Mozilla/Firefox (beginning with release number 93).
TZProvider provides a compact abstraction by using either the built-in enumeration or by testing the browser for any of the common and official IANA time zone names and enumerating those supported.

TZProvider is an independent stand-alone library providing the following static methods:

TZProvider.enumerate(all)

Argument (boolean)
- all: boolean flag, whether or not to include aliases.
  - true: return all supported time zone names including aliases.
  - false: return unique time zones only, like Intl.supportedValuesOf("timeZone").
  Mind that there are differences between browsers, regarding which time zones are implemented as original ones and which ones as aliases. E.g., Webkit/Safari implements "Arctic/Longyearbyen" as an original time zone, while it is implemented as an alias to "Europe/Oslo" in Mozilla/Firefox and is not included in the list generated by Intl.supportedValuesOf("timeZone").
Return Value (array)

Returns a sorted list (array of string) with supported time zone names, like
```
[
    "Africa/Abidjan",
    "Africa/Accra",
    "Africa/Addis_Ababa",
    ( … )
    "UTC",
    "W-SU",
    "WET"
]
```
Returns an empty array, if no implementation could be found.

See here for a list of common time zone names supported by the browser and the time zone names these actually resolve to in the given browser.
TZProvider.isSupportedValue(candidateString)

Checks if the provided string is a valid IANA time zone name supported by the browser.
(Similar to TZIntl.isSupportedTimeZone(), see above.)

Argument
- candidateString: A string to be tested as a time zone name.
Return Value (boolean)
- true: the provided string evaluates as a supported time zone name.
- false: the provided string failed to evaluate as a valid time zone name.

License

MIT — do not strip heading comments.

Copyright 2021 Norbert Landsteiner <www.masswerk.at>

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Version

1.1 — added support for time zone aliases.

Download

tzintl.js TZIntl (source)
tzintl.min.js TZIntl minified, 2.8 KB
tzprovider.js TZProvider (source)
tzprovider.min.js TZProvider minified, 7.3 KB

Author

Norbert Landsteiner, 2021, www.masswerk.at

If you want to support me:

TZIntl.js — International Date-Time Conversion

The Libraries

`TZIntl`

`TZIntl.getDateTime(timeZoneString, date)`

Arguments

Return Value (`object`)

`TZIntl.isSupported()`

Arguments

Return Value (`boolean`)

`TZIntl.isSupportedTimeZone(candidateString)`

Argument

Return Value (`boolean`)

`TZIntl.dd(number)`

Argument

Return Value (`string`)

Example

`TZProvider`

`TZProvider.enumerate(all)`

Argument (`boolean`)

Return Value (`array`)

`TZProvider.isSupportedValue(candidateString)`

Argument

Return Value (`boolean`)

License

Version

Download

Author

TZIntl.js — International Date-Time Conversion

The Libraries

TZIntl

TZIntl.getDateTime(timeZoneString, date)

Arguments

Return Value (object)

TZIntl.isSupported()

Arguments

Return Value (boolean)

TZIntl.isSupportedTimeZone(candidateString)

Argument

Return Value (boolean)

TZIntl.dd(number)

Argument

Return Value (string)

Example

TZProvider

TZProvider.enumerate(all)

Argument (boolean)

Return Value (array)

TZProvider.isSupportedValue(candidateString)

Argument

Return Value (boolean)

License

Version

Download

Author

`TZIntl`

`TZIntl.getDateTime(timeZoneString, date)`

Return Value (`object`)

`TZIntl.isSupported()`

Return Value (`boolean`)

`TZIntl.isSupportedTimeZone(candidateString)`

Return Value (`boolean`)

`TZIntl.dd(number)`

Return Value (`string`)

`TZProvider`

`TZProvider.enumerate(all)`

Argument (`boolean`)

Return Value (`array`)

`TZProvider.isSupportedValue(candidateString)`

Return Value (`boolean`)