@ultimat3/time 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 developerz.ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,98 @@
+# 🕒 @ultimat3/time
+
+**Golden rule: store UTC, format at the edge, always with an explicit IANA zone.**
+An `Instant` is a point on the UTC timeline with no zone attached. Zones exist only where
+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".
+
+| Concern | Store | Format / compute |
+|---|---|---|
+| Instants | UTC (`timestamptz`, ISO-8601 `Z`) | `Intl.DateTimeFormat` + explicit `timeZone` |
+| Wall clock | never | `toZoned` / `fromZoned` with a DST policy |
+| Zone | on the user record | resolved once per request into the ALS context |
+| Durations | milliseconds | `parseDuration('2h30m')`, `formatDuration(ms, locale)` |
+| Schedules | cron + IANA zone | `nextCronOccurrence`, `nextLocalSlot` |
+
+No `date-fns-tz`, no tzdata table. Zone math is derived from `Intl.DateTimeFormat` +
+`formatToParts`, which is exact in Bun and always current with the runtime's tzdata.
+
+## Use
+
+```ts
+import { formatWithOffset, fromIso, nextLocalSlot, now, toZoned } from '@ultimat3/time';
+
+const at = fromIso('2026-03-14T08:00:00Z');
+formatWithOffset(at, { locale: 'en-GB', zone: 'Europe/Berlin' });
+// "14 Mar 2026, 09:00 (GMT+1)"
+formatWithOffset(at, { locale: 'en-GB', zone: 'America/New_York' });
+// "14 Mar 2026, 04:00 (GMT-4)"
+
+nextLocalSlot({ zone: 'Asia/Kathmandu', hour: 9 }, now(clock)); // 09:00 local, +05:45 handled
+```
+
+## DST is a policy, not a guess
+
+`fromZoned(wall, zone, { gap, overlap })` is the function everything else is built on.
+
+| Case | What happens | Policy |
+|---|---|---|
+| Normal | one instant matches the wall clock | — |
+| **Gap** (spring forward) | `02:30` never happens | `'next'` (default), `'previous'`, `'throw'` |
+| **Overlap** (fall back) | `01:30` happens twice | `'first'` (default), `'second'`, `'throw'` |
+
+It works by search-and-verify: read the wall-clock fields as if they were UTC, subtract
+each candidate offset in force around that moment, then convert each candidate *back* and
+keep the ones that reproduce the requested wall clock. Two survivors means overlap, none
+means gap. `fromZonedDetailed()` returns which case it was — log it when scheduling.
+
+Half-hour and 45-minute zones (`Asia/Kolkata`, `Asia/Kathmandu`, `Australia/Adelaide`,
+`Pacific/Chatham`) are ordinary cases here, not special ones.
+
+## Calendar days
+
+**Never cross a day boundary with `86_400_000`.** A local day is 23, 24 or 25 hours long. Every
+one of these takes the zone explicitly, and none of them has a default.
+
+| Function | Answers |
+|---|---|
+| `startOfDay(at, zone)` / `endOfDay(at, zone)` | local midnight; the last millisecond of the day |
+| `addDaysInZone(at, days, zone)` | the same wall-clock time, `days` calendar days away |
+| `daysBetween(from, to, zone)` | local day boundaries crossed — signed, always integral |
+| `isoDateInZone(at, zone)` | `2026-03-14` |
+| `isSameLocalDay(left, right, zone)` | whether two instants share a local date |
+
+`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`.
+
+## Cron
+
+`parseCron` handles 5 or 6 fields, `*/n`, ranges, lists, named months and days, `@daily`
+macros, and Vixie's dom/dow OR rule. `nextCronOccurrence(expr, zone, after)` iterates the
+zone's **wall clock**, so `0 3 * * *` in `Europe/Berlin` stays at 03:00 local across a DST
+change, and a job scheduled inside the gap runs at the first existing local time instead of
+being skipped. `describeCron(expr, locale, phrases)` renders the dashboard summary — month and
+weekday names from `Intl`, every connective word **required** from the caller's `t('time.cron.*')`,
+because tier 1 cannot reach `t()` and a built-in default would ship English to every locale. A
+long clock-time list is capped and the remainder counted with `andMore`, never silently cut.
+
+## Business days
+
+The weekend is configuration. `WEEKEND_SAT_SUN`, `WEEKEND_FRI_SAT` (much of the Gulf),
+`WEEKEND_SUN_ONLY`, plus a holiday list of local `YYYY-MM-DD` dates.
+
+## Errors
+
+| Code | When |
+|---|---|
+| `X_TIMEZONE_INVALID` | not an IANA name (abbreviations and numeric offsets are rejected) |
+| `X_CRON_INVALID` | unparseable expression, or one that can never match |
+| `X_DURATION_INVALID` | `'3'` with no unit, trailing junk, unknown unit |
+| `X_DST_AMBIGUOUS` | overlap hit with `overlap: 'throw'` |
+| `X_DST_NONEXISTENT` | gap hit with `gap: 'throw'` |
+| `X_INSTANT_INVALID` | unparseable timestamp |
+| `X_LOCALE_INVALID` | a tag `Intl` cannot parse (`en_US`, `''`) reached `describeCron` |
+
+## Why it exists
+
+Naive time math breaks quietly: the digest goes out an hour early for half the year, the
+reminder never fires on the spring-forward day, and nobody notices until a customer does.

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@ultimat3/time",
+  "version": "1.0.0",
+  "description": "UTC instants, DST-correct zone math, cron, durations and Intl formatting with an explicit timezone",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/developerz-ai/ultimate.git",
+    "directory": "packages/time"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@ultimat3/core": "1.0.0"
+  }
+}

package/src/business.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Business-day math. The weekend is configuration, not a constant: Friday/Saturday in
+ * much of the Gulf, Sunday-only in parts of Asia, Saturday/Sunday in the West.
+ */
+import type { Instant } from './instant';
+import type { TimeZone } from './zones';
+/** ISO weekday numbers: 1 = Monday … 7 = Sunday. */
+export type IsoWeekday = 1 | 2 | 3 | 4 | 5 | 6 | 7;
+export declare const WEEKEND_SAT_SUN: readonly IsoWeekday[];
+/** Gulf states, and the default in Israel (Fri/Sat). */
+export declare const WEEKEND_FRI_SAT: readonly IsoWeekday[];
+export declare const WEEKEND_SUN_ONLY: readonly IsoWeekday[];
+export interface BusinessCalendar {
+    zone: TimeZone;
+    /** Defaults to Saturday + Sunday, which is a choice, not a law. */
+    weekendDays?: readonly IsoWeekday[];
+    /** Local `YYYY-MM-DD` dates that are holidays in this calendar. */
+    holidays?: readonly string[];
+}
+export declare function isWeekend(at: Instant, zone: TimeZone, weekendDays?: readonly IsoWeekday[]): boolean;
+export declare function isHoliday(at: Instant, calendar: BusinessCalendar): boolean;
+/** A business day is a non-weekend, non-holiday local day. */
+export declare function isBusinessDay(at: Instant, calendar: BusinessCalendar): boolean;
+/**
+ * Move `days` business days forward (or back, if negative), keeping the local wall-clock
+ * time. `days === 0` returns the input untouched, even on a weekend — callers that want
+ * "the next business day" should ask for 1.
+ */
+export declare function addBusinessDays(at: Instant, days: number, calendar: BusinessCalendar): Instant;
+/** The next business day at the same local time; today if it already qualifies. */
+export declare function nextBusinessDay(at: Instant, calendar: BusinessCalendar): Instant;
+/**
+ * Business days in `[from, to)`, counted on local calendar days. Order-independent:
+ * a reversed range returns a negative count.
+ */
+export declare function businessDaysBetween(from: Instant, to: Instant, calendar: BusinessCalendar): number;
+//# sourceMappingURL=business.d.ts.map

package/src/business.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"business.d.ts","sourceRoot":"","sources":["business.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAExC,oDAAoD;AACpD,MAAM,MAAM,UAAU,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAEnD,eAAO,MAAM,eAAe,EAAE,SAAS,UAAU,EAAW,CAAC;AAC7D,wDAAwD;AACxD,eAAO,MAAM,eAAe,EAAE,SAAS,UAAU,EAAW,CAAC;AAC7D,eAAO,MAAM,gBAAgB,EAAE,SAAS,UAAU,EAAQ,CAAC;AAE3D,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,QAAQ,CAAC;IACf,mEAAmE;IACnE,WAAW,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;IACpC,mEAAmE;IACnE,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC9B;AAED,wBAAgB,SAAS,CAAC,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,wBAAkB,GAAG,OAAO,CAE7F;AAED,wBAAgB,SAAS,CAAC,EAAE,EAAE,OAAO,EAAE,QAAQ,EAAE,gBAAgB,GAAG,OAAO,CAG1E;AAED,8DAA8D;AAC9D,wBAAgB,aAAa,CAAC,EAAE,EAAE,OAAO,EAAE,QAAQ,EAAE,gBAAgB,GAAG,OAAO,CAK9E;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,gBAAgB,GAAG,OAAO,CAe9F;AAED,mFAAmF;AACnF,wBAAgB,eAAe,CAAC,EAAE,EAAE,OAAO,EAAE,QAAQ,EAAE,gBAAgB,GAAG,OAAO,CAEhF;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,OAAO,EACb,EAAE,EAAE,OAAO,EACX,QAAQ,EAAE,gBAAgB,GACzB,MAAM,CAYR"}

package/src/business.js

@@ -0,0 +1,68 @@
+/**
+ * Business-day math. The weekend is configuration, not a constant: Friday/Saturday in
+ * much of the Gulf, Sunday-only in parts of Asia, Saturday/Sunday in the West.
+ */
+import { addDaysInZone, isoDateInZone, toZoned } from './zoned';
+export const WEEKEND_SAT_SUN = [6, 7];
+/** Gulf states, and the default in Israel (Fri/Sat). */
+export const WEEKEND_FRI_SAT = [5, 6];
+export const WEEKEND_SUN_ONLY = [7];
+export function isWeekend(at, zone, weekendDays = WEEKEND_SAT_SUN) {
+    return weekendDays.includes(toZoned(at, zone).weekday);
+}
+export function isHoliday(at, calendar) {
+    const holidays = calendar.holidays ?? [];
+    return holidays.includes(isoDateInZone(at, calendar.zone));
+}
+/** A business day is a non-weekend, non-holiday local day. */
+export function isBusinessDay(at, calendar) {
+    return (!isWeekend(at, calendar.zone, calendar.weekendDays ?? WEEKEND_SAT_SUN) &&
+        !isHoliday(at, calendar));
+}
+/**
+ * Move `days` business days forward (or back, if negative), keeping the local wall-clock
+ * time. `days === 0` returns the input untouched, even on a weekend — callers that want
+ * "the next business day" should ask for 1.
+ */
+export function addBusinessDays(at, days, calendar) {
+    if (days === 0)
+        return at;
+    const step = days > 0 ? 1 : -1;
+    let remaining = Math.abs(days);
+    let cursor = at;
+    let guard = 0;
+    while (remaining > 0) {
+        cursor = addDaysInZone(cursor, step, calendar.zone);
+        if (isBusinessDay(cursor, calendar))
+            remaining -= 1;
+        guard += 1;
+        // A calendar with every day marked as a holiday would otherwise loop forever.
+        if (guard > Math.abs(days) * 7 + 3650)
+            return cursor;
+    }
+    return cursor;
+}
+/** The next business day at the same local time; today if it already qualifies. */
+export function nextBusinessDay(at, calendar) {
+    return isBusinessDay(at, calendar) ? at : addBusinessDays(at, 1, calendar);
+}
+/**
+ * Business days in `[from, to)`, counted on local calendar days. Order-independent:
+ * a reversed range returns a negative count.
+ */
+export function businessDaysBetween(from, to, calendar) {
+    const sign = to.getTime() < from.getTime() ? -1 : 1;
+    const start = sign === 1 ? from : to;
+    const end = sign === 1 ? to : from;
+    let cursor = start;
+    let count = 0;
+    while (isoDateInZone(cursor, calendar.zone) !== isoDateInZone(end, calendar.zone)) {
+        cursor = addDaysInZone(cursor, 1, calendar.zone);
+        if (cursor.getTime() > end.getTime())
+            break;
+        if (isBusinessDay(cursor, calendar))
+            count += 1;
+    }
+    return sign * count;
+}
+//# sourceMappingURL=business.js.map

package/src/business.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"business.js","sourceRoot":"","sources":["business.ts"],"names":[],"mappings":"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"}

package/src/business.ts

@@ -0,0 +1,90 @@
+/**
+ * Business-day math. The weekend is configuration, not a constant: Friday/Saturday in
+ * much of the Gulf, Sunday-only in parts of Asia, Saturday/Sunday in the West.
+ */
+
+import type { Instant } from './instant';
+import { addDaysInZone, isoDateInZone, toZoned } from './zoned';
+import type { TimeZone } from './zones';
+
+/** ISO weekday numbers: 1 = Monday … 7 = Sunday. */
+export type IsoWeekday = 1 | 2 | 3 | 4 | 5 | 6 | 7;
+
+export const WEEKEND_SAT_SUN: readonly IsoWeekday[] = [6, 7];
+/** Gulf states, and the default in Israel (Fri/Sat). */
+export const WEEKEND_FRI_SAT: readonly IsoWeekday[] = [5, 6];
+export const WEEKEND_SUN_ONLY: readonly IsoWeekday[] = [7];
+
+export interface BusinessCalendar {
+  zone: TimeZone;
+  /** Defaults to Saturday + Sunday, which is a choice, not a law. */
+  weekendDays?: readonly IsoWeekday[];
+  /** Local `YYYY-MM-DD` dates that are holidays in this calendar. */
+  holidays?: readonly string[];
+}
+
+export function isWeekend(at: Instant, zone: TimeZone, weekendDays = WEEKEND_SAT_SUN): boolean {
+  return weekendDays.includes(toZoned(at, zone).weekday as IsoWeekday);
+}
+
+export function isHoliday(at: Instant, calendar: BusinessCalendar): boolean {
+  const holidays = calendar.holidays ?? [];
+  return holidays.includes(isoDateInZone(at, calendar.zone));
+}
+
+/** A business day is a non-weekend, non-holiday local day. */
+export function isBusinessDay(at: Instant, calendar: BusinessCalendar): boolean {
+  return (
+    !isWeekend(at, calendar.zone, calendar.weekendDays ?? WEEKEND_SAT_SUN) &&
+    !isHoliday(at, calendar)
+  );
+}
+
+/**
+ * Move `days` business days forward (or back, if negative), keeping the local wall-clock
+ * time. `days === 0` returns the input untouched, even on a weekend — callers that want
+ * "the next business day" should ask for 1.
+ */
+export function addBusinessDays(at: Instant, days: number, calendar: BusinessCalendar): Instant {
+  if (days === 0) return at;
+  const step = days > 0 ? 1 : -1;
+  let remaining = Math.abs(days);
+  let cursor = at;
+  let guard = 0;
+
+  while (remaining > 0) {
+    cursor = addDaysInZone(cursor, step, calendar.zone);
+    if (isBusinessDay(cursor, calendar)) remaining -= 1;
+    guard += 1;
+    // A calendar with every day marked as a holiday would otherwise loop forever.
+    if (guard > Math.abs(days) * 7 + 3650) return cursor;
+  }
+  return cursor;
+}
+
+/** The next business day at the same local time; today if it already qualifies. */
+export function nextBusinessDay(at: Instant, calendar: BusinessCalendar): Instant {
+  return isBusinessDay(at, calendar) ? at : addBusinessDays(at, 1, calendar);
+}
+
+/**
+ * Business days in `[from, to)`, counted on local calendar days. Order-independent:
+ * a reversed range returns a negative count.
+ */
+export function businessDaysBetween(
+  from: Instant,
+  to: Instant,
+  calendar: BusinessCalendar,
+): number {
+  const sign = to.getTime() < from.getTime() ? -1 : 1;
+  const start = sign === 1 ? from : to;
+  const end = sign === 1 ? to : from;
+  let cursor = start;
+  let count = 0;
+  while (isoDateInZone(cursor, calendar.zone) !== isoDateInZone(end, calendar.zone)) {
+    cursor = addDaysInZone(cursor, 1, calendar.zone);
+    if (cursor.getTime() > end.getTime()) break;
+    if (isBusinessDay(cursor, calendar)) count += 1;
+  }
+  return sign * count;
+}

package/src/context.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Resolve the request timezone once, then read it from the ALS context.
+ * User record → header → config default. Every formatter still takes the zone
+ * explicitly; this is where call sites get the value from, not a hidden default.
+ */
+import { type Ctx } from '@ultimat3/core';
+import { type TimeZone } from './zones';
+/** Header a client sets from `Intl.DateTimeFormat().resolvedOptions().timeZone`. */
+export declare const TIMEZONE_HEADER = "x-timezone";
+export interface TimeZoneSources {
+    /** `user.timeZone` — an explicit preference beats a browser guess. */
+    user?: string | null;
+    /** `x-timezone` request header. */
+    header?: string | null;
+    /** `?tz=Europe/Berlin`, for share links and email previews. */
+    query?: string | null;
+}
+export type TimeZoneSourceName = keyof TimeZoneSources;
+export interface TimeZoneResolution {
+    zone: TimeZone;
+    source: TimeZoneSourceName | 'default';
+}
+export interface TimeConfig {
+    /** The zone used when nothing else resolves. UTC unless the app says otherwise. */
+    defaultZone: TimeZone;
+    order: readonly TimeZoneSourceName[];
+}
+export declare function configureTime(partial: Partial<TimeConfig>): TimeConfig;
+export declare function timeConfig(): TimeConfig;
+/**
+ * First valid IANA name wins. An invalid value is skipped, never thrown: a stale
+ * `x-timezone` header from an old client must not fail the request.
+ */
+export declare function resolveTimeZone(sources: TimeZoneSources, overrides?: Partial<TimeConfig>): TimeZoneResolution;
+/** Called once per request by the HTTP layer. */
+export declare function attachTimeZone(ctx: Ctx, zone: TimeZone): TimeZone;
+export declare function timeZoneOf(ctx: Ctx): TimeZone;
+/** Ambient zone for the in-flight request; the configured default outside one. */
+export declare function currentTimeZone(): TimeZone;
+//# sourceMappingURL=context.d.ts.map

package/src/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["context.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,KAAK,GAAG,EAAc,MAAM,gBAAgB,CAAC;AACtD,OAAO,EAAmB,KAAK,QAAQ,EAAO,MAAM,SAAS,CAAC;AAE9D,oFAAoF;AACpF,eAAO,MAAM,eAAe,eAAe,CAAC;AAI5C,MAAM,WAAW,eAAe;IAC9B,sEAAsE;IACtE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,mCAAmC;IACnC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,+DAA+D;IAC/D,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED,MAAM,MAAM,kBAAkB,GAAG,MAAM,eAAe,CAAC;AAEvD,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,QAAQ,CAAC;IACf,MAAM,EAAE,kBAAkB,GAAG,SAAS,CAAC;CACxC;AAED,MAAM,WAAW,UAAU;IACzB,mFAAmF;IACnF,WAAW,EAAE,QAAQ,CAAC;IACtB,KAAK,EAAE,SAAS,kBAAkB,EAAE,CAAC;CACtC;AAID,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,CAAC,UAAU,CAAC,GAAG,UAAU,CAGtE;AAED,wBAAgB,UAAU,IAAI,UAAU,CAEvC;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,eAAe,EACxB,SAAS,GAAE,OAAO,CAAC,UAAU,CAAM,GAClC,kBAAkB,CAQpB;AAED,iDAAiD;AACjD,wBAAgB,cAAc,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,QAAQ,GAAG,QAAQ,CAGjE;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,GAAG,GAAG,QAAQ,CAE7C;AAED,kFAAkF;AAClF,wBAAgB,eAAe,IAAI,QAAQ,CAG1C"}

package/src/context.js

@@ -0,0 +1,61 @@
+/**
+ * Resolve the request timezone once, then read it from the ALS context.
+ * User record → header → config default. Every formatter still takes the zone
+ * explicitly; this is where call sites get the value from, not a hidden default.
+ */
+import { useContext } from '@ultimat3/core';
+import { isValidTimeZone, UTC } from './zones';
+/** Header a client sets from `Intl.DateTimeFormat().resolvedOptions().timeZone`. */
+export const TIMEZONE_HEADER = 'x-timezone';
+const CTX_TIMEZONE = 'timeZone';
+let config = { defaultZone: UTC, order: ['user', 'header', 'query'] };
+export function configureTime(partial) {
+    config = { ...config, ...partial };
+    return config;
+}
+export function timeConfig() {
+    return config;
+}
+/**
+ * First valid IANA name wins. An invalid value is skipped, never thrown: a stale
+ * `x-timezone` header from an old client must not fail the request.
+ */
+export function resolveTimeZone(sources, overrides = {}) {
+    const { defaultZone, order } = { ...config, ...overrides };
+    for (const name of order) {
+        const candidate = sources[name];
+        if (candidate === undefined || candidate === null || candidate === '')
+            continue;
+        if (isValidTimeZone(candidate))
+            return { zone: candidate, source: name };
+    }
+    return { zone: defaultZone, source: 'default' };
+}
+/** Called once per request by the HTTP layer. */
+export function attachTimeZone(ctx, zone) {
+    ctx[CTX_TIMEZONE] = zone;
+    return zone;
+}
+export function timeZoneOf(ctx) {
+    return readField(ctx, CTX_TIMEZONE) ?? config.defaultZone;
+}
+/** Ambient zone for the in-flight request; the configured default outside one. */
+export function currentTimeZone() {
+    const ctx = tryContext();
+    return (ctx === undefined ? undefined : readField(ctx, CTX_TIMEZONE)) ?? config.defaultZone;
+}
+function tryContext() {
+    try {
+        return useContext();
+    }
+    catch {
+        // Outside a request scope (boot, worker tick, CLI) — fall back to the configured zone.
+        return undefined;
+    }
+}
+/** `Ctx` belongs to core (tier 0) and cannot import `TimeZone`; read the field structurally. */
+function readField(ctx, field) {
+    const value = ctx[field];
+    return typeof value === 'string' && value !== '' ? value : undefined;
+}
+//# sourceMappingURL=context.js.map

package/src/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["context.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAY,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACtD,OAAO,EAAE,eAAe,EAAiB,GAAG,EAAE,MAAM,SAAS,CAAC;AAE9D,oFAAoF;AACpF,MAAM,CAAC,MAAM,eAAe,GAAG,YAAY,CAAC;AAE5C,MAAM,YAAY,GAAG,UAAU,CAAC;AAwBhC,IAAI,MAAM,GAAe,EAAE,WAAW,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,MAAM,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE,CAAC;AAElF,MAAM,UAAU,aAAa,CAAC,OAA4B;IACxD,MAAM,GAAG,EAAE,GAAG,MAAM,EAAE,GAAG,OAAO,EAAE,CAAC;IACnC,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,UAAU;IACxB,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAC7B,OAAwB,EACxB,SAAS,GAAwB,EAAE;IAEnC,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,MAAM,EAAE,GAAG,SAAS,EAAE,CAAC;IAC3D,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QAChC,IAAI,SAAS,KAAK,SAAS,IAAI,SAAS,KAAK,IAAI,IAAI,SAAS,KAAK,EAAE;YAAE,SAAS;QAChF,IAAI,eAAe,CAAC,SAAS,CAAC;YAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;IAC3E,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;AAClD,CAAC;AAED,iDAAiD;AACjD,MAAM,UAAU,cAAc,CAAC,GAAQ,EAAE,IAAc;IACpD,GAA0C,CAAC,YAAY,CAAC,GAAG,IAAI,CAAC;IACjE,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,GAAQ;IACjC,OAAO,SAAS,CAAC,GAAG,EAAE,YAAY,CAAC,IAAI,MAAM,CAAC,WAAW,CAAC;AAC5D,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,eAAe;IAC7B,MAAM,GAAG,GAAG,UAAU,EAAE,CAAC;IACzB,OAAO,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,EAAE,YAAY,CAAC,CAAC,IAAI,MAAM,CAAC,WAAW,CAAC;AAC9F,CAAC;AAED,SAAS,UAAU;IACjB,IAAI,CAAC;QACH,OAAO,UAAU,EAAE,CAAC;IACtB,CAAC;IAAC,MAAM,CAAC;QACP,uFAAuF;QACvF,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED,gGAAgG;AAChG,SAAS,SAAS,CAAC,GAAQ,EAAE,KAAa;IACxC,MAAM,KAAK,GAAI,GAA0C,CAAC,KAAK,CAAC,CAAC;IACjE,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AACvE,CAAC"}

package/src/context.ts

@@ -0,0 +1,94 @@
+/**
+ * Resolve the request timezone once, then read it from the ALS context.
+ * User record → header → config default. Every formatter still takes the zone
+ * explicitly; this is where call sites get the value from, not a hidden default.
+ */
+
+import { type Ctx, useContext } from '@ultimat3/core';
+import { isValidTimeZone, type TimeZone, UTC } from './zones';
+
+/** Header a client sets from `Intl.DateTimeFormat().resolvedOptions().timeZone`. */
+export const TIMEZONE_HEADER = 'x-timezone';
+
+const CTX_TIMEZONE = 'timeZone';
+
+export interface TimeZoneSources {
+  /** `user.timeZone` — an explicit preference beats a browser guess. */
+  user?: string | null;
+  /** `x-timezone` request header. */
+  header?: string | null;
+  /** `?tz=Europe/Berlin`, for share links and email previews. */
+  query?: string | null;
+}
+
+export type TimeZoneSourceName = keyof TimeZoneSources;
+
+export interface TimeZoneResolution {
+  zone: TimeZone;
+  source: TimeZoneSourceName | 'default';
+}
+
+export interface TimeConfig {
+  /** The zone used when nothing else resolves. UTC unless the app says otherwise. */
+  defaultZone: TimeZone;
+  order: readonly TimeZoneSourceName[];
+}
+
+let config: TimeConfig = { defaultZone: UTC, order: ['user', 'header', 'query'] };
+
+export function configureTime(partial: Partial<TimeConfig>): TimeConfig {
+  config = { ...config, ...partial };
+  return config;
+}
+
+export function timeConfig(): TimeConfig {
+  return config;
+}
+
+/**
+ * First valid IANA name wins. An invalid value is skipped, never thrown: a stale
+ * `x-timezone` header from an old client must not fail the request.
+ */
+export function resolveTimeZone(
+  sources: TimeZoneSources,
+  overrides: Partial<TimeConfig> = {},
+): TimeZoneResolution {
+  const { defaultZone, order } = { ...config, ...overrides };
+  for (const name of order) {
+    const candidate = sources[name];
+    if (candidate === undefined || candidate === null || candidate === '') continue;
+    if (isValidTimeZone(candidate)) return { zone: candidate, source: name };
+  }
+  return { zone: defaultZone, source: 'default' };
+}
+
+/** Called once per request by the HTTP layer. */
+export function attachTimeZone(ctx: Ctx, zone: TimeZone): TimeZone {
+  (ctx as unknown as Record<string, unknown>)[CTX_TIMEZONE] = zone;
+  return zone;
+}
+
+export function timeZoneOf(ctx: Ctx): TimeZone {
+  return readField(ctx, CTX_TIMEZONE) ?? config.defaultZone;
+}
+
+/** Ambient zone for the in-flight request; the configured default outside one. */
+export function currentTimeZone(): TimeZone {
+  const ctx = tryContext();
+  return (ctx === undefined ? undefined : readField(ctx, CTX_TIMEZONE)) ?? config.defaultZone;
+}
+
+function tryContext(): Ctx | undefined {
+  try {
+    return useContext();
+  } catch {
+    // Outside a request scope (boot, worker tick, CLI) — fall back to the configured zone.
+    return undefined;
+  }
+}
+
+/** `Ctx` belongs to core (tier 0) and cannot import `TimeZone`; read the field structurally. */
+function readField(ctx: Ctx, field: string): string | undefined {
+  const value = (ctx as unknown as Record<string, unknown>)[field];
+  return typeof value === 'string' && value !== '' ? value : undefined;
+}