health.appointment-slots Unreviewed

export function appointmentSlots(sessions: readonly ClinicSession[], slotMinutes: number, breaks: readonly ClinicBreak[], bookings: readonly Booking[]): readonly AppointmentSlot[]

/** One clinic session on one day; it cannot cross midnight. */
export interface ClinicSession {
  readonly date: string;
  /** HH:MM, 24-hour */
  readonly start: string;
  /** HH:MM, after start */
  readonly end: string;
}

/** A break inside sessions, such as lunch; slots restart after it. */
export interface ClinicBreak {
  /** null for a break on every session day */
  readonly date: string | null;
  /** HH:MM */
  readonly start: string;
  /** HH:MM, after start */
  readonly end: string;
}

/** An existing appointment. */
export interface Booking {
  readonly date: string;
  /** HH:MM */
  readonly start: string;
  /** HH:MM, after start */
  readonly end: string;
}

/** One bookable slot. */
export interface AppointmentSlot {
  readonly date: string;
  /** HH:MM */
  readonly start: string;
  /** HH:MM */
  readonly end: string;
}

import { appointmentSlots } from "#fune/health.appointment-slots@^1";

import { minutesBetween } from "./time_minutes_between.ts";  ← from time.minutes-between ^1.0.0 · built alongside by fune
import { type AppointmentSlot, type Booking, type ClinicBreak, type ClinicSession } from "./health_appointment_slots_types.ts";

/** A break without a date still needs a real date for the time check. */
const ANY_DATE = "2000-01-01";

interface Interval {
  date: string;
  start: number;
  end: number;
}

/** Minute of the day, 0 to 1439; throws on a malformed date or time. */
function minuteOfDay(date: string, time: string): number {
  return minutesBetween(date, "00:00", date, time);
}

function interval(kind: string, date: string | null, start: string, end: string): Interval {
  const on = date === null ? ANY_DATE : date;
  const from = minuteOfDay(on, start);
  const to = minuteOfDay(on, end);
  if (to <= from) {
    throw new RangeError(`${kind} on ${date === null ? "every day" : date} must end after it starts (${start} to ${end})`);
  }
  return { date: on, start: from, end: to };
}

function clock(minute: number): string {
  const hours = Math.floor(minute / 60);
  const minutes = minute % 60;
  return `${String(hours).padStart(2, "0")}:${String(minutes).padStart(2, "0")}`;
}

/**
 * Free appointment slots. Breaks split a session into segments and the slot
 * grid restarts at the start of each segment, so a 12:30-13:30 lunch gives
 * slots from 13:30 rather than from wherever the morning grid would have
 * landed. Bookings only take slots away: they never move the grid, because
 * they are booked into slots. Intervals are half-open, so a booking ending at
 * 09:15 does not touch the 09:15 slot.
 */
export function appointmentSlots(
  sessions: readonly ClinicSession[],
  slotMinutes: number,
  breaks: readonly ClinicBreak[],
  bookings: readonly Booking[],
): readonly AppointmentSlot[] {
  if (!Number.isInteger(slotMinutes) || slotMinutes < 1 || slotMinutes > 480) {
    throw new RangeError(`slotMinutes must be a whole number from 1 to 480, received ${slotMinutes}`);
  }
  const clinic = sessions.map((s) => interval("session", s.date, s.start, s.end));
  const closed = breaks.map((b) => ({ always: b.date === null, ...interval("break", b.date, b.start, b.end) }));
  const booked = bookings.map((b) => interval("booking", b.date, b.start, b.end));

  clinic.sort((a, b) => (a.date < b.date ? -1 : a.date > b.date ? 1 : a.start - b.start));
  for (let i = 1; i < clinic.length; i++) {
    if (clinic[i].date === clinic[i - 1].date && clinic[i].start < clinic[i - 1].end) {
      throw new RangeError(`sessions overlap on ${clinic[i].date}`);
    }
  }

  const slots: AppointmentSlot[] = [];
  for (const session of clinic) {
    const pauses = closed
      .filter((b) => b.always || b.date === session.date)
      .sort((a, b) => a.start - b.start || a.end - b.end);
    const segments: [number, number][] = [];
    let cursor = session.start;
    for (const pause of pauses) {
      if (pause.end <= cursor || pause.start >= session.end) continue;
      if (pause.start > cursor) segments.push([cursor, pause.start]);
      cursor = Math.max(cursor, pause.end);
    }
    if (cursor < session.end) segments.push([cursor, session.end]);

    for (const [from, to] of segments) {
      for (let t = from; t + slotMinutes <= to; t += slotMinutes) {
        const end = t + slotMinutes;
        const taken = booked.some((b) => b.date === session.date && b.start < end && b.end > t);
        if (!taken) slots.push({ date: session.date, start: clock(t), end: clock(end) });
      }
    }
  }
  return slots;
}

Install

fune build

With that line in your source, in a TypeScript project (language typescript in fune.project), fune build resolves it and its 1 dependency, pins them in fune.lock, downloads only the TypeScript package of each, and builds the code above into your project’s .fune/build, one readable file per capability with a header linking back here. Or pin a range in fune.project and build in one step:

fune add health.appointment-slots

The manifest, vectors and README with only the TypeScript implementation. Install it without the registry with fune add ./health.appointment-slots-1.0.1-typescript.fune, or fetch it from a terminal with fune pull health.appointment-slots@1.0.1:typescript.

The whole function, every language, is one file too: health.appointment-slots-1.0.1.fune, 28,395 bytes, sha256 9b81b0c2ed4032adce8b962d58a67032ce0817f7dcf79e05cf4ec899e66e00a1. It installs into a project of any language.

// fune: before health.appointment-slots

// fune: after health.appointment-slots

// fune: replace time.minutes-between in health.appointment-slots

// fune: step health.appointment-slots after <n|label>

More from the author

- **Breaks reshape a session.** A break (lunch, a team meeting) splits the session into free segments. Slots are laid back to back from the start of each segment, so after a 12:30-13:30 lunch the first slot is at 13:30, not wherever the morning's grid would have landed. A break with a null date applies to every session day. A break with a date applies to that day only. - **Leftovers are dropped.** A slot must fit wholly inside its segment. With 20-minute slots, 09:00-12:30 gives ten slots ending at 12:20, and the last 10 minutes are not offered. - **Bookings only take slots away.** A slot that overlaps any booking on the same date is removed, but the grid does not move. Bookings are made into slots, so a 5-minute booking at 09:05 removes the 09:00 slot and leaves 09:20 where it was. A booking across two slots removes both. - **Touching is not overlapping.** Intervals are half-open (start included, end excluded), so a booking ending at 09:15 leaves the 09:15 slot free.

Sessions may be given in any order. The result is sorted by date, then start time.

## Errors

The function refuses, rather than guessing, when:

- a time is not `HH:MM` from 00:00 to 23:59 (`9:00` and `24:00` are refused) - a date is not a real ISO date - a session, break or booking does not end after it starts - two sessions on the same date overlap - `slotMinutes` is not a whole number from 1 to 480

A session cannot cross midnight. Split an overnight clinic into two sessions, one on each date.

## What it does not do

It does not handle clinicians, rooms or appointment types. Call it once per clinician or resource. It does not handle double-booking capacity (more than one patient per slot) or daylight-saving changes. It does not keep slots in the past out of the list, because it never reads the clock: pass only the sessions still to come.

## Before you rely on this

**Not professional advice.** This capability calculates health figures from published rules. It is a software component for developers, not medical advice. Rules change and every rate here has an effective date. Check that the dates cover your case. Verify results against the official sources listed above, and have a clinician review how you use it, before anyone relies on the output. Provided "as is" under its licence, without warranty.

**Not a medical device.** It is not intended to diagnose, treat or support clinical decisions about any individual. Anyone building it into clinical software is responsible for that software's regulatory status, and must validate it under their own clinical governance.

**Unreviewed.** This capability's implementations agree in every language and pass its published test vectors, which were worked out from the official sources cited. But no qualified clinician has yet checked those vectors, or confirmed that the capability covers the cases it claims. Treat it as a draft. Do not use it for real people, money or decisions without your own expert review. Once a qualified reviewer signs off, this notice is replaced with their name, qualification and the date. Each new version needs fresh sign-off.

1.0.1 marks it unreviewed. The code and the tests are unchanged.

Files