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

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
• Luxon
• date-fns
  Consult the blog post for the pros and cons of these libraries.

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

40.2. Background: UTC vs. GMT

UTC (Coordinated Universal Time) and GMT (Greenwich Mean Time) have the same current time, but they are different things:

• 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.

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

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():

• 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

40.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;
  new Date(timeValue).toISOString(),

Coercing a Date to a number returns its time value:

> Number(new Date(123))

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

// Internally:

40.4.1. Creating time values

The following methods create time values:

• Date.now(): number

Returns the current time as a time value.

• Date.parse(dateTimeString): number (local time zone)

Parses dateTimeString and returns the corresponding time value.

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

Returns the time value for the specified UTC date time.

40.4.2. Getting and setting time values

• Date.prototype.getTime(): number

• Date.prototype.setTime(timeValue)

Sets this to the date encoded by timeValue.

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

• new Date(dateTimeStr: string) (UTC)

> new Date('2077-01-27').toISOString()

• new Date(timeValue: number)

> new Date(0).toISOString()

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

40.6. Getters and setters

40.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:

• Time

  • : 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.

Example Date:

const d = new Date(0);

40.7.1. Strings with times

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

> d.toTimeString()

• Date.prototype.toLocaleTimeString() (see ECMAScript internationalization API)

40.7.2. Strings with dates

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

> d.toDateString()

• Date.prototype.toLocaleDateString() (ECMAScript internationalization API)

40.7.3. Strings with dates and times

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

• Date.prototype.toLocaleString() (see ECMAScript internationalization API)

'Thu, 01 Jan 1970 00:00:00 GMT'

• Date.prototype.toISOString() (UTC)

'1970-01-01T00:00:00.000Z'

40.8. Pitfalls of the Date API

• You can’t specify a local time zone. That can lead to location-specific bugs if you are not careful. For example, the following interaction leads to different results, depending on where it is executed. We execute it in CET, which is why the ISO string (in UTC) has a different day of the month (26 vs. 27).

> new Date(2077, 0, 27).toISOString()

• January is 0, February is 1, etc.:

> new Date(1979, 0, 27, 10, 30).toISOString()

• For years y with 0 ≤ y ≤ 99, 1900 is added:

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