@northguild/gmt 1.14.2 → 1.15.0

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

@@ -1,15 +1,6 @@
-import type { RelativeRoundingMethod } from "../../types/index.js";
-type RelativeUnit = "year" | "month" | "week" | "day" | "hour" | "minute" | "second";
-export interface FormatRelativeUtcOptions {
-    style?: "long" | "short" | "narrow";
-    numeric?: "always" | "auto";
+import type { RelativeTimeFormatOptions, RelativeUnit } from "../../types/index.js";
+export interface FormatRelativeUtcOptions extends RelativeTimeFormatOptions {
     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;
     reference?: string;
     timeZone?: string;
 }
@@ -30,4 +21,3 @@ export interface FormatRelativeUtcOptions {
  * @example formatRelativeUtc("not-a-date") // ""
  */
 export declare function formatRelativeUtc(value: string, locale?: string, options?: FormatRelativeUtcOptions): string;
-export {};

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

@@ -1,5 +1,38 @@
+/**
+ * Options for `formatUtc`. Extends `Intl.DateTimeFormatOptions`; only the
+ * added/overridden members are listed below. All `Intl.DateTimeFormatOptions`
+ * (`dateStyle`, `timeStyle`, etc.) apply to the time-of-day portion.
+ *
+ * @remarks Members:
+ *
+ * | Member | Type | Default | Description |
+ * | --- | --- | --- | --- |
+ * | `timeZone` | `string` | `"UTC"` | IANA zone for rendering; invalid/omitted falls back to UTC via `normalizeTimeZone`. |
+ * | `includeTimeZoneName` | `boolean` | `false` | Appends the localized zone name (style via `Intl`) when true. |
+ *
+ * @example
+ * import { FormatUtcOptions } from "@northguild/gmt/utc";
+ * const opts: FormatUtcOptions = { includeTimeZoneName: true };
+ */
 export interface FormatUtcOptions extends Intl.DateTimeFormatOptions {
     timeZone?: string;
     includeTimeZoneName?: boolean;
 }
+/**
+ * Format a UTC ISO string as a localized date/time string.
+ *
+ * - Returns `""` if the input is not a valid UTC string.
+ * - `timeZone` controls the IANA zone used for rendering; defaults to `"UTC"`.
+ * - `includeTimeZoneName` appends the localized timezone name when true.
+ *
+ * @param value UTC ISO string to format
+ * @param locale optional: BCP 47 locale tag
+ * @param options optional: { timeZone, includeTimeZoneName }
+ * @returns the formatted date/time string, or "" on invalid input
+ *
+ * @example formatUtc("2026-03-16T18:30:00Z") // "3/16/2026, 6:30:00 PM"
+ * @example formatUtc("2026-03-16T18:30:00Z", "en-US", { timeZone: "America/New_York" }) // "3/16/2026, 2:30:00 PM"
+ * @example formatUtc("2026-03-16T18:30:00Z", "en-US", { timeZone: "America/New_York", includeTimeZoneName: true }) // "3/16/2026, 2:30:00 PM EDT"
+ * @example formatUtc("not-a-date") // ""
+ */
 export declare function formatUtc(value: string, locale?: string, options?: FormatUtcOptions): string;

package/dist/utc/format/formatUtc.js

@@ -2,6 +2,23 @@ import { normalizeDateTime } from "../../internal/normalizeDateTime.js";
 import { normalizeTimeZone } from "../../internal/normalizeTimeZone.js";
 import { toInstantFromUtc } from "../../internal/toInstantFromUtc.js";
 import { isValidUtc } from "../validate/index.js";
+/**
+ * Format a UTC ISO string as a localized date/time string.
+ *
+ * - Returns `""` if the input is not a valid UTC string.
+ * - `timeZone` controls the IANA zone used for rendering; defaults to `"UTC"`.
+ * - `includeTimeZoneName` appends the localized timezone name when true.
+ *
+ * @param value UTC ISO string to format
+ * @param locale optional: BCP 47 locale tag
+ * @param options optional: { timeZone, includeTimeZoneName }
+ * @returns the formatted date/time string, or "" on invalid input
+ *
+ * @example formatUtc("2026-03-16T18:30:00Z") // "3/16/2026, 6:30:00 PM"
+ * @example formatUtc("2026-03-16T18:30:00Z", "en-US", { timeZone: "America/New_York" }) // "3/16/2026, 2:30:00 PM"
+ * @example formatUtc("2026-03-16T18:30:00Z", "en-US", { timeZone: "America/New_York", includeTimeZoneName: true }) // "3/16/2026, 2:30:00 PM EDT"
+ * @example formatUtc("not-a-date") // ""
+ */
 export function formatUtc(value, locale, options) {
     if (!isValidUtc(value))
         return "";

package/dist/utc/get/getUtcNowUnit.d.ts

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

package/dist/utc/parse/parseUnitFromUtc.d.ts

@@ -1,3 +1,26 @@
+/**
+ * Units supported by `parseUnitFromUtc` when extracting a value from a UTC ISO
+ * string. Excludes `microsecond` and `nanosecond`, which `parseUnitFromUtc`
+ * does not expose.
+ *
+ * @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. |
+ *
+ * @example
+ * import { UtcUnit } from "@northguild/gmt/utc";
+ * const u: UtcUnit = "month";
+ */
 export type UtcUnit = "year" | "month" | "week" | "day" | "dayOfWeek" | "hour" | "minute" | "second" | "millisecond";
 /**
  * Extract a unit from a UTC datetime string.

package/dist/zoned/format/formatRelativeZoned.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 FormatRelativeZonedOptions {
     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;
     /**
      * Anchor point for the relative diff.
@@ -41,4 +35,3 @@ export interface FormatRelativeZonedOptions {
  * @example formatRelativeZoned("not-a-date") // ""
  */
 export declare function formatRelativeZoned(value: string, locale?: string, options?: FormatRelativeZonedOptions): string;
-export {};

package/dist/zoned/format/formatTimeZoneName.d.ts

@@ -1,6 +1,21 @@
 /**
  * Name style for `formatTimeZoneName`, mirroring
  * `Intl.DateTimeFormatOptions`'s `timeZoneName` values.
+ *
+ * @remarks Members:
+ *
+ * | Member | Example (America/New_York) | Description |
+ * | --- | --- | --- |
+ * | `short` | `EST`/`EDT` | Abbreviated zone name; seasonal for DST zones. |
+ * | `long` | `Eastern Standard Time` | Full zone name; seasonal for DST zones. |
+ * | `shortOffset` | `GMT-5` | Short UTC offset; seasonal. |
+ * | `longOffset` | `GMT-05:00` | Zero-padded UTC offset; seasonal. |
+ * | `shortGeneric` | `ET` | Season-independent generic abbreviation. |
+ * | `longGeneric` | `Eastern Time` | Season-independent generic full name. |
+ *
+ * @example
+ * import { TimeZoneNameStyle } from "@northguild/gmt/zoned";
+ * const s: TimeZoneNameStyle = "shortGeneric";
  */
 export type TimeZoneNameStyle = "short" | "long" | "shortOffset" | "longOffset" | "shortGeneric" | "longGeneric";
 export interface FormatTimeZoneNameOptions {

package/dist/zoned/format/formatZonedDateTime.d.ts

@@ -1,3 +1,4 @@
+import type { DateTimeFormatOptions } from "../../types/index.js";
 /**
  * Format a zoned ISO 8601 datetime string using the Intl.DateTimeFormat implementation.
  *
@@ -14,4 +15,4 @@
  * @example formatZonedDateTime("2024-02-29T12:34:56.789+00:00[UTC]", "en-GB", { dateStyle: "short", timeStyle: "short" }) // "29/02/2024, 12:34"
  * @example formatZonedDateTime("invalid", "en-US") // "" (invalid input)
  */
-export declare function formatZonedDateTime(value: string, locale?: string, options?: Intl.DateTimeFormatOptions): string;
+export declare function formatZonedDateTime(value: string, locale?: string, options?: DateTimeFormatOptions): string;

package/dist/zoned/format/formatZonedRange.d.ts

@@ -1,3 +1,4 @@
+import type { DateTimeFormatOptions } from "../../types/index.js";
 /**
  * Format a zoned datetime range using the Temporal Intl.DateTimeFormat formatRange API.
  *
@@ -15,4 +16,4 @@
  * @example formatZonedRange("2024-02-29T12:00:00.000+00:00[UTC]", "2024-02-29T14:00:00.000+00:00[UTC]", "en-GB", { dateStyle: "short", timeStyle: "short" }) // "29/02/2024, 12:00 – 14:00"
  * @example formatZonedRange("invalid", "2024-02-29T14:00:00.000+00:00[UTC]", "en-US") // "" (invalid input)
  */
-export declare function formatZonedRange(from: string, to: string, locale?: string, options?: Intl.DateTimeFormatOptions): string;
+export declare function formatZonedRange(from: string, to: string, locale?: string, options?: DateTimeFormatOptions): string;

package/dist/zoned/format/formatZonedToParts.d.ts

@@ -1,3 +1,4 @@
+import type { DateTimeFormatOptions } from "../../types/index.js";
 /**
  * Return the locale-formatted parts of a ZonedDateTime.
  *
@@ -23,7 +24,7 @@
  * @example formatZonedToParts("2024-03-15T14:30:00.000-04:00[America/New_York]", "en-US", { timeZoneName: "longOffset" }) // includes { type: "timeZoneName", value: "GMT-4" }
  * @example formatZonedToParts("invalid", "en-US") // []
  */
-export declare function formatZonedToParts(value: string, locale?: string, options?: Intl.DateTimeFormatOptions): Array<{
+export declare function formatZonedToParts(value: string, locale?: string, options?: DateTimeFormatOptions): Array<{
     type: string;
     value: string;
 }>;

package/dist/zoned/get/getDstTransitions.d.ts

@@ -1,6 +1,22 @@
 /**
- * A single DST transition instant, with the UTC offset in effect immediately
- * before and after the change.
+ * A single DST transition instant: the UTC instant of an offset change plus the
+ * offset in effect immediately before and after it.
+ *
+ * @remarks Members:
+ *
+ * | Member | Type | Description |
+ * | --- | --- | --- |
+ * | `instant` | `string` | UTC instant of the offset change, ISO 8601 ending in `Z` (e.g. `2024-03-10T07:00:00Z`). |
+ * | `offsetBefore` | `string` | UTC offset in effect immediately before the transition (e.g. `-05:00`). |
+ * | `offsetAfter` | `string` | UTC offset in effect immediately after the transition (e.g. `-04:00`). |
+ *
+ * @example
+ * import { DstTransition } from "@northguild/gmt/zoned";
+ * const t: DstTransition = {
+ *   instant: "2024-03-10T07:00:00Z",
+ *   offsetBefore: "-05:00",
+ *   offsetAfter: "-04:00",
+ * };
  */
 export interface DstTransition {
     instant: string;

package/dist/zoned/get/getZonedNowUnit.d.ts

@@ -1,3 +1,27 @@
+/**
+ * Units extractable from the current time in a specific IANA timeZone, as
+ * consumed by `getZonedNowUnit`.
+ *
+ * @remarks Members:
+ *
+ * | Member | Description |
+ * | --- | --- |
+ * | `year` | Full calendar year (e.g. `2024`), no padding. |
+ * | `month` | 1–12, zero-padded to 2 digits (e.g. `02`). |
+ * | `week` | Week-of-year from `parseWeekFromDate`, 1–53. |
+ * | `day` | Day of month 1–31, zero-padded (e.g. `15`). |
+ * | `dayOfWeek` | 1 (Mon)–7 (Sun). |
+ * | `hour` | 0–23, zero-padded. |
+ * | `minute` | 0–59, zero-padded. |
+ * | `second` | 0–59, zero-padded. |
+ * | `millisecond` | 0–999, zero-padded to 3. |
+ * | `microsecond` | Sub-millisecond microseconds (0–999999). |
+ * | `nanosecond` | Sub-millisecond nanoseconds (0–999999999). |
+ *
+ * @example
+ * import { ZonedNowUnit } from "@northguild/gmt/zoned";
+ * const u: ZonedNowUnit = "hour";
+ */
 export type ZonedNowUnit = "year" | "month" | "week" | "day" | "dayOfWeek" | "hour" | "minute" | "second" | "millisecond" | "microsecond" | "nanosecond";
 /**
  * Return the requested current unit value for the specified IANA timeZone.

package/dist/zoned/interval/intervalDifferenceZoned.d.ts

@@ -2,8 +2,8 @@
  * Return the portion(s) of interval A not covered by interval B.
  *
  * - Uses `Temporal.Instant.compare` for comparison (via `.toInstant()`).
- * - Returns `[]` when B fully covers A.
- * - Returns `[{ start, end }]` when B overlaps one edge of A (or equals A).
+ * - Returns `[]` when B fully covers A (this includes B being identical to A).
+ * - Returns `[{ start, end }]` when B overlaps exactly one edge of A.
  * - Returns `[{ start, end }, { start, end }]` when B is fully inside A with gaps on both sides.
  * - Returns `[]` if either interval is invalid (`start > end`).
  * - Returns `[]` on invalid input (wrong type, malformed strings, leap seconds).
@@ -28,7 +28,7 @@
  * @param bEnd ISO 8601 zoned datetime string for the second interval end
  * @returns array of `{ start, end }` records representing A minus B, or `[]` on invalid input
  *
- * @example intervalDifferenceZoned("2024-01-01T09:00:00+00:00[UTC]", "2024-12-31T17:00:00+00:00[UTC]", "2024-06-01T12:00:00+00:00[UTC]", "2024-07-01T13:00:00+00:00[UTC]") // [{ start: "2024-01-01T09:00:00+00:00[UTC]", end: "2024-05-31T17:00:00+00:00[UTC]" }, { start: "2024-07-01T13:00:01+00:00[UTC]", end: "2024-12-31T17:00:00+00:00[UTC]" }]
+ * @example intervalDifferenceZoned("2024-01-01T09:00:00+00:00[UTC]", "2024-12-31T17:00:00+00:00[UTC]", "2024-06-01T12:00:00+00:00[UTC]", "2024-07-01T13:00:00+00:00[UTC]") // [{ start: "2024-01-01T09:00:00+00:00[UTC]", end: "2024-06-01T11:59:59.999999999+00:00[UTC]" }, { start: "2024-07-01T13:00:00.000000001+00:00[UTC]", end: "2024-12-31T17:00:00+00:00[UTC]" }]
  * @example intervalDifferenceZoned("2024-01-01T09:00:00+00:00[UTC]", "2024-12-31T17:00:00+00:00[UTC]", "2024-01-01T09:00:00+00:00[UTC]", "2024-12-31T17:00:00+00:00[UTC]") // []
  * @example intervalDifferenceZoned("invalid", "2024-12-31T17:00:00+00:00[UTC]", "2024-06-01T12:00:00+00:00[UTC]", "2024-07-01T13:00:00+00:00[UTC]") // []
  */

package/dist/zoned/interval/intervalDifferenceZoned.js

@@ -5,8 +5,8 @@ import { isValidCalendarZonedDateTime } from "../validate/index.js";
  * Return the portion(s) of interval A not covered by interval B.
  *
  * - Uses `Temporal.Instant.compare` for comparison (via `.toInstant()`).
- * - Returns `[]` when B fully covers A.
- * - Returns `[{ start, end }]` when B overlaps one edge of A (or equals A).
+ * - Returns `[]` when B fully covers A (this includes B being identical to A).
+ * - Returns `[{ start, end }]` when B overlaps exactly one edge of A.
  * - Returns `[{ start, end }, { start, end }]` when B is fully inside A with gaps on both sides.
  * - Returns `[]` if either interval is invalid (`start > end`).
  * - Returns `[]` on invalid input (wrong type, malformed strings, leap seconds).
@@ -31,7 +31,7 @@ import { isValidCalendarZonedDateTime } from "../validate/index.js";
  * @param bEnd ISO 8601 zoned datetime string for the second interval end
  * @returns array of `{ start, end }` records representing A minus B, or `[]` on invalid input
  *
- * @example intervalDifferenceZoned("2024-01-01T09:00:00+00:00[UTC]", "2024-12-31T17:00:00+00:00[UTC]", "2024-06-01T12:00:00+00:00[UTC]", "2024-07-01T13:00:00+00:00[UTC]") // [{ start: "2024-01-01T09:00:00+00:00[UTC]", end: "2024-05-31T17:00:00+00:00[UTC]" }, { start: "2024-07-01T13:00:01+00:00[UTC]", end: "2024-12-31T17:00:00+00:00[UTC]" }]
+ * @example intervalDifferenceZoned("2024-01-01T09:00:00+00:00[UTC]", "2024-12-31T17:00:00+00:00[UTC]", "2024-06-01T12:00:00+00:00[UTC]", "2024-07-01T13:00:00+00:00[UTC]") // [{ start: "2024-01-01T09:00:00+00:00[UTC]", end: "2024-06-01T11:59:59.999999999+00:00[UTC]" }, { start: "2024-07-01T13:00:00.000000001+00:00[UTC]", end: "2024-12-31T17:00:00+00:00[UTC]" }]
  * @example intervalDifferenceZoned("2024-01-01T09:00:00+00:00[UTC]", "2024-12-31T17:00:00+00:00[UTC]", "2024-01-01T09:00:00+00:00[UTC]", "2024-12-31T17:00:00+00:00[UTC]") // []
  * @example intervalDifferenceZoned("invalid", "2024-12-31T17:00:00+00:00[UTC]", "2024-06-01T12:00:00+00:00[UTC]", "2024-07-01T13:00:00+00:00[UTC]") // []
  */

package/dist/zoned/interval/intervalXorZoned.d.ts

@@ -3,8 +3,10 @@
  *
  * - Uses `Temporal.Instant.compare` for comparison (via `.toInstant()`).
  * - Returns `[]` when intervals are identical or both invalid.
- * - Returns `[{ start, end }]` when one interval fully contains the other.
- * - Returns `[{ start, end }, { start, end }]` when intervals partially overlap.
+ * - Returns `[{ start, end }]` when the intervals share exactly one boundary — one starts (or
+ *   ends) precisely where the other ends (or starts), so only one remainder piece exists.
+ * - Returns `[{ start, end }, { start, end }]` when intervals partially overlap, and also when
+ *   one interval strictly contains the other (the piece before B and the piece after B).
  * - Returns `[]` if either interval is invalid (`start > end`).
  * - Returns `[]` on invalid input (wrong type, malformed strings, leap seconds).
  * - Accepts GMT calendar-annotated zoned strings (as produced by `convertZonedToCalendar`) as
@@ -28,8 +30,8 @@
  * @param bEnd ISO 8601 zoned datetime string for the second interval end
  * @returns array of `{ start, end }` records representing the symmetric difference, or `[]` on invalid input
  *
- * @example intervalXorZoned("2024-01-01T09:00:00+00:00[UTC]", "2024-06-30T12:00:00+00:00[UTC]", "2024-04-01T11:00:00+00:00[UTC]", "2024-12-31T17:00:00+00:00[UTC]") // [{ start: "2024-01-01T09:00:00+00:00[UTC]", end: "2024-03-31T17:00:00+00:00[UTC]" }, { start: "2024-06-30T12:00:01+00:00[UTC]", end: "2024-12-31T17:00:00+00:00[UTC]" }]
- * @example intervalXorZoned("2024-01-01T09:00:00+00:00[UTC]", "2024-12-31T17:00:00+00:00[UTC]", "2024-04-01T11:00:00+00:00[UTC]", "2024-06-30T12:00:00+00:00[UTC]") // [{ start: "2024-01-01T09:00:00+00:00[UTC]", end: "2024-03-31T17:00:00+00:00[UTC]" }, { start: "2024-06-30T12:00:01+00:00[UTC]", end: "2024-12-31T17:00:00+00:00[UTC]" }]
+ * @example intervalXorZoned("2024-01-01T09:00:00+00:00[UTC]", "2024-06-30T12:00:00+00:00[UTC]", "2024-04-01T11:00:00+00:00[UTC]", "2024-12-31T17:00:00+00:00[UTC]") // partial overlap — [{ start: "2024-01-01T09:00:00+00:00[UTC]", end: "2024-04-01T10:59:59.999999999+00:00[UTC]" }, { start: "2024-06-30T12:00:00.000000001+00:00[UTC]", end: "2024-12-31T17:00:00+00:00[UTC]" }]
+ * @example intervalXorZoned("2024-01-01T09:00:00+00:00[UTC]", "2024-12-31T17:00:00+00:00[UTC]", "2024-02-01T08:00:00+00:00[UTC]", "2024-03-01T10:00:00+00:00[UTC]") // B strictly inside A — two remainder pieces — [{ start: "2024-01-01T09:00:00+00:00[UTC]", end: "2024-02-01T07:59:59.999999999+00:00[UTC]" }, { start: "2024-03-01T10:00:00.000000001+00:00[UTC]", end: "2024-12-31T17:00:00+00:00[UTC]" }]
  * @example intervalXorZoned("2024-01-01T09:00:00+00:00[UTC]", "2024-12-31T17:00:00+00:00[UTC]", "2024-01-01T09:00:00+00:00[UTC]", "2024-12-31T17:00:00+00:00[UTC]") // []
  * @example intervalXorZoned("invalid", "2024-06-30T12:00:00+00:00[UTC]", "2024-07-01T13:00:00+00:00[UTC]", "2024-12-31T17:00:00+00:00[UTC]") // []
  */

package/dist/zoned/interval/intervalXorZoned.js

@@ -6,8 +6,10 @@ import { isValidCalendarZonedDateTime } from "../validate/index.js";
  *
  * - Uses `Temporal.Instant.compare` for comparison (via `.toInstant()`).
  * - Returns `[]` when intervals are identical or both invalid.
- * - Returns `[{ start, end }]` when one interval fully contains the other.
- * - Returns `[{ start, end }, { start, end }]` when intervals partially overlap.
+ * - Returns `[{ start, end }]` when the intervals share exactly one boundary — one starts (or
+ *   ends) precisely where the other ends (or starts), so only one remainder piece exists.
+ * - Returns `[{ start, end }, { start, end }]` when intervals partially overlap, and also when
+ *   one interval strictly contains the other (the piece before B and the piece after B).
  * - Returns `[]` if either interval is invalid (`start > end`).
  * - Returns `[]` on invalid input (wrong type, malformed strings, leap seconds).
  * - Accepts GMT calendar-annotated zoned strings (as produced by `convertZonedToCalendar`) as
@@ -31,8 +33,8 @@ import { isValidCalendarZonedDateTime } from "../validate/index.js";
  * @param bEnd ISO 8601 zoned datetime string for the second interval end
  * @returns array of `{ start, end }` records representing the symmetric difference, or `[]` on invalid input
  *
- * @example intervalXorZoned("2024-01-01T09:00:00+00:00[UTC]", "2024-06-30T12:00:00+00:00[UTC]", "2024-04-01T11:00:00+00:00[UTC]", "2024-12-31T17:00:00+00:00[UTC]") // [{ start: "2024-01-01T09:00:00+00:00[UTC]", end: "2024-03-31T17:00:00+00:00[UTC]" }, { start: "2024-06-30T12:00:01+00:00[UTC]", end: "2024-12-31T17:00:00+00:00[UTC]" }]
- * @example intervalXorZoned("2024-01-01T09:00:00+00:00[UTC]", "2024-12-31T17:00:00+00:00[UTC]", "2024-04-01T11:00:00+00:00[UTC]", "2024-06-30T12:00:00+00:00[UTC]") // [{ start: "2024-01-01T09:00:00+00:00[UTC]", end: "2024-03-31T17:00:00+00:00[UTC]" }, { start: "2024-06-30T12:00:01+00:00[UTC]", end: "2024-12-31T17:00:00+00:00[UTC]" }]
+ * @example intervalXorZoned("2024-01-01T09:00:00+00:00[UTC]", "2024-06-30T12:00:00+00:00[UTC]", "2024-04-01T11:00:00+00:00[UTC]", "2024-12-31T17:00:00+00:00[UTC]") // partial overlap — [{ start: "2024-01-01T09:00:00+00:00[UTC]", end: "2024-04-01T10:59:59.999999999+00:00[UTC]" }, { start: "2024-06-30T12:00:00.000000001+00:00[UTC]", end: "2024-12-31T17:00:00+00:00[UTC]" }]
+ * @example intervalXorZoned("2024-01-01T09:00:00+00:00[UTC]", "2024-12-31T17:00:00+00:00[UTC]", "2024-02-01T08:00:00+00:00[UTC]", "2024-03-01T10:00:00+00:00[UTC]") // B strictly inside A — two remainder pieces — [{ start: "2024-01-01T09:00:00+00:00[UTC]", end: "2024-02-01T07:59:59.999999999+00:00[UTC]" }, { start: "2024-03-01T10:00:00.000000001+00:00[UTC]", end: "2024-12-31T17:00:00+00:00[UTC]" }]
  * @example intervalXorZoned("2024-01-01T09:00:00+00:00[UTC]", "2024-12-31T17:00:00+00:00[UTC]", "2024-01-01T09:00:00+00:00[UTC]", "2024-12-31T17:00:00+00:00[UTC]") // []
  * @example intervalXorZoned("invalid", "2024-06-30T12:00:00+00:00[UTC]", "2024-07-01T13:00:00+00:00[UTC]", "2024-12-31T17:00:00+00:00[UTC]") // []
  */

package/dist/zoned/parse/getZonedOffsetAs.d.ts

@@ -1,5 +1,16 @@
 /**
  * Unit a zoned value's UTC offset can be read as via `getZonedOffsetAs`.
+ *
+ * @remarks Members:
+ *
+ * | Member | Description |
+ * | --- | --- |
+ * | `minutes` | Whole-minute offset (e.g. `-240` for `-04:00`). |
+ * | `nanoseconds` | Raw `offsetNanoseconds` from Temporal (e.g. `-14400000000000`). |
+ *
+ * @example
+ * import { getZonedOffsetAs } from "@northguild/gmt/zoned";
+ * getZonedOffsetAs("2024-07-15T12:00:00-04:00[America/New_York]", "minutes");
  */
 export type ZonedOffsetUnit = "minutes" | "nanoseconds";
 /**

package/dist/zoned/parse/parseUnitFromZoned.d.ts

@@ -1,3 +1,27 @@
+/**
+ * Units supported by `parseUnitFromZoned` when extracting a value from a zoned
+ * ISO string. Includes `timeZone` for reading the zone identifier.
+ *
+ * @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. |
+ * | `nanosecond` | Zero-padded 3. |
+ * | `timeZone` | IANA timeZone identifier string. |
+ *
+ * @example
+ * import { ZonedParseUnit } from "@northguild/gmt/zoned";
+ * const u: ZonedParseUnit = "month";
+ */
 export type ZonedParseUnit = "year" | "month" | "week" | "day" | "dayOfWeek" | "hour" | "minute" | "second" | "millisecond" | "nanosecond" | "timeZone";
 /**
  * Return the requested unit value from an ISO 8601 zoned datetime string.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@northguild/gmt",
-  "version": "1.14.2",
+  "version": "1.15.0",
   "description": "Temporal-based date and time utilities with timezone support and polyfill integration",
   "keywords": [
     "date",
@@ -11,7 +11,7 @@
     "time",
     "timezone"
   ],
-  "homepage": "https://github.com/northguild/gmt#readme",
+  "homepage": "https://gmt-dox.northguild.workers.dev",
   "bugs": {
     "url": "https://github.com/northguild/gmt/issues"
   },
@@ -34,7 +34,11 @@
   "files": [
     "dist",
     "LICENSE",
-    "skills"
+    "README.md",
+    "skills/gmt-basics",
+    "skills/gmt-arithmetic",
+    "skills/gmt-timezone",
+    "skills/gmt-integration"
   ],
   "type": "module",
   "main": "./dist/index.js",
@@ -67,8 +71,13 @@
       "default": "./dist/regex/index.js"
     },
     "./regex/*": {
-      "types": "./dist/regex/*.d.ts",
-      "default": "./dist/regex/*.js"
+      "types": "./dist/regex/*/index.d.ts",
+      "default": "./dist/regex/*/index.js"
+    },
+    "./regex/*/*": null,
+    "./types": {
+      "types": "./dist/types/index.d.ts",
+      "default": "./dist/types/index.js"
     },
     "./unix": {
       "types": "./dist/unix/index.d.ts",
@@ -87,7 +96,16 @@
       "types": "./dist/utc/*/index.d.ts",
       "default": "./dist/utc/*/index.js"
     },
-    "./utc/*/*": null
+    "./utc/*/*": null,
+    "./duration": {
+      "types": "./dist/duration/index.d.ts",
+      "default": "./dist/duration/index.js"
+    },
+    "./duration/*": {
+      "types": "./dist/duration/*/index.d.ts",
+      "default": "./dist/duration/*/index.js"
+    },
+    "./duration/*/*": null
   },
   "publishConfig": {
     "access": "public",
@@ -97,7 +115,7 @@
     "@js-temporal/polyfill": "^0.5.1"
   },
   "devDependencies": {
-    "@tanstack/intent": "^0.3.6",
+    "@tanstack/intent": "^0.3.8",
     "oxfmt": "^0.62.0",
     "oxlint": "^1.0.0",
     "@northguild/gmt-oxlint": "1.1.5"

package/skills/gmt-arithmetic/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: gmt-arithmetic
+description: >
+  Date arithmetic — add/subtract duration objects, diff values, clamp/closest,
+  ISO 8601 duration strings, and interval range math (contain, overlap, union,
+  split, count boundaries). Reads the installed package README.md and source
+  JSDoc for API details; this skill is a routing pointer, not an API dump.
+sources:
+  - 'northguild/gmt:README.md'
+  - 'northguild/gmt:packages/gmt/src/plain/calculate/index.ts'
+  - 'northguild/gmt:packages/gmt/src/duration/index.ts'
+  - 'northguild/gmt:packages/gmt/src/plain/interval/index.ts'
+  - 'northguild/gmt:packages/gmt/src/zoned/interval/index.ts'
+  - 'northguild/gmt:packages/gmt/src/unix/interval/index.ts'
+  - 'northguild/gmt:packages/gmt/src/utc/interval/index.ts'
+metadata:
+  type: core
+  library: '@northguild/gmt'
+  library_version: '1.15.0'
+---
+
+# GMT Arithmetic
+
+Use this skill when the task involves adding, subtracting, diffing, clamping,
+or doing range math over date/time values — including ISO 8601 duration strings
+and full interval set operations.
+
+## When to load
+
+- The user wants to move a date forward/backward by a quantity.
+- The user needs the difference between two dates as a number or a duration
+  string.
+- The user wants to restrict a value to a min/max range, or find the nearest
+  candidate.
+- The user needs range math: "do these overlap?", "merge these", "split this
+  into n parts".
+
+## Core rules
+
+1. **`add*` takes a `{ unit: number }` object, not an ISO duration string.**
+   `addDate("2024-03-15", { days: 5 })` works; `addDate("2024-03-15", "P5D")`
+   returns `""`. Use `diffDateAsDuration` / `addDuration` for duration strings.
+2. **`overflow`** defaults to `"constrain"` (clamps to a valid date). Pass
+   `{ overflow: "reject" }` to get the `""` sentinel instead of a clamp.
+3. **Calendar units need `relativeTo`.** `durationAs`, `normalizeDuration`, and
+   `compareDurations` return `null`/`""` for year/month/week arithmetic without
+   a `relativeTo` anchor — a month is not a fixed length.
+4. **Read the README.** This skill is a routing pointer. For full option shapes,
+   locale matrices, and code examples, read the installed package's `README.md`
+   and the source JSDoc of the function you intend to call.
+
+## Key functions
+
+- **Point arithmetic**: `addDate`, `addDateTime`, `addTime`, `subtractTime`,
+  `addBusinessDays`, `subtractBusinessDays`, `cycleDate`, `setDate`
+- **Diffs**: `diffDate`, `diffDateTime`, `diffTime` (+ `diffZoned`,
+  `diffUnix`, `diffUtc` in their namespaces)
+- **Bounds**: `clampDate`, `closestDateTo`, `startOfDate`, `endOfDate`,
+  `startOfQuarterForDate`, `getLocaleStartOfWeek`
+- **Durations (ISO 8601)**: `isValidDuration`, `parseDuration`, `addDuration`,
+  `subtractDuration`, `normalizeDuration`, `durationAs`, `formatDuration`,
+  `negateDuration`, `absDuration`, `compareDurations`, `getDurationUnit`,
+  `getDurationSign`
+- **Diff-to-duration bridge**: `diffDateAsDuration`,
+  `diffZonedAsDuration`, `diffUnixAsDuration`, `diffUtcAsDuration`
+- **Intervals (range math)**: `isValidDateInterval`, `intervalContainsDate`,
+  `intervalsOverlapDate`, `intervalIntersectionDate`, `intervalUnionDate`,
+  `intervalDifferenceDate`, `intervalXorDate`, `intervalFromDurationDate`,
+  `splitIntervalByUnitDate`, `intervalCountDate`, `intervalLengthDate`,
+  `intervalDivideEquallyDate`, `mergeIntervalsDate`
+
+## Namespace selection
+
+- `plain/*` — timezone-free dates, times, datetimes
+- `zoned/*` — IANA-timezone-aware (see `gmt-timezone` skill for disambiguation)
+- `unix/*` — epoch seconds/milliseconds
+- `utc/*` — UTC instants (`"2024-03-15T14:30:45Z"`)
+- `duration/*` — ISO 8601 duration strings
+
+## References
+
+- [README — Quick Start](README.md)
+- [Interval function reference](/reference/plain)