scschedule 2.0.2 → 2.1.1

package/dist/types.d.ts

@@ -0,0 +1,268 @@
+import type { SDate, STime, STimestamp, SWeekdays, Weekday } from 'scdate';
+import { RuleLocationType, ValidationIssue } from './constants.js';
+/**
+ * String in YYYY-MM-DD format representing a date.
+ */
+export type SDateString = string;
+/**
+ * String in HH:MM format representing a time.
+ */
+export type STimeString = string;
+/**
+ * String in YYYY-MM-DDTHH:MM format representing a timestamp.
+ */
+export type STimestampString = string;
+/**
+ * String in SMTWTFS format representing weekdays.
+ */
+export type SWeekdaysString = string;
+/**
+ * Represents a time range within a day. Time ranges can cross midnight. For
+ * example, a range from 20:00 to 02:00 represents 8:00 PM to 2:00 AM the next
+ * day.
+ */
+export interface TimeRange {
+    /** Start time of the range (inclusive) */
+    from: STime | STimeString;
+    /** End time of the range (inclusive) */
+    to: STime | STimeString;
+}
+/**
+ * Defines a recurring weekly availability pattern. Specifies which days of the
+ * week are available and what time ranges apply on those days.
+ */
+export interface WeeklyScheduleRule {
+    /** Days of the week this rule applies to */
+    weekdays: SWeekdays | SWeekdaysString;
+    /**
+     * Time ranges when available on the specified weekdays. Empty array means
+     * unavailable on these days.
+     */
+    times: TimeRange[];
+}
+/**
+ * Defines a date-specific override to the weekly schedule. Overrides apply to
+ * a date range and replace the weekly schedule for those dates. If `to` is
+ * omitted, the override applies indefinitely from the `from` date forward.
+ */
+export interface OverrideScheduleRule {
+    /** Start date of the override (inclusive) */
+    from: SDate | SDateString;
+    /**
+     * End date of the override (inclusive). If omitted, the override applies
+     * indefinitely from the `from` date.
+     */
+    to?: SDate | SDateString;
+    /**
+     * Weekly schedule rules that apply during this override period. Empty array
+     * means unavailable for the entire period.
+     */
+    rules: WeeklyScheduleRule[];
+}
+/**
+ * Represents a complete availability schedule. A schedule consists of a
+ * timezone for all date/time operations, base weekly recurring patterns, and
+ * optional date-specific overrides. Priority order for determining
+ * availability: 1. Specific override (with both from and to dates) 2.
+ * Indefinite override (with only from date) 3. Weekly schedule
+ */
+export interface Schedule {
+    /**
+     * IANA timezone identifier (e.g., 'America/New_York', 'Europe/London'). Must
+     * be in `Intl.supportedValuesOf('timeZone')`.
+     */
+    timezone: string;
+    /** Base recurring weekly schedule patterns */
+    weekly: WeeklyScheduleRule[];
+    /**
+     * Date-specific exceptions to the weekly schedule. Overrides take precedence
+     * over weekly rules.
+     */
+    overrides?: OverrideScheduleRule[];
+}
+/**
+ * Represents a continuous period of availability.
+ */
+export interface AvailabilityRange {
+    /** Start of the availability period (inclusive) */
+    from: STimestamp | STimestampString;
+    /** End of the availability period (inclusive) */
+    to: STimestamp | STimestampString;
+}
+/**
+ * Discriminated union of all possible validation errors. Each error type
+ * includes specific metadata about what failed validation. Use the `issue`
+ * property to narrow the type and access error-specific fields.
+ */
+export type ValidationError = {
+    /** The timezone string is not a valid IANA timezone identifier */
+    issue: ValidationIssue.InvalidTimezone;
+    /** The invalid timezone string that was provided */
+    timezone: string;
+} | {
+    /** Two or more specific overrides have identical date ranges */
+    issue: ValidationIssue.DuplicateOverrides;
+    /** Indexes of the two duplicate overrides */
+    overrideIndexes: [number, number];
+} | {
+    /** Two or more specific overrides have overlapping date ranges */
+    issue: ValidationIssue.OverlappingSpecificOverrides;
+    /** Indexes of the two overlapping overrides */
+    overrideIndexes: [number, number];
+} | {
+    /** Time ranges within a single rule overlap with each other */
+    issue: ValidationIssue.OverlappingTimesInRule;
+    /** Location of the rule containing overlapping times */
+    location: {
+        type: RuleLocationType.Weekly;
+        ruleIndex: number;
+    } | {
+        type: RuleLocationType.Override;
+        overrideIndex: number;
+        ruleIndex: number;
+    };
+    /** Indexes of the two overlapping time ranges within the rule */
+    timeRangeIndexes: [number, number];
+} | {
+    /**
+     * A rule has an empty times array
+     * (should have at least one time range or be removed)
+     */
+    issue: ValidationIssue.EmptyTimes;
+    /** Location of the rule with empty times */
+    location: {
+        type: RuleLocationType.Weekly;
+        ruleIndex: number;
+    } | {
+        type: RuleLocationType.Override;
+        overrideIndex: number;
+        ruleIndex: number;
+    };
+} | {
+    /**
+     * A field contains an invalid scdate format
+     * (SDate, STime, SWeekdays, or STimestamp)
+     */
+    issue: ValidationIssue.InvalidScDateFormat;
+    /** Path to the field with invalid format (e.g., 'weekly[0].weekdays') */
+    field: string;
+    /** The invalid value that was provided */
+    value: string;
+    /** The expected format (e.g., 'SMTWTFS', 'HH:MM', 'YYYY-MM-DD') */
+    expectedFormat: string;
+} | {
+    /**
+     * A rule has a weekdays pattern with no days selected (e.g., '-------')
+     */
+    issue: ValidationIssue.EmptyWeekdays;
+    /** Location of the rule with empty weekdays */
+    location: {
+        type: RuleLocationType.Weekly;
+        ruleIndex: number;
+    } | {
+        type: RuleLocationType.Override;
+        overrideIndex: number;
+        ruleIndex: number;
+    };
+} | {
+    /**
+     * An override has weekdays that don't match any actual dates in the
+     * override's date range
+     */
+    issue: ValidationIssue.OverrideWeekdaysMismatch;
+    /** Index of the override with the mismatch */
+    overrideIndex: number;
+    /** Index of the rule within the override */
+    ruleIndex: number;
+    /** The weekdays pattern that doesn't match */
+    weekdays: string;
+    /** The date range of the override */
+    dateRange: {
+        from: string;
+        to: string;
+    };
+} | {
+    /**
+     * Two or more rules in the weekly schedule have overlapping weekdays and
+     * time ranges
+     */
+    issue: ValidationIssue.OverlappingRulesInWeekly;
+    /** Indexes of the two overlapping rules */
+    ruleIndexes: [number, number];
+    /** The weekday where the overlap occurs */
+    weekday: Weekday;
+} | {
+    /**
+     * Two or more rules within the same override have overlapping weekdays
+     * and time ranges
+     */
+    issue: ValidationIssue.OverlappingRulesInOverride;
+    /** Index of the override containing the overlapping rules */
+    overrideIndex: number;
+    /** Indexes of the two overlapping rules within the override */
+    ruleIndexes: [number, number];
+    /** The weekday where the overlap occurs */
+    weekday: Weekday;
+} | {
+    /**
+     * Cross-midnight spillover (from weekly rule or previous override)
+     * conflicts with override's first day time ranges
+     */
+    issue: ValidationIssue.SpilloverConflictIntoOverrideFirstDay;
+    /** Index of the override whose first day has the conflict */
+    overrideIndex: number;
+    /** The first date of the override where conflict occurs */
+    date: string;
+    /** The override rule index being conflicted with */
+    overrideRuleIndex: number;
+    /**
+     * The source of spillover (weekly rule or previous override). If
+     * sourceOverrideIndex is undefined, it's a weekly rule.
+     */
+    sourceWeeklyRuleIndex?: number;
+    sourceOverrideIndex?: number;
+    sourceOverrideRuleIndex?: number;
+} | {
+    /**
+     * Cross-midnight spillover from override's last day conflicts with next
+     * day's time ranges
+     */
+    issue: ValidationIssue.SpilloverConflictOverrideIntoNext;
+    /** Index of the override whose last day causes spillover */
+    overrideIndex: number;
+    /** The last date of the override causing spillover */
+    date: string;
+    /** The override rule index causing the spillover */
+    overrideRuleIndex: number;
+    /**
+     * The next day's rule that conflicts (weekly or another override). If
+     * nextDayOverrideIndex is undefined, it's a weekly rule.
+     */
+    nextDayWeeklyRuleIndex?: number;
+    nextDayOverrideIndex?: number;
+    nextDayOverrideRuleIndex?: number;
+} | {
+    /**
+     * An override has a 'to' date that is before the 'from' date
+     */
+    issue: ValidationIssue.InvalidOverrideDateOrder;
+    /** Index of the override with invalid date order */
+    overrideIndex: number;
+    /** The from date */
+    from: string;
+    /** The to date that is before from */
+    to: string;
+};
+/**
+ * Result of validating a schedule. Contains a boolean flag indicating validity
+ * and an array of specific errors if validation failed.
+ */
+export interface ValidationResult {
+    /** True if the schedule passed all validation checks */
+    valid: boolean;
+    /**
+     * Array of validation errors. Empty if valid is true. Each error includes
+     * specific details about what failed.
+     */
+    errors: ValidationError[];
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/validateSchedule.d.ts

@@ -0,0 +1,15 @@
+import type { Schedule, ValidationResult } from './types.js';
+/**
+ * Validates a schedule configuration and returns all validation errors found.
+ *
+ * Validation is performed in two phases:
+ * 1. Structural validation (timezone, formats, date order, empty weekdays,
+ *    non-empty times, weekday-date mismatch) - runs on original schedule
+ * 2. Semantic validation (overlaps, conflicts) - runs on normalized schedule
+ *    after filtering weekdays to actual dates
+ *
+ * If structural errors are found, validation stops early and returns only
+ * those errors. This provides better user experience and avoids crashes from
+ * invalid data during normalization.
+ */
+export declare const validateSchedule: (schedule: Schedule) => ValidationResult;

package/dist/validateSchedule.js

@@ -0,0 +1,57 @@
+import { normalizeScheduleForValidation } from './internal/normalizeScheduleForValidation.js';
+import { validateNoEmptyWeekdays } from './internal/validateNoEmptyWeekdays.js';
+import { validateNoOverlappingOverrides } from './internal/validateNoOverlappingOverrides.js';
+import { validateNoOverlappingRules } from './internal/validateNoOverlappingRules.js';
+import { validateNoOverlappingTimesInRule } from './internal/validateNoOverlappingTimesInRule.js';
+import { validateNoSpilloverConflictsAtOverrideBoundaries } from './internal/validateNoSpilloverConflictsAtOverrideBoundaries.js';
+import { validateNonEmptyTimes } from './internal/validateNonEmptyTimes.js';
+import { validateOverrideDateOrder } from './internal/validateOverrideDateOrder.js';
+import { validateOverrideWeekdaysMatchDates } from './internal/validateOverrideWeekdaysMatchDates.js';
+import { validateScDateFormats } from './internal/validateScDateFormats.js';
+import { validateTimezone } from './internal/validateTimezone.js';
+/**
+ * Validates a schedule configuration and returns all validation errors found.
+ *
+ * Validation is performed in two phases:
+ * 1. Structural validation (timezone, formats, date order, empty weekdays,
+ *    non-empty times, weekday-date mismatch) - runs on original schedule
+ * 2. Semantic validation (overlaps, conflicts) - runs on normalized schedule
+ *    after filtering weekdays to actual dates
+ *
+ * If structural errors are found, validation stops early and returns only
+ * those errors. This provides better user experience and avoids crashes from
+ * invalid data during normalization.
+ */
+export const validateSchedule = (schedule) => {
+    // Phase 1: Structural validation
+    // Note: Order matters - date formats and order must be validated before
+    // weekday matching (which calls filterWeekdaysForDates)
+    const structuralErrors = [
+        ...validateTimezone(schedule),
+        ...validateScDateFormats(schedule),
+        ...validateOverrideDateOrder(schedule),
+        ...validateNoEmptyWeekdays(schedule),
+        ...validateNonEmptyTimes(schedule),
+        ...validateOverrideWeekdaysMatchDates(schedule),
+    ];
+    // Return immediately if structural errors exist
+    if (structuralErrors.length > 0) {
+        return {
+            valid: false,
+            errors: structuralErrors,
+        };
+    }
+    // Phase 2: Normalize - filter override weekdays to actual dates in range
+    const normalizedSchedule = normalizeScheduleForValidation(schedule);
+    // Phase 3: Semantic validation on normalized schedule
+    const semanticErrors = [
+        ...validateNoOverlappingOverrides(normalizedSchedule),
+        ...validateNoOverlappingTimesInRule(normalizedSchedule),
+        ...validateNoOverlappingRules(normalizedSchedule),
+        ...validateNoSpilloverConflictsAtOverrideBoundaries(normalizedSchedule),
+    ];
+    return {
+        valid: semanticErrors.length === 0,
+        errors: semanticErrors,
+    };
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scschedule",
-  "version": "2.0.2",
+  "version": "2.1.1",
   "type": "module",
   "exports": {
     ".": "./dist/index.js"
@@ -20,16 +20,16 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "scdate": "2.0.2"
+    "scdate": "2.1.1"
   },
   "devDependencies": {
-    "@eslint/js": "^9.39.1",
+    "@eslint/js": "^9.39.2",
     "@tsconfig/strictest": "^2.0.8",
-    "@types/node": "^24.10.1",
-    "eslint": "^9.39.1",
+    "@types/node": "^24.10.13",
+    "eslint": "^9.39.2",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.46.4",
-    "vitest": "^4.0.9"
+    "typescript-eslint": "^8.55.0",
+    "vitest": "^4.0.18"
   },
   "repository": {
     "type": "git",

package/dist/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,WAAW,eAAe,CAAA"}

package/dist/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,qCAAqC;AACrC,MAAM,CAAC,MAAM,WAAW,GAAG,YAAY,CAAA"}