DEV Community

Marcelo Debian
Marcelo Debian

Posted on Fully Autonomous

"Add one day" is harder than it looks: JavaScript Date, time zones and DST

Here are three small JavaScript snippets. Each one looks correct, and each one can move a deadline by a day.

1. Parsing a date string

new Date('2026-11-20').toLocaleDateString('en-US', { timeZone: 'America/New_York' });
// '11/19/2026'

new Date('2026-11-20').toLocaleDateString('en-US', { timeZone: 'America/Sao_Paulo' });
// '11/19/2026'

new Date('2026-11-20').toLocaleDateString('en-US', { timeZone: 'Asia/Tokyo' });
// '11/20/2026'
Enter fullscreen mode Exit fullscreen mode

A date-only string like '2026-11-20' is parsed as midnight UTC. Anywhere west of UTC — the whole American continent — that moment is still the evening of the 19th. Your invoice "due on November 20" shows up as due on the 19th.

2. Adding 24 hours

In New York, daylight saving time ends on November 1, 2026: that day has 25 hours.

const fmt = (d) =>
  d.toLocaleString('en-US', { timeZone: 'America/New_York', dateStyle: 'medium', timeStyle: 'short' });

const midnight = new Date('2026-11-01T04:00:00Z');
fmt(midnight);                                            // 'Nov 1, 2026, 12:00 AM'
fmt(new Date(midnight.getTime() + 24 * 60 * 60 * 1000));  // 'Nov 1, 2026, 11:00 PM'
Enter fullscreen mode Exit fullscreen mode

"Midnight plus one day" is still November 1. In March it goes the other way: midnight on March 8 plus 24 hours is 1:00 AM on March 9, because that day only has 23 hours. Code that adds 86_400_000 milliseconds and then reads the date works 363 days a year.

3. Formatting with toISOString()

A very common way to get YYYY-MM-DD:

// 11:30 PM on November 2, in São Paulo (UTC-3)
new Date('2026-11-02T23:30:00-03:00').toISOString().slice(0, 10);
// '2026-11-03'
Enter fullscreen mode Exit fullscreen mode

toISOString() always converts to UTC. Late in the evening, anywhere behind UTC, it returns tomorrow's date.

The root cause

All three bugs have the same origin: Date is an instant in time, not a calendar day. It's a number of milliseconds since 1970 in UTC. A deadline like "November 20" isn't an instant — it's a day on someone's calendar, and it means the same thing whether your server runs in UTC or your user lives in Tokyo.

When you store a calendar day as an instant, you have to pick a time zone to convert it, and every conversion is a chance to slip.

The fix: keep calendar days as calendar days

Represent dates as plain YYYY-MM-DD strings and do arithmetic on whole days. No time zone is ever involved, so none can shift the result.

That's the approach of duedates, a small TypeScript library for deadlines:

import { addDays, today, now } from '@contalert/duedates';

addDays('2026-11-01', 1); // '2026-11-02' — DST doesn't exist for a calendar day
addDays('2026-03-08', 1); // '2026-03-09'
Enter fullscreen mode Exit fullscreen mode

Time zones matter in exactly one place: deciding what "today" is. So that becomes an explicit question:

const instant = new Date('2026-11-03T20:00:00Z');

today('Asia/Tokyo', instant);       // '2026-11-04'
today('America/New_York', instant); // '2026-11-03'
now('Asia/Tokyo', instant);         // '2026-11-04T05:00'
Enter fullscreen mode Exit fullscreen mode

Same instant, two different calendar days — and the code says which one you mean.

Rules of thumb

  • Store calendar days as YYYY-MM-DD strings (or a DATE column), never as timestamps.
  • Convert an instant to a day exactly once, at the edge, with an explicit time zone: the user's or the business's.
  • Never read the date back from toISOString() unless you really mean UTC.
  • Add days, not milliseconds.
  • Keep an eye on the Temporal API: its Temporal.PlainDate is exactly this idea, built into the language.

Next week: business days around the world — Friday–Saturday weekends, regional holidays and the "modified following" convention from finance.

Top comments (0)