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 = clock // true
today(<timezone>)
Returns an instance of js-joda.LocalDate. Throws an error if passed an invalid timezone or instant.
const clock = clock // 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 = clock // 2016-08-27clock // 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 = clock // 15:03:24clock // 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 = clock // 2016-08-27T15:03.24clock // 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 = clock // 2016-08-27T15:03.24+01:00clock // 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 = clock // 2016-08-27clock // 2016-08-27 - same as todayclock // 15:03:24clock // 2016-08-27T15:03.24clock // 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 = nowable: '2016-08-27T14:03.24Z' clock // 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 =
You can also supply the version of js-joda that world-clock
will use by providing it as an option
const clock = 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.