scschedule 2.1.0 → 3.0.0

package/README.md

@@ -16,7 +16,7 @@ scschedule is a TypeScript library for managing time-based availability patterns
 - **Recurring patterns**: Define weekly schedules with different hours for different days
 - **Override system**: Add exceptions for holidays, special events, or schedule changes
 - **Cross-midnight support**: Handle time ranges that span midnight (e.g., 22:00-02:00)
-- **Timezone aware**: All operations use schedule's timezone for calculations
+- **Time zone aware**: Time zone passed at the call site where needed (DST-safe arithmetic)
 - **DST handling**: Properly handles daylight saving time transitions
 - **Immutable**: All operations return new instances
 - **Type-safe validation**: Discriminated union errors with detailed information
@@ -46,12 +46,11 @@ import {
 } from 'scschedule'
 import { sDate, sTime, sWeekdays, getTimestampNow } from 'scdate'
 
-// Define a restaurant schedule: Tuesday-Saturday, 11:00-22:00
+// Define a restaurant schedule: Monday-Saturday, 11:00-22:00
 const restaurant: Schedule = {
-  timezone: 'America/Puerto_Rico',
   weekly: [
     {
-      weekdays: sWeekdays('-MTWTFS'), // Tue-Sat
+      weekdays: sWeekdays('-MTWTFS'), // Mon-Sat
       times: [{ from: sTime('11:00'), to: sTime('22:00') }],
     },
   ],
@@ -68,8 +67,8 @@ const now = getTimestampNow('America/Puerto_Rico')
 const isOpen = isScheduleAvailable(restaurant, now)
 console.log(`Restaurant is ${isOpen ? 'open' : 'closed'}`)
 
-// Find next opening time
-const nextOpen = getNextAvailableFromSchedule(restaurant, now)
+// Find next opening time (search up to 30 days ahead)
+const nextOpen = getNextAvailableFromSchedule(restaurant, now, 30)
 if (nextOpen) {
   console.log(`Next opening: ${nextOpen.timestamp}`)
 }
@@ -81,14 +80,12 @@ if (nextOpen) {
 
 A `Schedule` consists of:
 
-- **timezone**: The timezone for all time calculations
-- **weekly**: Base recurring schedule (array of `WeeklyScheduleRule`)
+- **weekly**: Base recurring schedule — `true` (available 24/7), an array of `WeeklyScheduleRule` (time-based), or `[]` (never available; overrides can open windows)
 - **overrides** (optional): Date-specific exceptions (array of `OverrideScheduleRule`)
 
 ```typescript
 interface Schedule {
-  timezone: string
-  weekly: WeeklyScheduleRule[]
+  weekly: WeeklyScheduleRule[] | true
   overrides?: OverrideScheduleRule[]
 }
 ```
@@ -139,6 +136,17 @@ Rules are evaluated in order of priority:
 
 ### Validation
 
+#### `isValidTimeZone(timeZone: string): boolean`
+
+Re-exported from `scdate`. Checks if a string is a valid IANA time zone identifier (using `Intl.supportedValuesOf('timeZone')`).
+
+```typescript
+import { isValidTimeZone } from 'scschedule' // or from 'scdate'
+
+isValidTimeZone('America/New_York') // true
+isValidTimeZone('Invalid/Timezone') // false
+```
+
 #### `validateSchedule(schedule: Schedule): ValidationResult`
 
 Validates a schedule and returns detailed errors.
@@ -151,9 +159,6 @@ const result = validateSchedule(mySchedule)
 if (!result.valid) {
   result.errors.forEach((error) => {
     switch (error.issue) {
-      case ValidationIssue.InvalidTimezone:
-        console.error(`Invalid timezone: ${error.timezone}`)
-        break
       case ValidationIssue.OverlappingSpecificOverrides:
         console.error(
           `Overlapping overrides at indexes: ${error.overrideIndexes}`,
@@ -167,13 +172,16 @@ if (!result.valid) {
 
 **Validation checks**:
 
-- Valid timezone (in `Intl.supportedValuesOf('timeZone')`)
+- Valid scdate formats (SDate, STime, SWeekdays)
+- Override `to` date must not be before `from` date
 - No duplicate overrides (identical from/to dates)
 - No overlapping specific overrides (hierarchical nesting allowed)
-- No overlapping time ranges within rules (same weekday)
+- No overlapping time ranges within a single rule (same weekday)
+- No overlapping rules within the weekly schedule (shared weekdays with overlapping times)
+- No overlapping rules within the same override (shared weekdays with overlapping times)
+- No cross-midnight spillover conflicts at override boundaries
 - All rules have at least one time range
-- Valid scdate formats (SDate, STime, SWeekdays)
-- No empty weekdays patterns (e.g., '-------' with no days selected)
+- No empty weekdays patterns (e.g., `'-------'` with no days selected)
 - Override weekdays must match at least one date in the override's date range
 
 ### Schedule Management
@@ -208,27 +216,32 @@ const isOpen = isScheduleAvailable(
 )
 ```
 
-#### `getNextAvailableFromSchedule(schedule: Schedule, fromTimestamp: STimestamp | string, maxDaysToSearch?: number): STimestamp | undefined`
+#### `getNextAvailableFromSchedule(schedule: Schedule, fromTimestamp: STimestamp | string, maxDaysToSearch: number): STimestamp | undefined`
 
-Find the next available timestamp from a given time. Searches up to `maxDaysToSearch` days (default: 365).
+Find the next available timestamp from a given time. Searches up to `maxDaysToSearch` days forward.
 
 ```typescript
 import { getNextAvailableFromSchedule } from 'scschedule'
 
-const nextOpen = getNextAvailableFromSchedule(restaurant, now)
+const nextOpen = getNextAvailableFromSchedule(restaurant, now, 30)
 if (nextOpen) {
   console.log(`Opens at: ${nextOpen.timestamp}`)
 }
 ```
 
-#### `getNextUnavailableFromSchedule(schedule: Schedule, fromTimestamp: STimestamp | string): STimestamp | undefined`
+#### `getNextUnavailableFromSchedule(schedule: Schedule, timeZone: string, fromTimestamp: STimestamp | string, maxDaysToSearch: number): STimestamp | undefined`
 
-Find the next unavailable timestamp from a given time.
+Find the next unavailable timestamp from a given time. Requires a time zone for DST-safe timestamp arithmetic. Searches up to `maxDaysToSearch` days forward.
 
 ```typescript
 import { getNextUnavailableFromSchedule } from 'scschedule'
 
-const nextClosed = getNextUnavailableFromSchedule(restaurant, now)
+const nextClosed = getNextUnavailableFromSchedule(
+  restaurant,
+  'America/Puerto_Rico',
+  now,
+  30,
+)
 if (nextClosed) {
   console.log(`Closes at: ${nextClosed.timestamp}`)
 }
@@ -262,10 +275,9 @@ import { Schedule } from 'scschedule'
 import { sTime, sWeekdays } from 'scdate'
 
 const restaurant: Schedule = {
-  timezone: 'America/Puerto_Rico',
   weekly: [
     {
-      weekdays: sWeekdays('-MTWTFS'), // Tue-Sat
+      weekdays: sWeekdays('-MTWTFS'), // Mon-Sat
       times: [{ from: sTime('11:00'), to: sTime('22:00') }],
     },
   ],
@@ -276,10 +288,9 @@ const restaurant: Schedule = {
 
 ```typescript
 const restaurant: Schedule = {
-  timezone: 'America/Puerto_Rico',
   weekly: [
     {
-      weekdays: sWeekdays('-MTWTFS'), // Tue-Sat
+      weekdays: sWeekdays('-MTWTFS'), // Mon-Sat
       times: [
         { from: sTime('11:00'), to: sTime('14:00') }, // Lunch
         { from: sTime('17:00'), to: sTime('22:00') }, // Dinner
@@ -293,7 +304,6 @@ const restaurant: Schedule = {
 
 ```typescript
 const restaurant: Schedule = {
-  timezone: 'America/Puerto_Rico',
   weekly: [
     {
       // Weekdays: longer hours
@@ -371,7 +381,6 @@ const newSchedule: Schedule = {
 
 ```typescript
 const lateNightBar: Schedule = {
-  timezone: 'America/Puerto_Rico',
   weekly: [
     {
       weekdays: sWeekdays('----TFS'), // Thu-Sat
@@ -386,16 +395,65 @@ const lateNightBar: Schedule = {
 // - Saturday: 20:00-23:59, Sunday: 00:00-03:00
 ```
 
+### Always Available (`weekly: true`)
+
+Use `weekly: true` when an entity is available 24/7 by default. This is useful for items that inherit availability from a parent schedule (e.g., menu items that go through the restaurant's schedule filter first).
+
+```typescript
+// Menu item available 24/7 (restaurant hours handle the filtering)
+const menuItem: Schedule = {
+  weekly: true,
+  overrides: [
+    {
+      // Except Christmas Day
+      from: sDate('2025-12-25'),
+      to: sDate('2025-12-25'),
+      rules: [],
+    },
+  ],
+}
+```
+
+### Closed by Default (`weekly: []`)
+
+Use `weekly: []` when an entity is unavailable by default and only opens during specific override periods.
+
+```typescript
+// Pop-up shop: closed by default, open only during specific events
+const popUpShop: Schedule = {
+  weekly: [],
+  overrides: [
+    {
+      from: sDate('2025-12-20'),
+      to: sDate('2025-12-24'),
+      rules: [
+        {
+          weekdays: sWeekdays('SMTWTFS'),
+          times: [{ from: sTime('10:00'), to: sTime('18:00') }],
+        },
+      ],
+    },
+  ],
+}
+```
+
 ### Multiple Schedules (Layered Availability)
 
 ```typescript
 import { isScheduleAvailable } from 'scschedule'
 
 const businessHours: Schedule = {
-  /* ... */
+  weekly: [
+    {
+      weekdays: sWeekdays('-MTWTFS'),
+      times: [{ from: sTime('11:00'), to: sTime('22:00') }],
+    },
+  ],
 }
+
+// Menu available 24/7 — restaurant hours do the filtering
 const breakfastMenu: Schedule = {
-  /* ... */
+  weekly: true,
 }
 
 // Both must be available
@@ -411,8 +469,16 @@ The library uses discriminated unions for type-safe error handling:
 ```typescript
 type ValidationError =
   | {
-      issue: ValidationIssue.InvalidTimezone
-      timezone: string
+      issue: ValidationIssue.InvalidScDateFormat
+      field: string
+      value: string
+      expectedFormat: string
+    }
+  | {
+      issue: ValidationIssue.InvalidOverrideDateOrder
+      overrideIndex: number
+      from: string
+      to: string
     }
   | {
       issue: ValidationIssue.DuplicateOverrides
@@ -433,6 +499,17 @@ type ValidationError =
           }
       timeRangeIndexes: [number, number]
     }
+  | {
+      issue: ValidationIssue.OverlappingRulesInWeekly
+      ruleIndexes: [number, number]
+      weekday: Weekday
+    }
+  | {
+      issue: ValidationIssue.OverlappingRulesInOverride
+      overrideIndex: number
+      ruleIndexes: [number, number]
+      weekday: Weekday
+    }
   | {
       issue: ValidationIssue.EmptyTimes
       location:
@@ -443,12 +520,6 @@ type ValidationError =
             ruleIndex: number
           }
     }
-  | {
-      issue: ValidationIssue.InvalidScDateFormat
-      field: string
-      value: string
-      expectedFormat: string
-    }
   | {
       issue: ValidationIssue.EmptyWeekdays
       location:
@@ -466,6 +537,24 @@ type ValidationError =
       weekdays: string
       dateRange: { from: string; to: string }
     }
+  | {
+      issue: ValidationIssue.SpilloverConflictIntoOverrideFirstDay
+      overrideIndex: number
+      date: string
+      overrideRuleIndex: number
+      sourceWeeklyRuleIndex?: number
+      sourceOverrideIndex?: number
+      sourceOverrideRuleIndex?: number
+    }
+  | {
+      issue: ValidationIssue.SpilloverConflictOverrideIntoNext
+      overrideIndex: number
+      date: string
+      overrideRuleIndex: number
+      nextDayWeeklyRuleIndex?: number
+      nextDayOverrideIndex?: number
+      nextDayOverrideRuleIndex?: number
+    }
 ```
 
 ## Best Practices
@@ -475,14 +564,14 @@ type ValidationError =
 3. **Use specific date ranges** for overrides when possible - indefinite overrides are useful for permanent schedule changes
 4. **When using multiple indefinite overrides**, remember that the most recent one (latest `from` date) takes precedence
 5. **Test cross-midnight ranges** thoroughly if your schedule uses them
-6. **Consider timezone** carefully - all times are interpreted in the schedule's timezone
+6. **Validate time zones** separately using `isValidTimeZone()` before passing them to functions that require one
 7. **Handle DST transitions** by testing schedules during spring forward and fall back
 
 ## Edge Cases
 
 ### DST Transitions
 
-The library handles DST transitions using scdate's timezone functions. Times that fall in "missing hours" (spring forward) are treated as unavailable.
+The library handles DST transitions using scdate's time zone functions. Times that fall in "missing hours" (spring forward) are treated as unavailable.
 
 ### Cross-Midnight Ranges
 
@@ -505,7 +594,19 @@ import type {
   AvailabilityRange,
   ValidationError,
   ValidationResult,
+  SDateString,
+  STimeString,
+  STimestampString,
+  SWeekdaysString,
 } from 'scschedule'
+
+import { ValidationIssue, RuleLocationType } from 'scschedule'
+```
+
+Note: The `Weekday` enum (used in some `ValidationError` variants) is exported from `scdate`, not `scschedule`:
+
+```typescript
+import { Weekday } from 'scdate'
 ```
 
 ## Dependencies

package/dist/cleanupExpiredOverridesFromSchedule.d.ts

@@ -3,5 +3,9 @@ import type { Schedule } from './types.js';
 /**
  * Removes expired overrides from a schedule that ended before the
  * specified date. It does not remove indefinite overrides (no to date).
+ *
+ * @param schedule The schedule to clean up.
+ * @param beforeDate Overrides that ended before this date are removed. It
+ * can be an SDate or a string in the YYYY-MM-DD format.
  */
 export declare const cleanupExpiredOverridesFromSchedule: (schedule: Schedule, beforeDate: SDate | string) => Schedule;

package/dist/cleanupExpiredOverridesFromSchedule.js

@@ -2,6 +2,10 @@ import { isSameDateOrAfter } from 'scdate';
 /**
  * Removes expired overrides from a schedule that ended before the
  * specified date. It does not remove indefinite overrides (no to date).
+ *
+ * @param schedule The schedule to clean up.
+ * @param beforeDate Overrides that ended before this date are removed. It
+ * can be an SDate or a string in the YYYY-MM-DD format.
  */
 export const cleanupExpiredOverridesFromSchedule = (schedule, beforeDate) => {
     // If there are no overrides, return the schedule as-is

package/dist/constants.d.ts

@@ -4,8 +4,6 @@
  * validation failure.
  */
 export declare enum ValidationIssue {
-    /** The timezone string is not a valid IANA timezone identifier */
-    InvalidTimezone = "invalid-timezone",
     /** Two or more specific overrides have identical date ranges */
     DuplicateOverrides = "duplicate-overrides",
     /** Two or more specific overrides have overlapping date ranges */
@@ -49,7 +47,7 @@ export declare enum ValidationIssue {
     SpilloverConflictIntoOverrideFirstDay = "spillover-conflict-into-override-first-day",
     /**
      * Cross-midnight spillover from override's last day conflicts with next
-     * day's time ranges (weekly or another override)
+     * day's time ranges (weekly rules, weekly: true, or another override)
      */
     SpilloverConflictOverrideIntoNext = "spillover-conflict-override-into-next",
     /**

package/dist/constants.js

@@ -5,8 +5,6 @@
  */
 export var ValidationIssue;
 (function (ValidationIssue) {
-    /** The timezone string is not a valid IANA timezone identifier */
-    ValidationIssue["InvalidTimezone"] = "invalid-timezone";
     /** Two or more specific overrides have identical date ranges */
     ValidationIssue["DuplicateOverrides"] = "duplicate-overrides";
     /** Two or more specific overrides have overlapping date ranges */
@@ -50,7 +48,7 @@ export var ValidationIssue;
     ValidationIssue["SpilloverConflictIntoOverrideFirstDay"] = "spillover-conflict-into-override-first-day";
     /**
      * Cross-midnight spillover from override's last day conflicts with next
-     * day's time ranges (weekly or another override)
+     * day's time ranges (weekly rules, weekly: true, or another override)
      */
     ValidationIssue["SpilloverConflictOverrideIntoNext"] = "spillover-conflict-override-into-next";
     /**

package/dist/getAvailableRangesFromSchedule.d.ts

@@ -3,5 +3,15 @@ import type { AvailabilityRange, Schedule } from './types.js';
 /**
  * Returns all available time ranges within a schedule for the specified
  * date range.
+ *
+ * Iterates day-by-day from startDate to endDate (inclusive). For each day,
+ * when rules are `true` (always available), emits a full-day range
+ * (00:00-23:59). Otherwise, emits each matching time range, including
+ * cross-midnight ranges that extend into the next day.
+ *
+ * @param schedule The schedule to get availability from.
+ * @param startDate The start of the date range (inclusive).
+ * @param endDate The end of the date range (inclusive).
+ * @returns An array of availability ranges within the date range.
  */
 export declare const getAvailableRangesFromSchedule: (schedule: Schedule, startDate: SDate | string, endDate: SDate | string) => AvailabilityRange[];

package/dist/getAvailableRangesFromSchedule.js

@@ -3,6 +3,16 @@ import { getApplicableRuleForDate } from './internal/getApplicableRuleForDate.js
 /**
  * Returns all available time ranges within a schedule for the specified
  * date range.
+ *
+ * Iterates day-by-day from startDate to endDate (inclusive). For each day,
+ * when rules are `true` (always available), emits a full-day range
+ * (00:00-23:59). Otherwise, emits each matching time range, including
+ * cross-midnight ranges that extend into the next day.
+ *
+ * @param schedule The schedule to get availability from.
+ * @param startDate The start of the date range (inclusive).
+ * @param endDate The end of the date range (inclusive).
+ * @returns An array of availability ranges within the date range.
  */
 export const getAvailableRangesFromSchedule = (schedule, startDate, endDate) => {
     const ranges = [];
@@ -11,6 +21,15 @@ export const getAvailableRangesFromSchedule = (schedule, startDate, endDate) =>
     while (isSameDateOrBefore(currentDate, endDate)) {
         const weekday = getWeekdayFromDate(currentDate);
         const { rules } = getApplicableRuleForDate(schedule, currentDate);
+        // If weekly is true, the entire day is available
+        if (rules === true) {
+            ranges.push({
+                from: getTimestampFromDateAndTime(currentDate, '00:00'),
+                to: getTimestampFromDateAndTime(currentDate, '23:59'),
+            });
+            currentDate = addDaysToDate(currentDate, 1);
+            continue;
+        }
         // Find all time ranges for this day
         for (const rule of rules) {
             // Skip if this weekday is not in the rule

package/dist/getNextAvailableFromSchedule.d.ts

@@ -6,6 +6,7 @@ import type { Schedule } from './types.js';
  *
  * This function searches forward from the given timestamp to find when the
  * schedule next becomes available. It handles:
+ * - Always-available days (`weekly: true` or `rules: true` from an override)
  * - Same-day availability (finding the next time range on the current day)
  * - Cross-midnight spillover (ranges that extend past midnight are detected
  *   via isScheduleAvailable)
@@ -15,8 +16,9 @@ import type { Schedule } from './types.js';
  * The algorithm works by:
  * 1. Checking if fromTimestamp is already available (including spillover from
  *    the previous day's cross-midnight ranges)
- * 2. If not, finding the earliest time range start on the current day that
- *    occurs after fromTimestamp
+ * 2. If not, iterating day-by-day:
+ *    - If rules are `true`, the entire day is available (returns 00:00)
+ *    - Otherwise, finding the earliest time range start after fromTimestamp
  * 3. If no ranges found on current day, moving to the next day and repeating
  *
  * Note: Spillover ranges don't need explicit tracking because:
@@ -26,12 +28,11 @@ import type { Schedule } from './types.js';
  * - The "next available" time is always a time range start, never a spillover
  *   timestamp
  *
- * @param schedule - The schedule to check availability against
- * @param fromTimestamp - The starting timestamp to search from
- * @param maxDaysToSearch - Maximum number of days to search forward (default:
- *   365)
+ * @param schedule The schedule to check availability against.
+ * @param fromTimestamp The starting timestamp to search from.
+ * @param maxDaysToSearch Maximum number of days to search forward.
  * @returns The next available timestamp, or undefined if none found within
- *   the search window
+ *   the search window.
  *
  * @example
  * // Schedule: Mon-Fri 09:00-17:00
@@ -52,4 +53,4 @@ import type { Schedule } from './types.js';
  * // Custom search window: only search 30 days ahead
  * getNextAvailableFromSchedule(schedule, timestamp, 30)
  */
-export declare const getNextAvailableFromSchedule: (schedule: Schedule, fromTimestamp: STimestamp | string, maxDaysToSearch?: number) => STimestamp | undefined;
+export declare const getNextAvailableFromSchedule: (schedule: Schedule, fromTimestamp: STimestamp | string, maxDaysToSearch: number) => STimestamp | undefined;

package/dist/getNextAvailableFromSchedule.js

@@ -7,6 +7,7 @@ import { isScheduleAvailable } from './isScheduleAvailable.js';
  *
  * This function searches forward from the given timestamp to find when the
  * schedule next becomes available. It handles:
+ * - Always-available days (`weekly: true` or `rules: true` from an override)
  * - Same-day availability (finding the next time range on the current day)
  * - Cross-midnight spillover (ranges that extend past midnight are detected
  *   via isScheduleAvailable)
@@ -16,8 +17,9 @@ import { isScheduleAvailable } from './isScheduleAvailable.js';
  * The algorithm works by:
  * 1. Checking if fromTimestamp is already available (including spillover from
  *    the previous day's cross-midnight ranges)
- * 2. If not, finding the earliest time range start on the current day that
- *    occurs after fromTimestamp
+ * 2. If not, iterating day-by-day:
+ *    - If rules are `true`, the entire day is available (returns 00:00)
+ *    - Otherwise, finding the earliest time range start after fromTimestamp
  * 3. If no ranges found on current day, moving to the next day and repeating
  *
  * Note: Spillover ranges don't need explicit tracking because:
@@ -27,12 +29,11 @@ import { isScheduleAvailable } from './isScheduleAvailable.js';
  * - The "next available" time is always a time range start, never a spillover
  *   timestamp
  *
- * @param schedule - The schedule to check availability against
- * @param fromTimestamp - The starting timestamp to search from
- * @param maxDaysToSearch - Maximum number of days to search forward (default:
- *   365)
+ * @param schedule The schedule to check availability against.
+ * @param fromTimestamp The starting timestamp to search from.
+ * @param maxDaysToSearch Maximum number of days to search forward.
  * @returns The next available timestamp, or undefined if none found within
- *   the search window
+ *   the search window.
  *
  * @example
  * // Schedule: Mon-Fri 09:00-17:00
@@ -53,7 +54,7 @@ import { isScheduleAvailable } from './isScheduleAvailable.js';
  * // Custom search window: only search 30 days ahead
  * getNextAvailableFromSchedule(schedule, timestamp, 30)
  */
-export const getNextAvailableFromSchedule = (schedule, fromTimestamp, maxDaysToSearch = 365) => {
+export const getNextAvailableFromSchedule = (schedule, fromTimestamp, maxDaysToSearch) => {
     const initialTimestamp = sTimestamp(fromTimestamp);
     // Check if already available at fromTimestamp (handles spillover too)
     if (isScheduleAvailable(schedule, initialTimestamp)) {
@@ -65,6 +66,11 @@ export const getNextAvailableFromSchedule = (schedule, fromTimestamp, maxDaysToS
     for (let day = 0; day < maxDaysToSearch; day++) {
         const weekday = getWeekdayFromDate(currentDate);
         const { rules } = getApplicableRuleForDate(schedule, currentDate.date);
+        // If rules are true, the entire day is available. This only happens on
+        // day 1+ because on day 0, isScheduleAvailable would have returned true.
+        if (rules === true) {
+            return getTimestampFromDateAndTime(currentDate, '00:00');
+        }
         // Track earliest time
         let earliestTime;
         for (const rule of rules) {

package/dist/getNextUnavailableFromSchedule.d.ts

@@ -6,25 +6,30 @@ import type { Schedule } from './types.js';
  *
  * This function searches forward from the given timestamp to find when the
  * schedule next becomes unavailable. It handles:
+ * - Always-available schedules (`weekly: true`) by searching for overrides
  * - Same-day unavailability (gaps between time ranges or after the last range)
  * - Cross-midnight ranges (unavailability after a range that crosses midnight)
  * - Date overrides (temporary closures)
  *
  * The algorithm works by:
  * 1. Checking if fromTimestamp is already unavailable
- * 2. Collecting all potential "end of availability" candidates from:
+ * 2. If `weekly` is `true`, searching forward day-by-day for an override that
+ *    closes availability
+ * 3. Otherwise, collecting all potential "end of availability" candidates from:
  *    - Previous day's cross-midnight spillover (ends today at `to` time)
  *    - Current day's regular ranges (end today at `to` time)
  *    - Current day's cross-midnight ranges (end tomorrow at `to` time)
- * 3. Sorting candidates and returning the earliest one that's unavailable
+ * 4. Sorting candidates and returning the earliest one that's unavailable
  *
- * Note: No day-by-day iteration is needed because if we're available, we must
- * be in some range, and that range ends within at most 24 hours (or ~48 hours
- * for cross-midnight ranges).
+ * Note: For rule-based schedules, no day-by-day iteration is needed because if
+ * available, the current range ends within at most ~48 hours (cross-midnight).
  *
- * @param schedule - The schedule to check availability against
- * @param fromTimestamp - The starting timestamp to search from
- * @returns The next unavailable timestamp, or undefined if always available
+ * @param schedule The schedule to check availability against.
+ * @param timeZone IANA time zone identifier for timestamp arithmetic.
+ * @param fromTimestamp The starting timestamp to search from.
+ * @param maxDaysToSearch Maximum number of days to search forward.
+ * @returns The next unavailable timestamp, or undefined if no unavailability
+ *   is found within the search window.
  *
  * @example
  * // Schedule: Mon-Fri 09:00-17:00
@@ -40,5 +45,10 @@ import type { Schedule } from './types.js';
  * // Schedule: Thu-Sat 20:00-02:00 (cross-midnight)
  * // Query: Thursday at 23:00
  * // Returns: Friday at 02:01 (after shift ends)
+ *
+ * @example
+ * // Schedule: weekly: true, override closing Dec 25
+ * // Query: Dec 20 at 10:00
+ * // Returns: Dec 25 at 00:00
  */
-export declare const getNextUnavailableFromSchedule: (schedule: Schedule, fromTimestamp: STimestamp | string) => STimestamp | undefined;
+export declare const getNextUnavailableFromSchedule: (schedule: Schedule, timeZone: string, fromTimestamp: STimestamp | string, maxDaysToSearch: number) => STimestamp | undefined;