dater

Synopsis

dater is a library of date/time utilities, all of which are aware of time zones and daylight saving time. It provides for calculating with Durations (amount of UTC milliseconds) and with Periods (regular intervals in some timezone's time, which might be irregular in UTC). It has aware DateTimes (with timezone) and unaware DateTimes (without timezone) and you are prevented from mixing the two in calculations.

Why another date library?

Other libraries are great, we had different requirements. The main thing for us was that calculations should be stable and predictable, especially around DST change moments. Above all, it should give the same answers across platforms.

Try for example to convert some edge case timestamps back and forth between local and UTC or keep adding one hour to a timestamp through daylight saving time changes.

• Consistent behaviour across platforms and with different TZ environment variable settings
• Correct time zone conversions back and forth
• Correct Daylight Saving Time handling with predictable behavior for non-existing hours during DST changes
• Feature-rich:
  • DateTime class with or without time zone
  • Durations with units
  • Calculating with dates and durations across time zones
  • Periods with regular UTC or regular local time repetition
  • Utility functions for determining leap years, determining the last Monday of the month etc.
  • Formatting and parsing of dates using LDML format strings
  • Usable from Node.JS (CommonJS and ESM)
• Good test coverage
• dater is written in TypeScript and typings are included

TZ Data

The TZ data is installed as a separate NPM module tzdata. For browser use, the data is NOT automatically included, to allow you to choose a subset of the data to optimize your bundle.

Separating the TZ data from dater has three advantages:

1. The data becomes useful to other modules than just dater
2. By choosing for e.g. 'tzdata-northamerica', you can install just the time zones you need, which is handy for browser use (smaller footprint).
3. The upgrades to the TZ data become independent of changes to dater. That means you do not have to upgrade to the latest dater version to get the latest TZ data.

Usage

Node.JS

In Node.JS, dater automatically picks up the installed tzdata.

Install using:

npm install @lazyutil/dater

Then require the module in your code. dater will automatically find any installed tzdata modules:

const tc = require("@lazyutil/dater");

Or with ESM:

import * as tc from "@lazyutil/dater";

Quick example

const tc = require("@lazyutil/dater");

const utc = tc.nowUtc();
const local = utc.toZone(tc.zone('localtime'));
const diff = local.toZone(null).diff(utc.toZone(null));
const hourDiff = tc.hours(diff.hours());
console.log("Difference between local and UTC:", hourDiff.toString());

Webpack

Use a >=2.x version of webpack. Use a plugin to load the time zone data you need.

  plugins: [
    new webpack.ContextReplacementPlugin(
      /[\/\\]node_modules[\/\\]@lazyutil[\/\\]dater[\/\\]/,
      path.resolve("tz-database-context"),
      {
        "tzdata-backward-utc": "tzdata-backward-utc",
        "tzdata-etcetera": "tzdata-etcetera",
        "tzdata-europe": "tzdata-europe"
      }
    )
  ]

License

MIT