Skip to main content

minitz

Node.js CI Deno CI npm version NPM Downloads jsdelivr Codacy Badge MIT License

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: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 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:00

More 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://cdn.jsdelivr.net/gh/hexagon/minitz/src/minitz.js";

// ...

TypeScript

import { minitz } from "https://cdn.jsdelivr.net/gh/hexagon/minitz/src/minitz.js";

// ...

Browser

Manual

  • Download latest zipball
  • Unpack
  • Grab minitz.min.js (UMD and standalone) or minitz.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:09

If 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 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:42

If 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