JavaScript Date & Time Handling

Date is the canonical example of a bad date API, and its problems are structural. It is mutable; its month argument is 0-indexed (so new Date(2009, 0, 1) is January) while day-of-month is 1-indexed; two Dates are compared by reference, so a === b is almost always false; it reports epoch time in milliseconds (the off-by-1000 trap against Unix-seconds APIs); it parses non-ISO strings in implementation-defined ways; and it models only “local” and “UTC” with no real time-zone support. Each of these has its own section below.

new Date(2009, 0, 1);   // Jan 1, 2009 — month 0 is January (!)
new Date() === new Date();  // false — reference equality
Date.now();               // milliseconds, not seconds

For nine years the workaround was a library (Moment, then Luxon / date-fns / Day.js). The real fix is Temporal, which is immutable, time-zone-aware, and unambiguous by construction.

Source: MDN — Date.

Temporal splits the one overloaded Date into purpose-named, immutable types. Temporal.Instant is an exact moment on the timeline (like an epoch reading). Temporal.ZonedDateTime is an instant plus an IANA time zone — the fullest type, and the right default for “a moment, somewhere.” Temporal.PlainDate, PlainTime, and PlainDateTime are wall values with no zone (a birthday, an opening time). PlainYearMonth and PlainMonthDay cover partial dates; Temporal.Duration is an amount of time; and Temporal.Now is the clock.

Temporal.Now.instant();               // an exact moment (Instant)
Temporal.Now.zonedDateTimeISO();       // moment + your IANA zone
Temporal.PlainDate.from("2009-06-15");  // a wall date, no zone
Temporal.Instant.from("2009-06-15T20:45:30.617Z");

Rule of thumb: an absolute instant → Instant or ZonedDateTime; a wall date/time with no zone → PlainDate/PlainTime; an amount → Duration. Temporal reached Stage 4 in March 2026 and is slated for ECMAScript 2027; it ships in current engines, with a polyfill for Safari (as of July 2026).

Source: MDN — Temporal / TC39 Temporal docs.

Date.now() is the fast path to the current epoch in milliseconds (a number, no object allocated). new Date() gives a Date object for the same instant. For a Temporal value, Temporal.Now.instant() or Temporal.Now.zonedDateTimeISO(). And for elapsed time, none of these — use performance.now(), which is monotonic (see the precision section).

Date.now();                       // 1245098730617 (ms since epoch)
new Date();                       // a Date object at "now"
Temporal.Now.zonedDateTimeISO();  // now, in your IANA zone
performance.now();               // monotonic — for measuring, not clock time

Source: Date.now / Temporal.Now.

There is no native format string (see the reference above). For human-readable output, use toLocaleString / toLocaleDateString / toLocaleTimeString with an Intl.DateTimeFormat options object; for machine output, toISOString(). Build one Intl.DateTimeFormat and reuse it — constructing the formatter is the expensive part. The legacy toString / toDateString / toUTCString exist but are fixed-format and rarely what you want.

const fmt = new Intl.DateTimeFormat("en-US", {
  dateStyle: "long", timeStyle: "short", timeZone: "America/Los_Angeles" });
fmt.format(d);        // "June 15, 2009 at 1:45 PM"
d.toISOString();      // "2009-06-15T20:45:30.617Z" — machine output

No token syntax natively — reach for Intl, a library, or Temporal.toLocaleString.

Source: MDN — Intl.DateTimeFormat.

ISO 8601 is the only format you can rely on across engines; anything else ("June 15, 2009", "06/15/2009") is implementation-defined and may differ between browsers. The headline gotcha: a bare date "2025-03-15" parses as UTC midnight, but the same value with a time "2025-03-15T00:00" parses as local midnight — so in a US zone the first can display as March 14. Date.parse is the same parser as new Date(string), returning ms (or NaN). Temporal’s from methods are strict and unambiguous.

new Date("2025-03-15");       // UTC midnight → Mar 14 evening in the US
new Date("2025-03-15T00:00"); // LOCAL midnight → Mar 15
Temporal.PlainDate.from("2025-03-15");  // a date, no zone, no surprise

To parse a non-ISO layout, use a library’s explicit parser rather than trusting new Date(string).

Source: MDN — Date.parse (“date-only strings are treated as UTC”).

Native Date knows only two zones: the runtime’s local zone and UTC. You can format in any IANA zone with Intl.DateTimeFormat’s timeZone option, and read the local zone from Intl.DateTimeFormat().resolvedOptions().timeZone — but you can’t do zone math on a Date. That’s what Temporal.ZonedDateTime is for: it carries an IANA zone and does DST-aware arithmetic, with an explicit disambiguation option for the ambiguous (fall-back) and skipped (spring-forward) local times. JavaScript is IANA-only — there’s no Windows-vs-IANA zone-id tripwire (the one place JS is simpler than C#).

new Intl.DateTimeFormat("en-US", { timeZone: "Asia/Tokyo",
  dateStyle: "short", timeStyle: "short" }).format(d);
new Intl.DateTimeFormat().resolvedOptions().timeZone;  // "America/New_York"
Temporal.Now.instant().toZonedDateTimeISO("Asia/Tokyo");  // zone math

Source: Intl timeZone / Temporal.ZonedDateTime.

Every Date getter has a UTC twin: getHours() reads local, getUTCHours() reads UTC; likewise getUTCFullYear, getUTCMonth, getUTCDate, and so on. To build from UTC parts, Date.UTC(...) returns the epoch ms (whereas the new Date(y, m, d, ...) constructor interprets its parts as local). toISOString() always emits UTC. With Temporal, convert between an absolute Instant and a zoned view with .toZonedDateTimeISO(zone) / .toInstant().

d.getUTCHours();          // 20 (UTC)  vs  d.getHours() → local
Date.UTC(2009, 5, 15, 20, 45, 30);  // epoch ms from UTC parts (month 5 = June)
d.toISOString();          // "2009-06-15T20:45:30.617Z" — always UTC

Source: Date.UTC / toISOString.

With native Date there is no addDays — you mutate in place with setDate(getDate() + 1) (which conveniently rolls over month boundaries) or do epoch-ms math. Both are error-prone: the mutation changes the original, and a “day” of 86_400_000 ms isn’t always 24 hours across a DST boundary. Temporal is immutable and calendar-aware: .add() / .subtract() take a Duration and return a new value, respecting DST and month lengths.

const d2 = new Date(d);      // copy first — setDate mutates!
d2.setDate(d2.getDate() + 1);  // +1 day (rolls over months)

Temporal.PlainDate.from("2009-06-15").add({ days: 1 });
// → 2009-06-16, immutable, calendar-aware

Source: Date.setDate / Temporal.Duration.

Subtract them — the - operator coerces each Date to its epoch milliseconds, so the result is a number of ms. Divide by 86_400_000 for days, 3_600_000 for hours, and so on. There is no native “3 months, 2 days” breakdown — months and years aren’t fixed lengths. Temporal gives calendar-aware differences with .since() / .until(), which return a Duration.

const ms = date2 - date1;     // coerced to epoch ms
const days = ms / 86_400_000;  // e.g. 30

Temporal.PlainDate.from("2009-07-15")
  .since("2009-06-15", { largestUnit: "months" });  // P1M

Source: Date.getTime / Temporal — since.

The headline JavaScript date gotcha: a Date is an object, so === and == compare references, not instants. Two Dates built from the same moment are different objects, so a === b is false. Compare the underlying epoch numbers instead — a.getTime() === b.getTime(), or the unary-plus shorthand +a === +b. The relational operators (<, >, <=) do work, because they coerce each side to a number. With Temporal, use .equals() and the static compare().

const a = new Date("2009-06-15T20:45:30.617Z");
const b = new Date("2009-06-15T20:45:30.617Z");
a === b;                 // false — different objects
a.getTime() === b.getTime();  // true
+a === +b;               // true — unary-plus shorthand
a < b;                   // works — operators coerce to number

Source: Date.getTime / Temporal — equals.

A Date can represent ±8,640,000,000,000,000 ms from the epoch — about ±273,790 years, out to the year ±275,760. Past that you get an Invalid Date, which is also what any unparseable input produces (new Date("nope")). An Invalid Date’s getTime() is NaN, so test with Number.isNaN(d.getTime()) — not d === "Invalid Date" or d === null. There is no null-date type; use null/undefined for “no value.”

const d = new Date("nope");
d.getTime();                 // NaN
Number.isNaN(d.getTime());   // true → it's invalid
new Date(8_640_000_000_000_000).toISOString();
// "+275760-09-13T00:00:00.000Z" — the max

Source: MDN — the epoch, timestamps, and Invalid Date.

JavaScript is epoch-native, but in milliseconds: Date.now(), getTime(), and valueOf() all return ms since 1970-01-01 UTC, and new Date(ms) reads one back. The number-one interop bug is mixing this with Unix seconds APIs — multiply Unix seconds by 1000 going in, divide (and floor) going out. There is no year-2038 problem: the epoch is a 64-bit float of milliseconds, not a 32-bit signed integer of seconds. Temporal reads epoch values with fromEpochMilliseconds / fromEpochNanoseconds.

Date.now();                       // 1245098730617 — MILLISECONDS
new Date(unixSeconds * 1000);      // seconds → Date (don't forget × 1000)
Math.floor(Date.now() / 1000);    // Date → Unix seconds
Temporal.Instant.fromEpochMilliseconds(1245098730617);

Source: Date.getTime / Temporal.Instant.fromEpochMilliseconds.

Use performance.now(), never Date.now(). The wall clock is not monotonic — an NTP sync or a manual clock change can move it backward mid-measurement, giving a negative or wildly wrong elapsed time. performance.now() is backed by a monotonic clock and is sub-millisecond, though browsers intentionally clamp and jitter its resolution (a Spectre mitigation), so it’s for measuring durations, not for a high-precision wall clock. Date resolution is whole milliseconds.

const t0 = performance.now();
doWork();
const elapsedMs = performance.now() - t0;  // monotonic, sub-ms
// Never: Date.now() - start  (wall clock can jump)

Rule: Date / Temporal answer “what time is it?”; performance.now() answers “how long did that take?”

Source: MDN — performance.now().

Three design choices account for most JavaScript date bugs. Mutability: setMonth, setDate, setHours, … mutate the Date in place and return a timestamp number, not a new Date — so a value you passed to a function can be changed under you, and chaining doesn’t work as it looks. 0-indexed months: months run 0–11 (January is 0) while day-of-month runs 1–31 — the “why is my month off by one” bug. Reference equality: two Dates are never === (see comparison). Temporal is immutable, so none of these can happen.

const d = new Date(2009, 5, 15);  // month 5 = JUNE, not May
const ret = d.setMonth(0);       // mutates d AND returns a number (ms)
// ret is 1230966000000, NOT a Date; d itself is now January

Defensive habits: copy before mutating (new Date(d)), always +1 when reading/writing a human month, and never compare with ===. Or skip all of it and use Temporal.

Source: Date.setMonth / getMonth (0–11).

JSON.stringify calls Date.prototype.toJSON, which emits the ISO 8601 UTC string (the toISOString() shape). JSON.parse does not reverse this — it has no idea a string was a date, so you get a string back and must revive it with a reviver function (see the JSON section). structuredClone (and the structured-clone algorithm used by postMessage / IndexedDB) does preserve a real Date. Temporal values serialize through toString()/toJSON() as RFC 9557 extended ISO strings and read back with the matching .from().

JSON.stringify({ at: d });      // {"at":"2009-06-15T20:45:30.617Z"}
typeof JSON.parse('{"at":"...Z"}').at;  // "string" — NOT revived
structuredClone(d) instanceof Date;    // true — preserved

Source: Date.toJSON / structuredClone.

The everyday one-liners. Note the <input type="date"> recipe assembles the string from the local getters — using toISOString().slice(0, 10) would emit the UTC date and can be a day off.

// Start of day (local, immutable copy):
const sod = new Date(d); sod.setHours(0, 0, 0, 0);

// Add days safely (copy, don't mutate the original):
const plus7 = new Date(d); plus7.setDate(plus7.getDate() + 7);

// YYYY-MM-DD for <input type="date"> — LOCAL, not toISOString():
const p = (n) => String(n).padStart(2, "0");
const ymd = `${d.getFullYear()}-${p(d.getMonth()+1)}-${p(d.getDate())}`;

// Days between (whole days):
const days = Math.round((b - a) / 86_400_000);

// Is weekend / is leap year:
const weekend = [0, 6].includes(d.getDay());  // 0 = Sun, 6 = Sat
const leap = (y) => y % 4 === 0 && (y % 100 !== 0 || y % 400 === 0);

// Next Monday (on or after tomorrow):
const nm = new Date(d);
nm.setDate(nm.getDate() + ((8 - nm.getDay()) % 7 || 7));

Temporal.PlainDate makes the date-only recipes cleaner — .add({days}), .dayOfWeek, .toString() is already YYYY-MM-DD, no time component to strip.

Source: Date.setHours / getDay.

Four libraries are in common use; the choice is a set of tradeoffs, not a ranking.

Luxon — immutable, Intl/IANA-based, from a Moment maintainer. The natural pick when you want a modern, immutable object API with strong time-zone handling. date-fns — a functional, tree-shakeable toolkit of standalone helpers that operate on native Date; TypeScript-first, pay only for the functions you import. Day.js — ~2 KB with a nearly Moment-compatible API; the least-painful migration path off Moment. Moment — the original, now in maintenance mode: its own maintainers recommend against it for new projects (large, mutable, not tree-shakeable). Keep it for legacy code; don’t start new code on it.

// Luxon             date-fns                 Day.js / Moment
DateTime.now()    format(new Date(), "yyyy-MM-dd")   dayjs().format("YYYY-MM-DD")

Going forward, Temporal reduces the need for a library in many cases — immutable types, zones, and arithmetic are now built in. A library still earns its place for token-string formatting, relative-time strings, or the widest browser reach before Temporal is universal.

Sources: Luxon · date-fns · Day.js · Moment project status.