@ultimat3/time 1.0.0

package/src/duration.ts

@@ -0,0 +1,156 @@
+/**
+ * Durations as milliseconds, parsed from a human string.
+ * `step.sleep('3d')` in @ultimat3/jobs and every `retry.backoff` value comes through here.
+ */
+
+import { durationInvalid } from './errors';
+
+export const MS = 1;
+export const SECOND = 1000;
+export const MINUTE = 60 * SECOND;
+export const HOUR = 60 * MINUTE;
+export const DAY = 24 * HOUR;
+export const WEEK = 7 * DAY;
+
+/** Accepted suffixes. `m` is minutes and `ms` is milliseconds — never months. */
+const UNITS: Readonly<Record<string, number>> = {
+  ms: MS,
+  s: SECOND,
+  sec: SECOND,
+  m: MINUTE,
+  min: MINUTE,
+  h: HOUR,
+  hr: HOUR,
+  d: DAY,
+  w: WEEK,
+};
+
+const COMPONENT = /(\d+(?:\.\d+)?)\s*(ms|sec|min|hr|[smhdw])\s*/iy;
+const ISO_8601 = /^P(?:(\d+)W)?(?:(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:(\d+(?:\.\d+)?)S)?)?$/i;
+
+/**
+ * `'90s'` → 90000 · `'2h30m'` → 9000000 · `'3d'` → 259200000 · `'PT2H30M'` → 9000000.
+ * A bare number is rejected: `sleep(3)` is ambiguous, `sleep('3s')` is not.
+ */
+export function parseDuration(input: string): number {
+  const value = input.trim();
+  if (value === '') throw durationInvalid(input);
+
+  const negative = value.startsWith('-');
+  const body = negative ? value.slice(1) : value;
+
+  if (/^p/i.test(body)) return (negative ? -1 : 1) * parseIso8601Duration(body, input);
+
+  COMPONENT.lastIndex = 0;
+  let total = 0;
+  let matched = 0;
+  let match = COMPONENT.exec(body);
+  while (match !== null) {
+    const amount = Number.parseFloat(match[1] ?? '');
+    const unit = (match[2] ?? '').toLowerCase();
+    const scale = UNITS[unit];
+    if (!Number.isFinite(amount) || scale === undefined) throw durationInvalid(input);
+    total += amount * scale;
+    matched = COMPONENT.lastIndex;
+    match = COMPONENT.exec(body);
+  }
+  // Sticky matching starts at 0, so anything short of the end is trailing junk, and a
+  // zero-length match means there was no unit at all (`'3'` must not mean 3 of anything).
+  if (matched === 0 || matched !== body.length) throw durationInvalid(input);
+  return (negative ? -1 : 1) * Math.round(total);
+}
+
+/** Parse-or-passthrough for APIs that accept either form. */
+export function toMs(duration: string | number): number {
+  return typeof duration === 'number' ? duration : parseDuration(duration);
+}
+
+export function toSeconds(duration: string | number): number {
+  return Math.round(toMs(duration) / SECOND);
+}
+
+export interface FormatDurationOptions {
+  /** Largest unit count to show: `2h 30m` with 2, `2h` with 1. */
+  maxUnits?: number;
+  style?: 'long' | 'short' | 'narrow';
+}
+
+const FORMAT_UNITS: readonly [string, number][] = [
+  ['day', DAY],
+  ['hour', HOUR],
+  ['minute', MINUTE],
+  ['second', SECOND],
+  ['millisecond', MS],
+];
+
+/**
+ * `formatDuration(9_000_000, 'de-DE')` → `2 Std., 30 Min.`
+ * Built from `Intl.NumberFormat` unit style + `Intl.ListFormat`, so unit names and the
+ * list separator are both localized. `Intl.DurationFormat` is not yet everywhere.
+ */
+export function formatDuration(
+  ms: number,
+  locale: string,
+  options: FormatDurationOptions = {},
+): string {
+  const style = options.style ?? 'short';
+  const maxUnits = options.maxUnits ?? 2;
+  let remaining = Math.abs(Math.round(ms));
+  const pieces: string[] = [];
+
+  for (const [unit, scale] of FORMAT_UNITS) {
+    if (pieces.length >= maxUnits) break;
+    const count = Math.floor(remaining / scale);
+    if (count === 0) continue;
+    remaining -= count * scale;
+    pieces.push(
+      new Intl.NumberFormat(locale, { style: 'unit', unit, unitDisplay: style }).format(count),
+    );
+  }
+
+  if (pieces.length === 0) {
+    return new Intl.NumberFormat(locale, {
+      style: 'unit',
+      unit: 'second',
+      unitDisplay: style,
+    }).format(0);
+  }
+
+  const joined = new Intl.ListFormat(locale, { style: 'narrow', type: 'unit' }).format(pieces);
+  return ms < 0 ? `-${joined}` : joined;
+}
+
+/** `PT2H30M` — for OpenAPI schemas and cron metadata. */
+export function formatDurationIso(ms: number): string {
+  const total = Math.abs(Math.round(ms));
+  const days = Math.floor(total / DAY);
+  const hours = Math.floor((total % DAY) / HOUR);
+  const minutes = Math.floor((total % HOUR) / MINUTE);
+  const seconds = (total % MINUTE) / SECOND;
+  const date = days > 0 ? `${days}D` : '';
+  const time = [
+    hours > 0 ? `${hours}H` : '',
+    minutes > 0 ? `${minutes}M` : '',
+    seconds > 0 ? `${seconds}S` : '',
+  ].join('');
+  const body = `${date}${time === '' ? '' : `T${time}`}`;
+  return `${ms < 0 ? '-' : ''}P${body === '' ? '0D' : body}`;
+}
+
+function parseIso8601Duration(body: string, original: string): number {
+  const match = ISO_8601.exec(body);
+  if (match === null) throw durationInvalid(original);
+  const [, weeks, days, hours, minutes, seconds] = match;
+  const total =
+    number(weeks) * WEEK +
+    number(days) * DAY +
+    number(hours) * HOUR +
+    number(minutes) * MINUTE +
+    number(seconds) * SECOND;
+  if (total === 0 && body.toUpperCase() !== 'P0D') throw durationInvalid(original);
+  return Math.round(total);
+}
+
+function number(value: string | undefined): number {
+  return value === undefined ? 0 : Number.parseFloat(value);
+}

package/src/errors.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The X_* error codes owned by @ultimat3/time.
+ * DST ambiguity is a real state of the world, so it gets a code instead of a guess.
+ */
+import { UltimateError } from '@ultimat3/core';
+export declare const TIME_ERROR_CODES: readonly ['X_TIMEZONE_INVALID', 'X_CRON_INVALID', 'X_DURATION_INVALID', 'X_DST_AMBIGUOUS', 'X_DST_NONEXISTENT', 'X_INSTANT_INVALID', 'X_SCHEDULE_INVALID'];
+export type TimeErrorCode = (typeof TIME_ERROR_CODES)[number];
+export declare class TimeError extends UltimateError {
+    constructor(init: {
+        code: TimeErrorCode;
+        cause: string;
+        fix: string;
+    });
+}
+/**
+ * A wall-clock field outside its range. Separate from `X_DST_*`, which are about times that
+ * are legitimately absent or doubled — this one is a spec the caller got wrong.
+ */
+export declare function scheduleInvalid(field: string, value: unknown, range: string): TimeError;
+export declare function timezoneInvalid(zone: string): TimeError;
+export declare function cronInvalid(expression: string, reason: string): TimeError;
+export declare function durationInvalid(input: string): TimeError;
+export declare function dstAmbiguous(wall: string, zone: string): TimeError;
+export declare function dstNonexistent(wall: string, zone: string): TimeError;
+export declare function instantInvalid(input: string): TimeError;
+//# sourceMappingURL=errors.d.ts.map

package/src/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAE/C,eAAO,MAAM,gBAAgB,YAC3B,oBAAoB,EACpB,gBAAgB,EAChB,oBAAoB,EACpB,iBAAiB,EACjB,mBAAmB,EACnB,mBAAmB,EACnB,oBAAoB,CACZ,CAAC;AAEX,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE9D,qBAAa,SAAU,SAAQ,aAAa;IAC1C,YAAY,IAAI,EAAE;QAAE,IAAI,EAAE,aAAa,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,EAOpE;CACF;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,CAMvF;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAMvD;AAED,wBAAgB,WAAW,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,CAMzE;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAMxD;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,CAMlE;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,CAMpE;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAMvD"}

package/src/errors.js

@@ -0,0 +1,78 @@
+/**
+ * The X_* error codes owned by @ultimat3/time.
+ * DST ambiguity is a real state of the world, so it gets a code instead of a guess.
+ */
+import { UltimateError } from '@ultimat3/core';
+export const TIME_ERROR_CODES = [
+    'X_TIMEZONE_INVALID',
+    'X_CRON_INVALID',
+    'X_DURATION_INVALID',
+    'X_DST_AMBIGUOUS',
+    'X_DST_NONEXISTENT',
+    'X_INSTANT_INVALID',
+    'X_SCHEDULE_INVALID',
+];
+export class TimeError extends UltimateError {
+    constructor(init) {
+        super({
+            code: init.code,
+            cause: init.cause,
+            fix: init.fix,
+            docs: `https://ultimate.dev/errors/${init.code}`,
+        });
+    }
+}
+/**
+ * A wall-clock field outside its range. Separate from `X_DST_*`, which are about times that
+ * are legitimately absent or doubled — this one is a spec the caller got wrong.
+ */
+export function scheduleInvalid(field, value, range) {
+    return new TimeError({
+        code: 'X_SCHEDULE_INVALID',
+        cause: `${field} must be ${range}, got ${String(value)}`,
+        fix: `pass an integer in ${range} for ${field} — wall-clock fields are not wrapped or clamped, because a silently shifted schedule is worse than a failed one`,
+    });
+}
+export function timezoneInvalid(zone) {
+    return new TimeError({
+        code: 'X_TIMEZONE_INVALID',
+        cause: `"${zone}" is not an IANA timezone name`,
+        fix: 'use an IANA identifier such as Europe/Berlin, America/New_York or UTC — never an abbreviation like CET or a numeric offset',
+    });
+}
+export function cronInvalid(expression, reason) {
+    return new TimeError({
+        code: 'X_CRON_INVALID',
+        cause: `cron "${expression}": ${reason}`,
+        fix: "use 5 fields (m h dom mon dow) or 6 with seconds, e.g. '0 3 * * *' for 03:00 daily, '*/15 * * * *' every 15 minutes, '0 9 * * MON-FRI' weekday mornings",
+    });
+}
+export function durationInvalid(input) {
+    return new TimeError({
+        code: 'X_DURATION_INVALID',
+        cause: `"${input}" is not a duration`,
+        fix: "use a unit-suffixed duration: '90s', '2h30m', '3d', '1w', '250ms' — or an ISO-8601 form like 'PT2H30M'",
+    });
+}
+export function dstAmbiguous(wall, zone) {
+    return new TimeError({
+        code: 'X_DST_AMBIGUOUS',
+        cause: `${wall} happens twice in ${zone} (the fall-back hour repeats)`,
+        fix: "pass { overlap: 'first' } for the pre-transition instant or { overlap: 'second' } for the post-transition one",
+    });
+}
+export function dstNonexistent(wall, zone) {
+    return new TimeError({
+        code: 'X_DST_NONEXISTENT',
+        cause: `${wall} never happens in ${zone} (the spring-forward gap skips it)`,
+        fix: "pass { gap: 'next' } to shift forward past the gap or { gap: 'previous' } to shift back before it",
+    });
+}
+export function instantInvalid(input) {
+    return new TimeError({
+        code: 'X_INSTANT_INVALID',
+        cause: `"${input}" is not a valid instant`,
+        fix: 'pass an ISO-8601 timestamp with an offset or Z, e.g. 2026-03-14T09:00:00Z',
+    });
+}
+//# sourceMappingURL=errors.js.map

package/src/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAE/C,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,oBAAoB;IACpB,gBAAgB;IAChB,oBAAoB;IACpB,iBAAiB;IACjB,mBAAmB;IACnB,mBAAmB;IACnB,oBAAoB;CACZ,CAAC;AAIX,MAAM,OAAO,SAAU,SAAQ,aAAa;IAC1C,YAAY,IAAyD;QACnE,KAAK,CAAC;YACJ,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,GAAG,EAAE,IAAI,CAAC,GAAG;YACb,IAAI,EAAE,+BAA+B,IAAI,CAAC,IAAI,EAAE;SACjD,CAAC,CAAC;IACL,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,KAAa,EAAE,KAAc,EAAE,KAAa;IAC1E,OAAO,IAAI,SAAS,CAAC;QACnB,IAAI,EAAE,oBAAoB;QAC1B,KAAK,EAAE,GAAG,KAAK,YAAY,KAAK,SAAS,MAAM,CAAC,KAAK,CAAC,EAAE;QACxD,GAAG,EAAE,sBAAsB,KAAK,QAAQ,KAAK,iHAAiH;KAC/J,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,OAAO,IAAI,SAAS,CAAC;QACnB,IAAI,EAAE,oBAAoB;QAC1B,KAAK,EAAE,IAAI,IAAI,gCAAgC;QAC/C,GAAG,EAAE,4HAA4H;KAClI,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,UAAkB,EAAE,MAAc;IAC5D,OAAO,IAAI,SAAS,CAAC;QACnB,IAAI,EAAE,gBAAgB;QACtB,KAAK,EAAE,SAAS,UAAU,MAAM,MAAM,EAAE;QACxC,GAAG,EAAE,yJAAyJ;KAC/J,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,KAAa;IAC3C,OAAO,IAAI,SAAS,CAAC;QACnB,IAAI,EAAE,oBAAoB;QAC1B,KAAK,EAAE,IAAI,KAAK,qBAAqB;QACrC,GAAG,EAAE,wGAAwG;KAC9G,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,IAAY,EAAE,IAAY;IACrD,OAAO,IAAI,SAAS,CAAC;QACnB,IAAI,EAAE,iBAAiB;QACvB,KAAK,EAAE,GAAG,IAAI,qBAAqB,IAAI,+BAA+B;QACtE,GAAG,EAAE,+GAA+G;KACrH,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,IAAY,EAAE,IAAY;IACvD,OAAO,IAAI,SAAS,CAAC;QACnB,IAAI,EAAE,mBAAmB;QACzB,KAAK,EAAE,GAAG,IAAI,qBAAqB,IAAI,oCAAoC;QAC3E,GAAG,EAAE,mGAAmG;KACzG,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,KAAa;IAC1C,OAAO,IAAI,SAAS,CAAC;QACnB,IAAI,EAAE,mBAAmB;QACzB,KAAK,EAAE,IAAI,KAAK,0BAA0B;QAC1C,GAAG,EAAE,2EAA2E;KACjF,CAAC,CAAC;AACL,CAAC"}

package/src/errors.ts

@@ -0,0 +1,121 @@
+/**
+ * The X_* error codes owned by @ultimat3/time.
+ * DST ambiguity is a real state of the world, so it gets a code instead of a guess.
+ */
+
+import { registerErrorCodes, UltimateError } from '@ultimat3/core';
+
+export const TIME_ERROR_CODES = [
+  'X_TIMEZONE_INVALID',
+  'X_CRON_INVALID',
+  'X_DURATION_INVALID',
+  'X_DST_AMBIGUOUS',
+  'X_DST_NONEXISTENT',
+  'X_INSTANT_INVALID',
+  'X_SCHEDULE_INVALID',
+  'X_LOCALE_INVALID',
+] as const;
+
+export type TimeErrorCode = (typeof TIME_ERROR_CODES)[number];
+
+export const TIME_ERROR_TITLES: Readonly<Record<TimeErrorCode, string>> = {
+  X_TIMEZONE_INVALID: 'not an IANA zone',
+  X_CRON_INVALID: 'not a parseable cron expression',
+  X_DURATION_INVALID: 'not a parseable duration',
+  X_DST_AMBIGUOUS: 'the local time occurs twice',
+  X_DST_NONEXISTENT: 'the local time does not exist',
+  X_INSTANT_INVALID: 'not a parseable instant',
+  X_SCHEDULE_INVALID: 'a wall-clock field is out of range',
+  X_LOCALE_INVALID: 'not a well-formed BCP 47 tag',
+};
+
+// Titles must be registered for `format()` to render the contract's first line. Every code above is
+// owned here and none is borrowed, so the call is unconditional: a second package claiming one has
+// to fail as X_ERROR_CODE_DUPLICATE, not quietly keep whichever title was registered first.
+registerErrorCodes(
+  Object.fromEntries(Object.entries(TIME_ERROR_TITLES).map(([code, title]) => [code, { title }])),
+);
+
+export class TimeError extends UltimateError {
+  constructor(init: { code: TimeErrorCode; cause: string; fix: string }) {
+    super({
+      code: init.code,
+      cause: init.cause,
+      fix: init.fix,
+      docs: `https://ultimate.dev/errors/${init.code}`,
+    });
+  }
+}
+
+/**
+ * A wall-clock field outside its range. Separate from `X_DST_*`, which are about times that
+ * are legitimately absent or doubled — this one is a spec the caller got wrong.
+ */
+export function scheduleInvalid(field: string, value: unknown, range: string): TimeError {
+  return new TimeError({
+    code: 'X_SCHEDULE_INVALID',
+    cause: `${field} must be ${range}, got ${String(value)}`,
+    fix: `pass an integer in ${range} for ${field} — wall-clock fields are not wrapped or clamped, because a silently shifted schedule is worse than a failed one`,
+  });
+}
+
+export function timezoneInvalid(zone: string): TimeError {
+  return new TimeError({
+    code: 'X_TIMEZONE_INVALID',
+    cause: `"${zone}" is not an IANA timezone name`,
+    fix: 'use an IANA identifier such as Europe/Berlin, America/New_York or UTC — never an abbreviation like CET or a numeric offset',
+  });
+}
+
+export function cronInvalid(expression: string, reason: string): TimeError {
+  return new TimeError({
+    code: 'X_CRON_INVALID',
+    cause: `cron "${expression}": ${reason}`,
+    fix: "use 5 fields (m h dom mon dow) or 6 with seconds, e.g. '0 3 * * *' for 03:00 daily, '*/15 * * * *' every 15 minutes, '0 9 * * MON-FRI' weekday mornings",
+  });
+}
+
+export function durationInvalid(input: string): TimeError {
+  return new TimeError({
+    code: 'X_DURATION_INVALID',
+    cause: `"${input}" is not a duration`,
+    fix: "use a unit-suffixed duration: '90s', '2h30m', '3d', '1w', '250ms' — or an ISO-8601 form like 'PT2H30M'",
+  });
+}
+
+export function dstAmbiguous(wall: string, zone: string): TimeError {
+  return new TimeError({
+    code: 'X_DST_AMBIGUOUS',
+    cause: `${wall} happens twice in ${zone} (the fall-back hour repeats)`,
+    fix: "pass { overlap: 'first' } for the pre-transition instant or { overlap: 'second' } for the post-transition one",
+  });
+}
+
+export function dstNonexistent(wall: string, zone: string): TimeError {
+  return new TimeError({
+    code: 'X_DST_NONEXISTENT',
+    cause: `${wall} never happens in ${zone} (the spring-forward gap skips it)`,
+    fix: "pass { gap: 'next' } to shift forward past the gap or { gap: 'previous' } to shift back before it",
+  });
+}
+
+/**
+ * A tag `Intl` cannot parse. Distinct from i18n's `X_LOCALE_UNSUPPORTED`, which is a
+ * well-formed tag outside the app's supported set — this one is not a tag at all, and a raw
+ * `RangeError` from a formatter says nothing about which caller supplied it.
+ */
+export function localeInvalid(locale: string): TimeError {
+  return new TimeError({
+    code: 'X_LOCALE_INVALID',
+    cause: `"${locale}" is not a well-formed BCP 47 language tag`,
+    fix: "pass a tag like 'en', 'en-GB' or 'de-DE' — screen a header-supplied value with Intl.DateTimeFormat.supportedLocalesOf([tag]) before it reaches a formatter",
+  });
+}
+
+export function instantInvalid(input: string): TimeError {
+  return new TimeError({
+    code: 'X_INSTANT_INVALID',
+    cause: `"${input}" is not a valid instant`,
+    fix: 'pass an ISO-8601 timestamp with an offset or Z, e.g. 2026-03-14T09:00:00Z',
+  });
+}

package/src/format.d.ts

@@ -0,0 +1,54 @@
+/**
+ * `Intl.DateTimeFormat` at the edge. Every function takes an explicit `zone` and
+ * `locale` — there is no ambient default and no `toLocaleString()` without options,
+ * because "the server's timezone" is never the answer to "what time is it for the user".
+ */
+import { type Instant } from './instant';
+import { type TimeZone } from './zones';
+export type DateTimeStyle = 'short' | 'medium' | 'long' | 'full';
+export interface FormatContext {
+    locale: string;
+    /** IANA zone. Required, always. */
+    zone: TimeZone;
+}
+export interface FormatDateTimeOptions extends FormatContext {
+    /** Sets both date and time style; `dateStyle`/`timeStyle` override it. */
+    style?: DateTimeStyle;
+    dateStyle?: DateTimeStyle;
+    timeStyle?: DateTimeStyle;
+    hour12?: boolean;
+}
+/** `14 Mar 2026, 09:00` in `en-GB` / `Europe/Berlin`. */
+export declare function formatDateTime(at: Instant, options: FormatDateTimeOptions): string;
+export declare function formatDate(at: Instant, options: FormatContext & {
+    style?: DateTimeStyle;
+}): string;
+export declare function formatTime(at: Instant, options: FormatContext & {
+    style?: DateTimeStyle;
+    hour12?: boolean;
+}): string;
+/**
+ * `14 Mar 2026, 09:00 (GMT+1)` — the offset made visible.
+ * Built with `timeZoneName: 'shortOffset'` + `formatToParts` so the offset is appended
+ * in a fixed position instead of wherever the locale pattern happens to put it.
+ */
+export declare function formatWithOffset(at: Instant, options: FormatDateTimeOptions): string;
+/** ISO-8601 date parts in a zone, for `<input type="date">` and CSV columns. */
+export declare function formatIsoDate(at: Instant, zone: TimeZone): string;
+export interface FormatRelativeOptions extends Omit<FormatContext, 'zone'> {
+    /** The reference point. Pass `now(clock)` — never let this default to a live clock. */
+    now: Instant;
+    numeric?: 'always' | 'auto';
+    style?: 'long' | 'short' | 'narrow';
+}
+/** `in 3 days` / `2 hours ago`, picking the largest unit that fits. */
+export declare function formatRelative(at: Instant, options: FormatRelativeOptions): string;
+/** `14–16 Mar 2026` — one call, so the locale decides how to collapse the range. */
+export declare function formatRange(from: Instant, to: Instant, options: FormatDateTimeOptions): string;
+/**
+ * `Intl` renders `November 5, 2011`, never `5th of November`. When a design asks for the
+ * ordinal, build it from `Intl.PluralRules` with `type: 'ordinal'` — English-only by
+ * nature, which is why it is a helper and not the default date format.
+ */
+export declare function ordinal(value: number, locale?: string): string;
+//# sourceMappingURL=format.d.ts.map

package/src/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["format.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAgB,KAAK,OAAO,EAAE,MAAM,WAAW,CAAC;AACvD,OAAO,EAAkB,KAAK,QAAQ,EAAE,MAAM,SAAS,CAAC;AAExD,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAC;AAEjE,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,mCAAmC;IACnC,IAAI,EAAE,QAAQ,CAAC;CAChB;AAED,MAAM,WAAW,qBAAsB,SAAQ,aAAa;IAC1D,0EAA0E;IAC1E,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,yDAAyD;AACzD,wBAAgB,cAAc,CAAC,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,qBAAqB,GAAG,MAAM,CAQlF;AAED,wBAAgB,UAAU,CACxB,EAAE,EAAE,OAAO,EACX,OAAO,EAAE,aAAa,GAAG;IAAE,KAAK,CAAC,EAAE,aAAa,CAAA;CAAE,GACjD,MAAM,CAKR;AAED,wBAAgB,UAAU,CACxB,EAAE,EAAE,OAAO,EACX,OAAO,EAAE,aAAa,GAAG;IAAE,KAAK,CAAC,EAAE,aAAa,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,GACnE,MAAM,CAMR;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,qBAAqB,GAAG,MAAM,CAuBpF;AAED,gFAAgF;AAChF,wBAAgB,aAAa,CAAC,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,GAAG,MAAM,CAQjE;AAED,MAAM,WAAW,qBAAsB,SAAQ,IAAI,CAAC,aAAa,EAAE,MAAM,CAAC;IACxE,uFAAuF;IACvF,GAAG,EAAE,OAAO,CAAC;IACb,OAAO,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC;IAC5B,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;CACrC;AAYD,uEAAuE;AACvE,wBAAgB,cAAc,CAAC,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,qBAAqB,GAAG,MAAM,CAalF;AAED,oFAAoF;AACpF,wBAAgB,WAAW,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,qBAAqB,GAAG,MAAM,CAY9F;AAWD;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,SAAO,GAAG,MAAM,CAG5D"}

package/src/format.js

@@ -0,0 +1,133 @@
+/**
+ * `Intl.DateTimeFormat` at the edge. Every function takes an explicit `zone` and
+ * `locale` — there is no ambient default and no `toLocaleString()` without options,
+ * because "the server's timezone" is never the answer to "what time is it for the user".
+ */
+import { differenceMs } from './instant';
+import { assertTimeZone } from './zones';
+/** `14 Mar 2026, 09:00` in `en-GB` / `Europe/Berlin`. */
+export function formatDateTime(at, options) {
+    const style = options.style ?? 'medium';
+    return formatterFor(options.locale, {
+        timeZone: assertTimeZone(options.zone),
+        dateStyle: options.dateStyle ?? style,
+        timeStyle: options.timeStyle ?? (style === 'full' || style === 'long' ? 'medium' : style),
+        ...(options.hour12 === undefined ? {} : { hour12: options.hour12 }),
+    }).format(at);
+}
+export function formatDate(at, options) {
+    return formatterFor(options.locale, {
+        timeZone: assertTimeZone(options.zone),
+        dateStyle: options.style ?? 'medium',
+    }).format(at);
+}
+export function formatTime(at, options) {
+    return formatterFor(options.locale, {
+        timeZone: assertTimeZone(options.zone),
+        timeStyle: options.style ?? 'short',
+        ...(options.hour12 === undefined ? {} : { hour12: options.hour12 }),
+    }).format(at);
+}
+/**
+ * `14 Mar 2026, 09:00 (GMT+1)` — the offset made visible.
+ * Built with `timeZoneName: 'shortOffset'` + `formatToParts` so the offset is appended
+ * in a fixed position instead of wherever the locale pattern happens to put it.
+ */
+export function formatWithOffset(at, options) {
+    const style = options.style ?? 'medium';
+    // `timeZoneName` is a component option, and Intl forbids mixing those with dateStyle /
+    // timeStyle — so the components are spelled out here instead.
+    const parts = formatterFor(options.locale, {
+        timeZone: assertTimeZone(options.zone),
+        year: 'numeric',
+        month: style === 'short' ? 'numeric' : style === 'medium' ? 'short' : 'long',
+        day: 'numeric',
+        hour: '2-digit',
+        minute: '2-digit',
+        ...(options.hour12 === undefined ? { hourCycle: 'h23' } : { hour12: options.hour12 }),
+        timeZoneName: 'shortOffset',
+    }).formatToParts(at);
+    const offset = parts.find((part) => part.type === 'timeZoneName')?.value ?? '';
+    const text = parts
+        .filter((part) => part.type !== 'timeZoneName')
+        .map((part) => part.value)
+        .join('')
+        .replace(/[\s,]+$/u, '')
+        .trim();
+    return offset === '' ? text : `${text} (${offset})`;
+}
+/** ISO-8601 date parts in a zone, for `<input type="date">` and CSV columns. */
+export function formatIsoDate(at, zone) {
+    const parts = formatterFor('en-CA', {
+        timeZone: assertTimeZone(zone),
+        year: 'numeric',
+        month: '2-digit',
+        day: '2-digit',
+    }).format(at);
+    return parts.replace(/\//g, '-');
+}
+const RELATIVE_UNITS = [
+    ['year', 31_536_000_000],
+    ['month', 2_592_000_000],
+    ['week', 604_800_000],
+    ['day', 86_400_000],
+    ['hour', 3_600_000],
+    ['minute', 60_000],
+    ['second', 1000],
+];
+/** `in 3 days` / `2 hours ago`, picking the largest unit that fits. */
+export function formatRelative(at, options) {
+    const delta = differenceMs(options.now, at);
+    const formatter = new Intl.RelativeTimeFormat(options.locale, {
+        numeric: options.numeric ?? 'auto',
+        style: options.style ?? 'long',
+    });
+    const magnitude = Math.abs(delta);
+    for (const [unit, ms] of RELATIVE_UNITS) {
+        if (magnitude >= ms) {
+            return formatter.format(Math.trunc(delta / ms), unit);
+        }
+    }
+    return formatter.format(0, 'second');
+}
+/** `14–16 Mar 2026` — one call, so the locale decides how to collapse the range. */
+export function formatRange(from, to, options) {
+    const style = options.style ?? 'medium';
+    const formatter = formatterFor(options.locale, {
+        timeZone: assertTimeZone(options.zone),
+        dateStyle: options.dateStyle ?? style,
+        ...(options.timeStyle === undefined ? {} : { timeStyle: options.timeStyle }),
+    });
+    // `formatRange` is ES2021; fall back to two formatted endpoints on older engines.
+    if (typeof formatter.formatRange === 'function')
+        return formatter.formatRange(from, to);
+    return `${formatter.format(from)} – ${formatter.format(to)}`;
+}
+const ORDINAL_SUFFIX = {
+    one: 'st',
+    two: 'nd',
+    few: 'rd',
+    other: 'th',
+    zero: 'th',
+    many: 'th',
+};
+/**
+ * `Intl` renders `November 5, 2011`, never `5th of November`. When a design asks for the
+ * ordinal, build it from `Intl.PluralRules` with `type: 'ordinal'` — English-only by
+ * nature, which is why it is a helper and not the default date format.
+ */
+export function ordinal(value, locale = 'en') {
+    const category = new Intl.PluralRules(locale, { type: 'ordinal' }).select(value);
+    return `${value}${ORDINAL_SUFFIX[category]}`;
+}
+const cache = new Map();
+function formatterFor(locale, options) {
+    const key = `${locale}|${JSON.stringify(options)}`;
+    const cached = cache.get(key);
+    if (cached !== undefined)
+        return cached;
+    const formatter = new Intl.DateTimeFormat(locale, options);
+    cache.set(key, formatter);
+    return formatter;
+}
+//# sourceMappingURL=format.js.map

package/src/format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.js","sourceRoot":"","sources":["format.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,YAAY,EAAgB,MAAM,WAAW,CAAC;AACvD,OAAO,EAAE,cAAc,EAAiB,MAAM,SAAS,CAAC;AAkBxD,yDAAyD;AACzD,MAAM,UAAU,cAAc,CAAC,EAAW,EAAE,OAA8B;IACxE,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,QAAQ,CAAC;IACxC,OAAO,YAAY,CAAC,OAAO,CAAC,MAAM,EAAE;QAClC,QAAQ,EAAE,cAAc,CAAC,OAAO,CAAC,IAAI,CAAC;QACtC,SAAS,EAAE,OAAO,CAAC,SAAS,IAAI,KAAK;QACrC,SAAS,EAAE,OAAO,CAAC,SAAS,IAAI,CAAC,KAAK,KAAK,MAAM,IAAI,KAAK,KAAK,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC;QACzF,GAAG,CAAC,OAAO,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC;KACpE,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,UAAU,CACxB,EAAW,EACX,OAAkD;IAElD,OAAO,YAAY,CAAC,OAAO,CAAC,MAAM,EAAE;QAClC,QAAQ,EAAE,cAAc,CAAC,OAAO,CAAC,IAAI,CAAC;QACtC,SAAS,EAAE,OAAO,CAAC,KAAK,IAAI,QAAQ;KACrC,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,UAAU,CACxB,EAAW,EACX,OAAoE;IAEpE,OAAO,YAAY,CAAC,OAAO,CAAC,MAAM,EAAE;QAClC,QAAQ,EAAE,cAAc,CAAC,OAAO,CAAC,IAAI,CAAC;QACtC,SAAS,EAAE,OAAO,CAAC,KAAK,IAAI,OAAO;QACnC,GAAG,CAAC,OAAO,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC;KACpE,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;AAChB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,EAAW,EAAE,OAA8B;IAC1E,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,QAAQ,CAAC;IACxC,uFAAuF;IACvF,8DAA8D;IAC9D,MAAM,KAAK,GAAG,YAAY,CAAC,OAAO,CAAC,MAAM,EAAE;QACzC,QAAQ,EAAE,cAAc,CAAC,OAAO,CAAC,IAAI,CAAC;QACtC,IAAI,EAAE,SAAS;QACf,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM;QAC5E,GAAG,EAAE,SAAS;QACd,IAAI,EAAE,SAAS;QACf,MAAM,EAAE,SAAS;QACjB,GAAG,CAAC,OAAO,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,KAAc,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC;QAC9F,YAAY,EAAE,aAAa;KAC5B,CAAC,CAAC,aAAa,CAAC,EAAE,CAAC,CAAC;IAErB,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,KAAK,cAAc,CAAC,EAAE,KAAK,IAAI,EAAE,CAAC;IAC/E,MAAM,IAAI,GAAG,KAAK;SACf,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,KAAK,cAAc,CAAC;SAC9C,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC;SACzB,IAAI,CAAC,EAAE,CAAC;SACR,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC;SACvB,IAAI,EAAE,CAAC;IACV,OAAO,MAAM,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,KAAK,MAAM,GAAG,CAAC;AACtD,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,aAAa,CAAC,EAAW,EAAE,IAAc;IACvD,MAAM,KAAK,GAAG,YAAY,CAAC,OAAO,EAAE;QAClC,QAAQ,EAAE,cAAc,CAAC,IAAI,CAAC;QAC9B,IAAI,EAAE,SAAS;QACf,KAAK,EAAE,SAAS;QAChB,GAAG,EAAE,SAAS;KACf,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACd,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;AACnC,CAAC;AASD,MAAM,cAAc,GAAqD;IACvE,CAAC,MAAM,EAAE,cAAc,CAAC;IACxB,CAAC,OAAO,EAAE,aAAa,CAAC;IACxB,CAAC,MAAM,EAAE,WAAW,CAAC;IACrB,CAAC,KAAK,EAAE,UAAU,CAAC;IACnB,CAAC,MAAM,EAAE,SAAS,CAAC;IACnB,CAAC,QAAQ,EAAE,MAAM,CAAC;IAClB,CAAC,QAAQ,EAAE,IAAI,CAAC;CACjB,CAAC;AAEF,uEAAuE;AACvE,MAAM,UAAU,cAAc,CAAC,EAAW,EAAE,OAA8B;IACxE,MAAM,KAAK,GAAG,YAAY,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;IAC5C,MAAM,SAAS,GAAG,IAAI,IAAI,CAAC,kBAAkB,CAAC,OAAO,CAAC,MAAM,EAAE;QAC5D,OAAO,EAAE,OAAO,CAAC,OAAO,IAAI,MAAM;QAClC,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,MAAM;KAC/B,CAAC,CAAC;IACH,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IAClC,KAAK,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,cAAc,EAAE,CAAC;QACxC,IAAI,SAAS,IAAI,EAAE,EAAE,CAAC;YACpB,OAAO,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC;QACxD,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;AACvC,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,WAAW,CAAC,IAAa,EAAE,EAAW,EAAE,OAA8B;IACpF,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,QAAQ,CAAC;IACxC,MAAM,SAAS,GAAG,YAAY,CAAC,OAAO,CAAC,MAAM,EAAE;QAC7C,QAAQ,EAAE,cAAc,CAAC,OAAO,CAAC,IAAI,CAAC;QACtC,SAAS,EAAE,OAAO,CAAC,SAAS,IAAI,KAAK;QACrC,GAAG,CAAC,OAAO,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,CAAC;KAC7E,CAEA,CAAC;IACF,kFAAkF;IAClF,IAAI,OAAO,SAAS,CAAC,WAAW,KAAK,UAAU;QAAE,OAAO,SAAS,CAAC,WAAW,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;IACxF,OAAO,GAAG,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC;AAC/D,CAAC;AAED,MAAM,cAAc,GAAwC;IAC1D,GAAG,EAAE,IAAI;IACT,GAAG,EAAE,IAAI;IACT,GAAG,EAAE,IAAI;IACT,KAAK,EAAE,IAAI;IACX,IAAI,EAAE,IAAI;IACV,IAAI,EAAE,IAAI;CACX,CAAC;AAEF;;;;GAIG;AACH,MAAM,UAAU,OAAO,CAAC,KAAa,EAAE,MAAM,GAAG,IAAI;IAClD,MAAM,QAAQ,GAAG,IAAI,IAAI,CAAC,WAAW,CAAC,MAAM,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACjF,OAAO,GAAG,KAAK,GAAG,cAAc,CAAC,QAAQ,CAAC,EAAE,CAAC;AAC/C,CAAC;AAED,MAAM,KAAK,GAAG,IAAI,GAAG,EAA+B,CAAC;AAErD,SAAS,YAAY,CAAC,MAAc,EAAE,OAAmC;IACvE,MAAM,GAAG,GAAG,GAAG,MAAM,IAAI,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC;IACnD,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC9B,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC;IACxC,MAAM,SAAS,GAAG,IAAI,IAAI,CAAC,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC3D,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;IAC1B,OAAO,SAAS,CAAC;AACnB,CAAC"}