Please support this book: buy it or donate

40. Dates (Date)

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

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

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

40.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():
  1. '2033-05-28T15:59:59.123Z'

Date time formats have the following structures:

  • Date formats: Y=year; M=month; D=day
  1. YYYY-MM-DD
  2. YYYY-MM
  3. YYYY
  • Time formats: T=separator (the string 'T'); H=hour; m=minute; s=second and millisecond; Z=time zone is UTC (the string 'Z')
  1. THH:mm:ss.sss
  2. THH:mm:ss.sssZ
  4. THH:mm:ss
  5. THH:mm:ssZ
  7. THH:mm
  8. 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:

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

Coercing a Date to a number returns its time value:

  1. > Number(new Date(123))
  2. 123

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

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

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

Returns the time value corresponding to the Date.

  • Date.prototype.setTime(timeValue)

Sets this to the date encoded by timeValue.

40.5. Creating Dates

  • new Date(year: number, month: number, date?: number, hours?: number, minutes?: number, seconds?: number, milliseconds?: number) (local time zone)
  1. > new Date(2077,0,27, 21,49,58, 888).toISOString() // CET (UTC+1)
  2. '2077-01-27T20:49:58.888Z'
  • new Date(dateTimeStr: string) (UTC)
  1. > new Date('2077-01-27').toISOString()
  2. '2077-01-27T00:00:00.000Z'
  • new Date(timeValue: number)
  1. > new Date(0).toISOString()
  2. '1970-01-01T00:00:00.000Z'
  • 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:

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

40.7. Converting Dates to strings

Example Date:

  1. const d = new Date(0);

40.7.1. Strings with times

  • Date.prototype.toTimeString() (local time zone)
  1. > d.toTimeString()
  2. '01:00:00 GMT+0100 (Central European Standard Time)'

40.7.2. Strings with dates

  • Date.prototype.toDateString() (local time zone)
  1. > d.toDateString()
  2. 'Thu Jan 01 1970'

40.7.3. Strings with dates and times

  • Date.prototype.toString() (local time zone)
  1. > d.toString()
  2. 'Thu Jan 01 1970 01:00:00 GMT+0100 (Central European Standard Time)'
  1. > d.toUTCString()
  2. 'Thu, 01 Jan 1970 00:00:00 GMT'
  • Date.prototype.toISOString() (UTC)
  1. > d.toISOString()
  2. '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).
  1. > new Date(2077, 0, 27).toISOString()
  2. '2077-01-26T23:00:00.000Z'
  • January is 0, February is 1, etc.:
  1. > new Date(1979, 0, 27, 10, 30).toISOString()
  2. '1979-01-27T09:30:00.000Z'
  • For years y with 0 ≤ y ≤ 99, 1900 is added:
  1. > new Date(12, 1, 22, 19, 11).toISOString()
  2. '1912-02-22T18:11:00.000Z'