Date & time

One number, many clocks

Dates feel human: birthdays, deadlines, calendars, time zones, holidays. JavaScript’s Date is much simpler and much stranger: it stores one number, a timestamp in milliseconds since 1970-01-01T00:00:00.000Z. Everything else is a way to read or format that number.

That mental model connects lessons you already know. A timestamp is a Number. JSON.stringify turns dates into ISO strings, and JSON.parse can revive them in the JSON lesson. +date uses Object to primitive conversion to get the timestamp. Comparisons work because dates can become numbers.

Date.now() returns the current timestamp. Because “current” depends on when the reader loads the page, the playground below computes it only after the page mounts and labels the local results in your time zone. The same instant is shown several ways.

1const now = Date.now();2const instant = new Date(now);3instant.toISOString();4instant.toString();5instant.toLocaleString();6instant.toLocaleString("en-US", { timeZone: "Asia/Tokyo" });

new Date(timestamp) wraps the number. toISOString() shows the same instant in UTC. toString() and the default toLocaleString() show it through your environment’s local settings. When you need deterministic output, pass an explicit locale and timeZone to Intl.DateTimeFormat or toLocaleString options.

1const stamp = Date.UTC(2024, 0, 31, 12, 0, 0);Run2const moment = new Date(stamp);3const month = moment.getUTCMonth();4const iso = moment.toISOString();5const number = +moment;

There are four common ways to create dates. Use new Date() for the current instant, new Date(timestamp) when you already have milliseconds, Date.UTC(...) plus new Date(...) for deterministic components, and ISO strings for stored data.

Parsing is where old Date hurts. ISO strings are specified; many natural-language or slash formats are implementation-dependent. Try the lab, then notice which rows say UTC, local, offset, or invalid.

1new Date("2024-03-10");          // date-only ISO: UTC2new Date("2024-03-10T09:00");    // no offset: local time3new Date("2024-03-10T09:00Z");   // Z: UTC4new Date("2024-03-10T09:00+05:30");5new Date("March 10, 2024");      // non-ISO: avoid for data6new Date("not a date").getTime(); // NaN

ISO 8601 is the family of date formats like 2024-03-10T09:00:00.000Z. The Z suffix means UTC. An offset such as +05:30 means “this local clock time in a place five and a half hours ahead of UTC.” Both define a single instant.

Date.UTC(year, monthIndex, day, hour) is a reliable way to construct a timestamp from components. Remember the month index: January is 0, December is 11. It returns a number; wrap it with new Date(...) when you want Date methods.

Dates have local getters such as getFullYear(), getMonth(), getDate(), getDay(), and getHours(). They also have UTC versions: getUTCFullYear(), getUTCMonth(), and so on. The UTC versions are best for tests because they do not depend on the machine’s time zone.

1const jan31 = new Date(Date.UTC(2024, 0, 31, 9));2jan31.getUTCFullYear(); // 20243jan31.getUTCMonth();    // 0, January4jan31.getUTCDate();     // 31

Setters mutate the existing Date. They also overflow rather than clamp. If you ask for “February 31,” Date rolls into March. That is sometimes useful, sometimes a bug.

1const due = new Date(Date.UTC(2024, 0, 31, 9));Run2due.setUTCMonth(due.getUTCMonth() + 1);3due.setUTCDate(due.getUTCDate() + 7);4console.log(due.toISOString());

Date arithmetic

For exact instants, subtract timestamps. The result is milliseconds. Dividing by 86_400_000 gives 24-hour chunks. That is perfect for UTC timestamps like API expiry times, but it is not always the same as “calendar days in a local time zone” because daylight saving time can make local days 23 or 25 hours long.

1const a = new Date("2024-06-01T00:00:00Z");2const b = new Date("2024-06-01T00:00:00Z");3console.log(a === b);4console.log(a.getTime() === b.getTime());5console.log(a < new Date("2024-06-02T00:00:00Z"));

Two Date objects are objects, so === checks whether they are the same object, not whether they represent the same instant. Use getTime(), unary +date, or relational comparisons like < when you mean the timestamp.

1const due = new Date(Date.UTC(2024, 0, 31, 9));2due.setUTCMonth(due.getUTCMonth() + 1);3due.setUTCDate(due.getUTCDate() + 7);4console.log(due.toISOString());

toISOString, toJSON & toLocaleString

Use different output for machines and humans. toISOString() is for storage and APIs: always UTC, always a Z suffix. toJSON() calls toISOString(), which is why JSON turns Date objects into ISO strings. toLocaleString(), toLocaleDateString(), and Intl.DateTimeFormat are for people.

1const instant = new Date("2024-12-24T18:30:00Z");2console.log(instant.toISOString());3console.log(instant.toJSON());4console.log(new Intl.DateTimeFormat("en-GB", {5  weekday: "long",6  day: "numeric",7  month: "long",8  year: "numeric",9  timeZone: "UTC"10}).format(instant));

For UI, pass the locale and options on purpose: en-GB and en-US order dates differently; weekday and month: "long" make labels friendlier. The Internationalization with Intl lesson goes much deeper into formatting dates, numbers, lists, and plurals.

Where you’ll use this

Date work appears in forms, dashboards, calendars, cache expiration, logs, and API data. A practical workflow is: store an ISO string, revive or wrap it when you need Date methods, calculate with timestamps or UTC methods, then format at the edge for a specific audience.

Pitfalls & misconceptions

Key takeaways

• A Date stores one millisecond timestamp; methods choose how to read it.
• Date.now() and Date.UTC() return numbers. new Date(...) returns an object.
• Months are 0-based in component constructors and setters.
• Date-only ISO strings parse as UTC; date-time strings without offsets parse in local time.
• Use UTC methods and explicit timeZone options for deterministic tests.
• toISOString() is for machines; Intl.DateTimeFormat and locale methods are for people.

Up next: Temporal, the modern replacement that fixes many of Date’s pain points.