metatrondelivery/app/lib/time.ts

import { DateTime } from "luxon";

// All date math for scheduling lives here. Nothing in this file touches the
// DB, the clock, or Shopify — every function takes its inputs explicitly so
// it stays exhaustively unit-testable (CLAUDE.md: "pure functions... inject
// data, no I/O in the math").

const MINUTES_PER_DAY = 24 * 60;

export type IsoDate = string; // "YYYY-MM-DD", a calendar date with no timezone of its own

/**
 * The exact instant a "minutes from midnight" wall-clock offset (as stored
 * on SlotTemplate/SlotOverride) refers to, on a given calendar date, in a
 * given IANA timezone.
 *
 * Deliberately built via `DateTime.fromObject({ hour, minute }, { zone })`
 * rather than `midnight.plus({ minutes })`: `.plus()` on time units adds
 * *elapsed* real time, so on a spring-forward day it would land an hour
 * later than the intended wall-clock time (e.g. "9:00 AM" computed as
 * "540 elapsed minutes past local midnight" becomes 10:00 AM on the day the
 * clocks jump). Building from the wall-clock fields directly keeps "9:00 AM"
 * meaning 9:00 AM regardless of what the clocks did earlier that day.
 */
export function slotDateTime(date: IsoDate, minutesFromMidnight: number, timezone: string): DateTime {
  if (minutesFromMidnight < 0 || minutesFromMidnight > MINUTES_PER_DAY) {
    throw new RangeError(`minutesFromMidnight out of range: ${minutesFromMidnight}`);
  }

  const base = DateTime.fromISO(date, { zone: timezone });
  if (!base.isValid) {
    throw new RangeError(`Invalid date "${date}" for zone "${timezone}": ${base.invalidReason}`);
  }

  const hour = Math.floor(minutesFromMidnight / 60);
  const minute = minutesFromMidnight % 60;

  const result = base.set({ hour, minute, second: 0, millisecond: 0 });

  // A wall-clock time that doesn't exist (spring-forward gap, e.g. 2:30 AM
  // on the day clocks jump from 2:00 to 3:00) stays `isValid` in Luxon —
  // `.set()` silently rolls it forward past the gap (2:30 -> 3:30) instead
  // of rejecting it. Detect that by checking the fields actually landed
  // where asked; surface it rather than silently returning a shifted time
  // a merchant never configured.
  if (result.hour !== hour || result.minute !== minute) {
    throw new RangeError(
      `${date} ${String(hour).padStart(2, "0")}:${String(minute).padStart(2, "0")} does not exist in ${timezone} (DST spring-forward gap)`,
    );
  }

  return result;
}

/** 0 (Sunday) .. 6 (Saturday), evaluated as a calendar date — independent of what time or timezone the server itself is running in. */
export function weekdayOf(date: IsoDate, timezone: string): number {
  const dt = DateTime.fromISO(date, { zone: timezone });
  // Luxon's weekday is 1 (Monday) .. 7 (Sunday); our schema uses 0 (Sunday) .. 6 (Saturday).
  return dt.weekday % 7;
}

/**
 * Inclusive list of calendar dates from start to end (both "YYYY-MM-DD").
 * Pinned to UTC — these are plain calendar dates, not instants, so stepping
 * through them must not depend on the server process's own local timezone
 * or DST (which would otherwise risk skipping/repeating a date on the
 * server's own transition day).
 */
export function enumerateDates(startDate: IsoDate, endDate: IsoDate): IsoDate[] {
  const start = DateTime.fromISO(startDate, { zone: "utc" });
  const end = DateTime.fromISO(endDate, { zone: "utc" });
  if (!start.isValid || !end.isValid) {
    throw new RangeError(`Invalid date range: ${startDate}..${endDate}`);
  }

  const dates: IsoDate[] = [];
  for (let d = start; d <= end; d = d.plus({ days: 1 })) {
    dates.push(d.toISODate()!);
  }
  return dates;
}

/**
 * Minutes between `now` and a slot's start, in real elapsed time (correctly
 * reflecting a DST change if `now` and the slot fall on opposite sides of
 * one — e.g. a slot booked the evening before a fall-back has genuinely 60
 * more minutes of lead time than the wall-clock difference would suggest).
 */
export function minutesUntil(now: DateTime, target: DateTime): number {
  return target.diff(now, "minutes").minutes;
}