scschedule 2.0.2 → 2.1.0

package/README.md

@@ -1,24 +1,33 @@
 # scschedule
 
-**Schedule management utilities**
+**Schedule management library for time-based availability patterns**
 
 [![github license](https://img.shields.io/github/license/ericvera/scdate.svg?style=flat-square)](https://github.com/ericvera/scdate/blob/master/LICENSE)
 [![npm version](https://img.shields.io/npm/v/scschedule.svg?style=flat-square)](https://npmjs.org/package/scschedule)
 
+## Overview
+
+scschedule is a TypeScript library for managing time-based availability patterns. Built on top of [scdate](https://npmjs.org/package/scdate) for consistent date/time handling, it provides a powerful yet simple way to define and query when entities are available or unavailable using recurring patterns and date-specific overrides.
+
+**Use cases**: Business hours, resource availability, service windows, time-restricted access control, scheduling systems, and any application that needs to determine availability based on time patterns.
+
 ## Features
 
-- 🔧 Built on top of scdate for robust date/time handling
-- 📅 Schedule management utilities
-- ✅ Full TypeScript support
-- 📦 Zero runtime overhead
-- 🔒 Immutable data structures
+- **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
+- **DST handling**: Properly handles daylight saving time transitions
+- **Immutable**: All operations return new instances
+- **Type-safe validation**: Discriminated union errors with detailed information
+- **Tree-shakeable**: Each function in its own file for optimal bundling
 
 ## Installation
 
 ```bash
-npm install scschedule
+npm install scschedule scdate
 # or
-yarn add scschedule
+yarn add scschedule scdate
 ```
 
 ## Requirements
@@ -26,9 +35,478 @@ yarn add scschedule
 - Node.js >= 22
 - TypeScript >= 5.0 (for TypeScript users)
 
-## Documentation
+## Quick Start
+
+```typescript
+import {
+  Schedule,
+  isScheduleAvailable,
+  getNextAvailableFromSchedule,
+  validateSchedule,
+} from 'scschedule'
+import { sDate, sTime, sWeekdays, getTimestampNow } from 'scdate'
+
+// Define a restaurant schedule: Tuesday-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') }],
+    },
+  ],
+}
+
+// Validate the schedule
+const validation = validateSchedule(restaurant)
+if (!validation.valid) {
+  console.error('Invalid schedule:', validation.errors)
+}
+
+// Check if open now
+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)
+if (nextOpen) {
+  console.log(`Next opening: ${nextOpen.timestamp}`)
+}
+```
+
+## Core Concepts
+
+### Schedule Structure
+
+A `Schedule` consists of:
+
+- **timezone**: The timezone for all time calculations
+- **weekly**: Base recurring schedule (array of `WeeklyScheduleRule`)
+- **overrides** (optional): Date-specific exceptions (array of `OverrideScheduleRule`)
+
+```typescript
+interface Schedule {
+  timezone: string
+  weekly: WeeklyScheduleRule[]
+  overrides?: OverrideScheduleRule[]
+}
+```
+
+### Weekly Rules
+
+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'
+}
+```
+
+### Override Rules
+
+Override the weekly schedule for specific date ranges:
+
+```typescript
+interface OverrideScheduleRule {
+  from: SDate // Start date (required)
+  to?: SDate // End date (optional - if omitted, applies indefinitely)
+  rules: WeeklyScheduleRule[] // Empty array = unavailable/closed
+}
+```
+
+**Override semantics**:
+
+- **Closed for a day**: `{ from: '2025-12-25', rules: [] }` (Christmas Day)
+- **Closed indefinitely**: `{ from: '2025-12-25', rules: [] }` (no `to` date)
+- **Special hours**: Override with different weekly patterns for the date range
+
+### Rule Priority
+
+Rules are evaluated in order of priority:
+
+1. **Specific override** (with both `from` and `to`) - highest priority, shortest duration wins when multiple could apply
+2. **Indefinite override** (with only `from`, no `to`) - when multiple indefinite overrides could apply, the one with the latest `from` date wins (most recent policy)
+3. **Weekly rules** - lowest priority (base schedule)
+
+## API Reference
+
+### Validation
+
+#### `validateSchedule(schedule: Schedule): ValidationResult`
+
+Validates a schedule and returns detailed errors.
+
+```typescript
+import { validateSchedule, ValidationIssue } from 'scschedule'
+
+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}`,
+        )
+        break
+      // ... handle other error types
+    }
+  })
+}
+```
+
+**Validation checks**:
+
+- Valid timezone (in `Intl.supportedValuesOf('timeZone')`)
+- No duplicate overrides (identical from/to dates)
+- No overlapping specific overrides (hierarchical nesting allowed)
+- No overlapping time ranges within rules (same weekday)
+- All rules have at least one time range
+- Valid scdate formats (SDate, STime, SWeekdays)
+- 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
+
+#### `cleanupExpiredOverridesFromSchedule(schedule: Schedule, beforeDate: SDate | string): Schedule`
+
+Removes expired overrides (with a `to` date) that ended before a given date. Indefinite overrides (no `to` date) are never removed. Returns a new Schedule instance.
+
+```typescript
+import { cleanupExpiredOverridesFromSchedule } from 'scschedule'
+import { sDate } from 'scdate'
+
+const cleaned = cleanupExpiredOverridesFromSchedule(
+  mySchedule,
+  sDate('2025-01-01'),
+)
+```
+
+### Availability Queries
+
+#### `isScheduleAvailable(schedule: Schedule, timestamp: STimestamp | string): boolean`
+
+Check if schedule is available at a specific timestamp.
+
+```typescript
+import { isScheduleAvailable } from 'scschedule'
+import { getTimestampNow } from 'scdate'
+
+const isOpen = isScheduleAvailable(
+  restaurant,
+  getTimestampNow('America/Puerto_Rico'),
+)
+```
+
+#### `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).
+
+```typescript
+import { getNextAvailableFromSchedule } from 'scschedule'
+
+const nextOpen = getNextAvailableFromSchedule(restaurant, now)
+if (nextOpen) {
+  console.log(`Opens at: ${nextOpen.timestamp}`)
+}
+```
+
+#### `getNextUnavailableFromSchedule(schedule: Schedule, fromTimestamp: STimestamp | string): STimestamp | undefined`
+
+Find the next unavailable timestamp from a given time.
 
-Coming soon...
+```typescript
+import { getNextUnavailableFromSchedule } from 'scschedule'
+
+const nextClosed = getNextUnavailableFromSchedule(restaurant, now)
+if (nextClosed) {
+  console.log(`Closes at: ${nextClosed.timestamp}`)
+}
+```
+
+#### `getAvailableRangesFromSchedule(schedule: Schedule, startDate: SDate | string, endDate: SDate | string): AvailabilityRange[]`
+
+Get all available time ranges within a date range.
+
+```typescript
+import { getAvailableRangesFromSchedule } from 'scschedule'
+import { sDate } from 'scdate'
+
+const ranges = getAvailableRangesFromSchedule(
+  restaurant,
+  sDate('2025-11-11'),
+  sDate('2025-11-17'),
+)
+
+ranges.forEach((range) => {
+  console.log(`Available: ${range.from.timestamp} to ${range.to.timestamp}`)
+})
+```
+
+## Usage Examples
+
+### Basic Business Hours
+
+```typescript
+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') }],
+    },
+  ],
+}
+```
+
+### Split Schedules (Lunch & Dinner)
+
+```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
+      ],
+    },
+  ],
+}
+```
+
+### Different Hours for Different Days
+
+```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') }],
+    },
+    {
+      // Weekends: shorter hours
+      weekdays: sWeekdays('S-----S'), // Sat-Sun
+      times: [{ from: sTime('12:00'), to: sTime('20:00') }],
+    },
+  ],
+}
+```
+
+### Holiday Closure
+
+```typescript
+import { sDate } from 'scdate'
+
+const withHoliday: Schedule = {
+  ...restaurant,
+  overrides: [
+    {
+      from: sDate('2025-12-25'), // Christmas Day
+      rules: [], // Empty array = closed
+    },
+  ],
+}
+```
+
+### Extended Holiday Hours
+
+```typescript
+const withExtendedHours: Schedule = {
+  ...restaurant,
+  overrides: [
+    {
+      from: sDate('2025-12-01'),
+      to: sDate('2025-12-31'),
+      rules: [
+        {
+          // Extended hours for December, weekends only
+          weekdays: sWeekdays('S-----S'),
+          times: [{ from: sTime('08:00'), to: sTime('23:00') }],
+        },
+      ],
+    },
+  ],
+}
+```
+
+### Permanent Schedule Change
+
+```typescript
+const newSchedule: Schedule = {
+  ...restaurant,
+  overrides: [
+    {
+      // New schedule starting Jan 1, 2026 (indefinite)
+      from: sDate('2026-01-01'),
+      // No 'to' date = applies indefinitely
+      rules: [
+        {
+          weekdays: sWeekdays('SMTWTFS'), // All days
+          times: [{ from: sTime('09:00'), to: sTime('21:00') }],
+        },
+      ],
+    },
+  ],
+}
+```
+
+### Cross-Midnight Hours (Late Night)
+
+```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
+    },
+  ],
+}
+
+// This means:
+// - Thursday: 20:00-23:59, Friday: 00:00-03:00
+// - Friday: 20:00-23:59, Saturday: 00:00-03:00
+// - Saturday: 20:00-23:59, Sunday: 00:00-03:00
+```
+
+### Multiple Schedules (Layered Availability)
+
+```typescript
+import { isScheduleAvailable } from 'scschedule'
+
+const businessHours: Schedule = {
+  /* ... */
+}
+const breakfastMenu: Schedule = {
+  /* ... */
+}
+
+// Both must be available
+const canOrderBreakfast =
+  isScheduleAvailable(businessHours, timestamp) &&
+  isScheduleAvailable(breakfastMenu, timestamp)
+```
+
+## Validation Error Types
+
+The library uses discriminated unions for type-safe error handling:
+
+```typescript
+type ValidationError =
+  | {
+      issue: ValidationIssue.InvalidTimezone
+      timezone: string
+    }
+  | {
+      issue: ValidationIssue.DuplicateOverrides
+      overrideIndexes: [number, number]
+    }
+  | {
+      issue: ValidationIssue.OverlappingSpecificOverrides
+      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.InvalidScDateFormat
+      field: string
+      value: string
+      expectedFormat: string
+    }
+  | {
+      issue: ValidationIssue.EmptyWeekdays
+      location:
+        | { type: RuleLocationType.Weekly; ruleIndex: number }
+        | {
+            type: RuleLocationType.Override
+            overrideIndex: number
+            ruleIndex: number
+          }
+    }
+  | {
+      issue: ValidationIssue.OverrideWeekdaysMismatch
+      overrideIndex: number
+      ruleIndex: number
+      weekdays: string
+      dateRange: { from: string; to: string }
+    }
+```
+
+## Best Practices
+
+1. **Always validate schedules** before using them in production
+2. **Clean up expired overrides** periodically to keep schedules manageable
+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
+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.
+
+### Cross-Midnight Ranges
+
+Time ranges that cross midnight (e.g., `22:00-02:00`) are split internally and always spill into the next calendar day, regardless of whether that day is in the weekdays pattern.
+
+### Overlapping Overrides
+
+Specific overrides (with both `from` and `to`) cannot overlap - this is a validation error. However, indefinite overrides can coexist with each other and with future specific overrides. When multiple indefinite overrides could apply to a date, the one with the latest `from` date is used (most recent policy wins).
+
+## TypeScript Support
+
+The library is written in TypeScript and provides full type definitions. All types are exported for use in your code:
+
+```typescript
+import type {
+  Schedule,
+  WeeklyScheduleRule,
+  OverrideScheduleRule,
+  TimeRange,
+  AvailabilityRange,
+  ValidationError,
+  ValidationResult,
+} from 'scschedule'
+```
 
 ## Dependencies
 
@@ -36,6 +514,12 @@ This package depends on:
 
 - `scdate`: Core date and time handling library
 
+All of scdate's peer dependencies are also required.
+
 ## License
 
 MIT
+
+## Contributing
+
+Issues and pull requests are welcome on [GitHub](https://github.com/ericvera/scdate).

package/dist/cleanupExpiredOverridesFromSchedule.d.ts

@@ -0,0 +1,7 @@
+import { type SDate } from 'scdate';
+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).
+ */
+export declare const cleanupExpiredOverridesFromSchedule: (schedule: Schedule, beforeDate: SDate | string) => Schedule;

package/dist/cleanupExpiredOverridesFromSchedule.js

@@ -0,0 +1,29 @@
+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).
+ */
+export const cleanupExpiredOverridesFromSchedule = (schedule, beforeDate) => {
+    // If there are no overrides, return the schedule as-is
+    if (!schedule.overrides || schedule.overrides.length === 0) {
+        return schedule;
+    }
+    // Filter out overrides that have ended before the given date
+    const filteredOverrides = schedule.overrides.filter((override) => {
+        // Keep indefinite overrides (no 'to' date)
+        if (!override.to) {
+            return true;
+        }
+        // Keep overrides that end on or after beforeDate
+        return isSameDateOrAfter(override.to, beforeDate);
+    });
+    // Return new Schedule instance with filtered overrides
+    if (filteredOverrides.length === 0) {
+        const { overrides, ...rest } = schedule;
+        return rest;
+    }
+    return {
+        ...schedule,
+        overrides: filteredOverrides,
+    };
+};

package/dist/constants.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Enumeration of all possible validation issues that can occur when validating
+ * a schedule. Used in ValidationError to identify the specific type of
+ * 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)
+     */
+    InvalidScDateFormat = "invalid-scdate-format",
+    /**
+     * A rule has a weekdays pattern with no days selected (e.g., '-------')
+     */
+    EmptyWeekdays = "empty-weekdays",
+    /**
+     * An override has weekdays that don't match any actual dates in the
+     * override's date range, making it effectively closed (should use empty rules
+     * instead)
+     */
+    OverrideWeekdaysMismatch = "override-weekdays-mismatch",
+    /**
+     * Two or more rules in the weekly schedule have overlapping weekdays and
+     * time ranges
+     */
+    OverlappingRulesInWeekly = "overlapping-rules-in-weekly",
+    /**
+     * Two or more rules within the same override have overlapping weekdays and
+     * time ranges
+     */
+    OverlappingRulesInOverride = "overlapping-rules-in-override",
+    /**
+     * Cross-midnight spillover (from weekly rule or previous override) conflicts
+     * with override's first day time ranges
+     */
+    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)
+     */
+    SpilloverConflictOverrideIntoNext = "spillover-conflict-override-into-next",
+    /**
+     * An override has a 'to' date that is before the 'from' date
+     */
+    InvalidOverrideDateOrder = "invalid-override-date-order"
+}
+/**
+ * Enumeration of rule location types used in validation errors to indicate
+ * where a validation issue occurred within a schedule structure.
+ */
+export declare enum RuleLocationType {
+    /** The rule is in the weekly schedule section */
+    Weekly = "weekly",
+    /** The rule is in an override section */
+    Override = "override"
+}