@classytic/primitives 0.19.0 → 0.21.0

package/dist/state-diagram.mjs

@@ -54,7 +54,7 @@ function describeStateMachine(machine) {
 * that can never leave the state it is stuck in.
 */
 function unreachableStates(machine, initial) {
-	const seen = new Set([initial]);
+	const seen = /* @__PURE__ */ new Set([initial]);
 	const queue = [initial];
 	while (queue.length > 0) for (const next of machine.validTargets(queue.pop())) if (!seen.has(next)) {
 		seen.add(next);

package/dist/state-machine.mjs

@@ -149,6 +149,19 @@ function defineStateMachine(definition) {
 */
 async function assertAndClaim(machine, repo, id, args) {
 	const sources = Array.isArray(args.from) ? args.from : [args.from];
+	/**
+	* An EMPTY source list must never reach `claim()`.
+	*
+	* `validSources(to)` returns `[]` for a status nothing transitions into, and
+	* the multi-source idiom in the docblock above (`from: machine.validSources(x)`)
+	* makes that easy to hit. With `[]` the assert loop below runs ZERO times — the
+	* domain check silently does not happen — and the CAS is then handed an empty
+	* allow-list. Mongo's `$in: []` matches nothing so today that fails closed and
+	* looks exactly like a race-loss (`null`), which is the wrong diagnosis; a kit
+	* that read an empty list as "no constraint" would fail OPEN and claim from any
+	* state at all. An empty allow-list must never mean "any".
+	*/
+	if (sources.length === 0) throw new IllegalTransitionError(machine.name, id, "(none)", args.to);
 	for (const from of sources) machine.assertTransition(id, from, args.to);
 	return repo.claim(id, {
 		from: Array.isArray(args.from) ? args.from : args.from,

package/dist/suspension.d.mts

@@ -1,7 +1,6 @@
-import { UtcOffsetMinutes } from "./calendar.mjs";
+import { t as UtcOffsetMinutes } from "./calendar-DJWSbcgE.mjs";
 import { DateRange } from "./period.mjs";
 import { StatusChangeEntry } from "./status-history.mjs";
-
 //#region src/workflow/suspension.d.ts
 /**
  * One suspension, past or current.
@@ -84,7 +83,9 @@ declare function allowancePeriod(at: Date, periodMonths?: number, offsetMinutes?
  * December. Ignoring that double-counts a straddling pause in both periods and
  * refuses a member who is within their allowance.
  */
-declare function suspendedDaysInPeriod(history: readonly SuspensionSpan[], period: DateRange, /** Now — bounds still-open spans. Defaults to the period end. */at?: Date): number;
+declare function suspendedDaysInPeriod(history: readonly SuspensionSpan[], period: DateRange,
+/** Now — bounds still-open spans. Defaults to the period end. */
+at?: Date): number;
 /** Is any span still open at `at`? */
 declare function openSpans(history: readonly SuspensionSpan[], at: Date): readonly SuspensionSpan[];
 /**
@@ -144,7 +145,8 @@ declare function spansFromStatusHistory<TStatus extends string>(history: readonl
    * resume yet (a crash between the write and the append). Leaving it open would
    * charge the member allowance for time they were not frozen.
    */
-  readonly currentStatus?: TStatus | undefined; /** Closes a genuinely-open trailing span for counting. Defaults to open. */
+  readonly currentStatus?: TStatus | undefined;
+  /** Closes a genuinely-open trailing span for counting. Defaults to open. */
   readonly openEndedAt?: Date | undefined;
 }): SuspensionSpan[];
 //#endregion

package/dist/suspension.mjs

@@ -39,11 +39,12 @@ import { addMonths, startOfDay } from "./calendar.mjs";
 * PURE: no clock reads beyond the `at` you pass, no I/O. The same evaluation runs
 * on the server, in an admin preview, and in a test.
 */
-const MS_PER_DAY = 1440 * 60 * 1e3;
+const MS_PER_DAY = 864e5;
 /** The allowance period containing `at`, as a half-open range. */
 function allowancePeriod(at, periodMonths = 12, offsetMinutes = 0) {
+	const anchor = startOfDay(at, offsetMinutes);
 	return {
-		start: addMonths(startOfDay(at, offsetMinutes), -periodMonths),
+		start: addMonths(anchor, -periodMonths),
 		end: at
 	};
 }

package/dist/timezone-CxUjxmRU.d.mts

@@ -0,0 +1,113 @@
+import { t as Brand } from "./brand-Lj_75Y_r.mjs";
+import { s as IsoWeekday } from "./cadence-5X6TiD49.mjs";
+import { t as UtcOffsetMinutes } from "./calendar-DJWSbcgE.mjs";
+//#region src/scheduling/timezone.d.ts
+declare class TimeZoneError extends Error {
+  constructor(message: string);
+}
+/**
+ * Is `zone` a valid IANA timezone name on this runtime's ICU data?
+ * Use at BOOT to validate host config (an offer's `timezone`, an org
+ * setting) — fail loud at wiring time, not on the first localized read.
+ */
+declare function isValidTimeZone(zone: string): boolean;
+/**
+ * Every IANA timezone name this runtime supports — the data source for a
+ * Google-Calendar-style zone picker. Straight from ICU via
+ * `Intl.supportedValuesOf` (Node >= 18); no bundled tz list to go stale.
+ *
+ * UIs typically label each entry with its current offset:
+ * `listTimeZones().map((z) => ({ zone: z, label: zoneOffsetLabel(now, z) }))`.
+ */
+declare function listTimeZones(): readonly string[];
+/**
+ * The zone's UTC offset AT `instant`, in minutes east of UTC — DST-exact.
+ * `zoneOffsetMinutes(july, 'Europe/London')` → 60; `(january, …)` → 0;
+ * `(any, 'Asia/Dhaka')` → 360.
+ *
+ * This is the value `/calendar`'s docstring tells hosts to "resolve and pass
+ * in": `startOfMonth(instant, zoneOffsetMinutes(instant, zone))`.
+ */
+declare function zoneOffsetMinutes(instant: Date, zone: string): UtcOffsetMinutes;
+/**
+ * The zone's offset label AT `instant` — `'GMT+06:00'` / `'GMT-05:30'` /
+ * `'GMT'`. Ready-made display text for zone pickers.
+ */
+declare function zoneOffsetLabel(instant: Date, zone: string): string;
+interface LocalTimeParts {
+  /** ISO weekday in the zone — 1=Mon … 7=Sun (matches `/cadence`). */
+  isoWeekday: IsoWeekday;
+  /** Hour of day in the zone, 0–23. */
+  hour: number;
+  /** Minute of hour, 0–59. */
+  minute: number;
+  /** `hour * 60 + minute` — the shape "HH:MM window" checks want. */
+  minutesOfDay: number;
+}
+/**
+ * The wall-clock weekday + time of `instant` in `zone` — what pricing
+ * schedules ("peak Fri 17:00–22:00"), slot grids, and working-hours checks
+ * evaluate against. DST-exact per instant.
+ */
+declare function localTimeParts(instant: Date, zone: string): LocalTimeParts;
+/**
+ * A calendar day — `'YYYY-MM-DD'` — with NO time and NO zone until one is
+ * bound. The type for hotel nights, POS business dates, statement periods,
+ * VAT filing years. Lexicographic order == chronological order, so it's
+ * index- and range-query-friendly as a Mongo string key.
+ */
+type CivilDate = Brand<string, 'CivilDate'>;
+/** Runtime guard for external input. */
+declare function isCivilDate(value: unknown): value is CivilDate;
+/** Validate + brand a `'YYYY-MM-DD'` string. Throws on malformed input. */
+declare function civilDate(value: string): CivilDate;
+/**
+ * The calendar day `instant` falls on IN `zone` — e.g. the POS business
+ * date: `civilDateOf(new Date(), 'Asia/Dhaka')`. Never depends on the
+ * server's TZ env.
+ */
+declare function civilDateOf(instant: Date, zone: string): CivilDate;
+/**
+ * Bind a civil date (+ optional wall time) to a zone → the exact instant.
+ * `civilDateToInstant(night, hotelZone, { hour: 14 })` = check-in instant;
+ * with no `time`, local midnight — the DST-exact "start of that day in that
+ * zone".
+ *
+ * Two-pass offset resolution: the offset is looked up AT the candidate
+ * instant, then re-checked, so days where a DST transition sits between the
+ * wall time and the first guess still resolve correctly. Honest limit: a
+ * wall time that does not exist (inside a spring-forward gap) resolves to
+ * the instant the shifted clock reaches — the same choice Temporal's
+ * `disambiguation: 'compatible'` makes.
+ */
+declare function civilDateToInstant(cd: CivilDate, zone: string, time?: {
+  hour?: number;
+  minute?: number;
+  second?: number;
+  millisecond?: number;
+}): Date;
+/**
+ * Pure calendar-day arithmetic — `addCivilDays('2026-02-28', 1)` →
+ * `'2026-03-01'`. Zone-free by definition (a civil date has no zone);
+ * use it to iterate hotel nights / statement days.
+ */
+declare function addCivilDays(cd: CivilDate, days: number): CivilDate;
+/**
+ * Whole days from `a` to `b` (positive when `b` is later) — the NIGHTS
+ * count for a `[checkIn, checkOut)` stay expressed as civil dates.
+ */
+/**
+ * The ISO-8601 week a civil date belongs to, as `YYYY-Www`.
+ *
+ * Zone-free by definition — a civil date has no zone — so callers resolve the
+ * date in their business timezone FIRST (`civilDateOf`) and label it here.
+ *
+ * ISO week 1 is the week containing the first Thursday, which means the week
+ * YEAR can differ from the date's own: 2025-12-29 is `2026-W01`. Naive
+ * "day-of-year / 7" numbering gets that wrong every few years, silently
+ * splitting one business week across two report buckets.
+ */
+declare function isoWeekOfCivilDate(cd: CivilDate): string;
+declare function civilDaysBetween(a: CivilDate, b: CivilDate): number;
+//#endregion
+export { civilDate as a, civilDaysBetween as c, isoWeekOfCivilDate as d, listTimeZones as f, zoneOffsetMinutes as h, addCivilDays as i, isCivilDate as l, zoneOffsetLabel as m, LocalTimeParts as n, civilDateOf as o, localTimeParts as p, TimeZoneError as r, civilDateToInstant as s, CivilDate as t, isValidTimeZone as u };

package/dist/timezone.d.mts

@@ -1,100 +1,2 @@
-import { t as Brand } from "./brand-LLXqoh5J.mjs";
-import { IsoWeekday } from "./cadence.mjs";
-import { UtcOffsetMinutes } from "./calendar.mjs";
-
-//#region src/scheduling/timezone.d.ts
-declare class TimeZoneError extends Error {
-  constructor(message: string);
-}
-/**
- * Is `zone` a valid IANA timezone name on this runtime's ICU data?
- * Use at BOOT to validate host config (an offer's `timezone`, an org
- * setting) — fail loud at wiring time, not on the first localized read.
- */
-declare function isValidTimeZone(zone: string): boolean;
-/**
- * Every IANA timezone name this runtime supports — the data source for a
- * Google-Calendar-style zone picker. Straight from ICU via
- * `Intl.supportedValuesOf` (Node >= 18); no bundled tz list to go stale.
- *
- * UIs typically label each entry with its current offset:
- * `listTimeZones().map((z) => ({ zone: z, label: zoneOffsetLabel(now, z) }))`.
- */
-declare function listTimeZones(): readonly string[];
-/**
- * The zone's UTC offset AT `instant`, in minutes east of UTC — DST-exact.
- * `zoneOffsetMinutes(july, 'Europe/London')` → 60; `(january, …)` → 0;
- * `(any, 'Asia/Dhaka')` → 360.
- *
- * This is the value `/calendar`'s docstring tells hosts to "resolve and pass
- * in": `startOfMonth(instant, zoneOffsetMinutes(instant, zone))`.
- */
-declare function zoneOffsetMinutes(instant: Date, zone: string): UtcOffsetMinutes;
-/**
- * The zone's offset label AT `instant` — `'GMT+06:00'` / `'GMT-05:30'` /
- * `'GMT'`. Ready-made display text for zone pickers.
- */
-declare function zoneOffsetLabel(instant: Date, zone: string): string;
-interface LocalTimeParts {
-  /** ISO weekday in the zone — 1=Mon … 7=Sun (matches `/cadence`). */
-  isoWeekday: IsoWeekday;
-  /** Hour of day in the zone, 0–23. */
-  hour: number;
-  /** Minute of hour, 0–59. */
-  minute: number;
-  /** `hour * 60 + minute` — the shape "HH:MM window" checks want. */
-  minutesOfDay: number;
-}
-/**
- * The wall-clock weekday + time of `instant` in `zone` — what pricing
- * schedules ("peak Fri 17:00–22:00"), slot grids, and working-hours checks
- * evaluate against. DST-exact per instant.
- */
-declare function localTimeParts(instant: Date, zone: string): LocalTimeParts;
-/**
- * A calendar day — `'YYYY-MM-DD'` — with NO time and NO zone until one is
- * bound. The type for hotel nights, POS business dates, statement periods,
- * VAT filing years. Lexicographic order == chronological order, so it's
- * index- and range-query-friendly as a Mongo string key.
- */
-type CivilDate = Brand<string, 'CivilDate'>;
-/** Runtime guard for external input. */
-declare function isCivilDate(value: unknown): value is CivilDate;
-/** Validate + brand a `'YYYY-MM-DD'` string. Throws on malformed input. */
-declare function civilDate(value: string): CivilDate;
-/**
- * The calendar day `instant` falls on IN `zone` — e.g. the POS business
- * date: `civilDateOf(new Date(), 'Asia/Dhaka')`. Never depends on the
- * server's TZ env.
- */
-declare function civilDateOf(instant: Date, zone: string): CivilDate;
-/**
- * Bind a civil date (+ optional wall time) to a zone → the exact instant.
- * `civilDateToInstant(night, hotelZone, { hour: 14 })` = check-in instant;
- * with no `time`, local midnight — the DST-exact "start of that day in that
- * zone".
- *
- * Two-pass offset resolution: the offset is looked up AT the candidate
- * instant, then re-checked, so days where a DST transition sits between the
- * wall time and the first guess still resolve correctly. Honest limit: a
- * wall time that does not exist (inside a spring-forward gap) resolves to
- * the instant the shifted clock reaches — the same choice Temporal's
- * `disambiguation: 'compatible'` makes.
- */
-declare function civilDateToInstant(cd: CivilDate, zone: string, time?: {
-  hour?: number;
-  minute?: number;
-}): Date;
-/**
- * Pure calendar-day arithmetic — `addCivilDays('2026-02-28', 1)` →
- * `'2026-03-01'`. Zone-free by definition (a civil date has no zone);
- * use it to iterate hotel nights / statement days.
- */
-declare function addCivilDays(cd: CivilDate, days: number): CivilDate;
-/**
- * Whole days from `a` to `b` (positive when `b` is later) — the NIGHTS
- * count for a `[checkIn, checkOut)` stay expressed as civil dates.
- */
-declare function civilDaysBetween(a: CivilDate, b: CivilDate): number;
-//#endregion
-export { CivilDate, LocalTimeParts, TimeZoneError, addCivilDays, civilDate, civilDateOf, civilDateToInstant, civilDaysBetween, isCivilDate, isValidTimeZone, listTimeZones, localTimeParts, zoneOffsetLabel, zoneOffsetMinutes };
+import { a as civilDate, c as civilDaysBetween, d as isoWeekOfCivilDate, f as listTimeZones, h as zoneOffsetMinutes, i as addCivilDays, l as isCivilDate, m as zoneOffsetLabel, n as LocalTimeParts, o as civilDateOf, p as localTimeParts, r as TimeZoneError, s as civilDateToInstant, t as CivilDate, u as isValidTimeZone } from "./timezone-CxUjxmRU.mjs";
+export { CivilDate, LocalTimeParts, TimeZoneError, addCivilDays, civilDate, civilDateOf, civilDateToInstant, civilDaysBetween, isCivilDate, isValidTimeZone, isoWeekOfCivilDate, listTimeZones, localTimeParts, zoneOffsetLabel, zoneOffsetMinutes };

package/dist/timezone.mjs

@@ -78,7 +78,19 @@ function listTimeZones() {
 	cachedZones = Object.freeze(intl.supportedValuesOf("timeZone"));
 	return cachedZones;
 }
-const OFFSET_RE = /GMT(?:([+-])(\d{2}):(\d{2}))?/;
+/**
+* ANCHORED on purpose.
+*
+* The unanchored form (`/GMT(?:([+-])(\d{2}):(\d{2}))?/`) made the offset group
+* OPTIONAL *and* skippable: any label the runtime emits that this pattern cannot
+* fully parse — `'GMT+5:30'` from an ICU build that does not zero-pad, or a
+* locale that prefixes text — still matched the bare `GMT` alternative and
+* resolved to offset **0**. A half-read offset became "UTC" with no error, which
+* silently shifts every business-day boundary derived from it. Anchoring makes an
+* unrecognised label throw instead; `\d{1,2}` accepts the unpadded variant rather
+* than mis-reading it.
+*/
+const OFFSET_RE = /^GMT(?:([+-])(\d{1,2}):(\d{2}))?$/;
 /**
 * The zone's UTC offset AT `instant`, in minutes east of UTC — DST-exact.
 * `zoneOffsetMinutes(july, 'Europe/London')` → 60; `(january, …)` → 0;
@@ -204,7 +216,9 @@ function civilDateToInstant(cd, zone, time = {}) {
 	if (!m) throw new TimeZoneError(`Invalid civil date '${cd}'.`);
 	const hour = time.hour ?? 0;
 	const minute = time.minute ?? 0;
-	const wallAsUtc = Date.UTC(Number(m[1]), Number(m[2]) - 1, Number(m[3]), hour, minute);
+	const second = time.second ?? 0;
+	const millisecond = time.millisecond ?? 0;
+	const wallAsUtc = Date.UTC(Number(m[1]), Number(m[2]) - 1, Number(m[3]), hour, minute, second, millisecond);
 	const firstOffset = zoneOffsetMinutes(new Date(wallAsUtc), zone);
 	let instantMs = wallAsUtc - firstOffset * MINUTE_MS;
 	const refined = zoneOffsetMinutes(new Date(instantMs), zone);
@@ -226,6 +240,27 @@ function addCivilDays(cd, days) {
 * Whole days from `a` to `b` (positive when `b` is later) — the NIGHTS
 * count for a `[checkIn, checkOut)` stay expressed as civil dates.
 */
+/**
+* The ISO-8601 week a civil date belongs to, as `YYYY-Www`.
+*
+* Zone-free by definition — a civil date has no zone — so callers resolve the
+* date in their business timezone FIRST (`civilDateOf`) and label it here.
+*
+* ISO week 1 is the week containing the first Thursday, which means the week
+* YEAR can differ from the date's own: 2025-12-29 is `2026-W01`. Naive
+* "day-of-year / 7" numbering gets that wrong every few years, silently
+* splitting one business week across two report buckets.
+*/
+function isoWeekOfCivilDate(cd) {
+	const m = CIVIL_RE.exec(cd);
+	if (!m) throw new TimeZoneError(`Invalid civil date '${cd}'.`);
+	const utc = Date.UTC(Number(m[1]), Number(m[2]) - 1, Number(m[3]));
+	const dow = new Date(utc).getUTCDay() || 7;
+	const thursday = new Date(utc + (4 - dow) * 864e5);
+	const weekYear = thursday.getUTCFullYear();
+	const week = Math.floor((thursday.getTime() - Date.UTC(weekYear, 0, 1)) / 864e5 / 7) + 1;
+	return `${weekYear}-W${String(week).padStart(2, "0")}`;
+}
 function civilDaysBetween(a, b) {
 	const pa = CIVIL_RE.exec(a);
 	const pb = CIVIL_RE.exec(b);
@@ -235,4 +270,4 @@ function civilDaysBetween(a, b) {
 	return Math.round((mb - ma) / 864e5);
 }
 //#endregion
-export { TimeZoneError, addCivilDays, civilDate, civilDateOf, civilDateToInstant, civilDaysBetween, isCivilDate, isValidTimeZone, listTimeZones, localTimeParts, zoneOffsetLabel, zoneOffsetMinutes };
+export { TimeZoneError, addCivilDays, civilDate, civilDateOf, civilDateToInstant, civilDaysBetween, isCivilDate, isValidTimeZone, isoWeekOfCivilDate, listTimeZones, localTimeParts, zoneOffsetLabel, zoneOffsetMinutes };

package/dist/unit-cost-rate.d.mts

@@ -1,6 +1,4 @@
-import { r as CurrencyCode } from "./currency-BCJnJBlb.mjs";
-import { MinorUnits } from "./money.mjs";
-
+import { t as MinorUnits, w as CurrencyCode } from "./money-CfAvfNiM.mjs";
 //#region src/money/unit-cost-rate.d.ts
 /** Fixed, ecosystem-wide rate scale: 6 decimal places below the minor unit. */
 declare const RATE_SCALE = 1000000;