Time & Date

Tomasz Bogusz

ECMAScript Epoch: Milliseconds Since 1st January 1970 UTC

An instance of the JavaScript Date() constructor function primarily represents the ECMAScript Epoch i.e. a number of milliseconds that have elapsed since the 1st January UTC. Adversely, the UNIX Epoch represents the number seconds that have elapsed since 1st January 1970 UTC.

Coordinated Universal Time (UTC) & Local Time

As noted, instances of the ECMAScript Epoch are calculated on the basis of the Coordinated Universal Time but a specific client (host) system might be within a time zone with the local time differing from the UTC. Instances of Date() come with methods that allow for getting and setting both local time and UTC.

Date() Object Initialization

To get a new Date() object representing the current local (host) time use new Date().

new Date() // => Tue Sep 28 2021 08:40:08 GMT+0200 (Central European Summer Time)

To get a new Date() object on the basis of a specified local time use new Date(year, month, day, hour, minute, second, millisecond). Month is zero indexed but a day of the month is not.

new Date(1984, 0, 24, 5, 0, 0, 0) // => Tue Jan 24 1984 05:00:00 GMT+0100 (Central European Standard Time)

To get a new Date() object on the basis of a specified UTC time use new Date(Date.UTC(year, month, day, hour, minute, second)).

const macLaunchDate = new Date(Date.UTC(1984, 0, 24, 5, 0, 0)) // => Tue Jan 24 1984 06:00:00 GMT+0100 (Central European Standard Time)
macLaunchDate.toUTCString() // => Tue, 24 Jan 1984 05:00:00 GMT

Instance Methods

Instances JavaScript Date() have many getter built-in methods such as:

  • getTime() - returns the JavaScript Epoch,

  • getTimezoneOffset() - returns timezone offset between local time & UTC,

  • getFullYear() & getUTCFullYear(),

  • getMonth() & getUTCMonth(),

  • getDate() & getUTCDate() - date of a month,

  • getDay() & getUTCDay() - day of a week,

  • getHours() & getUTCHours(),

  • getMinutes() & getUTCMinutes(),

  • getSeconds() & getUTCSeconds(),

  • getMilliseconds() & getUTCMilliseconds(), and

  • methods allowing for getting textual representations of JavaScript Date() instances such as toString(), toDateString(), toISOString(), toLocaleDateString(), toUTCString(), etc.

Most of the getter methods have corresponding setter methods such as setDate(), setTime(), setFullYear(), setUTCFullYear(), etc.

Adding & Subtracting Dates

As each instance of the Date() object primarily represents a number of milliseconds since 1st January 1970 they can be - as numbers - added & subtracted.

const dateA = new Date(2021, 05, 30)
const dateB = new Date(2021, 05, 15)
const dateDiffNo = dateA - dateB // => 1296000000
const dateDiff = new Date(dateDiffNo)
dateDiff // => Fri Jan 16 1970 00:00:00 which is 15 days from the JavaScript Epoch and therefore the difference in days between dateA & dateB

It needs to be mentioned that deriving and presenting the actual passed time in days, months & years in the way described above can be burdened with errors as days, months & years can have different lengths.

Date.UTC() Static Method

The static method UTC() of Date() returns the JavaScript Epoch.