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 (less than 2 KB minified), no dependencies. Relies on JavaScript Intl and current best practices.
- 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.
Try it live on jsfiddle
Usage
Converting a Date object to another timezone in JavaScript is possible using the 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:45
However - 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 made to work in all environments (Node/Deno/Browser, ESM/UMD/CommonJS).
Simple examples of conversion from a remote timezone, and a conversion 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:00
More examples are available further below, and the full documentation is 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@4.0.0/src/minitz.js";
// ...
TypeScript
import { minitz } from "https://deno.land/x/minitz@4.0.0/src/minitz.js";
// ...
Check https://deno.land/x/minitz for latest available version
Browser
Manual
- Download the latest zipball
- Extract
- Grab
minitz.min.js
(UMD and standalone) orminitz.min.mjs
(ES-module) from the dist/ folder
CDN
To use as an UMD-module (stand alone, RequireJS etc.)
<script src="https://cdn.jsdelivr.net/npm/minitz/dist/minitz.min.js"></script>
To use as an ES-module
<script type="module">
import minitz from "https://cdn.jsdelivr.net/npm/minitz/dist/minitz.min.mjs";
// ... see usage section ...
</script>
More examples
The examples below will work only if you have imported minitz as described in the āInstallationā section. If thatās not the case the results may vary.
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:09
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:09
Convert local time to a specific timezone
Provided that you only need to display the result, converting local time to specific timezone is best achieved 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:42
If you need to use the result in any other way, itās better to use minitz to convert to a remote timezone. This way youāll get the results as an object, which also includes the timezone to which 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:
// {
// y: 2022,
// m: 9,
// d: 14,
// h: 17,
// i: 29,
// s: 42,
// tz: 'America/New_York'
// }
Contributing
Any contributions are welcome. See Contribution Guide
License
MIT