Add a plugin with the time zone support

Update: Day.js Time Zone Plugin https://day.js.org/docs/en/timezone/timezone

Business Case

A typical application, which displayed dates and expects dates entered by the users handles the time zone:

1. Consistently. The user should not be confused by different components working in different time zones.
2. Either using the local time zone from the web browser (operating system).
3. Or using the time zone specified in the user settings of the web application.

Interface Synopsis

A minimal support could include the following two scenarios, typical for applications displaying and editing dates:

1. From the storage to the presentation. Format a UTC date to show it converted to the time zone chosen by the user.
2. From the presentation to the storage. Parse a date entered by the user in their chosen time zone and convert it to UTC.

The API for these scenarios could use the constructor and the format method:

const timeZone = 'Europe/Berlin' // Canonical time zone name

// String without a time zone from the date picker
const enteredDate = '2018-09-02 23:41:22'
const storedDate = dayjs(enteredDate, { timeZone }).toISOString()
// Will contain "2018-09-02T21:41:22Z"

// String in UTC or anything that Day.js accepts
const storedDate = '2018-09-02T21:41:22Z'
const userFormat = 'D.M.YYYY H:mm:ss [GMT]Z (z)' // Standard Day.js format
const displayedDate = dayjs(storedDate).format(userFormat, { timeZone })
// Will contain "2.9.2018 23:41:22 GMT+02:00 (CEST)"

Implementation Proposal

Day.js uses an embedded Date object. That is why this library is so lightweight, but it limits its functionality. The Date object supports only local time zone and UTC. It does not work in other time zones. It is possible to continue leveraging this principle. without making more complicated by replacing internal Date object with something else. All other methods continue working as expected.

dayjs(input: any, { timeZone: boolean }?)

Day.js already supports an optional options object in the constructor and the parse method. The time zone parameter in the constructor is meant only for converting the parsed input string correctly to UTC. The embedded Date object will be initialised with UTC and offer the local time zone representation as usual. The original time zone offset will not be remembered. It is usually not important, because dates should be rendered consistently in user’s time zone; not in various time zones, which their string sources referred to.

format(format: string, { timeZone: boolean }?)

The options object is optionally recognised by the overridden format method. The time zone parameter will extract the date parts (year, month, …) from the embedded this.$d object in UTC and convert them to the specified time zone, before producing the output string.

This can be delivered as a new plugin. Not everyone need the full time zone handling and if the implementation includes the time zone data, it will not be small.

[jpike88]

Yikes this has put me off migrating dayjs from moment. I’m surprised there isn’t an official plugin already.

If there is no easy equivalent of this code, it’s a problem:

import moment from 'moment-timezone';
moment.tz.setDefault(UserService.user.timezone); // global setting of timezone, moment will from now on respect this

[iamkun]

Day.js Time Zone Plugin https://day.js.org/docs/en/timezone/timezone