Pages

2014-02-14

JavaScript time values: dates as milliseconds since 1970-01-01

This blog post explains how JavaScript dates are stored internally as time values, milliseconds since 1970-01-01.

What the date API calls time is called a time value by the ECMAScript specification. It is a primitive number that encodes a date as milliseconds since 1 January 1970 00:00:00 UTC. Each date object stores its state as a time value, in the internal property [[PrimitiveValue]] (the same property that instances of the wrapper constructors Boolean, Number, and String use to store their wrapped primitive values).

Warning: Leap seconds are ignored in time values.

The following methods work with time values:

new Date(timeValue) uses a time value to create a date.

Date.parse(dateTimeString) parses a string with a date time string and returns a time value.

Date.prototype.getTime() returns the time value stored in the receiver.

Date.prototype.setTime(timeValue) changes the date as specified via a time value.

Date.prototype.valueOf() returns the time value stored in the receiver. This method determines how dates are converted to primitives, as explained in the next subsection.

The range of JavaScript integers (53 bits plus a sign, see [1]) is large enough that a time span can be represented that starts at approximately 285,616 years before 1970 and ends at approximately 285,616 years after 1970.