dabke 0.82.0 → 0.83.0

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

@@ -0,0 +1,143 @@
+import * as z from "zod";
+import { DayOfWeekSchema } from "../../types.js";
+import type { CompilationRule } from "../model-builder.js";
+import type { Term } from "../types.js";
+import { priorityToPenalty, splitIntoWeeks } from "../utils.js";
+import {
+  PrioritySchema,
+  entityScope,
+  timeScope,
+  parseEntityScope,
+  parseTimeScope,
+  resolveMembersFromScope,
+  resolveActiveDaysFromScope,
+  ruleGroup,
+} from "./scope.types.js";
+
+const MaxDaysWeekBase = z.object({
+  days: z.number().int().min(0),
+  priority: PrioritySchema,
+  weekStartsOn: DayOfWeekSchema.optional(),
+});
+
+const MaxDaysWeekSchema = MaxDaysWeekBase.and(entityScope(["members", "roles", "skills"])).and(
+  timeScope(["dateRange", "specificDates", "dayOfWeek", "recurring"]),
+);
+
+/**
+ * Configuration for {@link createMaxDaysWeekRule}.
+ *
+ * - `days` (required): maximum number of days 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): `memberIds`, `roleIds`, `skillIds`
+ * Time scoping (at most one, optional): `dateRange`, `specificDates`, `dayOfWeek`, `recurringPeriods`
+ */
+export type MaxDaysWeekConfig = z.infer<typeof MaxDaysWeekSchema>;
+
+/**
+ * Caps total number of days a person can work within each scheduling week.
+ *
+ * @remarks
+ * Creates a binary "works on day" variable for each member and day, then
+ * constrains the weekly sum. This counts distinct days, regardless of how
+ * many shifts are assigned on a single day.
+ *
+ * @param config - See {@link MaxDaysWeekConfig}
+ * @example Limit everyone to 5 days per week
+ * ```ts
+ * createMaxDaysWeekRule({ days: 5, priority: "MANDATORY" });
+ * ```
+ *
+ * @example Part-time staff limited to 3 days
+ * ```ts
+ * createMaxDaysWeekRule({
+ *   roleIds: ["part-time"],
+ *   days: 3,
+ *   priority: "HIGH",
+ * });
+ * ```
+ */
+export function createMaxDaysWeekRule(config: MaxDaysWeekConfig): CompilationRule {
+  const parsed = MaxDaysWeekSchema.parse(config);
+  const entityScopeValue = parseEntityScope(parsed);
+  const timeScopeValue = parseTimeScope(parsed);
+  const { days, priority, weekStartsOn } = parsed;
+  const group = ruleGroup(
+    `max-days-week:${days}`,
+    `Max ${days}d per week`,
+    entityScopeValue,
+    timeScopeValue,
+  );
+
+  return {
+    compile(b) {
+      const targetMembers = resolveMembersFromScope(entityScopeValue, b.members);
+      const activeDays = resolveActiveDaysFromScope(timeScopeValue, b.days);
+
+      if (targetMembers.length === 0 || activeDays.length === 0) return;
+
+      const weeks = splitIntoWeeks(activeDays, weekStartsOn ?? b.weekStartsOn);
+
+      for (const emp of targetMembers) {
+        for (const weekDays of weeks) {
+          const weekWorkVars: string[] = [];
+
+          for (const day of weekDays) {
+            const dayAssignments = b.shiftPatterns
+              .filter((p) => b.canAssign(emp, p) && b.patternAvailableOnDay(p, day))
+              .map((p) => b.assignment(emp.id, p.id, day));
+
+            if (dayAssignments.length === 0) continue;
+
+            const worksVar = b.boolVar(`works_day_${emp.id}_${day}`);
+            weekWorkVars.push(worksVar);
+
+            // worksVar >= each assignment (if any assignment is 1, worksVar must be 1)
+            for (const assignVar of dayAssignments) {
+              b.addLinear(
+                [
+                  { var: worksVar, coeff: 1 },
+                  { var: assignVar, coeff: -1 },
+                ],
+                ">=",
+                0,
+              );
+            }
+
+            // worksVar <= sum(assignments) (if no assignment is 1, worksVar must be 0)
+            b.addLinear(
+              [{ var: worksVar, coeff: 1 }, ...dayAssignments.map((v) => ({ var: v, coeff: -1 }))],
+              "<=",
+              0,
+            );
+          }
+
+          if (weekWorkVars.length === 0) continue;
+
+          const weekLabel = weekDays[0]!;
+          const constraintId = `max-days-week:${emp.id}:${weekLabel}`;
+          const terms: Term[] = weekWorkVars.map((v) => ({ var: v, coeff: 1 }));
+
+          if (priority === "MANDATORY") {
+            b.addLinear(terms, "<=", days);
+          } else {
+            b.addSoftLinear(terms, "<=", days, priorityToPenalty(priority), constraintId);
+            b.reporter.trackConstraint({
+              id: constraintId,
+              type: "rule",
+              rule: "max-days-week",
+              description: `${emp.id} max ${days}d in week starting ${weekLabel}`,
+              targetValue: days,
+              comparator: "<=",
+              day: weekLabel,
+              context: { memberIds: [emp.id], days: weekDays },
+              group,
+            });
+          }
+        }
+      }
+    },
+  };
+}

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

@@ -0,0 +1,120 @@
+import * as z from "zod";
+import { DayOfWeekSchema } from "../../types.js";
+import type { CompilationRule } from "../model-builder.js";
+import type { Term } from "../types.js";
+import { priorityToPenalty, splitIntoWeeks } from "../utils.js";
+import {
+  PrioritySchema,
+  entityScope,
+  parseEntityScope,
+  resolveMembersFromScope,
+  ruleGroup,
+} from "./scope.types.js";
+
+const MinDaysWeekBase = z.object({
+  days: z.number().int().min(0),
+  priority: PrioritySchema,
+  weekStartsOn: DayOfWeekSchema.optional(),
+});
+
+const MinDaysWeekSchema = MinDaysWeekBase.and(entityScope(["members", "roles", "skills"]));
+
+/**
+ * Configuration for {@link createMinDaysWeekRule}.
+ *
+ * - `days` (required): minimum number of days required 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): `memberIds`, `roleIds`, `skillIds`
+ */
+export type MinDaysWeekConfig = z.infer<typeof MinDaysWeekSchema>;
+
+/**
+ * Enforces a minimum number of days a person must work per scheduling week.
+ *
+ * @remarks
+ * Creates a binary "works on day" variable for each member and day, then
+ * constrains the weekly sum. This counts distinct days, regardless of how
+ * many shifts are assigned on a single day.
+ *
+ * @param config - See {@link MinDaysWeekConfig}
+ * @example
+ * ```ts
+ * createMinDaysWeekRule({ days: 3, priority: "HIGH" });
+ * ```
+ */
+export function createMinDaysWeekRule(config: MinDaysWeekConfig): CompilationRule {
+  const parsed = MinDaysWeekSchema.parse(config);
+  const scope = parseEntityScope(parsed);
+  const { days, priority, weekStartsOn } = parsed;
+  const group = ruleGroup(`min-days-week:${days}`, `Min ${days}d per week`, scope);
+
+  return {
+    compile(b) {
+      if (days <= 0) return;
+
+      const members = resolveMembersFromScope(scope, b.members);
+      const weeks = splitIntoWeeks(b.days, weekStartsOn ?? b.weekStartsOn);
+
+      for (const emp of members) {
+        for (const weekDays of weeks) {
+          const weekWorkVars: string[] = [];
+
+          for (const day of weekDays) {
+            const dayAssignments = b.shiftPatterns
+              .filter((p) => b.canAssign(emp, p) && b.patternAvailableOnDay(p, day))
+              .map((p) => b.assignment(emp.id, p.id, day));
+
+            if (dayAssignments.length === 0) continue;
+
+            const worksVar = b.boolVar(`works_day_${emp.id}_${day}`);
+            weekWorkVars.push(worksVar);
+
+            // worksVar >= each assignment (if any assignment is 1, worksVar must be 1)
+            for (const assignVar of dayAssignments) {
+              b.addLinear(
+                [
+                  { var: worksVar, coeff: 1 },
+                  { var: assignVar, coeff: -1 },
+                ],
+                ">=",
+                0,
+              );
+            }
+
+            // worksVar <= sum(assignments) (if no assignment is 1, worksVar must be 0)
+            b.addLinear(
+              [{ var: worksVar, coeff: 1 }, ...dayAssignments.map((v) => ({ var: v, coeff: -1 }))],
+              "<=",
+              0,
+            );
+          }
+
+          if (weekWorkVars.length === 0) continue;
+
+          const weekLabel = weekDays[0]!;
+          const constraintId = `min-days-week:${emp.id}:${weekLabel}`;
+          const terms: Term[] = weekWorkVars.map((v) => ({ var: v, coeff: 1 }));
+
+          if (priority === "MANDATORY") {
+            b.addLinear(terms, ">=", days);
+          } else {
+            b.addSoftLinear(terms, ">=", days, priorityToPenalty(priority), constraintId);
+            b.reporter.trackConstraint({
+              id: constraintId,
+              type: "rule",
+              rule: "min-days-week",
+              description: `${emp.id} min ${days}d in week starting ${weekLabel}`,
+              targetValue: days,
+              comparator: ">=",
+              day: weekLabel,
+              context: { memberIds: [emp.id], days: weekDays },
+              group,
+            });
+          }
+        }
+      }
+    },
+  };
+}

package/src/cpsat/rules/must-assign.ts

@@ -0,0 +1,108 @@
+import * as z from "zod";
+import { DayOfWeekSchema } from "../../types.js";
+import type { CompilationRule } from "../model-builder.js";
+import type { Term } from "../types.js";
+import { priorityToPenalty, splitIntoWeeks } from "../utils.js";
+import {
+  entityScope,
+  parseEntityScope,
+  resolveMembersFromScope,
+  ruleGroup,
+} from "./scope.types.js";
+
+/** Internally always HIGH. Not user-configurable. */
+const MUST_ASSIGN_PENALTY = priorityToPenalty("HIGH");
+
+const MustAssignSchema = z
+  .object({
+    weekStartsOn: DayOfWeekSchema.optional(),
+  })
+  .and(entityScope(["members", "roles", "skills"]));
+
+/**
+ * Configuration for {@link createMustAssignRule}.
+ *
+ * - `weekStartsOn` (optional): which day starts the week; defaults to
+ *   {@link ModelBuilder.weekStartsOn}
+ *
+ * Entity scoping (at most one): `memberIds`, `roleIds`, `skillIds`
+ */
+export type MustAssignConfig = z.infer<typeof MustAssignSchema>;
+
+/**
+ * Guarantees that targeted members appear on the schedule.
+ *
+ * @remarks
+ * Use this for staffing obligations: salaried employees who are paid
+ * regardless of whether they work, or contracted staff who must be
+ * rostered. The solver ensures each targeted member has at least one
+ * assignment per scheduling week.
+ *
+ * Always compiles as a soft constraint (HIGH priority internally) so the
+ * schedule still generates when a member genuinely cannot be placed
+ * (e.g., full week of absences, no compatible shift patterns). Violations
+ * surface as validation warnings with distinct messaging from
+ * `min-days-week`.
+ *
+ * Unlike {@link createMinDaysWeekRule}, this rule communicates a staffing
+ * obligation rather than a scheduling preference. Validation messages
+ * reflect this: "Alice was not assigned (staffing obligation)" rather
+ * than "Alice worked 0 days, minimum was 1."
+ *
+ * @param config - See {@link MustAssignConfig}
+ *
+ * @example Ensure a salaried manager is always rostered
+ * ```ts
+ * createMustAssignRule({ memberIds: ["diana"] });
+ * ```
+ *
+ * @example Ensure all supervisors appear on the rota
+ * ```ts
+ * createMustAssignRule({ roleIds: ["supervisor"] });
+ * ```
+ */
+export function createMustAssignRule(config: MustAssignConfig): CompilationRule {
+  const parsed = MustAssignSchema.parse(config);
+  const scope = parseEntityScope(parsed);
+  const { weekStartsOn } = parsed;
+  const group = ruleGroup("must-assign", "Must assign", scope);
+
+  return {
+    compile(b) {
+      const members = resolveMembersFromScope(scope, b.members);
+      const weeks = splitIntoWeeks(b.days, weekStartsOn ?? b.weekStartsOn);
+
+      for (const emp of members) {
+        for (const weekDays of weeks) {
+          const terms: Term[] = [];
+
+          for (const day of weekDays) {
+            for (const pattern of b.shiftPatterns) {
+              if (!b.canAssign(emp, pattern)) continue;
+              if (!b.patternAvailableOnDay(pattern, day)) continue;
+              terms.push({ var: b.assignment(emp.id, pattern.id, day), coeff: 1 });
+            }
+          }
+
+          if (terms.length === 0) continue;
+
+          const weekLabel = weekDays[0]!;
+          const constraintId = `must-assign:${emp.id}:${weekLabel}`;
+
+          b.addSoftLinear(terms, ">=", 1, MUST_ASSIGN_PENALTY, constraintId);
+          b.reporter.trackConstraint({
+            id: constraintId,
+            type: "rule",
+            rule: "must-assign",
+            description: `${emp.id} not assigned in week starting ${weekLabel} (staffing obligation)`,
+            targetValue: 1,
+            comparator: ">=",
+            day: weekLabel,
+            context: { memberIds: [emp.id], days: weekDays },
+            group,
+          });
+        }
+      }
+    },
+  };
+}

package/src/cpsat/rules/registry.ts

@@ -3,13 +3,16 @@ import {
   createAssignmentPriorityRule,
   createLocationPreferenceRule,
   createMaxConsecutiveDaysRule,
+  createMaxDaysWeekRule,
   createMaxHoursDayRule,
   createMaxHoursWeekRule,
   createMaxShiftsDayRule,
   createMinConsecutiveDaysRule,
+  createMinDaysWeekRule,
   createMinHoursDayRule,
   createMinHoursWeekRule,
   createMinRestBetweenShiftsRule,
+  createMustAssignRule,
   createTimeOffRule,
   createMinimizeCostRule,
   createDayCostMultiplierRule,
@@ -32,13 +35,16 @@ export const builtInCpsatRuleFactories = {
   "assignment-priority": createAssignmentPriorityRule,
   "location-preference": createLocationPreferenceRule,
   "max-consecutive-days": createMaxConsecutiveDaysRule,
+  "max-days-week": createMaxDaysWeekRule,
   "max-hours-day": createMaxHoursDayRule,
   "max-hours-week": createMaxHoursWeekRule,
   "max-shifts-day": createMaxShiftsDayRule,
   "min-consecutive-days": createMinConsecutiveDaysRule,
+  "min-days-week": createMinDaysWeekRule,
   "min-hours-day": createMinHoursDayRule,
   "min-hours-week": createMinHoursWeekRule,
   "min-rest-between-shifts": createMinRestBetweenShiftsRule,
+  "must-assign": createMustAssignRule,
   "time-off": createTimeOffRule,
   "minimize-cost": createMinimizeCostRule,
   "day-cost-multiplier": createDayCostMultiplierRule,

package/src/cpsat/rules/rules.types.ts

@@ -8,13 +8,16 @@ export interface CpsatRuleRegistry {
   "assignment-priority": import("./assignment-priority.js").AssignmentPriorityConfig;
   "location-preference": import("./location-preference.js").LocationPreferenceConfig;
   "max-consecutive-days": import("./max-consecutive-days.js").MaxConsecutiveDaysConfig;
+  "max-days-week": import("./max-days-week.js").MaxDaysWeekConfig;
   "max-hours-day": import("./max-hours-day.js").MaxHoursDayConfig;
   "max-hours-week": import("./max-hours-week.js").MaxHoursWeekConfig;
   "max-shifts-day": import("./max-shifts-day.js").MaxShiftsDayConfig;
   "min-consecutive-days": import("./min-consecutive-days.js").MinConsecutiveDaysConfig;
+  "min-days-week": import("./min-days-week.js").MinDaysWeekConfig;
   "min-hours-day": import("./min-hours-day.js").MinHoursDayConfig;
   "min-hours-week": import("./min-hours-week.js").MinHoursWeekConfig;
   "min-rest-between-shifts": import("./min-rest-between-shifts.js").MinRestBetweenShiftsConfig;
+  "must-assign": import("./must-assign.js").MustAssignConfig;
   "time-off": import("./time-off.js").TimeOffConfig;
   "minimize-cost": import("./minimize-cost.js").MinimizeCostConfig;
   "day-cost-multiplier": import("./day-cost-multiplier.js").DayCostMultiplierConfig;

package/src/cpsat/rules/scope.types.ts

@@ -90,7 +90,7 @@ type NonEmptyArray<T> = [T, ...T[]];
 /**
  * Recurring calendar period for time scoping.
  *
- * @category Rules
+ * @category Supporting Types
  */
 export interface RecurringPeriod {
   name: string;

package/src/index.ts

@@ -1,5 +1,7 @@
 /**
- * @privateRemarks
+ * Scheduling library powered by constraint programming (CP-SAT).
+ *
+ * @remarks
  * ## Core Concepts
  *
  * **Schedule**: The primary API. Small, composable functions
@@ -158,10 +160,13 @@ export {
   maxHoursPerWeek,
   minHoursPerDay,
   minHoursPerWeek,
+  maxDaysPerWeek,
+  minDaysPerWeek,
   maxShiftsPerDay,
   maxConsecutiveDays,
   minConsecutiveDays,
   minRestBetweenShifts,
+  mustAssign,
   preference,
   preferLocation,
   timeOff,
@@ -178,7 +183,7 @@ export {
   tieredOvertimeMultiplier,
   weekdays,
   weekend,
-} from "./schedule.js";
+} from "./schedule/index.js";
 
 export type {
   CoverageEntry,
@@ -195,4 +200,4 @@ export type {
   SolveResult,
   SolveStatus,
   SolveOptions,
-} from "./schedule.js";
+} from "./schedule/index.js";