Brian Zindler - 12/29/19

The Javascript Date Class can be confusing because the value you see printed in the console is not its "real" value. This post aims to provide a sound mental model for reasoning about Javascript Date instances.

Internally Date instances are just an integer representing the number of seconds that have elapsed since 00:00:00 UTC on 1 January 1970. Otherwise known as a unix timestamp. You can see this number by calling [.valueOf](<https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/valueOf>) on a Date instance. The identity of a Date instance is this integer. All of the methods on a Date instance are just a translation layer between the user's computer and this value.

A Date instance's value is the same regardless of timezone. For example, if I run these two code examples in different timezones we can see that the .valueOf is the same.

🇺🇸Computer in San Francisco

🇧🇷Computer in Brazil

If the value is the same why is the console printing out 2 different times for the date variable? While a Date's value does not change based on the user's timezone the behavior of its methods will. In this case the [.toString](<https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toString>) method on the date instance is converting between the date's value and the user's local timezone.

Most of the setters and getters on the Date instance convert between the user's timezone and the Date's value. When calling a method on the Date instance it is important to ask "Is this method doing a timezone conversion?"

For example, lets say we are parsing a date string (new Date('02-28-2019')). Instantiating a date with a string will use [.parse](<https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/parse>) . Below we parse the same date in Brazil and San Francisco and we get different values.

🇺🇸Computer in San Francisco

🇧🇷Computer in Brazil

The parse method is interpreting the date as Feb 28 2019 00:00:00 in the user's local timezone then translating that to a unix timestamp. Because the timezone is different between Brazil and San Francisco we get different values.

As a rule of thumb, the Date methods without UTC in their name are doing a timezone conversion. The timezone that the Date methods use for conversion is the user's system timezone. Your Javascript program cannot override the system timezone used for the local getter/setter methods.

Example of Mac timezone settings.

So if you need to debug something Date related ask yourself:

"What is the date's real value (.valueOf)?"

"Is there a timezone conversion happening?"

"What timezone is the user's system clock set to?"

For most applications if you send UTC dates from the server, parse them as UTC on the client and display the time using the local timezone getter methods you should have no issues.