Dates and times

What a Date really is

A Date object stores one number: the milliseconds since midnight UTC on 1 January 1970 (called the Unix epoch). UTC (Coordinated Universal Time) is the world reference time with no time zone offset. Everything else (the year, the hour you see) is calculated from that number using a time zone.

const now = new Date();
console.log(now.getTime());       // e.g. 1792400000000 (ms since 1970 UTC)
console.log(Date.now());          // the same number without creating a Date
console.log(now.toISOString());   // e.g. '2026-10-19T11:40:00.000Z' (Z means UTC)

Creating dates

new Date('2026-01-15T10:00:00Z');   // from an ISO string in UTC (safest)
new Date(Date.UTC(2026, 0, 15, 10)); // from parts in UTC
new Date(2026, 0, 15);               // from parts in the LOCAL time zone
new Date(0);                         // the epoch

Reading parts

getFullYear, getMonth, getDate (day of month), getDay (day of week, 0 = Sunday), getHours… use the LOCAL time zone of the computer running the code. The getUTC… versions use UTC. On a server in Mumbai and a server in Frankfurt the local getters give different answers for the same moment.

Date arithmetic

const DAY = 24 * 60 * 60 * 1000;
const booked = new Date('2026-03-01T00:00:00Z');
const journey = new Date('2026-03-15T00:00:00Z');
console.log((journey - booked) / DAY);          // 14 (subtracting Dates gives ms)
const due = new Date(booked.getTime() + 30 * DAY);
console.log(due.toISOString().slice(0, 10));    // '2026-03-31'

Time zones and India

India Standard Time (IST) is UTC+5:30 all year, with no daylight-saving changes. Many countries do change their clocks, which is why "add 24 hours" and "the same time tomorrow" are not always the same thing abroad. The safe rule: store and send times in UTC (ISO strings ending in Z), and convert to a time zone only when showing them to a person.

const d = new Date(Date.UTC(2026, 0, 15, 6, 30)); // 06:30 UTC
const ist = new Intl.DateTimeFormat('en-IN', {
  timeZone: 'Asia/Kolkata', dateStyle: 'medium', timeStyle: 'short',
}).format(d);
console.log(ist); // '15 Jan 2026, 12:00 pm' (06:30 + 5:30)

Parsing pitfalls

new Date('2026-01-15') (date only) is read as UTC midnight, but new Date('2026-01-15T10:00') (date and time, no Z) is read as LOCAL time. Strings like '15/01/2026' are not reliably parsed at all. Parse Indian-format dates yourself by splitting the parts.

Temporal: the modern date API

Because Date has so many traps, TC39 designed a new API called Temporal, with separate types such as Temporal.PlainDate (a calendar date with no time zone) and Temporal.ZonedDateTime. It is arriving in JavaScript engines; check MDN's browser compatibility table before relying on it, and until then libraries like date-fns or Day.js are common in projects.