From bf0130780d11a98db59499be9e4b4128ca85ab67 Mon Sep 17 00:00:00 2001 From: AJ ONeal Date: Wed, 9 Mar 2022 23:40:03 -0700 Subject: [PATCH] docs!: toUTC* to fromTimeZone, toOffsetISOString --- README.md | 98 +++++++++++++++++++++++++++++------------------------- index.html | 18 +++++----- xtz.js | 49 ++++++++++++++++----------- 3 files changed, 90 insertions(+), 75 deletions(-) diff --git a/README.md b/README.md index 52dd116..fa22bdc 100644 --- a/README.md +++ b/README.md @@ -15,48 +15,26 @@ TZ.toLocalISOString(new Date()); // "2021-11-07T03:15:59.000-0500" TZ.timeZone(); // "America/New_York" ``` -> What UTC time will it be when it's 3:15am in New York? - ```js -// Relative New York time to Absolute UTC Time -TZ.toUTCISOString("2021-11-07 03:15:59.000", "America/New_York"); +// What will the ISO datetime string be +// 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" ``` ```js -var tzDate = TZ.toUTC("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" -// } +// What time will it be in New York +// when it's 7:15am UTC? +// +// (Absolute UTC time to Relative New York 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"); // "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 - [x] Translate a UTC time to a Time Zone @@ -108,8 +86,8 @@ https://www.youtube.com/playlist?list=PLxki0D-ilnqa6horOJ2G18WMZlJeQFlAt - `toLocalISOString(dateOrNull)` - `toTimeZone(utcDate, timeZone)` - `toTimeZoneISOString(isoString, timeZone)` -- `toUTC(dtString, timeZone)` -- `toUTCISOString(dtString, timeZone)` +- `fromTimeZone(dtString, timeZone)` +- `toOffsetISOString(dtString, 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" ``` -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 TZ.toTimeZoneISOString("2021-11-07T08:15:59.000Z", "America/New_York"); // "2021-11-07T03:15:59.000-0500" ``` -Or use our bespoke (custom) date object: +### Or use our bespoke (custom) date object: ```js 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 var tzDate = TZ.toTimeZone( @@ -148,14 +139,14 @@ console.log(tzDate.toISOString()); // "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 new Date("2021-11-07T03:15:59.000-0500").toISOString()); // "2021-11-07T08:15:59.000Z" ``` -## `toUTC(dtString, timeZone)` +## `fromTimeZone(dtString, timeZone)` > 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" ``` -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 -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" ``` -Or our bespoke date object: +### Or our bespoke date object: ```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 zone_** rather than absolute (this is a workaround for JavaScript's lack of bi-directional timezone support). ```js -var utcDate = TZ.toUTC( +var utcDate = TZ.fromTimeZone( new Date("2021-11-07T03:15:59.000Z"), "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 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"); + var utcDate = 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") @@ -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 with this library. ```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(); // "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") diff --git a/index.html b/index.html index 4290794..ae56e06 100644 --- a/index.html +++ b/index.html @@ -99,8 +99,8 @@ String(((new Date()).getTimezoneOffset() % 60)).padStart(2, '0')
-

Relative TimeZone to Absolute UTC:

- 
XTZ.toUTC("YYYY-03-14 03:15:69.000", "UTC")
+      
TimeZone-Relative (Local) to Absolute (ISO+Offset) String:

+      
XTZ.fromTimeZone("YYYY-03-14 03:15:69.000", "UTC")
    .toISOString()
 //


- +
-

Absolute UTC to Relative TimeZone

+

Absolute (UTC) to TimeZone-Relative (ISO+Offset) String:

XTZ.toTimeZone("YYYY-03-14 03:15:69.000", "UTC")
    .toISOString()
 //
@@ -201,17 +201,17 @@ Asia/Kolkata +0530 (No DST) (30-min) diff --git a/xtz.js b/xtz.js index 953bfeb..6313dba 100644 --- a/xtz.js +++ b/xtz.js @@ -1,6 +1,4 @@ -var XTZ; - -(function () { +(function (exports) { "use strict"; function toTimeZone(date, timeZone) { @@ -62,15 +60,16 @@ var XTZ; function toTimeZoneISOString(date, timeZone) { var whole = toTimeZone(date, timeZone); - return toOffsetISOString(whole); + return formatAsOffsetISOString(whole); } function _toOffsetISOString() { - return toOffsetISOString(this); + /* jshint validthis: true */ + return formatAsOffsetISOString(this); } 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)); return diff; } @@ -98,10 +97,21 @@ var XTZ; } // +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); return ( `${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) { // Either of these formats should work: // 2021-03-14 01:15:59 @@ -148,11 +158,6 @@ var XTZ; return tzD3; } - function toUTCISOString(date, timeZone) { - var whole = toUTC(date, timeZone); - return toOffsetISOString(whole); - } - function toLocalISOString(dateOrStr) { var d; if (dateOrStr) { @@ -174,15 +179,17 @@ var XTZ; return `${YYYY}-${MM}-${DD}T${hh}:${mm}:${ss}.${sss}${offset}`; } - XTZ = { + exports.XTZ = { // bespoke date => // 2021-11-07T3:15:59-0500 + // (todo?) + // xtzToISOString: formatAsOffsetISOString, + // (deprecated) toOffsetISOString: toOffsetISOString, // -240 => -0400 formatOffset: formatOffset, - // new Date() => "2021-11-07T03:15:59-0500" toLocalISOString: toLocalISOString, // [ "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-07T03:15:59-0500" // 2021-11-07T08:15:59Z - toUTC: toUTC, - toUTCISOString: toUTCISOString, + toUTC: fromTimeZone, + fromTimeZone: fromTimeZone, + // deprecated + toUTCISOString: toOffsetISOString, }; if ("undefined" != typeof module && module.exports) { - module.exports = XTZ; + module.exports = exports.XTZ; } -})(); +})(("undefined" === typeof module && window) || exports);