This library contains pure, immutable functions to query time zones, convert dates among them and parse and form date strings. The functions are grouped in three modules according to their usage scenarios.
Load the main module in an application using CommonJS modules:
const { findTimeZone, getZonedTime } = require('timezone-support')Load the main module in an application using ES6 modules:
import {
findTimeZone, getZonedTime
} from './node_modules/timezone-support/src/index.js'Load the main module in the browser with plain JavaScript:
<script src="./node_modules/timezone-support/dist/index.umd.js"></script>
<script>
(() => {
const { findTimeZone, getZonedTime } = window.timezoneSupport
})()
</script>You can also load a specific version from CDN, for example: https://unpkg.com/timezone-support@2.0.2/dist/index.umd.js.
Modules in the src directory require ES6 including the new module syntax, as available in Node.js 8 and newer. Modules in the dist directory require ES5 and follow the CommonJS standard for older Node.js releases. Files dist/*.umd.js require ES5, are minified and follow the UMD standard to work well in web browsers.
Main package module. The most usually chosen module with time zone lookup and date conversion functionality. Includes the bundled time zone data. Contains all functions from the module lookup-convert except for populateTimeZones.
const { ... } = require('timezone-support')
import { ... } from './node_modules/timezone-support/src/index.js'
<script src="./node_modules/timezone-support/dist/index.umd.js"></script>
Offers the time zone lookup and date conversion functionality, like the index module, but does not include the time zone data. You have to initialize the library with your own the time zone data by calling populateTimeZones before the first usage.
const { ... } = require('timezone-support/dist/lookup-convert')
import { ... } from './node_modules/timezone-support/src/lookup-convert.js'
<script src="./node_modules/timezone-support/dist/lookup-convert.umd.js"></script>
Offers a minimal date parsing and formatting support, if you want to use this library in an end-user application. Recognizes only numeric formatting tokens and no locale support.
const { ... } = require('timezone-support/dist/parse-format')
import { ... } from './node_modules/timezone-support/src/parse-format.js'
<script src="./node_modules/timezone-support/dist/parse-format.umd.js"></script>
Functions converting to an arbitrary time zone accept either a Date object, or a UNIX timestamp. (The UNIX timestamp is the time from the epoch in milliseconds, as returned by date.prototype.getTime.) They produce a complete time object. Functions converting from an arbitrary time zone accept a time object and return the UNIX timestamp.
convertDateToTime(date: Date) : Time
Returns a complete time object equal to the given date using the the local time for the time zone information.
date- a sourceDateobject
const { findTimeZone, convertDateToTime } = require('timezone-support')
const berlin = findTimeZone('Europe/Berlin')
const date = new Date()
const berlinTime = convertDateToTime(date, berlin)
// Returns {
// year, month, day, hours, minutes, seconds, milliseconds,
// dayOfWeek, epoch,
// zone: { abbreviation, offset }
// }convertTimeToDate(time: Time) : Date
Returns a Date object equal to the given time object, converting the time zone of the source time object to the local time.
time- a complete time object
const { findTimeZone, convertTimeToDate } = require('timezone-support')
const berlin = findTimeZone('Europe/Berlin')
const berlinTime = { year: 2018, month: 9, day: 2, hours: 10, minutes: 0,
zone: { abbreviation: 'CEST', offset: -120 } }
const date = convertTimeToDate(date, berlin)
// Returns a date in the local timefindTimeZone(name: string) : object
Returns an object with time zone data for the given canonical time zone name. Recognizes deprecated time zone names too. Throws an error, if no time zone can be found for the given name.
name- a canonical time zone name
const { findTimeZone } = require('timezone-support')
const berlin = findTimeZone('Europe/Berlin')
// Returns an object to be used by other functionsSee IANA time zones for the complete available list.
formatZonedTime(time: Time, format: string) : string
Formats a time object using a custom format pattern to a string.
const { formatZonedTime } = require('timezone-support/dist/parse-format')
const time = { year: 2018, month: 9, day: 2, hours: 10, minutes: 0,
zone: { abbreviation: 'CEST', offset: -120 } }
const format = 'D.M.YYYY H:mm zZ'
const output = formatZonedTime(time, format)
// Returns "2.9.2018 10:00 CEST+02:00"The following tokens are recognized in the format string:
| Unit | Token | Result examples |
|---|---|---|
| Month | M | 1, 2, ..., 12 |
| MM | 01, 02, ..., 12 | |
| Day of month | D | 1, 2, ..., 31 |
| DD | 01, 02, ..., 31 | |
| Day of week | d | 0, 1, ..., 6 |
| Year | YY | 00, 01, ..., 99 |
| YYYY | 1900, 1901, ..., 2099 | |
| AM/PM | A | AM, PM |
| a | am, pm | |
| Hour | H | 0, 1, ... 23 |
| HH | 00, 01, ... 23 | |
| h | 1, 2, ..., 12 | |
| hh | 01, 02, ..., 12 | |
| Minute | m | 0, 1, ..., 59 |
| mm | 00, 01, ..., 59 | |
| Second | s | 0, 1, ..., 59 |
| ss | 00, 01, ..., 59 | |
| 1/10 of second | S | 0, 1, ..., 9 |
| 1/100 of second | SS | 00, 01, ..., 99 |
| Millisecond | SSS | 000, 001, ..., 999 |
| Timezone abbreviation | z | CET, CEST, EST, EDT, ... |
| Timezone offset to UTC | Z | -01:00, +00:00, ... +12:00 |
| ZZ | -0100, +0000, ..., +1200 |
To escape characters in the format string, wrap them in square brackets (e.g. [GMT]). Punctuation symbols (-:/.()) do not need to be wrapped.
getUnixTime(time: Time, timeZone?: object) : number
Returns a Unix timestamp (UTC) for the given incomplete time object converted from the given time zone.
time- the source (incomplete) time objecttimeZone- the time zone object returned byfindTimeZone
const { findTimeZone, getUnixTime } = require('timezone-support')
const berlin = findTimeZone('Europe/Berlin')
const berlinTime = { year: 2018, month: 9, day: 2, hours: 10, minutes: 0 }
const date = getZonedTime(date, berlin)
// Returns the UNIX timestamp (UTC) in millisecondsThis method is usually used with incomplete time objects, which are entered by the user, or parsed from date strings without time zone information. (A complete time object contains properties epoch with the UTC time and zone with the time zone information. An incomplete one has to contain the date at least - year, month and day.)
The returned object is supposed to be passed to other functions, which use it to convert dates. It is not supposed to be inspected outside of this library.
getUTCOffset(date: number|Date, timeZone: object) : object
Returns the offset to UTC for a given date and the specific time zone, together with the time zone abbreviation.
date- either aDateobject, or a UNIX timestamp returned bydate.prototype.getTimetimeZone- the time zone object returned byfindTimeZone
const { findTimeZone, getUTCOffset } = require('timezone-support')
const berlin = findTimeZone('Europe/Berlin')
const date = new Date()
const timeZoneOffset = getUTCOffset(date, berlin)
// Returns {
// abbreviation: 'CET'
// offset: -60
// }The abbreviation value contains a string with the time zone abbreviation as it was used at the given time. It may depend on daylight-saving changes and country politics. The offset value contains a number with the difference from the zoned time to UTC in minutes. If you add it to the timestamp of the zoned time, you will get the timestamp in UTC. It is consistent with the value returned by Date.prototype.getTimezoneOffset for the local time.
getZonedTime(date: number|Date, timeZone: object) : Time
Returns a complete time object for the given date converted to the given time zone. The conversion uses the UNIX timestamp (UTC) of the date.
date- either aDateobject, or a UNIX timestamp returned bydate.prototype.getTimetimeZone- the time zone object returned byfindTimeZone
const { findTimeZone, getZonedTime } = require('timezone-support')
const berlin = findTimeZone('Europe/Berlin')
const date = new Date()
const time = getZonedTime(date, berlin)
// Returns {
// year, month, day, hours, minutes, seconds, milliseconds,
// dayOfWeek, epoch,
// zone: { abbreviation, offset }
// }listTimeZones() : Array<string>
Returns a list of canonical time zone names recognized by this library. Either included in the index module (see the [moment-timezone's latest data]), or initialized by the populateTimeZones method.
const { listTimeZones } = require('timezone-support')
const timeZones = listTimeZones()
// Returns [
// 'Africa/Abidjan',
// ...
// ]See IANA time zones for the complete available list.
parseZonedTime(input: string, format: string) : Time
Parses a date string using a custom format pattern to a time object. If the string does not contain a time zone offset, it can be added by setTimeZone.
const { parseZonedTime } = require('timezone-support/dist/parse-format')
const input = '2.9.2018 10:00 CEST+02:00'
const format = 'D.M.YYYY H:mm zZ'
const time = parseZonedTime(input, format)
// Returns { year: 2018, month: 9, day: 2, hours: 10, minutes: 0,
// zone: { abbreviation: 'CEST', offset: -120 } }The following tokens are recognized in the format string:
| Token | Input example | Description |
|---|---|---|
YY |
18 | Two-digit year |
YYYY |
2018 | Four-digit year |
M |
1-12 | Month, beginning at 1 |
MM |
01-12 | Month, 2-digits |
D |
1-31 | Day of month |
DD |
01-31 | Day of month, 2-digits |
H |
0-23 | Hours |
HH |
00-23 | Hours, 2-digits |
h |
1-12 | Hours, 12-hour clock |
hh |
01-12 | Hours, 12-hour clock, 2-digits |
m |
0-59 | Minutes |
mm |
00-59 | Minutes, 2-digits |
s |
0-59 | Seconds |
ss |
00-59 | Seconds, 2-digits |
S |
0-9 | Hundreds of milliseconds, 1-digit |
SS |
00-99 | Tens of milliseconds, 2-digits |
SSS |
000-999 | Milliseconds, 3-digits |
z |
EST | Time zone abbreviation |
Z |
-5:00 | Offset from UTC, 2-digits |
ZZ |
-0500 | Compact offset from UTC, 2-digits |
A |
AM PM | Post or ante meridiem, upper-case |
a |
am pm | Post or ante meridiem, lower-case |
To escape characters in the format string, wrap them in square brackets (e.g. [GMT]). Punctuation symbols (-:/.()) do not need to be wrapped.
populateTimeZones(data: object)
Initializes the time zone data and should be called just once, when the application starts. Needed only if you load the lookup-convert module instead of the index module.
The data object is supposed to contain packed time zone data as an array of strings and deprecated time zone names as an array of strings:
const data = {
zones: [
'Europe/Berlin|CET CEST CEMT|-10 -20 -30|0101...|-2aFe0 11d0 ...|41e5',
...
],
links: [
'Europe/Prague|Europe/Bratislava'
...
]
}See the moment-timezone's latest data as an example of the full data, which you can take a smaller part of to your application. This library includes limited data for this decade and two other year spans. Read also abot generation of custom time zone data, which allows production of a module with smaller, limited time zone data for other time periods.
If this function is called later, than during the application startup, the behaviour of this module may be unpredictable. Some time zone data might be used and cached in the application. You should avoid re-initialization to prevent hidden errors.
This function is not exported from the index module to prevent usage mistakes, because that module includes the complete time zone data already.
const { populateTimeZones, findTimeZone, getZonedTime } = require('timezone-support/dist/lookup-convert')
const data = require('timezone-support/dist/data-2012-2022')
// Get the time zone support ready to handle dates from years 2012-2022.
populateTimeZones(data)
const berlin = findTimeZone('Europe/Berlin')
const isoString = '2018-09-30T09:19:17.276Z'
const berlinTime = getZonedTime(new Date(isoString), berlin)setTimeZone(time: Date|Time, timeZone: object, options?: object) : Time
Returns a new complete time object for the given one completed with the given time zone. The completion will add the UNIX timestamp (UTC) and the time zone information.
time- aDateobject or a source time objecttimeZone- the time zone object returned byfindTimeZoneoptions- an object with options for the function calloptions.useUTC- a boolean flag to choose getters of theDateinstance;truewill choose the UTC getters (getUTCFullYear,getUTCMonth, ...) andfalsewill choose the local-time getters (getFullYear,getMonth, ...)
const { findTimeZone, setTimeZone } = require('timezone-support')
const berlin = findTimeZone('Europe/Berlin')
const time = { year: 2018, month: 9, day: 2, hours: 10, minutes: 0 }
const berlinTime = setTimeZone(time, berlin)
// Returns {
// year, month, day, hours, minutes, seconds, milliseconds,
// dayOfWeek, epoch,
// zone: { abbreviation, offset }
// }This method is supposed to be used with incomplete time objects, which are entered by the user, or parsed from date strings without time zone information.
Another possibility is to supply the time by a Date object, from which the date parts can be obtained by the corresponding local-time getters (getFullYear, getMonth, ...):
const { findTimeZone, setTimeZone } = require('timezone-support')
const berlin = findTimeZone('Europe/Berlin')
const date = new Date(2018, 8, 2, 10, 0)
const berlinTime = setTimeZone(date, berlin, { useUTC: false })
// Returns {
// year, month, day, hours, minutes, seconds, milliseconds,
// dayOfWeek, epoch,
// zone: { abbreviation, offset }
// }Finally the source Date object, from which the date parts can be obtained by the corresponding UTC getters (getUTCFullYear, getUTCMonth, ...):
const { findTimeZone, setTimeZone } = require('timezone-support')
const berlin = findTimeZone('Europe/Berlin')
const date = new Date(Date.UTC(2018, 8, 2, 10, 0))
const berlinTime = setTimeZone(date, berlin, { useUTC: true })
// Returns {
// year, month, day, hours, minutes, seconds, milliseconds,
// dayOfWeek, epoch,
// zone: { abbreviation, offset }
// }Date objects in the last two scenarios are initialized only for formatting or conversion purposes, because other methods, than the date part getters, deliver wrong results. Such "invalid" Date instances should exist only temporarily in a restricted scope. They should not be shared widely in the application to prevent mistakes from happening. The local time in a valid Date object has to match the UTC time maintained by the same object.
If you want to limit the time zone data to improve performance of your application by reducing the size of the JavaScript code, you can use the command-line tool included in this package:
Usage: create-timezone-data [options] <first year> <last year>
Generates time zone data for a selected year range.
Options:
-V, --version output the version number
-a, --all-years includes all available years
-c, --as-cjs-module format the time zone data as a CommonJS module
-d, --as-amd-module format the time zone data as an AMD module
-m, --as-module format the time zone data as a JavaScript module
-n, --umd-name <name> UMD global export name, if not "timezoneData"
-o, --output-file <file> write the time zone data to a file
-u, --as-umd-module format the time zone data as an UMD module
-o, --output-file <file> write the time zone data to a file
-h, --help output usage information
Time zone data are printed on the standard output as JSON by default.
Examples:
$ create-timezone-data 2012 2022
$ create-timezone-data -m -o custom-data.js 1970 2038The module generated by this tool exposes a data object as a default export, which is expected by the function populatePluralData.