dabke 0.81.1 → 0.83.0

package/src/datetime.utils.ts

@@ -1,48 +1,6 @@
-import { CalendarDate, DateTime, DateTimeRange, DayOfWeek, SchedulingPeriod } from "./types.js";
+import type { DayOfWeek, SchedulingPeriod } from "./types.js";
 
-/**
- * Converts a JavaScript Date to a CalendarDate
- */
-export function dateToCalendarDate(date: Date): CalendarDate {
-  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: DateTime): Date {
-  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: DateTime, dateTime2: DateTime): number {
-  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 = {
+export const DAY_OF_WEEK_MAP: Record<DayOfWeek, number> = {
   sunday: 0, // JavaScript Date week starts on Sunday
   monday: 1,
   tuesday: 2,
@@ -63,15 +21,7 @@ const DAY_NAMES = [
 ] as const;
 
 /**
- * Helper to get the day of week name from a Date (local time)
- */
-export function toDayOfWeek(date: Date): DayOfWeek {
-  // getDay() always returns 0-6
-  return DAY_NAMES[date.getDay()] as DayOfWeek;
-}
-
-/**
- * Helper to get the day of week name from a Date (UTC)
+ * 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: Date): DayOfWeek {
@@ -79,287 +29,6 @@ export function toDayOfWeekUTC(date: Date): DayOfWeek {
   return DAY_NAMES[date.getUTCDay()] as DayOfWeek;
 }
 
-/**
- * Formats a date as YYYY-MM-DD string
- */
-export function formatDateString(date: Date): string {
-  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: { start: Date; end: Date }): string[] {
-  const days: string[] = [];
-  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 }: { start: Date; end: Date }): [Date, Date][] {
-  const ranges: [Date, Date][] = [];
-
-  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,
-}: {
-  start: Date;
-  end: Date;
-  weekStartsOn: DayOfWeek;
-}): [Date, Date][] {
-  const DAYS_OF_WEEK: DayOfWeek[] = [
-    "sunday",
-    "monday",
-    "tuesday",
-    "wednesday",
-    "thursday",
-    "friday",
-    "saturday",
-  ];
-
-  const ranges: [Date, Date][] = [];
-
-  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: DateTimeRange, range2: DateTimeRange): boolean {
-  // 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: Date, end: Date): number {
-  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: Date, minutes: number): DateTime {
-  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]: [number, number], splitAt: number[]): number[] {
-  const points = new Set<number>([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.
  *

package/src/index.ts

@@ -1,15 +1,12 @@
 /**
  * Scheduling library powered by constraint programming (CP-SAT).
  *
- * Define teams, shifts, coverage, and rules declaratively. dabke compiles
- * them into a constraint model and solves for an optimized schedule.
- *
  * @remarks
  * ## Core Concepts
  *
- * **Schedule Definition**: The primary API. Small, composable functions
+ * **Schedule**: The primary API. Small, composable functions
  * ({@link time}, {@link cover}, {@link shift}, rule functions) produce a
- * complete scheduling configuration via {@link defineSchedule}. Each concept
+ * complete scheduling configuration via {@link schedule}. Each concept
  * is a single function call with full type safety.
  *
  * **Times vs Shift Patterns**: These are two distinct concepts.
@@ -28,73 +25,9 @@
  * - Scoping: apply rules globally, per person, per role, per skill, or per time period
  * - Priority: `MANDATORY` (hard constraint) vs `LOW`/`MEDIUM`/`HIGH` (soft preferences)
  *
- * **Solving**: {@link ScheduleDefinition.createSchedulerConfig} merges the
- * static definition with runtime data (members, scheduling period).
- * {@link ModelBuilder} compiles the config into a solver request;
- * {@link HttpSolverClient} sends it to the CP-SAT solver.
- *
- * @example Define a schedule
- * ```typescript
- * import {
- *   defineSchedule, t, time, cover, shift,
- *   maxHoursPerWeek, minRestBetweenShifts, timeOff,
- *   weekdays, weekend,
- * } from "dabke";
- *
- * const schedule = defineSchedule({
- *   roles: ["nurse", "doctor"],
- *   skills: ["charge_nurse"],
- *
- *   times: {
- *     morning_round: time({ startTime: t(7), endTime: t(9) }),
- *     day_ward: time({ startTime: t(7), endTime: t(15) }),
- *     night_ward: time({ startTime: t(23), endTime: t(7) }),
- *   },
- *
- *   coverage: [
- *     cover("morning_round", "doctor", 1),
- *     cover("day_ward", "nurse", 3, { dayOfWeek: weekdays }),
- *     cover("day_ward", "nurse", 2, { dayOfWeek: weekend }),
- *     cover("night_ward", "nurse", 2),
- *     cover("night_ward", "charge_nurse", 1),
- *   ],
- *
- *   shiftPatterns: [
- *     shift("day", t(7), t(15)),
- *     shift("night", t(23), t(7)),
- *   ],
- *
- *   rules: [
- *     maxHoursPerWeek(40),
- *     minRestBetweenShifts(11),
- *     timeOff({ appliesTo: "alice", dayOfWeek: weekend }),
- *   ],
- * });
- * ```
- *
- * @example Solve a schedule
- * ```typescript
- * import { ModelBuilder, HttpSolverClient, parseSolverResponse } from "dabke";
- *
- * const config = schedule.createSchedulerConfig({
- *   schedulingPeriod: {
- *     dateRange: { start: "2026-02-09", end: "2026-02-15" },
- *   },
- *   members: [
- *     { id: "alice", roles: ["nurse"], skills: ["charge_nurse"] },
- *     { id: "bob", roles: ["nurse"] },
- *     { id: "carol", roles: ["doctor"] },
- *   ],
- * });
- *
- * const builder = new ModelBuilder(config);
- * const { request, canSolve, validation } = builder.compile();
- * if (canSolve) {
- *   const client = new HttpSolverClient(fetch, "http://localhost:8080");
- *   const response = await client.solve(request);
- *   const result = parseSolverResponse(response);
- * }
- * ```
+ * **Solving**: {@link Schedule.compile} compiles the config into a
+ * solver request; {@link Schedule.solve} sends it to the CP-SAT solver
+ * and returns a {@link SolveResult}.
  *
  * @packageDocumentation
  */
@@ -103,22 +36,10 @@
 // Time primitives
 // ============================================================================
 
-export type { TimeOfDay, DayOfWeek, DateTime, SchedulingPeriod } from "./types.js";
+export type { TimeOfDay, DayOfWeek, SchedulingPeriod } from "./types.js";
 
 export { DayOfWeekSchema } from "./types.js";
 
-// ============================================================================
-// Date/time utilities
-// ============================================================================
-
-export { dateTimeToDate } from "./datetime.utils.js";
-
-// ============================================================================
-// Errors
-// ============================================================================
-
-export { ORSchedulingError } from "./errors.js";
-
 // ============================================================================
 // Solver client
 // ============================================================================
@@ -149,7 +70,6 @@ export type {
   CompilationResult,
   CompilationRule,
   RuleValidationContext,
-  CostContext,
   CostEntry,
   CostContribution,
 } from "./cpsat/model-builder.js";
@@ -162,15 +82,22 @@ export { parseSolverResponse, resolveAssignments } from "./cpsat/response.js";
 
 export type { ShiftAssignment, ResolvedShiftAssignment, SolverResult } from "./cpsat/response.js";
 
+// ============================================================================
+// Cost calculation
+// ============================================================================
+
+export { calculateScheduleCost, COST_CATEGORY } from "./cpsat/cost.js";
+
+export type { CostBreakdown, MemberCostDetail, CostCalculationConfig } from "./cpsat/cost.js";
+
 // ============================================================================
 // Rules (registry types)
 // ============================================================================
 
 export type {
-  CpsatRuleRegistry,
-  CpsatRuleName,
   CpsatRuleConfigEntry,
   CpsatRuleFactories,
+  CreateCpsatRuleFunction,
 } from "./cpsat/rules/rules.types.js";
 
 export type { RecurringPeriod } from "./cpsat/rules/scope.types.js";
@@ -186,9 +113,7 @@ export type {
   SalariedPay,
   SchedulingMember,
   ShiftPattern,
-  CoverageRequirement,
   Priority,
-  ModelBuilderOptions,
 } from "./cpsat/types.js";
 
 // ============================================================================
@@ -201,35 +126,32 @@ export { OBJECTIVE_WEIGHTS } from "./cpsat/utils.js";
 // Validation
 // ============================================================================
 
-export type { ValidationReporter } from "./cpsat/validation-reporter.js";
-
 export type {
+  ValidationGroup,
   ScheduleValidation,
   ScheduleError,
-  ScheduleViolation,
-  SchedulePassed,
   CoverageError,
-  CoverageViolation,
-  CoveragePassed,
   RuleError,
+  SolverError,
+  ScheduleViolation,
+  CoverageViolation,
   RuleViolation,
+  SchedulePassed,
+  CoveragePassed,
   RulePassed,
-  SolverError,
-  ValidationContext,
   ValidationSummary,
-  GroupKey,
 } from "./cpsat/validation.types.js";
 
 export { summarizeValidation } from "./cpsat/validation-reporter.js";
 
-export { groupKey } from "./cpsat/validation.types.js";
-
 // ============================================================================
-// Schedule Definition API (v2)
+// Schedule API
 // ============================================================================
 
 export {
-  defineSchedule,
+  schedule,
+  partialSchedule,
+  Schedule,
   t,
   time,
   cover,
@@ -238,14 +160,18 @@ export {
   maxHoursPerWeek,
   minHoursPerDay,
   minHoursPerWeek,
+  maxDaysPerWeek,
+  minDaysPerWeek,
   maxShiftsPerDay,
   maxConsecutiveDays,
   minConsecutiveDays,
   minRestBetweenShifts,
+  mustAssign,
   preference,
   preferLocation,
   timeOff,
   assignTogether,
+  defineRule,
   minimizeCost,
   dayMultiplier,
   daySurcharge,
@@ -257,19 +183,21 @@ export {
   tieredOvertimeMultiplier,
   weekdays,
   weekend,
-} from "./schedule.js";
+} from "./schedule/index.js";
 
 export type {
   CoverageEntry,
   CoverageOptions,
   CoverageVariant,
   RuleEntry,
+  RuleResolveContext,
   RuleOptions,
   EntityOnlyRuleOptions,
   TimeOffOptions,
   AssignTogetherOptions,
   CostRuleOptions,
-  RuntimeArgs,
-  ScheduleDefinition,
   ScheduleConfig,
-} from "./schedule.js";
+  SolveResult,
+  SolveStatus,
+  SolveOptions,
+} from "./schedule/index.js";