dabke 0.82.0 → 0.83.0

package/dist/{schedule.js → schedule/definition.js}

@@ -1,630 +1,15 @@
 /**
- * High-level schedule definition API.
- *
- * Small, composable factory functions that produce a complete scheduling
- * configuration. Designed for LLM code generation: each concept is a single
- * function call with per-call type safety.
- *
- * @example
- * ```typescript
- * import {
- *   schedule, t, time, cover, shift,
- *   maxHoursPerDay, maxHoursPerWeek, minRestBetweenShifts,
- *   weekdays, weekend,
- * } from "dabke";
- *
- * const venue = schedule({
- *   roleIds: ["cashier", "floor_lead", "stocker"],
- *   skillIds: ["keyholder"],
- *
- *   times: {
- *     opening: time({ startTime: t(8), endTime: t(10) }),
- *     peak_hours: time(
- *       { startTime: t(11), endTime: t(14) },
- *       { startTime: t(10), endTime: t(15), dayOfWeek: weekend },
- *     ),
- *     closing: time({ startTime: t(20), endTime: t(22) }),
- *   },
- *
- *   coverage: [
- *     cover("opening", "keyholder", 1),
- *     cover("peak_hours", "cashier", 3, { dayOfWeek: weekdays }),
- *     cover("peak_hours", "cashier", 5, { dayOfWeek: weekend }),
- *     cover("closing", "floor_lead", 1),
- *   ],
- *
- *   shiftPatterns: [
- *     shift("morning", t(8), t(14)),
- *     shift("afternoon", t(14), t(22)),
- *   ],
- *
- *   rules: [
- *     maxHoursPerDay(10),
- *     maxHoursPerWeek(48),
- *     minRestBetweenShifts(10),
- *   ],
- * });
- *
- * const result = await venue
- *   .with([
- *     { id: "alice", roleIds: ["cashier"], skillIds: ["keyholder"] },
- *   ])
- *   .solve(client, { dateRange: { start: "2025-03-03", end: "2025-03-09" } });
- * ```
+ * Schedule definition, compilation, and solving.
  *
  * @module
  */
-import { defineSemanticTimes } from "./cpsat/semantic-time.js";
-import { resolveDaysFromPeriod } from "./datetime.utils.js";
-import { ModelBuilder } from "./cpsat/model-builder.js";
-import { builtInCpsatRuleFactories } from "./cpsat/rules/registry.js";
-import { parseSolverResponse, resolveAssignments } from "./cpsat/response.js";
-import { calculateScheduleCost } from "./cpsat/cost.js";
-// ============================================================================
-// Primitives
-// ============================================================================
-/**
- * Creates a {@link TimeOfDay} value.
- *
- * @param hours - Hour component (0-23)
- * @param minutes - Minute component (0-59)
- *
- * @example Hours only
- * ```ts
- * t(9)   // { hours: 9, minutes: 0 }
- * ```
- *
- * @example Hours and minutes
- * ```ts
- * t(17, 30)  // { hours: 17, minutes: 30 }
- * ```
- *
- * @category Time Periods
- */
-export function t(hours, minutes = 0) {
-    return { hours, minutes };
-}
-/**
- * Monday through Friday.
- *
- * @category Time Periods
- */
-export const weekdays = [
-    "monday",
-    "tuesday",
-    "wednesday",
-    "thursday",
-    "friday",
-];
-/**
- * Saturday and Sunday.
- *
- * @category Time Periods
- */
-export const weekend = ["saturday", "sunday"];
-// ============================================================================
-// Semantic Times
-// ============================================================================
-/**
- * Define a named semantic time period.
- *
- * @remarks
- * Each entry has `startTime`/`endTime` and optional `dayOfWeek` or `dates`
- * scoping. Entries without scoping are the default.
- *
- * @example
- * ```typescript
- * times: {
- *   // Simple: same times every day
- *   lunch: time({ startTime: t(12), endTime: t(15) }),
- *
- *   // Variants: different times on weekends
- *   dinner: time(
- *     { startTime: t(17), endTime: t(21) },
- *     { startTime: t(18), endTime: t(22), dayOfWeek: weekend },
- *   ),
- *
- *   // Point-in-time window (keyholder at opening)
- *   opening: time({ startTime: t(8, 30), endTime: t(9) }),
- * }
- * ```
- *
- * @privateRemarks
- * Resolution precedence: `dates` > `dayOfWeek` > default.
- *
- * @category Time Periods
- */
-export function time(...entries) {
-    // Validate: at most one default (no dayOfWeek and no dates)
-    const defaults = entries.filter((e) => !e.dayOfWeek && !e.dates);
-    if (defaults.length > 1) {
-        throw new Error("time() accepts at most one default entry (without dayOfWeek or dates). " +
-            `Found ${defaults.length} default entries.`);
-    }
-    // Single entry without scoping: simple SemanticTimeDef
-    if (entries.length === 1 && !entries[0].dayOfWeek && !entries[0].dates) {
-        return {
-            startTime: entries[0].startTime,
-            endTime: entries[0].endTime,
-        };
-    }
-    // Multiple entries or scoped entries: shallow-copy to decouple from caller
-    return entries.map((entry) => Object.assign({}, entry));
-}
-export function cover(timeName, target, countOrFirstVariant, ...rest) {
-    if (typeof countOrFirstVariant === "number") {
-        // Simple form: cover(time, target, count, opts?)
-        return {
-            _type: "coverage",
-            timeName,
-            target,
-            count: countOrFirstVariant,
-            options: rest[0] ?? {},
-        };
-    }
-    // Variant form: cover(time, target, ...variants)
-    const variants = [countOrFirstVariant, ...rest];
-    const defaults = variants.filter((v) => !v.dayOfWeek && !v.dates);
-    if (defaults.length > 1) {
-        throw new Error("cover() accepts at most one default variant (without dayOfWeek or dates). " +
-            `Found ${defaults.length} default variants.`);
-    }
-    return {
-        _type: "coverage",
-        timeName,
-        target,
-        count: 0,
-        options: {},
-        variants,
-    };
-}
-// ============================================================================
-// Shift Patterns
-// ============================================================================
-/**
- * Define a shift pattern: a time slot available for employee assignment.
- *
- * @remarks
- * Each pattern repeats daily unless filtered by `dayOfWeek`.
- *
- * @example
- * ```typescript
- * shiftPatterns: [
- *   shift("morning", t(11, 30), t(15)),
- *   shift("evening", t(17), t(22)),
- *
- *   // Role-restricted shift
- *   shift("kitchen", t(6), t(14), { roleIds: ["chef", "prep_cook"] }),
- *
- *   // Day-restricted shift
- *   shift("saturday_short", t(9), t(14), { dayOfWeek: ["saturday"] }),
- *
- *   // Location-specific shift
- *   shift("terrace_lunch", t(12), t(16), { locationId: "terrace" }),
- * ]
- * ```
- *
- * @category Shift Patterns
- */
-export function shift(id, startTime, endTime, opts) {
-    const pattern = { id, startTime, endTime };
-    if (opts?.roleIds)
-        pattern.roleIds = opts.roleIds;
-    if (opts?.dayOfWeek)
-        pattern.dayOfWeek = opts.dayOfWeek;
-    if (opts?.locationId)
-        pattern.locationId = opts.locationId;
-    return pattern;
-}
-/**
- * Creates a rule entry for use in {@link ScheduleConfig.rules}.
- *
- * Built-in rules use the helpers (`maxHoursPerDay`, `timeOff`, etc.).
- * Custom rules can use `defineRule` to create entries that plug into the
- * same resolution and compilation pipeline.
- *
- * @param name - Rule name. Must match a key in the rule factory registry.
- * @param fields - Rule-specific configuration fields.
- * @param resolve - Optional custom resolver. When omitted, the default
- *   resolution applies: `appliesTo` is mapped to `roleIds`/`skillIds`/`memberIds`,
- *   `dates` is renamed to `specificDates`, and all other fields pass through.
- *
- * @category Rules
- */
-export function defineRule(name, fields, resolve) {
-    const { _type: _, _rule: __, ...safeFields } = fields;
-    const entry = { _type: "rule", _rule: name, ...safeFields };
-    if (resolve) {
-        Object.defineProperty(entry, "_resolve", { value: resolve, enumerable: false });
-    }
-    return entry;
-}
-function makeRule(rule, fields) {
-    return defineRule(rule, fields);
-}
-/**
- * Limits hours per day.
- *
- * @example
- * ```typescript
- * maxHoursPerDay(10)
- * maxHoursPerDay(4, { appliesTo: "student", dayOfWeek: weekdays })
- * ```
- *
- * @category Rules
- */
-export function maxHoursPerDay(hours, opts) {
-    return makeRule("max-hours-day", { hours, ...opts });
-}
-/**
- * Limits hours per scheduling week.
- *
- * @example
- * ```typescript
- * maxHoursPerWeek(48)
- * maxHoursPerWeek(20, { appliesTo: "student" })
- * ```
- *
- * @category Rules
- */
-export function maxHoursPerWeek(hours, opts) {
-    return makeRule("max-hours-week", { hours, ...opts });
-}
-/**
- * Minimum hours when assigned on a day.
- *
- * @example
- * ```typescript
- * minHoursPerDay(4)
- * ```
- *
- * @category Rules
- */
-export function minHoursPerDay(hours, opts) {
-    return makeRule("min-hours-day", { hours, ...opts });
-}
-/**
- * Minimum hours per scheduling week.
- *
- * @example
- * ```typescript
- * minHoursPerWeek(20, { priority: "HIGH" })
- * ```
- *
- * @category Rules
- */
-export function minHoursPerWeek(hours, opts) {
-    return makeRule("min-hours-week", { hours, ...opts });
-}
-/**
- * Maximum distinct shifts per day.
- *
- * @example
- * ```typescript
- * maxShiftsPerDay(1)
- * maxShiftsPerDay(2, { appliesTo: "student", dayOfWeek: weekend })
- * ```
- *
- * @category Rules
- */
-export function maxShiftsPerDay(shifts, opts) {
-    return makeRule("max-shifts-day", { shifts, ...opts });
-}
-/**
- * Maximum consecutive working days.
- *
- * @example
- * ```typescript
- * maxConsecutiveDays(5)
- * ```
- *
- * @category Rules
- */
-export function maxConsecutiveDays(days, opts) {
-    return makeRule("max-consecutive-days", { days, ...opts });
-}
-/**
- * Once working, continue for at least this many consecutive days.
- *
- * @example
- * ```typescript
- * minConsecutiveDays(2, { priority: "HIGH" })
- * ```
- *
- * @category Rules
- */
-export function minConsecutiveDays(days, opts) {
-    return makeRule("min-consecutive-days", { days, ...opts });
-}
-/**
- * Minimum rest hours between shifts.
- *
- * @example
- * ```typescript
- * minRestBetweenShifts(10)
- * ```
- *
- * @category Rules
- */
-export function minRestBetweenShifts(hours, opts) {
-    return makeRule("min-rest-between-shifts", { hours, ...opts });
-}
-/**
- * Prefer (`"high"`) or avoid (`"low"`) assigning. Requires `appliesTo`.
- *
- * @example
- * ```typescript
- * preference("high", { appliesTo: "waiter" })
- * preference("low", { appliesTo: "student", dayOfWeek: weekdays })
- * ```
- *
- * @category Rules
- */
-export function preference(level, opts) {
-    return makeRule("assignment-priority", { preference: level, ...opts });
-}
-/**
- * Prefer assigning to shifts at a specific location. Requires `appliesTo`.
- *
- * @example
- * ```typescript
- * preferLocation("terrace", { appliesTo: "alice" })
- * ```
- *
- * @category Rules
- */
-export function preferLocation(locationId, opts) {
-    return makeRule("location-preference", { locationId, ...opts });
-}
-/**
- * Tells the solver to minimize total labor cost.
- *
- * @remarks
- * Without this rule, cost modifiers only affect post-solve calculation.
- * When present, the solver actively prefers cheaper assignments.
- *
- * For hourly members, penalizes each assignment proportionally to cost.
- * For salaried members, adds a fixed weekly salary cost when they have
- * any assignment that week (zero marginal cost up to contracted hours).
- *
- * Cost modifiers adjust the calculation:
- * - `dayMultiplier(factor, opts?)` - multiply base rate on specific days
- * - `daySurcharge(amount, opts?)` - flat extra per hour on specific days
- * - `timeSurcharge(amount, window, opts?)` - flat extra per hour during a time window
- * - `overtimeMultiplier({ after, factor }, opts?)` - weekly overtime multiplier
- * - `overtimeSurcharge({ after, amount }, opts?)` - weekly overtime surcharge
- * - `dailyOvertimeMultiplier({ after, factor }, opts?)` - daily overtime multiplier
- * - `dailyOvertimeSurcharge({ after, amount }, opts?)` - daily overtime surcharge
- * - `tieredOvertimeMultiplier(tiers, opts?)` - multiple overtime thresholds
- *
- * @example
- * ```ts
- * minimizeCost()
- * ```
- *
- * @category Cost Optimization
- */
-export function minimizeCost(opts) {
-    return makeRule("minimize-cost", { ...opts });
-}
-/**
- * Multiplies the base rate for assignments on specified days.
- *
- * @remarks
- * The base cost (1x) is already counted by {@link minimizeCost};
- * this rule adds only the extra portion above 1x.
- *
- * @category Cost Optimization
- *
- * @example Weekend multiplier
- * ```typescript
- * dayMultiplier(1.5, { dayOfWeek: weekend })
- * ```
- */
-export function dayMultiplier(factor, opts) {
-    return makeRule("day-cost-multiplier", { factor, ...opts });
-}
-/**
- * Adds a flat extra amount per hour for assignments on specified days.
- *
- * @remarks
- * The surcharge is independent of the member's base rate.
- *
- * @category Cost Optimization
- *
- * @example Weekend surcharge
- * ```typescript
- * daySurcharge(500, { dayOfWeek: weekend })
- * ```
- */
-export function daySurcharge(amountPerHour, opts) {
-    return makeRule("day-cost-surcharge", { amountPerHour, ...opts });
-}
-/**
- * Adds a flat surcharge per hour for the portion of a shift that overlaps a time-of-day window.
- *
- * @remarks
- * The window supports overnight spans (e.g., 22:00-06:00). The surcharge
- * is independent of the member's base rate.
- *
- * @param amountPerHour - Flat surcharge per hour in smallest currency unit
- * @param window - Time-of-day window
- * @param opts - Entity and time scoping
- *
- * @category Cost Optimization
- *
- * @example Night differential
- * ```typescript
- * timeSurcharge(200, { from: t(22), until: t(6) })
- * ```
- */
-export function timeSurcharge(amountPerHour, window, opts) {
-    return makeRule("time-cost-surcharge", { amountPerHour, window, ...opts });
-}
-/**
- * Applies a multiplier to hours beyond a weekly threshold.
- *
- * @remarks
- * Only the extra portion above 1x is added (the base cost is already
- * counted by {@link minimizeCost}).
- *
- * @category Cost Optimization
- *
- * @example
- * ```typescript
- * overtimeMultiplier({ after: 40, factor: 1.5 })
- * ```
- */
-export function overtimeMultiplier(opts) {
-    return makeRule("overtime-weekly-multiplier", { ...opts });
-}
-/**
- * Adds a flat surcharge per hour beyond a weekly threshold.
- *
- * @remarks
- * The surcharge is independent of the member's base rate.
- *
- * @category Cost Optimization
- *
- * @example
- * ```typescript
- * overtimeSurcharge({ after: 40, amount: 1000 })
- * ```
- */
-export function overtimeSurcharge(opts) {
-    return makeRule("overtime-weekly-surcharge", { ...opts });
-}
-/**
- * Applies a multiplier to hours beyond a daily threshold.
- *
- * @remarks
- * Only the extra portion above 1x is added (the base cost is already
- * counted by {@link minimizeCost}).
- *
- * @category Cost Optimization
- *
- * @example
- * ```typescript
- * dailyOvertimeMultiplier({ after: 8, factor: 1.5 })
- * ```
- */
-export function dailyOvertimeMultiplier(opts) {
-    return makeRule("overtime-daily-multiplier", { ...opts });
-}
-/**
- * Adds a flat surcharge per hour beyond a daily threshold.
- *
- * @remarks
- * The surcharge is independent of the member's base rate.
- *
- * @category Cost Optimization
- *
- * @example
- * ```typescript
- * dailyOvertimeSurcharge({ after: 8, amount: 500 })
- * ```
- */
-export function dailyOvertimeSurcharge(opts) {
-    return makeRule("overtime-daily-surcharge", { ...opts });
-}
-/**
- * Applies multiple overtime thresholds with increasing multipliers.
- *
- * @remarks
- * Each tier applies only to the hours between its threshold and the next.
- * Tiers must be sorted by threshold ascending.
- *
- * @category Cost Optimization
- *
- * @example
- * ```typescript
- * // Hours 0-40: base rate
- * // Hours 40-48: 1.5x
- * // Hours 48+: 2.0x
- * tieredOvertimeMultiplier([
- *   { after: 40, factor: 1.5 },
- *   { after: 48, factor: 2.0 },
- * ])
- * ```
- */
-export function tieredOvertimeMultiplier(tiers, opts) {
-    return makeRule("overtime-tiered-multiplier", { tiers, ...opts });
-}
-/**
- * Block assignments during specified periods.
- * Requires at least one time scope (`dayOfWeek`, `dateRange`, `dates`, or `from`/`until`).
- *
- * @example
- * ```typescript
- * // Full days off
- * timeOff({ appliesTo: "alice", dateRange: { start: "2024-02-01", end: "2024-02-05" } })
- *
- * // Every weekend off
- * timeOff({ appliesTo: "mauro", dayOfWeek: weekend })
- *
- * // Wednesday afternoons off
- * timeOff({ appliesTo: "student", dayOfWeek: ["wednesday"], from: t(14) })
- * ```
- *
- * @category Rules
- */
-export function timeOff(opts) {
-    const { from, until, ...rest } = opts;
-    return defineRule("time-off", { from, until, ...rest }, (ctx) => {
-        if (!rest.dayOfWeek && !rest.dateRange && !rest.dates && !rest.recurringPeriods) {
-            throw new Error("timeOff() requires at least one time scope (dayOfWeek, dateRange, dates, or recurringPeriods).");
-        }
-        const { appliesTo, dates, ...passthrough } = rest;
-        const entityScope = resolveAppliesTo(appliesTo, ctx.roles, ctx.skills, ctx.memberIds);
-        const resolvedDates = dates ? { specificDates: dates } : {};
-        const partialDay = {};
-        if (from && until) {
-            partialDay.startTime = from;
-            partialDay.endTime = until;
-        }
-        else if (from) {
-            partialDay.startTime = from;
-            partialDay.endTime = { hours: 23, minutes: 59 };
-        }
-        else if (until) {
-            partialDay.startTime = { hours: 0, minutes: 0 };
-            partialDay.endTime = until;
-        }
-        return {
-            name: "time-off",
-            ...passthrough,
-            ...entityScope,
-            ...resolvedDates,
-            ...partialDay,
-        };
-    });
-}
-/**
- * Members work the same shifts on days they are both assigned.
- *
- * @example
- * ```typescript
- * assignTogether(["alice", "bob"])
- * assignTogether(["alice", "bob", "charlie"], { priority: "HIGH" })
- * ```
- *
- * @category Rules
- */
-export function assignTogether(memberIds, opts) {
-    return defineRule("assign-together", { members: memberIds, ...opts }, (ctx) => {
-        for (const member of memberIds) {
-            if (!ctx.memberIds.has(member)) {
-                throw new Error(`assignTogether references unknown member "${member}". ` +
-                    `Known member IDs: ${[...ctx.memberIds].join(", ")}`);
-            }
-        }
-        return {
-            name: "assign-together",
-            groupMemberIds: memberIds,
-            ...opts,
-        };
-    });
-}
+import { defineSemanticTimes } from "../cpsat/semantic-time.js";
+import { resolveDaysFromPeriod } from "../datetime.utils.js";
+import { ModelBuilder } from "../cpsat/model-builder.js";
+import { builtInCpsatRuleFactories } from "../cpsat/rules/registry.js";
+import { parseSolverResponse, resolveAssignments } from "../cpsat/response.js";
+import { calculateScheduleCost } from "../cpsat/cost.js";
+import { resolveAppliesTo } from "./rules.js";
 // ============================================================================
 // Schedule class
 // ============================================================================
@@ -1220,55 +605,6 @@ function buildVariantCoverageRequirement(entry, roles, skills) {
 // ============================================================================
 // Internal: Rule Translation
 // ============================================================================
-/**
- * Resolves an `appliesTo` value into entity scope fields.
- *
- * Each target string is checked against roles, skills, then member IDs.
- * If all targets resolve to the same namespace, they are combined into one
- * scope field. If they span namespaces, an error is thrown; the caller
- * should use separate rule entries instead.
- */
-function resolveAppliesTo(appliesTo, roles, skills, memberIds) {
-    if (!appliesTo)
-        return {};
-    const targets = Array.isArray(appliesTo) ? appliesTo : [appliesTo];
-    if (targets.length === 0)
-        return {};
-    const resolvedRoles = [];
-    const resolvedSkills = [];
-    const resolvedMembers = [];
-    for (const target of targets) {
-        if (roles.has(target)) {
-            resolvedRoles.push(target);
-        }
-        else if (skills.has(target)) {
-            resolvedSkills.push(target);
-        }
-        else if (memberIds.has(target)) {
-            resolvedMembers.push(target);
-        }
-        else {
-            throw new Error(`appliesTo target "${target}" is not a declared role, skill, or member ID.`);
-        }
-    }
-    // Count how many namespaces were used
-    const namespacesUsed = [resolvedRoles, resolvedSkills, resolvedMembers].filter((arr) => arr.length > 0).length;
-    if (namespacesUsed > 1) {
-        throw new Error(`appliesTo targets span multiple namespaces (roles: [${resolvedRoles.join(", ")}], ` +
-            `skills: [${resolvedSkills.join(", ")}], members: [${resolvedMembers.join(", ")}]). ` +
-            `Use separate rule entries for each namespace.`);
-    }
-    if (resolvedRoles.length > 0) {
-        return { roleIds: resolvedRoles };
-    }
-    if (resolvedSkills.length > 0) {
-        return { skillIds: resolvedSkills };
-    }
-    if (resolvedMembers.length > 0) {
-        return { memberIds: resolvedMembers };
-    }
-    return {};
-}
 function resolveRules(rules, roles, skills, memberIds) {
     const ctx = { roles, skills, memberIds };
     return rules.map((rule) => {
@@ -1320,4 +656,4 @@ function applyDaysFilter(schedulingPeriod, dayOfWeek) {
     const intersected = dayOfWeek.filter((day) => existingSet.has(day));
     return { ...schedulingPeriod, dayOfWeek: intersected };
 }
-//# sourceMappingURL=schedule.js.map
+//# sourceMappingURL=definition.js.map