Dealing with Timezone and Moment.js handling

Dec 22, 2018

You’re a good developer. You and your nice team are producing useful features for your clients. Everything is good till one day, your client sends to your team a report that their users complained about the time was displayed wrong when they changed their locations. The root cause is that your team hasn’t managed about timezone issue when implementing features. Oops!!!

People fear what they don’t understand

Handling timezone is a common issue within our applications, especially when our applications serve customers in many different countries. In this article, we’ll find out and understand more about timezone and hopefully, it will help us apply timezone to our applications better.

Standard Time And Date

You know we have 24 hours in one day. Everyone lives in the world in different countries will see different times. For example, I live in Vietnam and usually make a phone call at 9:00 P.M to my friend, who is an overseas student in Canada. She says “Good evening” and I say “Good morning”, because it’s 9:00 A.M at her side. So we call that our times, 9:00 P.M for me and 9:00 A.M for her, are local time. Because it depends on geographical location.

time zone on the world
time zone on the world

For convenience, people invent a standard date and time that we use to communicate with each other it calls ISO 8601 (I strongly recommend you to visit wiki page because it contains a good explanation).

Timezone

What’s time zone?

Time zone is a region of the globe that observes a uniform standard time which is offset from Coordinated Universal (UTC).

Please look at the image above. Let say we pick up the middle longitude in our map as UTC time. If I said that my country’s time zone is +07:00, it means that my country’s longitude is right side of UTC’s longitude and my time is ahead of UTC time, showing a positive number (+). My friend’s time zone, who I mentioned above at Canada, is -05:00. It means that her country’s longitude is left side of UTC’s longitude and her time is behind of UTC time, showing a negative number (-).

So how can I know what’s my friend time when I call her at 9:00 P.M in my side? Let’s do simple math. 9:00 P.M at my side is the same at 2:00 P.M UTC time, because my time zone is ahead of UTC 7 hours (+07:00). My friend time zone is behind UTC 5 hours (-05:00). It means 2:00 P.M UTC time is the same at 9:00 A.M. That’s all.

Time Standard Format

UTC Time

Let’s say we have 9:30:15 UTC time, so its standard symbols can be: 9:30:15Z or 093015Z (Z means zero UTC offset).

Time Offsets from UTC

time offset
time offset

Without Z symbol at the end of time, time offset appends negative or positive number instead. Such as the time at Canada, the zone designator would be -05:00 or -0500 or ismply -05. The zone designator at Vietnam would be +07:00 or +0700 or simply +07.

Note: In case missing Z or time offsets at the end of time, it means that we’re talking about local time. E.g: 10:30.

Combine With Date

The letter T is a delimiter between date and time representations. E.g: 2018-12-22T13:36:00.

With all that knowledge about standard time format, let do a quick practice:

  • 2018–12–22T11:42:00 means 11:42:00 local time on Dec 12, 2018.
  • 2018–12–22T11:42:00Z means 11:42:00 UTC time on Dec 12, 2018.
  • 2018–12–22T11:42:00+0700 means 11:42:00 UTC+7 time on Dec 12, 2018.
  • 2018–12–22T11:42:00-0500 means 11:42:00 UTC-5 time on Dec 12, 2018.

In the second part, we’ll go to our case regarding handle timezone in our application.

Issue Timezone Description

Issue timezone
Issue timezone

Our application is a website for clinician admin who can manage patient’s information. The patients, who live in Brazil, use a mobile application to perform assigned exercises from their doctor. All patient information will be sent to our server at San Francisco, we called it server side.

The requirement is that clinician admins who live in Vietnam can see all patient information, especially timing is at patient’s time, not at the local time in Vietnam.

Store A Date In Server Side

The best practice is we should store our patient’s date as UTC time in our server side. Thanks to moment.js and its supported library moment-timezone, we can handle this thing easily.

const moment = require('moment')
const momentTz = require('moment-timezone')

const dateToStore = '2018-01-27 10:30' // Patient local time at Brazil
const patientTimezone = 'America/Lima' // Patient timezone at Brazil

const momentDateTzUTC = momentTz.tz(dateToStore, 'YYYY-MM-DD HH:mm', patientTimezone).utc().format() // 2018-01-27T15:30:00Z

At our server side, we’ll store momentDateTzUTC result as a string field in our database and one more field such as patient_time_zone to store our patient’s time zone, in this case is America/Lima.

Display A Date In Web Application

From the date in UTC format and patient’s time zone we can show patient’s time in our website:

const moment = require('moment')
const momentTz = require('moment-timezone')

const dateToDisplay = '2018-01-27T15:30:00Z' // Date in UTC stored at server side
const patientTimezone = 'America/Lima' // Patient timezone at Brazil
const result = momentTz.tz(dateToDisplay, 'YYYY-MM-DDTHH:mm:ssZ', patientTimezone) // 2018-01-27T10:30:00-05:00

Now you can see the displayed time result is the same as the original patient’s time we store in the beginning.

Summary

Hopefully, after this article, you can understand more about time zone and how to store or display time correctly with the support from powerful library moment.js.