dabke 0.83.0 → 0.84.0

package/src/schedule/shift-patterns.ts

@@ -13,23 +13,6 @@ import type { ShiftPattern } from "../cpsat/types.js";
  * @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(

package/src/schedule/time-periods.ts

@@ -1,5 +1,26 @@
 /**
- * Time period primitives: day constants and time constructors.
+ * Time period primitives: day constants and semantic time constructors.
+ *
+ * Semantic times are business-relevant scheduling periods used to group
+ * coverage and rules. Some come directly from the requirements, for example opening,
+ * lunch, or closing. Others are inferred from the requirements so different
+ * parts of a day can carry different coverage floors or constraints.
+ *
+ * An unscoped `time(...)` entry applies every day in the scheduling period.
+ * Names are descriptive only, they do not scope a time to a day. If a time is
+ * day-specific, add `dayOfWeek` or `dates` explicitly.
+ *
+ * @example
+ * ```typescript
+ * 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 },
+ *   ),
+ *   thursday_open: time({ startTime: t(10), endTime: t(11), dayOfWeek: ["thursday"] }),
+ * }
+ * ```
  *
  * @module
  */
@@ -17,16 +38,6 @@ import type {
  * @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: number, minutes = 0): TimeOfDay {
@@ -61,24 +72,23 @@ export const weekend = ["saturday", "sunday"] as const satisfies readonly [
  *
  * @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) }),
+ * scoping. Entries without scoping are the default and apply every day in the
+ * scheduling period. The surrounding object key is only a name, it does not
+ * add scope. For example, `thursday_open: time({ startTime: ..., endTime: ... })`
+ * still applies on Monday, Tuesday, and every other scheduling day unless you
+ * add `dayOfWeek: ["thursday"]`.
  *
- *   // Variants: different times on weekends
- *   dinner: time(
- *     { startTime: t(17), endTime: t(21) },
- *     { startTime: t(18), endTime: t(22), dayOfWeek: weekend },
- *   ),
+ * Use semantic times to represent business periods, not shift patterns. Some
+ * periods have explicit boundaries in the requirements. Others are inferred so
+ * related coverage and rules can attach to the correct part of the day. Choose
+ * the simplest set of semantic times that preserves the business distinctions
+ * you need.
  *
- *   // Point-in-time window (keyholder at opening)
- *   opening: time({ startTime: t(8, 30), endTime: t(9) }),
- * }
- * ```
+ * Avoid adding a broad all-day semantic time when narrower windows already
+ * describe the day's distinct requirements. If opening, core trading, and
+ * closing each need different coverage, model those windows directly instead
+ * of layering an extra whole-day period on top unless the lower bound truly
+ * applies for the full span.
  *
  * @privateRemarks
  * Resolution precedence: `dates` > `dayOfWeek` > default.

package/src/types.ts

@@ -48,6 +48,118 @@ export interface TimeOfDay {
   minutes: number;
 }
 
+// ============================================================================
+// Date String
+// ============================================================================
+
+/**
+ * A date string in ISO 8601 calendar date format (YYYY-MM-DD).
+ *
+ * Template literal type that rejects arbitrary strings at compile time.
+ * Use this wherever a raw date string is expected in scheduling APIs.
+ *
+ * @category Supporting Types
+ */
+export type DateString = `${number}-${number}-${number}`;
+
+const DATE_STRING_RE = /^\d{4}-\d{2}-\d{2}$/;
+
+/**
+ * Checks whether a string matches the {@link DateString} YYYY-MM-DD format.
+ *
+ * @remarks
+ * This validates string shape only. It does not guarantee that the value is a
+ * semantically valid calendar date.
+ *
+ * @param value - String to test
+ *
+ * @category Supporting Types
+ */
+export function isDateString(value: string): value is DateString {
+  return DATE_STRING_RE.test(value);
+}
+
+// ============================================================================
+// Scheduling Day
+// ============================================================================
+
+/**
+ * A calendar day with pre-computed date components.
+ *
+ * Constructed once from a YYYY-MM-DD string via {@link schedulingDay}, then
+ * passed by reference. Replaces raw `string` day representations throughout
+ * the solver so downstream code never needs to parse dates.
+ *
+ * @category Supporting Types
+ */
+export interface SchedulingDay {
+  /** The canonical YYYY-MM-DD string. */
+  readonly iso: DateString;
+  /** Day of week (monday, tuesday, ...). */
+  readonly dayOfWeek: DayOfWeek;
+  /** 1-indexed month (1 = January, 12 = December). */
+  readonly month: number;
+  /** 1-indexed day of the month. */
+  readonly dayOfMonth: number;
+  /** Year-month key for grouping ("YYYY-MM"). */
+  readonly yearMonth: string;
+  /** Integer days since Unix epoch (1970-01-01 = 0). Useful for date arithmetic. */
+  readonly epochDay: number;
+}
+
+export const DAY_NAMES: readonly DayOfWeek[] = [
+  "sunday",
+  "monday",
+  "tuesday",
+  "wednesday",
+  "thursday",
+  "friday",
+  "saturday",
+];
+
+const DAY_OF_WEEK_INDEX: Record<DayOfWeek, number> = {
+  sunday: 0,
+  monday: 1,
+  tuesday: 2,
+  wednesday: 3,
+  thursday: 4,
+  friday: 5,
+  saturday: 6,
+};
+
+/**
+ * Creates a {@link SchedulingDay} from a YYYY-MM-DD string.
+ *
+ * Parses the date once in UTC and pre-computes all fields so that no
+ * downstream code ever needs to construct a `Date` object.
+ *
+ * @param iso - Date string in YYYY-MM-DD format
+ *
+ * @category Supporting Types
+ */
+export function schedulingDay(iso: DateString): SchedulingDay {
+  const date = new Date(`${iso}T00:00:00Z`);
+  const dayOfWeek = DAY_NAMES[date.getUTCDay()]!;
+  const month = date.getUTCMonth() + 1;
+  const dayOfMonth = date.getUTCDate();
+  return {
+    iso,
+    dayOfWeek,
+    month,
+    dayOfMonth,
+    yearMonth: iso.slice(0, 7),
+    epochDay: Math.floor(date.getTime() / 86_400_000),
+  };
+}
+
+/**
+ * Maps {@link DayOfWeek} names to JavaScript `Date.getUTCDay()` indices
+ * (0 = Sunday, 6 = Saturday).
+ *
+ * @category Supporting Types
+ */
+export { DAY_OF_WEEK_INDEX };
+
 // ============================================================================
 // Scheduling Period
 // ============================================================================
@@ -89,7 +201,7 @@ export interface SchedulingPeriod {
    * The overall scheduling window (start and end are inclusive).
    * Dates should be in YYYY-MM-DD format.
    */
-  dateRange: { start: string; end: string };
+  dateRange: { start: DateString; end: DateString };
   /**
    * Include only these days of the week.
    * If omitted, all days of the week are included.
@@ -99,5 +211,5 @@ export interface SchedulingPeriod {
    * Include only these specific dates (YYYY-MM-DD) within the range.
    * If omitted, all dates in the range are included (subject to dayOfWeek filter).
    */
-  dates?: string[];
+  dates?: DateString[];
 }