dabke 0.78.2 → 0.80.0

package/src/cpsat/rules/max-hours-day.ts

@@ -1,12 +1,18 @@
 import * as z from "zod";
 import type { CompilationRule } from "../model-builder.js";
-import type { SchedulingEmployee } from "../types.js";
 import type { Term } from "../types.js";
-import { parseDayString, priorityToPenalty } from "../utils.js";
-import { normalizeScope, withScopes, type RuleScope } from "./scoping.js";
-
-const MaxHoursDaySchema = withScopes(
-  z.object({
+import { priorityToPenalty } from "../utils.js";
+import {
+  entityScope,
+  timeScope,
+  parseEntityScope,
+  parseTimeScope,
+  resolveEmployeesFromScope,
+  resolveActiveDaysFromScope,
+} from "./scope.types.js";
+
+const MaxHoursDaySchema = z
+  .object({
     hours: z.number().min(0),
     priority: z.union([
       z.literal("LOW"),
@@ -14,21 +20,25 @@ const MaxHoursDaySchema = withScopes(
       z.literal("HIGH"),
       z.literal("MANDATORY"),
     ]),
-  }),
-  {
-    entities: ["employees", "roles", "skills"],
-    times: ["dateRange", "specificDates", "dayOfWeek", "recurring"],
-  },
-);
+  })
+  .and(entityScope(["employees", "roles", "skills"]))
+  .and(timeScope(["dateRange", "specificDates", "dayOfWeek", "recurring"]));
 
+/**
+ * Configuration for {@link createMaxHoursDayRule}.
+ *
+ * - `hours` (required): maximum hours allowed per day
+ * - `priority` (required): how strictly the solver enforces this rule
+ *
+ * Entity scoping (at most one): `employeeIds`, `roleIds`, `skillIds`
+ * Time scoping (at most one, optional): `dateRange`, `specificDates`, `dayOfWeek`, `recurringPeriods`
+ */
 export type MaxHoursDayConfig = z.infer<typeof MaxHoursDaySchema>;
 
 /**
  * Limits how many hours a person can work in a single day.
  *
- * Supports entity scoping (people, roles, skills) and time scoping
- * (date ranges, specific dates, days of week, recurring periods).
- *
+ * @param config - See {@link MaxHoursDayConfig}
  * @example Limit everyone to 8 hours per day
  * ```ts
  * createMaxHoursDayRule({
@@ -49,14 +59,15 @@ export type MaxHoursDayConfig = z.infer<typeof MaxHoursDaySchema>;
  */
 export function createMaxHoursDayRule(config: MaxHoursDayConfig): CompilationRule {
   const parsed = MaxHoursDaySchema.parse(config);
+  const entityScopeValue = parseEntityScope(parsed);
+  const timeScopeValue = parseTimeScope(parsed);
   const { hours, priority } = parsed;
   const maxMinutes = hours * 60;
 
   return {
     compile(b) {
-      const scope = normalizeScope(parsed, b.employees);
-      const targetEmployees = resolveEmployees(scope, b.employees);
-      const activeDays = resolveActiveDays(scope, b.days);
+      const targetEmployees = resolveEmployeesFromScope(entityScopeValue, b.employees);
+      const activeDays = resolveActiveDaysFromScope(timeScopeValue, b.days);
 
       if (targetEmployees.length === 0 || activeDays.length === 0) return;
 
@@ -84,104 +95,3 @@ export function createMaxHoursDayRule(config: MaxHoursDayConfig): CompilationRul
     },
   };
 }
-
-function resolveEmployees(scope: RuleScope, employees: SchedulingEmployee[]): SchedulingEmployee[] {
-  const entity = scope.entity;
-  switch (entity.type) {
-    case "employees":
-      return employees.filter((e) => entity.employeeIds.includes(e.id));
-    case "roles":
-      return employees.filter((e) => e.roleIds.some((r) => entity.roleIds.includes(r)));
-    case "skills":
-      return employees.filter((e) => e.skillIds?.some((s) => entity.skillIds.includes(s)));
-    case "global":
-    default:
-      return employees;
-  }
-}
-
-type DayName = "sunday" | "monday" | "tuesday" | "wednesday" | "thursday" | "friday" | "saturday";
-
-function getDayOfWeekName(dayIndex: number): DayName {
-  const names: Record<number, DayName> = {
-    0: "sunday",
-    1: "monday",
-    2: "tuesday",
-    3: "wednesday",
-    4: "thursday",
-    5: "friday",
-    6: "saturday",
-  };
-  return names[dayIndex % 7] ?? "sunday";
-}
-
-function resolveActiveDays(scope: RuleScope, allDays: string[]): string[] {
-  const timeScope = scope.time;
-
-  if (!timeScope) {
-    return allDays;
-  }
-
-  switch (timeScope.type) {
-    case "always":
-      return allDays;
-
-    case "dateRange": {
-      const start = timeScope.start;
-      const end = timeScope.end;
-      return allDays.filter((day) => day >= start && day <= end);
-    }
-
-    case "specificDates":
-      return allDays.filter((day) => timeScope.dates.includes(day));
-
-    case "dayOfWeek": {
-      const targetDays = new Set(timeScope.days);
-      return allDays.filter((day) => {
-        const date = parseDayString(day);
-        const dayName = getDayOfWeekName(date.getUTCDay());
-        return targetDays.has(dayName);
-      });
-    }
-
-    case "recurring": {
-      return allDays.filter((day) => {
-        const date = parseDayString(day);
-        const month = date.getUTCMonth() + 1;
-        const dayOfMonth = date.getUTCDate();
-
-        return timeScope.periods.some((period) =>
-          isDateInRecurringPeriod(month, dayOfMonth, period),
-        );
-      });
-    }
-
-    default:
-      return allDays;
-  }
-}
-
-function isDateInRecurringPeriod(
-  month: number,
-  dayOfMonth: number,
-  period: {
-    startMonth: number;
-    startDay: number;
-    endMonth: number;
-    endDay: number;
-  },
-): boolean {
-  const { startMonth, startDay, endMonth, endDay } = period;
-
-  if (startMonth <= endMonth) {
-    if (month < startMonth || month > endMonth) return false;
-    if (month === startMonth && dayOfMonth < startDay) return false;
-    if (month === endMonth && dayOfMonth > endDay) return false;
-    return true;
-  } else {
-    if (month > endMonth && month < startMonth) return false;
-    if (month === startMonth && dayOfMonth < startDay) return false;
-    if (month === endMonth && dayOfMonth > endDay) return false;
-    return true;
-  }
-}

package/src/cpsat/rules/max-hours-week.ts

@@ -1,43 +1,51 @@
 import * as z from "zod";
 import { DayOfWeekSchema } from "../../types.js";
 import type { CompilationRule } from "../model-builder.js";
-import type { SchedulingEmployee, Term } from "../types.js";
-import { parseDayString, priorityToPenalty, splitIntoWeeks } from "../utils.js";
-import { normalizeScope, withScopes, type RuleScope } from "./scoping.js";
-
-const MaxHoursWeekSchema = withScopes(
-  z.object({
-    hours: z.number().min(0),
-    priority: z.union([
-      z.literal("LOW"),
-      z.literal("MEDIUM"),
-      z.literal("HIGH"),
-      z.literal("MANDATORY"),
-    ]),
-    // Optional override; defaults to ModelBuilder.weekStartsOn
-    weekStartsOn: DayOfWeekSchema.optional(),
-  }),
-  {
-    entities: ["employees", "roles", "skills"],
-    times: ["dateRange", "specificDates", "dayOfWeek", "recurring"],
-  },
+import type { Term } from "../types.js";
+import { priorityToPenalty, splitIntoWeeks } from "../utils.js";
+import {
+  entityScope,
+  timeScope,
+  parseEntityScope,
+  parseTimeScope,
+  resolveEmployeesFromScope,
+  resolveActiveDaysFromScope,
+} from "./scope.types.js";
+
+const MaxHoursWeekBase = z.object({
+  hours: z.number().min(0),
+  priority: z.union([
+    z.literal("LOW"),
+    z.literal("MEDIUM"),
+    z.literal("HIGH"),
+    z.literal("MANDATORY"),
+  ]),
+  weekStartsOn: DayOfWeekSchema.optional(),
+});
+
+const MaxHoursWeekSchema = MaxHoursWeekBase.and(entityScope(["employees", "roles", "skills"])).and(
+  timeScope(["dateRange", "specificDates", "dayOfWeek", "recurring"]),
 );
 
+/**
+ * Configuration for {@link createMaxHoursWeekRule}.
+ *
+ * - `hours` (required): maximum hours allowed per scheduling week
+ * - `priority` (required): how strictly the solver enforces this rule
+ * - `weekStartsOn` (optional): which day starts the week; defaults to {@link ModelBuilder.weekStartsOn}
+ *
+ * Entity scoping (at most one): `employeeIds`, `roleIds`, `skillIds`
+ * Time scoping (at most one, optional): `dateRange`, `specificDates`, `dayOfWeek`, `recurringPeriods`
+ */
 export type MaxHoursWeekConfig = z.infer<typeof MaxHoursWeekSchema>;
 
 /**
  * Caps total hours a person can work within each scheduling week.
  *
- * Supports entity scoping (people, roles, skills) and time scoping
- * (date ranges, specific dates, days of week, recurring periods).
- * Time scoping filters which days within each week count toward the limit.
- *
+ * @param config - See {@link MaxHoursWeekConfig}
  * @example Limit everyone to 40 hours per week
  * ```ts
- * createMaxHoursWeekRule({
- *   hours: 40,
- *   priority: "HIGH",
- * });
+ * createMaxHoursWeekRule({ hours: 40, priority: "HIGH" });
  * ```
  *
  * @example Students limited to 20 hours during term time
@@ -47,7 +55,6 @@ export type MaxHoursWeekConfig = z.infer<typeof MaxHoursWeekSchema>;
  *   hours: 20,
  *   recurringPeriods: [
  *     { name: "fall-term", startMonth: 9, startDay: 1, endMonth: 12, endDay: 15 },
- *     { name: "spring-term", startMonth: 1, startDay: 15, endMonth: 5, endDay: 31 },
  *   ],
  *   priority: "MANDATORY",
  * });
@@ -55,18 +62,19 @@ export type MaxHoursWeekConfig = z.infer<typeof MaxHoursWeekSchema>;
  */
 export function createMaxHoursWeekRule(config: MaxHoursWeekConfig): CompilationRule {
   const parsed = MaxHoursWeekSchema.parse(config);
-  const { hours, priority } = parsed;
+  const entityScopeValue = parseEntityScope(parsed);
+  const timeScopeValue = parseTimeScope(parsed);
+  const { hours, priority, weekStartsOn } = parsed;
   const maxMinutes = hours * 60;
 
   return {
     compile(b) {
-      const scope = normalizeScope(parsed, b.employees);
-      const targetEmployees = resolveEmployees(scope, b.employees);
-      const activeDays = resolveActiveDays(scope, b.days);
+      const targetEmployees = resolveEmployeesFromScope(entityScopeValue, b.employees);
+      const activeDays = resolveActiveDaysFromScope(timeScopeValue, b.days);
 
       if (targetEmployees.length === 0 || activeDays.length === 0) return;
 
-      const weeks = splitIntoWeeks(activeDays, parsed.weekStartsOn ?? b.weekStartsOn);
+      const weeks = splitIntoWeeks(activeDays, weekStartsOn ?? b.weekStartsOn);
 
       for (const emp of targetEmployees) {
         for (const weekDays of weeks) {
@@ -94,104 +102,3 @@ export function createMaxHoursWeekRule(config: MaxHoursWeekConfig): CompilationR
     },
   };
 }
-
-function resolveEmployees(scope: RuleScope, employees: SchedulingEmployee[]): SchedulingEmployee[] {
-  const entity = scope.entity;
-  switch (entity.type) {
-    case "employees":
-      return employees.filter((e) => entity.employeeIds.includes(e.id));
-    case "roles":
-      return employees.filter((e) => e.roleIds.some((r) => entity.roleIds.includes(r)));
-    case "skills":
-      return employees.filter((e) => e.skillIds?.some((s) => entity.skillIds.includes(s)));
-    case "global":
-    default:
-      return employees;
-  }
-}
-
-type DayName = "sunday" | "monday" | "tuesday" | "wednesday" | "thursday" | "friday" | "saturday";
-
-function getDayOfWeekName(dayIndex: number): DayName {
-  const names: Record<number, DayName> = {
-    0: "sunday",
-    1: "monday",
-    2: "tuesday",
-    3: "wednesday",
-    4: "thursday",
-    5: "friday",
-    6: "saturday",
-  };
-  return names[dayIndex % 7] ?? "sunday";
-}
-
-function resolveActiveDays(scope: RuleScope, allDays: string[]): string[] {
-  const timeScope = scope.time;
-
-  if (!timeScope) {
-    return allDays;
-  }
-
-  switch (timeScope.type) {
-    case "always":
-      return allDays;
-
-    case "dateRange": {
-      const start = timeScope.start;
-      const end = timeScope.end;
-      return allDays.filter((day) => day >= start && day <= end);
-    }
-
-    case "specificDates":
-      return allDays.filter((day) => timeScope.dates.includes(day));
-
-    case "dayOfWeek": {
-      const targetDays = new Set(timeScope.days);
-      return allDays.filter((day) => {
-        const date = parseDayString(day);
-        const dayName = getDayOfWeekName(date.getUTCDay());
-        return targetDays.has(dayName);
-      });
-    }
-
-    case "recurring": {
-      return allDays.filter((day) => {
-        const date = parseDayString(day);
-        const month = date.getUTCMonth() + 1;
-        const dayOfMonth = date.getUTCDate();
-
-        return timeScope.periods.some((period) =>
-          isDateInRecurringPeriod(month, dayOfMonth, period),
-        );
-      });
-    }
-
-    default:
-      return allDays;
-  }
-}
-
-function isDateInRecurringPeriod(
-  month: number,
-  dayOfMonth: number,
-  period: {
-    startMonth: number;
-    startDay: number;
-    endMonth: number;
-    endDay: number;
-  },
-): boolean {
-  const { startMonth, startDay, endMonth, endDay } = period;
-
-  if (startMonth <= endMonth) {
-    if (month < startMonth || month > endMonth) return false;
-    if (month === startMonth && dayOfMonth < startDay) return false;
-    if (month === endMonth && dayOfMonth > endDay) return false;
-    return true;
-  } else {
-    if (month > endMonth && month < startMonth) return false;
-    if (month === startMonth && dayOfMonth < startDay) return false;
-    if (month === endMonth && dayOfMonth > endDay) return false;
-    return true;
-  }
-}

package/src/cpsat/rules/max-shifts-day.ts

@@ -1,12 +1,18 @@
 import * as z from "zod";
 import type { CompilationRule } from "../model-builder.js";
-import type { SchedulingEmployee } from "../types.js";
 import type { Term } from "../types.js";
-import { parseDayString, priorityToPenalty } from "../utils.js";
-import { normalizeScope, withScopes, type RuleScope } from "./scoping.js";
-
-const MaxShiftsDaySchema = withScopes(
-  z.object({
+import { priorityToPenalty } from "../utils.js";
+import {
+  entityScope,
+  timeScope,
+  parseEntityScope,
+  parseTimeScope,
+  resolveEmployeesFromScope,
+  resolveActiveDaysFromScope,
+} from "./scope.types.js";
+
+const MaxShiftsDaySchema = z
+  .object({
     shifts: z.number().int().min(1),
     priority: z.union([
       z.literal("LOW"),
@@ -14,25 +20,29 @@ const MaxShiftsDaySchema = withScopes(
       z.literal("HIGH"),
       z.literal("MANDATORY"),
     ]),
-  }),
-  {
-    entities: ["employees", "roles", "skills"],
-    times: ["dateRange", "specificDates", "dayOfWeek", "recurring"],
-  },
-);
+  })
+  .and(entityScope(["employees", "roles", "skills"]))
+  .and(timeScope(["dateRange", "specificDates", "dayOfWeek", "recurring"]));
 
+/**
+ * Configuration for {@link createMaxShiftsDayRule}.
+ *
+ * - `shifts` (required): maximum number of shifts per day (at least 1)
+ * - `priority` (required): how strictly the solver enforces this rule
+ *
+ * Entity scoping (at most one): `employeeIds`, `roleIds`, `skillIds`
+ * Time scoping (at most one, optional): `dateRange`, `specificDates`, `dayOfWeek`, `recurringPeriods`
+ */
 export type MaxShiftsDayConfig = z.infer<typeof MaxShiftsDaySchema>;
 
 /**
  * Limits how many shifts a person can work in a single day.
  *
- * This rule controls the maximum number of distinct shift assignments per day,
+ * Controls the maximum number of distinct shift assignments per day,
  * regardless of shift duration. For limiting total hours worked, use `max-hours-day`.
  *
- * Supports entity scoping (people, roles, skills) and time scoping
- * (date ranges, specific dates, days of week, recurring periods).
- *
- * @example Limit to one shift per day (common for most schedules)
+ * @param config - See {@link MaxShiftsDayConfig}
+ * @example Limit to one shift per day
  * ```ts
  * createMaxShiftsDayRule({
  *   shifts: 1,
@@ -40,15 +50,6 @@ export type MaxShiftsDayConfig = z.infer<typeof MaxShiftsDaySchema>;
  * });
  * ```
  *
- * @example Allow up to two shifts per day for part-time workers
- * ```ts
- * createMaxShiftsDayRule({
- *   roleIds: ["part-time"],
- *   shifts: 2,
- *   priority: "HIGH",
- * });
- * ```
- *
  * @example Students can work 2 shifts on weekends only
  * ```ts
  * createMaxShiftsDayRule({
@@ -61,13 +62,14 @@ export type MaxShiftsDayConfig = z.infer<typeof MaxShiftsDaySchema>;
  */
 export function createMaxShiftsDayRule(config: MaxShiftsDayConfig): CompilationRule {
   const parsed = MaxShiftsDaySchema.parse(config);
+  const entityScopeValue = parseEntityScope(parsed);
+  const timeScopeValue = parseTimeScope(parsed);
   const { shifts, priority } = parsed;
 
   return {
     compile(b) {
-      const scope = normalizeScope(parsed, b.employees);
-      const targetEmployees = resolveEmployees(scope, b.employees);
-      const activeDays = resolveActiveDays(scope, b.days);
+      const targetEmployees = resolveEmployeesFromScope(entityScopeValue, b.employees);
+      const activeDays = resolveActiveDaysFromScope(timeScopeValue, b.days);
 
       if (targetEmployees.length === 0 || activeDays.length === 0) return;
 
@@ -95,104 +97,3 @@ export function createMaxShiftsDayRule(config: MaxShiftsDayConfig): CompilationR
     },
   };
 }
-
-function resolveEmployees(scope: RuleScope, employees: SchedulingEmployee[]): SchedulingEmployee[] {
-  const entity = scope.entity;
-  switch (entity.type) {
-    case "employees":
-      return employees.filter((e) => entity.employeeIds.includes(e.id));
-    case "roles":
-      return employees.filter((e) => e.roleIds.some((r) => entity.roleIds.includes(r)));
-    case "skills":
-      return employees.filter((e) => e.skillIds?.some((s) => entity.skillIds.includes(s)));
-    case "global":
-    default:
-      return employees;
-  }
-}
-
-type DayName = "sunday" | "monday" | "tuesday" | "wednesday" | "thursday" | "friday" | "saturday";
-
-function getDayOfWeekName(dayIndex: number): DayName {
-  const names: Record<number, DayName> = {
-    0: "sunday",
-    1: "monday",
-    2: "tuesday",
-    3: "wednesday",
-    4: "thursday",
-    5: "friday",
-    6: "saturday",
-  };
-  return names[dayIndex % 7] ?? "sunday";
-}
-
-function resolveActiveDays(scope: RuleScope, allDays: string[]): string[] {
-  const timeScope = scope.time;
-
-  if (!timeScope) {
-    return allDays;
-  }
-
-  switch (timeScope.type) {
-    case "always":
-      return allDays;
-
-    case "dateRange": {
-      const start = timeScope.start;
-      const end = timeScope.end;
-      return allDays.filter((day) => day >= start && day <= end);
-    }
-
-    case "specificDates":
-      return allDays.filter((day) => timeScope.dates.includes(day));
-
-    case "dayOfWeek": {
-      const targetDays = new Set(timeScope.days);
-      return allDays.filter((day) => {
-        const date = parseDayString(day);
-        const dayName = getDayOfWeekName(date.getUTCDay());
-        return targetDays.has(dayName);
-      });
-    }
-
-    case "recurring": {
-      return allDays.filter((day) => {
-        const date = parseDayString(day);
-        const month = date.getUTCMonth() + 1;
-        const dayOfMonth = date.getUTCDate();
-
-        return timeScope.periods.some((period) =>
-          isDateInRecurringPeriod(month, dayOfMonth, period),
-        );
-      });
-    }
-
-    default:
-      return allDays;
-  }
-}
-
-function isDateInRecurringPeriod(
-  month: number,
-  dayOfMonth: number,
-  period: {
-    startMonth: number;
-    startDay: number;
-    endMonth: number;
-    endDay: number;
-  },
-): boolean {
-  const { startMonth, startDay, endMonth, endDay } = period;
-
-  if (startMonth <= endMonth) {
-    if (month < startMonth || month > endMonth) return false;
-    if (month === startMonth && dayOfMonth < startDay) return false;
-    if (month === endMonth && dayOfMonth > endDay) return false;
-    return true;
-  } else {
-    if (month > endMonth && month < startMonth) return false;
-    if (month === startMonth && dayOfMonth < startDay) return false;
-    if (month === endMonth && dayOfMonth > endDay) return false;
-    return true;
-  }
-}

package/src/cpsat/rules/min-consecutive-days.ts

@@ -1,10 +1,10 @@
 import * as z from "zod";
 import type { CompilationRule } from "../model-builder.js";
 import { priorityToPenalty } from "../utils.js";
-import { withScopes } from "./scoping.js";
+import { entityScope, parseEntityScope, resolveEmployeesFromScope } from "./scope.types.js";
 
-const MinConsecutiveDaysSchema = withScopes(
-  z.object({
+const MinConsecutiveDaysSchema = z
+  .object({
     days: z.number().min(0),
     priority: z.union([
       z.literal("LOW"),
@@ -12,35 +12,39 @@ const MinConsecutiveDaysSchema = withScopes(
       z.literal("HIGH"),
       z.literal("MANDATORY"),
     ]),
-  }),
-  { entities: ["employees", "roles", "skills"], times: [] },
-);
+  })
+  .and(entityScope(["employees", "roles", "skills"]));
 
+/**
+ * Configuration for {@link createMinConsecutiveDaysRule}.
+ *
+ * - `days` (required): minimum consecutive days required once a person starts working
+ * - `priority` (required): how strictly the solver enforces this rule
+ *
+ * Entity scoping (at most one): `employeeIds`, `roleIds`, `skillIds`
+ */
 export type MinConsecutiveDaysConfig = z.infer<typeof MinConsecutiveDaysSchema>;
 
 /**
  * Requires that once a person starts working, they continue for a minimum
  * number of consecutive days.
  *
+ * @param config - See {@link MinConsecutiveDaysConfig}
  * @example
  * ```ts
- * const rule = createMinConsecutiveDaysRule({
- *   days: 3,
- *   priority: "MANDATORY",
- * });
- * builder = new ModelBuilder({ ...config, rules: [rule] });
+ * createMinConsecutiveDaysRule({ days: 3, priority: "MANDATORY" });
  * ```
  */
 export function createMinConsecutiveDaysRule(config: MinConsecutiveDaysConfig): CompilationRule {
-  const { days, priority, employeeIds } = MinConsecutiveDaysSchema.parse(config);
+  const parsed = MinConsecutiveDaysSchema.parse(config);
+  const scope = parseEntityScope(parsed);
+  const { days, priority } = parsed;
 
   return {
     compile(b) {
       if (days <= 1) return;
 
-      const employees = employeeIds
-        ? b.employees.filter((e) => employeeIds.includes(e.id))
-        : b.employees;
+      const employees = resolveEmployeesFromScope(scope, b.employees);
 
       for (const emp of employees) {
         const worksByDay: string[] = [];