Parsing date strings without surprises

Understanding Parsing date strings without surprises

new Date(someString) and Date.parse(someString) run the same operation, and that operation is two parsers stacked. First the engine tries the format the language actually specifies, a subset of ISO 8601: YYYY-MM-DD, optionally followed by THH:mm, THH:mm:ss or THH:mm:ss.sss, optionally followed by Z or an offset like +05:30. If the string does not match, the engine may do whatever it likes, which is why V8 in Chrome and Node reads '05/03/2024' as 3 May while another engine is free to reject it. Portable code relies only on the first parser.

Inside the specified format there is one asymmetry worth memorising: when the string carries no offset, the engine fills one in, and its choice depends on whether a time is present. Date-only strings are treated as UTC; date-time strings are treated as local time. So '2024-03-05' is midnight UTC while '2024-03-05T00:00:00' is midnight wherever the code happens to run, and they are the same instant only in a UTC zone. That is the source of the classic off-by-one-day bug: getDate() on the UTC-midnight value reports 5 in Berlin but 4 in Sao Paulo, because there the instant is still 21:00 on the 4th.

A failed parse does not throw. You get a real Date object whose internal time value is NaN: it prints as 'Invalid Date', it is truthy, and it stays quiet until something forces the number out, at which point toISOString throws a RangeError or a total renders as NaN far from the bad input. So treat every incoming string as a shape to validate: test it with a regex, read the numbers yourself, build a calendar day with Date.UTC(year, month - 1, day) or an instant from an offset-bearing string, and round-trip the result to reject impossible dates like 31/02 that Date.UTC silently rolls forward.

const dateOnly = new Date('2024-03-05');
const localMidnight = new Date('2024-03-05T00:00:00');

// A date-only string is parsed as UTC midnight, in every time zone.
console.log(dateOnly.toISOString());

// With a time but no offset it is local midnight instead, so the two
// instants sit exactly one local offset apart.
const gapMinutes = (localMidnight.getTime() - dateOnly.getTime()) / 60000;
console.log(gapMinutes === localMidnight.getTimezoneOffset());

// Spell the offset out and the instant stops depending on the reader.
console.log(new Date('2024-03-05T00:00:00+05:30').toISOString());

Worked examples

function parseDMY(text) {
  const m = /^(\d{2})\/(\d{2})\/(\d{4})$/.exec(text);
  if (!m) return null;
  const day = Number(m[1]);
  const month = Number(m[2]);
  const year = Number(m[3]);
  const d = new Date(Date.UTC(year, month - 1, day));
  if (d.getUTCMonth() !== month - 1 || d.getUTCDate() !== day) return null;
  return d;
}

console.log(parseDMY('05/03/2024').toISOString());
console.log(parseDMY('31/02/2024'));
console.log(parseDMY('2024-03-05'));

const utc = new Date('2024-03-05T09:30:00Z');
const india = new Date('2024-03-05T15:00:00+05:30');

console.log(utc.getTime() === india.getTime());
console.log(india.toISOString());
console.log(new Date('2024-03-05T09:30:00.250Z').getUTCMilliseconds());
console.log(Date.parse('2024-03-05T09:30Z') === Date.parse('2024-03-05T09:30:00Z'));

const bad = new Date('qwe');

console.log(String(bad));
console.log(Boolean(bad), Number.isNaN(bad.getTime()));

try {
  bad.toISOString();
} catch (err) {
  console.log(err.name);
}

console.log(new Date(null).toISOString());

Important notes

Common mistakes

Try it yourself