1.3.2

README.md

@@ -5,55 +5,40 @@ in ~100 LoC. For Node.js & Browsers.
 
 [![](./xtz-preview.png)](https://therootcompany.github.io/tz.js/)
 
-XTZ is a poor man's Temporal polyfill, but just for time zones. \
+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?
+```js
+// What's the current time, in ISO+Offset format?
+
+TZ.toLocalISOString(new Date()); // "2021-11-07T03:15:59.000-0500"
+TZ.timeZone(); // "America/New_York"
+```
 
 ```js
-// Relative New York time to Absolute UTC Time
+// What will the ISO+Offset 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 ISO+Offset 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: 11, day: 7,
+//
-//   hour: 3, minute: 15, second: 59, millisecond: 0,
+// (Absolute UTC Zulu 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: 3, 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
+- [x] Translate a UTC Zulu time to a Time Zone
-- [x] Translate a Zoned time to UTC
+- [x] Translate a Zoned time to ISO+Offset
 - [x] Handles **Daylight Savings**, Weird Time Zones, etc...
   - [x] Well-tested `npm run test`
 - [x] Lightweight (No deps)
@@ -87,37 +72,60 @@ var TZ = require("xtz");
 
 See <https://therootcompany.github.io/tz.js/>.
 
+## How was this built?
+
+I live-streamed the creation of this entire project.
+
+If you'd like to learn how I did it and what challenges I encountered, you can watch here:
+https://www.youtube.com/playlist?list=PLxki0D-ilnqa6horOJ2G18WMZlJeQFlAt
+
+(though there have been a few minor updates and bug fixes off-camera)
+
 # API
 
+- `toLocalISOString(dateOrNull)`
 - `toTimeZone(utcDate, timeZone)`
 - `toTimeZoneISOString(isoString, timeZone)`
-- `toUTC(dtString, timeZone)`
+- `fromTimeZone(dtString, timeZone)`
-- `toUTCISOString(dtString, timeZone)`
+- `toOffsetISOString(dtString, timeZone)`
 
 ## `toTimeZone(utcDate, timeZone)`
 
 > 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 (ISO with or without offset):
 
 ```txt
 "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 ISO time:
 
 ```js
 var tzDate = TZ.toTimeZone(
@@ -131,16 +139,16 @@ 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
+> Convert a Target Time Zone into ISO
 
 Use ISO-like timestamps representing the _local_ time in the target time zone:
 
@@ -148,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"
 );
@@ -180,8 +203,8 @@ utcDate.toISOString();
 
 > In 2021 Daylight Savings (in the US)
 >
-> - begins at 2am on March 14th
+> - begins at 2am on March 14th (skips to 3am)
-> - ends at 2am on November 7th
+> - ends at 2am on November 7th (resets to 1am)
 >
 > See <https://www.timeanddate.com/time/change/usa>.
 
@@ -190,21 +213,21 @@ 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")
   ```
 
-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
+- 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 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
@@ -218,6 +241,7 @@ America/New_York    -0500
 America/Denver      -0700
 America/Phoenix     -0700 (No DST)
 America/Los_Angeles -0800
+UTC                 Z
 Australia/Adelaide  +0930 (30-min, has DST)
 Asia/Kathmandu      +0545 (No DST, 45-min)
 Asia/Kolkata        +0530 (No DST, 30-min)

examples.js

@@ -22,9 +22,9 @@ 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.fromTimeZone("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");
+    tzDate = XTZ.fromTimeZone("2021-03-14 08:15:59.000", "America/New_York");
     console.info(
       "\t" + tzDate.toISOString(),
       "// same as",
@@ -33,9 +33,9 @@ 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.fromTimeZone("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");
+    tzDate = XTZ.fromTimeZone("2021-11-07 08:15:59.000", "America/New_York");
     console.info(
       "\t" + tzDate.toISOString(),
       "// same as",
@@ -65,9 +65,9 @@ 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.fromTimeZone("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");
+    tzDate = XTZ.fromTimeZone("2021-11-07T08:15:59.000Z", "America/New_York");
     console.info(
       "\t" + tzDate.toISOString(),
       "// same as",

index.html

@@ -27,15 +27,82 @@
     </h1>
 
     <h3>
-      Current Time: <span class="js-my-dt">YYYY-MM-DDThh:mm:ss.mmm+0000</span>
+      Current Time:
+      <br />
+      <span class="js-my-dt">YYYY-MM-DDThh:mm:ss.mmm+0000</span>
     </h3>
+    <pre><code>new Intl.DateTimeFormat().resolvedOptions().timeZone;</code></pre>
     Current Time Zone: <span class="js-my-tz">America/XXXX</span>
     <br />
+    <pre><code>String(((new Date()).getTimezoneOffset() / 60)).padStart(2, '0') +
+String(((new Date()).getTimezoneOffset() % 60)).padStart(2, '0')</code></pre>
     Current Time Offset: <span class="js-my-offset">-0000</span>
     <hr />
 
+    <form class="js-tz2tz">
+      <h3>Convert Between Time Zones:</h3>
+      <label>
+        Time:
+        <input
+          class="js-dt-xtz"
+          type="text"
+          placeholder="ex: 2021-03-14 03:15:69.000"
+          required
+        />
+      </label>
+      <br />
+
+      <label>
+        Input Zone:
+        <input
+          class="js-tz1-xtz"
+          type="text"
+          placeholder="ex: UTC or America/New_York"
+          required
+        />
+      </label>
+      <br />
+
+      <label>
+        Output Zone:
+        <input
+          class="js-tz2-xtz"
+          type="text"
+          placeholder="ex: America/Los_Angeles or UTC"
+          required
+        />
+      </label>
+      <br />
+
+      <label>
+        ISO:
+        <input class="js-my-dt-xtz" type="text" disabled />
+      </label>
+      <br />
+      <br />
+      <button type="submit">Convert between Zones!</button>
+      <br />
+    </form>
+
+    <hr />
+
+    <form class="js-local">
+      <h3>Local ISO+Offset String:</h3>
+      <pre><code>XTZ.toLocalISOString(new Date())</code></pre>
+      <label>
+        ISO:
+        <input class="js-my-dt-local" type="text" disabled />
+      </label>
+      <br />
+    </form>
+
+    <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.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>
         Time:
         <input
@@ -48,7 +115,7 @@
       <br />
 
       <label>
-        Zone:
+        Input Zone:
         <input
           class="js-tz-tz"
           type="text"
@@ -63,14 +130,17 @@
       </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>
       <label>
         Time:
         <input
@@ -82,7 +152,7 @@
       </label>
       <br />
       <label>
-        Zone:
+        Output Zone:
         <input
           class="js-tz-utc"
           type="text"
@@ -113,6 +183,7 @@ 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)
+UTC                 Z                       (UTC "Zulu" Time)
 Australia/Adelaide  +0930 +1030    (30-min)
 Asia/Kathmandu      +0545 (No DST) (45-min)
 Asia/Kolkata        +0530 (No DST) (30-min)</pre
@@ -123,29 +194,59 @@ Asia/Kolkata        +0530 (No DST) (30-min)</pre
       >github.com/therootcompany/tz.js</a
     >
     <script src="./xtz.js"></script>
+    <script src="./tolocalisostring.js"></script>
     <script>
       function $(sel, el) {
         return (el || document.body).querySelector(sel);
       }
 
-      function toUTC() {
+      function translate(dt, tz, tz2) {
+        var utc = new Date(XTZ.fromTimeZone(dt, tz).toISOString());
+        if (!tz2) {
+          return utc;
+        }
+        return XTZ.toTimeZone(utc, tz2);
+      }
+
+      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;
+        $(".js-myx-dt-tz").innerText = $(".js-my-dt-tz").value;
       }
 
       function toTZ() {
         var curDt = $(".js-dt-utc").value;
         var curTz = $(".js-tz-utc").value;
         $(".js-my-dt-utc").value = XTZ.toTimeZone(curDt, curTz).toISOString();
+
+        $(".js-dtx-utc").innerText = curDt;
+        $(".js-tzx-utc").innerText = curTz;
+        $(".js-myx-dt-utc").innerText = $(".js-my-dt-utc").value;
       }
 
+      function xTZ() {
+        var curDt = $(".js-dt-xtz").value;
+        var inTz = $(".js-tz1-xtz").value;
+        var outTz = $(".js-tz2-xtz").value;
+        $(".js-my-dt-xtz").value = translate(curDt, inTz, outTz).toISOString();
+      }
+
+      $(".js-my-dt-local").value = XTZ.toLocalISOString();
+
       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();
+      $(".js-tz1-xtz").value = myTz;
+      $(".js-tz2-xtz").value = "Asia/Kathmandu";
+      var myOffset = -1 * new Date().getTimezoneOffset();
+      $(".js-my-offset").innerText =
+        XTZ.formatOffset(myOffset) + " (" + myOffset + ")";
 
       var myDate = new Date();
       $(".js-my-dt").innerText = XTZ.toTimeZone(myDate, myTz).toISOString();
@@ -153,6 +254,7 @@ Asia/Kolkata        +0530 (No DST) (30-min)</pre
         .toISOString()
         .replace("T", " ")
         .replace(/(Z|(\+|-)\d+)$/, "");
+      $(".js-dt-xtz").value = $(".js-dt-tz").value;
       $(".js-dt-utc").value = myDate.toISOString();
 
       $("form.js-utc2tz").addEventListener("submit", function (ev) {
@@ -163,11 +265,12 @@ 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>
   </body>
 </html>

package.json

@@ -1,10 +1,15 @@
 {
   "name": "xtz",
-  "version": "1.0.1",
+  "version": "1.3.2",
   "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",
+  "files": [
+    "xtz.js",
+    "tolocalisostring.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",

test.js

@@ -4,9 +4,10 @@ var TZ = require("./");
 
 function testUtcToTz(t) {
   var result = TZ.toTimeZone.apply(TZ, t.inputs).toISOString();
-  if (t.result !== result) {
+  var result2 = TZ.toTimeZoneISOString.apply(TZ, t.inputs);
+  if (result !== result2 || t.result !== result) {
     throw new Error(
-      `Invalid UTC to TZ conversion for ${t.desc}:\n` +
+      `Invalid UTC/ISO+Offset to TZ conversion for ${t.desc}:\n` +
         `\tExpected: ${t.result}\n` +
         `\tActual: ${result}\n`
     );
@@ -14,9 +15,11 @@ function testUtcToTz(t) {
 }
 
 function testTzToUtc(t) {
-  var result = TZ.toUTC.apply(TZ, t.inputs);
+  var result = TZ.fromTimeZone.apply(TZ, t.inputs).toISOString();
-  if (t.result !== result.toISOString()) {
+  var result2 = TZ.toOffsetISOString.apply(TZ, t.inputs);
-    console.log(result);
+  var result3 = TZ.toUTC.apply(TZ, t.inputs).toISOString();
+  if (t.result !== result || t.result !== result2 || t.result !== result3) {
+    console.error(result);
     throw new Error(
       `Invalid TZ to UTC conversion for ${t.desc}:\n` +
         `\tExpected: ${t.result}\n` +
@@ -44,23 +47,23 @@ function testTzToUtc(t) {
 
   // 12:15am NY -0500 => -0400
   {
-    desc: "UTC to 12:15am NY EST",
+    desc: "UTC Zulu to 12:15am NY EST",
     inputs: ["2021-03-14T05:15:59.000Z", "America/New_York"],
     result: "2021-03-14T00:15:59.000-0500",
   },
   {
-    desc: "UTC to 12:15am NY EST (2)",
+    desc: "ISO+Offset to 12:15am NY EST (2)",
     inputs: ["2021-03-14T00:15:59.000-0500", "America/New_York"],
     result: "2021-03-14T00:15:59.000-0500",
   },
   // 1:15am NY (non-DST)
   {
-    desc: "UTC to 1:15am NY EST",
+    desc: "UTC Zulu to 1:15am NY EST",
     inputs: ["2021-03-14T06:15:59.000Z", "America/New_York"],
     result: "2021-03-14T01:15:59.000-0500",
   },
   {
-    desc: "UTC to 1:15am NY EST (2)",
+    desc: "ISO+Offset to 1:15am NY EST (2)",
     inputs: ["2021-03-14T01:15:59.000-0500", "America/New_York"],
     result: "2021-03-14T01:15:59.000-0500",
   },
@@ -69,23 +72,23 @@ function testTzToUtc(t) {
 
   // 3:15am NY (DST)
   {
-    desc: "UTC to 3:15am NY EDT",
+    desc: "UTC Zulu to 3:15am NY EDT",
     inputs: ["2021-03-14T07:15:59.000Z", "America/New_York"],
     result: "2021-03-14T03:15:59.000-0400",
   },
   {
-    desc: "UTC to 3:15am NY EDT (2)",
+    desc: "ISO+Offset to 3:15am NY EDT (2)",
     inputs: ["2021-03-14T03:15:59.000-0400", "America/New_York"],
     result: "2021-03-14T03:15:59.000-0400",
   },
   // 4:15am NY
   {
-    desc: "UTC to 4:15am NY EDT",
+    desc: "UTC Zulu to 4:15am NY EDT",
     inputs: ["2021-03-14T08:15:59.000Z", "America/New_York"],
     result: "2021-03-14T04:15:59.000-0400",
   },
   {
-    desc: "UTC to 4:15am NY EDT (2)",
+    desc: "ISO+Offset to 4:15am NY EDT (2)",
     inputs: ["2021-03-14T04:15:59.000-0400", "America/New_York"],
     result: "2021-03-14T04:15:59.000-0400",
   },
@@ -106,57 +109,57 @@ function testTzToUtc(t) {
 
   // 12:15am NY -0400 => -0500
   {
-    desc: "UTC to 2021 Nov 7, 12:15am NY EDT",
+    desc: "UTC Zulu to 2021 Nov 7, 12:15am NY EDT",
     inputs: ["2021-11-07T04:15:59.000Z", "America/New_York"],
     result: "2021-11-07T00:15:59.000-0400",
   },
   {
-    desc: "UTC to 2021 Nov 7, 12:15am NY EDT (2)",
+    desc: "ISO+Offset to 2021 Nov 7, 12:15am NY EDT (2)",
     inputs: ["2021-11-07T00:15:59.000-0400", "America/New_York"],
     result: "2021-11-07T00:15:59.000-0400",
   },
   // 1:15am NY (DST) -0400
   // NOTE: 1:15am happens TWICE (with different offsets)
   {
-    desc: "UTC to 2021 Nov 7, 1:15am NY EDT",
+    desc: "UTC Zulu to 2021 Nov 7, 1:15am NY EDT",
     inputs: ["2021-11-07T05:15:59.000Z", "America/New_York"],
     result: "2021-11-07T01:15:59.000-0400",
   },
   {
-    desc: "UTC to 2021 Nov 7, 1:15am NY EDT (2)",
+    desc: "ISO+Offset to 2021 Nov 7, 1:15am NY EDT (2)",
     inputs: ["2021-11-07T01:15:59.000-0400", "America/New_York"],
     result: "2021-11-07T01:15:59.000-0400",
   },
   // 1:15am NY (non-DST) -0500
   {
-    desc: "UTC to 2021 Nov 7, 1:15am NY EST",
+    desc: "UTC Zulu to 2021 Nov 7, 1:15am NY EST",
     inputs: ["2021-11-07T06:15:59.000Z", "America/New_York"],
     result: "2021-11-07T01:15:59.000-0500",
   },
   {
-    desc: "UTC to 2021 Nov 7, 1:15am NY EST (2)",
+    desc: "ISO+Offset to 2021 Nov 7, 1:15am NY EST (2)",
     inputs: ["2021-11-07T01:15:59.000-0500", "America/New_York"],
     result: "2021-11-07T01:15:59.000-0500",
   },
   // 2:15am NY -0500
   {
-    desc: "UTC to 2021 Nov 7, 2:15am NY EST",
+    desc: "UTC Zulu to 2021 Nov 7, 2:15am NY EST",
     inputs: ["2021-11-07T07:15:59.000Z", "America/New_York"],
     result: "2021-11-07T02:15:59.000-0500",
   },
   {
-    desc: "UTC to 2021 Nov 7, 2:15am NY EST (2)",
+    desc: "ISO+Offset to 2021 Nov 7, 2:15am NY EST (2)",
     inputs: ["2021-11-07T02:15:59.000-0500", "America/New_York"],
     result: "2021-11-07T02:15:59.000-0500",
   },
   // 3:15am NY
   {
-    desc: "UTC to 2021 Nov 7, 3:15am NY EST",
+    desc: "UTC Zulu to 2021 Nov 7, 3:15am NY EST",
     inputs: ["2021-11-07T08:15:59.000Z", "America/New_York"],
     result: "2021-11-07T03:15:59.000-0500",
   },
   {
-    desc: "UTC to 2021 Nov 7, 3:15am NY EST (2)",
+    desc: "ISO+Offset to 2021 Nov 7, 3:15am NY EST (2)",
     inputs: ["2021-11-07T03:15:59.000-0500", "America/New_York"],
     result: "2021-11-07T03:15:59.000-0500",
   },
@@ -167,27 +170,29 @@ function testTzToUtc(t) {
 
   // Colombo +0530 (not DST)
   {
-    desc: "UTC to Asia/Colombo (1)",
+    desc: "UTC Zulu to Asia/Colombo (1)",
     inputs: ["2021-03-14T08:15:59.000Z", "Asia/Colombo"],
     result: "2021-03-14T13:45:59.000+0530",
   },
   {
-    desc: "UTC to Asia/Colombo (2)",
+    desc: "ISO+Offset to Asia/Colombo (2)",
     inputs: ["2021-03-14T13:45:59.000+0530", "Asia/Colombo"],
     result: "2021-03-14T13:45:59.000+0530",
   },
   {
-    desc: "UTC to Asia/Colombo (3)",
+    desc: "UTC Zulu to Asia/Colombo (3)",
     inputs: ["2021-11-07T08:15:59.000Z", "Asia/Colombo"],
     result: "2021-11-07T13:45:59.000+0530",
   },
   {
-    desc: "UTC to Asia/Colombo (4)",
+    desc: "ISO+Offset to Asia/Colombo (4)",
     inputs: ["2021-11-07T13:45:59.000+0530", "Asia/Colombo"],
     result: "2021-11-07T13:45:59.000+0530",
   },
 ].forEach(testUtcToTz);
-console.info("Pass: UTC to TZ for America/New_York and Asia/Colombo");
+console.info(
+  "Pass: UTC/ISO+Offset to TZ for America/New_York and Asia/Colombo"
+);
 
 [
   //
@@ -314,3 +319,16 @@ console.info("Pass: UTC to TZ for America/New_York and Asia/Colombo");
   },
 ].forEach(testTzToUtc);
 console.info("Pass: TZ to UTC for America/New_York and Asia/Colombo");
+
+var localISOString = TZ.toLocalISOString();
+var reISOString = /^\d\d\d\d-\d\d-\d\dT\d\d:\d\d:\d\d\.\d\d\d[+-]\d\d\d\d$/;
+if (!reISOString.test(localISOString)) {
+  throw new Error("Couldn't get local time as iso+offset");
+}
+console.info("Pass: can get local time as ISO+Offset");
+
+var tzName = TZ.timeZone();
+if (!/^[A-Z]\w+\/[A-Z]\w+$/.test(tzName)) {
+  throw new Error("Couldn't get local Time Zone");
+}
+console.info("Pass: can get local timezone");

tolocalisostring.js

@@ -0,0 +1,50 @@
+(function (exports) {
+  "use strict";
+
+  // See <https://github.com/coolaj86/AJScript/issues/27>
+
+  function toLocalISOString(dateOrStr) {
+    var d;
+    if (dateOrStr) {
+      d = new Date(dateOrStr);
+    } else {
+      d = new Date();
+    }
+
+    var YYYY = d.getFullYear();
+    var MM = p2(d.getMonth() + 1);
+    var DD = p2(d.getDate());
+    var hh = p2(d.getHours());
+    var mm = p2(d.getMinutes());
+    var ss = p2(d.getSeconds());
+    var sss = d.getMilliseconds().toString().padStart(3, "0");
+
+    var offset = formatOffset(-d.getTimezoneOffset());
+
+    return `${YYYY}-${MM}-${DD}T${hh}:${mm}:${ss}.${sss}${offset}`;
+  }
+
+  function formatOffset(minutes) {
+    if (!minutes) {
+      return "Z";
+    }
+
+    var h = Math.floor(Math.abs(minutes) / 60);
+    var m = Math.abs(minutes) % 60;
+    var offset = "";
+    if (minutes > 0) {
+      offset = "+";
+    } else if (minutes < 0) {
+      offset = "-";
+    }
+
+    // +0500, -0730
+    return offset + p2(h) + p2(m);
+  }
+
+  function p2(x) {
+    return String(x).padStart(2, "0");
+  }
+
+  exports.toLocalISOString = toLocalISOString;
+})(("undefined" === typeof module && window) || exports);

xtz.js

@@ -1,6 +1,4 @@
-var XTZ;
+(function (exports) {
-
-(function () {
   "use strict";
 
   function toTimeZone(date, timeZone) {
@@ -24,7 +22,8 @@ var XTZ;
     var formater = new Intl.DateTimeFormat("default", tzOptions);
     var parts = formater.formatToParts(date);
 
-    var whole = {};
+    // millisecond is explicitly 0 for iOS' lack of fractionalSecond support
+    var whole = { millisecond: 0 };
     parts.forEach(function (part) {
       var val = part.value;
       switch (part.type) {
@@ -49,7 +48,7 @@ var XTZ;
         default:
           val = parseInt(val, 10);
       }
-      // whole.month = 0;
+      // ex: whole.month = 0;
       whole[part.type] = val;
     });
 
@@ -61,16 +60,17 @@ 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);
+    var diff = Math.round((tzDate.valueOf() - utcDate.valueOf()) / (60 * 1000));
     return diff;
   }
 
@@ -102,7 +102,16 @@ var XTZ;
     );
   }
 
-  function toOffsetISOString(d) {
+  function toOffsetISOString(date, timeZone) {
+    if ("object" === typeof date && "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)}` +
@@ -112,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
@@ -126,7 +135,7 @@ var XTZ;
     var utcDate = new Date(dt);
     var tzD2 = toTimeZone(utcDate, tz);
     var offset = tzD2.offset;
-    tzD2.offset = "";
+    tzD2.offset = 0;
 
     var deltaDate = new Date(utcDate);
     deltaDate.setUTCMinutes(deltaDate.getUTCMinutes() - offset);
@@ -149,19 +158,47 @@ var XTZ;
     return tzD3;
   }
 
-  function toUTCISOString(date, timeZone) {
+  function toLocalISOString(dateOrStr) {
-    var whole = toUTC(date, timeZone);
+    var d;
-    return toOffsetISOString(whole);
+    if (dateOrStr) {
+      d = new Date(dateOrStr);
+    } else {
+      d = new Date();
+    }
+
+    var YYYY = d.getFullYear();
+    var MM = p2(d.getMonth() + 1);
+    var DD = p2(d.getDate());
+    var hh = p2(d.getHours());
+    var mm = p2(d.getMinutes());
+    var ss = p2(d.getSeconds());
+    var sss = d.getMilliseconds().toString().padStart(3, "0");
+
+    var offset = formatOffset(-d.getTimezoneOffset());
+
+    return `${YYYY}-${MM}-${DD}T${hh}:${mm}:${ss}.${sss}${offset}`;
   }
 
-  XTZ = {
+  function getTimeZone() {
+    return new Intl.DateTimeFormat().resolvedOptions().timeZone;
+  }
+
+  exports.XTZ = {
     // bespoke date =>
     // 2021-11-07T3:15:59-0500
+    // (todo?)
+    // xtzToISOString: formatAsOffsetISOString,
+    // (deprecated)
     toOffsetISOString: toOffsetISOString,
 
     // -240 => -0400
     formatOffset: formatOffset,
 
+    // "America/New_York"
+    timeZone: getTimeZone,
+    // "2021-11-07T03:15:59-0500"
+    toLocalISOString: toLocalISOString,
+
     // [ "2021-11-07T08:15:59Z", "America/New_York" ]
     // => "2021-11-07T03:15:59-0500" // 2021-11-07 03:15:59
     toTimeZone: toTimeZone,
@@ -169,11 +206,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);

xtz.min.js

@@ -1 +1 @@
-var XTZ;(function(){"use strict";function toTimeZone(date,timeZone){date=new Date(date);var options={timeZone:timeZone,year:"numeric",month:"numeric",day:"numeric",hour12:false,hour:"numeric",minute:"numeric",second:"numeric",fractionalSecondDigits:3};var tzOptions=Object.assign({timeZoneName:"long"},options);var formater=new Intl.DateTimeFormat("default",tzOptions);var parts=formater.formatToParts(date);var whole={};parts.forEach(function(part){var val=part.value;switch(part.type){case"literal":return;case"timeZoneName":break;case"month":val=parseInt(val,10)-1;break;case"hour":val=parseInt(val,10)%24;break;case"fractionalSecond":whole.millisecond=parseInt(val,10);return;default:val=parseInt(val,10)}whole[part.type]=val});whole.timeZone=timeZone;whole.offset=getOffset(date,whole);whole.toISOString=_toOffsetISOString;return whole}function toTimeZoneISOString(date,timeZone){var whole=toTimeZone(date,timeZone);return toOffsetISOString(whole)}function _toOffsetISOString(){return toOffsetISOString(this)}function getOffset(utcDate,tzD2){var tzDate=new Date(toOffsetISOString(tzD2));var diff=Math.round(tzDate.valueOf()-utcDate.valueOf())/(60*1e3);return diff}function p2(x){return String(x).padStart(2,"0")}function p3(x){return String(x).padStart(3,"0")}function formatOffset(minutes){if(!minutes){return"Z"}var h=Math.floor(Math.abs(minutes)/60);var m=Math.abs(minutes)%60;var offset="";if(minutes>0){offset="+"}else if(minutes<0){offset="-"}return offset+h.toString().padStart(2,"0")+m.toString().padStart(2,"0")}function toOffsetISOString(d){var offset=formatOffset(d.offset);return`${d.year}-${p2(d.month+1)}-${p2(d.day)}`+`T${p2(d.hour)}:${p2(d.minute)}:${p2(d.second)}.${p3(d.millisecond)}${offset}`}function toUTC(dt,tz){if("string"===typeof dt){dt=dt.replace("T"," ").replace("Z","").replace(" ","T").replace(/$/,"Z")}var utcDate=new Date(dt);var tzD2=toTimeZone(utcDate,tz);var offset=tzD2.offset;tzD2.offset="";var deltaDate=new Date(utcDate);deltaDate.setUTCMinutes(deltaDate.getUTCMinutes()-offset);var tzD3=toTimeZone(deltaDate,tz);if(tzD3.hour===utcDate.getUTCHours()&&tzD3.minute===utcDate.getUTCMinutes()){return tzD3}var diff=tzD3.offset-offset;var h=Math.floor(Math.abs(diff)/60);var m=Math.abs(diff)%60;var sign=Math.abs(diff)/diff;tzD3.hour-=h*sign;tzD3.minute-=m*sign;return tzD3}function toUTCISOString(date,timeZone){var whole=toUTC(date,timeZone);return toOffsetISOString(whole)}XTZ={toOffsetISOString:toOffsetISOString,formatOffset:formatOffset,toTimeZone:toTimeZone,toTimeZoneISOString:toTimeZoneISOString,toUTC:toUTC,toUTCISOString:toUTCISOString};if("undefined"!=typeof module&&module.exports){module.exports=XTZ}})();
+var XTZ;(function(){"use strict";function toTimeZone(date,timeZone){date=new Date(date);var options={timeZone:timeZone,year:"numeric",month:"numeric",day:"numeric",hour12:false,hour:"numeric",minute:"numeric",second:"numeric",fractionalSecondDigits:3};var tzOptions=Object.assign({timeZoneName:"long"},options);var formater=new Intl.DateTimeFormat("default",tzOptions);var parts=formater.formatToParts(date);var whole={millisecond:0};parts.forEach(function(part){var val=part.value;switch(part.type){case"literal":return;case"timeZoneName":break;case"month":val=parseInt(val,10)-1;break;case"hour":val=parseInt(val,10)%24;break;case"fractionalSecond":whole.millisecond=parseInt(val,10);return;default:val=parseInt(val,10)}whole[part.type]=val});whole.timeZone=timeZone;whole.offset=getOffset(date,whole);whole.toISOString=_toOffsetISOString;return whole}function toTimeZoneISOString(date,timeZone){var whole=toTimeZone(date,timeZone);return toOffsetISOString(whole)}function _toOffsetISOString(){return toOffsetISOString(this)}function getOffset(utcDate,tzD2){var tzDate=new Date(toOffsetISOString(tzD2));var diff=Math.round((tzDate.valueOf()-utcDate.valueOf())/(60*1e3));return diff}function p2(x){return String(x).padStart(2,"0")}function p3(x){return String(x).padStart(3,"0")}function formatOffset(minutes){if(!minutes){return"Z"}var h=Math.floor(Math.abs(minutes)/60);var m=Math.abs(minutes)%60;var offset="";if(minutes>0){offset="+"}else if(minutes<0){offset="-"}return offset+h.toString().padStart(2,"0")+m.toString().padStart(2,"0")}function toOffsetISOString(d){var offset=formatOffset(d.offset);return`${d.year}-${p2(d.month+1)}-${p2(d.day)}`+`T${p2(d.hour)}:${p2(d.minute)}:${p2(d.second)}.${p3(d.millisecond)}${offset}`}function toUTC(dt,tz){if("string"===typeof dt){dt=dt.replace("T"," ").replace("Z","").replace(" ","T").replace(/$/,"Z")}var utcDate=new Date(dt);var tzD2=toTimeZone(utcDate,tz);var offset=tzD2.offset;tzD2.offset=0;var deltaDate=new Date(utcDate);deltaDate.setUTCMinutes(deltaDate.getUTCMinutes()-offset);var tzD3=toTimeZone(deltaDate,tz);if(tzD3.hour===utcDate.getUTCHours()&&tzD3.minute===utcDate.getUTCMinutes()){return tzD3}var diff=tzD3.offset-offset;var h=Math.floor(Math.abs(diff)/60);var m=Math.abs(diff)%60;var sign=Math.abs(diff)/diff;tzD3.hour-=h*sign;tzD3.minute-=m*sign;return tzD3}function toUTCISOString(date,timeZone){var whole=toUTC(date,timeZone);return toOffsetISOString(whole)}XTZ={toOffsetISOString:toOffsetISOString,formatOffset:formatOffset,toTimeZone:toTimeZone,toTimeZoneISOString:toTimeZoneISOString,toUTC:toUTC,toUTCISOString:toUTCISOString};if("undefined"!=typeof module&&module.exports){module.exports=XTZ}})();