41 Dates (Date)

This chapter describes JavaScript’s API for working with dates – the class Date.

41.1 Best practice: don’t use the current built-in API

The JavaScript Date API is cumbersome to use. Hence, it’s best to rely on a library for anything related to dates. Popular libraries include:

• Moment.js
• Day.js
• Luxon
• js-joda
• date-fns

Consult the blog post “Why you shouldn’t use Moment.js…” for the pros and cons of these libraries.

Additionally, TC39 is working on a new date API for JavaScript: temporal.

41.1.1 Things to look for in a date library

Two things are important to keep in mind:

• Tree-shaking can considerably reduce the size of a library. It is a technique of only deploying those exports of a library to a web server, that are imported somewhere. Functions are much more amenable to tree-shaking than classes.

• Support for time zones: As explained later, Date does not support time zones, which introduces a number of pitfalls and is a key weakness. Make sure that your date library supports them.

41.2 Time zones

41.2.1 Background: UTC vs. GMT

UTC (Coordinated Universal Time) and GMT (Greenwich Mean Time) are ways of specifying time that are similar, but subtly different:

• UTC: is the time standard that all times zones are based on. They are specified relative to it. That is, no country or territory has UTC as its local time zone.

• GMT: is a time zone used in some European and African countries. It is UTC plus zero hours and therefore has the same time as UTC.

Source: “The Difference Between GMT and UTC” at TimeAndDate.com

41.2.2 Dates only support UTC and the local time zone

You can’t specify arbitrary time zones for JavaScript dates. Two time systems are used:

• UTC
• The local time zone (picked up automatically from the operating system)

Instances of Date store their time in UTC. Whenever you convert between dates and other data, you need to be mindful of whether UTC or the local time zone is used. For example: new Date() uses the local time zone, while .toISOString() uses UTC.

> new Date(2077, 0, 27).toISOString()
'2077-01-26T23:00:00.000Z'

Dates interpret 0 as January. The day of the month is 27 in the local time zone, but 26 in UTC.

41.2.3 The downsides of not being able to specify time zones

Not being able to specify time zones, has two downsides:

• It makes it impossible to support multiple time zones.

• It can lead to location-specific bugs. For example, the previous example produces different results, depending on where it is executed. In this particular case, the input was interpreted as CET, while the output was in UTC. That’s why the days of the month differed (27 vs. 26).

41.3 Background: date time formats (ISO)

Date time formats describe:

• The strings accepted by:
  • Date.parse()
  • new Date()
• The strings returned by (always longest format):
  • Date.prototype.toISOString()

The following is an example of a date time string returned by .toISOString():

'2033-05-28T15:59:59.123Z'

Date time formats have the following structures:

• Date formats: Y=year; M=month; D=day

  YYYY-MM-DD
  YYYY-MM
  YYYY

• Time formats: T=separator (the string 'T'); H=hour; m=minute; s=second and millisecond; Z=time zone is UTC (the string 'Z')

  THH:mm:ss.sss
  THH:mm:ss.sssZ
  
  THH:mm:ss
  THH:mm:ssZ
  
  THH:mm
  THH:mmZ

• Date time formats: are date formats followed by time formats.

  • For example (longest): YYYY-MM-DDTHH:mm:ss.sssZ

Alternative to Z – time zones relative to UTC:

• +hh:mm
• -hh:mm

41.4 Time values

A time value represents a date via the number of milliseconds since 1 January 1970 00:00:00 UTC.

Time values can be used to create Dates:

const timeValue = 0;
assert.equal(
  new Date(timeValue).toISOString(),
  '1970-01-01T00:00:00.000Z');

Coercing a Date to a number returns its time value:

> Number(new Date(123))
123

Ordering operators coerce their operands to numbers. Therefore, you can use these operators to compare Dates:

assert.equal(new Date('1972-05-03') < new Date('2001-12-23'), true);
// Internally:
assert.equal(73699200000 < 1009065600000, true);

41.4.1 Creating time values

The following methods create time values:

• Date.now(): number

  Returns the current time as a time value.

• Date.parse(dateTimeStr: string): number (time zone specified in string)

  Parses dateTimeStr and returns the corresponding time value.

• Date.UTC(year, month, date?, hours?, minutes?, seconds?, milliseconds?): number (UTC)

  Returns the time value for the specified UTC date time.

41.4.2 Getting and setting time values

• Date.prototype.getTime(): number

  Returns the time value corresponding to the Date.

• Date.prototype.setTime(timeValue)

  Sets this to the date encoded by timeValue.

41.5 Creating Dates

• new Date(year: number, month: number, date?: number, hours?: number, minutes?: number, seconds?: number, milliseconds?: number) (local time zone)

  > new Date(2077,0,27, 21,49).toISOString() // CET (UTC+1)
  '2077-01-27T20:49:00.000Z'

  Note how input (local time zone) and output (UTC) differ.

• new Date(dateTimeStr: string) (time zone specified in string)

  > new Date('2077-01-27T21:49').toISOString() // local = CET
  '2077-01-27T20:49:00.000Z'
  > new Date('2077-01-27T21:49Z').toISOString() // Z = UTC
  '2077-01-27T21:49:00.000Z'

• new Date(timeValue: number)

  > new Date(0).toISOString()
  '1970-01-01T00:00:00.000Z'

• new Date() (same as new Date(Date.now()))

41.5.1 Pitfalls of the first constructor

The first variant of new Date() receives two time units that are problematic:

• For month, 0 is January, etc.

• If 0 ≤ year ≤ 99, then 1900 is added:

  > new Date(12, 1, 22, 19, 11).getFullYear()
  1912

  That’s why, elsewhere in this chapter, we always use the time unit fullYear. But in this case, we have no choice.

41.6 Getters and setters

41.6.1 Time unit getters and setters

Dates have getters and setters for time units. For example:

• Date.prototype.getFullYear()
• Date.prototype.setFullYear(num)

These getters and setters conform to the following patterns:

• Local time:
  • Date.prototype.get«Unit»()
  • Date.prototype.set«Unit»(num)
• Universal time:
  • Date.prototype.getUTC«Unit»()
  • Date.prototype.setUTC«Unit»(num)

These are the time units that are supported:

• Date
  • FullYear
  • Month: month (0–11). Pitfall: 0 is January, etc.
  • Date: day of the month (1–31)
  • Day (getter only): day of the week (0–6, 0 is Sunday)
• Time
  • Hours: hour (0–23)
  • Minutes: minutes (0–59)
  • Seconds: seconds (0–59)
  • Milliseconds: milliseconds (0–999)

There is one more getter that doesn’t conform to the previously mentioned patterns:

• Date.prototype.getTimezoneOffset()

  Returns the time difference between local time and UTC in minutes. For example, for CET, it returns -60.

41.7 Converting Dates to strings

Example Date:

const d = new Date(0);

41.7.1 Strings with times

• Date.prototype.toTimeString() (local time zone)

  > d.toTimeString()
  '01:00:00 GMT+0100 (Central European Standard Time)'

41.7.2 Strings with dates

• Date.prototype.toDateString() (local time zone)

  > d.toDateString()
  'Thu Jan 01 1970'

41.7.3 Strings with dates and times

• Date.prototype.toString() (local time zone)

  > d.toString()
  'Thu Jan 01 1970 01:00:00 GMT+0100 (Central European Standard Time)'

• Date.prototype.toUTCString() (UTC)

  > d.toUTCString()
  'Thu, 01 Jan 1970 00:00:00 GMT'

• Date.prototype.toISOString() (UTC)

  > d.toISOString()
  '1970-01-01T00:00:00.000Z'

41.7.4 Other methods

The following three methods are not really part of ECMAScript, but rather of the ECMAScript internationalization API. That API has significant functionality for formatting dates (incl. support for time zones), but not for parsing them.

• Date.prototype.toLocaleTimeString()
• Date.prototype.toLocaleDateString()
• Date.prototype.toLocaleString()