Dates

The Date class is JavaScript's API for working with dates and times. To create a Date object that represents the current date and time, use the constructor with no arguments. If you pass one numeric argument, the Date() constructor interprets it as the number of milliseconds since the 1970 epoch.

let now = new Date();
let epoch = new Date(0);

If you provide two or more integer arguments, they are interpreted as the year, month, day-of-month, hour, minute, second, and millisecond in your local time zone.

let future = new Date(2025, // Year 2025
   0, // January
   1, // 1st
   2, 3, 4, 5); // 02:03:04.005

The static method Date.UTC() takes the same arguments as the Date() constructor, interprets them in UTC, and returns a millisecond timestamp that you can pass to the Date() constructor. To display a date in UTC, convert it to a string with toUTCString() or toISOString() methods.

let birthday = new Date(Date.UTC(2000, 0, 1));
birthday.toUTCString(); // => 'Sat, 01 Jan 2000 00:00:00 GMT'
birthday.toISOString(); // => '2000-01-01T00:00:00.000Z'

When a string is provided to the Date() constructor, it will attempt to parse a date in the formats produced by the toString(), toUTCString() and toISOString() methods.

let century = new Date('2100-01-01T00:00:00.000Z');

After you have a Date object, you can query and modify the year, month, day-of-month, hour, minute, second, and millisecond fields.

let d = new Date(); // Start with the current date
d.setFullYear(d.getFullYear() + 1); // Increment the year
d.getMonth(); // => 4
d.getDate(); // => 16
d.getHours(); // => 19
d.getMinutes(); // => 37
d.getSeconds(); // => 47
d.getMilliseconds(); // => 593

Some methods allow you to set more than one field at a time. Note that getDay() and getUTCDate() methods return the read-only day-of-week (0 for Sunday through 6 for Saturday).

let alarm = new Date();
alarm.setFullYear(2025, 0, 1);
alarm.setUTCHours(10, 30, 40);
alarm.toUTCString(); // => 'Wed, 01 Jan 2025 10:30:40 GMT'
alarm.getDay(); // => 3

Timestamps

JavaScript represent dates internally as integers that specify the number of milliseconds since (or before) midnight on January 1, 1970, UTC time. The getTime() method returns this internal value, and the setTime() method sets it. The static method Date.now() returns the current timestamp. The static method Date.parse() parses a date in the formats produced by the toString(), toUTCString() and toISOString() methods and returns a timestamp.

d.setTime(d.getTime() + 30000);
Date.now(); // => 1715860594407
Date.parse('Sat, 01 Jan 2000 00:00:00 GMT'); // => 946684800000

The performance API allows measuring the elapsed time with high precision. The performance.now() function returns a timestamp since a web page was loaded or since the Node process was started. In order to use the performance object in node, you must import it first.

const {performance} = require('perf_hooks');
performance.now(); // => 4293.4000000059605

Date arithmetic

Date objects can be compared using the standard <, <=, >, and >= operators, which evaluate the number of milliseconds between the two dates. To add or subtract a specified number of days, months, or other time units, use the setDate(), setMonth(), and similar methods. If a Date field overflows, the next larger field is automatically incremented accordingly.

let date = new Date();
date.toISOString(); // => 2024-05-16T12:30:09.336Z
date.setMonth(date.getMonth() + 4);
date.setDate(date.getDate() + 20);
date.toISOString(); // => 2024-10-06T12:30:09.336Z

The Date class defines a few methods that convert Date objects to strings.

let aDate = new Date(2025, 0, 20, 15, 10, 30);
aDate.toString(); // => 'Mon Jan 20 2025 15:10:30 GMT+0800 (Taipei Standard Time)'
aDate.toLocaleString(); // => '1/20/2025, 3:10:30 PM'

aDate.toUTCString(); // => 'Mon, 20 Jan 2025 07:10:30 GMT'
aDate.toISOString(); // => '2025-01-20T07:10:30.000Z'

aDate.toDateString(); // => 'Mon Jan 20 2025'
aDate.toLocaleDateString(); // => '1/20/2025'

aDate.toTimeString(); // => '15:10:30 GMT+0800 (Taipei Standard Time)'
aDate.toLocaleTimeString(); // => '3:10:30 PM'