Compare commits

..

7 Commits
v1.2.0 ... main

5 changed files with 70 additions and 45 deletions

View File

@ -9,17 +9,17 @@ XTZ is a poor man's `Temporal` polyfill, but just for time zones. \
Demo: <https://therootcompany.github.io/tz.js/> Demo: <https://therootcompany.github.io/tz.js/>
```js ```js
// What's the current time, in ISO format? // What's the current time, in ISO+Offset format?
TZ.toLocalISOString(new Date()); // "2021-11-07T03:15:59.000-0500" TZ.toLocalISOString(new Date()); // "2021-11-07T03:15:59.000-0500"
TZ.timeZone(); // "America/New_York" TZ.timeZone(); // "America/New_York"
``` ```
```js ```js
// What will the ISO datetime string be // What will the ISO+Offset datetime string be
// when it's 3:15am in New York? // when it's 3:15am in New York?
// //
// (Relative New York time to Absolute UTC Time) // (Relative New York time to Absolute ISO+Offset Time)
TZ.toOffsetISOString("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"
@ -29,7 +29,7 @@ TZ.toOffsetISOString("2021-11-07 03:15:59.000", "America/New_York");
// What time will it be in New York // What time will it be in New York
// when it's 7:15am UTC? // when it's 7:15am UTC?
// //
// (Absolute UTC time to Relative New York time) // (Absolute UTC Zulu 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"
@ -37,8 +37,8 @@ TZ.toTimeZoneISOString("2021-03-14T07:15:59.000Z", "America/New_York");
# Features # 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] Handles **Daylight Savings**, Weird Time Zones, etc...
- [x] Well-tested `npm run test` - [x] Well-tested `npm run test`
- [x] Lightweight (No deps) - [x] Lightweight (No deps)
@ -93,7 +93,7 @@ https://www.youtube.com/playlist?list=PLxki0D-ilnqa6horOJ2G18WMZlJeQFlAt
> Convert UTC into a Target Time Zone > Convert UTC into a Target Time Zone
Use ISO timestamps representing the absolute UTC time (with or without offset): Use ISO timestamps representing the absolute UTC time (ISO with or without offset):
```txt ```txt
"2021-11-07T08:15:59.000Z" "2021-11-07T08:15:59.000Z"
@ -125,7 +125,7 @@ TZ.toTimeZoneISOString("2021-11-07T08:15:59.000Z", "America/New_York");
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 ISO time:
```js ```js
var tzDate = TZ.toTimeZone( var tzDate = TZ.toTimeZone(
@ -148,7 +148,7 @@ new Date("2021-11-07T03:15:59.000-0500").toISOString());
## `fromTimeZone(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: Use ISO-like timestamps representing the _local_ time in the target time zone:

View File

@ -22,9 +22,9 @@ var XTZ;
console.info(); console.info();
console.info("\t// during daylight savings"); 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()`); 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( console.info(
"\t" + tzDate.toISOString(), "\t" + tzDate.toISOString(),
"// same as", "// same as",
@ -33,9 +33,9 @@ var XTZ;
console.info(); console.info();
console.info("\t// during standard time"); 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()`); 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( console.info(
"\t" + tzDate.toISOString(), "\t" + tzDate.toISOString(),
"// same as", "// same as",
@ -65,9 +65,9 @@ var XTZ;
console.info(); console.info();
console.info("\t// during standard time"); 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()`); 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( console.info(
"\t" + tzDate.toISOString(), "\t" + tzDate.toISOString(),
"// same as", "// same as",

View File

@ -1,6 +1,6 @@
{ {
"name": "xtz", "name": "xtz",
"version": "1.2.0", "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.", "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", "main": "xtz.js",
"files": [ "files": [

74
test.js
View File

@ -4,9 +4,10 @@ var TZ = require("./");
function testUtcToTz(t) { function testUtcToTz(t) {
var result = TZ.toTimeZone.apply(TZ, t.inputs).toISOString(); 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( 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` + `\tExpected: ${t.result}\n` +
`\tActual: ${result}\n` `\tActual: ${result}\n`
); );
@ -14,9 +15,11 @@ function testUtcToTz(t) {
} }
function testTzToUtc(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( throw new Error(
`Invalid TZ to UTC conversion for ${t.desc}:\n` + `Invalid TZ to UTC conversion for ${t.desc}:\n` +
`\tExpected: ${t.result}\n` + `\tExpected: ${t.result}\n` +
@ -44,23 +47,23 @@ function testTzToUtc(t) {
// 12:15am NY -0500 => -0400 // 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"], inputs: ["2021-03-14T05:15:59.000Z", "America/New_York"],
result: "2021-03-14T00:15:59.000-0500", 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"], inputs: ["2021-03-14T00:15:59.000-0500", "America/New_York"],
result: "2021-03-14T00:15:59.000-0500", result: "2021-03-14T00:15:59.000-0500",
}, },
// 1:15am NY (non-DST) // 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"], inputs: ["2021-03-14T06:15:59.000Z", "America/New_York"],
result: "2021-03-14T01:15:59.000-0500", 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"], inputs: ["2021-03-14T01:15:59.000-0500", "America/New_York"],
result: "2021-03-14T01:15:59.000-0500", result: "2021-03-14T01:15:59.000-0500",
}, },
@ -69,23 +72,23 @@ function testTzToUtc(t) {
// 3:15am NY (DST) // 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"], inputs: ["2021-03-14T07:15:59.000Z", "America/New_York"],
result: "2021-03-14T03:15:59.000-0400", 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"], inputs: ["2021-03-14T03:15:59.000-0400", "America/New_York"],
result: "2021-03-14T03:15:59.000-0400", result: "2021-03-14T03:15:59.000-0400",
}, },
// 4:15am NY // 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"], inputs: ["2021-03-14T08:15:59.000Z", "America/New_York"],
result: "2021-03-14T04:15:59.000-0400", 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"], inputs: ["2021-03-14T04:15:59.000-0400", "America/New_York"],
result: "2021-03-14T04:15:59.000-0400", result: "2021-03-14T04:15:59.000-0400",
}, },
@ -106,57 +109,57 @@ function testTzToUtc(t) {
// 12:15am NY -0400 => -0500 // 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"], inputs: ["2021-11-07T04:15:59.000Z", "America/New_York"],
result: "2021-11-07T00:15:59.000-0400", 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"], inputs: ["2021-11-07T00:15:59.000-0400", "America/New_York"],
result: "2021-11-07T00:15:59.000-0400", result: "2021-11-07T00:15:59.000-0400",
}, },
// 1:15am NY (DST) -0400 // 1:15am NY (DST) -0400
// NOTE: 1:15am happens TWICE (with different offsets) // 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"], inputs: ["2021-11-07T05:15:59.000Z", "America/New_York"],
result: "2021-11-07T01:15:59.000-0400", 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"], inputs: ["2021-11-07T01:15:59.000-0400", "America/New_York"],
result: "2021-11-07T01:15:59.000-0400", result: "2021-11-07T01:15:59.000-0400",
}, },
// 1:15am NY (non-DST) -0500 // 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"], inputs: ["2021-11-07T06:15:59.000Z", "America/New_York"],
result: "2021-11-07T01:15:59.000-0500", 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"], inputs: ["2021-11-07T01:15:59.000-0500", "America/New_York"],
result: "2021-11-07T01:15:59.000-0500", result: "2021-11-07T01:15:59.000-0500",
}, },
// 2:15am NY -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"], inputs: ["2021-11-07T07:15:59.000Z", "America/New_York"],
result: "2021-11-07T02:15:59.000-0500", 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"], inputs: ["2021-11-07T02:15:59.000-0500", "America/New_York"],
result: "2021-11-07T02:15:59.000-0500", result: "2021-11-07T02:15:59.000-0500",
}, },
// 3:15am NY // 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"], inputs: ["2021-11-07T08:15:59.000Z", "America/New_York"],
result: "2021-11-07T03:15:59.000-0500", 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"], inputs: ["2021-11-07T03:15:59.000-0500", "America/New_York"],
result: "2021-11-07T03:15:59.000-0500", result: "2021-11-07T03:15:59.000-0500",
}, },
@ -167,27 +170,29 @@ function testTzToUtc(t) {
// Colombo +0530 (not DST) // 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"], inputs: ["2021-03-14T08:15:59.000Z", "Asia/Colombo"],
result: "2021-03-14T13:45:59.000+0530", 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"], inputs: ["2021-03-14T13:45:59.000+0530", "Asia/Colombo"],
result: "2021-03-14T13:45:59.000+0530", 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"], inputs: ["2021-11-07T08:15:59.000Z", "Asia/Colombo"],
result: "2021-11-07T13:45:59.000+0530", 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"], inputs: ["2021-11-07T13:45:59.000+0530", "Asia/Colombo"],
result: "2021-11-07T13:45:59.000+0530", result: "2021-11-07T13:45:59.000+0530",
}, },
].forEach(testUtcToTz); ].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); ].forEach(testTzToUtc);
console.info("Pass: TZ to UTC for America/New_York and Asia/Colombo"); 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");

9
xtz.js
View File

@ -103,7 +103,7 @@
} }
function toOffsetISOString(date, timeZone) { function toOffsetISOString(date, timeZone) {
if ("offset" in date && "year" in date) { if ("object" === typeof date && "offset" in date && "year" in date) {
return formatAsOffsetISOString(date); return formatAsOffsetISOString(date);
} }
@ -179,6 +179,10 @@
return `${YYYY}-${MM}-${DD}T${hh}:${mm}:${ss}.${sss}${offset}`; return `${YYYY}-${MM}-${DD}T${hh}:${mm}:${ss}.${sss}${offset}`;
} }
function getTimeZone() {
return new Intl.DateTimeFormat().resolvedOptions().timeZone;
}
exports.XTZ = { exports.XTZ = {
// bespoke date => // bespoke date =>
// 2021-11-07T3:15:59-0500 // 2021-11-07T3:15:59-0500
@ -190,6 +194,9 @@
// -240 => -0400 // -240 => -0400
formatOffset: formatOffset, formatOffset: formatOffset,
// "America/New_York"
timeZone: getTimeZone,
// "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" ]