Date-only values & daylight saving time

Some values are instants: an order was placed, a message was sent. Others are calendar dates: a birthday, a due date, a public holiday, a hotel check-in day. A birthday on July 4 is July 4 in Tokyo and in New York. It has no time and no zone.

Turn a calendar date into an instant and it starts moving:

const birthday = new Date("1990-07-04"); // an instant: midnight UTC
birthday.toLocaleDateString("en-US");    // in New York: "7/3/1990"

Midnight UTC is the evening of July 3 anywhere west of UTC, so half the world sees the wrong birthday. Nothing in that code looks wrong, which is why this bug ships.

The fix is to keep calendar dates as date-only values, the string "YYYY-MM-DD", end to end:

• in JSON: { "birthday": "1990-07-04" }, not "1990-07-04T00:00:00.000Z";
• in the database: a date type without a time;
• in code: as the string, or as UTC midnight used only with UTC methods (next example).

To display one, either print the parts yourself, or format UTC midnight in UTC, so no zone can shift it:

new Date("1990-07-04").toLocaleDateString("en-US", { timeZone: "UTC", dateStyle: "long" });
// "July 4, 1990" on every machine

There is exactly one place where a calendar date needs a zone: "what is today?" Today is March 10 in New York while it's already March 11 in Tokyo. So "is this task overdue?" compares the due date with today in the user's zone, never with the server's clock.

A small set of helpers that treat "YYYY-MM-DD" as UTC midnight of that day. Every function takes and returns date-only strings, so callers never hold a Date they could read with a local getter.

const DAY_MS = 86_400_000;

/** "2026-03-10" → epoch ms of 2026-03-10T00:00:00Z. */
function toUtcMidnight(day: string): number {
  const [year, month, dayOfMonth] = day.split("-").map(Number);
  return Date.UTC(year, month - 1, dayOfMonth); // month is 0-indexed here too
}

/** epoch ms of a UTC midnight → "YYYY-MM-DD". toISOString is always UTC. */
const fromUtcMidnight = (ms: number): string => new Date(ms).toISOString().slice(0, 10);

export const addDays = (day: string, days: number): string =>
  fromUtcMidnight(toUtcMidnight(day) + days * DAY_MS);

export const daysBetween = (from: string, to: string): number =>
  (toUtcMidnight(to) - toUtcMidnight(from)) / DAY_MS;

/** 0 = Sunday … 6 = Saturday, the same on every machine. */
export const weekday = (day: string): number => new Date(toUtcMidnight(day)).getUTCDay();

Why each piece is the way it is:

• Date.UTC, not new Date(y, m, d). The constructor builds local midnight; Date.UTC builds UTC midnight and returns a number.
• days * DAY_MS is safe here, and only here. It's wrong for local times because a local day can be 23 or 25 hours. In UTC it's always 24.
• daysBetween needs no rounding. Both values are UTC midnights, so the difference is an exact multiple of DAY_MS. With New York local midnights, March 7 to March 9 spans the 23-hour March 8: 47 hours, and Math.floor(47 / 24) is 1.
• toISOString().slice(0, 10) to read back. getDate() and getMonth() would read the machine's zone and could hand back the previous day.
• getUTCDay() for the weekday. Same reason as getUTCDate().

Overflow still works for you: Date.UTC(2026, 11, 32) is January 1, 2027, so month and year ends need no special cases.

What these helpers don't do yet: reject "2026-02-30" (Date.UTC rolls it into March), or answer "is it overdue?", which needs today's date in the user's zone. Both are in the next example.

A date-only string compared with an ISO instant

Strings compare character by character, and a string that is a prefix of another sorts first:

"2026-03-10" < "2026-03-10T00:00:00.000Z";  // true
"2026-03-10" >= "2026-03-10T05:00:00.000Z"; // false: ">=" drops its own day

So tasks.filter((t) => t.due >= new Date().toISOString()), meant as "due today or later", silently drops everything due today, and due < now.toISOString() marks every task overdue on its own due date. The same bug happens in a database query that compares a text date column with an ISO timestamp. Compare like with like: two date-only strings (which do sort chronologically), or two instants. For "overdue", that means today's date in the user's zone:

const overdue = dateInZone(new Date(), user.timeZone) > task.due; // both "YYYY-MM-DD"

dateInZone is the formatToParts helper from the parsing unit. Slicing toISOString() instead gives today in UTC, which for a user in Los Angeles is already tomorrow from 5 p.m. (4 p.m. in winter).

A regex isn't a calendar

/^\d{4}-\d{2}-\d{2}$/ checks the shape. It accepts "2026-02-30", and so does every step after it: Date.UTC(2026, 1, 30) rolls over to March 2, and V8's new Date("2026-02-30") does the same. Build the date, then check that what you asked for is what you got:

const [y, m, d] = value.split("-").map(Number);
const date = new Date(Date.UTC(y, m - 1, d));
const real =
  date.getUTCFullYear() === y && date.getUTCMonth() === m - 1 && date.getUTCDate() === d;

Reject at the boundary with a RangeError, so "2026-02-30" can't become a due date of March 2 that nobody entered.

Local times that never happen, or happen twice

On a spring-forward day, local times in the gap don't exist; on a fall-back day, an hour happens twice. Date doesn't fail on either. The spec reads a skipped time with the offset from before the change, and picks the earlier of two repeated times:

// machine in America/New_York
new Date(2026, 2, 8, 2, 30);  // 03:30 EDT: 2:30 a.m. didn't happen on March 8
new Date(2026, 10, 1, 1, 30); // 01:30 EDT, the first of the two 1:30s (05:30 UTC)

A reminder scheduled for "2:30 a.m. local" quietly fires at 3:30 once a year. Store the wall time and zone, and decide explicitly what a skipped or repeated time should mean.