Skip to content
ITEN

date-tz

Dates and times in any time zone, in TypeScript, with no dependencies.

ISCTypeScriptActiveVersion 3.0.2
RepositoryPackageDocumentationTry it online

What it's for

JavaScript's Date knows two time zones: the machine's and UTC. In our products people sit in different time zones, and a booking or a message has to show the right time to whoever reads it, even on the days the clocks change. We needed a solution with no dependencies, and with dates that survive the trip between services, databases and message queues. So we wrote date-tz, and today we use it in Chattoo.

Installation

npm install @open-rlb/date-tz

Example

import { DateTz } from '@open-rlb/date-tz';

// Message sent at 08:00 in Rome (CET, UTC+1)
const sent = DateTz.parse('2026-01-15 08:00:00', 'YYYY-MM-DD HH:mm:ss', 'Europe/Rome');

// What does the Tokyo reader (JST, UTC+9) see?
const forTokyo = sent.cloneToTimezone('Asia/Tokyo');
forTokyo.toString();   // '2026-01-15 16:00:00'
sent.toString();       // '2026-01-15 08:00:00'  ← original unchanged

What it does

No dependencies

The package installs no other libraries and ships no time zone data. It reads offsets from the IANA database that Node.js or the browser already has, through Intl.

New rules already included

A runtime's time zone database only changes when Node.js, the browser or the operating system is updated. That's why we've already put the new rules for Morocco (from 20 September 2026) and British Columbia (from 1 November 2026) into date-tz. Others can be registered when the app starts.

Try it in the browser

On the playground we publish on GitHub Pages every feature can be tried without installing anything: world clock, parsing and formatting, time zone comparison, exceptions.

Dates that travel intact

An instance serialises to JSON as four fields, even inside a queued message or a database document. When it's rebuilt, the offset and DST are worked out again with the receiving runtime's data.

DST without surprises

A wall-clock time that is skipped or repeated when the clocks change always resolves by the same rule. And adding a day lands on the same time the next day, even when that day lasts 23 or 25 hours.

Strict parsing

Formatting and parsing share one set of tokens. When a string doesn't match the pattern, date-tz throws: we'd rather raise an error than return a wrong date.

Requirements

  • No runtime dependencies
  • Node.js or a browser, with the Intl API and IANA time zone data
  • CommonJS package with TypeScript types, compiled for ES2024
  • Dates from 1 January 1970 onwards

License and contributions

License
ISC License
Issues
https://github.com/open-riolabs/date-tz/issues

The code, releases and issues are on GitHub.

Go to the repository