Date & Intl

Working with dates and times in JavaScript — the Date object, common pitfalls, and Intl for locale-aware formatting.

What it is, in plain English: Date is JavaScript's built-in object for working with dates and times. It stores a moment as milliseconds since 1 January 1970 UTC (Unix epoch). The Intl API (Internationalisation) provides locale-aware formatting for dates, numbers, currencies, and relative times — so '3 days ago' and '$1,234.56' render correctly for any language and region without writing the logic yourself.

Where this bites you

setMonth(getMonth() + 1) looks like "one month later", but Date doesn't know what to do with 31 February. It quietly rolls the extra days into the next month, so a bill due on 31 January becomes due on 3 March. February is simply skipped. The same thing happens with 31 March plus one month (31 April becomes 1 May), and with setFullYear on 29 February.

function addOneMonth(date) {
  const d = new Date(date);
  d.setMonth(d.getMonth() + 1);
  return d;
}

const due = addOneMonth(new Date(2026, 0, 31));   // 31 January
console.log(due.toDateString());
// Tue Mar 03 2026

Working with dates and formatting them for users

Creating a Date

// The current date and time:
const now = new Date();
console.log(now);   // something like: Fri Jun 27 2026 14:30:00 GMT+0530

// A specific date from an ISO string (recommended format):
const launch = new Date("2026-01-15");
const meeting = new Date("2026-06-27T14:30:00");

// From individual parts (trap: months are 0-indexed!):
const d = new Date(2026, 5, 27);  // June 27, 2026 — month 5, not 6!
// This is one of JS's most famous gotchas. Always use ISO strings when possible.

Months are 0-indexed. January = 0, February = 1, ... December = 11. This trips everyone. If you pass month numbers as arguments, subtract 1. Using ISO string format ("2026-06-27") avoids this entirely.

Getting parts of a date

const d = new Date("2026-06-27T14:30:00");

d.getFullYear()   // 2026
d.getMonth()      // 5  ← June (0-indexed — add 1 to display)
d.getDate()       // 27 (day of month, 1-31)
d.getDay()        // 6  (day of week: 0=Sunday, 6=Saturday)
d.getHours()      // 14
d.getMinutes()    // 30
d.getSeconds()    // 0

// The safe, unambiguous string formats:
d.toISOString()      // "2026-06-27T09:00:00.000Z" — UTC, always use for storage
d.toLocaleDateString() // "6/27/2026" — locale-dependent, only for display
d.toDateString()     // "Sat Jun 27 2026" — human-readable but not locale-aware

Date arithmetic — using timestamps

The safest way to do date arithmetic is with timestamps — milliseconds since the Unix epoch (1 Jan 1970 UTC). Every Date can become a timestamp and back.

// Get timestamp:
const now = Date.now();            // milliseconds since epoch (no object needed)
const ts  = new Date().getTime(); // same thing via a Date object

// Calculate future/past dates:
const ONE_DAY_MS  = 24 * 60 * 60 * 1000;   // 86,400,000
const ONE_WEEK_MS = 7 * ONE_DAY_MS;

const today    = new Date();
const tomorrow = new Date(today.getTime() + ONE_DAY_MS);
const lastWeek = new Date(today.getTime() - ONE_WEEK_MS);

console.log(tomorrow.toDateString());   // tomorrow's date
console.log(lastWeek.toDateString());   // last week

// Difference between two dates:
const start = new Date("2026-01-01");
const end   = new Date("2026-06-27");
const diffMs   = end.getTime() - start.getTime();
const diffDays = Math.floor(diffMs / ONE_DAY_MS);
console.log(`${diffDays} days between them`);  // 177 days

Fixed-length steps, such as days and weeks, work with timestamps as shown above. Months don't have a fixed length, so decide what "one month later" should mean and code it. The usual rule, used by banks and billing systems, is to keep the same day number but clamp it to the last day of the target month. Day 0 of a month gives you the last day of the month before, which is the shortest way to find that limit:

function addOneMonth(date) {
  const d = new Date(date);
  const day = d.getDate();
  d.setDate(1);                        // park on the 1st so the month change can't overflow
  d.setMonth(d.getMonth() + 1);
  const lastDay = new Date(d.getFullYear(), d.getMonth() + 1, 0).getDate();   // day 0 = last day of previous month
  d.setDate(Math.min(day, lastDay));   // clamp: 31 Jan -> 28 Feb
  return d;
}

console.log(addOneMonth(new Date(2026, 0, 31)).toDateString());
console.log(addOneMonth(new Date(2026, 2, 15)).toDateString());
// Sat Feb 28 2026
// Wed Apr 15 2026

Intl — let the browser format dates and numbers

Never write your own date formatter. The Intl API does it correctly for every locale, timezone, and language automatically.

const date = new Date("2026-06-27T14:30:00");

// DateTimeFormat — pick your locale and style:
new Intl.DateTimeFormat("en-US").format(date)   // "6/27/2026"
new Intl.DateTimeFormat("en-GB").format(date)   // "27/06/2026"
new Intl.DateTimeFormat("en-IN").format(date)   // "27/6/2026"
new Intl.DateTimeFormat("de-DE").format(date)   // "27.6.2026"
new Intl.DateTimeFormat("ja-JP").format(date)   // "2026/6/27"

// Control what's shown:
const fmt = new Intl.DateTimeFormat("en-IN", {
  weekday: "long",   // "Saturday"
  year:    "numeric",
  month:   "long",   // "June"
  day:     "numeric",
  hour:    "2-digit",
  minute:  "2-digit",
  timeZoneName: "short"
});
console.log(fmt.format(date));
// "Saturday, 27 June 2026 at 02:30 pm IST" (Node 22; punctuation varies by browser)

// NumberFormat for currency:
const price = 1234.56;
new Intl.NumberFormat("en-IN", { style: "currency", currency: "INR" }).format(price)
// "₹1,234.56"

new Intl.NumberFormat("en-US", { style: "currency", currency: "USD" }).format(price)
// "$1,234.56"

Relative time: "3 days ago"

const rtf = new Intl.RelativeTimeFormat("en", { numeric: "auto" });

rtf.format(-1, "day")    // "yesterday"
rtf.format(-3, "day")    // "3 days ago"
rtf.format(0,  "day")    // "today"
rtf.format(1,  "day")    // "tomorrow"
rtf.format(-2, "week")   // "2 weeks ago"
rtf.format(1,  "month")  // "next month"

// Calculate which unit to use:
function timeAgo(date) {
  const diffMs = date.getTime() - Date.now();
  const diffSec = Math.round(diffMs / 1000);
  const diffMin = Math.round(diffSec / 60);
  const diffHr  = Math.round(diffMin / 60);
  const diffDay = Math.round(diffHr / 24);

  if (Math.abs(diffSec) < 60)  return rtf.format(diffSec, "second");
  if (Math.abs(diffMin) < 60)  return rtf.format(diffMin, "minute");
  if (Math.abs(diffHr)  < 24)  return rtf.format(diffHr,  "hour");
  return rtf.format(diffDay, "day");
}

console.log(timeAgo(new Date(Date.now() - 5 * 60 * 1000)));  // "5 minutes ago"

Try It Yourself

// Creating dates
const now     = new Date();            // current date and time
const specific = new Date("2026-01-15"); // from ISO string
const fromParts = new Date(2026, 0, 15); // year, month (0=Jan), day

console.log(now.toISOString());   // "2026-06-27T..." — always UTC, always safe

// Getting parts
const d = new Date("2026-06-27T10:30:00");
console.log(d.getFullYear());  // 2026
console.log(d.getMonth());     // 5  ← June is 5 (months are 0-indexed!)
console.log(d.getDate());      // 27 (day of month)
console.log(d.getDay());       // 6  (day of week: 0=Sun, 6=Sat)
console.log(d.getHours());     // 10

// Timestamps — milliseconds since epoch
const ts = Date.now();               // most efficient: no Date object needed
console.log(ts);                     // e.g. 1751021400000
const elapsed = Date.now() - ts;
console.log("Elapsed ms:", elapsed); // near-zero

// Date arithmetic
const today    = new Date();
const tomorrow = new Date(today.getTime() + 24 * 60 * 60 * 1000);
const nextWeek = new Date(today.getTime() + 7 * 24 * 60 * 60 * 1000);
console.log("Tomorrow:", tomorrow.toDateString());

// Intl — locale-aware formatting
const date = new Date("2026-06-27T14:30:00");

// Format for India:
const inFmt = new Intl.DateTimeFormat("en-IN", { dateStyle: "full", timeStyle: "short" });
console.log(inFmt.format(date));

// Format as currency:
const price = 1234567.89;
const usdFmt = new Intl.NumberFormat("en-US", { style: "currency", currency: "USD" });
const inrFmt = new Intl.NumberFormat("en-IN", { style: "currency", currency: "INR" });
console.log(usdFmt.format(price));  // "$1,234,567.89"
console.log(inrFmt.format(price));  // "₹12,34,567.89"

// Relative time: "3 days ago"
const rtf = new Intl.RelativeTimeFormat("en", { numeric: "auto" });
console.log(rtf.format(-3, "day"));   // "3 days ago"
console.log(rtf.format(1, "week"));   // "next week"

Timezones, Date comparison, and Temporal (the future)

Timezone pain — and how to avoid it

// Date stores UTC internally — local display depends on the runtime timezone
const d = new Date("2026-06-27T00:00:00");
// In India (UTC+5:30): getHours() returns 0 but UTC hours may differ

// ALWAYS store and transfer dates as ISO strings (UTC):
const stored = d.toISOString();   // "2026-06-26T18:30:00.000Z" — unambiguous

// Display in a specific timezone with Intl:
new Intl.DateTimeFormat("en-IN", {
  timeZone:  "Asia/Kolkata",
  dateStyle: "full",
  timeStyle: "short",
}).format(d);  // always correct for IST regardless of server timezone

// Avoid date-only strings ambiguity:
new Date("2026-06-27")          // parsed as UTC midnight → may show June 26 locally!
new Date("2026-06-27T00:00:00") // parsed as LOCAL midnight — safer for local dates

Comparing dates

const d1 = new Date("2026-01-01");
const d2 = new Date("2026-06-27");

// Compare via timestamps:
d1 < d2              // true — dates coerce to numbers (timestamps) for < >
d1.getTime() < d2.getTime()  // more explicit, same result
d1 === d2            // false — different objects even if same date!
d1.getTime() === d2.getTime()  // true if same moment

// Sort an array of dates:
const dates = [new Date("2026-06-27"), new Date("2026-01-01"), new Date("2026-03-15")];
dates.sort((a, b) => a - b);  // ascending (subtraction returns millisecond diff)

Performance: Date.now() vs new Date()

// For timestamps only, Date.now() is faster — no object creation:
console.time("loop");
for (let i = 0; i < 1_000_000; i++) {
  const t = Date.now();  // fast
}
console.timeEnd("loop");

// performance.now() for high-resolution timing (browser/Node):
const start = performance.now();
// ... some operation ...
const duration = performance.now() - start;
console.log(`Operation took ${duration.toFixed(3)}ms`);

Intl.ListFormat and Intl.PluralRules

// Format a list of items correctly for a locale:
const lf = new Intl.ListFormat("en", { style: "long", type: "conjunction" });
lf.format(["Alice", "Bob", "Charlie"]);  // "Alice, Bob, and Charlie"
lf.format(["Alice", "Bob"]);             // "Alice and Bob"
lf.format(["Alice"]);                    // "Alice"

// Pluralisation rules vary by language:
const pr = new Intl.PluralRules("en");
pr.select(0)  // "other" → "0 items"
pr.select(1)  // "one"   → "1 item"
pr.select(2)  // "other" → "2 items"

// Use it:
function items(n) {
  return `${n} ${pr.select(n) === "one" ? "item" : "items"}`;
}
console.log(items(1));   // "1 item"
console.log(items(5));   // "5 items"

Temporal API, epoch internals, and the Intl spec

The Temporal API (TC39 Stage 3)

The Temporal proposal (TC39 Stage 3 as of 2024, shipping in some browsers) replaces Date with a comprehensive, timezone-correct date/time library. Key types:

// Temporal.Now — current moments
Temporal.Now.instant()          // nanosecond-precision UTC instant
Temporal.Now.zonedDateTimeISO() // current local date+time+tz as one object
Temporal.Now.plainDateISO()     // current date only, no time

// Temporal.PlainDate — date without time or timezone
const d = Temporal.PlainDate.from("2026-06-27");
d.year   // 2026
d.month  // 6 (1-indexed! unlike Date)
d.day    // 27

// Arithmetic — clean API:
d.add({ months: 3 })         // 2026-09-27
d.subtract({ days: 100 })    // 2026-03-18
d.until(Temporal.PlainDate.from("2027-01-01")).days  // days until

// ZonedDateTime — timezone-aware
const meeting = Temporal.ZonedDateTime.from("2026-06-27T14:30[Asia/Kolkata]");
meeting.withTimeZone("America/New_York").toString()  // converts correctly

Date internals — the UTC time value

A Date stores a single time value: a 64-bit float representing milliseconds since 1 January 1970 00:00:00 UTC (the Unix epoch), valid from -100,000,000 to +100,000,000 days from epoch (~±273,972 years). NaN time value → Invalid Date. getTime() returns the raw time value. Local methods (getHours, getDate) apply the host timezone offset; UTC methods (getUTCHours) return the UTC value directly.

The Intl spec — ECMA-402

The Intl object is specified by ECMA-402 (ECMAScript Internationalisation API Specification), separate from ECMA-262. It builds on the Unicode CLDR (Common Locale Data Repository) for locale data. Implementations are permitted to use any conforming locale data source; browsers typically bundle CLDR. The spec defines: locale negotiation (BestFitMatcher / LookupMatcher), calendar systems (gregory, buddhist, hebrew, islamic, persian, etc.), numbering systems (latn, arab, deva, etc.), and collation rules.

Official Sources

The Codex links only to official documentation and the ECMAScript specification. No third-party tutorials.