WIP: add translate feature

README.md

@@ -5,14 +5,22 @@ 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 timezones. \
 Demo: <https://therootcompany.github.io/tz.js/>
 
 > What UTC time will it be when it's 3:15am in New York?
 
+```js
+TZ.toISOString("2021-11-07 03:15:59.000", "UTC", "America/New_York");
+TZ.toISOString("2021-11-07 03:15:59.000", "America/New_York", "UTC");
+TZ.toISOString("2021-11-07 03:15:59.000", "America/New_York");
+TZ.toISOString("2021-11-07T03:15:59.000Z", "America/New_York");
+TZ.toISOString("2021-11-07 03:15:59.000", "America/New_York", "America/Denver");
+```
+
 ```js
 // Relative New York time to Absolute UTC Time
-TZ.toUTCISOString("2021-11-07 03:15:59.000", "America/New_York");
+TZ.toISOString("2021-11-07 03:15:59.000", "America/New_York");
 // "2021-11-07T03:15:59.000-0500"
 ```
 
@@ -33,7 +41,7 @@ tzDate.toISOString();
 
 ```js
 // Absolute UTC time to Relative New York time
-TZ.toTimeZoneISOString("2021-03-14T07:15:59.000Z", "America/New_York");
+TZ.toISOString("2021-03-14 07:15:59.000", "UTC", "America/New_York");
 // "2021-03-14T03:15:59.000-0400"
 ```
 
@@ -89,12 +97,12 @@ See <https://therootcompany.github.io/tz.js/>.
 
 # API
 
-- `toTimeZone(utcDate, timeZone)`
+- `toTimeZone(utcDate, outputZone)`
-- `toTimeZoneISOString(isoString, timeZone)`
+- `toTimeZoneISOString(isoString, outputZone)`
-- `toUTC(dtString, timeZone)`
+- `toUTC(dtString, inputZone)`
-- `toUTCISOString(dtString, timeZone)`
+- `toUTCISOString(dtString, inputZone)`
 
-## `toTimeZone(utcDate, timeZone)`
+## `toTimeZone(utcDate, outputZone)`
 
 > Convert UTC into a Target Time Zone
 
@@ -138,7 +146,7 @@ new Date("2021-11-07T03:15:59.000-0500").toISOString());
 // "2021-11-07T08:15:59.000Z"
 ```
 
-## `toUTC(dtString, timeZone)`
+## `toUTC(dtString, outputZone)`
 
 > Convert a Target Time Zone into UTC
 

test.js

@@ -25,8 +25,26 @@ function testTzToUtc(t) {
   }
 }
 
+function testTzToTz(t) {
+  var result = TZ.translate.apply(TZ, t.inputs);
+  if (t.result !== result.toISOString()) {
+    console.log(result);
+    throw new Error(
+      `Invalid TZ to TZ conversion for ${t.desc}:\n` +
+        `\tExpected: ${t.result}\n` +
+        `\tActual: ${result.toISOString()}\n`
+    );
+  }
+}
+
 // At this real UTC time, what does the timezone translate it to?
 [
+  {
+    desc: "UTC Identity (1)",
+    inputs: ["2021-03-14T05:15:59.000Z", "UTC"],
+    result: "2021-03-14T05:15:59.000Z",
+  },
+
   //
   // Start-of-DST Tests
   //
@@ -190,6 +208,12 @@ function testTzToUtc(t) {
 console.info("Pass: UTC to TZ for America/New_York and Asia/Colombo");
 
 [
+  {
+    desc: "UTC Identity (2)",
+    inputs: ["2021-03-14 05:15:59.000", "UTC"],
+    result: "2021-03-14T05:15:59.000Z",
+  },
+
   //
   // Start-of-DST Tests
   //
@@ -314,3 +338,36 @@ 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");
+
+[
+  {
+    desc: "(Xa) UTC Identity",
+    inputs: ["2021-03-14 05:15:59.000", "UTC", "UTC"],
+    result: "2021-03-14T05:15:59.000Z",
+  },
+  {
+    desc: "(Xb) UTC to 12:15am NY EST",
+    inputs: ["2021-03-14 05:15:59.000", "UTC", "America/New_York"],
+    result: "2021-03-14T00:15:59.000-0500",
+  },
+  {
+    desc: "(Xc) 2021 Mar 14, 12:15am NY EST to UTC",
+    inputs: ["2021-03-14 00:15:59.000", "America/New_York", "UTC"],
+    result: "2021-03-14T05:15:59.000Z",
+  },
+  {
+    desc: "(Xd) Asia/Colombo to America/New_York",
+    // 2021-11-07T13:45:59.000+0530
+    // to 2021-11-07T03:15:59.000-0500
+    inputs: ["2021-11-07 13:45:59.000", "Asia/Colombo", "America/New_York"],
+    result: "2021-11-07T03:15:59.000-0500",
+  },
+  {
+    desc: "(Xe) America/New_York to Asia/Colombo",
+    // 2021-11-07T03:15:59.000-0500
+    // to 2021-11-07T13:45:59.000+0530
+    inputs: ["2021-11-07 03:15:59.000", "America/New_York", "Asia/Colombo"],
+    result: "2021-11-07T13:45:59.000+0530",
+  },
+].forEach(testTzToTz);
+console.info("Pass: TZ to TZ for America/New_York, UTC, and Asia/Colombo");

xtz.js

@@ -126,6 +126,9 @@ var XTZ;
     }
     var utcDate = new Date(dt);
     var tzD2 = toTimeZone(utcDate, tz);
+    if ("UTC" === tz) {
+      return tzD2;
+    }
     var offset = tzD2.offset;
     tzD2.offset = 0;
 
@@ -155,6 +158,18 @@ var XTZ;
     return toOffsetISOString(whole);
   }
 
+  function translate(dt, tz, tz2) {
+    var utc = new Date(toUTC(dt, tz).toISOString());
+    if (!tz2) {
+        return utc;
+    }
+    return toTimeZone(utc, tz2);
+  }
+
+  function toISOString(dt, tz, tz2) {
+    return translate(dt, tz, tz2).toISOString();
+  }
+
   XTZ = {
     // bespoke date =>
     // 2021-11-07T3:15:59-0500
@@ -172,6 +187,10 @@ var XTZ;
     // => "2021-11-07T03:15:59-0500" // 2021-11-07T08:15:59Z
     toUTC: toUTC,
     toUTCISOString: toUTCISOString,
+
+    toISOString: toISOString,
+
+    translate: translate,
   };
 
   if ("undefined" != typeof module && module.exports) {