Normal Programming Mistake

    world-clock

    1.4.0 • Public • Published

    world-clock

    A library for getting dates/times in explicit timezones.

    NPM version NPM downloads Build Status Code Climate Test Coverage Code Style Dependency Status devDependencies Status

    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.

    Install

    npm i world-clock

    DownloadsWeekly Downloads

    5

    Version

    1.4.0

    License

    ISC

    Unpacked Size

    26 kB

    Total Files

    13

    Last publish

    Collaborators

    • guidesmiths_bot
    • feliun
    • ulisesgascon
    • cressie176