@northguild/gmt 1.14.2

package/dist/regex/leap-second.d.ts

@@ -0,0 +1 @@
+export declare const leapSecond: RegExp;

package/dist/regex/leap-second.js

@@ -0,0 +1,2 @@
+// ISO 8601 leap second pattern (second = 60)
+export const leapSecond = /T\d{2}:\d{2}:60(?:[.,]\d+)?(?:[-+Zz[])/;

package/dist/regex/rfc-2822.d.ts

@@ -0,0 +1 @@
+export declare const rfc2822DateTime: RegExp;

package/dist/regex/rfc-2822.js

@@ -0,0 +1,9 @@
+// RFC 5322 §3.3 date-time grammar (obsoletes RFC 2822, same date-time shape).
+// English day/month names are mandated by the spec regardless of locale — see
+// `internal/englishCalendarNames.ts`. Day is `1*2DIGIT` per the formal
+// grammar, so single-digit days are valid on input even though GMT's own
+// formatter always emits the zero-padded 2-digit form. `zone` accepts a
+// numeric offset or one of the obsolete named zones RFC 5322 §4.3 lists
+// (UT/GMT plus the eight North American zones); any other obs-zone letter is
+// unrecognized and treated as invalid rather than guessed at.
+export const rfc2822DateTime = /^(?:(Mon|Tue|Wed|Thu|Fri|Sat|Sun), )?(\d{1,2}) (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) (\d{4}) (\d{2}):(\d{2})(?::(\d{2}))? (UT|GMT|EST|EDT|CST|CDT|MST|MDT|PST|PDT|[+-]\d{4})$/;

package/dist/regex/rfc-3339.d.ts

@@ -0,0 +1 @@
+export declare const rfc3339DateTime: RegExp;

package/dist/regex/rfc-3339.js

@@ -0,0 +1,7 @@
+// RFC 3339 §5.6 date-time — the same field grammar as ISO 8601 but with a
+// *mandatory* offset (Z or ±HH:MM) and a date/time separator that may be
+// "T", "t", or " ". GMT's own zoned strings additionally carry a bracketed
+// IANA zone annotation ("...+00:00[UTC]") that RFC 3339 does not permit,
+// which is why this needs its own regex rather than reusing `plainDateTime`
+// or `zoned`-style patterns (see roadmap J13's RFC 3339 go/no-go decision).
+export const rfc3339DateTime = /^(\d{4})-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])[Tt ](0[0-9]|1[0-9]|2[0-3]):([0-5][0-9]):([0-5][0-9])(\.[0-9]{1,9})?(Z|z|[+-][0-9]{2}:[0-9]{2})$/;

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

@@ -0,0 +1 @@
+export declare const sqlDateTime: RegExp;

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

@@ -0,0 +1,7 @@
+// ANSI SQL / ODBC timestamp literal: space-separated (never "T"), always
+// zero-padded (unlike RFC 2822's lenient 1-2 digit day), with an optional
+// fractional-seconds component. This checks *shape* only — `parseSql` still
+// hands the extracted string to `Temporal.PlainDateTime.from` for real
+// calendar validation, same as GMT's other `isValid*` + `Temporal.*.from`
+// pairs.
+export const sqlDateTime = /^(?:\d{4}|[+-]\d{6})-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01]) (0[0-9]|1[0-9]|2[0-3]):[0-5][0-9](?::[0-5][0-9](?:\.[0-9]{1,9})?)?$/;

package/dist/regex/time-zone-like.d.ts

@@ -0,0 +1 @@
+export declare const timeZoneLike: RegExp;

package/dist/regex/time-zone-like.js

@@ -0,0 +1 @@
+export const timeZoneLike = /^(?:UTC|GMT|[A-Za-z_+-]+(?:\/[A-Za-z0-9_+-]+)+)$/;

package/dist/regex/time.d.ts

@@ -0,0 +1,6 @@
+export declare const hour: RegExp;
+export declare const minute: RegExp;
+export declare const second: RegExp;
+export declare const fractionalSecond: RegExp;
+export declare const millisecond: RegExp;
+export declare const plainTime: RegExp;

package/dist/regex/time.js

@@ -0,0 +1,9 @@
+// regex patterns exported for usage
+export const hour = /^(0[0-9]|1[0-9]|2[0-3])$/;
+export const minute = /^[0-5][0-9]$/;
+export const second = /^[0-5][0-9]$/;
+export const fractionalSecond = /^[0-9]{1,9}$/;
+// Backward-compatible alias; prefer fractionalSecond for new usage.
+export const millisecond = fractionalSecond;
+// ISO 8601 local time (extended): HH:mm[:ss[.fffffffff]]
+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

@@ -0,0 +1,2 @@
+export declare const unixSeconds: RegExp;
+export declare const unixMilliseconds: RegExp;

package/dist/regex/unix.js

@@ -0,0 +1,2 @@
+export const unixSeconds = /^\d{10}$/;
+export const unixMilliseconds = /^\d{13}$/;

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

@@ -0,0 +1 @@
+export declare const utcDateTime: RegExp;

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

@@ -0,0 +1,2 @@
+// ISO 8601 UTC datetime: <date>T<time>Z with optional fractional seconds
+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-system.d.ts

@@ -0,0 +1 @@
+export type CalendarSystem = "gregorian" | "hebrew" | "islamic-civil" | "islamic-tabular" | "islamic-umalqura" | "japanese" | "buddhist" | "taiwan" | "persian" | "indian" | "ethiopic" | "ethiopic-amete-alem" | "coptic";

package/dist/types/date-cycle-field.d.ts

@@ -0,0 +1 @@
+export type DateCycleField = "year" | "month" | "day";

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

@@ -0,0 +1,2 @@
+import type { Temporal } from "@js-temporal/polyfill";
+export type DateDurationUnit = keyof Pick<Temporal.DurationLike, "years" | "months" | "weeks" | "days">;

package/dist/types/date-time-cycle-field.d.ts

@@ -0,0 +1,3 @@
+import type { DateCycleField } from "./date-cycle-field.js";
+import type { TimeCycleField } from "./time-cycle-field.js";
+export type DateTimeCycleField = DateCycleField | TimeCycleField;

package/dist/types/date-time-duration-units.d.ts

@@ -0,0 +1,2 @@
+import type { Temporal } from "@js-temporal/polyfill";
+export type DateTimeDurationUnit = keyof Temporal.DurationLike;

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

@@ -0,0 +1,2 @@
+import type { Temporal } from "@js-temporal/polyfill";
+export type DateTimeUnit = Temporal.TimeUnit | Temporal.DateUnit;

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

@@ -0,0 +1,2 @@
+import type { Temporal } from "@js-temporal/polyfill";
+export type DateUnit = Temporal.DateUnit;

package/dist/types/disambiguation.d.ts

@@ -0,0 +1,2 @@
+import type { Temporal } from "@js-temporal/polyfill";
+export type Disambiguation = Temporal.ToInstantOptions["disambiguation"];

package/dist/types/duration-relative-to.d.ts

@@ -0,0 +1,2 @@
+import type { Temporal } from "@js-temporal/polyfill";
+export type DurationRelativeTo = Temporal.PlainDateTime | Temporal.ZonedDateTime | Temporal.PlainDateTimeLike | Temporal.ZonedDateTimeLike | string;

package/dist/types/duration-string-options.d.ts

@@ -0,0 +1,6 @@
+import type { Temporal } from "@js-temporal/polyfill";
+export type DurationStringOptions = {
+    toStringSmallestUnit?: Temporal.ToStringPrecisionOptions["smallestUnit"];
+    fractionalSecondDigits?: Temporal.ToStringPrecisionOptions["fractionalSecondDigits"];
+    toStringRoundingMode?: Temporal.ToStringPrecisionOptions["roundingMode"];
+};

package/dist/types/fractional-digit.d.ts

@@ -0,0 +1 @@
+export type FractionalDigit = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | "auto";

package/dist/types/index.d.ts

@@ -0,0 +1,18 @@
+export * from "./calendar-system.js";
+export * from "./date-cycle-field.js";
+export * from "./date-duration-unit.js";
+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 "./disambiguation.js";
+export * from "./duration-relative-to.js";
+export * from "./duration-string-options.js";
+export * from "./fractional-digit.js";
+export * from "./offset.js";
+export * from "./overflow.js";
+export * from "./relative-rounding-method.js";
+export * from "./rounding-options.js";
+export * from "./time-cycle-field.js";
+export * from "./time-duration-unit.js";
+export * from "./time-unit.js";

package/dist/types/index.js

@@ -0,0 +1,18 @@
+export * from "./calendar-system.js";
+export * from "./date-cycle-field.js";
+export * from "./date-duration-unit.js";
+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 "./disambiguation.js";
+export * from "./duration-relative-to.js";
+export * from "./duration-string-options.js";
+export * from "./fractional-digit.js";
+export * from "./offset.js";
+export * from "./overflow.js";
+export * from "./relative-rounding-method.js";
+export * from "./rounding-options.js";
+export * from "./time-cycle-field.js";
+export * from "./time-duration-unit.js";
+export * from "./time-unit.js";

package/dist/types/offset.d.ts

@@ -0,0 +1,2 @@
+import type { Temporal } from "@js-temporal/polyfill";
+export type Offset = Temporal.ZonedDateTimeAssignmentOptions["offset"];

package/dist/types/overflow.d.ts

@@ -0,0 +1,2 @@
+import type { Temporal } from "@js-temporal/polyfill";
+export type Overflow = Temporal.ArithmeticOptions["overflow"];

package/dist/types/relative-rounding-method.d.ts

@@ -0,0 +1 @@
+export type RelativeRoundingMethod = "floor" | "ceil" | "round";

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

@@ -0,0 +1,6 @@
+import type { Temporal } from "@js-temporal/polyfill";
+export type RoundingOptions<Unit extends Temporal.DateTimeUnit> = {
+    smallestUnit?: Temporal.SmallestUnit<Unit>;
+    roundingIncrement?: number;
+    roundingMode?: Temporal.RoundingMode;
+};

package/dist/types/time-cycle-field.d.ts

@@ -0,0 +1 @@
+export type TimeCycleField = "hour" | "minute" | "second" | "millisecond" | "microsecond" | "nanosecond";

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

@@ -0,0 +1,2 @@
+import type { Temporal } from "@js-temporal/polyfill";
+export type TimeDurationUnit = keyof Pick<Temporal.DurationLike, "hours" | "minutes" | "seconds" | "milliseconds" | "microseconds" | "nanoseconds">;

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

@@ -0,0 +1,2 @@
+import type { Temporal } from "@js-temporal/polyfill";
+export type TimeUnit = Temporal.TimeUnit;

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

@@ -0,0 +1,25 @@
+import type { DateTimeDurationUnit, Overflow } from "../../types/index.js";
+/**
+ * Add a temporal amount to a Unix epoch value and return the resulting epoch.
+ *
+ * - Converts to ZonedDateTime, adds the duration, then converts back to epoch.
+ * - Validates duration units and values.
+ * - Returns null for invalid input.
+ *
+ * `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. adding 1 month
+ * to Jan 31: "constrain" clamps to Feb 29/28, "reject" throws (resulting in null).
+ *
+ * @param value Unix timestamp (number)
+ * @param units Partial<Record<DateTimeDurationUnit, number>> object specifying units to add
+ * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA), overflow ("constrain" | "reject")
+ * @returns Unix epoch number after addition, or null on invalid input
+ *
+ * @example addUnix(1706659200000, { days: 1 }) // 1706745600000
+ * @example addUnix(1706659200, { days: 1 }, { epochUnit: "seconds" }) // 1706745600
+ * @example addUnix(-86400000, { days: 1 }) // 0 (Dec 31 1969 + 1 day = Jan 1 1970)
+ */
+export declare function addUnix(value: number, units: Partial<Record<DateTimeDurationUnit, number>>, options?: {
+    epochUnit?: "seconds" | "milliseconds";
+    timeZone?: string;
+    overflow?: Overflow;
+}): number | null;

package/dist/unix/calculate/addUnix.js

@@ -0,0 +1,51 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidAmount, resolveOverflow } from "../../internal/index.js";
+import { isValidDateTimeDurationUnit } from "../../plain/validate/index.js";
+import { getSystemTimeZone } from "../../zoned/get/index.js";
+import { isValidTimeZone } from "../../zoned/validate/index.js";
+/**
+ * Add a temporal amount to a Unix epoch value and return the resulting epoch.
+ *
+ * - Converts to ZonedDateTime, adds the duration, then converts back to epoch.
+ * - Validates duration units and values.
+ * - Returns null for invalid input.
+ *
+ * `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. adding 1 month
+ * to Jan 31: "constrain" clamps to Feb 29/28, "reject" throws (resulting in null).
+ *
+ * @param value Unix timestamp (number)
+ * @param units Partial<Record<DateTimeDurationUnit, number>> object specifying units to add
+ * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA), overflow ("constrain" | "reject")
+ * @returns Unix epoch number after addition, or null on invalid input
+ *
+ * @example addUnix(1706659200000, { days: 1 }) // 1706745600000
+ * @example addUnix(1706659200, { days: 1 }, { epochUnit: "seconds" }) // 1706745600
+ * @example addUnix(-86400000, { days: 1 }) // 0 (Dec 31 1969 + 1 day = Jan 1 1970)
+ */
+export function addUnix(value, units, options) {
+    const epochUnit = options?.epochUnit ?? "milliseconds";
+    const timeZone = options?.timeZone ?? getSystemTimeZone();
+    const overflow = resolveOverflow(options?.overflow);
+    if (!timeZone || !isValidTimeZone(timeZone))
+        return null;
+    const validUnits = Object.keys(units).every(isValidDateTimeDurationUnit);
+    const validAmounts = Object.values(units).every(isValidAmount);
+    if (!validUnits || !validAmounts) {
+        return null;
+    }
+    if (!Number.isFinite(value) || !Number.isInteger(value)) {
+        return null;
+    }
+    try {
+        const instant = Temporal.Instant.fromEpochMilliseconds(epochUnit === "seconds" ? value * 1000 : value);
+        const zdt = instant.toZonedDateTimeISO(timeZone);
+        const result = zdt.add(units, { overflow });
+        const epoch = epochUnit === "seconds"
+            ? Math.floor(result.epochMilliseconds / 1000)
+            : result.epochMilliseconds;
+        return epoch;
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -0,0 +1,30 @@
+import { Temporal } from "@js-temporal/polyfill";
+import type { DateTimeDurationUnit, RoundingOptions } from "../../types/index.js";
+/**
+ * Return the difference between two Unix timestamps measured in the given unit.
+ *
+ * - Uses Temporal.Instant.until() to calculate the difference.
+ * - Supports single unit or array of units.
+ * - Returns null for invalid input.
+ *
+ * `smallestUnit`, `roundingIncrement`, and `roundingMode` control optional rounding of the result,
+ * per Temporal's DifferenceOptions — e.g. `{ smallestUnit: "hour", roundingMode: "halfExpand" }`
+ * rounds the difference to the nearest hour before extracting the requested unit.
+ * - When `units` is an array, `smallestUnit` must not be coarser than the largest unit in the
+ *   array (e.g. `["day", "hour"]` with `smallestUnit: "week"`) — this combination is rejected by
+ *   Temporal and returns null, same as other invalid input.
+ *
+ * @param value1 first Unix timestamp
+ * @param value2 second Unix timestamp
+ * @param units DateTimeDurationUnit | DateTimeDurationUnit[] to measure the difference
+ * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA), smallestUnit, roundingIncrement, roundingMode (Temporal.DifferenceOptions rounding controls)
+ * @returns numeric difference in the requested unit, or null on invalid input
+ *
+ * @example diffUnix(1706745600000, 1706659200000, "day") // 1
+ * @example diffUnix(1706745600, 1706659200, "day", { epochUnit: "seconds" }) // 1
+ * @example diffUnix(0, -86400000, "day") // 1 (Jan 1 1970 - Dec 31 1969 = 1 day)
+ */
+export declare function diffUnix(value1: number, value2: number, units: DateTimeDurationUnit | DateTimeDurationUnit[], options?: {
+    epochUnit?: "seconds" | "milliseconds";
+    timeZone?: string;
+} & RoundingOptions<Temporal.DateTimeUnit>): number | Record<DateTimeDurationUnit, number> | null;

package/dist/unix/calculate/diffUnix.js

@@ -0,0 +1,66 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidUnixEpochPair, resolveUnixTimeZone, } from "../../internal/resolveUnixTimeZone.js";
+import { getLargestDateTimeDurationUnit } from "../../plain/calculate/getLargestDateTimeDurationUnit.js";
+import { isValidDateTimeDurationUnit } from "../../plain/validate/index.js";
+/**
+ * Return the difference between two Unix timestamps measured in the given unit.
+ *
+ * - Uses Temporal.Instant.until() to calculate the difference.
+ * - Supports single unit or array of units.
+ * - Returns null for invalid input.
+ *
+ * `smallestUnit`, `roundingIncrement`, and `roundingMode` control optional rounding of the result,
+ * per Temporal's DifferenceOptions — e.g. `{ smallestUnit: "hour", roundingMode: "halfExpand" }`
+ * rounds the difference to the nearest hour before extracting the requested unit.
+ * - When `units` is an array, `smallestUnit` must not be coarser than the largest unit in the
+ *   array (e.g. `["day", "hour"]` with `smallestUnit: "week"`) — this combination is rejected by
+ *   Temporal and returns null, same as other invalid input.
+ *
+ * @param value1 first Unix timestamp
+ * @param value2 second Unix timestamp
+ * @param units DateTimeDurationUnit | DateTimeDurationUnit[] to measure the difference
+ * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA), smallestUnit, roundingIncrement, roundingMode (Temporal.DifferenceOptions rounding controls)
+ * @returns numeric difference in the requested unit, or null on invalid input
+ *
+ * @example diffUnix(1706745600000, 1706659200000, "day") // 1
+ * @example diffUnix(1706745600, 1706659200, "day", { epochUnit: "seconds" }) // 1
+ * @example diffUnix(0, -86400000, "day") // 1 (Jan 1 1970 - Dec 31 1969 = 1 day)
+ */
+export function diffUnix(value1, value2, units, options) {
+    const epochUnit = options?.epochUnit ?? "milliseconds";
+    const timeZone = resolveUnixTimeZone(options?.timeZone);
+    if (!timeZone)
+        return null;
+    const isSingleUnit = !Array.isArray(units);
+    const validUnits = isSingleUnit
+        ? isValidDateTimeDurationUnit(units)
+        : units.every(isValidDateTimeDurationUnit);
+    if (!validUnits) {
+        return null;
+    }
+    if (!isValidUnixEpochPair(value1, value2)) {
+        return null;
+    }
+    try {
+        const instant1 = Temporal.Instant.fromEpochMilliseconds(epochUnit === "seconds" ? value1 * 1000 : value1);
+        const instant2 = Temporal.Instant.fromEpochMilliseconds(epochUnit === "seconds" ? value2 * 1000 : value2);
+        const zdt1 = instant1.toZonedDateTimeISO(timeZone);
+        const zdt2 = instant2.toZonedDateTimeISO(timeZone);
+        const duration = zdt1.until(zdt2, {
+            largestUnit: isSingleUnit ? units : getLargestDateTimeDurationUnit(units),
+            smallestUnit: options?.smallestUnit,
+            roundingIncrement: options?.roundingIncrement,
+            roundingMode: options?.roundingMode,
+        });
+        if (isSingleUnit) {
+            return duration[units] ?? 0;
+        }
+        return units.reduce((result, unit) => {
+            result[unit] = duration[unit] ?? 0;
+            return result;
+        }, {});
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -0,0 +1,35 @@
+import { Temporal } from "@js-temporal/polyfill";
+import type { DateTimeDurationUnit, DurationStringOptions, RoundingOptions } from "../../types/index.js";
+/**
+ * Return the difference between two Unix timestamps as an ISO 8601 duration string,
+ * bridging to the `duration` namespace (see `parseDuration`, `normalizeDuration`).
+ *
+ * - Uses Temporal.Instant.until() with `largestUnit` set to `unit`, then `.toString()`.
+ * - Unlike `diffUnix`, `unit` is a single unit (not an array) — an ISO duration string
+ *   already expresses a full multi-unit breakdown via `largestUnit` alone, so there's no
+ *   array-of-units overload here.
+ * - Returns `""` for invalid input (negative diffs are valid and render with a leading `-`).
+ *
+ * `smallestUnit`, `roundingIncrement`, and `roundingMode` control optional rounding of the
+ * underlying difference before it's rendered, per Temporal's DifferenceOptions — same as
+ * `diffUnix`. `toStringSmallestUnit`, `fractionalSecondDigits`, and `toStringRoundingMode`
+ * control the precision of the rendered string itself, per Temporal's ToStringPrecisionOptions
+ * (mirroring `parseDuration`'s options) — kept separate from the `.until()` rounding options
+ * above because both option sets have colliding `smallestUnit`/`roundingMode` keys with
+ * different Temporal types.
+ *
+ * @param value1 first Unix timestamp
+ * @param value2 second Unix timestamp
+ * @param unit DateTimeDurationUnit to use as the duration's largestUnit
+ * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA), smallestUnit, roundingIncrement, roundingMode (.until() rounding); toStringSmallestUnit, fractionalSecondDigits, toStringRoundingMode (.toString() precision)
+ * @returns ISO 8601 duration string, or "" on invalid input
+ *
+ * @example diffUnixAsDuration(1706659200000, 1706745600000, "days") // "P1D"
+ * @example diffUnixAsDuration(1706745600000, 1706659200000, "days") // "-P1D"
+ * @example diffUnixAsDuration(1706659200, 1706745600, "days", { epochUnit: "seconds" }) // "P1D"
+ * @example diffUnixAsDuration(NaN, 1706745600000, "days") // ""
+ */
+export declare function diffUnixAsDuration(value1: number, value2: number, unit: DateTimeDurationUnit, options?: {
+    epochUnit?: "seconds" | "milliseconds";
+    timeZone?: string;
+} & RoundingOptions<Temporal.DateTimeUnit> & DurationStringOptions): string;

package/dist/unix/calculate/diffUnixAsDuration.js

@@ -0,0 +1,56 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { durationUntilString } from "../../internal/index.js";
+import { isValidUnixEpochPair, resolveUnixTimeZone, } from "../../internal/resolveUnixTimeZone.js";
+import { isValidDateTimeDurationUnit } from "../../plain/validate/index.js";
+/**
+ * Return the difference between two Unix timestamps as an ISO 8601 duration string,
+ * bridging to the `duration` namespace (see `parseDuration`, `normalizeDuration`).
+ *
+ * - Uses Temporal.Instant.until() with `largestUnit` set to `unit`, then `.toString()`.
+ * - Unlike `diffUnix`, `unit` is a single unit (not an array) — an ISO duration string
+ *   already expresses a full multi-unit breakdown via `largestUnit` alone, so there's no
+ *   array-of-units overload here.
+ * - Returns `""` for invalid input (negative diffs are valid and render with a leading `-`).
+ *
+ * `smallestUnit`, `roundingIncrement`, and `roundingMode` control optional rounding of the
+ * underlying difference before it's rendered, per Temporal's DifferenceOptions — same as
+ * `diffUnix`. `toStringSmallestUnit`, `fractionalSecondDigits`, and `toStringRoundingMode`
+ * control the precision of the rendered string itself, per Temporal's ToStringPrecisionOptions
+ * (mirroring `parseDuration`'s options) — kept separate from the `.until()` rounding options
+ * above because both option sets have colliding `smallestUnit`/`roundingMode` keys with
+ * different Temporal types.
+ *
+ * @param value1 first Unix timestamp
+ * @param value2 second Unix timestamp
+ * @param unit DateTimeDurationUnit to use as the duration's largestUnit
+ * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA), smallestUnit, roundingIncrement, roundingMode (.until() rounding); toStringSmallestUnit, fractionalSecondDigits, toStringRoundingMode (.toString() precision)
+ * @returns ISO 8601 duration string, or "" on invalid input
+ *
+ * @example diffUnixAsDuration(1706659200000, 1706745600000, "days") // "P1D"
+ * @example diffUnixAsDuration(1706745600000, 1706659200000, "days") // "-P1D"
+ * @example diffUnixAsDuration(1706659200, 1706745600, "days", { epochUnit: "seconds" }) // "P1D"
+ * @example diffUnixAsDuration(NaN, 1706745600000, "days") // ""
+ */
+export function diffUnixAsDuration(value1, value2, unit, options) {
+    const epochUnit = options?.epochUnit ?? "milliseconds";
+    const timeZone = resolveUnixTimeZone(options?.timeZone);
+    if (!timeZone)
+        return "";
+    const validUnit = isValidDateTimeDurationUnit(unit);
+    if (!validUnit) {
+        return "";
+    }
+    if (!isValidUnixEpochPair(value1, value2)) {
+        return "";
+    }
+    try {
+        const instant1 = Temporal.Instant.fromEpochMilliseconds(epochUnit === "seconds" ? value1 * 1000 : value1);
+        const instant2 = Temporal.Instant.fromEpochMilliseconds(epochUnit === "seconds" ? value2 * 1000 : value2);
+        const zdt1 = instant1.toZonedDateTimeISO(timeZone);
+        const zdt2 = instant2.toZonedDateTimeISO(timeZone);
+        return durationUntilString(zdt1, zdt2, unit, options);
+    }
+    catch {
+        return "";
+    }
+}

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

@@ -0,0 +1,23 @@
+import type { Disambiguation, Offset } from "../../types/index.js";
+/**
+ * Return the end of the quarter for a Unix timestamp.
+ *
+ * - Converts to ZonedDateTime, calculates quarter end, converts back to epoch.
+ * - Q1 ends month 3, Q2 ends month 6, Q3 ends month 9, Q4 ends month 12.
+ * - `disambiguation` controls DST gap/overlap resolution when a quarter boundary lands on an ambiguous local time: "compatible" (default, matches Temporal's default), "earlier", "later", or "reject" (throws, resulting in null).
+ * - `offset` controls whether the source's existing UTC offset is kept when computing a new boundary: "prefer" (Temporal's own default — keeps the source offset whenever still valid, which **makes `disambiguation` inert** in the (rare) common-zone case since quarter boundaries don't fall on DST transitions), "use", "ignore" (**this function's default** — always recomputes from time zone + local time, discarding the stale offset), or "reject" (throws if the source offset is invalid for the new fields, independent of `disambiguation`). Leave `offset` at its default unless you specifically need Temporal's raw `.with()` semantics.
+ * - Returns null for invalid input.
+ *
+ * @param value Unix timestamp (number)
+ * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA), disambiguation ("compatible" | "earlier" | "later" | "reject"), offset ("prefer" | "use" | "ignore" | "reject", default "ignore")
+ * @returns Unix epoch number representing the end of the quarter, or null on invalid input
+ *
+ * @example endOfQuarterForUnix(1706659200000) // 1711977599999
+ * @example endOfQuarterForUnix(-86400000) // -1 (Q4 1969 ends Dec 31)
+ */
+export declare function endOfQuarterForUnix(value: number, options?: {
+    epochUnit?: "seconds" | "milliseconds";
+    timeZone?: string;
+    disambiguation?: Disambiguation;
+    offset?: Offset;
+}): number | null;

package/dist/unix/calculate/endOfQuarterForUnix.js

@@ -0,0 +1,56 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidUnixUnit } from "../../unix/validate/isValidUnixUnit.js";
+import { getSystemTimeZone } from "../../zoned/get/index.js";
+import { isValidTimeZone } from "../../zoned/validate/index.js";
+/**
+ * Return the end of the quarter for a Unix timestamp.
+ *
+ * - Converts to ZonedDateTime, calculates quarter end, converts back to epoch.
+ * - Q1 ends month 3, Q2 ends month 6, Q3 ends month 9, Q4 ends month 12.
+ * - `disambiguation` controls DST gap/overlap resolution when a quarter boundary lands on an ambiguous local time: "compatible" (default, matches Temporal's default), "earlier", "later", or "reject" (throws, resulting in null).
+ * - `offset` controls whether the source's existing UTC offset is kept when computing a new boundary: "prefer" (Temporal's own default — keeps the source offset whenever still valid, which **makes `disambiguation` inert** in the (rare) common-zone case since quarter boundaries don't fall on DST transitions), "use", "ignore" (**this function's default** — always recomputes from time zone + local time, discarding the stale offset), or "reject" (throws if the source offset is invalid for the new fields, independent of `disambiguation`). Leave `offset` at its default unless you specifically need Temporal's raw `.with()` semantics.
+ * - Returns null for invalid input.
+ *
+ * @param value Unix timestamp (number)
+ * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA), disambiguation ("compatible" | "earlier" | "later" | "reject"), offset ("prefer" | "use" | "ignore" | "reject", default "ignore")
+ * @returns Unix epoch number representing the end of the quarter, or null on invalid input
+ *
+ * @example endOfQuarterForUnix(1706659200000) // 1711977599999
+ * @example endOfQuarterForUnix(-86400000) // -1 (Q4 1969 ends Dec 31)
+ */
+export function endOfQuarterForUnix(value, options) {
+    const epochUnit = options?.epochUnit ?? "milliseconds";
+    const timeZone = options?.timeZone ?? getSystemTimeZone();
+    const disambiguation = options?.disambiguation ?? "compatible";
+    const offset = options?.offset ?? "ignore";
+    if (!timeZone || !isValidTimeZone(timeZone) || !isValidUnixUnit(epochUnit)) {
+        return null;
+    }
+    if (!Number.isFinite(value) || !Number.isInteger(value)) {
+        return null;
+    }
+    try {
+        const instant = Temporal.Instant.fromEpochMilliseconds(epochUnit === "seconds" ? value * 1000 : value);
+        const zdt = instant.toZonedDateTimeISO(timeZone);
+        const month = zdt.month;
+        const quarterEndMonth = Math.floor((month - 1) / 3) * 3 + 3;
+        const quarterStart = zdt.with({ month: quarterEndMonth, day: 1, hour: 0, minute: 0, second: 0 }, { disambiguation, offset });
+        const nextQuarterStart = quarterStart.add({ months: 1 });
+        const lastDayOfQuarter = nextQuarterStart.subtract({ days: 1 });
+        const result = lastDayOfQuarter.with({
+            hour: 23,
+            minute: 59,
+            second: 59,
+            millisecond: 999,
+            microsecond: 999,
+            nanosecond: 999,
+        }, { disambiguation, offset });
+        const epoch = epochUnit === "seconds"
+            ? Math.floor(result.epochMilliseconds / 1000)
+            : result.epochMilliseconds;
+        return epoch;
+    }
+    catch {
+        return null;
+    }
+}