- Notifications
You must be signed in to change notification settings - Fork2
A fast, lightweight, zero-dependency library to translate between Time Zones and UTC with native Intl.DateTimeFormat in ~100 LoC.
License
therootcompany/tz.js
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
A fast, lightweight, zero-dependency library to translate between Time Zones and UTC with nativeIntl.DateTimeFormatin ~100 LoC. For Node.js & Browsers.
XTZ is a poor man'sTemporal polyfill, but just for time zones.
Demo:https://therootcompany.github.io/tz.js/
// What's the current time, in ISO+Offset format?TZ.toLocalISOString(newDate());// "2021-11-07T03:15:59.000-0500"TZ.timeZone();// "America/New_York"
// What will the ISO+Offset datetime string be// when it's 3:15am in New York?//// (Relative New York time to Absolute ISO+Offset Time)TZ.toOffsetISOString("2021-11-07 03:15:59.000","America/New_York");// "2021-11-07T03:15:59.000-0500"
// What time will it be in New York// when it's 7:15am UTC?//// (Absolute UTC Zulu time to Relative New York time)TZ.toTimeZoneISOString("2021-03-14T07:15:59.000Z","America/New_York");// "2021-03-14T03:15:59.000-0400"
- Translate a UTC Zulu time to a Time Zone
- Translate a Zoned time to ISO+Offset
- HandlesDaylight Savings, Weird Time Zones, etc...
- Well-tested
npm run test
- Well-tested
- Lightweight (No deps)
- 5kb Source + Comments
- 2.5kb Minified
- <1kb
gzipd
Compatible with Browsers, and Node.js.
<scriptsrc="https://unpkg.com/xtz@latest/xtz.min.js"></script>
varTZ=window.XTZ;
npm install --save xtz
varTZ=require("xtz");
Seehttps://therootcompany.github.io/tz.js/.
I live-streamed the creation of this entire project.
If you'd like to learn how I did it and what challenges I encountered, you can watch here:https://www.youtube.com/playlist?list=PLxki0D-ilnqa6horOJ2G18WMZlJeQFlAt
(though there have been a few minor updates and bug fixes off-camera)
toLocalISOString(dateOrNull)toTimeZone(utcDate, timeZone)toTimeZoneISOString(isoString, timeZone)fromTimeZone(dtString, timeZone)toOffsetISOString(dtString, timeZone)
Convert UTC into a Target Time Zone
Use ISO timestamps representing the absolute UTC time (ISO with or without offset):
"2021-11-07T08:15:59.000Z"
varutcDate=TZ.toTimeZone("2021-03-14T07:15:59.000Z","America/New_York");// {// year: 2021, month: 2, day: 14,// hour: 3, minute: 15, second: 59, millisecond: 0,// offset: -240, timeZoneName: "Eastern Daylight Time"// }utcDate.toISOString();// "2021-03-14T03:15:59.000-0400"// (same as "2021-11-07T07:15:59.000Z")
TZ.toTimeZoneISOString("2021-11-07T08:15:59.000Z","America/New_York");// "2021-11-07T03:15:59.000-0500"
vartzDate=TZ.toTimeZone("2021-11-07T08:15:59.000Z","America/New_York");
vartzDate=TZ.toTimeZone(newDate("2021-11-07T08:15:59.000Z"),"America/New_York");
console.log(tzDate.toISOString());// "2021-11-07T03:15:59.000-0500"
newDate("2021-11-07T03:15:59.000-0500").toISOString());// "2021-11-07T08:15:59.000Z"
Convert a Target Time Zone into ISO
Use ISO-like timestamps representing thelocal time in the target time zone:
"2021-11-0 03:15:59.000"
vartzDate=TZ.fromTimeZone("2021-11-07 03:15:59.000","America/New_York");// {// year: 2021, month: 10, day: 7,// hour: 3, minute: 15, second: 59, millisecond: 0,// offset: -300, timeZoneName: "Eastern Standard Time"// }tzDate.toISOString();// "2021-11-07T03:15:59.000-0500"// (same as "2021-11-07T08:15:59.000Z")
TZ.toOffsetISOString("2021-11-07 03:15:59.000","America/New_York");// "2021-11-07T03:15:59.000-0500"
varutcDate=TZ.fromTimeZone("2021-11-07 03:15:59.000","America/New_York");
You can also use a date object as the source time, but the date's UTC time will be treated asrelative to timezone rather than absolute (this is a workaround for JavaScript's lack of bi-directional timezone support).
varutcDate=TZ.fromTimeZone(newDate("2021-11-07T03:15:59.000Z"),"America/New_York");
utcDate.toISOString();// "2021-11-07T03:15:59.000-0500"
In 2021 Daylight Savings (in the US)
- begins at 2am on March 14th (skips to 3am)
- ends at 2am on November 7th (resets to 1am)
Q: What happens in March when 2am is skipped?
- A: Although 2am is not a valid time, rather than throwing an error this library will resolve to 1am instead, whichis an hour early in real ("tick-tock" or "monotonic") time.
varutcDate=TZ.fromTimeZone("2021-03-14 02:15:59.000","America/New_York");utcDate.toISOString();// "2021-03-14T02:15:59.000-0400"// (same as "2021-03-14T01:15:59.000-0500")
Q: What happens in November when 1am happens twice?
- A: Although both 1ams are distinguishable with ISO offset times, only the first can be resolved from a local timewith this library.
varutcDate=TZ.fromTimeZone("2021-11-07 01:15:59.000","America/New_York");utcDate.toISOString();// "2021-11-07T01:15:59.000-0400", same as "2021-11-07T05:15:59.000Z"// (an hour before the 2nd 1am at "2021-11-07T01:15:59.000-0500")
See theFull List of Time Zones on Wikipedia.
Common Zones for Testing:
America/New_York -0500America/Denver -0700America/Phoenix -0700 (No DST)America/Los_Angeles -0800UTC ZAustralia/Adelaide +0930 (30-min, has DST)Asia/Kathmandu +0545 (No DST, 45-min)Asia/Kolkata +0530 (No DST, 30-min)
About
A fast, lightweight, zero-dependency library to translate between Time Zones and UTC with native Intl.DateTimeFormat in ~100 LoC.