@ultimat3/time 1.0.0

package/src/format.ts

@@ -0,0 +1,175 @@
+/**
+ * `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, type Instant } from './instant';
+import { assertTimeZone, 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 function formatDateTime(at: Instant, options: FormatDateTimeOptions): string {
+  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: Instant,
+  options: FormatContext & { style?: DateTimeStyle },
+): string {
+  return formatterFor(options.locale, {
+    timeZone: assertTimeZone(options.zone),
+    dateStyle: options.style ?? 'medium',
+  }).format(at);
+}
+
+export function formatTime(
+  at: Instant,
+  options: FormatContext & { style?: DateTimeStyle; hour12?: boolean },
+): string {
+  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: Instant, options: FormatDateTimeOptions): string {
+  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' as const } : { 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: Instant, zone: TimeZone): string {
+  const parts = formatterFor('en-CA', {
+    timeZone: assertTimeZone(zone),
+    year: 'numeric',
+    month: '2-digit',
+    day: '2-digit',
+  }).format(at);
+  return parts.replace(/\//g, '-');
+}
+
+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';
+}
+
+const RELATIVE_UNITS: readonly [Intl.RelativeTimeFormatUnit, number][] = [
+  ['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: Instant, options: FormatRelativeOptions): string {
+  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: Instant, to: Instant, options: FormatDateTimeOptions): string {
+  const style = options.style ?? 'medium';
+  const formatter = formatterFor(options.locale, {
+    timeZone: assertTimeZone(options.zone),
+    dateStyle: options.dateStyle ?? style,
+    ...(options.timeStyle === undefined ? {} : { timeStyle: options.timeStyle }),
+  }) as Intl.DateTimeFormat & {
+    formatRange?: (start: Date, end: Date) => string;
+  };
+  // `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: Record<Intl.LDMLPluralRule, string> = {
+  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: number, locale = 'en'): string {
+  const category = new Intl.PluralRules(locale, { type: 'ordinal' }).select(value);
+  return `${value}${ORDINAL_SUFFIX[category]}`;
+}
+
+const cache = new Map<string, Intl.DateTimeFormat>();
+
+function formatterFor(locale: string, options: Intl.DateTimeFormatOptions): Intl.DateTimeFormat {
+  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;
+}

package/src/index.d.ts

@@ -0,0 +1,12 @@
+/** Public surface of @ultimat3/time. Explicit exports only. */
+export { addBusinessDays, type BusinessCalendar, businessDaysBetween, type IsoWeekday, isBusinessDay, isHoliday, isWeekend, nextBusinessDay, WEEKEND_FRI_SAT, WEEKEND_SAT_SUN, WEEKEND_SUN_ONLY, } from './business';
+export { attachTimeZone, configureTime, currentTimeZone, resolveTimeZone, TIMEZONE_HEADER, type TimeConfig, type TimeZoneResolution, type TimeZoneSourceName, type TimeZoneSources, timeConfig, timeZoneOf, } from './context';
+export { type CronExpression, type CronPhrases, DEFAULT_CRON_PHRASES, describeCron, firedSince, isValidCron, matchesCron, nextCronOccurrence, nextCronOccurrenceMs, nextCronOccurrences, parseCron, } from './cron';
+export { DAY, type FormatDurationOptions, formatDuration, formatDurationIso, HOUR, MINUTE, MS, parseDuration, SECOND, toMs, toSeconds, WEEK, } from './duration';
+export { cronInvalid, dstAmbiguous, dstNonexistent, durationInvalid, instantInvalid, TIME_ERROR_CODES, TimeError, type TimeErrorCode, timezoneInvalid, } from './errors';
+export { type DateTimeStyle, type FormatContext, type FormatDateTimeOptions, type FormatRelativeOptions, formatDate, formatDateTime, formatIsoDate, formatRange, formatRelative, formatTime, formatWithOffset, ordinal, } from './format';
+export { addMs, compareInstants, differenceMs, EPOCH, fromEpochMs, fromEpochSeconds, fromIso, type Instant, instant, isAfter, isBefore, isInstant, now, subtractMs, toEpochMs, toIso, toIsoDateUtc, } from './instant';
+export { type LocalSlot, nextLocalSlot, nextLocalSlots, nextWeeklySlot, type WeeklySlot, } from './schedule';
+export { addDaysInZone, endOfDay, type FromZonedOptions, type FromZonedResult, fromZoned, fromZonedDetailed, type GapPolicy, isoDateInZone, isSameLocalDay, type OverlapPolicy, startOfDay, toZoned, type WallClock, type ZonedDateTime, type ZonedResolution, } from './zoned';
+export { assertTimeZone, isValidTimeZone, observesDst, offsetAt, offsetLabel, type TimeZone, UTC, type ZoneParts, zoneAbbrev, zonePartsAt, } from './zones';
+//# sourceMappingURL=index.d.ts.map

package/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAE/D,OAAO,EACL,eAAe,EACf,KAAK,gBAAgB,EACrB,mBAAmB,EACnB,KAAK,UAAU,EACf,aAAa,EACb,SAAS,EACT,SAAS,EACT,eAAe,EACf,eAAe,EACf,eAAe,EACf,gBAAgB,GACjB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,cAAc,EACd,aAAa,EACb,eAAe,EACf,eAAe,EACf,eAAe,EACf,KAAK,UAAU,EACf,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACpB,UAAU,EACV,UAAU,GACX,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,oBAAoB,EACpB,YAAY,EACZ,UAAU,EACV,WAAW,EACX,WAAW,EACX,kBAAkB,EAClB,oBAAoB,EACpB,mBAAmB,EACnB,SAAS,GACV,MAAM,QAAQ,CAAC;AAChB,OAAO,EACL,GAAG,EACH,KAAK,qBAAqB,EAC1B,cAAc,EACd,iBAAiB,EACjB,IAAI,EACJ,MAAM,EACN,EAAE,EACF,aAAa,EACb,MAAM,EACN,IAAI,EACJ,SAAS,EACT,IAAI,GACL,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,WAAW,EACX,YAAY,EACZ,cAAc,EACd,eAAe,EACf,cAAc,EACd,gBAAgB,EAChB,SAAS,EACT,KAAK,aAAa,EAClB,eAAe,GAChB,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC1B,UAAU,EACV,cAAc,EACd,aAAa,EACb,WAAW,EACX,cAAc,EACd,UAAU,EACV,gBAAgB,EAChB,OAAO,GACR,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,KAAK,EACL,eAAe,EACf,YAAY,EACZ,KAAK,EACL,WAAW,EACX,gBAAgB,EAChB,OAAO,EACP,KAAK,OAAO,EACZ,OAAO,EACP,OAAO,EACP,QAAQ,EACR,SAAS,EACT,GAAG,EACH,UAAU,EACV,SAAS,EACT,KAAK,EACL,YAAY,GACb,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,KAAK,SAAS,EACd,aAAa,EACb,cAAc,EACd,cAAc,EACd,KAAK,UAAU,GAChB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,aAAa,EACb,QAAQ,EACR,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,SAAS,EACT,iBAAiB,EACjB,KAAK,SAAS,EACd,aAAa,EACb,cAAc,EACd,KAAK,aAAa,EAClB,UAAU,EACV,OAAO,EACP,KAAK,SAAS,EACd,KAAK,aAAa,EAClB,KAAK,eAAe,GACrB,MAAM,SAAS,CAAC;AACjB,OAAO,EACL,cAAc,EACd,eAAe,EACf,WAAW,EACX,QAAQ,EACR,WAAW,EACX,KAAK,QAAQ,EACb,GAAG,EACH,KAAK,SAAS,EACd,UAAU,EACV,WAAW,GACZ,MAAM,SAAS,CAAC"}

package/src/index.js

@@ -0,0 +1,12 @@
+/** Public surface of @ultimat3/time. Explicit exports only. */
+export { addBusinessDays, businessDaysBetween, isBusinessDay, isHoliday, isWeekend, nextBusinessDay, WEEKEND_FRI_SAT, WEEKEND_SAT_SUN, WEEKEND_SUN_ONLY, } from './business';
+export { attachTimeZone, configureTime, currentTimeZone, resolveTimeZone, TIMEZONE_HEADER, timeConfig, timeZoneOf, } from './context';
+export { DEFAULT_CRON_PHRASES, describeCron, firedSince, isValidCron, matchesCron, nextCronOccurrence, nextCronOccurrenceMs, nextCronOccurrences, parseCron, } from './cron';
+export { DAY, formatDuration, formatDurationIso, HOUR, MINUTE, MS, parseDuration, SECOND, toMs, toSeconds, WEEK, } from './duration';
+export { cronInvalid, dstAmbiguous, dstNonexistent, durationInvalid, instantInvalid, TIME_ERROR_CODES, TimeError, timezoneInvalid, } from './errors';
+export { formatDate, formatDateTime, formatIsoDate, formatRange, formatRelative, formatTime, formatWithOffset, ordinal, } from './format';
+export { addMs, compareInstants, differenceMs, EPOCH, fromEpochMs, fromEpochSeconds, fromIso, instant, isAfter, isBefore, isInstant, now, subtractMs, toEpochMs, toIso, toIsoDateUtc, } from './instant';
+export { nextLocalSlot, nextLocalSlots, nextWeeklySlot, } from './schedule';
+export { addDaysInZone, endOfDay, fromZoned, fromZonedDetailed, isoDateInZone, isSameLocalDay, startOfDay, toZoned, } from './zoned';
+export { assertTimeZone, isValidTimeZone, observesDst, offsetAt, offsetLabel, UTC, zoneAbbrev, zonePartsAt, } from './zones';
+//# sourceMappingURL=index.js.map

package/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAE/D,OAAO,EACL,eAAe,EAEf,mBAAmB,EAEnB,aAAa,EACb,SAAS,EACT,SAAS,EACT,eAAe,EACf,eAAe,EACf,eAAe,EACf,gBAAgB,GACjB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,cAAc,EACd,aAAa,EACb,eAAe,EACf,eAAe,EACf,eAAe,EAKf,UAAU,EACV,UAAU,GACX,MAAM,WAAW,CAAC;AACnB,OAAO,EAGL,oBAAoB,EACpB,YAAY,EACZ,UAAU,EACV,WAAW,EACX,WAAW,EACX,kBAAkB,EAClB,oBAAoB,EACpB,mBAAmB,EACnB,SAAS,GACV,MAAM,QAAQ,CAAC;AAChB,OAAO,EACL,GAAG,EAEH,cAAc,EACd,iBAAiB,EACjB,IAAI,EACJ,MAAM,EACN,EAAE,EACF,aAAa,EACb,MAAM,EACN,IAAI,EACJ,SAAS,EACT,IAAI,GACL,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,WAAW,EACX,YAAY,EACZ,cAAc,EACd,eAAe,EACf,cAAc,EACd,gBAAgB,EAChB,SAAS,EAET,eAAe,GAChB,MAAM,UAAU,CAAC;AAClB,OAAO,EAKL,UAAU,EACV,cAAc,EACd,aAAa,EACb,WAAW,EACX,cAAc,EACd,UAAU,EACV,gBAAgB,EAChB,OAAO,GACR,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,KAAK,EACL,eAAe,EACf,YAAY,EACZ,KAAK,EACL,WAAW,EACX,gBAAgB,EAChB,OAAO,EAEP,OAAO,EACP,OAAO,EACP,QAAQ,EACR,SAAS,EACT,GAAG,EACH,UAAU,EACV,SAAS,EACT,KAAK,EACL,YAAY,GACb,MAAM,WAAW,CAAC;AACnB,OAAO,EAEL,aAAa,EACb,cAAc,EACd,cAAc,GAEf,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,aAAa,EACb,QAAQ,EAGR,SAAS,EACT,iBAAiB,EAEjB,aAAa,EACb,cAAc,EAEd,UAAU,EACV,OAAO,GAIR,MAAM,SAAS,CAAC;AACjB,OAAO,EACL,cAAc,EACd,eAAe,EACf,WAAW,EACX,QAAQ,EACR,WAAW,EAEX,GAAG,EAEH,UAAU,EACV,WAAW,GACZ,MAAM,SAAS,CAAC"}

package/src/index.ts

@@ -0,0 +1,137 @@
+/** Public surface of @ultimat3/time. Explicit exports only. */
+
+export {
+  addBusinessDays,
+  type BusinessCalendar,
+  businessDaysBetween,
+  type IsoWeekday,
+  isBusinessDay,
+  isHoliday,
+  isWeekend,
+  nextBusinessDay,
+  WEEKEND_FRI_SAT,
+  WEEKEND_SAT_SUN,
+  WEEKEND_SUN_ONLY,
+} from './business';
+export {
+  attachTimeZone,
+  configureTime,
+  currentTimeZone,
+  resolveTimeZone,
+  TIMEZONE_HEADER,
+  type TimeConfig,
+  type TimeZoneResolution,
+  type TimeZoneSourceName,
+  type TimeZoneSources,
+  timeConfig,
+  timeZoneOf,
+} from './context';
+export {
+  type CronExpression,
+  type CronPhrases,
+  describeCron,
+  firedSince,
+  isValidCron,
+  matchesCron,
+  nextCronOccurrence,
+  nextCronOccurrenceMs,
+  nextCronOccurrences,
+  parseCron,
+} from './cron';
+export {
+  DAY,
+  type FormatDurationOptions,
+  formatDuration,
+  formatDurationIso,
+  HOUR,
+  MINUTE,
+  MS,
+  parseDuration,
+  SECOND,
+  toMs,
+  toSeconds,
+  WEEK,
+} from './duration';
+export {
+  cronInvalid,
+  dstAmbiguous,
+  dstNonexistent,
+  durationInvalid,
+  instantInvalid,
+  localeInvalid,
+  TIME_ERROR_CODES,
+  TIME_ERROR_TITLES,
+  TimeError,
+  type TimeErrorCode,
+  timezoneInvalid,
+} from './errors';
+export {
+  type DateTimeStyle,
+  type FormatContext,
+  type FormatDateTimeOptions,
+  type FormatRelativeOptions,
+  formatDate,
+  formatDateTime,
+  formatIsoDate,
+  formatRange,
+  formatRelative,
+  formatTime,
+  formatWithOffset,
+  ordinal,
+} from './format';
+export {
+  addMs,
+  compareInstants,
+  differenceMs,
+  EPOCH,
+  fromEpochMs,
+  fromEpochSeconds,
+  fromIso,
+  type Instant,
+  instant,
+  isAfter,
+  isBefore,
+  isInstant,
+  now,
+  subtractMs,
+  toEpochMs,
+  toIso,
+  toIsoDateUtc,
+} from './instant';
+export {
+  type LocalSlot,
+  nextLocalSlot,
+  nextLocalSlots,
+  nextWeeklySlot,
+  type WeeklySlot,
+} from './schedule';
+export {
+  addDaysInZone,
+  daysBetween,
+  endOfDay,
+  type FromZonedOptions,
+  type FromZonedResult,
+  fromZoned,
+  fromZonedDetailed,
+  type GapPolicy,
+  isoDateInZone,
+  isSameLocalDay,
+  type OverlapPolicy,
+  startOfDay,
+  toZoned,
+  type WallClock,
+  type ZonedDateTime,
+  type ZonedResolution,
+} from './zoned';
+export {
+  assertTimeZone,
+  isValidTimeZone,
+  observesDst,
+  offsetAt,
+  offsetLabel,
+  type TimeZone,
+  UTC,
+  type ZoneParts,
+  zoneAbbrev,
+  zonePartsAt,
+} from './zones';

package/src/instant.d.ts

@@ -0,0 +1,38 @@
+/**
+ * An `Instant` is a point on the UTC timeline. **All storage is UTC** — columns are
+ * `timestamptz`, wire format is ISO-8601 with `Z`, and no zone is attached to a stored
+ * value. Zones exist only at the edge, in `format.ts` and `zoned.ts`.
+ */
+import { type Clock } from '@ultimat3/core';
+declare const instantBrand: unique symbol;
+/** A `Date` that has been proven valid and is documented as UTC. */
+export type Instant = Date & {
+    readonly [instantBrand]: 'utc';
+};
+/** Wrap a `Date` from an untrusted source (a DB driver, a parsed payload). */
+export declare function instant(value: Date): Instant;
+/** ISO-8601 in, `Instant` out. An offset or `Z` is required — a bare local string is a bug. */
+export declare function fromIso(iso: string): Instant;
+/** The only serialization: `2026-03-14T09:00:00.000Z`. */
+export declare function toIso(at: Instant): string;
+/** Date-only ISO form in UTC. Use `formatIsoDate` when you need it in a zone. */
+export declare function toIsoDateUtc(at: Instant): string;
+export declare function fromEpochMs(ms: number): Instant;
+export declare function toEpochMs(at: Instant): number;
+export declare function fromEpochSeconds(seconds: number): Instant;
+/**
+ * The clock is always injected. Tests freeze time by passing a fake clock; nothing in
+ * the framework calls `Date.now()` directly.
+ */
+export declare function now(clock?: Clock): Instant;
+export declare function addMs(at: Instant, ms: number): Instant;
+export declare function subtractMs(at: Instant, ms: number): Instant;
+/** Signed milliseconds from `from` to `to`. */
+export declare function differenceMs(from: Instant, to: Instant): number;
+export declare function isBefore(left: Instant, right: Instant): boolean;
+export declare function isAfter(left: Instant, right: Instant): boolean;
+export declare function compareInstants(left: Instant, right: Instant): -1 | 0 | 1;
+export declare function isInstant(value: unknown): value is Instant;
+export declare const EPOCH: Instant;
+export {};
+//# sourceMappingURL=instant.d.ts.map

package/src/instant.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instant.d.ts","sourceRoot":"","sources":["instant.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,KAAK,KAAK,EAAe,MAAM,gBAAgB,CAAC;AAGzD,OAAO,CAAC,MAAM,YAAY,EAAE,OAAO,MAAM,CAAC;AAE1C,oEAAoE;AACpE,MAAM,MAAM,OAAO,GAAG,IAAI,GAAG;IAAE,QAAQ,CAAC,CAAC,YAAY,CAAC,EAAE,KAAK,CAAA;CAAE,CAAC;AAEhE,8EAA8E;AAC9E,wBAAgB,OAAO,CAAC,KAAK,EAAE,IAAI,GAAG,OAAO,CAG5C;AAED,+FAA+F;AAC/F,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAI5C;AAED,0DAA0D;AAC1D,wBAAgB,KAAK,CAAC,EAAE,EAAE,OAAO,GAAG,MAAM,CAEzC;AAED,iFAAiF;AACjF,wBAAgB,YAAY,CAAC,EAAE,EAAE,OAAO,GAAG,MAAM,CAEhD;AAED,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAG/C;AAED,wBAAgB,SAAS,CAAC,EAAE,EAAE,OAAO,GAAG,MAAM,CAE7C;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAEzD;AAED;;;GAGG;AACH,wBAAgB,GAAG,CAAC,KAAK,GAAE,KAAmB,GAAG,OAAO,CAEvD;AAED,wBAAgB,KAAK,CAAC,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAEtD;AAED,wBAAgB,UAAU,CAAC,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAE3D;AAED,+CAA+C;AAC/C,wBAAgB,YAAY,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,GAAG,MAAM,CAE/D;AAED,wBAAgB,QAAQ,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAE/D;AAED,wBAAgB,OAAO,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAE9D;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAGzE;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,OAAO,CAE1D;AAED,eAAO,MAAM,KAAK,EAAE,OAAgC,CAAC"}

package/src/instant.js

@@ -0,0 +1,76 @@
+/**
+ * An `Instant` is a point on the UTC timeline. **All storage is UTC** — columns are
+ * `timestamptz`, wire format is ISO-8601 with `Z`, and no zone is attached to a stored
+ * value. Zones exist only at the edge, in `format.ts` and `zoned.ts`.
+ */
+import { systemClock } from '@ultimat3/core';
+import { instantInvalid } from './errors';
+/** Wrap a `Date` from an untrusted source (a DB driver, a parsed payload). */
+export function instant(value) {
+    if (Number.isNaN(value.getTime()))
+        throw instantInvalid(String(value));
+    return value;
+}
+/** ISO-8601 in, `Instant` out. An offset or `Z` is required — a bare local string is a bug. */
+export function fromIso(iso) {
+    const parsed = new Date(iso);
+    if (Number.isNaN(parsed.getTime()))
+        throw instantInvalid(iso);
+    return parsed;
+}
+/** The only serialization: `2026-03-14T09:00:00.000Z`. */
+export function toIso(at) {
+    return at.toISOString();
+}
+/** Date-only ISO form in UTC. Use `formatIsoDate` when you need it in a zone. */
+export function toIsoDateUtc(at) {
+    return at.toISOString().slice(0, 10);
+}
+export function fromEpochMs(ms) {
+    if (!Number.isFinite(ms))
+        throw instantInvalid(String(ms));
+    return new Date(ms);
+}
+export function toEpochMs(at) {
+    return at.getTime();
+}
+export function fromEpochSeconds(seconds) {
+    return fromEpochMs(seconds * 1000);
+}
+/**
+ * The clock is always injected. Tests freeze time by passing a fake clock; nothing in
+ * the framework calls `Date.now()` directly.
+ */
+export function now(clock = systemClock) {
+    return fromEpochMs(epochMsOf(clock.now()));
+}
+export function addMs(at, ms) {
+    return fromEpochMs(at.getTime() + ms);
+}
+export function subtractMs(at, ms) {
+    return fromEpochMs(at.getTime() - ms);
+}
+/** Signed milliseconds from `from` to `to`. */
+export function differenceMs(from, to) {
+    return to.getTime() - from.getTime();
+}
+export function isBefore(left, right) {
+    return left.getTime() < right.getTime();
+}
+export function isAfter(left, right) {
+    return left.getTime() > right.getTime();
+}
+export function compareInstants(left, right) {
+    if (left.getTime() < right.getTime())
+        return -1;
+    return left.getTime() > right.getTime() ? 1 : 0;
+}
+export function isInstant(value) {
+    return value instanceof Date && !Number.isNaN(value.getTime());
+}
+export const EPOCH = new Date(0);
+/** Tolerates a `Clock` whose `now()` returns either a `Date` or epoch milliseconds. */
+function epochMsOf(value) {
+    return typeof value === 'number' ? value : value.getTime();
+}
+//# sourceMappingURL=instant.js.map

package/src/instant.js.map

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

package/src/instant.ts

@@ -0,0 +1,94 @@
+/**
+ * An `Instant` is a point on the UTC timeline. **All storage is UTC** — columns are
+ * `timestamptz`, wire format is ISO-8601 with `Z`, and no zone is attached to a stored
+ * value. Zones exist only at the edge, in `format.ts` and `zoned.ts`.
+ */
+
+import { type Clock, systemClock } from '@ultimat3/core';
+import { instantInvalid } from './errors';
+
+declare const instantBrand: unique symbol;
+
+/** A `Date` that has been proven valid and is documented as UTC. */
+export type Instant = Date & { readonly [instantBrand]: 'utc' };
+
+/** Wrap a `Date` from an untrusted source (a DB driver, a parsed payload). */
+export function instant(value: Date): Instant {
+  if (Number.isNaN(value.getTime())) throw instantInvalid(String(value));
+  return value as Instant;
+}
+
+/** ISO-8601 in, `Instant` out. An offset or `Z` is required — a bare local string is a bug. */
+export function fromIso(iso: string): Instant {
+  const parsed = new Date(iso);
+  if (Number.isNaN(parsed.getTime())) throw instantInvalid(iso);
+  return parsed as Instant;
+}
+
+/** The only serialization: `2026-03-14T09:00:00.000Z`. */
+export function toIso(at: Instant): string {
+  return at.toISOString();
+}
+
+/** Date-only ISO form in UTC. Use `formatIsoDate` when you need it in a zone. */
+export function toIsoDateUtc(at: Instant): string {
+  return at.toISOString().slice(0, 10);
+}
+
+export function fromEpochMs(ms: number): Instant {
+  if (!Number.isFinite(ms)) throw instantInvalid(String(ms));
+  return new Date(ms) as Instant;
+}
+
+export function toEpochMs(at: Instant): number {
+  return at.getTime();
+}
+
+export function fromEpochSeconds(seconds: number): Instant {
+  return fromEpochMs(seconds * 1000);
+}
+
+/**
+ * The clock is always injected. Tests freeze time by passing a fake clock; nothing in
+ * the framework calls `Date.now()` directly.
+ */
+export function now(clock: Clock = systemClock): Instant {
+  return fromEpochMs(epochMsOf(clock.now()));
+}
+
+export function addMs(at: Instant, ms: number): Instant {
+  return fromEpochMs(at.getTime() + ms);
+}
+
+export function subtractMs(at: Instant, ms: number): Instant {
+  return fromEpochMs(at.getTime() - ms);
+}
+
+/** Signed milliseconds from `from` to `to`. */
+export function differenceMs(from: Instant, to: Instant): number {
+  return to.getTime() - from.getTime();
+}
+
+export function isBefore(left: Instant, right: Instant): boolean {
+  return left.getTime() < right.getTime();
+}
+
+export function isAfter(left: Instant, right: Instant): boolean {
+  return left.getTime() > right.getTime();
+}
+
+export function compareInstants(left: Instant, right: Instant): -1 | 0 | 1 {
+  if (left.getTime() < right.getTime()) return -1;
+  return left.getTime() > right.getTime() ? 1 : 0;
+}
+
+export function isInstant(value: unknown): value is Instant {
+  return value instanceof Date && !Number.isNaN(value.getTime());
+}
+
+export const EPOCH: Instant = new Date(0) as Instant;
+
+/** Tolerates a `Clock` whose `now()` returns either a `Date` or epoch milliseconds. */
+function epochMsOf(value: Date | number): number {
+  return typeof value === 'number' ? value : value.getTime();
+}

package/src/schedule.d.ts

@@ -0,0 +1,24 @@
+/**
+ * "Send at 09:00 local" — the scheduling primitive digests, reminders and drip campaigns
+ * are built from. Local means the *recipient's* local, and it survives DST.
+ */
+import type { Instant } from './instant';
+import { type TimeZone } from './zones';
+export interface LocalSlot {
+    zone: TimeZone;
+    /** 0–23, wall clock in `zone`. */
+    hour: number;
+    /** 0–59. */
+    minute?: number;
+    second?: number;
+}
+export declare function nextLocalSlot(slot: LocalSlot, after: Instant): Instant;
+/** The next `count` daily slots — a preview for the schedule screen. */
+export declare function nextLocalSlots(slot: LocalSlot, after: Instant, count: number): Instant[];
+export interface WeeklySlot extends LocalSlot {
+    /** ISO weekday: 1 = Monday … 7 = Sunday. */
+    weekday: number;
+}
+/** Next `weekday` at the local time, strictly after `after`. */
+export declare function nextWeeklySlot(slot: WeeklySlot, after: Instant): Instant;
+//# sourceMappingURL=schedule.d.ts.map

package/src/schedule.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schedule.d.ts","sourceRoot":"","sources":["schedule.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,EAAkB,KAAK,QAAQ,EAAE,MAAM,SAAS,CAAC;AAExD,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,QAAQ,CAAC;IACf,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,YAAY;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAgBD,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CA6BtE;AAED,wEAAwE;AACxE,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,EAAE,CAQxF;AAED,MAAM,WAAW,UAAW,SAAQ,SAAS;IAC3C,4CAA4C;IAC5C,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,gEAAgE;AAChE,wBAAgB,cAAc,CAAC,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAQxE"}

package/src/schedule.js

@@ -0,0 +1,67 @@
+/**
+ * "Send at 09:00 local" — the scheduling primitive digests, reminders and drip campaigns
+ * are built from. Local means the *recipient's* local, and it survives DST.
+ */
+import { scheduleInvalid, timezoneInvalid } from './errors';
+import { fromZoned, toZoned } from './zoned';
+import { assertTimeZone } from './zones';
+/**
+ * Next instant matching the local `HH:mm` in `zone`, strictly after `after`.
+ *
+ * Walks forward day by day on the *local* calendar rather than adding 86 400 000 ms, so
+ * a 23- or 25-hour day does not shift the slot. If the slot falls in a spring-forward
+ * gap, `{ gap: 'next' }` picks the first existing local time instead of skipping the day.
+ */
+/** Wall-clock fields are never wrapped or clamped — a shifted schedule beats no schedule. */
+function assertWallField(field, value, max) {
+    if (!Number.isInteger(value) || value < 0 || value > max) {
+        throw scheduleInvalid(field, value, `an integer 0-${String(max)}`);
+    }
+}
+export function nextLocalSlot(slot, after) {
+    assertTimeZone(slot.zone);
+    assertWallField('slot.hour', slot.hour, 23);
+    const minute = slot.minute ?? 0;
+    const second = slot.second ?? 0;
+    // Validated too: a minute of 90 would otherwise roll into the next hour and ship a
+    // schedule an hour off, which is exactly the class of bug this package exists to prevent.
+    assertWallField('slot.minute', minute, 59);
+    assertWallField('slot.second', second, 59);
+    const start = toZoned(after, slot.zone);
+    for (let dayOffset = 0; dayOffset < 4; dayOffset += 1) {
+        const candidate = fromZoned({
+            year: start.year,
+            month: start.month,
+            day: start.day + dayOffset,
+            hour: slot.hour,
+            minute,
+            second,
+        }, slot.zone, { gap: 'next', overlap: 'first' });
+        if (candidate.getTime() > after.getTime())
+            return candidate;
+    }
+    // Four local days always contain the slot; reaching here means the zone data is broken.
+    throw timezoneInvalid(slot.zone);
+}
+/** The next `count` daily slots — a preview for the schedule screen. */
+export function nextLocalSlots(slot, after, count) {
+    const slots = [];
+    let cursor = after;
+    for (let index = 0; index < count; index += 1) {
+        cursor = nextLocalSlot(slot, cursor);
+        slots.push(cursor);
+    }
+    return slots;
+}
+/** Next `weekday` at the local time, strictly after `after`. */
+export function nextWeeklySlot(slot, after) {
+    let cursor = after;
+    for (let index = 0; index < 8; index += 1) {
+        const candidate = nextLocalSlot(slot, cursor);
+        if (toZoned(candidate, slot.zone).weekday === slot.weekday)
+            return candidate;
+        cursor = candidate;
+    }
+    throw timezoneInvalid(slot.zone);
+}
+//# sourceMappingURL=schedule.js.map