scschedule 3.2.0 → 4.1.0

package/README.md

@@ -263,6 +263,19 @@ ranges.forEach((range) => {
 })
 ```
 
+#### `getApplicableRuleForDate(schedule: Schedule, date: SDate | SDateString): ApplicableRule`
+
+Returns the rules that apply for a given date, indicating whether they come from the weekly schedule or an override. When `source` is `'weekly'`, `rules` is the weekly schedule (`true` or `WeeklyScheduleRule[]`). When `source` is `'override'`, `rules` is the override's rules and `overrideIndex` identifies which override applies.
+
+```typescript
+import { getApplicableRuleForDate } from 'scschedule'
+import { sDate } from 'scdate'
+
+const result = getApplicableRuleForDate(restaurant, sDate('2025-12-15'))
+// result.source === 'weekly' | 'override'
+// result.rules === true | WeeklyScheduleRule[]
+```
+
 ## Usage Examples
 
 ### Basic Business Hours
@@ -472,13 +485,52 @@ const canOrderBreakfast =
 
 ## Validation Error Types
 
-The library uses discriminated unions for type-safe error handling:
+The library uses discriminated unions for type-safe error handling. Location types (`RuleLocation`, `FieldLocation`) provide structured data for finding and highlighting errors in the UI—no path parsing required.
+
+```typescript
+// RuleLocation - where a rule lives (used by EmptyWeekdays)
+type RuleLocation =
+  | { type: RuleLocationType.Weekly; ruleIndex: number }
+  | {
+      type: RuleLocationType.Override
+      overrideIndex: number
+      ruleIndex: number
+    }
+
+// FieldLocation - where a field lives (used by InvalidScDateFormat)
+type FieldLocation =
+  | { type: RuleLocationType.Weekly; ruleIndex: number; field: RuleField }
+  | {
+      type: RuleLocationType.Override
+      overrideIndex: number
+      field: OverrideField
+    }
+  | {
+      type: RuleLocationType.Override
+      overrideIndex: number
+      ruleIndex: number
+      field: RuleField
+    }
+
+// RuleField - rule-level fields (weekdays, from, to)
+enum RuleField {
+  Weekdays = 'weekdays',
+  From = 'from',
+  To = 'to',
+}
+
+// OverrideField - override date range fields (from, to)
+enum OverrideField {
+  From = 'from',
+  To = 'to',
+}
+```
 
 ```typescript
 type ValidationError =
   | {
       issue: ValidationIssue.InvalidScDateFormat
-      field: string
+      location: FieldLocation
       value: string
       expectedFormat: string
     }
@@ -509,13 +561,7 @@ type ValidationError =
     }
   | {
       issue: ValidationIssue.EmptyWeekdays
-      location:
-        | { type: RuleLocationType.Weekly; ruleIndex: number }
-        | {
-            type: RuleLocationType.Override
-            overrideIndex: number
-            ruleIndex: number
-          }
+      location: RuleLocation
     }
   | {
       issue: ValidationIssue.OverrideWeekdaysMismatch
@@ -574,19 +620,27 @@ The library is written in TypeScript and provides full type definitions. All typ
 
 ```typescript
 import type {
+  ApplicableRule,
   Schedule,
   WeeklyScheduleRule,
   OverrideScheduleRule,
   AvailabilityRange,
   ValidationError,
   ValidationResult,
+  RuleLocation,
+  FieldLocation,
   SDateString,
   STimeString,
   STimestampString,
   SWeekdaysString,
 } from 'scschedule'
 
-import { ValidationIssue, RuleLocationType } from 'scschedule'
+import {
+  ValidationIssue,
+  RuleLocationType,
+  RuleField,
+  OverrideField,
+} from 'scschedule'
 ```
 
 Note: The `Weekday` enum (used in some `ValidationError` variants) is exported from `scdate`, not `scschedule`:

package/dist/constants.d.ts

@@ -58,3 +58,25 @@ export declare enum RuleLocationType {
     /** The rule is in an override section */
     Override = "override"
 }
+/**
+ * Fields within a rule (weekly or override rule) that can contain scdate
+ * format values. Used in validation errors for rule-level format failures.
+ */
+export declare enum RuleField {
+    /** Days of the week (SMTWTFS format) */
+    Weekdays = "weekdays",
+    /** Start time */
+    From = "from",
+    /** End time */
+    To = "to"
+}
+/**
+ * Fields on an override's date range that can contain scdate format values.
+ * Used in validation errors for override-level format failures.
+ */
+export declare enum OverrideField {
+    /** Start date */
+    From = "from",
+    /** End date */
+    To = "to"
+}

package/dist/constants.js

@@ -60,3 +60,27 @@ export var RuleLocationType;
     /** The rule is in an override section */
     RuleLocationType["Override"] = "override";
 })(RuleLocationType || (RuleLocationType = {}));
+/**
+ * Fields within a rule (weekly or override rule) that can contain scdate
+ * format values. Used in validation errors for rule-level format failures.
+ */
+export var RuleField;
+(function (RuleField) {
+    /** Days of the week (SMTWTFS format) */
+    RuleField["Weekdays"] = "weekdays";
+    /** Start time */
+    RuleField["From"] = "from";
+    /** End time */
+    RuleField["To"] = "to";
+})(RuleField || (RuleField = {}));
+/**
+ * Fields on an override's date range that can contain scdate format values.
+ * Used in validation errors for override-level format failures.
+ */
+export var OverrideField;
+(function (OverrideField) {
+    /** Start date */
+    OverrideField["From"] = "from";
+    /** End date */
+    OverrideField["To"] = "to";
+})(OverrideField || (OverrideField = {}));

package/dist/{internal/getApplicableRuleForDate.d.ts → getApplicableRuleForDate.d.ts}

@@ -1,5 +1,5 @@
 import { SDate } from 'scdate';
-import type { Schedule, SDateString, WeeklyScheduleRule } from '../types.js';
+import type { Schedule, SDateString, WeeklyScheduleRule } from './types.js';
 export type ApplicableRule = {
     source: 'weekly';
     rules: WeeklyScheduleRule[] | true;

package/dist/getAvailableRangesFromSchedule.js

@@ -1,5 +1,5 @@
 import { addDaysToDate, doesWeekdaysIncludeWeekday, getTimestampFromDateAndTime, getWeekdayFromDate, isAfterTime, isSameDateOrBefore, } from 'scdate';
-import { getApplicableRuleForDate } from './internal/getApplicableRuleForDate.js';
+import { getApplicableRuleForDate } from './getApplicableRuleForDate.js';
 /**
  * Returns all available time ranges within a schedule for the specified
  * date range.

package/dist/getNextAvailableFromSchedule.js

@@ -1,5 +1,5 @@
 import { addDaysToDate, doesWeekdaysIncludeWeekday, getDateFromTimestamp, getTimeFromTimestamp, getTimestampFromDateAndTime, getWeekdayFromDate, isAfterTime, isBeforeTime, sTimestamp, } from 'scdate';
-import { getApplicableRuleForDate } from './internal/getApplicableRuleForDate.js';
+import { getApplicableRuleForDate } from './getApplicableRuleForDate.js';
 import { isScheduleAvailable } from './isScheduleAvailable.js';
 /**
  * Finds the next available timestamp in a schedule starting from the

package/dist/getNextUnavailableFromSchedule.js

@@ -1,5 +1,5 @@
 import { addDaysToDate, addMinutesToTimestamp, doesWeekdaysIncludeWeekday, getDateFromTimestamp, getTimeFromTimestamp, getTimestampFromDateAndTime, getWeekdayFromDate, isAfterTime, isBeforeTimestamp, isSameTimeOrAfter, sTimestamp, } from 'scdate';
-import { getApplicableRuleForDate } from './internal/getApplicableRuleForDate.js';
+import { getApplicableRuleForDate } from './getApplicableRuleForDate.js';
 import { isScheduleAvailable } from './isScheduleAvailable.js';
 /**
  * Collects "range end + 1 minute" candidate timestamps for a given date's

package/dist/index.d.ts

@@ -4,6 +4,7 @@ export * from './constants.js';
 export type * from './types.js';
 export * from './validateSchedule.js';
 export * from './cleanupExpiredOverridesFromSchedule.js';
+export * from './getApplicableRuleForDate.js';
 export * from './getAvailableRangesFromSchedule.js';
 export * from './getNextAvailableFromSchedule.js';
 export * from './getNextUnavailableFromSchedule.js';

package/dist/index.js

@@ -7,6 +7,7 @@ export * from './validateSchedule.js';
 // Export schedule management functions
 export * from './cleanupExpiredOverridesFromSchedule.js';
 // Export availability query functions
+export * from './getApplicableRuleForDate.js';
 export * from './getAvailableRangesFromSchedule.js';
 export * from './getNextAvailableFromSchedule.js';
 export * from './getNextUnavailableFromSchedule.js';

package/dist/internal/index.d.ts

@@ -2,7 +2,6 @@ export type * from './types.js';
 export * from './doOverridesOverlap.js';
 export * from './doRulesOverlap.js';
 export * from './doTimeRangesOverlap.js';
-export * from './getApplicableRuleForDate.js';
 export * from './getEffectiveTimesForWeekday.js';
 export * from './isTimeInTimeRange.js';
 export * from './normalizeScheduleForValidation.js';

package/dist/internal/index.js

@@ -2,7 +2,6 @@
 export * from './doOverridesOverlap.js';
 export * from './doRulesOverlap.js';
 export * from './doTimeRangesOverlap.js';
-export * from './getApplicableRuleForDate.js';
 export * from './getEffectiveTimesForWeekday.js';
 export * from './isTimeInTimeRange.js';
 export * from './normalizeScheduleForValidation.js';

package/dist/internal/validateNoSpilloverConflictsAtOverrideBoundaries.js

@@ -1,7 +1,7 @@
 import { addDaysToDate, doesWeekdaysIncludeWeekday, getWeekdayFromDate, sDate, } from 'scdate';
 import { ValidationIssue } from '../constants.js';
 import { doTimeRangesOverlap } from './doTimeRangesOverlap.js';
-import { getApplicableRuleForDate } from './getApplicableRuleForDate.js';
+import { getApplicableRuleForDate } from '../getApplicableRuleForDate.js';
 import { splitCrossMidnightTimeRange } from './splitCrossMidnightTimeRange.js';
 /**
  * Validates that cross-midnight spillover at override boundaries doesn't

package/dist/internal/validateScDateFormats.js

@@ -1,16 +1,16 @@
 import { sDate, sTime, sWeekdays } from 'scdate';
-import { ValidationIssue } from '../constants.js';
+import { OverrideField, RuleField, RuleLocationType, ValidationIssue, } from '../constants.js';
 /**
  * Validates that a value is a valid SDate format (YYYY-MM-DD).
  */
-const validateSDateValue = (value, field) => {
+const validateSDateValue = (value, location) => {
     try {
         sDate(value);
     }
     catch {
         return {
             issue: ValidationIssue.InvalidScDateFormat,
-            field,
+            location,
             value: String(value),
             expectedFormat: 'YYYY-MM-DD',
         };
@@ -20,14 +20,14 @@ const validateSDateValue = (value, field) => {
 /**
  * Validates that a value is a valid STime format (HH:MM).
  */
-const validateSTimeValue = (value, field) => {
+const validateSTimeValue = (value, location) => {
     try {
         sTime(value);
     }
     catch {
         return {
             issue: ValidationIssue.InvalidScDateFormat,
-            field,
+            location,
             value: String(value),
             expectedFormat: 'HH:MM',
         };
@@ -37,14 +37,14 @@ const validateSTimeValue = (value, field) => {
 /**
  * Validates that a value is a valid SWeekdays format (SMTWTFS).
  */
-const validateSWeekdaysValue = (value, field) => {
+const validateSWeekdaysValue = (value, location) => {
     try {
         sWeekdays(value);
     }
     catch {
         return {
             issue: ValidationIssue.InvalidScDateFormat,
-            field,
+            location,
             value: String(value),
             expectedFormat: 'SMTWTFS',
         };
@@ -54,13 +54,19 @@ const validateSWeekdaysValue = (value, field) => {
 /**
  * Validates both from and to times in a time range.
  */
-const validateTimeRange = (timeRange, fieldPrefix) => {
+const validateTimeRange = (timeRange, locationBase) => {
     const errors = [];
-    const fromError = validateSTimeValue(timeRange.from, `${fieldPrefix}.from`);
+    const fromError = validateSTimeValue(timeRange.from, {
+        ...locationBase,
+        field: RuleField.From,
+    });
     if (fromError) {
         errors.push(fromError);
     }
-    const toError = validateSTimeValue(timeRange.to, `${fieldPrefix}.to`);
+    const toError = validateSTimeValue(timeRange.to, {
+        ...locationBase,
+        field: RuleField.To,
+    });
     if (toError) {
         errors.push(toError);
     }
@@ -69,13 +75,16 @@ const validateTimeRange = (timeRange, fieldPrefix) => {
 /**
  * Validates a rule (weekdays and time range).
  */
-const validateRule = (rule, fieldPrefix) => {
+const validateRule = (rule, locationBase) => {
     const errors = [];
-    const weekdaysError = validateSWeekdaysValue(rule.weekdays, `${fieldPrefix}.weekdays`);
+    const weekdaysError = validateSWeekdaysValue(rule.weekdays, {
+        ...locationBase,
+        field: RuleField.Weekdays,
+    });
     if (weekdaysError) {
         errors.push(weekdaysError);
     }
-    errors.push(...validateTimeRange(rule, fieldPrefix));
+    errors.push(...validateTimeRange(rule, locationBase));
     return errors;
 };
 /**
@@ -86,22 +95,37 @@ export const validateScDateFormats = (schedule) => {
     // Validate weekly rules
     const weeklyRules = schedule.weekly === true ? [] : schedule.weekly;
     weeklyRules.forEach((rule, ruleIndex) => {
-        errors.push(...validateRule(rule, `weekly[${String(ruleIndex)}]`));
+        errors.push(...validateRule(rule, {
+            type: RuleLocationType.Weekly,
+            ruleIndex,
+        }));
     });
     // Validate overrides
     schedule.overrides?.forEach((override, overrideIndex) => {
-        const fromError = validateSDateValue(override.from, `overrides[${String(overrideIndex)}].from`);
+        const fromError = validateSDateValue(override.from, {
+            type: RuleLocationType.Override,
+            overrideIndex,
+            field: OverrideField.From,
+        });
         if (fromError) {
             errors.push(fromError);
         }
         if (override.to) {
-            const toError = validateSDateValue(override.to, `overrides[${String(overrideIndex)}].to`);
+            const toError = validateSDateValue(override.to, {
+                type: RuleLocationType.Override,
+                overrideIndex,
+                field: OverrideField.To,
+            });
             if (toError) {
                 errors.push(toError);
             }
         }
         override.rules.forEach((rule, ruleIndex) => {
-            errors.push(...validateRule(rule, `overrides[${String(overrideIndex)}].rules[${String(ruleIndex)}]`));
+            errors.push(...validateRule(rule, {
+                type: RuleLocationType.Override,
+                overrideIndex,
+                ruleIndex,
+            }));
         });
     });
     return errors;

package/dist/isScheduleAvailable.js

@@ -1,5 +1,5 @@
 import { addDaysToDate, doesWeekdaysIncludeWeekday, getDateFromTimestamp, getTimeFromTimestamp, getWeekdayFromDate, } from 'scdate';
-import { getApplicableRuleForDate } from './internal/getApplicableRuleForDate.js';
+import { getApplicableRuleForDate } from './getApplicableRuleForDate.js';
 import { isTimeInTimeRange } from './internal/isTimeInTimeRange.js';
 /**
  * Checks if a schedule is available at the specified timestamp.

package/dist/types.d.ts

@@ -1,5 +1,35 @@
 import type { SDate, STime, STimestamp, SWeekdays, Weekday } from 'scdate';
-import { RuleLocationType, ValidationIssue } from './constants.js';
+import { OverrideField, RuleField, RuleLocationType, ValidationIssue } from './constants.js';
+/**
+ * Location of a rule within the schedule structure. Used by validation errors
+ * that point to a specific rule (e.g. EmptyWeekdays).
+ */
+export type RuleLocation = {
+    type: RuleLocationType.Weekly;
+    ruleIndex: number;
+} | {
+    type: RuleLocationType.Override;
+    overrideIndex: number;
+    ruleIndex: number;
+};
+/**
+ * Location of a field within the schedule structure. Used by validation errors
+ * that point to a specific field (e.g. InvalidScDateFormat).
+ */
+export type FieldLocation = {
+    type: RuleLocationType.Weekly;
+    ruleIndex: number;
+    field: RuleField;
+} | {
+    type: RuleLocationType.Override;
+    overrideIndex: number;
+    field: OverrideField;
+} | {
+    type: RuleLocationType.Override;
+    overrideIndex: number;
+    ruleIndex: number;
+    field: RuleField;
+};
 /**
  * String in YYYY-MM-DD format representing a date.
  */
@@ -98,8 +128,8 @@ export type ValidationError = {
      * (SDate, STime, SWeekdays, or STimestamp)
      */
     issue: ValidationIssue.InvalidScDateFormat;
-    /** Path to the field with invalid format (e.g., 'weekly[0].weekdays') */
-    field: string;
+    /** Location of the field with invalid format */
+    location: FieldLocation;
     /** The invalid value that was provided */
     value: string;
     /** The expected format (e.g., 'SMTWTFS', 'HH:MM', 'YYYY-MM-DD') */
@@ -110,14 +140,7 @@ export type ValidationError = {
      */
     issue: ValidationIssue.EmptyWeekdays;
     /** Location of the rule with empty weekdays */
-    location: {
-        type: RuleLocationType.Weekly;
-        ruleIndex: number;
-    } | {
-        type: RuleLocationType.Override;
-        overrideIndex: number;
-        ruleIndex: number;
-    };
+    location: RuleLocation;
 } | {
     /**
      * An override has weekdays that don't match any actual dates in the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scschedule",
-  "version": "3.2.0",
+  "version": "4.1.0",
   "type": "module",
   "exports": {
     ".": "./dist/index.js"
@@ -20,15 +20,15 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "scdate": "3.2.0"
+    "scdate": "workspace:*"
   },
   "devDependencies": {
-    "@eslint/js": "^9.39.2",
+    "@eslint/js": "^9.39.3",
     "@tsconfig/strictest": "^2.0.8",
-    "@types/node": "^24.10.13",
-    "eslint": "^9.39.2",
+    "@types/node": "^24.11.0",
+    "eslint": "^9.39.3",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.55.0",
+    "typescript-eslint": "^8.56.1",
     "vitest": "^4.0.18"
   },
   "repository": {
@@ -46,4 +46,4 @@
   "publishConfig": {
     "access": "public"
   }
-}
+}