From 73bc0521873502596e9347af7819de8232859bb1 Mon Sep 17 00:00:00 2001 From: tkoehlerlg Date: Thu, 24 Sep 2026 23:14:36 +0200 Subject: [PATCH] docs: say what a pattern means when the clock changes Three places a reader meets a surprise and the README was silent: that an availability pattern names wall-clock times, so a shift is eight hours on the clock and seven or nine elapsed on a transition day; that a daily window is measured on the caller's day, so an evening window crossing UTC midnight keeps its slots; and that busy times are now validated and copied on the way in, so a bad Date throws rather than being scheduled against. Co-Authored-By: Claude Opus 5 (1M context) --- README.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/README.md b/README.md index 4736553..23e9ffc 100644 --- a/README.md +++ b/README.md @@ -97,6 +97,8 @@ const availableSlots = scheduler.findAvailableSlots( ### Managing Busy Times +Busy times are validated on the way in: both boundaries must be real `Date`s and the interval must not end before it starts, or the call throws. They are copied, so mutating what you passed in — or what `getBusyTimes()` hands back — does not change the scheduler's answers. + ```typescript import { Scheduler } from 'scheduling-sdk' @@ -136,6 +138,8 @@ const currentBusyTimes = scheduler.getBusyTimes() **Business hours made easy ;)** +A pattern names times on your clock, not instants: `09:00`–`17:00` is eight hours on the clock every week, which is seven or nine *elapsed* hours on the two days a year the zone changes offset — the same thing a recurring block does in Google Calendar or Outlook. A wall time the clock skips is simply not offered, and one it repeats is offered twice. + ```typescript import { AvailabilityScheduler } from 'scheduling-sdk' @@ -244,6 +248,7 @@ Notes: - If you use `AvailabilityScheduler`, you may omit `timezone` in `findAvailableSlots` when using `earliestTime`/`latestTime`; it will default to the scheduler’s timezone. - If you use the core `Scheduler`, providing `earliestTime`/`latestTime` without `timezone` will throw a validation error. - Daily windows filter by slot START time. +- The window is measured on the caller's **local** day, so an evening window that crosses UTC midnight (say `20:00`–`24:00` in New York) keeps its slots. ### Allowing Overlaps (K-overlaps)