dabke 0.78.2 → 0.80.0

package/package.json

@@ -1,41 +1,38 @@
 {
   "name": "dabke",
-  "version": "0.78.2",
-  "license": "MIT",
+  "version": "0.80.0",
   "description": "Scheduling library powered by constraint programming (CP-SAT)",
-  "author": "Christian Klotz <hello@christianklotz.co.uk>",
-  "homepage": "https://github.com/christianklotz/dabke#readme",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/christianklotz/dabke.git"
-  },
-  "bugs": {
-    "url": "https://github.com/christianklotz/dabke/issues"
-  },
   "keywords": [
-    "scheduling",
-    "staff-scheduling",
     "constraint-programming",
     "cp-sat",
-    "workforce-management",
-    "optimization",
     "operations-research",
-    "or-tools"
+    "optimization",
+    "or-tools",
+    "scheduling",
+    "staff-scheduling",
+    "workforce-management"
   ],
-  "type": "module",
-  "sideEffects": false,
-  "engines": {
-    "node": ">=20"
+  "homepage": "https://github.com/christianklotz/dabke#readme",
+  "bugs": {
+    "url": "https://github.com/christianklotz/dabke/issues"
+  },
+  "license": "MIT",
+  "author": "Christian Klotz <hello@christianklotz.co.uk>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/christianklotz/dabke.git"
   },
   "files": [
+    "CHANGELOG.md",
     "dist",
-    "src",
-    "solver",
-    "llms.txt",
     "LICENSE",
+    "llms.txt",
     "README.md",
-    "CHANGELOG.md"
+    "solver",
+    "src"
   ],
+  "type": "module",
+  "sideEffects": false,
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
@@ -72,5 +69,8 @@
     "commander": "^14.0.2",
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"
+  },
+  "engines": {
+    "node": ">=20"
   }
-}
+}

package/src/client.types.ts

@@ -22,20 +22,78 @@ import type {
 // Types derived from Zod schemas
 // --------------------------------------------------------------------------
 
+/**
+ * A single linear term in a constraint or objective.
+ *
+ * - `var` (required): variable name
+ * - `coeff` (required): integer coefficient
+ */
 export type SolverTerm = z.infer<typeof SolverTermSchema>;
 
+/**
+ * A decision variable in the CP-SAT model.
+ *
+ * - `name` (required): unique variable identifier
+ * - `lb` (required): lower bound
+ * - `ub` (required): upper bound
+ * - `isBoolean` (optional): whether this is a boolean variable
+ * - `isInterval` (optional): whether this is an interval variable
+ * - `start`, `end`, `size`, `presenceVar` (optional): interval variable fields
+ */
 export type SolverVariable = z.infer<typeof SolverVariableSchema>;
 
+/**
+ * A constraint in the CP-SAT model.
+ *
+ * - `name` (required): constraint identifier
+ * - `type` (required): constraint kind (e.g. "linear", "bool_and", "no_overlap")
+ * - Additional fields vary by constraint type
+ */
 export type SolverConstraint = z.infer<typeof SolverConstraintSchema>;
 
+/**
+ * An optimization objective for the solver.
+ *
+ * - `terms` (required): linear terms to minimize/maximize
+ * - `minimize` (required): whether to minimize (true) or maximize (false)
+ */
 export type SolverObjective = z.infer<typeof SolverObjectiveSchema>;
 
+/**
+ * The full request payload sent to the CP-SAT solver service.
+ *
+ * - `variables` (required): all decision variables
+ * - `constraints` (required): all constraints
+ * - `objective` (optional): optimization objective
+ * - `timeoutSeconds` (optional): solver time limit
+ */
 export type SolverRequest = z.infer<typeof SolverRequestSchema>;
 
+/**
+ * The response payload returned by the CP-SAT solver service.
+ *
+ * - `status` (required): solve outcome (see {@link SolverStatus})
+ * - `values` (optional): variable assignments when a solution is found
+ * - `statistics` (optional): solve time, conflicts, branches
+ * - `softViolations` (optional): which soft constraints were violated
+ * - `error` (optional): error message on failure
+ * - `solutionInfo` (optional): solver diagnostic info
+ */
 export type SolverResponse = z.infer<typeof SolverResponseSchema>;
 
+/**
+ * Solver outcome status.
+ *
+ * One of `"OPTIMAL"`, `"FEASIBLE"`, `"INFEASIBLE"`, `"TIMEOUT"`, or `"ERROR"`.
+ */
 export type SolverStatus = z.infer<typeof SolverStatusSchema>;
 
+/**
+ * A soft constraint violation reported by the solver.
+ *
+ * - `constraintId` (required): which soft constraint was violated
+ * - `violationAmount` (required): magnitude of the violation
+ */
 export type SoftConstraintViolation = z.infer<typeof SoftConstraintViolationSchema>;
 
 // --------------------------------------------------------------------------

package/src/cpsat/model-builder.ts

@@ -37,8 +37,17 @@ export interface RuleValidationContext {
   readonly shiftPatterns: ShiftPattern[];
 }
 
+/**
+ * A rule that adds constraints or objectives to the solver model.
+ *
+ * Rules implement `compile` to emit solver constraints during model building,
+ * and optionally `validate` to check the solution after solving.
+ * Use the `create*Rule` functions to create built-in rules.
+ */
 export interface CompilationRule {
+  /** Emit constraints and objectives into the model builder. */
   compile(builder: ModelBuilder): void;
+  /** Validate the solved schedule and report violations. */
   validate?(
     assignments: ResolvedShiftAssignment[],
     reporter: ValidationReporter,
@@ -69,11 +78,13 @@ export interface CompilationResult {
  * ```
  */
 export interface ModelBuilderConfig extends ModelBuilderOptions {
+  /** Team members available for scheduling. */
   employees: SchedulingEmployee[];
+  /** Available shift patterns (time slots) that employees can be assigned to. */
   shiftPatterns: ShiftPattern[];
   /**
-   * Defines when scheduling should occur. Can specify either a date range
-   * (with optional day-of-week filtering) or a list of specific dates.
+   * Defines when scheduling should occur as a date range with optional
+   * `daysOfWeek` and `dates` filters that compose to narrow which days are included.
    */
   schedulingPeriod: SchedulingPeriod;
   coverage: CoverageRequirement[];
@@ -448,11 +459,12 @@ export class ModelBuilder {
       const covStart = timeOfDayToMinutes(cov.startTime);
       const covEnd = normalizeEndMinutes(covStart, timeOfDayToMinutes(cov.endTime));
       const covKey = cov.roleIds?.join(",") ?? cov.skillIds?.join(",") ?? "unknown";
-      const coverageLabel = cov.roleIds && cov.roleIds.length > 0
-        ? cov.roleIds.length === 1
-          ? `role "${cov.roleIds[0]}"`
-          : `role "${cov.roleIds.join(" or ")}"`
-        : `skills [${cov.skillIds?.join(", ")}]`;
+      const coverageLabel =
+        cov.roleIds && cov.roleIds.length > 0
+          ? cov.roleIds.length === 1
+            ? `role "${cov.roleIds[0]}"`
+            : `role "${cov.roleIds.join(" or ")}"`
+          : `skills [${cov.skillIds?.join(", ")}]`;
       const coverageWindow = formatTimeRange(covStart, covEnd);
 
       const eligibleEmployees = this.employeesForCoverage(cov);

package/src/cpsat/response.ts

@@ -2,12 +2,13 @@ import type { SolverResponse } from "../client.types.js";
 import type { ShiftPattern } from "./types.js";
 import type { TimeOfDay } from "../types.js";
 
-/**
- * A shift assignment extracted from the solver response.
- */
+/** A raw assignment from the solver: which employee works which shift on which day. */
 export interface ShiftAssignment {
+  /** The assigned employee's ID. */
   employeeId: string;
+  /** The shift pattern this employee is assigned to. */
   shiftPatternId: string;
+  /** The date of the assignment (YYYY-MM-DD). */
   day: string;
 }
 
@@ -15,9 +16,13 @@ export interface ShiftAssignment {
  * A shift assignment with resolved times.
  */
 export interface ResolvedShiftAssignment {
+  /** The assigned employee's ID. */
   employeeId: string;
+  /** The date of the assignment (YYYY-MM-DD). */
   day: string;
+  /** When the shift starts. */
   startTime: TimeOfDay;
+  /** When the shift ends. */
   endTime: TimeOfDay;
 }
 
@@ -25,9 +30,13 @@ export interface ResolvedShiftAssignment {
  * Parsed solver result with assignments and metadata.
  */
 export interface SolverResult {
+  /** The solver outcome: OPTIMAL, FEASIBLE, INFEASIBLE, TIMEOUT, or ERROR. */
   status: SolverResponse["status"];
+  /** The shift assignments extracted from the solution. */
   assignments: ShiftAssignment[];
+  /** Solver performance statistics (branches, conflicts, solve time). */
   statistics?: SolverResponse["statistics"];
+  /** Error message if the solver returned an error status. */
   error?: string;
 }
 

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

@@ -17,12 +17,19 @@ const AssignTogetherSchema = z.object({
   ]),
 });
 
+/**
+ * Configuration for {@link createAssignTogetherRule}.
+ *
+ * - `groupEmployeeIds` (required): employee IDs to assign together (at least two, must be unique)
+ * - `priority` (required): how strictly the solver enforces this rule
+ */
 export type AssignTogetherConfig = z.infer<typeof AssignTogetherSchema>;
 
 /**
  * Encourages or enforces that team members in the group work the same shift patterns on a day.
  * For each pair of team members in the group, ensures they are assigned to the same shifts.
  *
+ * @param config - See {@link AssignTogetherConfig}
  * @example
  * ```ts
  * const rule = createAssignTogetherRule({

package/src/cpsat/rules/employee-assignment-priority.ts

@@ -1,27 +1,36 @@
 import * as z from "zod";
 import type { CompilationRule } from "../model-builder.js";
-import type { SchedulingEmployee } from "../types.js";
-import { OBJECTIVE_WEIGHTS, parseDayString } from "../utils.js";
-import { normalizeScope, withScopes, type RuleScope } from "./scoping.js";
-
-const EmployeeAssignmentPrioritySchema = withScopes(
-  z.object({
+import { OBJECTIVE_WEIGHTS } from "../utils.js";
+import {
+  entityScope,
+  timeScope,
+  parseEntityScope,
+  parseTimeScope,
+  resolveEmployeesFromScope,
+  resolveActiveDaysFromScope,
+} from "./scope.types.js";
+
+const EmployeeAssignmentPrioritySchema = z
+  .object({
     preference: z.union([z.literal("high"), z.literal("low")]),
-  }),
-  {
-    entities: ["employees", "roles", "skills"],
-    times: ["dateRange", "specificDates", "dayOfWeek", "recurring"],
-  },
-);
+  })
+  .and(entityScope(["employees", "roles", "skills"]))
+  .and(timeScope(["dateRange", "specificDates", "dayOfWeek", "recurring"]));
 
+/**
+ * Configuration for {@link createEmployeeAssignmentPriorityRule}.
+ *
+ * - `preference` (required): `"high"` to prefer assigning or `"low"` to avoid assigning
+ *
+ * Entity scoping (at most one): `employeeIds`, `roleIds`, `skillIds`
+ * Time scoping (at most one, optional): `dateRange`, `specificDates`, `dayOfWeek`, `recurringPeriods`
+ */
 export type EmployeeAssignmentPriorityConfig = z.infer<typeof EmployeeAssignmentPrioritySchema>;
 
 /**
  * Adds objective weight to prefer or avoid assigning team members.
  *
- * Supports entity scoping (people, roles, skills) and time scoping
- * (date ranges, specific dates, days of week, recurring periods).
- *
+ * @param config - See {@link EmployeeAssignmentPriorityConfig}
  * @example Prefer specific team members
  * ```ts
  * createEmployeeAssignmentPriorityRule({
@@ -38,27 +47,19 @@ export type EmployeeAssignmentPriorityConfig = z.infer<typeof EmployeeAssignment
  *   preference: "low",
  * });
  * ```
- *
- * @example Prefer experienced staff on weekends
- * ```ts
- * createEmployeeAssignmentPriorityRule({
- *   skillIds: ["senior"],
- *   dayOfWeek: ["saturday", "sunday"],
- *   preference: "high",
- * });
- * ```
  */
 export function createEmployeeAssignmentPriorityRule(
   config: EmployeeAssignmentPriorityConfig,
 ): CompilationRule {
   const parsed = EmployeeAssignmentPrioritySchema.parse(config);
   const { preference } = parsed;
+  const entityScopeValue = parseEntityScope(parsed);
+  const timeScopeValue = parseTimeScope(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;
 
@@ -79,104 +80,3 @@ export function createEmployeeAssignmentPriorityRule(
     },
   };
 }
-
-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/location-preference.ts

@@ -2,10 +2,10 @@ import * as z from "zod";
 import type { CompilationRule } from "../model-builder.js";
 import type { Priority } from "../types.js";
 import { OBJECTIVE_WEIGHTS } from "../utils.js";
-import { withScopes } from "./scoping.js";
+import { entityScope, parseEntityScope, resolveEmployeesFromScope } from "./scope.types.js";
 
-const LocationPreferenceSchema = withScopes(
-  z.object({
+const LocationPreferenceSchema = z
+  .object({
     locationId: z.string(),
     priority: z.union([
       z.literal("LOW"),
@@ -13,43 +13,50 @@ const LocationPreferenceSchema = withScopes(
       z.literal("HIGH"),
       z.literal("MANDATORY"),
     ]),
-  }),
-  { entities: ["employees", "roles", "skills"], times: [] },
-);
+  })
+  .and(entityScope(["employees", "roles", "skills"]));
 
+/**
+ * Configuration for {@link createLocationPreferenceRule}.
+ *
+ * - `locationId` (required): the location ID to prefer for matching shift patterns
+ * - `priority` (required): how strongly to prefer this location
+ *
+ * Entity scoping (at most one): `employeeIds`, `roleIds`, `skillIds`
+ */
 export type LocationPreferenceConfig = z.infer<typeof LocationPreferenceSchema>;
 
 const PRIORITY_WEIGHTS: Record<Priority, number> = {
-  LOW: OBJECTIVE_WEIGHTS.FAIRNESS, // 5 - same as fairness, weak preference
-  MEDIUM: OBJECTIVE_WEIGHTS.ASSIGNMENT_PREFERENCE, // 10 - standard preference
-  HIGH: OBJECTIVE_WEIGHTS.ASSIGNMENT_PREFERENCE * 2.5, // 25 - strong preference
-  MANDATORY: OBJECTIVE_WEIGHTS.ASSIGNMENT_PREFERENCE * 5, // 50 - very strong
+  LOW: OBJECTIVE_WEIGHTS.FAIRNESS,
+  MEDIUM: OBJECTIVE_WEIGHTS.ASSIGNMENT_PREFERENCE,
+  HIGH: OBJECTIVE_WEIGHTS.ASSIGNMENT_PREFERENCE * 2.5,
+  MANDATORY: OBJECTIVE_WEIGHTS.ASSIGNMENT_PREFERENCE * 5,
 };
 
 /**
  * Prefers assigning a person to shift patterns matching a specific location.
  *
+ * @param config - See {@link LocationPreferenceConfig}
  * @example
  * ```ts
- * const rule = createLocationPreferenceRule({
+ * createLocationPreferenceRule({
  *   locationId: "terrace",
  *   priority: "HIGH",
  *   employeeIds: ["alice"],
  * });
- * builder = new ModelBuilder({ ...config, rules: [rule] });
  * ```
  */
 export function createLocationPreferenceRule(config: LocationPreferenceConfig): CompilationRule {
-  const { locationId, priority, employeeIds } = LocationPreferenceSchema.parse(config);
-  const weight = PRIORITY_WEIGHTS[priority] ?? 0;
+  const parsed = LocationPreferenceSchema.parse(config);
+  const scope = parseEntityScope(parsed);
+  const { locationId } = parsed;
+  const weight = PRIORITY_WEIGHTS[parsed.priority] ?? 0;
 
   return {
     compile(b) {
       if (weight === 0) 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) {
         for (const pattern of b.shiftPatterns) {

package/src/cpsat/rules/max-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 MaxConsecutiveDaysSchema = withScopes(
-  z.object({
+const MaxConsecutiveDaysSchema = z
+  .object({
     days: z.number().min(0),
     priority: z.union([
       z.literal("LOW"),
@@ -12,33 +12,37 @@ const MaxConsecutiveDaysSchema = withScopes(
       z.literal("HIGH"),
       z.literal("MANDATORY"),
     ]),
-  }),
-  { entities: ["employees", "roles", "skills"], times: [] },
-);
+  })
+  .and(entityScope(["employees", "roles", "skills"]));
 
+/**
+ * Configuration for {@link createMaxConsecutiveDaysRule}.
+ *
+ * - `days` (required): maximum consecutive days allowed
+ * - `priority` (required): how strictly the solver enforces this rule
+ *
+ * Entity scoping (at most one): `employeeIds`, `roleIds`, `skillIds`
+ */
 export type MaxConsecutiveDaysConfig = z.infer<typeof MaxConsecutiveDaysSchema>;
 
 /**
  * Limits how many consecutive days a person can be assigned.
  *
+ * @param config - See {@link MaxConsecutiveDaysConfig}
  * @example
  * ```ts
- * const rule = createMaxConsecutiveDaysRule({
- *   days: 5,
- *   priority: "MANDATORY",
- * });
- * builder = new ModelBuilder({ ...config, rules: [rule] });
+ * createMaxConsecutiveDaysRule({ days: 5, priority: "MANDATORY" });
  * ```
  */
 export function createMaxConsecutiveDaysRule(config: MaxConsecutiveDaysConfig): CompilationRule {
-  const { days, priority, employeeIds } = MaxConsecutiveDaysSchema.parse(config);
+  const parsed = MaxConsecutiveDaysSchema.parse(config);
+  const scope = parseEntityScope(parsed);
+  const { days, priority } = parsed;
   const windowSize = days + 1;
 
   return {
     compile(b) {
-      const employees = employeeIds
-        ? b.employees.filter((e) => employeeIds.includes(e.id))
-        : b.employees;
+      const employees = resolveEmployeesFromScope(scope, b.employees);
 
       for (const emp of employees) {
         for (let i = 0; i <= b.days.length - windowSize; i++) {