@js-joda/timezone

What is @js-joda/timezone?

@js-joda/timezone is an npm package that extends the js-joda library to handle time zones. It provides functionality for working with dates and times in different time zones, making it easier to perform operations like converting between time zones, getting the current time in a specific time zone, and more.

What are @js-joda/timezone's main functionalities?

Convert between time zones

This feature allows you to convert a date and time from one time zone to another. The code sample demonstrates converting the current time in 'America/New_York' to 'Europe/London'.

const { ZonedDateTime, ZoneId } = require('@js-joda/core');
const { ZoneRulesProvider } = require('@js-joda/timezone');

const zonedDateTime = ZonedDateTime.now(ZoneId.of('America/New_York'));
const convertedDateTime = zonedDateTime.withZoneSameInstant(ZoneId.of('Europe/London'));
console.log(convertedDateTime.toString());

Get current time in a specific time zone

This feature allows you to get the current time in a specific time zone. The code sample demonstrates getting the current time in 'Asia/Tokyo'.

const { ZonedDateTime, ZoneId } = require('@js-joda/core');
const { ZoneRulesProvider } = require('@js-joda/timezone');

const currentTimeInTokyo = ZonedDateTime.now(ZoneId.of('Asia/Tokyo'));
console.log(currentTimeInTokyo.toString());

List available time zones

This feature allows you to list all available time zones. The code sample demonstrates how to retrieve and print all available time zone IDs.

const { ZoneId } = require('@js-joda/core');
const { ZoneRulesProvider } = require('@js-joda/timezone');

const availableZoneIds = ZoneRulesProvider.getAvailableZoneIds();
console.log(availableZoneIds);

Other packages similar to @js-joda/timezone

moment-timezone

moment-timezone is an extension for moment.js that adds support for time zones. It allows you to parse, manipulate, and display dates and times in different time zones. Compared to @js-joda/timezone, moment-timezone is built on top of the moment.js library, which is more widely used but also larger in size and less modern in its API design.

luxon

Luxon is a modern JavaScript library for working with dates and times, created by one of the Moment.js developers. It includes built-in support for time zones and offers a more modern and immutable API compared to moment-timezone. Luxon is similar to @js-joda/timezone in its approach to immutability and modern API design.

date-fns-tz

date-fns-tz is a time zone extension for the date-fns library. It provides functions for working with dates and times in different time zones, similar to @js-joda/timezone. date-fns-tz is known for its modular approach, allowing you to include only the functions you need, which can result in smaller bundle sizes.

README

@js-joda/timezone

Motivation

Implementation of the js-joda ZoneRulesProvider, providing the bindings to the iana tzdb, using latest zone file generated by moment-timezone

Usage

Node

Install joda using npm

npm install @js-joda
npm install @js-joda/timezone

es5

var jsJoda = require('@js-joda/core')
require('@js-joda/timezone')

var { LocalDateTime, ZoneId, ZonedDateTime } = jsJoda;
     
LocalDateTime
    .parse('2016-06-30T11:30')
    .atZone(ZoneId.of('Europe/Berlin'))
    .toString()  // 2016-06-30T11:30+02:00[Europe/Berlin]
     
ZonedDateTime
    .parse('2016-06-30T11:30+02:00[Europe/Berlin]') 
    .withZoneSameInstant(ZoneId.of('America/New_York'))
    .toString() // 2016-06-30T05:30-04:00[America/New_York]

ZonedDateTime
    .parse('2016-06-30T11:30+02:00[Europe/Berlin]')
    .withZoneSameLocal(ZoneId.of('America/New_York'))
    .toString() // 2016-06-30T11:30-04:00[America/New_York]

es6 / typescript

import { ZonedDateTime, ZoneId } from '@js-joda/core'
import '@js-joda/timezone'

const zdt = ZonedDateTime.now(ZoneId.of('America/New_York'))

Browser

<script src="./packages/core/dist/js-joda.js"></script>
<script src="./packages/timezone/dist/js-joda-timezone.js"></script>
<script>
    // copy all js-joda classes to the global scope
    for(let key in JSJoda) { this[key] = JSJoda[key]; }
        
    LocalDateTime
        .parse('2016-06-30T11:30')
        .atZone(ZoneId.of('Europe/Berlin'))
        .toString()  // 2016-06-30T11:30+02:00[Europe/Berlin]
         
    ZonedDateTime
        .parse('2016-06-30T11:30+02:00[Europe/Berlin]') 
        .withZoneSameInstant(ZoneId.of('America/New_York'))
        .toString() // 2016-06-30T05:30-04:00[America/New_York]

    ZonedDateTime
        .parse('2016-06-30T11:30+02:00[Europe/Berlin]')
        .withZoneSameLocal(ZoneId.of('America/New_York'))
        .toString() // 2016-06-30T11:30-04:00[America/New_York]
</script>

Reducing js-joda-timezone file size

If you don't need all the historical data that @js-joda/timezone provides, you can instead use one of the reduced files ize builds:

• js-joda-timezone-10-year-range.js covers +- five years from the current version's release
• js-joda-timezone-1970-2030.js covers from 1970 to 2030
• js-joda-timezone-2012-2022.js covers from 2012 to 2022 // deprecated, will be removed in future releases
• js-joda-timezone-2017-2027.js covers from 2017 to 2027

To use one of these, just change your import path to the following format:

import '@js-joda/timezone/dist/js-joda-timezone-1970-2030'

Implementation details

• This ZoneRulesProvider implemantion supplies all functionality that is required by the js-joda package.
• Additional ZoneRules functionality like transitions(), etc. is not implemented.

License

• @js-joda/timezone is released under the BSD 3-clause license:

• The author of joda time and the lead architect of the JSR-310 is Stephen Colebourne.

• The json versions of the iana tzdb are imported from and generated with moment-timezone.