@ultimat3/time 29.4.0 → 30.1.0

package/README.md

@@ -5,6 +5,15 @@ An `Instant` is a point on the UTC timeline with no zone attached. Zones exist o
 a human reads the value. No formatter in this package has an ambient default zone, and
 none ever will — "the server's timezone" is not an answer to "what time is it for the user".
 
+`bun add @ultimat3/time` · guide: [Timezones And Dates](https://github.com/developerz-ai/ultimate/wiki/Timezones-And-Dates)
+
+```ts
+import { formatDateTime, fromIso } from '@ultimat3/time';
+
+formatDateTime(fromIso('2026-03-14T08:00:00Z'), { locale: 'en-GB', zone: 'Europe/Berlin' });
+// '14 Mar 2026, 09:00:00' — no zone, no format: there is no ambient default
+```
+
 | Concern | Store | Format / compute |
 |---|---|---|
 | Instants | UTC (`timestamptz`, ISO-8601 `Z`) | `Intl.DateTimeFormat` + explicit `timeZone` |
@@ -21,6 +30,11 @@ answers the canonical spelling (or `undefined`), and `assertTimeZone` / `resolve
 return it. Anything reading a zone off a request header should canonicalize before caching on it:
 4,096 casings of `Europe/Berlin` used to mint 4,096 permanent `Intl.DateTimeFormat`s, 31 MB.
 
+**The request's zone, in order:** `user`, `cookie` (a picker's `x_timezone`), `query` (`?tz=`),
+`header` (`x-timezone`), `detected` (`TIMEZONE_DETECTED_COOKIE`, `x_timezone_detected`), then the
+`configureTime` default. `detected` is what `@ultimat3/render`'s `zoneScript` writes on `app/`
+documents under `time: { detect: true }`: a guess, below everything chosen, never written over it.
+
 **A zone is `Area/Location`, or `UTC`.** Nothing else. `CET`, `EST5EDT` and `+02:00` name no
 jurisdiction and carry no DST rule; the single-label `backward` links (`Japan`, `GB`, `Eire`) are
 refused with them, because no rule keeps the first group out and lets the second in. Write the

package/package.json

@@ -1,7 +1,18 @@
 {
   "name": "@ultimat3/time",
-  "version": "29.4.0",
+  "version": "30.1.0",
   "description": "UTC instants, DST-correct zone math, cron, durations and Intl formatting with an explicit timezone",
+  "keywords": [
+    "ultimate",
+    "bun",
+    "framework",
+    "time",
+    "timezone",
+    "cron",
+    "dates",
+    "intl"
+  ],
+  "homepage": "https://github.com/developerz-ai/ultimate/wiki/Timezones-And-Dates",
   "license": "MIT",
   "type": "module",
   "sideEffects": [
@@ -35,7 +46,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "29.4.0",
-    "@ultimat3/schema": "29.4.0"
+    "@ultimat3/core": "30.1.0",
+    "@ultimat3/schema": "30.1.0"
   }
 }

package/src/context.ts

@@ -11,6 +11,13 @@ import { assertTimeZone, type TimeZone, UTC } from './zones';
 /** Header a client sets from `Intl.DateTimeFormat().resolvedOptions().timeZone`. */
 export const TIMEZONE_HEADER = 'x-timezone';
 
+/**
+ * Cookie `@ultimat3/render`'s zone script writes from the same `Intl` call, on `app/` documents: a
+ * document navigation sends no header, so without it a new visitor's first pages render in UTC.
+ * Never the chosen cookie — a guess written there would erase the visitor's own pick.
+ */
+export const TIMEZONE_DETECTED_COOKIE = 'x_timezone_detected';
+
 export interface TimeZoneSources {
   /** `user.timeZone` — an explicit preference beats a browser guess. */
   user?: string | null;
@@ -20,6 +27,8 @@ export interface TimeZoneSources {
   query?: string | null;
   /** `x-timezone` request header. */
   header?: string | null;
+  /** `x_timezone_detected`, the zone script's guess — below the header a client sent on purpose. */
+  detected?: string | null;
 }
 
 export type TimeZoneSourceName = keyof TimeZoneSources;
@@ -39,9 +48,15 @@ export interface TimeConfig {
  * Explicit before inferred, the same rule `@ultimat3/i18n`'s locale order states: `Accept-Language`
  * and `x-timezone` are what the browser was installed as, while the user row, the cookie and the
  * query are what a person *chose*. A zone picker that wrote a cookie the header always outranked
- * would appear to do nothing.
+ * would appear to do nothing. `detected` is last: a script's guess, written with no request asking.
  */
-const DEFAULT_ORDER: readonly TimeZoneSourceName[] = ['user', 'cookie', 'query', 'header'];
+const DEFAULT_ORDER: readonly TimeZoneSourceName[] = [
+  'user',
+  'cookie',
+  'query',
+  'header',
+  'detected',
+];
 
 let config: TimeConfig = { defaultZone: UTC, order: DEFAULT_ORDER };
 

package/src/index.ts

@@ -20,6 +20,7 @@ export {
   configureTime,
   currentTimeZone,
   resolveTimeZone,
+  TIMEZONE_DETECTED_COOKIE,
   TIMEZONE_HEADER,
   type TimeConfig,
   type TimeZoneResolution,

package/src/zoned.ts

@@ -9,6 +9,7 @@ import {
   assertTimeZone,
   offsetAt,
   offsetLabel,
+  offsetSecondsAt,
   type TimeZone,
   utcEpoch,
   zonePartsAt,
@@ -91,7 +92,8 @@ export function toZoned(at: Instant, zone: TimeZone): ZonedDateTime {
  *      - exactly one                      → normal case
  *      - none                             → the hour was skipped (gap)
  *
- * Milliseconds ride along untouched: every real offset is a whole number of minutes.
+ * Milliseconds ride along untouched: an offset is whole seconds, the search is in seconds, and a
+ * zone off the minute (Africa/Monrovia until 1972) is searched at its real offset.
  */
 export function fromZonedDetailed(
   wall: WallClock,
@@ -114,11 +116,11 @@ export function fromZonedDetailed(
   );
 
   const probes = [target - 86_400_000, target, target + 86_400_000];
-  const offsets = new Set(probes.map((ms) => offsetAt(zone, new Date(ms) as Instant)));
+  const offsets = new Set(probes.map((ms) => offsetSecondsAt(zone, new Date(ms) as Instant)));
 
   const verified: number[] = [];
-  for (const offsetMinutes of offsets) {
-    const candidate = target - offsetMinutes * 60_000;
+  for (const offsetSeconds of offsets) {
+    const candidate = target - offsetSeconds * 1000;
     if (matchesWall(candidate, zone, normal)) verified.push(candidate);
   }
   const distinct = [...new Set(verified)].sort((a, b) => a - b);
@@ -136,7 +138,7 @@ export function fromZonedDetailed(
   // the smaller lands before the transition, the larger after it.
   if (gap === 'throw') throw dstNonexistent(describeWall(normal), zone);
   const bracket = [...offsets]
-    .map((offsetMinutes) => target - offsetMinutes * 60_000)
+    .map((offsetSeconds) => target - offsetSeconds * 1000)
     .sort((a, b) => a - b);
   const chosen = gap === 'next' ? bracket[bracket.length - 1] : bracket[0];
   return finish(chosen ?? target, millisecond, zone, 'gap');
@@ -184,6 +186,9 @@ export function addDaysInZone(at: Instant, days: number, zone: TimeZone): Instan
   if (!Number.isSafeInteger(days)) {
     throw scheduleInvalid('days', days, 'a whole number of days');
   }
+  // Identity, and not a round trip: the wall clock of a repeated hour names two instants, and
+  // reading this one back answered the first pass whichever one `at` was.
+  if (days === 0) return at;
   const zoned = toZoned(at, zone);
   return fromZoned(
     {
@@ -211,12 +216,18 @@ export function isoDateInZone(at: Instant, zone: TimeZone): string {
  * (which is what `toIso` is for). The form a schedule is read in: the two passes of a fall-back
  * hour are one wall time and two instants, and the offset is the only thing that tells them
  * apart. Seconds precision; `fromIso` reads it back to the same second.
+ *
+ * An offset off the minute (Africa/Monrovia, -00:44:30 until 1972) has no ISO-8601 spelling — an
+ * offset is `±HH:MM`, and `fromIso` refuses more — so the label rounds and the clock written is the
+ * one THAT label names: 30 s from the zone's own dial, never 30 s from the instant.
  */
 export function isoInZone(at: Instant, zone: TimeZone): string {
-  const zoned = toZoned(at, zone);
-  const date = `${String(zoned.year).padStart(4, '0')}-${pad2(zoned.month)}-${pad2(zoned.day)}`;
-  const time = `${pad2(zoned.hour)}:${pad2(zoned.minute)}:${pad2(zoned.second)}`;
-  return `${date}T${time}${offsetLabel(zoned.offsetMinutes)}`;
+  const offsetMinutes = toZoned(at, zone).offsetMinutes;
+  const clock = new Date(Math.floor(at.getTime() / 1000) * 1000 + offsetMinutes * 60_000);
+  const year = String(clock.getUTCFullYear()).padStart(4, '0');
+  const date = `${year}-${pad2(clock.getUTCMonth() + 1)}-${pad2(clock.getUTCDate())}`;
+  const time = `${pad2(clock.getUTCHours())}:${pad2(clock.getUTCMinutes())}:${pad2(clock.getUTCSeconds())}`;
+  return `${date}T${time}${offsetLabel(offsetMinutes)}`;
 }
 
 /** True when both instants fall on the same local calendar day. */

package/src/zones.ts

@@ -102,10 +102,29 @@ export function offsetAt(zone: TimeZone, at: Instant): number {
     parts.minute,
     parts.second,
   );
-  // Offsets are whole minutes; rounding absorbs the sub-second part `asIfUtc` drops.
+  // Rounded for a label: modern offsets are whole minutes, a historic one is `offsetSecondsAt`'s.
   return Math.round((asIfUtc - at.getTime()) / 60_000);
 }
 
+/**
+ * The same difference in SECONDS, unrounded: what an instant is computed from. A zone's history
+ * holds offsets off the minute (Africa/Monrovia was -00:44:30 until 1972), and rounding one moved
+ * every instant built from it. Internal: a label and `offsetMinutes` are the public reading.
+ */
+export function offsetSecondsAt(zone: TimeZone, at: Instant): number {
+  const parts = zonePartsAt(zone, at);
+  const asIfUtc = utcEpoch(
+    parts.year,
+    parts.month,
+    parts.day,
+    parts.hour,
+    parts.minute,
+    parts.second,
+  );
+  // Whole seconds on both sides: the wall clock above has dropped the milliseconds.
+  return (asIfUtc - Math.floor(at.getTime() / 1000) * 1000) / 1000;
+}
+
 /** `+01:00`, `-04:00`, `+05:45`, `Z`. */
 export function offsetLabel(minutes: number): string {
   if (minutes === 0) return 'Z';