What is availability, anyway?

Three different things wearing one word

When someone says a booking page “shows the wrong availability”, they almost always mean one of three unrelated things. Untangling them is most of the work of building a scheduling product, and all of the work of debugging one.

The first is the rule: the hours you have declared bookable. The second is the calendar: the events that block some of those hours. The third is the promise: what you have implicitly told the invitee about how soon they can expect a slot.

A page can be correct on all three and still feel wrong, which is why this is worth being precise about.

The rule is a declaration, not a measurement

A rule is something you write: Monday to Thursday, 10:00 to 16:00, in Lisbon time, twenty-minute slots, on the hour and half hour.

Rules are declarations, so they can be wrong in ways calendars cannot. A rule that opens at 09:00 when you are never at a desk before 09:40 is not a bug in anyone’s software. It is a promise you did not intend to make.

Because rules are declarations, they should be few, named and shared. Three people running the same conversation should point at the same rule, not maintain three copies that agree today.

The calendar is a subtraction

Given a rule, the calendar removes things. Busy blocks, travel, an all-day event that should not have counted, the meeting you accepted twice.

The subtraction is where time zones bite. A rule expressed in local wall-clock time and a calendar expressed in absolute instants have to be reconciled, and the reconciliation has to survive daylight-saving transitions in both directions:

// Windows are wall-clock in the host's zone; busy blocks are absolute
// instants. Convert the window per day so DST shifts are handled once.
export function openSlots(day: CalendarDay, rule: Rule, busy: Interval[]) {
  const window = toInstants(rule.window, day.date, rule.zone);
  const free = (slot: Interval) => !busy.some((b) => overlaps(slot, b));

  return sliceIntoSlots(window, rule.slotMinutes).filter(free);
}

Two rules of thumb keep this honest. Store instants, never local strings. And convert once, at the boundary, rather than sprinkling conversions through the call stack — every extra conversion is a chance to lose an hour twice a year.

The promise is the part nobody writes down

The third meaning is the one that causes complaints. If your first free slot is eleven days out, your page is technically correct and practically useless. The invitee reads it as “this person does not want to talk to me”.

Good pages make the promise explicit: the earliest slot, the typical wait, and whether a shorter conversation is available sooner. It is better to say “next week” clearly than to show a calendar that quietly implies “never”.

Where the confusion shows up

Most support conversations about availability resolve to one of four sentences. The rule is wider than the person’s real day. A calendar is not connected, so nothing is being subtracted. The zone on the rule is not the zone the person lives in. Or the page is fine and the wait is simply long.

None of those are the same problem, and only one of them is fixed by looking at the calendar.

A practical definition

So: availability is a named rule, expressed in a stated zone, minus the busy blocks of the calendars you have connected, presented alongside an honest statement of how soon a real conversation can happen.

Anything less than all four parts, and you have a grid of clickable rectangles rather than a booking page.