Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/guidesmiths/world-clock
A world clock underwritten by js-joda and zoneinfo
https://github.com/guidesmiths/world-clock
Last synced: 3 months ago
JSON representation
A world clock underwritten by js-joda and zoneinfo
- Host: GitHub
- URL: https://github.com/guidesmiths/world-clock
- Owner: guidesmiths
- License: isc
- Created: 2016-08-27T14:46:12.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2018-10-07T10:41:11.000Z (over 6 years ago)
- Last Synced: 2024-10-12T00:27:09.320Z (4 months ago)
- Language: JavaScript
- Size: 66.4 KB
- Stars: 4
- Watchers: 15
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# world-clock
A library for getting dates/times in explicit timezones.
[](https://www.npmjs.com/package/world-clock)
[](https://www.npmjs.com/package/world-clock)
[](https://travis-ci.org/guidesmiths/world-clock)
[](https://codeclimate.com/github/guidesmiths/world-clock)
[](https://codeclimate.com/github/guidesmiths/world-clock/coverage)
[](https://github.com/guidesmiths/eslint-config-imperative)
[](https://david-dm.org/guidesmiths/world-clock)
[](https://david-dm.org/guidesmiths/world-clock?type=dev)
## API
### isValid(<timezone>, [<millis|date|string>])
Returns whether the timezone and optional instant is valid, e.g.
```js
const clock = require('world-clock')()
clock.isValid('Europe/London', Date.now()) // true
```
### today(<timezone>)
Returns an instance of [js-joda.LocalDate](https://js-joda.github.io/js-joda/esdoc/class/src/LocalDate.js~LocalDate.html). Throws an error if passed an invalid timezone or instant.
```js
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](https://js-joda.github.io/js-joda/esdoc/class/src/LocalDate.js~LocalDate.html). Throws an error if passed an invalid timezone or instant.
```js
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](https://js-joda.github.io/js-joda/esdoc/class/src/LocalTime.js~LocalTime.html). Throws an error if passed an invalid timezone or instant.
```js
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](https://js-joda.github.io/js-joda/esdoc/class/src/LocalDateTime.js~LocalDateTime.html). Throws an error if passed an invalid timezone or instant.
```js
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](https://js-joda.github.io/js-joda/esdoc/class/src/ZonedDateTime.js~ZonedDateTime.html). Throws an error if passed an invalid timezone or instant.
```js
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...
```js
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.
```js
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](https://github.com/guidesmiths/groundhog-day) for fixing time when testing.
### Getting / Setting Joda
```world-clock``` exposes its version of js-joda in joda.js
```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
```js
const clock = require('world-clock')({
joda: require('js-joda')
})
```
## FAQ
### Why not use moment-timezone?
[moment-timezone](https://github.com/moment/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](https://github.com/moment/moment).
### Why not use js-joda?
[js-joda](https://github.com/js-joda/js-joda) does not currently handle timezone names (e.g. 'Europe/London'). This issue is being tracked [here](https://github.com/js-joda/js-joda/issues/32).
### Why doesn't world-clock work on Windows?
world-clock relies on [zoneinfo](https://github.com/gsmcwhirter/node-zoneinfo) which parses zoneinfo files from ```/usr/share/zoneinfo```. It therefore does not work on windows.