dabke 0.82.0 → 0.83.0

package/dist/schedule/definition.d.ts

@@ -0,0 +1,227 @@
+/**
+ * Schedule definition, compilation, and solving.
+ *
+ * @module
+ */
+import type { DayOfWeek } from "../types.js";
+import type { SemanticTimeEntry } from "../cpsat/semantic-time.js";
+import type { CompilationResult } from "../cpsat/model-builder.js";
+import { ModelBuilder } from "../cpsat/model-builder.js";
+import type { SchedulingMember, ShiftPattern } from "../cpsat/types.js";
+import type { CreateCpsatRuleFunction } from "../cpsat/rules/rules.types.js";
+import type { SolverClient } from "../client.types.js";
+import type { ShiftAssignment } from "../cpsat/response.js";
+import type { ScheduleValidation } from "../cpsat/validation.types.js";
+import type { CostBreakdown } from "../cpsat/cost.js";
+import type { CoverageEntry } from "./coverage.js";
+import type { RuleEntry } from "./rules.js";
+/** A value that can be passed to {@link Schedule.with}. */
+type WithArg = Schedule | SchedulingMember[];
+/** Status of a solve attempt, using idiomatic lowercase TypeScript literals. */
+export type SolveStatus = "optimal" | "feasible" | "infeasible" | "no_solution";
+/**
+ * Result of {@link Schedule.solve}.
+ *
+ * @category Schedule Definition
+ */
+export interface SolveResult {
+    /** Outcome of the solve attempt. */
+    status: SolveStatus;
+    /** Shift assignments (empty when infeasible or no solution). */
+    assignments: ShiftAssignment[];
+    /** Validation diagnostics from compilation. */
+    validation: ScheduleValidation;
+    /** Cost breakdown (present when cost rules are used and a solution is found). */
+    cost?: CostBreakdown;
+}
+/**
+ * Options for {@link Schedule.solve} and {@link Schedule.compile}.
+ *
+ * @category Schedule Definition
+ */
+export interface SolveOptions {
+    /** The date range to schedule. */
+    dateRange: {
+        start: string;
+        end: string;
+    };
+    /**
+     * Fixed assignments from a prior solve (e.g., rolling schedule).
+     * These are injected as fixed variables in the solver.
+     *
+     * Not yet implemented. Providing pinned assignments throws an error.
+     */
+    pinned?: ShiftAssignment[];
+}
+/**
+ * Configuration for {@link schedule}.
+ *
+ * @remarks
+ * Coverage entries for the same semantic time and target stack additively.
+ * An unscoped entry applies every day; adding a weekend-only entry on top
+ * doubles the count on those days. Use mutually exclusive `dayOfWeek` on
+ * both entries to avoid stacking. See {@link cover} for details.
+ *
+ * `roleIds`, `times`, `coverage`, and `shiftPatterns` are required.
+ * These four fields form the minimum solvable schedule.
+ *
+ * @category Schedule Definition
+ */
+export interface ScheduleConfig<R extends readonly string[] = readonly string[], S extends readonly string[] = readonly [], T extends Record<string, SemanticTimeEntry> = Record<string, SemanticTimeEntry>> {
+    /** Declared role IDs. */
+    roleIds: R;
+    /** Declared skill IDs. When omitted, coverage targets can only be roles. */
+    skillIds?: S;
+    /** Named semantic time periods. */
+    times: T;
+    /** Staffing requirements per time period (entries stack additively). */
+    coverage: NoInfer<CoverageEntry<keyof T & string, R[number] | S[number]>>[];
+    /** Available shift patterns. */
+    shiftPatterns: ShiftPattern[];
+    /** Scheduling rules and constraints. */
+    rules?: RuleEntry[];
+    /**
+     * Custom rule factories. Keys are rule names, values are functions
+     * that take a config object and return a {@link CompilationRule}.
+     * Built-in rule names cannot be overridden.
+     */
+    ruleFactories?: Record<string, CreateCpsatRuleFunction>;
+    /** Team members (typically added via `.with()` at runtime). */
+    members?: SchedulingMember[];
+    /** Days of the week the business operates (inclusion filter). */
+    dayOfWeek?: readonly [DayOfWeek, ...DayOfWeek[]];
+    /** Which day starts the week for weekly rules. Defaults to `"monday"`. */
+    weekStartsOn?: DayOfWeek;
+}
+/** Internal representation of a fully merged schedule. */
+interface MergedScheduleConfig {
+    roleIds: string[];
+    skillIds: string[];
+    times: Record<string, SemanticTimeEntry>;
+    coverage: CoverageEntry[];
+    shiftPatterns: ShiftPattern[];
+    rules: RuleEntry[];
+    ruleFactories: Record<string, CreateCpsatRuleFunction>;
+    members: SchedulingMember[];
+    dayOfWeek?: readonly [DayOfWeek, ...DayOfWeek[]];
+    weekStartsOn?: DayOfWeek;
+}
+/**
+ * An immutable schedule definition.
+ *
+ * Created by {@link schedule}, composed via {@link Schedule.with},
+ * and solved via {@link Schedule.solve}.
+ *
+ * @category Schedule Definition
+ */
+export declare class Schedule {
+    #private;
+    /** @internal */
+    constructor(config: MergedScheduleConfig);
+    /** @internal Returns a defensive copy of the config for merging. */
+    _getConfig(): MergedScheduleConfig;
+    /** Declared role IDs. */
+    get roleIds(): readonly string[];
+    /** Declared skill IDs. */
+    get skillIds(): readonly string[];
+    /** Names of declared semantic times. */
+    get timeNames(): readonly string[];
+    /** Shift pattern IDs. */
+    get shiftPatternIds(): readonly string[];
+    /** Internal rule identifiers in kebab-case. */
+    get ruleNames(): readonly string[];
+    /**
+     * Merges schedules or members onto this schedule, returning a new
+     * immutable `Schedule`. The original is untouched.
+     *
+     * Accepts any mix of `Schedule` instances and `SchedulingMember[]` arrays.
+     *
+     * Merge semantics (when merging schedules):
+     * - Roles: union (additive)
+     * - Skills: union (additive)
+     * - Times: additive; error on name collision
+     * - Coverage: additive
+     * - Shift patterns: additive; error on ID collision
+     * - Rules: additive
+     * - Members: additive; error on duplicate ID
+     *
+     * Validation runs eagerly: role/skill disjointness, coverage targets
+     * referencing declared roles/skills, member role references, etc.
+     */
+    with(...args: WithArg[]): Schedule;
+    /**
+     * Compiles, validates, solves, and parses in one call.
+     *
+     * @param client - Solver client (e.g., `new HttpSolverClient(fetch, url)`)
+     * @param options - Date range and optional pinned assignments
+     */
+    solve(client: SolverClient, options: SolveOptions): Promise<SolveResult>;
+    /**
+     * Diagnostic escape hatch. Compiles the schedule without solving.
+     *
+     * @param options - Date range and optional pinned assignments
+     */
+    compile(options: SolveOptions): CompilationResult & {
+        builder: ModelBuilder;
+    };
+}
+/**
+ * Create a schedule definition.
+ *
+ * Returns an immutable {@link Schedule} that can be composed via `.with()`
+ * and solved via `.solve()`.
+ *
+ * @example
+ * ```typescript
+ * const venue = schedule({
+ *   roleIds: ["waiter", "runner", "manager"],
+ *   skillIds: ["senior"],
+ *   times: {
+ *     lunch: time({ startTime: t(12), endTime: t(15) }),
+ *     dinner: time(
+ *       { startTime: t(17), endTime: t(21) },
+ *       { startTime: t(18), endTime: t(22), dayOfWeek: weekend },
+ *     ),
+ *   },
+ *   coverage: [
+ *     cover("lunch", "waiter", 2),
+ *     cover("dinner", "waiter", 4, { dayOfWeek: weekdays }),
+ *     cover("dinner", "waiter", 5, { dayOfWeek: weekend }),
+ *     cover("dinner", "manager", 1),
+ *   ],
+ *   shiftPatterns: [
+ *     shift("lunch_shift", t(11, 30), t(15)),
+ *     shift("evening", t(17), t(22)),
+ *   ],
+ *   rules: [
+ *     maxHoursPerDay(10),
+ *     maxHoursPerWeek(48),
+ *     minRestBetweenShifts(11),
+ *   ],
+ * });
+ * ```
+ *
+ * @category Schedule Definition
+ */
+export declare function schedule<const R extends readonly string[], const S extends readonly string[] = readonly [], const T extends Record<string, SemanticTimeEntry> = Record<string, SemanticTimeEntry>>(config: ScheduleConfig<R, S, T>): Schedule;
+/**
+ * Create a partial schedule for composition via `.with()`.
+ *
+ * Unlike {@link schedule}, all fields are optional. Use this for
+ * schedules that layer rules, coverage, or other config onto a
+ * complete base schedule.
+ *
+ * @example
+ * ```typescript
+ * const companyPolicy = partialSchedule({
+ *   rules: [maxHoursPerWeek(40), minRestBetweenShifts(11)],
+ * });
+ *
+ * const ready = venue.with(companyPolicy, teamMembers);
+ * ```
+ *
+ * @category Schedule Definition
+ */
+export declare function partialSchedule(config: Partial<ScheduleConfig<readonly string[], readonly string[]>>): Schedule;
+export {};
+//# sourceMappingURL=definition.d.ts.map

package/dist/schedule/definition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"definition.d.ts","sourceRoot":"","sources":["../../src/schedule/definition.ts"],"names":[],"mappings":"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"}