minitz
Features
- Convert dates between any timezone supported by the system.
- Parses ISO8601 time strings.
- MIT licensed, use the library any way you want. For real.
- Minimal, no dependencies. Relies on JavaScript Intl and current best practises.
- Works in Node.js >=14.0 (both require and import).
- Works in Deno >=1.8.
- Works in browsers as standalone, UMD or ES-module.
- Includes TypeScript typings.
Usage
Converting a Date object to another timezone in JavaScript is possible using Intl feature of vanilla JS.
// Get current time in Asia/Tokyo, using vanilla js
new Date().toLocaleString("sv-SE", { timeZone: "Asia/Tokyo" });
// -> 2022-09-15 17:23:45However - if you want to convert date/time from another timezone, or convert between different timezones, things get trickier.
Minitz is a minimal library built to solve the problem in the simplest possible way, and work in all environments (Node/Deno/Browser, ESM/UMD/CommonJS).
Short examples on converting from a remote timezone, and converting between different timezones.
// Get local time from time in Asia/Tokyo, using minitz and vanilla js
const localTime = minitz(2022,9,15,23,0,0,"Asia/Tokyo")
console.log( localTime.toLocaleString("sv-SE") );
// -> 2022-09-15 16:00:00// Get time in America/New_York from time in Asia/Tokyo, using minitz and vanilla js
// Also demonstrates that it's possible to use ISO8601 strings as input to minitz, through `.fromTZISO`
const localTime = minitz.fromTZISO("2022-09-15 23:00:00","Asia/Tokyo");
console.log( localTime.toLocaleString("sv-SE", { timeZone: "America/New_York" }) );
// -> 2022-09-15 10:00:00More examples further down, and full documentation available at hexagon.github.io/minitz.
Installation
Node.js
npm install minitz --save
JavaScript
// ESM Import ...
import minitz from "minitz";
// ... or CommonJS Require
const minitz = require("minitz");TypeScript
Note that only default export is available in Node.js TypeScript, as the commonjs module is used internally.
import minitz from "minitz";
// ...Deno
JavaScript
import minitz from "https://deno.land/x/minitz@2.1.1/src/minitz.js";
// ...TypeScript
import { minitz } from "https://deno.land/x/minitz@2.1.1/src/minitz.js";
// ...Check https://deno.land/x/minitz for latest available version
Browser
Manual
- Download latest zipball
- Unpack
- Grab
minitz.min.js(UMD and standalone) orminitz.min.mjs(ES-module) from the dist/ folder
CDN
To use as a UMD-module (stand alone, RequireJS etc.)
<script src="https://cdn.jsdelivr.net/npm/minitz/dist/minitz.min.js"></script>To use as a ES-module
<script type="module">
import minitz from "https://cdn.jsdelivr.net/npm/minitz/dist/minitz.min.mjs";
// ... see usage section ...
</script>More examples
Assuming you have imported minitz as described under ‘Installation’.
Convert a specific timezone to local time
Standard way
// Convert 2022-09-10 23:08:09 in New York to local time (in this example Europe/Stockholm)
console.log("Local time: ", minitz(2022, 9, 10, 23, 8, 9, "America/New_York").toLocaleString("sv-SE"));
// Local time: 2022-09-11 05:08:09If providing an ISO8601 timestring
// Convert 2022-09-10 23:08:09 in New York to local time (in this example Europe/Stockholm)
console.log("Local time: ", minitz("2022-09-10 23:08:99", "America/New_York").toLocaleString("sv-SE"));
// Local time: 2022-09-11 05:08:09Convert local time to a specific timezone
Provided that you only neeed to display the result, converting local time to specific timezone is best done with vanilla JavaScript.
console.log("Time in New York printed with system locale: ", new Date().toLocaleString("sv-SE", { timeZone: "America/New_York"}));
// -> Time in New York printed with system locale: 2022-09-14 17:29:42If you need to use the result in any way, it’s better to use minitz to convert to a remote timezone. That way you get the results as an object, which also includes which timezone the time is converted to.
// Convert to local time to time in America/New_York
// As time in other timezones than local cannot be represented correctly by a date object
// a generic object is returned
console.log("Time in New York: ", minitz.toTZ(new Date(), "America/New_York"));
// -> Time in New York:
// {
// year: 2022,
// month: 9,
// day: 14,
// hour: 17,
// minute: 29,
// second: 42,
// timezone: 'America/New_York'
// }Contributing
Any contributions are welcome. See Contribution Guide
License
MIT