dabke 0.78.0

package/dist/datetime.utils.d.ts

@@ -0,0 +1,245 @@
+import { CalendarDate, DateTime, DateTimeRange, DayOfWeek, SchedulingPeriod } from "./types.js";
+/**
+ * Converts a JavaScript Date to a CalendarDate
+ */
+export declare function dateToCalendarDate(date: Date): CalendarDate;
+/**
+ * Converts a DateTime to a JavaScript Date
+ * Internal helper function
+ */
+export declare function dateTimeToDate(dateTime: DateTime): Date;
+/**
+ * Compares two DateTimes
+ * Returns:
+ *  -1 if dateTime1 < dateTime2
+ *   0 if dateTime1 = dateTime2
+ *   1 if dateTime1 > dateTime2
+ */
+export declare function compareDateTimes(dateTime1: DateTime, dateTime2: DateTime): number;
+export declare const DAY_OF_WEEK_MAP: {
+    sunday: number;
+    monday: number;
+    tuesday: number;
+    wednesday: number;
+    thursday: number;
+    friday: number;
+    saturday: number;
+};
+/**
+ * Helper to get the day of week name from a Date (local time)
+ */
+export declare function toDayOfWeek(date: Date): DayOfWeek;
+/**
+ * Helper to get the day of week name from a Date (UTC)
+ * Use this when working with date strings like "2026-01-10" that are timezone-agnostic.
+ */
+export declare function toDayOfWeekUTC(date: Date): DayOfWeek;
+/**
+ * Formats a date as YYYY-MM-DD string
+ */
+export declare function formatDateString(date: Date): string;
+/**
+ * Generates an array of day strings (YYYY-MM-DD) from a time horizon.
+ *
+ * @param horizon - The time horizon with start (inclusive) and end (inclusive) dates
+ * @returns Array of day strings in YYYY-MM-DD format
+ *
+ * @example
+ * ```typescript
+ * const days = generateDays({
+ *   start: new Date('2025-01-01'),
+ *   end: new Date('2025-01-04')
+ * });
+ * // Returns: ["2025-01-01", "2025-01-02", "2025-01-03", "2025-01-04"]
+ * ```
+ */
+export declare function generateDays(horizon: {
+    start: Date;
+    end: Date;
+}): string[];
+/**
+ * Splits a time period into consecutive day ranges.
+ *
+ * Each range represents a single calendar day within the period from start to end.
+ * This is useful for rules that need to apply constraints on a per-day basis,
+ * such as maximum or minimum hours per day.
+ *
+ * @param start - The start date of the period (inclusive)
+ * @param end - The end date of the period (exclusive)
+ * @returns An array of [startDate, endDate] tuples, where each tuple represents
+ *          a single day. The last range's end date will be the provided end date.
+ *
+ * @example
+ * ```typescript
+ * const ranges = splitPeriodIntoDays({
+ *   start: new Date('2025-01-01'),
+ *   end: new Date('2025-01-03')
+ * });
+ * // Returns:
+ * // [
+ * //   [Date('2025-01-01'), Date('2025-01-02')],
+ * //   [Date('2025-01-02'), Date('2025-01-03')]
+ * // ]
+ * ```
+ */
+export declare function splitPeriodIntoDays({ start, end }: {
+    start: Date;
+    end: Date;
+}): [Date, Date][];
+/**
+ * Splits a time period into consecutive week ranges.
+ *
+ * Each range represents a week period starting on the specified day of the week.
+ * This is useful for rules that need to apply constraints on a per-week basis,
+ * such as maximum or minimum hours per week.
+ *
+ * The first range starts at the provided start date (not necessarily on weekStartsOn).
+ * Subsequent ranges align to the weekStartsOn day. The last range's end date will be
+ * the provided end date.
+ *
+ * @param start - The start date of the period (inclusive)
+ * @param end - The end date of the period (exclusive)
+ * @param weekStartsOn - The day of the week that weeks start on (e.g., "monday", "sunday")
+ * @returns An array of [startDate, endDate] tuples, where each tuple represents
+ *          a week period aligned to the specified week start day.
+ *
+ * @example
+ * ```typescript
+ * const ranges = splitPeriodIntoWeeks({
+ *   start: new Date('2025-01-01'), // Wednesday
+ *   end: new Date('2025-01-15'),
+ *   weekStartsOn: 'monday'
+ * });
+ * // Returns ranges starting from Jan 1 (Wed), then aligning to Mondays:
+ * // [
+ * //   [Date('2025-01-01 Wed'), Date('2025-01-06 Mon')],
+ * //   [Date('2025-01-06 Mon'), Date('2025-01-13 Mon')],
+ * //   [Date('2025-01-13 Mon'), Date('2025-01-15 Wed')]
+ * // ]
+ * ```
+ */
+export declare function splitPeriodIntoWeeks({ start, end, weekStartsOn, }: {
+    start: Date;
+    end: Date;
+    weekStartsOn: DayOfWeek;
+}): [Date, Date][];
+/**
+ * Checks if two DateTime ranges overlap in both date and time.
+ * Ranges overlap if they share any moment in time.
+ *
+ * Two ranges overlap if: range1.start < range2.end AND range2.start < range1.end
+ *
+ * @param range1 First time range with start (inclusive) and end (exclusive)
+ * @param range2 Second time range with start (inclusive) and end (exclusive)
+ * @returns true if ranges overlap, false otherwise
+ *
+ * @example
+ * ```typescript
+ * // Same day, overlapping times (9-17 overlaps with 12-20)
+ * dateTimeRangesOverlap(
+ *   {
+ *     start: { year: 2025, month: 6, day: 1, hours: 9, minutes: 0 },
+ *     end: { year: 2025, month: 6, day: 1, hours: 17, minutes: 0 }
+ *   },
+ *   {
+ *     start: { year: 2025, month: 6, day: 1, hours: 12, minutes: 0 },
+ *     end: { year: 2025, month: 6, day: 1, hours: 20, minutes: 0 }
+ *   }
+ * ); // true
+ *
+ * // Different days - no overlap
+ * dateTimeRangesOverlap(
+ *   {
+ *     start: { year: 2025, month: 6, day: 1, hours: 9, minutes: 0 },
+ *     end: { year: 2025, month: 6, day: 1, hours: 17, minutes: 0 }
+ *   },
+ *   {
+ *     start: { year: 2025, month: 6, day: 2, hours: 9, minutes: 0 },
+ *     end: { year: 2025, month: 6, day: 2, hours: 17, minutes: 0 }
+ *   }
+ * ); // false
+ *
+ * // Works naturally with Shift objects
+ * dateTimeRangesOverlap(
+ *   { start: shift1.startDateTime, end: shift1.endDateTime },
+ *   { start: shift2.startDateTime, end: shift2.endDateTime }
+ * );
+ * ```
+ */
+export declare function dateTimeRangesOverlap(range1: DateTimeRange, range2: DateTimeRange): boolean;
+/**
+ * Calculates the number of complete days between two dates
+ * @param start The start date
+ * @param end The end date
+ * @returns Number of complete days from start to end (can be negative if end < start)
+ *
+ * @example
+ * ```typescript
+ * daysBetween(new Date('2025-01-01'), new Date('2025-01-05')); // 4
+ * ```
+ */
+export declare function daysBetween(start: Date, end: Date): number;
+/**
+ * Adds a number of minutes to a base date and returns a DateTime.
+ * Treats the base date as a reference point (typically midnight of horizon start),
+ * and the minutes parameter as absolute minutes from that point.
+ *
+ * @param baseDate The starting date (used as reference point)
+ * @param minutes Absolute minutes from the base date
+ * @returns DateTime representing the result
+ *
+ * @example
+ * ```typescript
+ * // Add 90 minutes from midnight
+ * addMinutesToDate(new Date('2025-01-01'), 90);
+ * // Returns: { year: 2025, month: 1, day: 1, hours: 1, minutes: 30 }
+ *
+ * // Add 1500 minutes (spans to next day)
+ * addMinutesToDate(new Date('2025-01-01'), 1500);
+ * // Returns: { year: 2025, month: 1, day: 2, hours: 1, minutes: 0 }
+ * ```
+ */
+export declare function addMinutesToDate(baseDate: Date, minutes: number): DateTime;
+/**
+ * Returns the points where a range should be split, filtered to within [start, end).
+ * Always includes range start. Sorted ascending.
+ */
+export declare function splitPoints([start, end]: [number, number], splitAt: number[]): number[];
+/**
+ * Computes the list of day strings (YYYY-MM-DD) from a SchedulingPeriod.
+ *
+ * For date ranges, generates all days between start and end (inclusive),
+ * optionally filtering to specific days of the week.
+ *
+ * For specific dates, returns the dates as-is (sorted).
+ *
+ * @param period - The scheduling period specification
+ * @returns Array of day strings in YYYY-MM-DD format, sorted chronologically
+ *
+ * @example Date range with day-of-week filter
+ * ```typescript
+ * const days = resolveDaysFromPeriod({
+ *   dateRange: { start: '2025-02-03', end: '2025-02-09' },
+ *   daysOfWeek: ['wednesday', 'friday'],
+ * });
+ * // Returns: ['2025-02-05', '2025-02-07'] (Wed and Fri only)
+ * ```
+ *
+ * @example Date range without filter
+ * ```typescript
+ * const days = resolveDaysFromPeriod({
+ *   dateRange: { start: '2025-02-03', end: '2025-02-05' },
+ * });
+ * // Returns: ['2025-02-03', '2025-02-04', '2025-02-05']
+ * ```
+ *
+ * @example Specific dates
+ * ```typescript
+ * const days = resolveDaysFromPeriod({
+ *   specificDates: ['2025-02-07', '2025-02-03', '2025-02-10'],
+ * });
+ * // Returns: ['2025-02-03', '2025-02-07', '2025-02-10'] (sorted)
+ * ```
+ */
+export declare function resolveDaysFromPeriod(period: SchedulingPeriod): string[];
+//# sourceMappingURL=datetime.utils.d.ts.map

package/dist/datetime.utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"datetime.utils.d.ts","sourceRoot":"","sources":["../src/datetime.utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,aAAa,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEhG;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,IAAI,GAAG,YAAY,CAM3D;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI,CASvD;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,GAAG,MAAM,CAOjF;AAED,eAAO,MAAM,eAAe;;;;;;;;CAQ3B,CAAC;AAYF;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,IAAI,GAAG,SAAS,CAGjD;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,GAAG,SAAS,CAGpD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAKnD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE;IAAE,KAAK,EAAE,IAAI,CAAC;IAAC,GAAG,EAAE,IAAI,CAAA;CAAE,GAAG,MAAM,EAAE,CAU1E;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;IAAE,KAAK,EAAE,IAAI,CAAC;IAAC,GAAG,EAAE,IAAI,CAAA;CAAE,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,CAsB9F;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,oBAAoB,CAAC,EACnC,KAAK,EACL,GAAG,EACH,YAAY,GACb,EAAE;IACD,KAAK,EAAE,IAAI,CAAC;IACZ,GAAG,EAAE,IAAI,CAAC;IACV,YAAY,EAAE,SAAS,CAAC;CACzB,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,CAoCjB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,aAAa,GAAG,OAAO,CAM3F;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,GAAG,MAAM,CAG1D;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,GAAG,QAAQ,CAc1E;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,CAAC,KAAK,EAAE,GAAG,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAQvF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,EAAE,CA2BxE"}

package/dist/datetime.utils.js

@@ -0,0 +1,372 @@
+/**
+ * Converts a JavaScript Date to a CalendarDate
+ */
+export function dateToCalendarDate(date) {
+    return {
+        year: date.getFullYear(),
+        month: date.getMonth() + 1, // JS months are 0-indexed
+        day: date.getDate(),
+    };
+}
+/**
+ * Converts a DateTime to a JavaScript Date
+ * Internal helper function
+ */
+export function dateTimeToDate(dateTime) {
+    return new Date(dateTime.year || 0, (dateTime.month || 1) - 1, dateTime.day || 1, dateTime.hours || 0, dateTime.minutes || 0, dateTime.seconds || 0);
+}
+/**
+ * Compares two DateTimes
+ * Returns:
+ *  -1 if dateTime1 < dateTime2
+ *   0 if dateTime1 = dateTime2
+ *   1 if dateTime1 > dateTime2
+ */
+export function compareDateTimes(dateTime1, dateTime2) {
+    const date1 = dateTimeToDate(dateTime1);
+    const date2 = dateTimeToDate(dateTime2);
+    if (date1 < date2)
+        return -1;
+    if (date1 > date2)
+        return 1;
+    return 0;
+}
+export const DAY_OF_WEEK_MAP = {
+    sunday: 0, // JavaScript Date week starts on Sunday
+    monday: 1,
+    tuesday: 2,
+    wednesday: 3,
+    thursday: 4,
+    friday: 5,
+    saturday: 6,
+};
+const DAY_NAMES = [
+    "sunday",
+    "monday",
+    "tuesday",
+    "wednesday",
+    "thursday",
+    "friday",
+    "saturday",
+];
+/**
+ * Helper to get the day of week name from a Date (local time)
+ */
+export function toDayOfWeek(date) {
+    // getDay() always returns 0-6
+    return DAY_NAMES[date.getDay()];
+}
+/**
+ * Helper to get the day of week name from a Date (UTC)
+ * Use this when working with date strings like "2026-01-10" that are timezone-agnostic.
+ */
+export function toDayOfWeekUTC(date) {
+    // getUTCDay() always returns 0-6
+    return DAY_NAMES[date.getUTCDay()];
+}
+/**
+ * Formats a date as YYYY-MM-DD string
+ */
+export function formatDateString(date) {
+    const year = date.getFullYear();
+    const month = (date.getMonth() + 1).toString().padStart(2, "0");
+    const day = date.getDate().toString().padStart(2, "0");
+    return `${year}-${month}-${day}`;
+}
+/**
+ * Generates an array of day strings (YYYY-MM-DD) from a time horizon.
+ *
+ * @param horizon - The time horizon with start (inclusive) and end (inclusive) dates
+ * @returns Array of day strings in YYYY-MM-DD format
+ *
+ * @example
+ * ```typescript
+ * const days = generateDays({
+ *   start: new Date('2025-01-01'),
+ *   end: new Date('2025-01-04')
+ * });
+ * // Returns: ["2025-01-01", "2025-01-02", "2025-01-03", "2025-01-04"]
+ * ```
+ */
+export function generateDays(horizon) {
+    const days = [];
+    const current = new Date(horizon.start);
+    while (current <= horizon.end) {
+        days.push(formatDateString(current));
+        current.setDate(current.getDate() + 1);
+    }
+    return days;
+}
+/**
+ * Splits a time period into consecutive day ranges.
+ *
+ * Each range represents a single calendar day within the period from start to end.
+ * This is useful for rules that need to apply constraints on a per-day basis,
+ * such as maximum or minimum hours per day.
+ *
+ * @param start - The start date of the period (inclusive)
+ * @param end - The end date of the period (exclusive)
+ * @returns An array of [startDate, endDate] tuples, where each tuple represents
+ *          a single day. The last range's end date will be the provided end date.
+ *
+ * @example
+ * ```typescript
+ * const ranges = splitPeriodIntoDays({
+ *   start: new Date('2025-01-01'),
+ *   end: new Date('2025-01-03')
+ * });
+ * // Returns:
+ * // [
+ * //   [Date('2025-01-01'), Date('2025-01-02')],
+ * //   [Date('2025-01-02'), Date('2025-01-03')]
+ * // ]
+ * ```
+ */
+export function splitPeriodIntoDays({ start, end }) {
+    const ranges = [];
+    let leftBound = new Date(start);
+    let done = false;
+    // Loop through each day
+    leftBound = new Date(start);
+    while (!done) {
+        // Create next day date
+        let rightBound = new Date(leftBound);
+        rightBound.setDate(rightBound.getDate() + 1);
+        if (rightBound >= end) {
+            rightBound = end;
+            done = true;
+        }
+        ranges.push([leftBound, rightBound]);
+        leftBound = rightBound;
+    }
+    return ranges;
+}
+/**
+ * Splits a time period into consecutive week ranges.
+ *
+ * Each range represents a week period starting on the specified day of the week.
+ * This is useful for rules that need to apply constraints on a per-week basis,
+ * such as maximum or minimum hours per week.
+ *
+ * The first range starts at the provided start date (not necessarily on weekStartsOn).
+ * Subsequent ranges align to the weekStartsOn day. The last range's end date will be
+ * the provided end date.
+ *
+ * @param start - The start date of the period (inclusive)
+ * @param end - The end date of the period (exclusive)
+ * @param weekStartsOn - The day of the week that weeks start on (e.g., "monday", "sunday")
+ * @returns An array of [startDate, endDate] tuples, where each tuple represents
+ *          a week period aligned to the specified week start day.
+ *
+ * @example
+ * ```typescript
+ * const ranges = splitPeriodIntoWeeks({
+ *   start: new Date('2025-01-01'), // Wednesday
+ *   end: new Date('2025-01-15'),
+ *   weekStartsOn: 'monday'
+ * });
+ * // Returns ranges starting from Jan 1 (Wed), then aligning to Mondays:
+ * // [
+ * //   [Date('2025-01-01 Wed'), Date('2025-01-06 Mon')],
+ * //   [Date('2025-01-06 Mon'), Date('2025-01-13 Mon')],
+ * //   [Date('2025-01-13 Mon'), Date('2025-01-15 Wed')]
+ * // ]
+ * ```
+ */
+export function splitPeriodIntoWeeks({ start, end, weekStartsOn, }) {
+    const DAYS_OF_WEEK = [
+        "sunday",
+        "monday",
+        "tuesday",
+        "wednesday",
+        "thursday",
+        "friday",
+        "saturday",
+    ];
+    const ranges = [];
+    let leftBound = new Date(start);
+    let done = false;
+    const startDayIndex = DAYS_OF_WEEK.indexOf(weekStartsOn);
+    // Create weekly ranges
+    while (!done) {
+        const dayOfWeek = leftBound.getDay(); // 0 = Sunday, 1 = Monday, etc.
+        const daysToNextWeek = (7 - ((dayOfWeek - startDayIndex) % 7)) % 7;
+        const daysToAdd = daysToNextWeek === 0 ? 7 : daysToNextWeek;
+        let rightBound = new Date(leftBound);
+        rightBound.setDate(rightBound.getDate() + daysToAdd);
+        if (rightBound >= end) {
+            rightBound = end;
+            done = true;
+        }
+        ranges.push([leftBound, rightBound]);
+        leftBound = rightBound;
+    }
+    return ranges;
+}
+/**
+ * Checks if two DateTime ranges overlap in both date and time.
+ * Ranges overlap if they share any moment in time.
+ *
+ * Two ranges overlap if: range1.start < range2.end AND range2.start < range1.end
+ *
+ * @param range1 First time range with start (inclusive) and end (exclusive)
+ * @param range2 Second time range with start (inclusive) and end (exclusive)
+ * @returns true if ranges overlap, false otherwise
+ *
+ * @example
+ * ```typescript
+ * // Same day, overlapping times (9-17 overlaps with 12-20)
+ * dateTimeRangesOverlap(
+ *   {
+ *     start: { year: 2025, month: 6, day: 1, hours: 9, minutes: 0 },
+ *     end: { year: 2025, month: 6, day: 1, hours: 17, minutes: 0 }
+ *   },
+ *   {
+ *     start: { year: 2025, month: 6, day: 1, hours: 12, minutes: 0 },
+ *     end: { year: 2025, month: 6, day: 1, hours: 20, minutes: 0 }
+ *   }
+ * ); // true
+ *
+ * // Different days - no overlap
+ * dateTimeRangesOverlap(
+ *   {
+ *     start: { year: 2025, month: 6, day: 1, hours: 9, minutes: 0 },
+ *     end: { year: 2025, month: 6, day: 1, hours: 17, minutes: 0 }
+ *   },
+ *   {
+ *     start: { year: 2025, month: 6, day: 2, hours: 9, minutes: 0 },
+ *     end: { year: 2025, month: 6, day: 2, hours: 17, minutes: 0 }
+ *   }
+ * ); // false
+ *
+ * // Works naturally with Shift objects
+ * dateTimeRangesOverlap(
+ *   { start: shift1.startDateTime, end: shift1.endDateTime },
+ *   { start: shift2.startDateTime, end: shift2.endDateTime }
+ * );
+ * ```
+ */
+export function dateTimeRangesOverlap(range1, range2) {
+    // Use existing compareDateTimes for temporal comparison
+    // Ranges overlap if: start1 < end2 AND start2 < end1
+    return (compareDateTimes(range1.start, range2.end) < 0 && compareDateTimes(range2.start, range1.end) < 0);
+}
+/**
+ * Calculates the number of complete days between two dates
+ * @param start The start date
+ * @param end The end date
+ * @returns Number of complete days from start to end (can be negative if end < start)
+ *
+ * @example
+ * ```typescript
+ * daysBetween(new Date('2025-01-01'), new Date('2025-01-05')); // 4
+ * ```
+ */
+export function daysBetween(start, end) {
+    const ms = end.getTime() - start.getTime();
+    return Math.floor(ms / (1000 * 60 * 60 * 24));
+}
+/**
+ * Adds a number of minutes to a base date and returns a DateTime.
+ * Treats the base date as a reference point (typically midnight of horizon start),
+ * and the minutes parameter as absolute minutes from that point.
+ *
+ * @param baseDate The starting date (used as reference point)
+ * @param minutes Absolute minutes from the base date
+ * @returns DateTime representing the result
+ *
+ * @example
+ * ```typescript
+ * // Add 90 minutes from midnight
+ * addMinutesToDate(new Date('2025-01-01'), 90);
+ * // Returns: { year: 2025, month: 1, day: 1, hours: 1, minutes: 30 }
+ *
+ * // Add 1500 minutes (spans to next day)
+ * addMinutesToDate(new Date('2025-01-01'), 1500);
+ * // Returns: { year: 2025, month: 1, day: 2, hours: 1, minutes: 0 }
+ * ```
+ */
+export function addMinutesToDate(baseDate, minutes) {
+    const days = Math.floor(minutes / 1440);
+    const minutesInDay = minutes % 1440;
+    const targetDate = new Date(baseDate);
+    targetDate.setDate(targetDate.getDate() + days);
+    return {
+        year: targetDate.getFullYear(),
+        month: targetDate.getMonth() + 1,
+        day: targetDate.getDate(),
+        hours: Math.floor(minutesInDay / 60),
+        minutes: minutesInDay % 60,
+    };
+}
+/**
+ * Returns the points where a range should be split, filtered to within [start, end).
+ * Always includes range start. Sorted ascending.
+ */
+export function splitPoints([start, end], splitAt) {
+    const points = new Set([start]);
+    for (const p of splitAt) {
+        if (p > start && p < end)
+            points.add(p);
+    }
+    return [...points].toSorted((a, b) => a - b);
+}
+/**
+ * Computes the list of day strings (YYYY-MM-DD) from a SchedulingPeriod.
+ *
+ * For date ranges, generates all days between start and end (inclusive),
+ * optionally filtering to specific days of the week.
+ *
+ * For specific dates, returns the dates as-is (sorted).
+ *
+ * @param period - The scheduling period specification
+ * @returns Array of day strings in YYYY-MM-DD format, sorted chronologically
+ *
+ * @example Date range with day-of-week filter
+ * ```typescript
+ * const days = resolveDaysFromPeriod({
+ *   dateRange: { start: '2025-02-03', end: '2025-02-09' },
+ *   daysOfWeek: ['wednesday', 'friday'],
+ * });
+ * // Returns: ['2025-02-05', '2025-02-07'] (Wed and Fri only)
+ * ```
+ *
+ * @example Date range without filter
+ * ```typescript
+ * const days = resolveDaysFromPeriod({
+ *   dateRange: { start: '2025-02-03', end: '2025-02-05' },
+ * });
+ * // Returns: ['2025-02-03', '2025-02-04', '2025-02-05']
+ * ```
+ *
+ * @example Specific dates
+ * ```typescript
+ * const days = resolveDaysFromPeriod({
+ *   specificDates: ['2025-02-07', '2025-02-03', '2025-02-10'],
+ * });
+ * // Returns: ['2025-02-03', '2025-02-07', '2025-02-10'] (sorted)
+ * ```
+ */
+export function resolveDaysFromPeriod(period) {
+    if ("specificDates" in period && period.specificDates) {
+        return [...period.specificDates].toSorted();
+    }
+    const { dateRange, daysOfWeek } = period;
+    const startDate = new Date(`${dateRange.start}T00:00:00Z`);
+    const endDate = new Date(`${dateRange.end}T00:00:00Z`);
+    const allowedDays = daysOfWeek ? new Set(daysOfWeek) : null;
+    const days = [];
+    const current = new Date(startDate);
+    while (current <= endDate) {
+        const dayOfWeek = toDayOfWeekUTC(current);
+        if (!allowedDays || allowedDays.has(dayOfWeek)) {
+            const year = current.getUTCFullYear();
+            const month = (current.getUTCMonth() + 1).toString().padStart(2, "0");
+            const day = current.getUTCDate().toString().padStart(2, "0");
+            days.push(`${year}-${month}-${day}`);
+        }
+        current.setUTCDate(current.getUTCDate() + 1);
+    }
+    return days;
+}
+//# sourceMappingURL=datetime.utils.js.map

package/dist/datetime.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"datetime.utils.js","sourceRoot":"","sources":["../src/datetime.utils.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Error thrown when Google OR Tools scheduling API requests fail.
+ *
+ * Contains the HTTP status code and raw response data from the API for debugging.
+ * Common causes include infeasible constraints, invalid requests, or API unavailability.
+ */
+export declare class ORSchedulingError extends Error {
+    readonly status: number;
+    readonly data: unknown;
+    constructor(message: string, status: number, data: unknown);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,SAAgB,MAAM,EAAE,MAAM,CAAC;IAC/B,SAAgB,IAAI,EAAE,OAAO,CAAC;gBAElB,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO;CAM3D"}

package/dist/errors.js

@@ -0,0 +1,17 @@
+/**
+ * Error thrown when Google OR Tools scheduling API requests fail.
+ *
+ * Contains the HTTP status code and raw response data from the API for debugging.
+ * Common causes include infeasible constraints, invalid requests, or API unavailability.
+ */
+export class ORSchedulingError extends Error {
+    status;
+    data;
+    constructor(message, status, data) {
+        super(message);
+        this.name = "ORSchedulingError";
+        this.status = status;
+        this.data = data;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IAC1B,MAAM,CAAS;IACf,IAAI,CAAU;IAE9B,YAAY,OAAe,EAAE,MAAc,EAAE,IAAa;QACxD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;QAChC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF"}