@northguild/gmt 1.14.2 → 1.15.0

package/dist/regex/time.js

@@ -1,9 +1,65 @@
-// regex patterns exported for usage
+/**
+ * RegExp matching an ISO 8601 hour in extended format: `00`–`23`.
+ *
+ * @example hour.test("00") // true
+ * @example hour.test("12") // true
+ * @example hour.test("23") // true
+ * @example hour.test("24") // false (out of range)
+ * @example hour.test("9")  // false (not zero-padded)
+ */
 export const hour = /^(0[0-9]|1[0-9]|2[0-3])$/;
+/**
+ * RegExp matching an ISO 8601 minute: `00`–`59`.
+ *
+ * @example minute.test("00") // true
+ * @example minute.test("30") // true
+ * @example minute.test("59") // true
+ * @example minute.test("60") // false (out of range)
+ */
 export const minute = /^[0-5][0-9]$/;
+/**
+ * RegExp matching an ISO 8601 second: `00`–`59`.
+ *
+ * @example second.test("00") // true
+ * @example second.test("30") // true
+ * @example second.test("59") // true
+ * @example second.test("60") // false (out of range; leap seconds use a different pattern)
+ */
 export const second = /^[0-5][0-9]$/;
+/**
+ * RegExp matching 1–9 fractional-second digits (nanosecond precision).
+ *
+ * - Used for the fractional portion after `.` or `,` in time strings.
+ * - Backward-compatible alias `millisecond` points to this same pattern.
+ *
+ * @example fractionalSecond.test("123")       // true (milliseconds)
+ * @example fractionalSecond.test("123456789") // true (nanoseconds)
+ * @example fractionalSecond.test("0")         // false (must be 1–9 digits)
+ * @example fractionalSecond.test("")          // false (empty)
+ */
 export const fractionalSecond = /^[0-9]{1,9}$/;
-// Backward-compatible alias; prefer fractionalSecond for new usage.
+/**
+ * Backward-compatible alias for `fractionalSecond`. Prefer `fractionalSecond` for new
+ * usage — the pattern matches 1–9 digits of fractional seconds, not just milliseconds.
+ */
 export const millisecond = fractionalSecond;
-// ISO 8601 local time (extended): HH:mm[:ss[.fffffffff]]
+/**
+ * RegExp matching ISO 8601 local time (extended): `HH:mm[:ss[.fffffffff]]`.
+ *
+ * - Hours: `00`–`23`, zero-padded.
+ * - Minutes and seconds: `00`–`59`, zero-padded.
+ * - Seconds are optional; fractional seconds use `.` or `,` followed by 1–9 digits.
+ * - No timezone designator — this is a plain/local time only.
+ * - Shape-only validation; real field validation is delegated to
+ *   `Temporal.PlainTime.from` in `parseTime`.
+ *
+ * Capture groups: 1 hour, 2 minute, 3 second (optional), 4 fractional (optional).
+ *
+ * @example plainTime.test("14:30")              // true
+ * @example plainTime.test("14:30:00")           // true
+ * @example plainTime.test("14:30:00.123")       // true (fractional seconds)
+ * @example plainTime.test("14:30:00,123")       // true (comma separator)
+ * @example plainTime.test("24:00:00")           // false (hour out of range)
+ * @example plainTime.test("14:30:60")           // false (second out of range)
+ */
 export const plainTime = /^(0[0-9]|1[0-9]|2[0-3]):[0-5][0-9](?::[0-5][0-9](?:[.,][0-9]{1,9})?)?$/;

package/dist/regex/unix.d.ts

@@ -1,2 +1,23 @@
+/**
+ * RegExp matching a Unix timestamp in seconds: exactly 10 digits.
+ *
+ * - Covers the range from `0000000000` (1970-01-01T00:00:00Z) through
+ *   `3999999999` (2096-10-11T03:33:19Z), which is the practical range for
+ *   10-digit Unix-second timestamps.
+ *
+ * @example unixSeconds.test("1710511800") // true
+ * @example unixSeconds.test("0000000000") // true (epoch)
+ * @example unixSeconds.test("17105118001") // false (11 digits)
+ */
 export declare const unixSeconds: RegExp;
+/**
+ * RegExp matching a Unix timestamp in milliseconds: exactly 13 digits.
+ *
+ * - Covers the range from `0000000000000` (1970-01-01T00:00:00Z) through
+ *   `3999999999999` (2096-10-11T03:33:19.999Z).
+ *
+ * @example unixMilliseconds.test("1710511800123") // true
+ * @example unixMilliseconds.test("0000000000000")  // true (epoch)
+ * @example unixMilliseconds.test("17105118001")    // false (11 digits)
+ */
 export declare const unixMilliseconds: RegExp;

package/dist/regex/unix.js

@@ -1,2 +1,23 @@
+/**
+ * RegExp matching a Unix timestamp in seconds: exactly 10 digits.
+ *
+ * - Covers the range from `0000000000` (1970-01-01T00:00:00Z) through
+ *   `3999999999` (2096-10-11T03:33:19Z), which is the practical range for
+ *   10-digit Unix-second timestamps.
+ *
+ * @example unixSeconds.test("1710511800") // true
+ * @example unixSeconds.test("0000000000") // true (epoch)
+ * @example unixSeconds.test("17105118001") // false (11 digits)
+ */
 export const unixSeconds = /^\d{10}$/;
+/**
+ * RegExp matching a Unix timestamp in milliseconds: exactly 13 digits.
+ *
+ * - Covers the range from `0000000000000` (1970-01-01T00:00:00Z) through
+ *   `3999999999999` (2096-10-11T03:33:19.999Z).
+ *
+ * @example unixMilliseconds.test("1710511800123") // true
+ * @example unixMilliseconds.test("0000000000000")  // true (epoch)
+ * @example unixMilliseconds.test("17105118001")    // false (11 digits)
+ */
 export const unixMilliseconds = /^\d{13}$/;

package/dist/regex/utc-date-time.d.ts

@@ -1 +1,21 @@
+/**
+ * RegExp matching ISO 8601 UTC datetime: `<date>T<time>Z` with optional fractional
+ * seconds. The timezone designator accepts `Z` or `z` (lowercase is accepted for
+ * leniency, though GMT's own formatter always emits uppercase).
+ *
+ * - Date half: `YYYY-MM-DD` or `±YYYYYY-MM-DD` (6-digit year with sign).
+ * - Time half: `HH:mm` with optional `:ss[.fffffffff]` (fractional seconds use `.` or `,`).
+ * - No numeric offset — only the `Z`/`z` UTC designator is accepted.
+ * - Shape-only validation; real calendar validation is delegated to
+ *   `Temporal.PlainDateTime.from` in `parseUtcDateTime`.
+ *
+ * Capture groups: 1 year, 2 month, 3 day, 4 hour, 5 minute, 6 second (optional),
+ * 7 fractional (optional).
+ *
+ * @example utcDateTime.test("2024-03-15T14:30:00Z")       // true
+ * @example utcDateTime.test("2024-03-15T14:30z")          // true (lowercase z)
+ * @example utcDateTime.test("2024-03-15T14:30:00.123Z")   // true (fractional seconds)
+ * @example utcDateTime.test("2024-03-15T14:30:00+00:00")  // false (numeric offset)
+ * @example utcDateTime.test("2024-03-15T14:30:00")        // false (no timezone)
+ */
 export declare const utcDateTime: RegExp;

package/dist/regex/utc-date-time.js

@@ -1,2 +1,21 @@
-// ISO 8601 UTC datetime: <date>T<time>Z with optional fractional seconds
+/**
+ * RegExp matching ISO 8601 UTC datetime: `<date>T<time>Z` with optional fractional
+ * seconds. The timezone designator accepts `Z` or `z` (lowercase is accepted for
+ * leniency, though GMT's own formatter always emits uppercase).
+ *
+ * - Date half: `YYYY-MM-DD` or `±YYYYYY-MM-DD` (6-digit year with sign).
+ * - Time half: `HH:mm` with optional `:ss[.fffffffff]` (fractional seconds use `.` or `,`).
+ * - No numeric offset — only the `Z`/`z` UTC designator is accepted.
+ * - Shape-only validation; real calendar validation is delegated to
+ *   `Temporal.PlainDateTime.from` in `parseUtcDateTime`.
+ *
+ * Capture groups: 1 year, 2 month, 3 day, 4 hour, 5 minute, 6 second (optional),
+ * 7 fractional (optional).
+ *
+ * @example utcDateTime.test("2024-03-15T14:30:00Z")       // true
+ * @example utcDateTime.test("2024-03-15T14:30z")          // true (lowercase z)
+ * @example utcDateTime.test("2024-03-15T14:30:00.123Z")   // true (fractional seconds)
+ * @example utcDateTime.test("2024-03-15T14:30:00+00:00")  // false (numeric offset)
+ * @example utcDateTime.test("2024-03-15T14:30:00")        // false (no timezone)
+ */
 export const utcDateTime = /^(?:\d{4}|[+-]\d{6})-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])T(0[0-9]|1[0-9]|2[0-3]):[0-5][0-9](?::[0-5][0-9](?:[.,]\d{1,9})?)?[Zz]$/;

package/dist/types/calendar-options.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Core fields shared by all calendar-formatting interfaces.
+ * Each domain variant (plain, unix, utc, zoned) extends this and may
+ * add domain-specific fields like `timeZone` or `epochUnit`.
+ */
+export interface CalendarOptions {
+    /** Anchor point for the relative day comparison. */
+    reference?: string;
+    /** `Intl.DateTimeFormatOptions` `timeStyle` for the time-of-day half. */
+    timeStyle?: "short" | "medium" | "full";
+}

package/dist/types/datetime-format-options.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Options accepted by date/time formatting functions that delegate to
+ * `Intl.DateTimeFormat` (via Temporal's `.toLocaleString()` or
+ * `TemporalIntl.DateTimeFormat`).
+ */
+export type DateTimeFormatOptions = Intl.DateTimeFormatOptions;

package/dist/types/duration-unit.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Plural unit keys accepted by `formatDuration` for `UNIT_TO_INTL` lookup. Maps to
+ * singular `Intl.NumberFormat` unit labels (e.g. `"years"` → `"year"`).
+ */
+export type DurationUnit = "years" | "months" | "weeks" | "days" | "hours" | "minutes" | "seconds";

package/dist/types/index.d.ts

@@ -1,3 +1,4 @@
+export * from "./calendar-options.js";
 export * from "./calendar-system.js";
 export * from "./date-cycle-field.js";
 export * from "./date-duration-unit.js";
@@ -5,14 +6,24 @@ export * from "./date-time-cycle-field.js";
 export * from "./date-time-duration-units.js";
 export * from "./date-time-unit.js";
 export * from "./date-unit.js";
+export * from "./datetime-format-options.js";
 export * from "./disambiguation.js";
 export * from "./duration-relative-to.js";
 export * from "./duration-string-options.js";
+export * from "./duration-unit.js";
 export * from "./fractional-digit.js";
+export * from "./now-unit.js";
 export * from "./offset.js";
 export * from "./overflow.js";
+export * from "./relative-date-time-unit.js";
+export * from "./relative-date-unit.js";
 export * from "./relative-rounding-method.js";
+export * from "./relative-time-options.js";
+export * from "./relative-time-unit.js";
+export * from "./relative-unit.js";
 export * from "./rounding-options.js";
 export * from "./time-cycle-field.js";
 export * from "./time-duration-unit.js";
 export * from "./time-unit.js";
+export * from "./unix-now-unit.js";
+export * from "./utc-now-unit.js";

package/dist/types/index.js

@@ -1,3 +1,4 @@
+export * from "./calendar-options.js";
 export * from "./calendar-system.js";
 export * from "./date-cycle-field.js";
 export * from "./date-duration-unit.js";
@@ -5,14 +6,24 @@ export * from "./date-time-cycle-field.js";
 export * from "./date-time-duration-units.js";
 export * from "./date-time-unit.js";
 export * from "./date-unit.js";
+export * from "./datetime-format-options.js";
 export * from "./disambiguation.js";
 export * from "./duration-relative-to.js";
 export * from "./duration-string-options.js";
+export * from "./duration-unit.js";
 export * from "./fractional-digit.js";
+export * from "./now-unit.js";
 export * from "./offset.js";
 export * from "./overflow.js";
+export * from "./relative-date-time-unit.js";
+export * from "./relative-date-unit.js";
 export * from "./relative-rounding-method.js";
+export * from "./relative-time-options.js";
+export * from "./relative-time-unit.js";
+export * from "./relative-unit.js";
 export * from "./rounding-options.js";
 export * from "./time-cycle-field.js";
 export * from "./time-duration-unit.js";
 export * from "./time-unit.js";
+export * from "./unix-now-unit.js";
+export * from "./utc-now-unit.js";

package/dist/types/now-unit.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Units extractable from the current system local time via `getNowUnit`.
+ * Defined as `DateTimeUnit | "dayOfWeek"`.
+ */
+export type NowUnit = import("./date-time-unit.js").DateTimeUnit | "dayOfWeek";

package/dist/types/relative-date-time-unit.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Full 7-member `RelativeUnit` for `PlainDateTime`-based formatting. Covers the
+ * complete set of `Intl.RelativeTimeFormat` units supported by Temporal, excluding
+ * `quarter`.
+ */
+export type RelativeDateTimeUnit = "year" | "month" | "week" | "day" | "hour" | "minute" | "second";

package/dist/types/relative-date-unit.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Narrow `RelativeUnit` for `PlainDate`-based formatting. Excludes `hour`,
+ * `minute`, and `second` because `PlainDate` has no time component.
+ */
+export type RelativeDateUnit = "year" | "month" | "week" | "day";

package/dist/types/relative-time-options.d.ts

@@ -0,0 +1,18 @@
+import type { RelativeRoundingMethod } from "./relative-rounding-method.js";
+/**
+ * Core fields shared by all relative-time formatting interfaces.
+ * Each domain variant (plain, unix, utc, zoned) extends this and may
+ * restrict `largestUnit` or add domain-specific fields.
+ */
+export interface RelativeTimeFormatOptions {
+    /** Name style: "long" (default), "short", or "narrow". */
+    style?: "long" | "short" | "narrow";
+    /** Whether to use relative time words ("in 2 days") or numeric ("2 days"). */
+    numeric?: "always" | "auto";
+    /** The largest unit to display. Each domain restricts the allowed values. */
+    largestUnit?: string;
+    /** How the computed distance rounds to the display unit. */
+    roundingMethod?: RelativeRoundingMethod;
+    /** Anchor point for the relative diff. */
+    reference?: string;
+}

package/dist/types/relative-time-unit.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Narrow `RelativeUnit` for `PlainTime`-based formatting. Excludes date units
+ * (`year`, `month`, `week`, `day`) because `PlainTime` has no date component.
+ */
+export type RelativeTimeUnit = "hour" | "minute" | "second";

package/dist/types/relative-unit.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Canonical 7-member unit for `Intl.RelativeTimeFormat` and Temporal `since`/`until`
+ * totals, excluding `quarter`. Shared by `formatRelativeUnix`, `formatRelativeUtc`,
+ * and `formatRelativeZoned` after importing from this barrel.
+ */
+export type RelativeUnit = "year" | "month" | "week" | "day" | "hour" | "minute" | "second";

package/dist/types/unix-now-unit.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Units extractable from the current Unix timestamp in UTC via `getUnixNowUnit`.
+ * Defined as `DateTimeUnit | "dayOfWeek"`.
+ */
+export type UnixNowUnit = import("./date-time-unit.js").DateTimeUnit | "dayOfWeek";

package/dist/types/utc-now-unit.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Units extractable from the current UTC instant via `getUtcNowUnit`.
+ * Defined as `DateTimeUnit | "dayOfWeek"`.
+ */
+export type UtcNowUnit = import("./date-time-unit.js").DateTimeUnit | "dayOfWeek";

package/dist/unix/calculate/startOrEndOfUnix.d.ts

@@ -1,5 +1,23 @@
 import { Temporal } from "@js-temporal/polyfill";
 import type { Disambiguation, Offset } from "../../types/index.js";
+/**
+ * Internal shared implementation for `startOfUnix` / `endOfUnix`.
+ *
+ * - Converts the epoch to a ZonedDateTime, snaps to the start or end of the
+ *   requested unit, then converts back to an epoch number.
+ * - Supports every Temporal `DateUnit` and `TimeUnit`.
+ * - `epochUnit` controls whether the input/output is interpreted as `"milliseconds"` (default) or `"seconds"`.
+ * - `timeZone` defaults to the system time zone via `getSystemTimeZone()`.
+ * - `disambiguation` and `offset` are forwarded to Temporal's `.with()` for
+ *   DST-gap/overlap boundaries; see `startOfUnix`'s JSDoc for the full
+ *   semantics — they behave identically here.
+ *
+ * @param value Unix epoch number
+ * @param unit Temporal.DateUnit | Temporal.TimeUnit to snap to
+ * @param options optional: epochUnit, timeZone, weekStartsOn, disambiguation, offset
+ * @param isEnd false for start-of-unit, true for end-of-unit
+ * @returns Unix epoch number, or null on invalid input
+ */
 export declare function startOrEndOfUnix(value: number, unit: Temporal.DateUnit | Temporal.TimeUnit, options: {
     epochUnit?: "seconds" | "milliseconds";
     timeZone?: string;

package/dist/unix/calculate/startOrEndOfUnix.js

@@ -3,6 +3,24 @@ import { isValidDateTimeUnit } from "../../plain/index.js";
 import { isValidUnixUnit } from "../../unix/validate/isValidUnixUnit.js";
 import { getSystemTimeZone } from "../../zoned/get/index.js";
 import { isValidTimeZone } from "../../zoned/validate/index.js";
+/**
+ * Internal shared implementation for `startOfUnix` / `endOfUnix`.
+ *
+ * - Converts the epoch to a ZonedDateTime, snaps to the start or end of the
+ *   requested unit, then converts back to an epoch number.
+ * - Supports every Temporal `DateUnit` and `TimeUnit`.
+ * - `epochUnit` controls whether the input/output is interpreted as `"milliseconds"` (default) or `"seconds"`.
+ * - `timeZone` defaults to the system time zone via `getSystemTimeZone()`.
+ * - `disambiguation` and `offset` are forwarded to Temporal's `.with()` for
+ *   DST-gap/overlap boundaries; see `startOfUnix`'s JSDoc for the full
+ *   semantics — they behave identically here.
+ *
+ * @param value Unix epoch number
+ * @param unit Temporal.DateUnit | Temporal.TimeUnit to snap to
+ * @param options optional: epochUnit, timeZone, weekStartsOn, disambiguation, offset
+ * @param isEnd false for start-of-unit, true for end-of-unit
+ * @returns Unix epoch number, or null on invalid input
+ */
 export function startOrEndOfUnix(value, unit, options, isEnd) {
     const epochUnit = options.epochUnit ?? "milliseconds";
     const timeZone = options.timeZone ?? getSystemTimeZone();

package/dist/unix/format/formatCalendarUnix.d.ts

@@ -1,6 +1,32 @@
+/**
+ * Options for `formatCalendarUnix`. Mirrors the option shape of
+ * `formatCalendar` but targets the unix domain, adding `epochUnit`.
+ *
+ * @remarks Members:
+ *
+ * | Member | Type | Default | Description |
+ * | --- | --- | --- | --- |
+ * | `style` | `"long"\|"short"\|"narrow"` | `"long"` | `RelativeTimeFormat` style for the day label. |
+ * | `numeric` | `"always"\|"auto"` | `"auto"` | Numeric formatting of the relative day label. |
+ * | `largestUnit` | `"year"\|"month"\|"week"\|"day"` | auto | Largest unit for the relative diff. |
+ * | `roundingMethod` | `"expand"\|"trunc"\|"floor"\|"ceil"` | — | Rounding for the computed distance. |
+ * | `reference` | `string\|number` | now (UTC) | Anchor epoch/ISO for the "today/tomorrow" comparison. |
+ * | `epochUnit` | `"milliseconds"\|"seconds"` | `"milliseconds"` | Interpretation of numeric `value`/`reference`. |
+ * | `timeZone` | `string` | `"UTC"` | IANA zone for both day-comparison and clock-time rendering. |
+ * | `timeStyle` | `"short"\|"medium"\|"full"` | `"short"` | `Intl` `timeStyle` for the time-of-day portion. |
+ *
+ * @example
+ * import { FormatCalendarUnixOptions } from "@northguild/gmt/unix";
+ * const opts: FormatCalendarUnixOptions = { timeZone: "America/New_York" };
+ */
 export interface FormatCalendarUnixOptions {
-    epochUnit?: "milliseconds" | "seconds";
+    style?: "long" | "short" | "narrow";
+    numeric?: "always" | "auto";
+    largestUnit?: "year" | "month" | "week" | "day";
+    roundingMethod?: "expand" | "trunc" | "floor" | "ceil";
+    /** Anchor point for the relative day comparison. Accepts ISO strings or numeric epochs. */
     reference?: string | number;
+    epochUnit?: "milliseconds" | "seconds";
     /**
      * IANA timezone used for both the calendar-day comparison and the
      * rendered clock time. Resolved via `normalizeTimeZone` — `"local"` for

package/dist/unix/format/formatRelativeUnix.d.ts

@@ -1,14 +1,8 @@
-import type { RelativeRoundingMethod } from "../../types/index.js";
-type RelativeUnit = "year" | "month" | "week" | "day" | "hour" | "minute" | "second";
+import type { RelativeRoundingMethod, RelativeUnit } from "../../types/index.js";
 export interface FormatRelativeUnixOptions {
     style?: "long" | "short" | "narrow";
     numeric?: "always" | "auto";
     largestUnit?: RelativeUnit;
-    /**
-     * How the computed distance rounds to the display unit: "floor" rounds toward the
-     * earlier boundary, "ceil" toward the later boundary, "round" (default) to the nearest —
-     * matches current behavior when omitted.
-     */
     roundingMethod?: RelativeRoundingMethod;
     epochUnit?: "milliseconds" | "seconds";
     reference?: string | number;
@@ -31,4 +25,3 @@ export interface FormatRelativeUnixOptions {
  * @example formatRelativeUnix("not-a-number") // ""
  */
 export declare function formatRelativeUnix(value: string | number, locale?: string, options?: FormatRelativeUnixOptions): string;
-export {};

package/dist/unix/format/formatUnix.d.ts

@@ -3,4 +3,23 @@ export interface FormatUnixOptions extends Intl.DateTimeFormatOptions {
     timeZone?: string;
     includeTimeZoneName?: boolean;
 }
+/**
+ * Format a unix epoch value (string or number) as a localized date/time string.
+ *
+ * - Returns `""` if the input is not a valid unix epoch value for the given `epochUnit`.
+ * - `epochUnit` controls whether the input is interpreted as `"milliseconds"` or `"seconds"`; defaults to `"milliseconds"`.
+ * - `timeZone` controls the IANA zone used for rendering; defaults to `"UTC"`.
+ * - `includeTimeZoneName` appends the localized timezone name when true.
+ *
+ * @param value unix epoch value to format (string or number, per `epochUnit`)
+ * @param locale optional: BCP 47 locale tag
+ * @param options optional: { epochUnit, timeZone, includeTimeZoneName }
+ * @returns the formatted date/time string, or "" on invalid input
+ *
+ * @example formatUnix("1710685845000", "en-US", { epochUnit: "milliseconds" }) // "3/17/2024, 2:30:45 PM"
+ * @example formatUnix(1710685845000, "en-US", { epochUnit: "milliseconds" }) // "3/17/2024, 2:30:45 PM"
+ * @example formatUnix("1710685845", "en-US", { epochUnit: "seconds" }) // "3/17/2024, 2:30:45 PM"
+ * @example formatUnix("1710685845000", "en-US", { epochUnit: "milliseconds", includeTimeZoneName: true }) // "3/17/2024, 2:30:45 PM UTC"
+ * @example formatUnix("not-a-number") // ""
+ */
 export declare function formatUnix(value: string | number, locale?: string, options?: FormatUnixOptions): string;

package/dist/unix/format/formatUnix.js

@@ -20,6 +20,25 @@ function parseEpochMs(value, epochUnit) {
         return null;
     return epochUnit === "seconds" ? n * 1000 : n;
 }
+/**
+ * Format a unix epoch value (string or number) as a localized date/time string.
+ *
+ * - Returns `""` if the input is not a valid unix epoch value for the given `epochUnit`.
+ * - `epochUnit` controls whether the input is interpreted as `"milliseconds"` or `"seconds"`; defaults to `"milliseconds"`.
+ * - `timeZone` controls the IANA zone used for rendering; defaults to `"UTC"`.
+ * - `includeTimeZoneName` appends the localized timezone name when true.
+ *
+ * @param value unix epoch value to format (string or number, per `epochUnit`)
+ * @param locale optional: BCP 47 locale tag
+ * @param options optional: { epochUnit, timeZone, includeTimeZoneName }
+ * @returns the formatted date/time string, or "" on invalid input
+ *
+ * @example formatUnix("1710685845000", "en-US", { epochUnit: "milliseconds" }) // "3/17/2024, 2:30:45 PM"
+ * @example formatUnix(1710685845000, "en-US", { epochUnit: "milliseconds" }) // "3/17/2024, 2:30:45 PM"
+ * @example formatUnix("1710685845", "en-US", { epochUnit: "seconds" }) // "3/17/2024, 2:30:45 PM"
+ * @example formatUnix("1710685845000", "en-US", { epochUnit: "milliseconds", includeTimeZoneName: true }) // "3/17/2024, 2:30:45 PM UTC"
+ * @example formatUnix("not-a-number") // ""
+ */
 export function formatUnix(value, locale, options) {
     const { epochUnit = "milliseconds", timeZone, includeTimeZoneName = false, ...intlOptions } = options ?? {};
     if (!isValidUnixUnit(epochUnit))

package/dist/unix/get/getUnixNowUnit.d.ts

@@ -1,5 +1,5 @@
-import type { DateTimeUnit } from "../../types/index.js";
-type UnixNowUnit = DateTimeUnit | "dayOfWeek";
+import type { UnixNowUnit } from "../../types/index.js";
+export type { UnixNowUnit };
 /**
  * Return the requested unit value from the current Unix timestamp in UTC.
  *
@@ -15,4 +15,3 @@ type UnixNowUnit = DateTimeUnit | "dayOfWeek";
  * @example getUnixNowUnit("invalid") // ""
  */
 export declare function getUnixNowUnit(unit: UnixNowUnit): string;
-export {};

package/dist/unix/parse/parseUnitFromUnix.d.ts

@@ -1,4 +1,28 @@
 import { type UnixUnit } from "../validate/index.js";
+/**
+ * Units extractable from a unix epoch value via `parseUnitFromUnix`. Covers the
+ * full set of date/time units plus sub-millisecond precision.
+ *
+ * @remarks Members:
+ *
+ * | Member | Description |
+ * | --- | --- |
+ * | `year` | Full year, no padding (e.g. `2024`). |
+ * | `month` | Zero-padded 2 (e.g. `03`). |
+ * | `week` | Week-of-year, 1–53 (`weekStartsOn`-controlled). |
+ * | `day` | Zero-padded 2. |
+ * | `dayOfWeek` | 1 (Mon)–7 (Sun). |
+ * | `hour` | Zero-padded 2. |
+ * | `minute` | Zero-padded 2. |
+ * | `second` | Zero-padded 2. |
+ * | `millisecond` | Zero-padded 3. |
+ * | `microsecond` | Zero-padded 3. |
+ * | `nanosecond` | Zero-padded 9. |
+ *
+ * @example
+ * import { PlainNowUnit } from "@northguild/gmt/unix";
+ * const u: PlainNowUnit = "month";
+ */
 export type PlainNowUnit = "year" | "month" | "week" | "day" | "dayOfWeek" | "hour" | "minute" | "second" | "millisecond" | "microsecond" | "nanosecond";
 /**
  * Extract a unit from a unix epoch value.

package/dist/unix/validate/isValidUnixUnit.d.ts

@@ -1,3 +1,18 @@
+/**
+ * Unit accepted by `epochUnit` in unix-epoch functions. Determines whether a
+ * numeric value is interpreted as milliseconds or seconds.
+ *
+ * @remarks Members:
+ *
+ * | Member | Description |
+ * | --- | --- |
+ * | `seconds` | Value is Unix epoch seconds (e.g. `1700000000`). |
+ * | `milliseconds` | Value is Unix epoch milliseconds (e.g. `1700000000000`). |
+ *
+ * @example
+ * import { isValidUnixUnit } from "@northguild/gmt/unix";
+ * isValidUnixUnit("milliseconds"); // true
+ */
 export type UnixUnit = "seconds" | "milliseconds";
 /**
  * Return true when `unit` is a valid UnixUnit.

package/dist/utc/calculate/startOrEndOfUtc.d.ts

@@ -1,5 +1,22 @@
 import { Temporal } from "@js-temporal/polyfill";
 import type { FractionalDigit } from "../../types/index.js";
+/**
+ * Internal shared implementation for `startOfUtc` / `endOfUtc`.
+ *
+ * - Converts the UTC Instant to a ZonedDateTime, snaps to the start or end of
+ *   the requested unit, then converts back to an Instant string.
+ * - Supports every Temporal `DateUnit` and `TimeUnit`.
+ * - `weekStartsOn` shifts the week boundary: `"monday"` (default) or `"sunday"`.
+ * - `fractionalSecondDigits` overrides the default sub-second precision for the
+ *   returned Instant string; defaults to 3 for millisecond, 6 for microsecond,
+ *   9 for nanosecond, and 0 for all coarser units.
+ *
+ * @param value ISO UTC datetime string
+ * @param unit Temporal.DateUnit | Temporal.TimeUnit to snap to
+ * @param options optional: weekStartsOn, fractionalSecondDigits
+ * @param isEnd false for start-of-unit, true for end-of-unit
+ * @returns UTC Instant string, or "" on invalid input
+ */
 export declare function startOrEndOfUtc(value: string, unit: Temporal.DateUnit | Temporal.TimeUnit, options: {
     weekStartsOn?: "monday" | "sunday";
     fractionalSecondDigits?: FractionalDigit;

package/dist/utc/calculate/startOrEndOfUtc.js

@@ -1,6 +1,23 @@
 import { Temporal } from "@js-temporal/polyfill";
 import { isValidDateTimeUnit } from "../../plain/index.js";
 import { isValidUtc } from "../validate/isValidUtc.js";
+/**
+ * Internal shared implementation for `startOfUtc` / `endOfUtc`.
+ *
+ * - Converts the UTC Instant to a ZonedDateTime, snaps to the start or end of
+ *   the requested unit, then converts back to an Instant string.
+ * - Supports every Temporal `DateUnit` and `TimeUnit`.
+ * - `weekStartsOn` shifts the week boundary: `"monday"` (default) or `"sunday"`.
+ * - `fractionalSecondDigits` overrides the default sub-second precision for the
+ *   returned Instant string; defaults to 3 for millisecond, 6 for microsecond,
+ *   9 for nanosecond, and 0 for all coarser units.
+ *
+ * @param value ISO UTC datetime string
+ * @param unit Temporal.DateUnit | Temporal.TimeUnit to snap to
+ * @param options optional: weekStartsOn, fractionalSecondDigits
+ * @param isEnd false for start-of-unit, true for end-of-unit
+ * @returns UTC Instant string, or "" on invalid input
+ */
 export function startOrEndOfUtc(value, unit, options, isEnd) {
     const weekStartsOn = options.weekStartsOn ?? "monday";
     const fractionalSecondDigits = options.fractionalSecondDigits;

package/dist/utc/format/formatCalendarUtc.d.ts

@@ -1,5 +1,5 @@
-export interface FormatCalendarUtcOptions {
-    reference?: string;
+import type { CalendarOptions } from "../../types/index.js";
+export interface FormatCalendarUtcOptions extends CalendarOptions {
     /**
      * IANA timezone used for both the calendar-day comparison and the
      * rendered clock time. Resolved via `normalizeTimeZone` — `"local"` for