Compare commits

...

14 Commits

Author SHA1 Message Date
AJ ONeal 5c35bd2148 fix typo, clarify comment 2021-05-28 08:37:35 -06:00
AJ ONeal 8b8af276ef add build command 2021-05-28 08:28:18 -06:00
AJ ONeal 72f68a10f0 fix bad description 2021-05-28 08:28:01 -06:00
AJ ONeal 4de76c4ccc fix typo: 2nd 2am => 2nd 1am 2021-05-28 08:08:53 -06:00
AJ ONeal dea25807e0 make current time copy/paste easier 2021-05-28 02:16:33 -06:00
AJ ONeal 6d6635b838 1.0.1 2021-05-28 02:14:17 -06:00
AJ ONeal 7ea37d8772 typo fix 2021-05-28 02:14:13 -06:00
AJ ONeal 37181d65a0 bugfix: respect updated tz values 2021-05-28 02:09:15 -06:00
AJ ONeal 77300f69b2 add demo link 2021-05-28 02:04:29 -06:00
AJ ONeal dacf0eaaf2 update docs with demo 2021-05-28 02:03:49 -06:00
AJ ONeal a0172f68a3 add demo page 2021-05-28 01:55:01 -06:00
AJ ONeal ff9e266052 make Prettier 2021-05-28 00:57:42 -06:00
AJ ONeal aaa31a25b9 note tests 2021-05-28 00:51:14 -06:00
AJ ONeal 8ddd8cd2f5 update cdn link, put browser first 2021-05-28 00:42:21 -06:00
9 changed files with 763 additions and 580 deletions

1
.prettierignore Normal file
View File

@ -0,0 +1 @@
*.min.js

7
.prettierrc.json Normal file
View File

@ -0,0 +1,7 @@
{
"printWidth": 80,
"tabWidth": 2,
"singleQuote": false,
"bracketSpacing": true,
"semi": true
}

View File

@ -1,10 +1,12 @@
# [xtz.js](https://github.com/therootcompany/tz.js)
A fast, lightweight, zero-dependency library to
translate between Time Zones and UTC with native
`Intl.DateTimeFormat` in ~100 LoC. For Node.js & Browsers.
A fast, lightweight, zero-dependency library to translate between Time Zones and UTC with native `Intl.DateTimeFormat`
in ~100 LoC. For Node.js & Browsers.
XTZ is a poor man's Temporal polyfill, but just for time zones.
[![](./xtz-preview.png)](https://therootcompany.github.io/tz.js/)
XTZ is a poor man's `Temporal` polyfill, but just for time zones. \
Demo: <https://therootcompany.github.io/tz.js/>
> What UTC time will it be when it's 3:15am in New York?
@ -17,7 +19,7 @@ TZ.toUTCISOString("2021-11-07 03:15:59.000", "America/New_York");
```js
var tzDate = TZ.toUTC("2021-11-07 03:15:59.000", "America/New_York");
// {
// year: 2021, month: 11, day: 7,
// year: 2021, month: 10, day: 7,
// hour: 3, minute: 15, second: 59, millisecond: 0,
// offset: -300, timeZoneName: "Eastern Standard Time"
// }
@ -38,7 +40,7 @@ TZ.toTimeZoneISOString("2021-03-14T07:15:59.000Z", "America/New_York");
```js
var utcDate = TZ.toTimeZone("2021-03-14T07:15:59.000Z", "America/New_York");
// {
// year: 2021, month: 3, day: 14,
// year: 2021, month: 2, day: 14,
// hour: 3, minute: 15, second: 59, millisecond: 0,
// offset: -240, timeZoneName: "Eastern Daylight Time"
// }
@ -53,12 +55,23 @@ utcDate.toISOString();
- [x] Translate a UTC time to a Time Zone
- [x] Translate a Zoned time to UTC
- [x] Handles **Daylight Savings**, Weird Time Zones, etc...
- [x] Well-tested `npm run test`
- [x] Lightweight (No deps)
- 5kb Source + Comments
- 2.5kb Minified
- <1kb `gzip`d
Compatible with Node.js & Browsers.
Compatible with Browsers, and Node.js.
## Browsers
```html
<script src="https://unpkg.com/xtz@latest/xtz.min.js"></script>
```
```js
var TZ = window.XTZ;
```
## Node.js & Webpack
@ -70,15 +83,9 @@ npm install --save xtz
var TZ = require("xtz");
```
## Browsers
## Demo
```html
<script src="https://unpkg.com/xtz@1.0.0-rc.1/xtz.min.js"></script>
```
```js
var TZ = window.XTZ;
```
See <https://therootcompany.github.io/tz.js/>.
# API
@ -91,7 +98,7 @@ var TZ = window.XTZ;
> Convert UTC into a Target Time Zone
Use ISO timestamps representing the absolute UTC time in the target time zone:
Use ISO timestamps representing the absolute UTC time (with or without offset):
```txt
"2021-11-07T08:15:59.000Z"
@ -138,7 +145,7 @@ new Date("2021-11-07T03:15:59.000-0500").toISOString());
Use ISO-like timestamps representing the _local_ time in the target time zone:
```txt
"2021-11-0 T03:15:59.000"
"2021-11-0 03:15:59.000"
```
Convert directly to an offset ISO String:
@ -154,7 +161,8 @@ Or our bespoke date object:
var utcDate = TZ.toUTC("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 as **_relative to time zone_** rather than absolute (this is a workaround for JavaScript's lack of bi-directional timezone support).
You can also use a date object as the source time, but the date's UTC time will be treated as **_relative to time
zone_** rather than absolute (this is a workaround for JavaScript's lack of bi-directional timezone support).
```js
var utcDate = TZ.toUTC(
@ -172,14 +180,15 @@ utcDate.toISOString();
> In 2021 Daylight Savings (in the US)
>
> - begins at 2am on March 14th
> - ends at 2am on November 7th
> - begins at 2am on March 14th (skips to 3am)
> - ends at 2am on November 7th (resets to 1am)
>
> See <https://www.timeanddate.com/time/change/usa>.
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, which is an hour early in real ("tick-tock" or "monotonic") time.
- A: Although 2am is not a valid time, rather than throwing an error this library will resolve to 1am instead, which
is an hour early in real ("tick-tock" or "monotonic") time.
```js
var utcDate = TZ.toUTC("2021-03-14 02:15:59.000", "America/New_York");
utcDate.toISOString();
@ -187,14 +196,15 @@ Q: What happens in March when 2am is skipped?
// (same as "2021-03-14T01:15:59.000-0500")
```
Q: What happens in November when 2am happens twice?
Q: What happens in November when 1am happens twice?
- A: Although both 2ams are distinguishable with ISO offset times, only the first can be resolved from a local time with this library.
- A: Although both 1ams are distinguishable with ISO offset times, only the first can be resolved from a local time
with this library.
```js
var utcDate = TZ.toUTC("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 2am at "2021-11-07T01:15:59.000-0500")
// (an hour before the 2nd 1am at "2021-11-07T01:15:59.000-0500")
```
# List of Time Zones

View File

@ -22,9 +22,7 @@ var XTZ;
console.info();
console.info("\t// during daylight savings");
console.info(
`\tXTZ.toUTC("2021-03-14 08:15:59.000", "America/New_York")`
);
console.info(`\tXTZ.toUTC("2021-03-14 08:15:59.000", "America/New_York")`);
console.info(`\ttzDate.toISOString()`);
tzDate = XTZ.toUTC("2021-03-14 08:15:59.000", "America/New_York");
console.info(
@ -35,9 +33,7 @@ var XTZ;
console.info();
console.info("\t// during standard time");
console.info(
`\tXTZ.toUTC("2021-11-07 08:15:59.000", "America/New_York")`
);
console.info(`\tXTZ.toUTC("2021-11-07 08:15:59.000", "America/New_York")`);
console.info(`\ttzDate.toISOString()`);
tzDate = XTZ.toUTC("2021-11-07 08:15:59.000", "America/New_York");
console.info(
@ -52,9 +48,7 @@ var XTZ;
// Time Zone-relative time translated to UTC
//
function demo2() {
console.info(
"What time is it in New York at 8:15am on March 14th UTC?"
);
console.info("What time is it in New York at 8:15am on March 14th UTC?");
console.info();
console.info("\t// during daylight savings");
@ -71,9 +65,7 @@ var XTZ;
console.info();
console.info("\t// during standard time");
console.info(
`\tXTZ.toUTC("2021-11-07T08:15:59.000Z", "America/New_York")`
);
console.info(`\tXTZ.toUTC("2021-11-07T08:15:59.000Z", "America/New_York")`);
console.info(`\ttzDate.toISOString()`);
tzDate = XTZ.toUTC("2021-11-07T08:15:59.000Z", "America/New_York");
console.info(

175
index.html Normal file
View File

@ -0,0 +1,175 @@
<!DOCTYPE html>
<html lang="en" class="no-js">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width" />
<title>Convert TimeZones in Your Browser</title>
<link rel="canonical" href="https://therootcompany.github.io/tz.js/" />
<meta name="theme-color" content="#FF00FF" />
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/spcss@0.7.0" />
<style>
input {
width: 24em;
}
</style>
</head>
<body>
<!-- Content -->
<h1>
<a href="https://github.com/therootcompany/tz.js" target="_blank"
>XTZ.js</a
>
</h1>
<h3>
Current Time:
<br />
<span class="js-my-dt">YYYY-MM-DDThh:mm:ss.mmm+0000</span>
</h3>
Current Time Zone: <span class="js-my-tz">America/XXXX</span>
<br />
Current Time Offset: <span class="js-my-offset">-0000</span>
<hr />
<form class="js-tz2utc">
<h3>Relative TimeZone to Absolute UTC:</h3>
<label>
Time:
<input
class="js-dt-tz"
type="text"
placeholder="ex: 2021-03-14 03:15:69.000"
required
/>
</label>
<br />
<label>
Zone:
<input
class="js-tz-tz"
type="text"
placeholder="ex: America/New_York"
required
/>
</label>
<br />
<label>
ISO:
<input class="js-my-dt-tz" type="text" disabled />
</label>
<br />
<br />
<button type="submit">Convert to UTC!</button>
<br />
</form>
<hr />
<form class="js-utc2tz">
<h3>Absolute UTC to Relative TimeZone</h3>
<label>
Time:
<input
class="js-dt-utc"
type="text"
placeholder="ex: 2021-03-14 03:15:69.000"
required
/>
</label>
<br />
<label>
Zone:
<input
class="js-tz-utc"
type="text"
placeholder="ex: America/New_York"
required
/>
</label>
<br />
<label>
ISO:
<input class="js-my-dt-utc" type="text" disabled />
</label>
<br />
<br />
<button type="submit">Convert to TZ!</button>
<br />
</form>
<hr />
<h3>Time Zones List</h3>
See the
<a href="https://en.wikipedia.org/wiki/List_of_tz_database_time_zones"
>Full List of Time Zones</a
>
on Wikipedia.
<pre>
America/New_York -0500 -0400 (Eastern Time)
America/Denver -0700 -0600 (Mountain Time)
America/Phoenix -0700 (No DST) (Arizona Time)
America/Los_Angeles -0800 -0700 (Pacific Time)
Australia/Adelaide +0930 +1030 (30-min)
Asia/Kathmandu +0545 (No DST) (45-min)
Asia/Kolkata +0530 (No DST) (30-min)</pre
>
<hr />
Code at
<a href="https://github.com/therootcompany/tz.js" target="_blank"
>github.com/therootcompany/tz.js</a
>
<script src="./xtz.js"></script>
<script>
function $(sel, el) {
return (el || document.body).querySelector(sel);
}
function toUTC() {
var curDt = $(".js-dt-tz").value;
var curTz = $(".js-tz-tz").value;
$(".js-my-dt-tz").value = XTZ.toUTC(curDt, curTz).toISOString();
}
function toTZ() {
var curDt = $(".js-dt-utc").value;
var curTz = $(".js-tz-utc").value;
$(".js-my-dt-utc").value = XTZ.toTimeZone(curDt, curTz).toISOString();
}
var myTz = new Intl.DateTimeFormat("default", {}).resolvedOptions()
.timeZone;
$(".js-my-tz").innerText = myTz;
$(".js-tz-tz").value = myTz;
$(".js-tz-utc").value = myTz;
$(".js-my-offset").innerText = -1 * new Date().getTimezoneOffset();
var myDate = new Date();
$(".js-my-dt").innerText = XTZ.toTimeZone(myDate, myTz).toISOString();
$(".js-dt-tz").value = XTZ.toTimeZone(myDate, myTz)
.toISOString()
.replace("T", " ")
.replace(/(Z|(\+|-)\d+)$/, "");
$(".js-dt-utc").value = myDate.toISOString();
$("form.js-utc2tz").addEventListener("submit", function (ev) {
ev.preventDefault();
ev.stopPropagation();
toTZ();
});
$("form.js-tz2utc").addEventListener("submit", function (ev) {
ev.preventDefault();
ev.stopPropagation();
toUTC();
});
toUTC();
toTZ();
</script>
</body>
</html>

View File

@ -1,10 +1,11 @@
{
"name": "xtz",
"version": "1.0.0",
"version": "1.0.1",
"description": "A fast, lightweight, zero-dependency library to translate between Time Zones and UTC with native Intl.DateTimeFormat in ~100 LoC. For Node.js & Browsers.",
"main": "xtz.js",
"scripts": {
"test": "node ./test.js"
"test": "node ./test.js",
"build": "uglifyjs ./xtz.js > ./xtz.min.js ; gzip -k -f ./xtz.min.js"
},
"repository": {
"type": "git",

BIN
xtz-preview.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 80 KiB

11
xtz.js
View File

@ -49,7 +49,7 @@ var XTZ;
default:
val = parseInt(val, 10);
}
// whole.month = 0;
// ex: whole.month = 0;
whole[part.type] = val;
});
@ -70,8 +70,7 @@ var XTZ;
function getOffset(utcDate, tzD2) {
var tzDate = new Date(toOffsetISOString(tzD2));
var diff =
Math.round(tzDate.valueOf() - utcDate.valueOf()) / (60 * 1000);
var diff = Math.round(tzDate.valueOf() - utcDate.valueOf()) / (60 * 1000);
return diff;
}
@ -99,9 +98,7 @@ var XTZ;
// +0500, -0730
return (
offset +
h.toString().padStart(2, "0") +
m.toString().padStart(2, "0")
offset + h.toString().padStart(2, "0") + m.toString().padStart(2, "0")
);
}
@ -179,4 +176,4 @@ var XTZ;
if ("undefined" != typeof module && module.exports) {
module.exports = XTZ;
}
}());
})();