@classytic/primitives 0.19.0 → 0.20.0

package/dist/timezone-tlG7ygwx.d.mts

@@ -0,0 +1,114 @@
+import { t as Brand } from "./brand-LLXqoh5J.mjs";
+import { s as IsoWeekday } from "./cadence-BFQVC1Qp.mjs";
+import { t as UtcOffsetMinutes } from "./calendar-B6fm-FbR.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-tlG7ygwx.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,5 +1,4 @@
-import { r as CurrencyCode } from "./currency-BCJnJBlb.mjs";
-import { MinorUnits } from "./money.mjs";
+import { t as MinorUnits, w as CurrencyCode } from "./money-DPo9fLBi.mjs";
 
 //#region src/money/unit-cost-rate.d.ts
 /** Fixed, ecosystem-wide rate scale: 6 decimal places below the minor unit. */