docs!: toUTC* to fromTimeZone, toOffsetISOString

This commit is contained in:
AJ ONeal 2022-03-09 23:40:03 -07:00
parent ff996abbc0
commit bf0130780d
Signed by: coolaj86
GPG Key ID: 585419CA6DB0AA23
3 changed files with 90 additions and 75 deletions

View File

@ -15,48 +15,26 @@ TZ.toLocalISOString(new Date()); // "2021-11-07T03:15:59.000-0500"
TZ.timeZone(); // "America/New_York" TZ.timeZone(); // "America/New_York"
``` ```
> What UTC time will it be when it's 3:15am in New York?
```js ```js
// Relative New York time to Absolute UTC Time // What will the ISO datetime string be
TZ.toUTCISOString("2021-11-07 03:15:59.000", "America/New_York"); // when it's 3:15am in New York?
//
// (Relative New York time to Absolute UTC Time)
TZ.toOffsetISOString("2021-11-07 03:15:59.000", "America/New_York");
// "2021-11-07T03:15:59.000-0500" // "2021-11-07T03:15:59.000-0500"
``` ```
```js ```js
var tzDate = TZ.toUTC("2021-11-07 03:15:59.000", "America/New_York"); // What time will it be in New York
// { // when it's 7:15am UTC?
// year: 2021, month: 10, day: 7, //
// hour: 3, minute: 15, second: 59, millisecond: 0, // (Absolute UTC time to Relative New York time)
// offset: -300, timeZoneName: "Eastern Standard Time"
// }
tzDate.toISOString();
// "2021-11-07T03:15:59.000-0500"
// (same as "2021-11-07T08:15:59.000Z")
```
> What time will it be in New York when it's 7:15am UTC?
```js
// Absolute UTC time to Relative New York time
TZ.toTimeZoneISOString("2021-03-14T07:15:59.000Z", "America/New_York"); TZ.toTimeZoneISOString("2021-03-14T07:15:59.000Z", "America/New_York");
// "2021-03-14T03:15:59.000-0400" // "2021-03-14T03:15:59.000-0400"
``` ```
```js
var utcDate = 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")
```
# Features # Features
- [x] Translate a UTC time to a Time Zone - [x] Translate a UTC time to a Time Zone
@ -108,8 +86,8 @@ https://www.youtube.com/playlist?list=PLxki0D-ilnqa6horOJ2G18WMZlJeQFlAt
- `toLocalISOString(dateOrNull)` - `toLocalISOString(dateOrNull)`
- `toTimeZone(utcDate, timeZone)` - `toTimeZone(utcDate, timeZone)`
- `toTimeZoneISOString(isoString, timeZone)` - `toTimeZoneISOString(isoString, timeZone)`
- `toUTC(dtString, timeZone)` - `fromTimeZone(dtString, timeZone)`
- `toUTCISOString(dtString, timeZone)` - `toOffsetISOString(dtString, timeZone)`
## `toTimeZone(utcDate, timeZone)` ## `toTimeZone(utcDate, timeZone)`
@ -121,20 +99,33 @@ Use ISO timestamps representing the absolute UTC time (with or without offset):
"2021-11-07T08:15:59.000Z" "2021-11-07T08:15:59.000Z"
``` ```
Convert directly to an ISO String: ```js
var utcDate = 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")
```
### Convert directly to an ISO String:
```js ```js
TZ.toTimeZoneISOString("2021-11-07T08:15:59.000Z", "America/New_York"); TZ.toTimeZoneISOString("2021-11-07T08:15:59.000Z", "America/New_York");
// "2021-11-07T03:15:59.000-0500" // "2021-11-07T03:15:59.000-0500"
``` ```
Or use our bespoke (custom) date object: ### Or use our bespoke (custom) date object:
```js ```js
var tzDate = TZ.toTimeZone("2021-11-07T08:15:59.000Z", "America/New_York"); var tzDate = TZ.toTimeZone("2021-11-07T08:15:59.000Z", "America/New_York");
``` ```
You can also use a date object with an absolute UTC time: ### You can also use a date object with an absolute UTC time:
```js ```js
var tzDate = TZ.toTimeZone( var tzDate = TZ.toTimeZone(
@ -148,14 +139,14 @@ console.log(tzDate.toISOString());
// "2021-11-07T03:15:59.000-0500" // "2021-11-07T03:15:59.000-0500"
``` ```
Our ISO Strings + Offsets work with JavaScript's native Date object!! ### Our ISO Strings + Offsets work with JavaScript's native Date object!!
```js ```js
new Date("2021-11-07T03:15:59.000-0500").toISOString()); new Date("2021-11-07T03:15:59.000-0500").toISOString());
// "2021-11-07T08:15:59.000Z" // "2021-11-07T08:15:59.000Z"
``` ```
## `toUTC(dtString, timeZone)` ## `fromTimeZone(dtString, timeZone)`
> Convert a Target Time Zone into UTC > Convert a Target Time Zone into UTC
@ -165,24 +156,39 @@ Use ISO-like timestamps representing the _local_ time in the target time zone:
"2021-11-0 03:15:59.000" "2021-11-0 03:15:59.000"
``` ```
Convert directly to an offset ISO String: ```js
var tzDate = 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")
```
### Convert directly to an offset ISO String:
```js ```js
TZ.toUTCISOString("2021-11-07 03:15:59.000", "America/New_York"); TZ.toOffsetISOString("2021-11-07 03:15:59.000", "America/New_York");
// "2021-11-07T03:15:59.000-0500" // "2021-11-07T03:15:59.000-0500"
``` ```
Or our bespoke date object: ### Or our bespoke date object:
```js ```js
var utcDate = TZ.toUTC("2021-11-07 03:15:59.000", "America/New_York"); var utcDate = TZ.fromTimeZone("2021-11-07 03:15:59.000", "America/New_York");
``` ```
### Use a Date as a source time
You can also use a date object as the source time, but the date's UTC time will be treated as **_relative to time 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). zone_** rather than absolute (this is a workaround for JavaScript's lack of bi-directional timezone support).
```js ```js
var utcDate = TZ.toUTC( var utcDate = TZ.fromTimeZone(
new Date("2021-11-07T03:15:59.000Z"), new Date("2021-11-07T03:15:59.000Z"),
"America/New_York" "America/New_York"
); );
@ -207,7 +213,7 @@ 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 - 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. is an hour early in real ("tick-tock" or "monotonic") time.
```js ```js
var utcDate = TZ.toUTC("2021-03-14 02:15:59.000", "America/New_York"); var utcDate = TZ.fromTimeZone("2021-03-14 02:15:59.000", "America/New_York");
utcDate.toISOString(); utcDate.toISOString();
// "2021-03-14T02:15:59.000-0400" // "2021-03-14T02:15:59.000-0400"
// (same as "2021-03-14T01:15:59.000-0500") // (same as "2021-03-14T01:15:59.000-0500")
@ -218,7 +224,7 @@ 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 time - A: Although both 1ams are distinguishable with ISO offset times, only the first can be resolved from a local time
with this library. with this library.
```js ```js
var utcDate = TZ.toUTC("2021-11-07 01:15:59.000", "America/New_York"); var utcDate = TZ.fromTimeZone("2021-11-07 01:15:59.000", "America/New_York");
utcDate.toISOString(); utcDate.toISOString();
// "2021-11-07T01:15:59.000-0400", same as "2021-11-07T05:15:59.000Z" // "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") // (an hour before the 2nd 1am at "2021-11-07T01:15:59.000-0500")

View File

@ -99,8 +99,8 @@ String(((new Date()).getTimezoneOffset() % 60)).padStart(2, '0')</code></pre>
<hr /> <hr />
<form class="js-tz2utc"> <form class="js-tz2utc">
<h3>Relative TimeZone to Absolute UTC:</h3> <h3>TimeZone-Relative (Local) to Absolute (ISO+Offset) String:</h3>
<pre><code>XTZ.toUTC("<span class="js-dtx-tz">YYYY-03-14 03:15:69.000</span>", "<span class="js-tzx-tz">UTC</span>") <pre><code>XTZ.fromTimeZone("<span class="js-dtx-tz">YYYY-03-14 03:15:69.000</span>", "<span class="js-tzx-tz">UTC</span>")
.toISOString() .toISOString()
// <span class="js-myx-dt-tz"></span></code></pre> // <span class="js-myx-dt-tz"></span></code></pre>
<label> <label>
@ -130,14 +130,14 @@ String(((new Date()).getTimezoneOffset() % 60)).padStart(2, '0')</code></pre>
</label> </label>
<br /> <br />
<br /> <br />
<button type="submit">Convert to UTC!</button> <button type="submit">Convert to ISO+Offset!</button>
<br /> <br />
</form> </form>
<hr /> <hr />
<form class="js-utc2tz"> <form class="js-utc2tz">
<h3>Absolute UTC to Relative TimeZone</h3> <h3>Absolute (UTC) to TimeZone-Relative (ISO+Offset) String:</h3>
<pre><code>XTZ.toTimeZone("<span class="js-dtx-utc">YYYY-03-14 03:15:69.000</span>", "<span class="js-tzx-utc">UTC</span>") <pre><code>XTZ.toTimeZone("<span class="js-dtx-utc">YYYY-03-14 03:15:69.000</span>", "<span class="js-tzx-utc">UTC</span>")
.toISOString() .toISOString()
// <span class="js-myx-dt-utc"></span></code></pre> // <span class="js-myx-dt-utc"></span></code></pre>
@ -201,17 +201,17 @@ Asia/Kolkata +0530 (No DST) (30-min)</pre
} }
function translate(dt, tz, tz2) { function translate(dt, tz, tz2) {
var utc = new Date(XTZ.toUTC(dt, tz).toISOString()); var utc = new Date(XTZ.fromTimeZone(dt, tz).toISOString());
if (!tz2) { if (!tz2) {
return utc; return utc;
} }
return XTZ.toTimeZone(utc, tz2); return XTZ.toTimeZone(utc, tz2);
} }
function toUTC() { function fromTimeZone() {
var curDt = $(".js-dt-tz").value; var curDt = $(".js-dt-tz").value;
var curTz = $(".js-tz-tz").value; var curTz = $(".js-tz-tz").value;
$(".js-my-dt-tz").value = XTZ.toUTC(curDt, curTz).toISOString(); $(".js-my-dt-tz").value = XTZ.fromTimeZone(curDt, curTz).toISOString();
$(".js-dtx-tz").innerText = curDt; $(".js-dtx-tz").innerText = curDt;
$(".js-tzx-tz").innerText = curTz; $(".js-tzx-tz").innerText = curTz;
@ -265,10 +265,10 @@ Asia/Kolkata +0530 (No DST) (30-min)</pre
$("form.js-tz2utc").addEventListener("submit", function (ev) { $("form.js-tz2utc").addEventListener("submit", function (ev) {
ev.preventDefault(); ev.preventDefault();
ev.stopPropagation(); ev.stopPropagation();
toUTC(); fromTimeZone();
}); });
toUTC(); fromTimeZone();
toTZ(); toTZ();
xTZ(); xTZ();
</script> </script>

49
xtz.js
View File

@ -1,6 +1,4 @@
var XTZ; (function (exports) {
(function () {
"use strict"; "use strict";
function toTimeZone(date, timeZone) { function toTimeZone(date, timeZone) {
@ -62,15 +60,16 @@ var XTZ;
function toTimeZoneISOString(date, timeZone) { function toTimeZoneISOString(date, timeZone) {
var whole = toTimeZone(date, timeZone); var whole = toTimeZone(date, timeZone);
return toOffsetISOString(whole); return formatAsOffsetISOString(whole);
} }
function _toOffsetISOString() { function _toOffsetISOString() {
return toOffsetISOString(this); /* jshint validthis: true */
return formatAsOffsetISOString(this);
} }
function getOffset(utcDate, tzD2) { function getOffset(utcDate, tzD2) {
var tzDate = new Date(toOffsetISOString(tzD2)); var tzDate = new Date(formatAsOffsetISOString(tzD2));
var diff = Math.round((tzDate.valueOf() - utcDate.valueOf()) / (60 * 1000)); var diff = Math.round((tzDate.valueOf() - utcDate.valueOf()) / (60 * 1000));
return diff; return diff;
} }
@ -98,10 +97,21 @@ var XTZ;
} }
// +0500, -0730 // +0500, -0730
return offset + p2(h) + p2(m); return (
offset + h.toString().padStart(2, "0") + m.toString().padStart(2, "0")
);
} }
function toOffsetISOString(d) { function toOffsetISOString(date, timeZone) {
if ("offset" in date && "year" in date) {
return formatAsOffsetISOString(date);
}
var whole = fromTimeZone(date, timeZone);
return formatAsOffsetISOString(whole);
}
function formatAsOffsetISOString(d) {
var offset = formatOffset(d.offset); var offset = formatOffset(d.offset);
return ( return (
`${d.year}-${p2(d.month + 1)}-${p2(d.day)}` + `${d.year}-${p2(d.month + 1)}-${p2(d.day)}` +
@ -111,7 +121,7 @@ var XTZ;
); );
} }
function toUTC(dt, tz) { function fromTimeZone(dt, tz) {
if ("string" === typeof dt) { if ("string" === typeof dt) {
// Either of these formats should work: // Either of these formats should work:
// 2021-03-14 01:15:59 // 2021-03-14 01:15:59
@ -148,11 +158,6 @@ var XTZ;
return tzD3; return tzD3;
} }
function toUTCISOString(date, timeZone) {
var whole = toUTC(date, timeZone);
return toOffsetISOString(whole);
}
function toLocalISOString(dateOrStr) { function toLocalISOString(dateOrStr) {
var d; var d;
if (dateOrStr) { if (dateOrStr) {
@ -174,15 +179,17 @@ var XTZ;
return `${YYYY}-${MM}-${DD}T${hh}:${mm}:${ss}.${sss}${offset}`; return `${YYYY}-${MM}-${DD}T${hh}:${mm}:${ss}.${sss}${offset}`;
} }
XTZ = { exports.XTZ = {
// bespoke date => // bespoke date =>
// 2021-11-07T3:15:59-0500 // 2021-11-07T3:15:59-0500
// (todo?)
// xtzToISOString: formatAsOffsetISOString,
// (deprecated)
toOffsetISOString: toOffsetISOString, toOffsetISOString: toOffsetISOString,
// -240 => -0400 // -240 => -0400
formatOffset: formatOffset, formatOffset: formatOffset,
// new Date() => "2021-11-07T03:15:59-0500"
toLocalISOString: toLocalISOString, toLocalISOString: toLocalISOString,
// [ "2021-11-07T08:15:59Z", "America/New_York" ] // [ "2021-11-07T08:15:59Z", "America/New_York" ]
@ -192,11 +199,13 @@ var XTZ;
// [ "2021-11-07 03:15:59", "America/New_York" ] // [ "2021-11-07 03:15:59", "America/New_York" ]
// => "2021-11-07T03:15:59-0500" // 2021-11-07T08:15:59Z // => "2021-11-07T03:15:59-0500" // 2021-11-07T08:15:59Z
toUTC: toUTC, toUTC: fromTimeZone,
toUTCISOString: toUTCISOString, fromTimeZone: fromTimeZone,
// deprecated
toUTCISOString: toOffsetISOString,
}; };
if ("undefined" != typeof module && module.exports) { if ("undefined" != typeof module && module.exports) {
module.exports = XTZ; module.exports = exports.XTZ;
} }
})(); })(("undefined" === typeof module && window) || exports);