Iurii Schedules: Booking Slots Across Daylight Saving Time (Luxon)

A salon’s working hours are a wall-clock fact: open nine, close eight. A booking is an instant: this client, this specialist, this exact moment. Most of the time, converting between the two needs no thought. At daylight saving transitions, that conversion can have a gap or more than one answer. A wall-clock time that never happened can silently turn into a real instant – the same one as the slot an hour later. A working block’s own start or end time can be the one that doesn’t exist that day. And the day itself can be 23 or 25 hours long instead of 24.

This is the boundary KRI, the booking SaaS I designed and built for beauty businesses, has to get right on every date, in whichever IANA time zone the salon owner picked at sign-up. The examples below use Luxon 3.7.2, the version KRI runs. Its default gap handling needs an explicit check, and reviewing its autumn behaviour exposed a separate assumption in KRI that a pinned version does not make safe.

Instants in the Database, Wall Clocks in the Schedule

KRI stores two different kinds of time, and mixing them up is the entire source of the problem. A booking – its start and its end – is a UTC instant, a use case for TIMESTAMPTZ rather than a timezone-free TIMESTAMP: a moment that means the same thing regardless of who reads it. A specialist’s working hours are the opposite on purpose: "09:00"–"20:00", a wall-clock string with no offset attached, because that’s what actually stays true across a daylight saving change. A salon that opens at nine keeps opening at nine in March and in October; what changes is which UTC instant ‘nine’ happens to be that day.

This article covers one path: slot generation and the client’s online booking page. Everywhere that path turns a specialist’s stored "09:00" into a bookable UTC instant for a specific date, or turns a client-submitted instant back into the local date it falls on, it goes through one server-side conversion module. So do that path’s day windows and date-by-date scans. The chokepoint is deliberate: daylight saving time is cheap to get right once and expensive to get right N times. The salon owner’s own dashboard has a separate manual-booking path with its own client-side conversion; it’s outside the scope of this article.

Why isValid Doesn’t Catch a Skipped Hour

This is the case the chokepoint exists for. Take Europe/Warsaw on 29 March 2026, the day clocks spring forward from 02:00 to 03:00. The wall-clock times 02:00–02:59 don’t happen that day, yet asking Luxon to build a DateTime for "02:30" in that zone doesn’t fail:

02:30 and the real 03:30 land on the exact same instant. In Luxon 3.7.2, DateTime.fromFormat (and fromObject behaves the same way) returns a valid DateTime for a wall-clock time inside a spring-forward gap: it silently shifts the time forward past the gap and reports the result as valid, so isValid can’t detect it. Ask for the same "02:30" in Europe/Helsinki, which is one hour ahead and has its own gap starting at 03:00 that day, and 02:30 exists where you’d expect, no shift. The failure depends on the zone whose gap you land in, not on the time 02:30 itself, and isValid gives no signal either way: it’s true in both zones, for different reasons.

So a naive ‘generate a slot for every 10 minutes between opening and closing, check isValid’ loop hands out a slot for the hour that never happened, silently pointing at the same instant as the slot an hour later.

Catching It: Convert, Then Convert Back

The fix needs no application-maintained table of transitions; Luxon uses the runtime’s time zone data. Convert the requested wall clock to an instant, then format that instant back into a wall clock in the same zone and compare the two strings:

function localToUtc(date: string, time: string, zone: string): Date | null {
  const dt = DateTime.fromFormat(`${date} ${time}`, "yyyy-MM-dd HH:mm", { zone });
  if (!dt.isValid) return null;
 
  // Luxon shifts a non-existent wall clock forward instead of reporting it
  // invalid. Compare the result with the requested local date and time.
  if (dt.toFormat("yyyy-MM-dd HH:mm") !== `${date} ${time}`) return null;
 
  return dt.toJSDate();
}

Detection comes down to formatting the result back in the same zone and comparing. If the wall clock you get back differs from the one you asked for, the time you asked for never existed – you’re looking at the silent forward shift, not a coincidence. That’s the whole detection, with no table of DST transition dates.

This doesn’t produce a working slot where there wasn’t one; there still isn’t one. What it changes is the failure: an explicit null the caller has to handle instead of a slot quietly pointing at the wrong instant that nothing downstream would flag. That matters most where a naive loop is least likely to notice: at the edges of a working block, when a specialist’s stored start or end time falls inside the gap.

What a Gap Does to a Slot List

KRI’s slot generator walks each working block in fixed 10-minute wall-clock steps and converts every step through the function above. Two different things can go wrong with a block on a given date, and they’re handled differently:

• A single step inside an otherwise normal block lands in the gap. That one candidate slot is skipped; the rest of the block still offers its normal slots.
• The block’s start or end time itself is the one that doesn’t exist that day – a specialist scheduled to start at 02:00 on a morning where 02:00 never happens. The entire block for that date is dropped, not clipped to whatever fragment might remain. Once a non-existent boundary is shifted, the generator has no principled way to guess what it was supposed to mean, so it refuses the whole block rather than invent a partial one.

A service’s duration is added to a converted slot start in real elapsed milliseconds, not by adding minutes to a wall clock, so a duration that spans a transition is measured correctly even though the wall clock reads a full hour later than a naive add would show. In practice this only matters late at night or in the small hours. In the European zones above, the spring gap sits between 02:00 and 04:00 local time (02:00–02:59 in Warsaw, 03:00–03:59 in Helsinki), well outside a salon open 09:00–20:00. Some zones shift at midnight instead – a different case, covered below. For a salon open only during the day, those particular slot-level cases will not occur.

The Repeated Hour: Pinning the Version Is Not a Policy

On 25 October 2026, Europe/Warsaw’s clocks fall back from 03:00 to 02:00. The local time 02:30 occurs twice: at 00:30Z with offset +02:00, and at 01:30Z with offset +01:00. Both pass the round-trip check because both are real occurrences of the requested wall clock.

KRI’s conversion code assumed Luxon 3.7.2 would choose the earlier occurrence. Reviewing that assumption produced this result, with the same library version and input:

This is reproducible by changing only Settings.now in a test:

import { DateTime, Settings } from "luxon";
 
const originalNow = Settings.now;
try {
  for (const now of ["2026-01-15T12:00:00Z", "2026-07-15T12:00:00Z"]) {
    Settings.now = () => Date.parse(now);
    Settings.resetCaches();
    const dt = DateTime.fromFormat("2026-10-25 02:30", "yyyy-MM-dd HH:mm", {
      zone: "Europe/Warsaw",
    });
    console.log(now, dt.toISO(), dt.toUTC().toISO());
  }
} finally {
  Settings.now = originalNow;
  Settings.resetCaches();
}

Run this in isolation: Settings.now is global test state. The 3.7.2 implementation uses the zone’s offset at the current time as an initial guess when constructing this value. Luxon’s documentation makes no promise about which ambiguous occurrence a plain lookup chooses. The dependency is therefore broader than a library upgrade: the result can change while the version stays fixed.

If the product’s policy is to offer the earlier occurrence only, select it explicitly after the validity and round-trip checks:

const candidates = dt.getPossibleOffsets();
const earlier = candidates.reduce((a, b) => (a.toMillis() <= b.toMillis() ? a : b));
return earlier.toJSDate();

This is the proposed correction to KRI’s assumption, not a claim that its current conversion module already contains this selection. A product that offers both occurrences needs a different interface: two distinct instants with enough offset or time-zone information for the client to tell them apart. Either policy can be deliberate; leaving it to a default constructor cannot guarantee either one.

A Day Isn’t Always 24 Hours

Date math has the same trap wall-clock math does. Advance a UTC instant by a fixed 24 hours across the Warsaw autumn transition and the local calendar date it lands on doesn’t advance cleanly – two consecutive 24-hour hops can land on the same local date, because one of those days was 25 real hours long. That’s why KRI’s own day-by-day iteration (walking a booking window date by date) advances a "YYYY-MM-DD" string by calendar arithmetic, never by adding a fixed duration to an instant. In a DST-observing zone, ‘add a day’ and ‘the next calendar day’ don’t always mean the same thing.

The same reasoning extends to where a day starts. A window for a given date is built from startOf('day') in the salon’s zone rather than assuming "00:00" – because in some zones, on some dates, midnight itself is the wall clock the DST shift removes. Africa/Cairo, America/Havana, America/Santiago, Asia/Beirut, and Atlantic/Azores all skip midnight on at least one date in 2026. A strict conversion asked for "00:00" on one of those dates correctly returns null – there is no such instant – so building the day window from a fixed "00:00" lookup would fail on exactly the dates it needs to work. startOf('day') sidesteps the question and returns the first instant that exists that day, whatever its wall-clock time. Unlike the gap and duration cases above, which only bite at hours outside a typical salon’s working day, this applies to every day window and date-by-date scan behind slot generation and the booking page, in every zone, on every date.

Failing Loudly on a Bad Time Zone

One more failure mode is silent in a way that looks nothing like a bug: an invalid or unset IANA zone. Luxon doesn’t throw when you ask it to convert into a time zone it doesn’t recognise – DateTime.local().setZone("Europe/Wrsaw") (one letter off) comes back with isValid: false and no exception. Feed that into the conversion function above and every wall-clock lookup for that salon returns null, on every date, for every slot. The calendar isn’t broken – it’s just empty. To a client on the salon’s booking page – or the owner checking that same page – ‘no availability’ and ‘the time zone is misconfigured’ look identical.

So the zone itself is checked at the start of every conversion, and a bad one throws rather than falls through:

function assertTimezone(zone: string | null | undefined): string {
  if (!zone || !DateTime.local().setZone(zone).isValid) {
    throw new Error(`Invalid tenant timezone: ${String(zone)}`);
  }
  return zone;
}

The time zone is a business value here, not a formatting detail – it decides which real-world instant a booking lands on – so an unknown or missing one fails the request instead of quietly defaulting. An unset zone option would fall back to whatever the process’s own local zone happens to be, which is a different kind of wrong: not empty, but confidently pointing at the wrong instants.

What This Doesn’t Cover

Everything above covers slot generation and the client’s online booking page, not every path in the product. The salon owner’s own dashboard has a separate manual-booking flow that converts wall clock to instant with its own code. It isn’t covered here, and this article makes no claim that one module handles every booking-related conversion in the system.

Dropping a working block with an invalid boundary is KRI’s current conservative policy. Autumn ambiguity is different: the earlier-occurrence assumption needs the explicit selection above and regression checks with both winter and summer current dates.

The checks are small, but they answer different questions: does this local time exist, which occurrence do we mean, where does the day begin, and is the configured zone valid? Treating those as separate decisions makes the calendar easier to reason about and test.

Further reading:

• kri.rocks – Booking Website and Online Scheduling SaaS for Beauty Businesses – the project this article’s time zone handling is drawn from
• PostgreSQL Production Checklist: UUIDs, RLS, Indexes, Pooling – the TIMESTAMPTZ convention this article’s storage model relies on
• A Green Test Can Still Miss the Race: Testing Concurrency in PostgreSQL – a different kind of correctness problem in the same booking system
• Luxon – Time Zones and Offsets – the official documentation on invalid and ambiguous local times cited above