@ultimat3/time 2.0.0 → 3.0.0

package/CLAUDE.md

@@ -10,8 +10,6 @@
 | `instant.ts` | the UTC `Instant` brand, ISO/epoch conversion, `now(clock)`, `epoch()` |
 | `zones.ts` | IANA validation, `offsetAt` (minutes east), zone labels |
 | `zone-canonical.ts` | one zone, one key: `canonicalTimeZone` — the casing/alias collapse every cache keys on |
-| `locale-canonical.ts` | one locale, one key: `canonicalLocale` — the same collapse for the `Accept-Language` half |
-| `intl-cache.ts` | the one bounded FIFO every `Intl` formatter cache in this package uses |
 | `zoned.ts` | `toZoned` / `fromZoned` + gap and overlap policies. Everything depends on this. |
 | `format.ts` | `Intl` rendering. Every function takes `locale` **and** `zone`. |
 | `duration.ts` | `'2h30m'` ⇄ ms |
@@ -22,6 +20,7 @@
 | `schedule.ts` | `nextLocalSlot` — "09:00 local tomorrow" |
 | `business.ts` | weekends as config, holidays as local dates |
 | `context.ts` | request timezone: which source wins, and reading core's `Ctx.tz` back off the ALS |
+| `plain-date.ts` | `PlainDate` — a calendar date with no time and no zone, and the two conversions to an instant |
 
 ## Rules
 
@@ -35,7 +34,10 @@
   possible version of the rule above. Never reintroduce either half.
 - **Never cache an `Intl` formatter on a raw caller string.** A zone and a locale both arrive from
   a request header, so the key must be canonical (`canonicalTimeZone` for a zone, `canonicalLocale`
-  for a locale) and the cache must be bounded (`cachedFormatter`, `intl-cache.ts`). An unbounded
+  for a locale) and the cache must be bounded (`cachedFormatter`). **`cachedFormatter`,
+  `MAX_CACHED_FORMATTERS` and `canonicalLocale` are `@ultimat3/core`'s as of 2.0.0**, not this
+  package's: `@ultimat3/money` hit the identical unbounded-`Map`-on-a-header bug and tier 1 may not
+  import sideways, so the mechanism moved down a tier rather than being copied. An unbounded
   `Map` keyed on `x-timezone` grew 31 MB for 4,096 casings of one zone name, and the casing space
   of a 13-letter zone is 2^12. **Both halves, always** — a canonical key does not bound anything
   (an unknown `-u-` extension value survives canonicalization as a distinct string) and the cap
@@ -50,6 +52,21 @@
   no seconds phrase, so a 6-field expression with a non-trivial seconds field is
   `X_CRON_NOT_DESCRIBABLE`. Adding a required field to `CronPhrases` would break every caller
   (`packages/cli/src/cmd-tasks.ts` builds one) to describe a schedule almost nobody writes.
+- **A `PlainDate` is a branded STRING, and the golden rule does not apply to it** — decided
+  2026-08 for `@ultimat3/entity`'s `date()` column. "Never format a date without a zone" is about
+  INSTANTS; a calendar date names no instant, so it needs no zone, and giving it one is the bug:
+  `effective_on` stored as a `timestamptz` is a different date on either side of midnight for half
+  the planet. Not a `Date` (that is an instant, and binding one to a Postgres `date` parameter
+  fails outright — `time zone "gmt-0500" not recognized`, measured on 17.10) and not
+  `{ year, month, day }` (an object sorts by nothing and JSON-stringifies as three fields). The ISO
+  string sorts lexicographically exactly as it sorts chronologically, which is why every cursor,
+  `orderBy` and `compare` in the framework handles it with no special case at all.
+- **`plainDateIn` takes a zone and `plainDateUtc` does not, and neither is a default for the
+  other.** An instant has a calendar date only in a zone; a `Date` a driver returns for a `date`
+  column is midnight UTC and reading its LOCAL fields loses a day west of Greenwich. `bun test`
+  pins the process to UTC, so that bug is invisible to every in-process test — `plain-date.test.ts`
+  spawns a subprocess with `TZ=America/Los_Angeles` for exactly one assertion, and that is the only
+  reason it can fail.
 - Never add `86_400_000` to cross a day boundary — use `addDaysInZone` / `fromZoned`.
 - Never take the clock from `Date.now()`; accept a `Clock` (`now(clock)`).
 - Cron and schedules iterate the **local wall clock**, then convert once with `fromZoned`.

package/README.md

@@ -23,8 +23,10 @@ return it. Anything reading a zone off a request header should canonicalize befo
 
 One **locale** is one key for the same reason — `Accept-Language` spells one locale `EN-us`,
 `en-US` and `en-latn-us`, and `formatDateTime` and `describeCron` collapse the three before they
-reach a formatter cache. The cap in `intl-cache.ts` stays either way: an unknown `-u-` extension
-value survives canonicalization as a distinct string, so the key bounds nothing on its own.
+reach a formatter cache. The cap stays either way: an unknown `-u-` extension value survives
+canonicalization as a distinct string, so the key bounds nothing on its own. Both halves —
+`canonicalLocale` and `cachedFormatter` — are `@ultimat3/core`'s as of 2.0.0, so `@ultimat3/money`
+reads the same bound rather than a copy of it.
 
 Every value this package hands back is its own object: `instant(date)` copies rather than branding
 the caller's `Date`, and `epoch()` is a function — the `EPOCH` constant it replaces was one shared
@@ -78,6 +80,34 @@ one of these takes the zone explicitly, and none of them has a default.
 `daysBetween` counts boundaries, not milliseconds: 23 real hours across spring forward is `1`,
 and 24 real hours inside a 25-hour fall-back day is `0`.
 
+## A calendar date is not an instant
+
+`PlainDate` is `2026-03-14`: a year, a month and a day, with **no time and therefore no zone**,
+`As of 2026-08`. The golden rule at the top of this page is about instants — a `PlainDate` needs no
+zone because it names no moment, and that is the honest modelling of the values that have one.
+`effective_on` is the date a rate applies; a birthday is a date; an invoice period is two of them.
+Stored as a `timestamptz`, every one of those is a different date on either side of midnight for
+half the planet.
+
+| Function | Answers |
+|---|---|
+| `plainDate(value)` / `isPlainDate(value)` | the date, or a refusal — `2026-02-30` is not one, and a regex cannot say so |
+| `plainDateOf({ year, month, day })` | the same, from fields; an impossible day throws instead of rolling into the next month |
+| `plainDateParts(date)` | back to fields |
+| `plainDateIn(at, zone)` | the calendar date an **instant** falls on, in a named zone. It takes the zone because there is no other honest way to make this conversion |
+| `plainDateUtc(at)` | the date a `Date` holds read as UTC — for the one caller that needs it: a Postgres driver returns a `date` column as midnight UTC |
+| `plainDateToUtcInstant(date)` | midnight UTC of the date. The inverse of `plainDateUtc`, and never of `plainDateIn` |
+| `addPlainDays(date, days)` / `plainDaysBetween(from, to)` | calendar arithmetic with no zone in it: a DST day is one day, because there is no zone to shorten |
+| `comparePlainDates(a, b)` | `-1` / `0` / `1` |
+
+It is a branded **string**, and both halves are load-bearing. Not a `Date`: a `Date` is an instant,
+so `2026-03-14T00:00:00Z` is the 13th anywhere west of Greenwich, and binding one to a Postgres
+`date` parameter fails outright (`time zone "gmt-0500" not recognized`, measured on 17.10). A
+string: the ISO form sorts lexicographically exactly as it sorts chronologically, round-trips
+through `JSON.stringify` as itself, and is the literal Postgres accepts and returns.
+
+`@ultimat3/entity`'s `date()` column is the one that stores it.
+
 ## Cron
 
 `parseCron` handles 5 or 6 fields, `*/n`, ranges, lists, named months and days, `@daily`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/time",
-  "version": "2.0.0",
+  "version": "3.0.0",
   "description": "UTC instants, DST-correct zone math, cron, durations and Intl formatting with an explicit timezone",
   "license": "MIT",
   "type": "module",
@@ -31,6 +31,6 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "2.0.0"
+    "@ultimat3/core": "3.0.0"
   }
 }

package/src/cron-describe.ts

@@ -4,10 +4,9 @@
  * ship English to every locale that forgot the argument — so injection is mandatory, not opt-in.
  */
 
+import { cachedFormatter, canonicalLocale } from '@ultimat3/core';
 import { type CronExpression, parseCronOnce } from './cron-parse';
 import { cronNotDescribable, localeInvalid } from './errors';
-import { cachedFormatter } from './intl-cache';
-import { canonicalLocale } from './locale-canonical';
 
 export interface CronPhrases {
   everyMinute: string;
@@ -134,8 +133,9 @@ function fill(template: string, vars: Readonly<Record<string, string | number>>)
  * header. `canonicalLocale` collapses the spellings of one locale — `EN-us`, `en-latn-us` — but it
  * still returns a distinct string for every unknown `-u-` extension value, so the key alone does
  * not bound anything and only the cap keeps the key space finite. Neither half is redundant. The
- * cap and its FIFO live in `intl-cache.ts`, because `zones.ts` and `format.ts` needed the same
- * rule and a hazard documented in one file is a hazard the other two repeat.
+ * cap and its FIFO live in `@ultimat3/core`'s `intl-cache.ts`, because `zones.ts`, `format.ts` and
+ * `@ultimat3/money`'s formatter all need the same rule, and a hazard documented in one file is a
+ * hazard every other one repeats.
  *
  * Both caches are fed the canonical `tag` by `describeCron` alone, never a caller string.
  */

package/src/cron-parse.ts

@@ -65,7 +65,9 @@ export function parseCron(expression: string): CronExpression {
   const hours = parseField(expression, hourField ?? '*', 0, 23);
   const daysOfMonth = parseField(expression, domField ?? '*', 1, 31);
   const months = parseField(expression, monthField ?? '*', 1, 12, MONTH_NAMES, 1);
-  const rawDow = parseField(expression, dowField ?? '*', 0, 7, DAY_NAMES, 0);
+  // Span 7, not `max - min + 1` = 8: the dow field accepts 0-7 because Sunday has two spellings,
+  // so the modulus a wrap strides over is a week with a phantom day in it unless it is stated.
+  const rawDow = parseField(expression, dowField ?? '*', 0, 7, DAY_NAMES, 0, 7);
 
   // 0 and 7 are both Sunday in cron; ISO calls Sunday 7.
   const daysOfWeek = [...new Set(rawDow.map((day) => (day === 0 ? 7 : day)))].sort((a, b) => a - b);
@@ -113,6 +115,13 @@ function parseField(
   max: number,
   names: readonly string[] = [],
   nameOffset = 0,
+  /**
+   * How many distinct values one full turn of this field has — `max - min + 1` for every field
+   * whose spelling is one-to-one. Day-of-week is the exception and the reason this is a parameter:
+   * it spells Sunday twice (0 and 7), so its 0-7 bounds describe 8 slots over a 7-day week, and a
+   * wrapping stride computed from the bounds walked a day that does not exist.
+   */
+  span = max - min + 1,
 ): number[] {
   const values = new Set<number>();
   for (const part of field.split(',')) {
@@ -144,7 +153,6 @@ function parseField(
       // Wrapping ranges (`fri-mon`, `22-2`) are a real cron idiom, and the stride CONTINUES across
       // the wrap: `23-3/2` is 23, 01, 03 — every second hour starting at 23. Restarting at `min`
       // answered 23, 00, 02, an hour off for every occurrence past midnight.
-      const span = max - min + 1;
       const length = to - from + span;
       for (let offset = 0; offset <= length; offset += step) {
         values.add(min + ((from - min + offset) % span));

package/src/format.ts

@@ -4,9 +4,8 @@
  * because "the server's timezone" is never the answer to "what time is it for the user".
  */
 
+import { cachedFormatter, canonicalLocale } from '@ultimat3/core';
 import { differenceMs, type Instant } from './instant';
-import { cachedFormatter } from './intl-cache';
-import { canonicalLocale } from './locale-canonical';
 import { assertTimeZone, type TimeZone } from './zones';
 
 export type DateTimeStyle = 'short' | 'medium' | 'long' | 'full';

package/src/index.ts

@@ -97,6 +97,21 @@ export {
   toIso,
   toIsoDateUtc,
 } from './instant';
+export {
+  addPlainDays,
+  comparePlainDates,
+  isPlainDate,
+  PLAIN_DATE_PATTERN,
+  type PlainDate,
+  type PlainDateParts,
+  plainDate,
+  plainDateIn,
+  plainDateOf,
+  plainDateParts,
+  plainDateToUtcInstant,
+  plainDateUtc,
+  plainDaysBetween,
+} from './plain-date';
 export {
   type LocalSlot,
   nextLocalSlot,

package/src/plain-date.ts

@@ -0,0 +1,133 @@
+// A calendar date: a year, a month and a day, with no time and therefore no zone. The framework's
+// "never format a date without an IANA zone" rule is about INSTANTS — a `PlainDate` needs no zone
+// because it names no instant, and that is the whole reason it exists: `effective_on` is the date
+// a rate applies, not a moment, and storing it as a `timestamptz` makes it a different date either
+// side of midnight for half the planet.
+
+import { scheduleInvalid } from './errors';
+import { type Instant, instant } from './instant';
+import { isoDateInZone } from './zoned';
+import type { TimeZone } from './zones';
+
+declare const plainDateBrand: unique symbol;
+
+/**
+ * `2026-03-14`. A branded STRING, not an object and not a `Date`, and each half of that is load-
+ * bearing:
+ *
+ * - not a `Date`, because a `Date` is an instant: read back through the local zone,
+ *   `2026-03-14T00:00:00Z` is the 13th anywhere west of Greenwich, and binding one to a Postgres
+ *   `date` parameter fails outright (`time zone "gmt-0500" not recognized`, measured on 17.10).
+ * - a string, because the ISO form sorts lexicographically exactly as it sorts chronologically,
+ *   round-trips through `JSON.stringify` as itself, and is the literal Postgres accepts and
+ *   returns for a `date` column.
+ */
+export type PlainDate = string & { readonly [plainDateBrand]: 'plain-date' };
+
+/** The shape a CHECK constraint and a JSON Schema both spell. ECMAScript and POSIX ERE agree. */
+export const PLAIN_DATE_PATTERN = '^\\d{4}-\\d{2}-\\d{2}$';
+
+const SHAPE = /^(\d{4})-(\d{2})-(\d{2})$/;
+
+export interface PlainDateParts {
+  readonly year: number;
+  readonly month: number;
+  readonly day: number;
+}
+
+const pad = (value: number, width: number): string => String(value).padStart(width, '0');
+
+/** Days in a month, Gregorian. February is the only interesting one. */
+const daysInMonth = (year: number, month: number): number =>
+  month === 2
+    ? (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0
+      ? 29
+      : 28
+    : [4, 6, 9, 11].includes(month)
+      ? 30
+      : 31;
+
+/**
+ * The parse every other function here goes through. `null` rather than a throw, so the guard and
+ * the thrower share one rule and only the failure policy differs — the same split
+ * `resolveEnvironment` / `tryResolveEnvironment` make in core.
+ */
+const read = (value: unknown): PlainDateParts | null => {
+  if (typeof value !== 'string') return null;
+  const match = SHAPE.exec(value);
+  if (match === null) return null;
+  const year = Number(match[1]);
+  const month = Number(match[2]);
+  const day = Number(match[3]);
+  if (month < 1 || month > 12) return null;
+  // A day the month does not have is the case a regex cannot see, and it is the one that matters:
+  // `2026-02-30` reaches Postgres as `date` input and is rejected there, three layers later.
+  if (day < 1 || day > daysInMonth(year, month)) return null;
+  return { year, month, day };
+};
+
+export const isPlainDate = (value: unknown): value is PlainDate => read(value) !== null;
+
+/** A calendar date from its ISO form. Throws on anything that is not one — including `2026-02-30`. */
+export function plainDate(value: string): PlainDate {
+  const parts = read(value);
+  if (parts === null) {
+    throw scheduleInvalid('date', value, 'a real YYYY-MM-DD calendar date');
+  }
+  return value as PlainDate;
+}
+
+/** A calendar date from its fields. Out-of-range fields throw rather than wrap into another month. */
+export function plainDateOf(parts: PlainDateParts): PlainDate {
+  return plainDate(`${pad(parts.year, 4)}-${pad(parts.month, 2)}-${pad(parts.day, 2)}`);
+}
+
+export function plainDateParts(date: PlainDate): PlainDateParts {
+  const parts = read(date);
+  if (parts === null) throw scheduleInvalid('date', date, 'a real YYYY-MM-DD calendar date');
+  return parts;
+}
+
+/**
+ * The calendar date an instant falls on **in a named zone** — the one conversion between the two,
+ * and it takes a zone because there is no other honest way to make it. 09:00 UTC on the 14th is
+ * still the 13th in Los Angeles.
+ */
+export const plainDateIn = (at: Instant, zone: TimeZone): PlainDate =>
+  isoDateInZone(at, zone) as PlainDate;
+
+/**
+ * The calendar date a `Date` holds when read as UTC. For ONE caller: a Postgres driver hands a
+ * `date` column back as a `Date` at UTC midnight (measured: Bun's `sql` and PGlite both), so the
+ * date the column holds is its UTC date and reading it through the local zone loses a day west of
+ * Greenwich. Never use this on a timestamp — that is `plainDateIn`, which asks for the zone.
+ */
+export function plainDateUtc(at: Date): PlainDate {
+  const checked = instant(at);
+  return `${pad(checked.getUTCFullYear(), 4)}-${pad(checked.getUTCMonth() + 1, 2)}-${pad(
+    checked.getUTCDate(),
+    2,
+  )}` as PlainDate;
+}
+
+/** Midnight UTC of the date, as an instant — the inverse of `plainDateUtc`, and never of `plainDateIn`. */
+export const plainDateToUtcInstant = (date: PlainDate): Instant =>
+  instant(new Date(`${plainDate(date)}T00:00:00.000Z`));
+
+/** `-1`, `0`, `1`. Lexicographic order IS chronological order for this form; that is why it sorts. */
+export const comparePlainDates = (left: PlainDate, right: PlainDate): number =>
+  left < right ? -1 : left > right ? 1 : 0;
+
+const DAY_MS = 86_400_000;
+
+/** Whole days added, over UTC midnights, so no DST rule and no zone can shorten a day here. */
+export function addPlainDays(date: PlainDate, days: number): PlainDate {
+  if (!Number.isSafeInteger(days)) {
+    throw scheduleInvalid('days', days, 'a whole number of days');
+  }
+  return plainDateUtc(new Date(plainDateToUtcInstant(date).getTime() + days * DAY_MS));
+}
+
+/** Signed whole days from `from` to `to`. Always integral: both ends are UTC midnights. */
+export const plainDaysBetween = (from: PlainDate, to: PlainDate): number =>
+  (plainDateToUtcInstant(to).getTime() - plainDateToUtcInstant(from).getTime()) / DAY_MS;

package/src/zone-canonical.ts

@@ -4,7 +4,7 @@
  * A 13-letter name has 2^12 casings and a request header can name any of them.
  */
 
-import { cachedFormatter } from './intl-cache';
+import { cachedFormatter } from '@ultimat3/core';
 
 /** ES2024 `Intl` accepts `+01:00` as a zone; we do not — a fixed offset has no DST rules. */
 const NUMERIC_OFFSET = /^[+-]/;

package/src/zones.ts

@@ -4,9 +4,9 @@
  * is no offset table to keep in sync and no `date-fns-tz` dependency.
  */
 
+import { cachedFormatter, canonicalLocale } from '@ultimat3/core';
 import { timezoneInvalid } from './errors';
 import type { Instant } from './instant';
-import { cachedFormatter } from './intl-cache';
 import { canonicalTimeZone } from './zone-canonical';
 
 /** An IANA identifier: `Europe/Berlin`, `Asia/Kathmandu`, `UTC`. Never `CET`, never `+01:00`. */
@@ -117,13 +117,22 @@ export function zoneAbbrev(
   locale = 'en-US',
   style: 'short' | 'long' | 'shortOffset' | 'longOffset' = 'short',
 ): string {
-  const formatter = new Intl.DateTimeFormat(locale, {
-    timeZone: zone,
-    timeZoneName: style,
-    hourCycle: 'h23',
+  const canonical = assertTimeZone(zone);
+  // A tag `Intl` cannot parse falls through unchanged, exactly as in `format.ts`: this decides a
+  // cache key, never whether a locale is acceptable.
+  const tag = canonicalLocale(locale) ?? locale;
+  // The one `Intl` construction in this package that escaped the shared cache: it built a formatter
+  // per call on the caller's raw zone and locale, so an `x-timezone` an app renders a label from
+  // paid for a fresh `Intl.DateTimeFormat` every time and an unknown one escaped as a `RangeError`.
+  const formatter = cachedFormatter(labelFormatters, `${canonical}|${tag}|${style}`, () => {
+    return new Intl.DateTimeFormat(tag, {
+      timeZone: canonical,
+      timeZoneName: style,
+      hourCycle: 'h23',
+    });
   });
   const label = formatter.formatToParts(at).find((part) => part.type === 'timeZoneName')?.value;
-  return label ?? offsetLabel(offsetAt(zone, at));
+  return label ?? offsetLabel(offsetAt(canonical, at));
 }
 
 /**
@@ -145,6 +154,7 @@ export function observesDst(zone: TimeZone, at: Instant): boolean {
 }
 
 const formatters = new Map<string, Intl.DateTimeFormat>();
+const labelFormatters = new Map<string, Intl.DateTimeFormat>();
 
 function partsFormatterFor(zone: TimeZone): Intl.DateTimeFormat {
   // Keyed on the canonical name, so 4,096 casings of one zone are one entry rather than 4,096.

package/src/intl-cache.ts

@@ -1,26 +0,0 @@
-/**
- * One bounded cache for every `Intl` formatter this package builds.
- * A locale and a zone both arrive from a request header, so an unbounded `Map` keyed on that
- * string is memory the client chooses: 4,096 case-variants of one zone name retained 31 MB,
- * ~7.7 KB per `Intl.DateTimeFormat`, and 600 zones times 2^12 casings has no ceiling at all.
- */
-
-/**
- * Above the full canonical IANA set (445 zones as of tzdata 2025) so a correct app never evicts,
- * and small enough that the worst case is a few megabytes rather than a leak. A miss costs one
- * `Intl` construction, never a wrong answer — which is what makes a bound safe here at all.
- */
-export const MAX_CACHED_FORMATTERS = 512;
-
-/** FIFO — a `Map` iterates in insertion order, so the first key inserted is the first evicted. */
-export function cachedFormatter<T>(cache: Map<string, T>, key: string, build: () => T): T {
-  const hit = cache.get(key);
-  if (hit !== undefined) return hit;
-  const formatter = build();
-  if (cache.size >= MAX_CACHED_FORMATTERS) {
-    const oldest = cache.keys().next().value;
-    if (oldest !== undefined) cache.delete(oldest);
-  }
-  cache.set(key, formatter);
-  return formatter;
-}

package/src/locale-canonical.ts

@@ -1,23 +0,0 @@
-/**
- * One locale, one key. `Intl` accepts `EN-us`, `en-US` and `en-latn-us` as the same locale, so a
- * cache keyed on the caller's spelling holds three formatters where one would do — and the caller
- * is `Accept-Language`. The twin of `zone-canonical.ts`, for the other header-supplied string.
- */
-
-/**
- * The canonical BCP 47 spelling, or `undefined` when the tag is not structurally valid at all
- * (`en_US`, `''`, `not a locale`). Well-formed but unknown to ICU (`zz`) is a locale — `Intl`
- * falls back for it, and refusing here would be stricter than the formatters this feeds.
- *
- * Deliberately **not** memoised: this is string work, and a `Map` keyed on a header value is the
- * unbounded cache the whole `intl-cache.ts` bound exists to prevent.
- */
-export function canonicalLocale(locale: string): string | undefined {
-  try {
-    // `getCanonicalLocales` runs the same IsStructurallyValidLanguageTag check that
-    // `supportedLocalesOf` throws on, and unlike it, hands back the canonical spelling.
-    return Intl.getCanonicalLocales(locale)[0];
-  } catch {
-    return undefined;
-  }
-}