docs!: toUTC* to fromTimeZone, toOffsetISOString
This commit is contained in:
parent
ff996abbc0
commit
bf0130780d
98
README.md
98
README.md
|
@ -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")
|
||||||
|
|
18
index.html
18
index.html
|
@ -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
49
xtz.js
|
@ -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);
|
||||||
|
|
Loading…
Reference in New Issue