- 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.
Topics
Resources
License
Security policy
Uh oh!
There was an error while loading.Please reload this page.
Stars
Watchers
Forks
Packages0
Uh oh!
There was an error while loading.Please reload this page.