docs!: toUTC* to fromTimeZone, toOffsetISOString

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
+// 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"
 ```
 
 ```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");
 // "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)`
+- `fromTimeZone(dtString, timeZone)`
-- `toUTCISOString(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")

index.html

@@ -99,8 +99,8 @@ String(((new Date()).getTimezoneOffset() % 60)).padStart(2, '0')</code></pre>
     <hr />
 
     <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()
 // <span class="js-myx-dt-tz"></span></code></pre>
       <label>
@@ -130,14 +130,14 @@ String(((new Date()).getTimezoneOffset() % 60)).padStart(2, '0')</code></pre>
       </label>
       <br />
       <br />
-      <button type="submit">Convert to UTC!</button>
+      <button type="submit">Convert to ISO+Offset!</button>
       <br />
     </form>
 
     <hr />
 
     <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>")
    .toISOString()
 // <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) {
-        var utc = new Date(XTZ.toUTC(dt, tz).toISOString());
+        var utc = new Date(XTZ.fromTimeZone(dt, tz).toISOString());
         if (!tz2) {
           return utc;
         }
         return XTZ.toTimeZone(utc, tz2);
       }
 
-      function toUTC() {
+      function fromTimeZone() {
         var curDt = $(".js-dt-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-tzx-tz").innerText = curTz;
@@ -265,10 +265,10 @@ Asia/Kolkata        +0530 (No DST) (30-min)</pre
       $("form.js-tz2utc").addEventListener("submit", function (ev) {
         ev.preventDefault();
         ev.stopPropagation();
-        toUTC();
+        fromTimeZone();
       });
 
-      toUTC();
+      fromTimeZone();
       toTZ();
       xTZ();
     </script>

xtz.js

@@ -1,6 +1,4 @@
-var XTZ;
+(function (exports) {
-
-(function () {
   "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,
+    toUTC: fromTimeZone,
-    toUTCISOString: toUTCISOString,
+    fromTimeZone: fromTimeZone,
+    // deprecated
+    toUTCISOString: toOffsetISOString,
   };
 
   if ("undefined" != typeof module && module.exports) {
-    module.exports = XTZ;
+    module.exports = exports.XTZ;
   }
-})();
+})(("undefined" === typeof module && window) || exports);