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 Bun >=0.2.2
• 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.3/src/minitz.js";

// ...

TypeScript

import { minitz } from "https://deno.land/x/minitz@4.0.3/src/minitz.js";

// ...

Check https://deno.land/x/minitz for latest available version

Bun

bun add minitz

Note If you experience problems during install, try using bun add minitz --backend=copyfile.

JavaScript

import minitz from "minitz";

Browser

Manual

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