Formatting dates for display and storage

Understanding Formatting dates for display and storage

A Date holds one number: milliseconds since the epoch. Everything you can print from it is a projection of that number through a time zone and a set of locale conventions, and two projections of the same instant disagree, sometimes about the hour and sometimes about the calendar day. Storage and display want opposite things from that projection: storage wants one canonical, reversible form that every machine reads identically, while display wants whatever the person in front of the screen expects. The two jobs therefore need separate code paths and separate formats.

For an instant, meaning the moment something happened, the storage form is toISOString(): a fixed-width UTC string such as 2024-01-18T02:30:05.250Z that sorts lexicographically in chronological order, keeps milliseconds, and parses back to the exact same timestamp in every engine. JSON.stringify already produces it, because Date.prototype.toJSON delegates to toISOString, so a Date inside a payload becomes UTC whether you asked for that or not. The strings from toString, toDateString and toLocaleString are display output: they depend on the host time zone, on the host's locale data, and in toString's case on an implementation-defined format, so none of them belongs in a file, a URL, or a database column.

For a calendar date, such as a birthday, an invoice day or a hotel check-in, the storage form is YYYY-MM-DD with no time and no zone, because the value has no instant attached and inventing midnight plus a zone is exactly what makes such dates drift. The classic bug is toISOString().slice(0, 10), which projects through UTC first: a Date built from local components in a zone with a positive offset is still the previous day in UTC, so the stored date is one day early. Take the year, month and day in a zone you name, assemble the string yourself, and go the other way only at render time, formatting the stored canonical value for the current reader.

const instant = new Date(Date.UTC(2024, 0, 18, 2, 30, 5, 250));

// Storage: one canonical UTC string, milliseconds included.
console.log(instant.toISOString());
console.log(JSON.stringify({ createdAt: instant }));

// Display: convert to the viewer's wall clock, then assemble.
const parts = Object.fromEntries(
  new Intl.DateTimeFormat('en-US', {
    timeZone: 'America/New_York',
    year: 'numeric',
    month: '2-digit',
    day: '2-digit',
    hour: 'numeric',
    minute: '2-digit',
    hourCycle: 'h23'
  })
    .formatToParts(instant)
    .map((p) => [p.type, p.value])
);
console.log(`${parts.day}/${parts.month}/${parts.year} ${parts.hour}:${parts.minute}`);

// The shortcut disagrees: it reports the UTC calendar day, not the viewer's.
console.log(instant.toISOString().slice(0, 10));

Worked examples

function isoDateIn(instant, timeZone) {
  const parts = new Intl.DateTimeFormat('en-US', {
    timeZone,
    year: 'numeric',
    month: '2-digit',
    day: '2-digit'
  }).formatToParts(instant);
  const get = (type) => parts.find((p) => p.type === type).value;
  return `${get('year')}-${get('month')}-${get('day')}`;
}

const instant = new Date('2024-11-03T02:30:00Z');
console.log(isoDateIn(instant, 'UTC'));
console.log(isoDateIn(instant, 'America/New_York'));
console.log(isoDateIn(instant, 'Asia/Tokyo'));

const d = new Date(Date.UTC(2024, 10, 3, 2, 30, 5, 250));
const stored = d.toISOString();
console.log(stored);
console.log(new Date(stored).getTime() === d.getTime());

const trimmed = stored.replace(/\.\d{3}Z$/, 'Z');
console.log(trimmed);
console.log(new Date(trimmed).getTime() - d.getTime());

function datetimeLocalValue(instant, timeZone) {
  const v = Object.fromEntries(
    new Intl.DateTimeFormat('en-US', {
      timeZone,
      year: 'numeric',
      month: '2-digit',
      day: '2-digit',
      hour: 'numeric',
      minute: 'numeric',
      hourCycle: 'h23'
    })
      .formatToParts(instant)
      .map((p) => [p.type, p.value])
  );
  const pad = (s) => s.padStart(2, '0');
  return `${v.year}-${v.month}-${v.day}T${pad(v.hour)}:${pad(v.minute)}`;
}

const meeting = new Date('2024-11-03T02:30:00Z');
console.log(datetimeLocalValue(meeting, 'America/New_York'));
console.log(datetimeLocalValue(meeting, 'Europe/Berlin'));

Important notes

Common mistakes

Try it yourself