@northguild/gmt 1.14.2

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

@@ -0,0 +1,30 @@
+import { Temporal } from "@js-temporal/polyfill";
+import type { Disambiguation, Offset } from "../../types/index.js";
+/**
+ * Return the end of the specified unit for a Unix timestamp.
+ *
+ * - Converts to ZonedDateTime, sets to end of unit, converts back to epoch.
+ * - Supports: "year", "month", "week", "day", "hour", "minute", "second", "millisecond", "microsecond", "nanosecond".
+ * - `disambiguation` controls DST gap/overlap resolution when the boundary jump 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 the new boundary: "prefer" (Temporal's own default — keeps the source offset whenever still valid, which **makes `disambiguation` inert** for almost every case here since the source offset is nearly always still valid after a same-day field reset), "use", "ignore" (**this function's default** — always recomputes from time zone + local time, discarding the stale offset; this is what makes `disambiguation` actually take effect), 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 unit Temporal.DateUnit | Temporal.TimeUnit to specify the end
+ * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA), weekStartsOn ("monday" | "sunday"), disambiguation ("compatible" | "earlier" | "later" | "reject"), offset ("prefer" | "use" | "ignore" | "reject", default "ignore")
+ * @returns Unix epoch number representing the end of the unit, or null on invalid input
+ *
+ * @example endOfUnix(1706659200000, "year") // 1735689600000
+ * @example endOfUnix(1706659200000, "month") // 1708012800000
+ * @example endOfUnix(1706659200, "day", { epochUnit: "seconds" }) // 1706736000
+ * @example endOfUnix(-86400000, "year") // -1 (end of 1969)
+ * @example endOfUnix(1730616300000, "hour", { timeZone: "America/New_York", disambiguation: "reject" }) // null (1730616300000 is the second, repeated 1:45am of the Nov 3 2024 fall-back overlap; end-of-hour is ambiguous)
+ * @example endOfUnix(1730616300000, "hour", { timeZone: "America/New_York", disambiguation: "reject", offset: "prefer" }) // 1730617199999 (setting offset to "prefer" makes disambiguation inert here — the source's -05:00 offset is still valid for 1am, so it's kept and "reject" never fires)
+ */
+export declare function endOfUnix(value: number, unit: Temporal.DateUnit | Temporal.TimeUnit, options?: {
+    epochUnit?: "seconds" | "milliseconds";
+    timeZone?: string;
+    weekStartsOn?: "monday" | "sunday";
+    disambiguation?: Disambiguation;
+    offset?: Offset;
+}): number | null;

package/dist/unix/calculate/endOfUnix.js

@@ -0,0 +1,26 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { startOrEndOfUnix } from "./startOrEndOfUnix.js";
+/**
+ * Return the end of the specified unit for a Unix timestamp.
+ *
+ * - Converts to ZonedDateTime, sets to end of unit, converts back to epoch.
+ * - Supports: "year", "month", "week", "day", "hour", "minute", "second", "millisecond", "microsecond", "nanosecond".
+ * - `disambiguation` controls DST gap/overlap resolution when the boundary jump 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 the new boundary: "prefer" (Temporal's own default — keeps the source offset whenever still valid, which **makes `disambiguation` inert** for almost every case here since the source offset is nearly always still valid after a same-day field reset), "use", "ignore" (**this function's default** — always recomputes from time zone + local time, discarding the stale offset; this is what makes `disambiguation` actually take effect), 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 unit Temporal.DateUnit | Temporal.TimeUnit to specify the end
+ * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA), weekStartsOn ("monday" | "sunday"), disambiguation ("compatible" | "earlier" | "later" | "reject"), offset ("prefer" | "use" | "ignore" | "reject", default "ignore")
+ * @returns Unix epoch number representing the end of the unit, or null on invalid input
+ *
+ * @example endOfUnix(1706659200000, "year") // 1735689600000
+ * @example endOfUnix(1706659200000, "month") // 1708012800000
+ * @example endOfUnix(1706659200, "day", { epochUnit: "seconds" }) // 1706736000
+ * @example endOfUnix(-86400000, "year") // -1 (end of 1969)
+ * @example endOfUnix(1730616300000, "hour", { timeZone: "America/New_York", disambiguation: "reject" }) // null (1730616300000 is the second, repeated 1:45am of the Nov 3 2024 fall-back overlap; end-of-hour is ambiguous)
+ * @example endOfUnix(1730616300000, "hour", { timeZone: "America/New_York", disambiguation: "reject", offset: "prefer" }) // 1730617199999 (setting offset to "prefer" makes disambiguation inert here — the source's -05:00 offset is still valid for 1am, so it's kept and "reject" never fires)
+ */
+export function endOfUnix(value, unit, options) {
+    return startOrEndOfUnix(value, unit, options ?? {}, true);
+}

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

@@ -0,0 +1,14 @@
+export * from "./addUnix.js";
+export * from "./diffUnix.js";
+export * from "./diffUnixAsDuration.js";
+export * from "./endOfQuarterForUnix.js";
+export * from "./endOfUnix.js";
+export * from "./isBetweenUnix.js";
+export * from "./maxUnix.js";
+export * from "./minUnix.js";
+export * from "./roundUnix.js";
+export * from "./setUnix.js";
+export * from "./sortUnix.js";
+export * from "./startOfQuarterForUnix.js";
+export * from "./startOfUnix.js";
+export * from "./subtractUnix.js";

package/dist/unix/calculate/index.js

@@ -0,0 +1,14 @@
+export * from "./addUnix.js";
+export * from "./diffUnix.js";
+export * from "./diffUnixAsDuration.js";
+export * from "./endOfQuarterForUnix.js";
+export * from "./endOfUnix.js";
+export * from "./isBetweenUnix.js";
+export * from "./maxUnix.js";
+export * from "./minUnix.js";
+export * from "./roundUnix.js";
+export * from "./setUnix.js";
+export * from "./sortUnix.js";
+export * from "./startOfQuarterForUnix.js";
+export * from "./startOfUnix.js";
+export * from "./subtractUnix.js";

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

@@ -0,0 +1,23 @@
+/**
+ * Return true when the Unix timestamp is between start and end (inclusive by default).
+ *
+ * - Uses Temporal.Instant.compare for comparison.
+ * - Returns false if start > end or inputs are invalid.
+ * - Use options.inclusiveStart/inclusiveEnd to control boundaries.
+ *
+ * @param value Unix timestamp to check
+ * @param start Unix timestamp for range start
+ * @param end Unix timestamp for range end
+ * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA), inclusiveStart (boolean), inclusiveEnd (boolean)
+ * @returns boolean indicating whether value is between start and end
+ *
+ * @example isBetweenUnix(1705000000000, 1704000000000, 1706000000000) // true
+ * @example isBetweenUnix(1705000000, 1704000000, 1706000000, { epochUnit: "seconds" }) // true
+ * @example isBetweenUnix(1703000000000, 1704000000000, 1706000000000) // false
+ */
+export declare function isBetweenUnix(value: number, start: number, end: number, options?: {
+    epochUnit?: "seconds" | "milliseconds";
+    timeZone?: string;
+    inclusiveStart?: boolean;
+    inclusiveEnd?: boolean;
+}): boolean;

package/dist/unix/calculate/isBetweenUnix.js

@@ -0,0 +1,54 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { getSystemTimeZone } from "../../zoned/get/index.js";
+import { isValidTimeZone } from "../../zoned/validate/index.js";
+/**
+ * Return true when the Unix timestamp is between start and end (inclusive by default).
+ *
+ * - Uses Temporal.Instant.compare for comparison.
+ * - Returns false if start > end or inputs are invalid.
+ * - Use options.inclusiveStart/inclusiveEnd to control boundaries.
+ *
+ * @param value Unix timestamp to check
+ * @param start Unix timestamp for range start
+ * @param end Unix timestamp for range end
+ * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA), inclusiveStart (boolean), inclusiveEnd (boolean)
+ * @returns boolean indicating whether value is between start and end
+ *
+ * @example isBetweenUnix(1705000000000, 1704000000000, 1706000000000) // true
+ * @example isBetweenUnix(1705000000, 1704000000, 1706000000, { epochUnit: "seconds" }) // true
+ * @example isBetweenUnix(1703000000000, 1704000000000, 1706000000000) // false
+ */
+export function isBetweenUnix(value, start, end, options) {
+    const epochUnit = options?.epochUnit ?? "milliseconds";
+    const timeZone = options?.timeZone ?? getSystemTimeZone();
+    const inclusiveStart = options?.inclusiveStart ?? true;
+    const inclusiveEnd = options?.inclusiveEnd ?? true;
+    if (!timeZone || !isValidTimeZone(timeZone))
+        return false;
+    if (!Number.isFinite(value) ||
+        !Number.isInteger(value) ||
+        !Number.isFinite(start) ||
+        !Number.isInteger(start) ||
+        !Number.isFinite(end) ||
+        !Number.isInteger(end)) {
+        return false;
+    }
+    try {
+        const instant = Temporal.Instant.fromEpochMilliseconds(epochUnit === "seconds" ? value * 1000 : value);
+        const startInstant = Temporal.Instant.fromEpochMilliseconds(epochUnit === "seconds" ? start * 1000 : start);
+        const endInstant = Temporal.Instant.fromEpochMilliseconds(epochUnit === "seconds" ? end * 1000 : end);
+        if (Temporal.Instant.compare(startInstant, endInstant) === 1) {
+            return false;
+        }
+        const startCheck = inclusiveStart
+            ? Temporal.Instant.compare(startInstant, instant) <= 0
+            : Temporal.Instant.compare(startInstant, instant) < 0;
+        const endCheck = inclusiveEnd
+            ? Temporal.Instant.compare(instant, endInstant) <= 0
+            : Temporal.Instant.compare(instant, endInstant) < 0;
+        return startCheck && endCheck;
+    }
+    catch {
+        return false;
+    }
+}

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

@@ -0,0 +1,13 @@
+/**
+ * Return the latest (maximum) of the given Unix timestamp values.
+ *
+ * - Filters invalid values before finding maximum.
+ * - Returns null if array is empty or has no valid values.
+ *
+ * @param unixValues Array of Unix timestamps (e.g. 1699531200)
+ * @returns The latest Unix timestamp, or null on invalid input
+ *
+ * @example maxUnix([1706659200000, 1704067200000, 1700000000000]) // 1706659200000
+ * @example maxUnix([]) // null
+ */
+export declare function maxUnix(unixValues: number[]): number | null;

package/dist/unix/calculate/maxUnix.js

@@ -0,0 +1,21 @@
+import { isValidAmount } from "../../internal/index.js";
+/**
+ * Return the latest (maximum) of the given Unix timestamp values.
+ *
+ * - Filters invalid values before finding maximum.
+ * - Returns null if array is empty or has no valid values.
+ *
+ * @param unixValues Array of Unix timestamps (e.g. 1699531200)
+ * @returns The latest Unix timestamp, or null on invalid input
+ *
+ * @example maxUnix([1706659200000, 1704067200000, 1700000000000]) // 1706659200000
+ * @example maxUnix([]) // null
+ */
+export function maxUnix(unixValues) {
+    if (!unixValues.length)
+        return null;
+    const valid = unixValues.filter(isValidAmount);
+    if (!valid.length)
+        return null;
+    return Math.max(...valid);
+}

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

@@ -0,0 +1,13 @@
+/**
+ * Return the earliest (minimum) of the given Unix timestamp values.
+ *
+ * - Filters invalid values before finding minimum.
+ * - Returns null if array is empty or has no valid values.
+ *
+ * @param unixValues Array of Unix timestamps (e.g. 1699531200)
+ * @returns The earliest Unix timestamp, or null on invalid input
+ *
+ * @example minUnix([1706659200000, 1704067200000, 1700000000000]) // 1700000000000
+ * @example minUnix([]) // null
+ */
+export declare function minUnix(unixValues: number[]): number | null;

package/dist/unix/calculate/minUnix.js

@@ -0,0 +1,21 @@
+import { isValidAmount } from "../../internal/index.js";
+/**
+ * Return the earliest (minimum) of the given Unix timestamp values.
+ *
+ * - Filters invalid values before finding minimum.
+ * - Returns null if array is empty or has no valid values.
+ *
+ * @param unixValues Array of Unix timestamps (e.g. 1699531200)
+ * @returns The earliest Unix timestamp, or null on invalid input
+ *
+ * @example minUnix([1706659200000, 1704067200000, 1700000000000]) // 1700000000000
+ * @example minUnix([]) // null
+ */
+export function minUnix(unixValues) {
+    if (!unixValues.length)
+        return null;
+    const valid = unixValues.filter(isValidAmount);
+    if (!valid.length)
+        return null;
+    return Math.min(...valid);
+}

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

@@ -0,0 +1,27 @@
+import { Temporal } from "@js-temporal/polyfill";
+/**
+ * Round a Unix timestamp to the specified unit.
+ *
+ * - Converts to ZonedDateTime, rounds, converts back to epoch.
+ * - Supports: "day", "hour", "minute", "second", "millisecond", "microsecond", "nanosecond".
+ * - Date units ("year", "month", "week") are not supported by the Temporal polyfill's ZonedDateTime.round() — they return null.
+ * - Returns null for invalid input.
+ *
+ * @param value Unix timestamp (number)
+ * @param options Rounding options: smallestUnit, optional roundingIncrement, roundingMode, epochUnit, timeZone
+ * @returns Rounded Unix epoch number, or null on invalid input
+ *
+ * @example roundUnix(1706659200000, { smallestUnit: "hour" }) // 1706662800000 (rounded up to next hour)
+ * @example roundUnix(1706659200000, { smallestUnit: "day", epochUnit: "seconds" }) // 1706640000 (start of day in seconds)
+ * @example roundUnix(1706659200000, { smallestUnit: "hour", roundingIncrement: 2 }) // 1706662800000 (rounded to nearest 2-hour mark)
+ * @example roundUnix(-86400000, { smallestUnit: "day" }) // -86400000 (start of day for negative timestamp)
+ * @example roundUnix("invalid", { smallestUnit: "hour" }) // null
+ * @example roundUnix(NaN, { smallestUnit: "hour" }) // null
+ */
+export declare function roundUnix(value: number, options: {
+    smallestUnit: Temporal.SmallestUnit<"day" | "hour" | "minute" | "second" | "millisecond" | "microsecond" | "nanosecond">;
+    roundingIncrement?: number;
+    roundingMode?: Temporal.RoundingMode;
+    epochUnit?: "seconds" | "milliseconds";
+    timeZone?: string;
+}): number | null;

package/dist/unix/calculate/roundUnix.js

@@ -0,0 +1,62 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidDateTimeUnit } from "../../plain/index.js";
+import { getSystemTimeZone } from "../../zoned/get/index.js";
+import { isValidTimeZone } from "../../zoned/validate/index.js";
+/**
+ * Round a Unix timestamp to the specified unit.
+ *
+ * - Converts to ZonedDateTime, rounds, converts back to epoch.
+ * - Supports: "day", "hour", "minute", "second", "millisecond", "microsecond", "nanosecond".
+ * - Date units ("year", "month", "week") are not supported by the Temporal polyfill's ZonedDateTime.round() — they return null.
+ * - Returns null for invalid input.
+ *
+ * @param value Unix timestamp (number)
+ * @param options Rounding options: smallestUnit, optional roundingIncrement, roundingMode, epochUnit, timeZone
+ * @returns Rounded Unix epoch number, or null on invalid input
+ *
+ * @example roundUnix(1706659200000, { smallestUnit: "hour" }) // 1706662800000 (rounded up to next hour)
+ * @example roundUnix(1706659200000, { smallestUnit: "day", epochUnit: "seconds" }) // 1706640000 (start of day in seconds)
+ * @example roundUnix(1706659200000, { smallestUnit: "hour", roundingIncrement: 2 }) // 1706662800000 (rounded to nearest 2-hour mark)
+ * @example roundUnix(-86400000, { smallestUnit: "day" }) // -86400000 (start of day for negative timestamp)
+ * @example roundUnix("invalid", { smallestUnit: "hour" }) // null
+ * @example roundUnix(NaN, { smallestUnit: "hour" }) // null
+ */
+export function roundUnix(value, options) {
+    const { smallestUnit, roundingIncrement, roundingMode, epochUnit = "milliseconds", timeZone = getSystemTimeZone(), } = options;
+    if (!timeZone ||
+        !isValidDateTimeUnit(smallestUnit) ||
+        !isValidTimeZone(timeZone)) {
+        return null;
+    }
+    if (!Number.isFinite(value) || !Number.isInteger(value)) {
+        return null;
+    }
+    // Polyfill limitation: year/month/week not supported for ZonedDateTime.round()
+    const supportedUnits = [
+        "day",
+        "hour",
+        "minute",
+        "second",
+        "millisecond",
+        "microsecond",
+        "nanosecond",
+    ];
+    if (!supportedUnits.includes(smallestUnit)) {
+        return null;
+    }
+    try {
+        let epochMs = epochUnit === "seconds" ? value * 1000 : value;
+        const instant = Temporal.Instant.fromEpochMilliseconds(epochMs);
+        const source = instant.toZonedDateTimeISO(timeZone);
+        const result = source.round({
+            smallestUnit,
+            roundingIncrement,
+            roundingMode,
+        });
+        epochMs = result.epochMilliseconds;
+        return epochUnit === "seconds" ? Math.floor(epochMs / 1000) : epochMs;
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -0,0 +1,35 @@
+import { Temporal } from "@js-temporal/polyfill";
+import type { Disambiguation, Offset, Overflow } from "../../types/index.js";
+/**
+ * Return a Unix epoch value with the given `fields` set on `value`, interpreted in `timeZone`.
+ *
+ * - Converts to ZonedDateTime, wraps `Temporal.ZonedDateTime.prototype.with()` (resolving every
+ *   supplied field in a single atomic overflow pass), then converts back to epoch. This is the
+ *   safe alternative to composing `addUnix()` calls field-by-field — see `setZoned`'s doc for
+ *   why order-independent field resolution matters, and why `disambiguation`/`offset` require
+ *   `.with()` rather than arithmetic.
+ * - `fields` may set any of `year`, `month`, `monthCode`, `day`, `hour`, `minute`, `second`,
+ *   `millisecond`, `microsecond`, `nanosecond`, `era`, and/or `eraYear`; omitted fields keep
+ *   their current value. An empty object is a no-op.
+ * - `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. setting
+ *   `month: 2` on a value whose `day` is 31: "constrain" clamps to Feb 29/28, "reject" throws
+ *   (resulting in null).
+ * - Returns null for invalid input.
+ *
+ * @param value Unix timestamp (number)
+ * @param fields Partial<Temporal.ZonedDateTimeLike> object (excluding calendar/timeZone/offset) specifying fields to set
+ * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA), overflow ("constrain" | "reject"), disambiguation ("compatible" | "earlier" | "later" | "reject"), offset ("prefer" | "use" | "ignore" | "reject", default "ignore")
+ * @returns Unix epoch number with fields set, or null on invalid input
+ *
+ * @example setUnix(1710072000000, { hour: 9 }, { timeZone: "UTC" }) // 1710061200000 (2024-03-10T09:00:00Z)
+ * @example setUnix(1706659200000, { year: 2025 }, { timeZone: "UTC" }) // 1738281600000 (2025-01-31T00:00:00Z)
+ * @example setUnix(1706659200000, {}, { timeZone: "UTC" }) // 1706659200000 (empty fields object is a no-op)
+ * @example setUnix(NaN, { hour: 9 }) // null
+ */
+export declare function setUnix(value: number, fields: Omit<Temporal.ZonedDateTimeLike, "calendar" | "timeZone" | "offset">, options?: {
+    epochUnit?: "seconds" | "milliseconds";
+    timeZone?: string;
+    overflow?: Overflow;
+    disambiguation?: Disambiguation;
+    offset?: Offset;
+}): number | null;

package/dist/unix/calculate/setUnix.js

@@ -0,0 +1,60 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { resolveOverflow } from "../../internal/index.js";
+import { getSystemTimeZone } from "../../zoned/get/index.js";
+import { isValidTimeZone } from "../../zoned/validate/index.js";
+/**
+ * Return a Unix epoch value with the given `fields` set on `value`, interpreted in `timeZone`.
+ *
+ * - Converts to ZonedDateTime, wraps `Temporal.ZonedDateTime.prototype.with()` (resolving every
+ *   supplied field in a single atomic overflow pass), then converts back to epoch. This is the
+ *   safe alternative to composing `addUnix()` calls field-by-field — see `setZoned`'s doc for
+ *   why order-independent field resolution matters, and why `disambiguation`/`offset` require
+ *   `.with()` rather than arithmetic.
+ * - `fields` may set any of `year`, `month`, `monthCode`, `day`, `hour`, `minute`, `second`,
+ *   `millisecond`, `microsecond`, `nanosecond`, `era`, and/or `eraYear`; omitted fields keep
+ *   their current value. An empty object is a no-op.
+ * - `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. setting
+ *   `month: 2` on a value whose `day` is 31: "constrain" clamps to Feb 29/28, "reject" throws
+ *   (resulting in null).
+ * - Returns null for invalid input.
+ *
+ * @param value Unix timestamp (number)
+ * @param fields Partial<Temporal.ZonedDateTimeLike> object (excluding calendar/timeZone/offset) specifying fields to set
+ * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA), overflow ("constrain" | "reject"), disambiguation ("compatible" | "earlier" | "later" | "reject"), offset ("prefer" | "use" | "ignore" | "reject", default "ignore")
+ * @returns Unix epoch number with fields set, or null on invalid input
+ *
+ * @example setUnix(1710072000000, { hour: 9 }, { timeZone: "UTC" }) // 1710061200000 (2024-03-10T09:00:00Z)
+ * @example setUnix(1706659200000, { year: 2025 }, { timeZone: "UTC" }) // 1738281600000 (2025-01-31T00:00:00Z)
+ * @example setUnix(1706659200000, {}, { timeZone: "UTC" }) // 1706659200000 (empty fields object is a no-op)
+ * @example setUnix(NaN, { hour: 9 }) // null
+ */
+export function setUnix(value, fields, options) {
+    const epochUnit = options?.epochUnit ?? "milliseconds";
+    const timeZone = options?.timeZone ?? getSystemTimeZone();
+    if (!timeZone || !isValidTimeZone(timeZone))
+        return null;
+    if (!Number.isFinite(value) || !Number.isInteger(value))
+        return null;
+    const overflow = resolveOverflow(options?.overflow);
+    const disambiguation = options?.disambiguation ?? "compatible";
+    // "ignore" (not Temporal's own "prefer" default) so `disambiguation` actually takes effect —
+    // see C3 / docs/dst-disambiguation.md: with "prefer", the source's still-valid offset is kept
+    // and disambiguation is silently never consulted.
+    const offset = options?.offset ?? "ignore";
+    try {
+        const epochMs = epochUnit === "seconds" ? value * 1000 : value;
+        const instant = Temporal.Instant.fromEpochMilliseconds(epochMs);
+        const zoned = instant.toZonedDateTimeISO(timeZone);
+        // Temporal.ZonedDateTime.prototype.with() throws on an empty fields object ("no supported
+        // properties found") rather than treating it as a no-op, so short-circuit here.
+        const result = Object.keys(fields).length === 0
+            ? zoned
+            : zoned.with(fields, { overflow, disambiguation, offset });
+        return epochUnit === "seconds"
+            ? Math.floor(result.epochMilliseconds / 1000)
+            : result.epochMilliseconds;
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -0,0 +1,16 @@
+/**
+ * Sort an array of Unix timestamp values in ascending or descending order.
+ *
+ * - Filters invalid values before sorting.
+ * - Supports "asc" (earliest first) or "desc" (latest first).
+ * - Returns [] if array is empty or has no valid values.
+ *
+ * @param unixValues Array of Unix timestamps (e.g. 1699531200)
+ * @param order "asc" for ascending (earliest first) | "desc" for descending (latest first)
+ * @returns Sorted array of Unix timestamps
+ *
+ * @example sortUnix([1706659200000, 1704067200000, 1700000000000]) // [1700000000000, 1704067200000, 1706659200000]
+ * @example sortUnix([1704067200, 1700000000], "desc") // [1704067200, 1700000000]
+ * @example sortUnix([]) // []
+ */
+export declare function sortUnix(unixValues: number[], order?: "asc" | "desc"): number[];

package/dist/unix/calculate/sortUnix.js

@@ -0,0 +1,28 @@
+import { isValidAmount } from "../../internal/index.js";
+/**
+ * Sort an array of Unix timestamp values in ascending or descending order.
+ *
+ * - Filters invalid values before sorting.
+ * - Supports "asc" (earliest first) or "desc" (latest first).
+ * - Returns [] if array is empty or has no valid values.
+ *
+ * @param unixValues Array of Unix timestamps (e.g. 1699531200)
+ * @param order "asc" for ascending (earliest first) | "desc" for descending (latest first)
+ * @returns Sorted array of Unix timestamps
+ *
+ * @example sortUnix([1706659200000, 1704067200000, 1700000000000]) // [1700000000000, 1704067200000, 1706659200000]
+ * @example sortUnix([1704067200, 1700000000], "desc") // [1704067200, 1700000000]
+ * @example sortUnix([]) // []
+ */
+export function sortUnix(unixValues, order = "asc") {
+    if (!unixValues.length)
+        return [];
+    const valid = unixValues.filter(isValidAmount);
+    if (!valid.length)
+        return [];
+    const sorted = valid.sort((a, b) => a - b);
+    if (order === "desc") {
+        return sorted.reverse();
+    }
+    return sorted;
+}

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

@@ -0,0 +1,23 @@
+import type { Disambiguation, Offset } from "../../types/index.js";
+/**
+ * Return the start of the quarter for a Unix timestamp.
+ *
+ * - Converts to ZonedDateTime, calculates quarter start, converts back to epoch.
+ * - Q1 returns month 1, Q2 returns month 4, Q3 returns month 7, Q4 returns month 10.
+ * - `disambiguation` controls DST gap/overlap resolution when the quarter-start 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 the 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 start of the quarter, or null on invalid input
+ *
+ * @example startOfQuarterForUnix(1706659200000) // 1704067200000
+ * @example startOfQuarterForUnix(-86400000) // -25598400001 (Q1 1969 starts Jan 1)
+ */
+export declare function startOfQuarterForUnix(value: number, options?: {
+    epochUnit?: "seconds" | "milliseconds";
+    timeZone?: string;
+    disambiguation?: Disambiguation;
+    offset?: Offset;
+}): number | null;

package/dist/unix/calculate/startOfQuarterForUnix.js

@@ -0,0 +1,46 @@
+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 start of the quarter for a Unix timestamp.
+ *
+ * - Converts to ZonedDateTime, calculates quarter start, converts back to epoch.
+ * - Q1 returns month 1, Q2 returns month 4, Q3 returns month 7, Q4 returns month 10.
+ * - `disambiguation` controls DST gap/overlap resolution when the quarter-start 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 the 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 start of the quarter, or null on invalid input
+ *
+ * @example startOfQuarterForUnix(1706659200000) // 1704067200000
+ * @example startOfQuarterForUnix(-86400000) // -25598400001 (Q1 1969 starts Jan 1)
+ */
+export function startOfQuarterForUnix(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 quarterStartMonth = Math.floor((month - 1) / 3) * 3 + 1;
+        const result = zdt.with({ month: quarterStartMonth, day: 1, hour: 0, minute: 0, second: 0 }, { disambiguation, offset });
+        const epoch = epochUnit === "seconds"
+            ? Math.floor(result.epochMilliseconds / 1000)
+            : result.epochMilliseconds;
+        return epoch;
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -0,0 +1,30 @@
+import { Temporal } from "@js-temporal/polyfill";
+import type { Disambiguation, Offset } from "../../types/index.js";
+/**
+ * Return the start of the specified unit for a Unix timestamp.
+ *
+ * - Converts to ZonedDateTime, sets to start of unit, converts back to epoch.
+ * - Supports: "year", "month", "week", "day", "hour", "minute", "second", "millisecond", "microsecond", "nanosecond".
+ * - `disambiguation` controls DST gap/overlap resolution when the boundary jump 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 the new boundary: "prefer" (Temporal's own default — keeps the source offset whenever still valid, which **makes `disambiguation` inert** for almost every case here since the source offset is nearly always still valid after a same-day field reset), "use", "ignore" (**this function's default** — always recomputes from time zone + local time, discarding the stale offset; this is what makes `disambiguation` actually take effect), 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 unit Temporal.DateUnit | Temporal.TimeUnit to specify the start
+ * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA), weekStartsOn ("monday" | "sunday"), disambiguation ("compatible" | "earlier" | "later" | "reject"), offset ("prefer" | "use" | "ignore" | "reject", default "ignore")
+ * @returns Unix epoch number representing the start of the unit, or null on invalid input
+ *
+ * @example startOfUnix(1706659200000, "year") // 1704067200000
+ * @example startOfUnix(1706659200000, "month") // 1705353600000
+ * @example startOfUnix(1706659200, "day", { epochUnit: "seconds" }) // 1706640000
+ * @example startOfUnix(-86400000, "year") // -31536000001 (start of 1969)
+ * @example startOfUnix(1730616300000, "hour", { timeZone: "America/New_York", disambiguation: "reject" }) // null (1730616300000 is the second, repeated 1:45am of the Nov 3 2024 fall-back overlap; start-of-hour is ambiguous)
+ * @example startOfUnix(1730616300000, "hour", { timeZone: "America/New_York", disambiguation: "reject", offset: "prefer" }) // 1730613600000 (setting offset to "prefer" makes disambiguation inert here — the source's -05:00 offset is still valid for 1am, so it's kept and "reject" never fires)
+ */
+export declare function startOfUnix(value: number, unit: Temporal.DateUnit | Temporal.TimeUnit, options?: {
+    epochUnit?: "seconds" | "milliseconds";
+    timeZone?: string;
+    weekStartsOn?: "monday" | "sunday";
+    disambiguation?: Disambiguation;
+    offset?: Offset;
+}): number | null;

package/dist/unix/calculate/startOfUnix.js

@@ -0,0 +1,26 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { startOrEndOfUnix } from "./startOrEndOfUnix.js";
+/**
+ * Return the start of the specified unit for a Unix timestamp.
+ *
+ * - Converts to ZonedDateTime, sets to start of unit, converts back to epoch.
+ * - Supports: "year", "month", "week", "day", "hour", "minute", "second", "millisecond", "microsecond", "nanosecond".
+ * - `disambiguation` controls DST gap/overlap resolution when the boundary jump 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 the new boundary: "prefer" (Temporal's own default — keeps the source offset whenever still valid, which **makes `disambiguation` inert** for almost every case here since the source offset is nearly always still valid after a same-day field reset), "use", "ignore" (**this function's default** — always recomputes from time zone + local time, discarding the stale offset; this is what makes `disambiguation` actually take effect), 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 unit Temporal.DateUnit | Temporal.TimeUnit to specify the start
+ * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA), weekStartsOn ("monday" | "sunday"), disambiguation ("compatible" | "earlier" | "later" | "reject"), offset ("prefer" | "use" | "ignore" | "reject", default "ignore")
+ * @returns Unix epoch number representing the start of the unit, or null on invalid input
+ *
+ * @example startOfUnix(1706659200000, "year") // 1704067200000
+ * @example startOfUnix(1706659200000, "month") // 1705353600000
+ * @example startOfUnix(1706659200, "day", { epochUnit: "seconds" }) // 1706640000
+ * @example startOfUnix(-86400000, "year") // -31536000001 (start of 1969)
+ * @example startOfUnix(1730616300000, "hour", { timeZone: "America/New_York", disambiguation: "reject" }) // null (1730616300000 is the second, repeated 1:45am of the Nov 3 2024 fall-back overlap; start-of-hour is ambiguous)
+ * @example startOfUnix(1730616300000, "hour", { timeZone: "America/New_York", disambiguation: "reject", offset: "prefer" }) // 1730613600000 (setting offset to "prefer" makes disambiguation inert here — the source's -05:00 offset is still valid for 1am, so it's kept and "reject" never fires)
+ */
+export function startOfUnix(value, unit, options) {
+    return startOrEndOfUnix(value, unit, options ?? {}, false);
+}

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

@@ -0,0 +1,9 @@
+import { Temporal } from "@js-temporal/polyfill";
+import type { Disambiguation, Offset } from "../../types/index.js";
+export declare function startOrEndOfUnix(value: number, unit: Temporal.DateUnit | Temporal.TimeUnit, options: {
+    epochUnit?: "seconds" | "milliseconds";
+    timeZone?: string;
+    weekStartsOn?: "monday" | "sunday";
+    disambiguation?: Disambiguation;
+    offset?: Offset;
+}, isEnd: boolean): number | null;