world-clock

A library for getting dates/times in explicit timezones.

API

isValid(<timezone>, [<millis|date|string>])

Returns whether the timezone and optional instant is valid, e.g.

const clock = require('world-clock')()

clock.isValid('Europe/London', Date.now()) // true

today(<timezone>)

Returns an instance of js-joda.LocalDate. Throws an error if passed an invalid timezone or instant.

const clock = require('world-clock')()

clock.today('Europe/London').toString() // 2016-08-27

localDate(<timezone>, [<millis|date|string>])

Returns an instance of js-joda.LocalDate. Throws an error if passed an invalid timezone or instant.

const clock = require('world-clock')()

clock.localDate('Europe/London').toString()             // 2016-08-27
clock.localDate('Europe/London', Date.now()).toString() // 2016-08-27

localTime(<timezone>, [<millis|date|string>])

Returns an instance of js-joda.LocalTime. Throws an error if passed an invalid timezone or instant.

const clock = require('world-clock')()

clock.localTime('Europe/London').toString()             // 15:03:24
clock.localTime('Europe/London', Date.now()).toString() // 15:03:24

localDateTime(<timezone>, [<millis|date|string>])

Returns an instance of js-joda.LocalDateTime. Throws an error if passed an invalid timezone or instant.

const clock = require('world-clock')()

clock.localDateTime('Europe/London').toString()             // 2016-08-27T15:03.24
clock.localDateTime('Europe/London', Date.now()).toString() // 2016-08-27T15:03.24

zonedDateTime(<timezone>, [<millis|date|string>])

Returns an instance of js-joda.ZonedDateTime. Throws an error if passed an invalid timezone or instant.

const clock = require('world-clock')()

clock.zonedDateTime('Europe/London').toString()             // 2016-08-27T15:03.24+01:00
clock.zonedDateTime('Europe/London', Date.now()).toString() // 2016-08-27T15:03.24+01:00

Advanced Usage

Using the system time zone

This is not recommented since a lot of date related bugs are caused because of accidental reliance on the system time zone, but if you really need to…

const clock = require('world-clock')()

clock.today('SYSTEM').toString()          // 2016-08-27
clock.localDate('SYSTEM').toString()      // 2016-08-27 - same as today
clock.localTime('SYSTEM').toString()      // 15:03:24
clock.localDateTime('SYSTEM').toString()  // 2016-08-27T15:03.24
clock.zonedDateTime('SYSTEM').toString()  // 2016-08-27T15:03.24+01:00[SYSTEM]

Fixing dates

For automatied testing it can be handy to fix time to a known instant. world-clock can be passed any ‘nowable’ object, i.e. one that exposes a now() function. e.g.

const clock = require('world-clock')({
    nowable: {
        now: () => new Date('2016-08-27T14:03.24Z').getTime()
    }
})

clock.today('Europe/London').toString() // 2016-08-27

We use groundhog-day for fixing time when testing.

Getting / Setting Joda

world-clock exposes its version of js-joda in joda.js

const joda = require('world-clock/joda')

You can also supply the version of js-joda that world-clock will use by providing it as an option

const clock = require('world-clock')({
    joda: require('js-joda')
})

FAQ

Why not use moment-timezone?

moment-timezone is mutable which can result in hard to diagnose bugs. It lacks support for local dates/times and is restricted by trying to remain compatible with moment.

Why not use js-joda?

js-joda does not currently handle timezone names (e.g. ‘Europe/London’). This issue is being tracked here.

Why doesn’t world-clock work on Windows?

world-clock relies on zoneinfo which parses zoneinfo files from /usr/share/zoneinfo. It therefore does not work on windows.