scschedule 2.1.1 → 3.1.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,13 +46,13 @@ 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
-      times: [{ from: sTime('11:00'), to: sTime('22:00') }],
+      weekdays: sWeekdays('-MTWTFS'), // Mon-Sat
+      from: sTime('11:00'),
+      to: sTime('22:00'),
     },
   ],
 }
@@ -68,8 +68,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 +81,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[]
 }
 ```
@@ -100,10 +98,6 @@ Define recurring availability patterns for specific days of the week:
 ```typescript
 interface WeeklyScheduleRule {
   weekdays: SWeekdays // e.g., 'SMTWTFS' or '-MTWTF-'
-  times: TimeRange[] // Array of time ranges
-}
-
-interface TimeRange {
   from: STime // e.g., '09:00'
   to: STime // e.g., '17:00'
 }
@@ -139,6 +133,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 +156,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 +169,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 +213,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,11 +272,11 @@ import { Schedule } from 'scschedule'
 import { sTime, sWeekdays } from 'scdate'
 
 const restaurant: Schedule = {
-  timezone: 'America/Puerto_Rico',
   weekly: [
     {
-      weekdays: sWeekdays('-MTWTFS'), // Tue-Sat
-      times: [{ from: sTime('11:00'), to: sTime('22:00') }],
+      weekdays: sWeekdays('-MTWTFS'), // Mon-Sat
+      from: sTime('11:00'),
+      to: sTime('22:00'),
     },
   ],
 }
@@ -276,14 +286,16 @@ const restaurant: Schedule = {
 
 ```typescript
 const restaurant: Schedule = {
-  timezone: 'America/Puerto_Rico',
   weekly: [
     {
-      weekdays: sWeekdays('-MTWTFS'), // Tue-Sat
-      times: [
-        { from: sTime('11:00'), to: sTime('14:00') }, // Lunch
-        { from: sTime('17:00'), to: sTime('22:00') }, // Dinner
-      ],
+      weekdays: sWeekdays('-MTWTFS'), // Mon-Sat
+      from: sTime('11:00'),
+      to: sTime('14:00'), // Lunch
+    },
+    {
+      weekdays: sWeekdays('-MTWTFS'), // Mon-Sat
+      from: sTime('17:00'),
+      to: sTime('22:00'), // Dinner
     },
   ],
 }
@@ -293,17 +305,18 @@ const restaurant: Schedule = {
 
 ```typescript
 const restaurant: Schedule = {
-  timezone: 'America/Puerto_Rico',
   weekly: [
     {
       // Weekdays: longer hours
       weekdays: sWeekdays('-MTWTF-'), // Mon-Fri
-      times: [{ from: sTime('10:00'), to: sTime('23:00') }],
+      from: sTime('10:00'),
+      to: sTime('23:00'),
     },
     {
       // Weekends: shorter hours
       weekdays: sWeekdays('S-----S'), // Sat-Sun
-      times: [{ from: sTime('12:00'), to: sTime('20:00') }],
+      from: sTime('12:00'),
+      to: sTime('20:00'),
     },
   ],
 }
@@ -338,7 +351,8 @@ const withExtendedHours: Schedule = {
         {
           // Extended hours for December, weekends only
           weekdays: sWeekdays('S-----S'),
-          times: [{ from: sTime('08:00'), to: sTime('23:00') }],
+          from: sTime('08:00'),
+          to: sTime('23:00'),
         },
       ],
     },
@@ -359,7 +373,8 @@ const newSchedule: Schedule = {
       rules: [
         {
           weekdays: sWeekdays('SMTWTFS'), // All days
-          times: [{ from: sTime('09:00'), to: sTime('21:00') }],
+          from: sTime('09:00'),
+          to: sTime('21:00'),
         },
       ],
     },
@@ -371,11 +386,11 @@ const newSchedule: Schedule = {
 
 ```typescript
 const lateNightBar: Schedule = {
-  timezone: 'America/Puerto_Rico',
   weekly: [
     {
       weekdays: sWeekdays('----TFS'), // Thu-Sat
-      times: [{ from: sTime('20:00'), to: sTime('03:00') }], // 8PM-3AM
+      from: sTime('20:00'),
+      to: sTime('03:00'), // 8PM-3AM
     },
   ],
 }
@@ -386,16 +401,67 @@ 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'),
+          from: sTime('10:00'),
+          to: sTime('18:00'),
+        },
+      ],
+    },
+  ],
+}
+```
+
 ### Multiple Schedules (Layered Availability)
 
 ```typescript
 import { isScheduleAvailable } from 'scschedule'
 
 const businessHours: Schedule = {
-  /* ... */
+  weekly: [
+    {
+      weekdays: sWeekdays('-MTWTFS'),
+      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 +477,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
@@ -423,31 +497,15 @@ type ValidationError =
       overrideIndexes: [number, number]
     }
   | {
-      issue: ValidationIssue.OverlappingTimesInRule
-      location:
-        | { type: RuleLocationType.Weekly; ruleIndex: number }
-        | {
-            type: RuleLocationType.Override
-            overrideIndex: number
-            ruleIndex: number
-          }
-      timeRangeIndexes: [number, number]
-    }
-  | {
-      issue: ValidationIssue.EmptyTimes
-      location:
-        | { type: RuleLocationType.Weekly; ruleIndex: number }
-        | {
-            type: RuleLocationType.Override
-            overrideIndex: number
-            ruleIndex: number
-          }
+      issue: ValidationIssue.OverlappingRulesInWeekly
+      ruleIndexes: [number, number]
+      weekday: Weekday
     }
   | {
-      issue: ValidationIssue.InvalidScDateFormat
-      field: string
-      value: string
-      expectedFormat: string
+      issue: ValidationIssue.OverlappingRulesInOverride
+      overrideIndex: number
+      ruleIndexes: [number, number]
+      weekday: Weekday
     }
   | {
       issue: ValidationIssue.EmptyWeekdays
@@ -466,6 +524,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 +551,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
 
@@ -501,11 +577,22 @@ import type {
   Schedule,
   WeeklyScheduleRule,
   OverrideScheduleRule,
-  TimeRange,
   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,19 +4,10 @@
  * 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 */
     OverlappingSpecificOverrides = "overlapping-specific-overrides",
-    /** Time ranges within a single rule overlap with each other */
-    OverlappingTimesInRule = "overlapping-times-in-rule",
-    /**
-     * A rule has an empty times array (should have at least one time range or be
-     * removed)
-     */
-    EmptyTimes = "empty-times",
     /**
      * A field contains an invalid scdate format (SDate, STime, SWeekdays, or
      * STimestamp)
@@ -49,7 +40,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,19 +5,10 @@
  */
 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 */
     ValidationIssue["OverlappingSpecificOverrides"] = "overlapping-specific-overrides";
-    /** Time ranges within a single rule overlap with each other */
-    ValidationIssue["OverlappingTimesInRule"] = "overlapping-times-in-rule";
-    /**
-     * A rule has an empty times array (should have at least one time range or be
-     * removed)
-     */
-    ValidationIssue["EmptyTimes"] = "empty-times";
     /**
      * A field contains an invalid scdate format (SDate, STime, SWeekdays, or
      * STimestamp)
@@ -50,7 +41,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,25 +21,31 @@ 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
             if (!doesWeekdaysIncludeWeekday(rule.weekdays, weekday)) {
                 continue;
             }
-            // Process each time range
-            for (const timeRange of rule.times) {
-                // Handle cross-midnight ranges (from > to means it crosses midnight)
-                const isCrossMidnight = isAfterTime(timeRange.from, timeRange.to);
-                const rangeStart = getTimestampFromDateAndTime(currentDate, timeRange.from);
-                const rangeEnd = isCrossMidnight
-                    ? getTimestampFromDateAndTime(addDaysToDate(currentDate, 1), timeRange.to)
-                    : getTimestampFromDateAndTime(currentDate, timeRange.to);
-                ranges.push({
-                    from: rangeStart,
-                    to: rangeEnd,
-                });
-            }
+            // Handle cross-midnight ranges (from > to means it crosses midnight)
+            const isCrossMidnight = isAfterTime(rule.from, rule.to);
+            const rangeStart = getTimestampFromDateAndTime(currentDate, rule.from);
+            const rangeEnd = isCrossMidnight
+                ? getTimestampFromDateAndTime(addDaysToDate(currentDate, 1), rule.to)
+                : getTimestampFromDateAndTime(currentDate, rule.to);
+            ranges.push({
+                from: rangeStart,
+                to: rangeEnd,
+            });
         }
         // Move to the next day
         currentDate = addDaysToDate(currentDate, 1);

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;