dabke 0.78.0

package/src/cpsat/response.ts

@@ -0,0 +1,130 @@
+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.
+ */
+export interface ShiftAssignment {
+  employeeId: string;
+  shiftPatternId: string;
+  day: string;
+}
+
+/**
+ * A shift assignment with resolved times.
+ */
+export interface ResolvedShiftAssignment {
+  employeeId: string;
+  day: string;
+  startTime: TimeOfDay;
+  endTime: TimeOfDay;
+}
+
+/**
+ * Parsed solver result with assignments and metadata.
+ */
+export interface SolverResult {
+  status: SolverResponse["status"];
+  assignments: ShiftAssignment[];
+  statistics?: SolverResponse["statistics"];
+  error?: string;
+}
+
+/**
+ * Extracts shift assignments from solver response.
+ *
+ * Parses variable names matching the pattern `assign:${employeeId}:${patternId}:${day}`
+ * and returns assignments where the variable value is 1 (true).
+ *
+ * @remarks
+ * IDs are validated by ModelBuilder to not contain colons,
+ * ensuring unambiguous parsing.
+ *
+ * @param response - The solver response containing variable values
+ * @returns Parsed schedule result with assignments
+ *
+ * @example
+ * ```typescript
+ * const response = await client.solve(request);
+ * const result = parseSolverResponse(response);
+ *
+ * if (result.status === "OPTIMAL" || result.status === "FEASIBLE") {
+ *   for (const assignment of result.assignments) {
+ *     console.log(`${assignment.employeeId} works ${assignment.shiftPatternId} on ${assignment.day}`);
+ *   }
+ * }
+ * ```
+ */
+export function parseSolverResponse(response: SolverResponse): SolverResult {
+  if (response.status === "INFEASIBLE" || response.status === "ERROR") {
+    return {
+      status: response.status,
+      assignments: [],
+      statistics: response.statistics,
+      error: response.error,
+    };
+  }
+
+  const assignments: ShiftAssignment[] = [];
+
+  for (const [varName, value] of Object.entries(response.values ?? {})) {
+    if (value !== 1) continue;
+    if (!varName.startsWith("assign:")) continue;
+
+    // Pattern: assign:${employeeId}:${patternId}:${day}
+    // IDs are validated to not contain colons, so splitting is unambiguous.
+    const parts = varName.split(":");
+    if (parts.length !== 4) continue;
+
+    const [, employeeId, shiftPatternId, day] = parts;
+    if (!employeeId || !shiftPatternId || !day) continue;
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(day)) continue;
+
+    assignments.push({ employeeId, shiftPatternId, day });
+  }
+
+  return {
+    status: response.status,
+    assignments,
+    statistics: response.statistics,
+  };
+}
+
+/**
+ * Resolves shift assignments to concrete times using shift patterns.
+ *
+ * @param assignments - Raw assignments from parseScheduleResult
+ * @param shiftPatterns - The shift patterns used in the model
+ * @returns Assignments with resolved start/end times
+ *
+ * @example
+ * ```typescript
+ * const result = parseScheduleResult(response);
+ * const resolved = resolveAssignments(result.assignments, shiftPatterns);
+ *
+ * for (const shift of resolved) {
+ *   console.log(`${shift.employeeId} works ${shift.day} from ${shift.startTime.hours}:${shift.startTime.minutes}`);
+ * }
+ * ```
+ */
+export function resolveAssignments(
+  assignments: ShiftAssignment[],
+  shiftPatterns: ShiftPattern[],
+): ResolvedShiftAssignment[] {
+  const patternMap = new Map(shiftPatterns.map((p) => [p.id, p]));
+
+  return assignments
+    .map((a) => {
+      const pattern = patternMap.get(a.shiftPatternId);
+      if (!pattern) return null;
+
+      return {
+        employeeId: a.employeeId,
+        day: a.day,
+        startTime: pattern.startTime,
+        endTime: pattern.endTime,
+      };
+    })
+    .filter((a): a is ResolvedShiftAssignment => a !== null);
+}

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

@@ -0,0 +1,96 @@
+import * as z from "zod";
+import type { CompilationRule } from "../model-builder.js";
+import { priorityToPenalty } from "../utils.js";
+
+const AssignTogetherSchema = z.object({
+  groupEmployeeIds: z
+    .tuple([z.string(), z.string()])
+    .rest(z.string())
+    .refine((ids) => new Set(ids).size === ids.length, {
+      message: "IDs must be unique",
+    }),
+  priority: z.union([
+    z.literal("LOW"),
+    z.literal("MEDIUM"),
+    z.literal("HIGH"),
+    z.literal("MANDATORY"),
+  ]),
+});
+
+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.
+ *
+ * @example
+ * ```ts
+ * const rule = createAssignTogetherRule({
+ *   groupEmployeeIds: ["alice", "bob", "charlie"],
+ *   priority: "HIGH",
+ * });
+ * builder = new ModelBuilder({ ...config, rules: [rule] });
+ * ```
+ */
+export function createAssignTogetherRule(config: AssignTogetherConfig): CompilationRule {
+  const { groupEmployeeIds, priority } = AssignTogetherSchema.parse(config);
+
+  return {
+    compile(b) {
+      const employees = groupEmployeeIds
+        .map((id) => b.employees.find((e) => e.id === id))
+        .filter((e): e is NonNullable<typeof e> => e !== undefined);
+
+      if (employees.length < 2) return;
+
+      for (let i = 0; i < employees.length - 1; i++) {
+        const emp1 = employees[i]!;
+        const emp2 = employees[i + 1]!;
+
+        for (const pattern of b.shiftPatterns) {
+          const canAssign1 = b.canAssign(emp1, pattern);
+          const canAssign2 = b.canAssign(emp2, pattern);
+          if (!canAssign1 || !canAssign2) continue;
+
+          for (const day of b.days) {
+            if (!b.patternAvailableOnDay(pattern, day)) continue;
+            const var1 = b.assignment(emp1.id, pattern.id, day);
+            const var2 = b.assignment(emp2.id, pattern.id, day);
+
+            if (priority === "MANDATORY") {
+              b.addLinear(
+                [
+                  { var: var1, coeff: 1 },
+                  { var: var2, coeff: -1 },
+                ],
+                "==",
+                0,
+              );
+            } else {
+              const diffVar = b.boolVar(`together_diff_${emp1.id}_${emp2.id}_${pattern.id}_${day}`);
+              b.addLinear(
+                [
+                  { var: diffVar, coeff: 1 },
+                  { var: var1, coeff: -1 },
+                  { var: var2, coeff: 1 },
+                ],
+                ">=",
+                0,
+              );
+              b.addLinear(
+                [
+                  { var: diffVar, coeff: 1 },
+                  { var: var1, coeff: 1 },
+                  { var: var2, coeff: -1 },
+                ],
+                ">=",
+                0,
+              );
+              b.addPenalty(diffVar, priorityToPenalty(priority));
+            }
+          }
+        }
+      }
+    },
+  };
+}

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

@@ -0,0 +1,182 @@
+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({
+    preference: z.union([z.literal("high"), z.literal("low")]),
+  }),
+  {
+    entities: ["employees", "roles", "skills"],
+    times: ["dateRange", "specificDates", "dayOfWeek", "recurring"],
+  },
+);
+
+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).
+ *
+ * @example Prefer specific team members
+ * ```ts
+ * createEmployeeAssignmentPriorityRule({
+ *   employeeIds: ["alice", "bob"],
+ *   preference: "high",
+ * });
+ * ```
+ *
+ * @example Avoid assigning students on weekdays
+ * ```ts
+ * createEmployeeAssignmentPriorityRule({
+ *   roleIds: ["student"],
+ *   dayOfWeek: ["monday", "tuesday", "wednesday", "thursday", "friday"],
+ *   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;
+
+  return {
+    compile(b) {
+      const scope = normalizeScope(parsed, b.employees);
+      const targetEmployees = resolveEmployees(scope, b.employees);
+      const activeDays = resolveActiveDays(scope, b.days);
+
+      if (targetEmployees.length === 0 || activeDays.length === 0) return;
+
+      const weight =
+        preference === "high"
+          ? -OBJECTIVE_WEIGHTS.ASSIGNMENT_PREFERENCE
+          : OBJECTIVE_WEIGHTS.ASSIGNMENT_PREFERENCE;
+
+      for (const emp of targetEmployees) {
+        for (const pattern of b.shiftPatterns) {
+          if (!b.canAssign(emp, pattern)) continue;
+          for (const day of activeDays) {
+            if (!b.patternAvailableOnDay(pattern, day)) continue;
+            b.addPenalty(b.assignment(emp.id, pattern.id, day), weight);
+          }
+        }
+      }
+    },
+  };
+}
+
+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/index.ts

@@ -0,0 +1,12 @@
+export { createAssignTogetherRule } from "./assign-together.js";
+export { createEmployeeAssignmentPriorityRule } from "./employee-assignment-priority.js";
+export { createLocationPreferenceRule } from "./location-preference.js";
+export { createMaxConsecutiveDaysRule } from "./max-consecutive-days.js";
+export { createMaxHoursDayRule } from "./max-hours-day.js";
+export { createMaxHoursWeekRule } from "./max-hours-week.js";
+export { createMaxShiftsDayRule } from "./max-shifts-day.js";
+export { createMinConsecutiveDaysRule } from "./min-consecutive-days.js";
+export { createMinHoursDayRule } from "./min-hours-day.js";
+export { createMinHoursWeekRule } from "./min-hours-week.js";
+export { createMinRestBetweenShiftsRule } from "./min-rest-between-shifts.js";
+export { createTimeOffRule } from "./time-off.js";

package/src/cpsat/rules/location-preference.ts

@@ -0,0 +1,68 @@
+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";
+
+const LocationPreferenceSchema = withScopes(
+  z.object({
+    locationId: z.string(),
+    priority: z.union([
+      z.literal("LOW"),
+      z.literal("MEDIUM"),
+      z.literal("HIGH"),
+      z.literal("MANDATORY"),
+    ]),
+  }),
+  { entities: ["employees", "roles", "skills"], times: [] },
+);
+
+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
+};
+
+/**
+ * Prefers assigning a person to shift patterns matching a specific location.
+ *
+ * @example
+ * ```ts
+ * const rule = 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;
+
+  return {
+    compile(b) {
+      if (weight === 0) return;
+
+      const employees = employeeIds
+        ? b.employees.filter((e) => employeeIds.includes(e.id))
+        : b.employees;
+
+      for (const emp of employees) {
+        for (const pattern of b.shiftPatterns) {
+          if (!b.canAssign(emp, pattern)) continue;
+          const isPreferred = pattern.locationId === locationId;
+          if (isPreferred) continue;
+
+          for (const day of b.days) {
+            if (!b.patternAvailableOnDay(pattern, day)) continue;
+            b.addPenalty(b.assignment(emp.id, pattern.id, day), weight);
+          }
+        }
+      }
+    },
+  };
+}

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

@@ -0,0 +1,98 @@
+import * as z from "zod";
+import type { CompilationRule } from "../model-builder.js";
+import { priorityToPenalty } from "../utils.js";
+import { withScopes } from "./scoping.js";
+
+const MaxConsecutiveDaysSchema = withScopes(
+  z.object({
+    days: z.number().min(0),
+    priority: z.union([
+      z.literal("LOW"),
+      z.literal("MEDIUM"),
+      z.literal("HIGH"),
+      z.literal("MANDATORY"),
+    ]),
+  }),
+  { entities: ["employees", "roles", "skills"], times: [] },
+);
+
+export type MaxConsecutiveDaysConfig = z.infer<typeof MaxConsecutiveDaysSchema>;
+
+/**
+ * Limits how many consecutive days a person can be assigned.
+ *
+ * @example
+ * ```ts
+ * const rule = createMaxConsecutiveDaysRule({
+ *   days: 5,
+ *   priority: "MANDATORY",
+ * });
+ * builder = new ModelBuilder({ ...config, rules: [rule] });
+ * ```
+ */
+export function createMaxConsecutiveDaysRule(config: MaxConsecutiveDaysConfig): CompilationRule {
+  const { days, priority, employeeIds } = MaxConsecutiveDaysSchema.parse(config);
+  const windowSize = days + 1;
+
+  return {
+    compile(b) {
+      const employees = employeeIds
+        ? b.employees.filter((e) => employeeIds.includes(e.id))
+        : b.employees;
+
+      for (const emp of employees) {
+        for (let i = 0; i <= b.days.length - windowSize; i++) {
+          const windowDays = b.days.slice(i, i + windowSize);
+
+          const worksDayVars: string[] = [];
+          for (const day of windowDays) {
+            const worksVar = b.boolVar(`works_${emp.id}_${day}`);
+            worksDayVars.push(worksVar);
+
+            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) {
+              b.addLinear([{ var: worksVar, coeff: 1 }], "==", 0);
+            } else {
+              for (const assignVar of dayAssignments) {
+                b.addLinear(
+                  [
+                    { var: worksVar, coeff: 1 },
+                    { var: assignVar, coeff: -1 },
+                  ],
+                  ">=",
+                  0,
+                );
+              }
+              b.addLinear(
+                [
+                  { var: worksVar, coeff: 1 },
+                  ...dayAssignments.map((v) => ({ var: v, coeff: -1 })),
+                ],
+                "<=",
+                0,
+              );
+            }
+          }
+
+          if (priority === "MANDATORY") {
+            b.addLinear(
+              worksDayVars.map((v) => ({ var: v, coeff: 1 })),
+              "<=",
+              days,
+            );
+          } else {
+            b.addSoftLinear(
+              worksDayVars.map((v) => ({ var: v, coeff: 1 })),
+              "<=",
+              days,
+              priorityToPenalty(priority),
+            );
+          }
+        }
+      }
+    },
+  };
+}