Files
HealthLog/src/lib/medications/scheduling/recurrence.ts
T
Marc-André Bombeck 6526780f3b feat(medications): build the on-time band from the persisted dose window
Thread the persisted `doseWindows` through the shared band minter so the
on-time band for a dose time uses its explicit `[start, end]` range
(minted DST-correctly on the slot's local day) instead of the symmetric
±1h default; the late tail stays cadence-derived. A `normaliseDoseWindows`
helper coerces the stored JSON into a clean entry list, dropping anything
malformed so the read/write paths never defend against an arbitrary shape.

Every band consumer reads the same field: the dose-history endpoint, the
compliance %, the cadence timeline (card last/next dose), and the
write/edit slot attribution all resolve through one minter, so the
history view and the rate can never disagree. The write/edit and
health-score schedule selects now pull the column.
2026-06-08 18:29:17 +02:00

866 lines
35 KiB
TypeScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
/**
* v1.5.0 — canonical recurrence engine for medication scheduling.
*
* Single source of truth for "what dose slots does this schedule emit
* between A and B?" The canonical engine is introduced in this release;
* the v1.5.0 cut wires only the reminder worker (via
* `worker-helpers.ts`) through it. The today-projector
* (`expandTodayIntakes`), the cadence chart (`expandScheduleSlots`),
* and the form-level helpers continue on the legacy walker through
* v1.5.x and migrate per the read-flip plan. The medication card's
* "next intake" line reads the server-computed `nextDueAt` (this engine
* via `computeNextDueAt`) directly as of v1.8.4.
*
* Dispatch tiers (first matching tier wins):
*
* 1. **One-shot** (`medication.oneShot === true`) — single slot at
* the anchor date, one per `timesOfDay` entry.
* 2. **Rolling** (`schedule.rollingIntervalDays !== null`) — next
* slot is `lastIntakeAt + N days`. With no intake yet the FIRST
* dose is due AT `startsOn ?? createdAt` (not `+ N`); the `+ N`
* cadence only begins once the first intake is logged. Only the
* immediately next slot is emitted; further slots depend on the
* user actually logging the intake.
* 3. **RRULE** (`schedule.rrule !== null`) — RFC 5545 expansion
* via the `rrule` npm lib. Day-anchored dates are returned in
* UTC by the library; each `timesOfDay` entry is then applied
* to that day in the user's IANA timezone (DST-aware via
* `wallClockInTz`).
* 4. **Legacy fallback** — both `rrule` and `rollingIntervalDays`
* are NULL and `oneShot` is false. Decodes the legacy
* `daysOfWeek` string via `parseScheduleRecurrence` and emits
* weekly slots. **Honours `intervalWeeks > 1` correctly** —
* the existing `expandTodayIntakes` skipped it (the legacy
* bi-weekly worker bug R-3 finding 5 calls out); this engine
* anchors the week phase to `startsOn ?? createdAt` and emits
* on the matching weeks only.
*
* Pure functions, no DB access. Caller fetches `lastIntakeAt`
* (latest `MedicationIntakeEvent.takenAt`) and threads it through
* `RecurrenceContext`.
*/
import { RRule } from "rrule";
import { annotate } from "@/lib/logging/context";
import { parseScheduleRecurrence } from "@/lib/medication-schedule";
import { wallClockInTz } from "@/lib/tz/wall-clock";
/**
* v1.7.0 — schedule-type discriminator on the canonical schedule.
* SCHEDULED keeps the rrule / rolling / legacy dispatch unchanged. PRN
* emits no slots (it is as-needed — never projected, reminded, or
* counted in compliance-expected, but still loggable). CYCLIC gates
* whichever inner cadence (rrule / legacy) the schedule describes by an
* N-weeks-on / M-weeks-off phase anchored to `startsOn ?? createdAt`.
*/
export const SCHEDULE_TYPES = ["SCHEDULED", "PRN", "CYCLIC"] as const;
export type ScheduleType = (typeof SCHEDULE_TYPES)[number];
export interface CanonicalSchedule {
id: string;
rrule: string | null;
rollingIntervalDays: number | null;
timesOfDay: string[];
/**
* Legacy fallback fields. Read-only — the engine consults these
* only when `rrule` and `rollingIntervalDays` are both NULL and
* `oneShot` is false. Pre-v1.5 rows always populate these.
*/
daysOfWeek: string | null;
windowStart: string;
windowEnd: string;
reminderGraceMinutes: number | null;
/**
* v1.7.0 — schedule type. Defaults to SCHEDULED for every pre-v1.7
* row. PRN short-circuits the engine to zero slots; CYCLIC wraps the
* inner cadence with an on/off-week phase gate.
*/
scheduleType: ScheduleType;
/** v1.7.0 — cyclic "on" weeks. Only read when `scheduleType === "CYCLIC"`. */
cyclicOnWeeks: number | null;
/** v1.7.0 — cyclic "off" weeks. Only read when `scheduleType === "CYCLIC"`. */
cyclicOffWeeks: number | null;
/**
* v1.15.18 — per-dose configurable on-time intake windows. The recurrence
* engine itself never reads these (slot timing is unchanged); they ride on
* the canonical schedule purely so the band minter can build a slot's
* on-time band from an explicit `[start, end]` range for the matching
* `timeOfDay`. NULL / empty = every slot uses the default ±1h derivation.
*/
doseWindows?: DoseWindowEntry[] | null;
}
/**
* v1.15.18 — one explicit per-dose on-time window. `timeOfDay` keys the dose
* the window applies to (matching a `timesOfDay` entry); `start`/`end` are the
* HH:mm on-time bounds in the user's wall clock (`start <= end`, same local day).
*/
export interface DoseWindowEntry {
timeOfDay: string;
start: string;
end: string;
}
export interface RecurrenceContext {
/** The parent medication. */
medication: {
id: string;
startsOn: Date | null;
endsOn: Date | null;
oneShot: boolean;
createdAt: Date;
};
/** The user's IANA timezone (e.g. "Europe/Berlin"). */
timeZone: string;
/**
* Latest `MedicationIntakeEvent.takenAt` for this medication.
* Used only by rolling schedules. Null when the user has never
* logged an intake (rolling then anchors on `startsOn ?? createdAt`).
*/
lastIntakeAt: Date | null;
}
export interface Occurrence {
/**
* The start instant of this occurrence. The `timeOfDay` is applied
* to the day in the user's timezone, with DST handled correctly via
* the existing `wallClockInTz` two-pass solver.
*/
at: Date;
/**
* The grace-window end instant. Computed from
* `reminderGraceMinutes` when set, otherwise from the legacy
* `windowEnd - windowStart` span.
*/
graceUntil: Date;
/**
* Which `timesOfDay` entry this occurrence corresponds to (or
* `windowStart` when falling back to legacy). Lets the UI label
* "Morning dose" vs "Evening dose" of the same day.
*/
timeOfDay: string;
}
const DAY_MS = 24 * 60 * 60 * 1000;
const WEEK_MS = 7 * DAY_MS;
const DEFAULT_GRACE_MINUTES = 60;
const ONE_MINUTE_MS = 60_000;
// ────────────────────────────────────────────────────────────────────
// Public API
// ────────────────────────────────────────────────────────────────────
/**
* Emit every occurrence in `[from, to]` (inclusive of both ends) in
* chronological order. Pure: no DB access, no side effects.
*/
export function occurrencesBetween(
schedule: CanonicalSchedule,
from: Date,
to: Date,
ctx: RecurrenceContext,
): Occurrence[] {
if (to.getTime() < from.getTime()) return [];
// v1.7.0 — PRN (as-needed) emits no scheduled slots. It is loggable
// through the intake route but never projected, reminded, or counted
// in compliance-expected. The early return keeps every downstream
// surface (projector, worker, compliance) PRN-aware in one place.
if (schedule.scheduleType === "PRN") return [];
let slots: Occurrence[];
if (ctx.medication.oneShot) {
slots = expandOneShot(schedule, ctx, from, to);
} else if (schedule.rollingIntervalDays !== null) {
slots = expandRolling(schedule, ctx, from, to);
} else if (schedule.rrule !== null) {
slots = expandRrule(schedule, ctx, from, to);
} else {
slots = expandLegacy(schedule, ctx, from, to);
}
// v1.7.0 — CYCLIC gate. Drop any slot that lands in an "off" week of
// the N-on / M-off cycle. The inner cadence (rrule / legacy / rolling
// / one-shot) still decides which days emit within an "on" week; this
// only suppresses the off-week slots. Composes with `intervalWeeks`
// (the inner legacy stride) because the two phase computations are
// independent: the legacy stride filters weeks first, the cyclic gate
// filters the surviving slots second.
if (schedule.scheduleType === "CYCLIC") {
return slots.filter((s) => isInCyclicOnWeek(s.at, schedule, ctx));
}
return slots;
}
/**
* v1.7.0 — true when `instant` falls in an "on" week of the cyclic
* on/off phase. The anchor is the medication's `startsOn ?? createdAt`,
* snapped to its UTC week start. `phase = weeksFromAnchor mod
* (on + off)`; the slot survives iff `phase < on`. A non-positive or
* missing `cyclicOnWeeks` keeps every slot (defensive — the route + Zod
* require a positive value for CYCLIC, but the engine never throws on a
* malformed row).
*/
function isInCyclicOnWeek(
instant: Date,
schedule: CanonicalSchedule,
ctx: RecurrenceContext,
): boolean {
const onWeeks = schedule.cyclicOnWeeks;
const offWeeks = schedule.cyclicOffWeeks ?? 0;
if (onWeeks === null || onWeeks <= 0) return true;
const cycleLen = onWeeks + offWeeks;
if (cycleLen <= 0) return true;
const anchor = ctx.medication.startsOn ?? ctx.medication.createdAt;
const anchorWeekStart = startOfUtcWeek(anchor).getTime();
const instantWeekStart = startOfUtcWeek(instant).getTime();
const weeksFromAnchor = Math.round(
(instantWeekStart - anchorWeekStart) / WEEK_MS,
);
const phase = ((weeksFromAnchor % cycleLen) + cycleLen) % cycleLen;
return phase < onWeeks;
}
/**
* Compute the next occurrence strictly after `after`. Returns null
* when the schedule has terminated (one-shot anchor in the past;
* `endsOn` already crossed; rolling with neither a last intake nor a
* `startsOn` to anchor against).
*
* Implementation: walks forward in chunks (90 days for RRULE/legacy,
* one rolling cycle for rolling) until an occurrence is found or the
* `endsOn` boundary is reached. Caps at ~10 years out so a broken
* RRULE never spins.
*/
export function nextOccurrenceAfter(
schedule: CanonicalSchedule,
after: Date,
ctx: RecurrenceContext,
): Occurrence | null {
// v1.7.0 — PRN never has a next due instant.
if (schedule.scheduleType === "PRN") return null;
const endsOn = ctx.medication.endsOn;
const hardCap = new Date(after.getTime() + 365 * 10 * DAY_MS);
const limit = endsOn
? new Date(Math.min(endOfUtcDay(endsOn).getTime(), hardCap.getTime()))
: hardCap;
const cyclic = schedule.scheduleType === "CYCLIC";
// One-shot is single-slot — fast path. (One-shot is never cyclic, but
// gate defensively so a malformed row can't surface an off-week slot.)
if (ctx.medication.oneShot) {
const slots = expandOneShot(
schedule,
ctx,
new Date(after.getTime() + 1),
limit,
);
for (const s of slots) {
if (s.at.getTime() <= after.getTime()) continue;
if (cyclic && !isInCyclicOnWeek(s.at, schedule, ctx)) continue;
return s;
}
return null;
}
// Rolling is also single-slot (only emits the immediately next).
//
// v1.8.5 — floor the search window to the start of the user's current
// day rather than the strict `after` instant. A rolling dose whose slot
// lands earlier today (a past `startsOn` with no intake, or an overdue
// `lastIntakeAt + N`) is DUE/OVERDUE and must surface as "take now",
// not be skipped by a strict `> now` filter. Flooring to start-of-day
// keeps a slot the user has not yet acted on visible through the rest
// of its due day instead of silently rolling it forward by N.
if (schedule.rollingIntervalDays !== null) {
const dayFloor = startOfDayInTz(after, ctx.timeZone);
// With no intake logged the first dose anchors at `startsOn ?? createdAt`.
// When that anchor is on a PRIOR calendar day the dose is overdue by ≥1
// day and must still surface ("take now"); flooring only to the start of
// the user's current day dropped it out of existence (null next-due AND
// no reminder). Reach the floor back to the first-dose instant in that
// case so a multi-day-overdue start dose is returned. After an intake the
// re-anchor (`lastIntakeAt + N`) is always in the future, so the dayFloor
// is the correct, tighter bound there.
const floor =
ctx.lastIntakeAt === null
? new Date(Math.min(dayFloor.getTime(), firstRollingDoseDayFloor(ctx)))
: dayFloor;
const slots = expandRolling(schedule, ctx, floor, limit);
for (const s of slots) {
if (s.at.getTime() < floor.getTime()) continue;
if (cyclic && !isInCyclicOnWeek(s.at, schedule, ctx)) continue;
return s;
}
return null;
}
// Calendar cadences — walk in 90-day chunks.
//
// Defence-in-depth alongside the 10-year `hardCap`: every chunk
// costs one `rrule.between(...)` invocation (the rrule lib's
// internal MAXYEAR=9999 bounds each call, but the chunk count
// itself is unbounded). Cap the walk at MAX_CHUNKS so a pathological
// RRULE that emits very rarely (e.g. `FREQ=YEARLY;BYMONTHDAY=29;
// BYMONTH=2`) cannot spend an open-ended amount of time iterating
// the engine. Returns null on cap-hit, matching the "schedule has
// terminated" contract.
const MAX_CHUNKS = 80;
const chunkMs = 90 * DAY_MS;
let cursor = new Date(after.getTime() + 1);
let chunks = 0;
while (cursor.getTime() <= limit.getTime()) {
if (chunks++ >= MAX_CHUNKS) return null;
const chunkEnd = new Date(
Math.min(cursor.getTime() + chunkMs, limit.getTime()),
);
const slots = occurrencesBetween(schedule, cursor, chunkEnd, ctx);
for (const s of slots) {
if (s.at.getTime() > after.getTime()) return s;
}
cursor = new Date(chunkEnd.getTime() + 1);
}
return null;
}
/**
* Convenience predicate: does this schedule emit an occurrence at
* exactly `instant` (within a 1-minute tolerance)?
*/
export function matchesInstant(
schedule: CanonicalSchedule,
instant: Date,
ctx: RecurrenceContext,
): boolean {
const from = new Date(instant.getTime() - ONE_MINUTE_MS);
const to = new Date(instant.getTime() + ONE_MINUTE_MS);
const slots = occurrencesBetween(schedule, from, to, ctx);
return slots.some(
(s) => Math.abs(s.at.getTime() - instant.getTime()) <= ONE_MINUTE_MS,
);
}
// ────────────────────────────────────────────────────────────────────
// Dispatch — one-shot
// ────────────────────────────────────────────────────────────────────
function expandOneShot(
schedule: CanonicalSchedule,
ctx: RecurrenceContext,
from: Date,
to: Date,
): Occurrence[] {
const anchor = ctx.medication.startsOn ?? ctx.medication.createdAt;
const times = effectiveTimesOfDay(schedule);
const slots: Occurrence[] = [];
for (const time of times) {
const at = applyTimeOfDayToDate(anchor, time, ctx.timeZone);
if (at.getTime() < from.getTime() || at.getTime() > to.getTime()) continue;
slots.push(buildOccurrence(at, time, schedule));
}
return slots.sort((a, b) => a.at.getTime() - b.at.getTime());
}
// ────────────────────────────────────────────────────────────────────
// Dispatch — rolling
// ────────────────────────────────────────────────────────────────────
/**
* Rolling cadence — "every N days from last intake".
*
* Anchoring (v1.8.5 — medically-correct first dose):
* - After an intake → next slot is `lastIntakeAt + N days` (the
* v1.8.4 re-anchor). Logging a dose pushes the next one out by N.
* - No intake yet → the FIRST dose is due AT `startsOn ?? createdAt`,
* NOT `start + N`. A rolling course's first dose lands on the start
* date; the `+ N` cadence only kicks in once the first intake is
* logged. The pre-v1.8.5 engine emitted `start + N` here, which
* silently skipped the start-date dose (and suppressed its reminder,
* since the worker shares this engine).
*
* A past `startsOn` with no intake therefore surfaces the start dose as
* DUE/OVERDUE ("take now") via `nextOccurrenceAfter`'s rolling branch,
* rather than rolling it forward.
*
* Design choice: only the FIRST time-of-day entry is emitted even
* when multiple are configured. The rolling semantic — "every N days
* from when I last took it" — doesn't compose cleanly with multiple
* per-day intakes; the canonical rolling case is a once-weekly
* injection. A future revision could fan out, but that's a UX
* decision (does logging the morning intake re-anchor the evening
* intake?), not an engine one.
*
* Only the immediately-next slot is returned. Past rolling slots are
* historical intake events, not "expected slots" the schedule
* predicts forward.
*/
/**
* Start-of-day (in the user's timezone) of the no-intake first rolling dose
* anchor — `startsOn ?? createdAt`. Used by `nextOccurrenceAfter` to clamp the
* search floor so a multi-day-overdue first dose still surfaces. Mirrors the
* anchor `expandRolling` emits in the `lastIntakeAt === null` branch; flooring
* to the anchor's start-of-day keeps the time-of-day slot (e.g. 08:00) within
* the window rather than ahead of a raw-instant floor.
*/
function firstRollingDoseDayFloor(ctx: RecurrenceContext): number {
const anchor = ctx.medication.startsOn ?? ctx.medication.createdAt;
return startOfDayInTz(anchor, ctx.timeZone).getTime();
}
function expandRolling(
schedule: CanonicalSchedule,
ctx: RecurrenceContext,
from: Date,
to: Date,
): Occurrence[] {
const n = schedule.rollingIntervalDays;
if (n === null || n <= 0) return [];
// After an intake the next dose is N days out. With no intake yet the
// FIRST dose is the start date itself (no `+ N`) — see the doc comment.
const nextDue =
ctx.lastIntakeAt !== null
? new Date(ctx.lastIntakeAt.getTime() + n * DAY_MS)
: ctx.medication.startsOn ?? ctx.medication.createdAt;
// endsOn cap.
if (
ctx.medication.endsOn &&
nextDue.getTime() > endOfUtcDay(ctx.medication.endsOn).getTime()
) {
return [];
}
const time = schedule.timesOfDay[0] ?? schedule.windowStart;
const at = applyTimeOfDayToDate(nextDue, time, ctx.timeZone);
if (at.getTime() < from.getTime() || at.getTime() > to.getTime()) return [];
return [buildOccurrence(at, time, schedule)];
}
/**
* v1.13.x compliance — RETROSPECTIVE rolling expansion.
*
* `expandRolling` is forward-only by contract (the projector + reminder
* worker depend on it emitting ONLY the immediately-next slot). That is
* correct for "what's next" surfaces but wrong for the compliance grid,
* which must reconstruct the *historical* expected-dose slots a rolling
* cadence implies over a trailing window so a faithfully-adherent weekly
* injection reads its true rate instead of the vacuous 100%-or-0% flip
* the forward-only path produced.
*
* Medically-correct reading: a rolling "every N days from last dose"
* cadence re-anchors on each intake, so the retrospective expected grid
* *is* the observed intake history (each logged dose is exactly one
* satisfied expected slot) PLUS:
*
* - back-filled `missed` slots for genuinely skipped whole cycles: when
* two consecutive intakes are more than `1.5 · N` apart the user
* skipped one or more cycles → emit a slot at `prevIntake + k·N` for
* each whole cycle the gap spans (the `1.5·N` tolerance gate means a
* dose logged a day late never synthesizes a phantom miss); and
* - the single forward next-due slot, emitted ONLY when it is past-due
* (`nextDue ≤ now`). A not-yet-due forward slot is `upcoming` and is
* excluded so the open current cycle never counts against the
* denominator.
*
* Because the back-filled / forward slots carry no nearby intake, they
* pair to nothing in `pairDoses` and read `missed`; the per-intake slots
* are anchored AT the intake instant so they pair (distance 0) and read
* `taken`. The same grid feeds the count-only callers
* (`expectedSlotsBetween` / `expectedSlotCountForDay`) so numerator,
* denominator, and the heatmap `due` flags route through ONE expansion
* (the v1.7.3 B15 numerator/denominator-convergence rule).
*
* Kept here (not folded into `expandRolling`) so the engine's forward
* contract is untouched; compliance opts in explicitly via
* `expandRollingRetrospective`.
*
* @param intakeInstants Non-skipped intake instants for THIS medication
* (ascending or unsorted — sorted internally). The compliance layer
* supplies these; the engine has no DB access.
* @param now The wall-clock anchor (the compliance window's `to`-side
* "now"), used to decide whether the forward next-due slot is past-due.
*/
export function expandRollingRetrospective(
schedule: CanonicalSchedule,
ctx: RecurrenceContext,
from: Date,
to: Date,
intakeInstants: Date[],
now: Date,
): Occurrence[] {
const n = schedule.rollingIntervalDays;
if (n === null || n <= 0) return [];
const time = schedule.timesOfDay[0] ?? schedule.windowStart;
const cycleMs = n * DAY_MS;
// Tolerance: a gap up to 1.5·N is "on time" (a dose logged a little
// late). Only a gap strictly beyond this synthesizes skipped cycles.
const gapToleranceMs = 1.5 * cycleMs;
const endsCap = ctx.medication.endsOn
? endOfUtcDay(ctx.medication.endsOn).getTime()
: Infinity;
const inWindow = (at: Date): boolean =>
at.getTime() >= from.getTime() &&
at.getTime() <= to.getTime() &&
at.getTime() <= endsCap;
const slots: Occurrence[] = [];
// Each logged intake is a satisfied expected slot at its own instant.
// Sort ascending so the gap walk between consecutive intakes is correct.
const sorted = [...intakeInstants].sort((a, b) => a.getTime() - b.getTime());
for (const instant of sorted) {
if (inWindow(instant)) {
slots.push(buildOccurrence(instant, time, schedule));
}
}
// Back-fill missed slots for genuinely skipped whole cycles between
// consecutive intakes (gap > 1.5·N). The synthesized slots land at the
// schedule's time-of-day on each skipped cycle's day so they read as a
// real expected dose in the user's timezone.
for (let i = 1; i < sorted.length; i++) {
const prev = sorted[i - 1];
const next = sorted[i];
const gap = next.getTime() - prev.getTime();
if (gap <= gapToleranceMs) continue;
// Number of whole cycles the user skipped: floor(gap/N) − 1 missed
// cycles sit strictly between the two intakes.
const cyclesInGap = Math.floor(gap / cycleMs);
for (let k = 1; k < cyclesInGap; k++) {
const anchor = new Date(prev.getTime() + k * cycleMs);
const at = applyTimeOfDayToDate(anchor, time, ctx.timeZone);
if (inWindow(at)) {
slots.push(buildOccurrence(at, time, schedule));
}
}
}
// The single forward next-due slot — emitted as a missed slot ONLY when
// the open cycle is GENUINELY overdue, i.e. `now` is more than half a
// cycle past `nextDue`. A dose merely a little late (within `0.5·N`) is
// the current open cycle still in its window — it must NOT synthesize a
// phantom miss (the N-tolerance gate). A not-yet-due forward slot
// (`nextDue > now`) is excluded entirely (upcoming → out of the
// denominator). This keeps the open current cycle off the percentage rows
// until it is unambiguously missed; the `currentCycle` descriptor carries
// the softer on_track / due / missed state for the card.
const forwardToleranceMs = cycleMs / 2;
const lastInstant =
sorted.length > 0 ? sorted[sorted.length - 1] : ctx.lastIntakeAt;
const nextDue =
lastInstant !== null
? new Date(lastInstant.getTime() + cycleMs)
: ctx.medication.startsOn ?? ctx.medication.createdAt;
if (now.getTime() - nextDue.getTime() > forwardToleranceMs) {
const at = applyTimeOfDayToDate(nextDue, time, ctx.timeZone);
// Dedupe: a forward slot already represented by a logged intake (the
// intake re-anchored exactly N days out) must not double-count.
const alreadyPresent = slots.some(
(s) => Math.abs(s.at.getTime() - at.getTime()) < cycleMs / 2,
);
if (inWindow(at) && !alreadyPresent) {
slots.push(buildOccurrence(at, time, schedule));
}
}
return slots.sort((a, b) => a.at.getTime() - b.at.getTime());
}
// ────────────────────────────────────────────────────────────────────
// Dispatch — RRULE
// ────────────────────────────────────────────────────────────────────
function expandRrule(
schedule: CanonicalSchedule,
ctx: RecurrenceContext,
from: Date,
to: Date,
): Occurrence[] {
const rruleStr = schedule.rrule;
if (!rruleStr) return [];
const dtstart = ctx.medication.startsOn ?? ctx.medication.createdAt;
const dtstartLine = `DTSTART:${formatUtcBasic(startOfUtcDay(dtstart))}`;
// Skip the engine-side UNTIL suffix when the user's RRULE already
// bounds the recurrence with COUNT or UNTIL — RFC 5545 forbids both
// (and any two-UNTIL collision), and RRule.fromString throws on the
// duplicate, silently collapsing the schedule to zero slots.
const userBoundsRecurrence = /(?:^|;)(?:COUNT|UNTIL)=/.test(rruleStr);
const untilSuffix =
ctx.medication.endsOn && !userBoundsRecurrence
? `;UNTIL=${formatUtcBasic(endOfUtcDay(ctx.medication.endsOn))}`
: "";
const full = `${dtstartLine}\nRRULE:${rruleStr}${untilSuffix}`;
let rule: RRule;
try {
rule = RRule.fromString(full);
} catch {
annotate({
action: { name: "medication.recurrence.parse_error" },
meta: { rrule: rruleStr },
});
return [];
}
// Walk a generously padded day-anchor window so a per-day timesOfDay
// expansion still hits the requested [from, to] after the time-of-day
// is applied. The rrule lib's day-anchored dates land at midnight UTC
// of the BYDAY/BYMONTHDAY day; the time-of-day might push back across
// a day boundary in some timezones, so widen the window by 2 days on
// each side.
const padded = 2 * DAY_MS;
const after = new Date(from.getTime() - padded);
const before = new Date(to.getTime() + padded);
const dayAnchors = rule.between(after, before, true);
const times = effectiveTimesOfDay(schedule);
const slots: Occurrence[] = [];
for (const anchor of dayAnchors) {
for (const time of times) {
const at = applyTimeOfDayToDate(anchor, time, ctx.timeZone);
if (at.getTime() < from.getTime()) continue;
if (at.getTime() > to.getTime()) continue;
slots.push(buildOccurrence(at, time, schedule));
}
}
return slots.sort((a, b) => a.at.getTime() - b.at.getTime());
}
// ────────────────────────────────────────────────────────────────────
// Dispatch — legacy fallback
// ────────────────────────────────────────────────────────────────────
function expandLegacy(
schedule: CanonicalSchedule,
ctx: RecurrenceContext,
from: Date,
to: Date,
): Occurrence[] {
const recurrence = parseScheduleRecurrence(schedule.daysOfWeek);
const anchor = ctx.medication.startsOn ?? ctx.medication.createdAt;
const anchorWeekStartUtc = startOfUtcWeek(anchor).getTime();
const times = effectiveTimesOfDay(schedule);
const slots: Occurrence[] = [];
// Iterate every UTC day in [from-1, to+1] to cover any time-of-day
// that might land in [from, to] after applying the local-tz HH:mm.
const start = startOfUtcDay(new Date(from.getTime() - DAY_MS));
const end = startOfUtcDay(new Date(to.getTime() + DAY_MS));
const startsOnFloor = ctx.medication.startsOn
? startOfUtcDay(ctx.medication.startsOn).getTime()
: null;
for (
let day = start;
day.getTime() <= end.getTime();
day = new Date(day.getTime() + DAY_MS)
) {
// startsOn floor — every other dispatch tier honours it; the
// legacy walker used to iterate from creation regardless, so a
// legacy-shape schedule with a future startsOn emitted historical
// slots. Mirror the endsOn cap below.
if (startsOnFloor !== null && day.getTime() < startsOnFloor) {
continue;
}
// Day-of-week filter (empty = every day). Use the user's
// timezone weekday so the legacy "Mon = 1" encoding aligns with
// the user's local-Mon, not UTC-Mon.
const localWeekday = wallClockInTz(day, ctx.timeZone).weekday;
if (
recurrence.daysOfWeek.length > 0 &&
!recurrence.daysOfWeek.includes(localWeekday)
) {
continue;
}
// Multi-week interval — the fix vs the legacy worker, which
// silently ignored intervalWeeks.
if (recurrence.intervalWeeks > 1) {
const dayWeekStart = startOfUtcWeek(day).getTime();
const weeksFromAnchor = Math.round(
(dayWeekStart - anchorWeekStartUtc) / WEEK_MS,
);
const phase =
((weeksFromAnchor % recurrence.intervalWeeks) +
recurrence.intervalWeeks) %
recurrence.intervalWeeks;
if (phase !== 0) continue;
}
// endsOn cap.
if (
ctx.medication.endsOn &&
day.getTime() > endOfUtcDay(ctx.medication.endsOn).getTime()
) {
continue;
}
for (const time of times) {
const at = applyTimeOfDayToDate(day, time, ctx.timeZone);
if (at.getTime() < from.getTime()) continue;
if (at.getTime() > to.getTime()) continue;
slots.push(buildOccurrence(at, time, schedule));
}
}
return slots.sort((a, b) => a.at.getTime() - b.at.getTime());
}
// ────────────────────────────────────────────────────────────────────
// Shared helpers
// ────────────────────────────────────────────────────────────────────
function effectiveTimesOfDay(schedule: CanonicalSchedule): string[] {
return schedule.timesOfDay.length > 0
? schedule.timesOfDay
: [schedule.windowStart];
}
/**
* Apply an "HH:mm" time-of-day to `day` in the user's IANA timezone,
* returning the corresponding UTC instant. DST-aware via the two-pass
* solver pattern from `medication-schedule.ts`.
*
* `day` is interpreted as "the day in the user's timezone at which
* the time-of-day should land" — we read its wall-clock Y/M/D in the
* target zone, then materialise the instant for that Y/M/D + H/M in
* that zone. So passing midnight-UTC on the spring-forward day with
* Europe/Berlin gives the local-Berlin day, not the previous-Berlin
* day even if the UTC midnight technically falls before the local
* day boundary.
*/
function applyTimeOfDayToDate(day: Date, hhmm: string, tz: string): Date {
const [hStr, mStr] = hhmm.split(":");
const h = Number(hStr);
const m = Number(mStr);
if (!Number.isFinite(h) || !Number.isFinite(m)) return day;
const parts = wallClockInTz(day, tz);
let guess = new Date(
Date.UTC(parts.year, parts.month - 1, parts.day, h, m, 0, 0),
);
for (let i = 0; i < 2; i++) {
const offsetMin = tzOffsetMinutes(guess, tz);
guess = new Date(
Date.UTC(parts.year, parts.month - 1, parts.day, h, m, 0, 0) -
offsetMin * 60_000,
);
}
return guess;
}
/**
* The UTC instant of midnight (00:00 wall-clock) on `instant`'s day in
* the user's IANA timezone. Used by the rolling-cadence next-due search
* to floor the window to the start of the user's current day so an
* overdue / due-earlier-today rolling dose still surfaces.
*/
function startOfDayInTz(instant: Date, tz: string): Date {
return applyTimeOfDayToDate(instant, "00:00", tz);
}
function tzOffsetMinutes(date: Date, tz: string): number {
const parts = wallClockInTz(date, tz);
const asIfUtc = Date.UTC(
parts.year,
parts.month - 1,
parts.day,
parts.hour,
parts.minute,
parts.second,
);
return Math.round((asIfUtc - date.getTime()) / 60_000);
}
function buildOccurrence(
at: Date,
timeOfDay: string,
schedule: CanonicalSchedule,
): Occurrence {
return {
at,
timeOfDay,
graceUntil: new Date(at.getTime() + graceWindowMs(schedule)),
};
}
/**
* Resolve the grace window for an occurrence:
*
* - `reminderGraceMinutes` when set on the schedule
* - else `windowEnd - windowStart` span (in minutes)
* - else `DEFAULT_GRACE_MINUTES` (60) when the legacy fields agree
* (single-time window like "08:00..08:00")
*
* Handles overnight legacy windows (`windowEnd < windowStart`) by
* pushing windowEnd to the next day.
*/
function graceWindowMs(schedule: CanonicalSchedule): number {
if (schedule.reminderGraceMinutes !== null) {
return schedule.reminderGraceMinutes * ONE_MINUTE_MS;
}
const startMin = hhmmToMinutes(schedule.windowStart);
const endMin = hhmmToMinutes(schedule.windowEnd);
if (startMin === null || endMin === null) {
return DEFAULT_GRACE_MINUTES * ONE_MINUTE_MS;
}
let span = endMin - startMin;
if (span < 0) span += 24 * 60; // overnight window
if (span === 0) span = DEFAULT_GRACE_MINUTES;
return span * ONE_MINUTE_MS;
}
function hhmmToMinutes(hhmm: string): number | null {
const [hStr, mStr] = hhmm.split(":");
const h = Number(hStr);
const m = Number(mStr);
if (!Number.isFinite(h) || !Number.isFinite(m)) return null;
return h * 60 + m;
}
// ────────────────────────────────────────────────────────────────────
// UTC date helpers (RRULE day-anchor + endsOn cap arithmetic)
// ────────────────────────────────────────────────────────────────────
function startOfUtcDay(d: Date): Date {
return new Date(
Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate(), 0, 0, 0, 0),
);
}
function endOfUtcDay(d: Date): Date {
return new Date(
Date.UTC(
d.getUTCFullYear(),
d.getUTCMonth(),
d.getUTCDate(),
23,
59,
59,
999,
),
);
}
function startOfUtcWeek(d: Date): Date {
const midnight = startOfUtcDay(d);
const weekday = midnight.getUTCDay(); // 0 = Sun
return new Date(midnight.getTime() - weekday * DAY_MS);
}
/** RFC 5545 basic-format UTC instant: `YYYYMMDDTHHMMSSZ`. */
function formatUtcBasic(d: Date): string {
const pad = (n: number, w = 2): string => String(n).padStart(w, "0");
return (
`${d.getUTCFullYear()}${pad(d.getUTCMonth() + 1)}${pad(d.getUTCDate())}` +
`T${pad(d.getUTCHours())}${pad(d.getUTCMinutes())}${pad(d.getUTCSeconds())}Z`
);
}