@northguild/gmt 1.14.2

package/dist/unix/calculate/startOrEndOfUnix.js

@@ -0,0 +1,122 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidDateTimeUnit } from "../../plain/index.js";
+import { isValidUnixUnit } from "../../unix/validate/isValidUnixUnit.js";
+import { getSystemTimeZone } from "../../zoned/get/index.js";
+import { isValidTimeZone } from "../../zoned/validate/index.js";
+export function startOrEndOfUnix(value, unit, options, isEnd) {
+    const epochUnit = options.epochUnit ?? "milliseconds";
+    const timeZone = options.timeZone ?? getSystemTimeZone();
+    const weekStartsOn = options.weekStartsOn ?? "monday";
+    const disambiguation = options.disambiguation ?? "compatible";
+    const offset = options.offset ?? "ignore";
+    if (!timeZone ||
+        !isValidDateTimeUnit(unit) ||
+        !isValidTimeZone(timeZone) ||
+        !isValidUnixUnit(epochUnit)) {
+        return null;
+    }
+    if (!Number.isFinite(value) || !Number.isInteger(value)) {
+        return null;
+    }
+    try {
+        const epochMs = epochUnit === "seconds" ? value * 1000 : value;
+        const instant = Temporal.Instant.fromEpochMilliseconds(epochMs);
+        const source = instant.toZonedDateTimeISO(timeZone);
+        const timeFields = isEnd
+            ? {
+                hour: 23,
+                minute: 59,
+                second: 59,
+                millisecond: 999,
+                microsecond: 999,
+                nanosecond: 999,
+            }
+            : {
+                hour: 0,
+                minute: 0,
+                second: 0,
+                millisecond: 0,
+                microsecond: 0,
+                nanosecond: 0,
+            };
+        let result;
+        switch (unit) {
+            case "year":
+                result = isEnd
+                    ? source.with({ month: 12, day: 31, ...timeFields }, { disambiguation, offset })
+                    : source.with({ month: 1, day: 1, ...timeFields }, { disambiguation, offset });
+                break;
+            case "month": {
+                const lastDay = Temporal.PlainDate.from({
+                    year: source.year,
+                    month: source.month,
+                    day: 1,
+                }).daysInMonth;
+                result = isEnd
+                    ? source.with({ day: lastDay, ...timeFields }, { disambiguation, offset })
+                    : source.with({ day: 1, ...timeFields }, { disambiguation, offset });
+                break;
+            }
+            case "week": {
+                const daysToSubtract = weekStartsOn === "monday"
+                    ? source.dayOfWeek - 1
+                    : source.dayOfWeek % 7;
+                const weekAnchor = source.subtract({ days: daysToSubtract });
+                result = isEnd
+                    ? weekAnchor
+                        .add({ days: 6 })
+                        .with({ ...timeFields }, { disambiguation, offset })
+                    : weekAnchor.with({ ...timeFields }, { disambiguation, offset });
+                break;
+            }
+            case "day":
+                result = source.with({ ...timeFields }, { disambiguation, offset });
+                break;
+            case "hour":
+                result = source.with({
+                    minute: timeFields.minute,
+                    second: timeFields.second,
+                    millisecond: timeFields.millisecond,
+                    microsecond: timeFields.microsecond,
+                    nanosecond: timeFields.nanosecond,
+                }, { disambiguation, offset });
+                break;
+            case "minute":
+                result = source.with({
+                    second: timeFields.second,
+                    millisecond: timeFields.millisecond,
+                    microsecond: timeFields.microsecond,
+                    nanosecond: timeFields.nanosecond,
+                }, { disambiguation, offset });
+                break;
+            case "second":
+                result = source.with({
+                    millisecond: timeFields.millisecond,
+                    microsecond: timeFields.microsecond,
+                    nanosecond: timeFields.nanosecond,
+                }, { disambiguation, offset });
+                break;
+            case "millisecond":
+                result = source.with({
+                    microsecond: timeFields.microsecond,
+                    nanosecond: timeFields.nanosecond,
+                }, { disambiguation, offset });
+                break;
+            case "microsecond":
+                result = source.with({ nanosecond: timeFields.nanosecond }, { disambiguation, offset });
+                break;
+            case "nanosecond":
+                result = source;
+                break;
+            default:
+                return null;
+        }
+        const epoch = epochUnit === "seconds"
+            ? Math.floor(result.epochMilliseconds / 1000)
+            : result.epochMilliseconds;
+        return epoch;
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -0,0 +1,25 @@
+import type { DateTimeDurationUnit, Overflow } from "../../types/index.js";
+/**
+ * Subtract a temporal amount from a Unix epoch value and return the resulting epoch.
+ *
+ * - Converts to ZonedDateTime, subtracts 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. subtracting
+ * 1 month from Mar 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 subtract
+ * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA), overflow ("constrain" | "reject")
+ * @returns Unix epoch number after subtraction, or null on invalid input
+ *
+ * @example subtractUnix(1706745600000, { days: 1 }) // 1706659200000
+ * @example subtractUnix(1706745600, { days: 1 }, { epochUnit: "seconds" }) // 1706659200
+ * @example subtractUnix(0, { days: 1 }) // -86400000 (Jan 1 1970 - 1 day = Dec 31 1969)
+ */
+export declare function subtractUnix(value: number, units: Partial<Record<DateTimeDurationUnit, number>>, options?: {
+    epochUnit?: "seconds" | "milliseconds";
+    timeZone?: string;
+    overflow?: Overflow;
+}): number | null;

package/dist/unix/calculate/subtractUnix.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";
+/**
+ * Subtract a temporal amount from a Unix epoch value and return the resulting epoch.
+ *
+ * - Converts to ZonedDateTime, subtracts 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. subtracting
+ * 1 month from Mar 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 subtract
+ * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA), overflow ("constrain" | "reject")
+ * @returns Unix epoch number after subtraction, or null on invalid input
+ *
+ * @example subtractUnix(1706745600000, { days: 1 }) // 1706659200000
+ * @example subtractUnix(1706745600, { days: 1 }, { epochUnit: "seconds" }) // 1706659200
+ * @example subtractUnix(0, { days: 1 }) // -86400000 (Jan 1 1970 - 1 day = Dec 31 1969)
+ */
+export function subtractUnix(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.subtract(units, { overflow });
+        const epoch = epochUnit === "seconds"
+            ? Math.floor(result.epochMilliseconds / 1000)
+            : result.epochMilliseconds;
+        return epoch;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/unix/compare/areUnixEqual.d.ts

@@ -0,0 +1,21 @@
+import type { UnixUnit } from "../validate/isValidUnixUnit.js";
+/**
+ * Return whether `value1` and `value2` represent the same instant.
+ *
+ * - Uses Temporal.Instant.compare to check equality.
+ * - Returns false if either input is invalid.
+ *
+ * @param value1 first unix epoch value
+ * @param value2 second unix epoch value
+ * @param options epoch unit and options
+ * @returns `true` if `value1` and `value2` are equal, otherwise `false`
+ *
+ * @example areUnixEqual(1706659200, 1706659200) // true
+ * @example areUnixEqual(1706659200, 1704067200) // false
+ * @example areUnixEqual(1706659200, 1706659200000, { epochUnit: "seconds" }) // true
+ * @example areUnixEqual(1706659200, 1706659200000) // false
+ * @example areUnixEqual(-86400000, 0) // false (1969-12-31 is not equal to 1970-01-01)
+ */
+export declare function areUnixEqual(value1: number, value2: number, options?: {
+    epochUnit?: UnixUnit;
+}): boolean;

package/dist/unix/compare/areUnixEqual.js

@@ -0,0 +1,33 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidAmount } from "../../internal/index.js";
+/**
+ * Return whether `value1` and `value2` represent the same instant.
+ *
+ * - Uses Temporal.Instant.compare to check equality.
+ * - Returns false if either input is invalid.
+ *
+ * @param value1 first unix epoch value
+ * @param value2 second unix epoch value
+ * @param options epoch unit and options
+ * @returns `true` if `value1` and `value2` are equal, otherwise `false`
+ *
+ * @example areUnixEqual(1706659200, 1706659200) // true
+ * @example areUnixEqual(1706659200, 1704067200) // false
+ * @example areUnixEqual(1706659200, 1706659200000, { epochUnit: "seconds" }) // true
+ * @example areUnixEqual(1706659200, 1706659200000) // false
+ * @example areUnixEqual(-86400000, 0) // false (1969-12-31 is not equal to 1970-01-01)
+ */
+export function areUnixEqual(value1, value2, options) {
+    const epochUnit = options?.epochUnit ?? "milliseconds";
+    if (!isValidAmount(value1) || !isValidAmount(value2)) {
+        return false;
+    }
+    try {
+        const instant1 = Temporal.Instant.fromEpochMilliseconds(epochUnit === "seconds" ? value1 * 1000 : value1);
+        const instant2 = Temporal.Instant.fromEpochMilliseconds(epochUnit === "seconds" ? value2 * 1000 : value2);
+        return Temporal.Instant.compare(instant1, instant2) === 0;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/unix/compare/areUnixEqualBy.d.ts

@@ -0,0 +1,31 @@
+import type { DateTimeUnit } from "../../types/index.js";
+import type { UnixUnit } from "../validate/isValidUnixUnit.js";
+/**
+ * Compare two Unix epoch values for equality at a given unit.
+ *
+ * - Both values are resolved to the start of `unit` in `options.timeZone`
+ *   (default: the system time zone) before comparison, so `"day"` compares
+ *   calendar days in that zone, not raw epoch buckets.
+ * - `"month"` requires the same month AND year, matching `areDateTimesEqualBy`.
+ * - Returns false for an unsupported unit or invalid input.
+ *
+ * Mapping from date-fns (Decision 5, `context/roadmap/issues/J.md`):
+ * - `isSameDay(a, b)` → `areUnixEqualBy(a, b, "day")`
+ * - `isSameMonth(a, b)` → `areUnixEqualBy(a, b, "month")`
+ * - `isSameYear(a, b)` → `areUnixEqualBy(a, b, "year")`
+ *
+ * @param value1 first Unix epoch value
+ * @param value2 second Unix epoch value
+ * @param unit Temporal.DateUnit | Temporal.TimeUnit to compare by
+ * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA), weekStartsOn ("monday" | "sunday")
+ * @returns true if both values share the same start-of-unit boundary, false on an unsupported unit or invalid input
+ *
+ * @example areUnixEqualBy(1710498000000, 1710503000000, "day", { timeZone: "UTC" }) // true (both fall on 2024-03-15 in UTC)
+ * @example areUnixEqualBy(1704067200000, 1735689600000, "year", { timeZone: "UTC" }) // false (2024-01-01 vs 2025-01-01)
+ * @example areUnixEqualBy(Number.NaN, 1710498000000, "day") // false
+ */
+export declare function areUnixEqualBy(value1: number, value2: number, unit: DateTimeUnit, options?: {
+    epochUnit?: UnixUnit;
+    timeZone?: string;
+    weekStartsOn?: "monday" | "sunday";
+}): boolean;

package/dist/unix/compare/areUnixEqualBy.js

@@ -0,0 +1,39 @@
+import { isValidAmount } from "../../internal/index.js";
+import { startOfUnix } from "../calculate/startOfUnix.js";
+/**
+ * Compare two Unix epoch values for equality at a given unit.
+ *
+ * - Both values are resolved to the start of `unit` in `options.timeZone`
+ *   (default: the system time zone) before comparison, so `"day"` compares
+ *   calendar days in that zone, not raw epoch buckets.
+ * - `"month"` requires the same month AND year, matching `areDateTimesEqualBy`.
+ * - Returns false for an unsupported unit or invalid input.
+ *
+ * Mapping from date-fns (Decision 5, `context/roadmap/issues/J.md`):
+ * - `isSameDay(a, b)` → `areUnixEqualBy(a, b, "day")`
+ * - `isSameMonth(a, b)` → `areUnixEqualBy(a, b, "month")`
+ * - `isSameYear(a, b)` → `areUnixEqualBy(a, b, "year")`
+ *
+ * @param value1 first Unix epoch value
+ * @param value2 second Unix epoch value
+ * @param unit Temporal.DateUnit | Temporal.TimeUnit to compare by
+ * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA), weekStartsOn ("monday" | "sunday")
+ * @returns true if both values share the same start-of-unit boundary, false on an unsupported unit or invalid input
+ *
+ * @example areUnixEqualBy(1710498000000, 1710503000000, "day", { timeZone: "UTC" }) // true (both fall on 2024-03-15 in UTC)
+ * @example areUnixEqualBy(1704067200000, 1735689600000, "year", { timeZone: "UTC" }) // false (2024-01-01 vs 2025-01-01)
+ * @example areUnixEqualBy(Number.NaN, 1710498000000, "day") // false
+ */
+export function areUnixEqualBy(value1, value2, unit, options) {
+    if (!isValidAmount(value1) || !isValidAmount(value2)) {
+        return false;
+    }
+    try {
+        const start1 = startOfUnix(value1, unit, options);
+        const start2 = startOfUnix(value2, unit, options);
+        return start1 !== null && start1 === start2;
+    }
+    catch {
+        return false;
+    }
+}

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

@@ -0,0 +1,4 @@
+export * from "./areUnixEqual.js";
+export * from "./areUnixEqualBy.js";
+export * from "./isAfterUnix.js";
+export * from "./isBeforeUnix.js";

package/dist/unix/compare/index.js

@@ -0,0 +1,4 @@
+export * from "./areUnixEqual.js";
+export * from "./areUnixEqualBy.js";
+export * from "./isAfterUnix.js";
+export * from "./isBeforeUnix.js";

package/dist/unix/compare/isAfterUnix.d.ts

@@ -0,0 +1,19 @@
+import type { UnixUnit } from "../validate/isValidUnixUnit.js";
+/**
+ * Return whether `value1` represents an instant strictly after `value2`.
+ *
+ * - Uses Temporal.Instant.compare to check ordering.
+ * - Returns false if either input is invalid.
+ *
+ * @param value1 first unix epoch value
+ * @param value2 second unix epoch value
+ * @param options optional: epochUnit ("seconds" | "milliseconds")
+ * @returns `true` if `value1` is after `value2`, otherwise `false`
+ *
+ * @example isAfterUnix(1706659200, 1704067200) // true
+ * @example isAfterUnix(1706659200, 1706659200) // false
+ * @example isAfterUnix(-1, 0) // false
+ */
+export declare function isAfterUnix(value1: number, value2: number, options?: {
+    epochUnit?: UnixUnit;
+}): boolean;

package/dist/unix/compare/isAfterUnix.js

@@ -0,0 +1,31 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidAmount } from "../../internal/index.js";
+/**
+ * Return whether `value1` represents an instant strictly after `value2`.
+ *
+ * - Uses Temporal.Instant.compare to check ordering.
+ * - Returns false if either input is invalid.
+ *
+ * @param value1 first unix epoch value
+ * @param value2 second unix epoch value
+ * @param options optional: epochUnit ("seconds" | "milliseconds")
+ * @returns `true` if `value1` is after `value2`, otherwise `false`
+ *
+ * @example isAfterUnix(1706659200, 1704067200) // true
+ * @example isAfterUnix(1706659200, 1706659200) // false
+ * @example isAfterUnix(-1, 0) // false
+ */
+export function isAfterUnix(value1, value2, options) {
+    const epochUnit = options?.epochUnit ?? "milliseconds";
+    if (!isValidAmount(value1) || !isValidAmount(value2)) {
+        return false;
+    }
+    try {
+        const instant1 = Temporal.Instant.fromEpochMilliseconds(epochUnit === "seconds" ? value1 * 1000 : value1);
+        const instant2 = Temporal.Instant.fromEpochMilliseconds(epochUnit === "seconds" ? value2 * 1000 : value2);
+        return Temporal.Instant.compare(instant1, instant2) === 1;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/unix/compare/isBeforeUnix.d.ts

@@ -0,0 +1,21 @@
+import type { UnixUnit } from "../validate/isValidUnixUnit.js";
+/**
+ * Return whether `value1` represents an instant strictly before `value2`.
+ *
+ * - Uses Temporal.Instant.compare to check ordering.
+ * - Returns false if either input is invalid.
+ *
+ * @param value1 first unix epoch value
+ * @param value2 second unix epoch value
+ * @param options optional: epochUnit ("seconds" | "milliseconds")
+ * @returns `true` if `value1` is before `value2`, otherwise `false`
+ *
+ * @example isBeforeUnix(1704067200, 1706659200) // true
+ * @example isBeforeUnix(1706659200, 1706659200) // false
+ * @example isBeforeUnix(-1, 0) // true (1969-12-31T23:59:59.999Z is before 1970-01-01T00:00:00Z)
+ * @example isBeforeUnix('invalid', 1704067200000) // false
+ * @example isBeforeUnix(1704067200000, 'invalid') // false
+ */
+export declare function isBeforeUnix(value1: number, value2: number, options?: {
+    epochUnit?: UnixUnit;
+}): boolean;

package/dist/unix/compare/isBeforeUnix.js

@@ -0,0 +1,33 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidAmount } from "../../internal/index.js";
+/**
+ * Return whether `value1` represents an instant strictly before `value2`.
+ *
+ * - Uses Temporal.Instant.compare to check ordering.
+ * - Returns false if either input is invalid.
+ *
+ * @param value1 first unix epoch value
+ * @param value2 second unix epoch value
+ * @param options optional: epochUnit ("seconds" | "milliseconds")
+ * @returns `true` if `value1` is before `value2`, otherwise `false`
+ *
+ * @example isBeforeUnix(1704067200, 1706659200) // true
+ * @example isBeforeUnix(1706659200, 1706659200) // false
+ * @example isBeforeUnix(-1, 0) // true (1969-12-31T23:59:59.999Z is before 1970-01-01T00:00:00Z)
+ * @example isBeforeUnix('invalid', 1704067200000) // false
+ * @example isBeforeUnix(1704067200000, 'invalid') // false
+ */
+export function isBeforeUnix(value1, value2, options) {
+    const epochUnit = options?.epochUnit ?? "milliseconds";
+    if (!isValidAmount(value1) || !isValidAmount(value2)) {
+        return false;
+    }
+    try {
+        const instant1 = Temporal.Instant.fromEpochMilliseconds(epochUnit === "seconds" ? value1 * 1000 : value1);
+        const instant2 = Temporal.Instant.fromEpochMilliseconds(epochUnit === "seconds" ? value2 * 1000 : value2);
+        return Temporal.Instant.compare(instant1, instant2) === -1;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/unix/convert/convertUnixToPlainDate.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Convert a Unix timestamp to a plain date string in the format "YYYY-MM-DD".
+ *
+ * - Converts to PlainDate using the specified or system timezone.
+ * - Validates epoch unit ("seconds" | "milliseconds").
+ * - Returns "" for invalid input.
+ *
+ * @param unix Unix timestamp (number)
+ * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA)
+ * @returns plain date string in "YYYY-MM-DD" format or "" on invalid input
+ *
+ * @example convertUnixToPlainDate(1709164800000) // "2024-02-29"
+ * @example convertUnixToPlainDate(1709164800, { epochUnit: "seconds" }) // "2024-02-29"
+ * @example convertUnixToPlainDate(-1) // "1969-12-31"
+ */
+export declare function convertUnixToPlainDate(unix: number, options?: {
+    epochUnit?: "seconds" | "milliseconds";
+    timeZone?: string;
+}): string;

package/dist/unix/convert/convertUnixToPlainDate.js

@@ -0,0 +1,38 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidTimeZone } from "../../zoned/index.js";
+import { getSystemTimeZone } from "../../zoned/get/index.js";
+import { isValidUnixMilliseconds, isValidUnixSeconds, isValidUnixUnit, } from "../validate/index.js";
+/**
+ * Convert a Unix timestamp to a plain date string in the format "YYYY-MM-DD".
+ *
+ * - Converts to PlainDate using the specified or system timezone.
+ * - Validates epoch unit ("seconds" | "milliseconds").
+ * - Returns "" for invalid input.
+ *
+ * @param unix Unix timestamp (number)
+ * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA)
+ * @returns plain date string in "YYYY-MM-DD" format or "" on invalid input
+ *
+ * @example convertUnixToPlainDate(1709164800000) // "2024-02-29"
+ * @example convertUnixToPlainDate(1709164800, { epochUnit: "seconds" }) // "2024-02-29"
+ * @example convertUnixToPlainDate(-1) // "1969-12-31"
+ */
+export function convertUnixToPlainDate(unix, options) {
+    const { epochUnit = "milliseconds", timeZone = getSystemTimeZone() } = options ?? {};
+    if (!isValidUnixUnit(epochUnit))
+        return "";
+    if (!isValidTimeZone(timeZone))
+        return "";
+    try {
+        if ((epochUnit === "milliseconds" && !isValidUnixMilliseconds(unix)) ||
+            (epochUnit === "seconds" && !isValidUnixSeconds(unix))) {
+            return "";
+        }
+        const instant = Temporal.Instant.fromEpochMilliseconds(epochUnit === "seconds" ? unix * 1000 : unix);
+        const zonedDateTime = instant.toZonedDateTimeISO(timeZone);
+        return zonedDateTime.toPlainDate().toString();
+    }
+    catch {
+        return "";
+    }
+}

package/dist/unix/convert/convertUnixToPlainDateTime.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Convert a Unix timestamp to a plain datetime string in the format "YYYY-MM-DDTHH:mm:ss".
+ *
+ * - Converts to PlainDateTime using the specified or system timezone.
+ * - Validates epoch unit ("seconds" | "milliseconds").
+ * - Returns "" for invalid input.
+ *
+ * @param unix Unix timestamp (number)
+ * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA)
+ * @returns plain datetime string in "YYYY-MM-DDTHH:mm:ss" format or "" on invalid input
+ *
+ * @example convertUnixToPlainDateTime(1709164800000) // "2024-02-29T00:00:00"
+ * @example convertUnixToPlainDateTime(1709164800, { epochUnit: "seconds" }) // "2024-02-29T00:00:00"
+ * @example convertUnixToPlainDateTime(-1) // "1969-12-31T23:59:59.999"
+ */
+export declare function convertUnixToPlainDateTime(unix: number, options?: {
+    epochUnit?: "seconds" | "milliseconds";
+    timeZone?: string;
+}): string;

package/dist/unix/convert/convertUnixToPlainDateTime.js

@@ -0,0 +1,38 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidTimeZone } from "../../zoned/index.js";
+import { getSystemTimeZone } from "../../zoned/get/index.js";
+import { isValidUnixMilliseconds, isValidUnixSeconds, isValidUnixUnit, } from "../validate/index.js";
+/**
+ * Convert a Unix timestamp to a plain datetime string in the format "YYYY-MM-DDTHH:mm:ss".
+ *
+ * - Converts to PlainDateTime using the specified or system timezone.
+ * - Validates epoch unit ("seconds" | "milliseconds").
+ * - Returns "" for invalid input.
+ *
+ * @param unix Unix timestamp (number)
+ * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA)
+ * @returns plain datetime string in "YYYY-MM-DDTHH:mm:ss" format or "" on invalid input
+ *
+ * @example convertUnixToPlainDateTime(1709164800000) // "2024-02-29T00:00:00"
+ * @example convertUnixToPlainDateTime(1709164800, { epochUnit: "seconds" }) // "2024-02-29T00:00:00"
+ * @example convertUnixToPlainDateTime(-1) // "1969-12-31T23:59:59.999"
+ */
+export function convertUnixToPlainDateTime(unix, options) {
+    const { epochUnit = "milliseconds", timeZone = getSystemTimeZone() } = options ?? {};
+    if (!isValidUnixUnit(epochUnit))
+        return "";
+    if (!isValidTimeZone(timeZone))
+        return "";
+    try {
+        if ((epochUnit === "milliseconds" && !isValidUnixMilliseconds(unix)) ||
+            (epochUnit === "seconds" && !isValidUnixSeconds(unix))) {
+            return "";
+        }
+        const instant = Temporal.Instant.fromEpochMilliseconds(epochUnit === "seconds" ? unix * 1000 : unix);
+        const zonedDateTime = instant.toZonedDateTimeISO(timeZone);
+        return zonedDateTime.toPlainDateTime().toString();
+    }
+    catch {
+        return "";
+    }
+}

package/dist/unix/convert/convertUnixToPlainTime.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Convert a Unix timestamp to a plain time string in the format "HH:mm:ss".
+ *
+ * - Converts to PlainTime using the specified or system timezone.
+ * - Validates epoch unit ("seconds" | "milliseconds").
+ * - Returns "" for invalid input.
+ *
+ * @param unix Unix timestamp (number)
+ * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA)
+ * @returns plain time string in "HH:mm:ss" format or "" on invalid input
+ *
+ * @example convertUnixToPlainTime(1706659200000) // "00:00:00"
+ * @example convertUnixToPlainTime(1706659200, { epochUnit: "seconds" }) // "00:00:00"
+ * @example convertUnixToPlainTime(-1) // "23:59:59.999"
+ */
+export declare function convertUnixToPlainTime(unix: number, options?: {
+    epochUnit?: "seconds" | "milliseconds";
+    timeZone?: string;
+}): string;

package/dist/unix/convert/convertUnixToPlainTime.js

@@ -0,0 +1,38 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidTimeZone } from "../../zoned/index.js";
+import { getSystemTimeZone } from "../../zoned/get/index.js";
+import { isValidUnixMilliseconds, isValidUnixSeconds, isValidUnixUnit, } from "../validate/index.js";
+/**
+ * Convert a Unix timestamp to a plain time string in the format "HH:mm:ss".
+ *
+ * - Converts to PlainTime using the specified or system timezone.
+ * - Validates epoch unit ("seconds" | "milliseconds").
+ * - Returns "" for invalid input.
+ *
+ * @param unix Unix timestamp (number)
+ * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA)
+ * @returns plain time string in "HH:mm:ss" format or "" on invalid input
+ *
+ * @example convertUnixToPlainTime(1706659200000) // "00:00:00"
+ * @example convertUnixToPlainTime(1706659200, { epochUnit: "seconds" }) // "00:00:00"
+ * @example convertUnixToPlainTime(-1) // "23:59:59.999"
+ */
+export function convertUnixToPlainTime(unix, options) {
+    const { epochUnit = "milliseconds", timeZone = getSystemTimeZone() } = options ?? {};
+    if (!isValidUnixUnit(epochUnit))
+        return "";
+    if (!isValidTimeZone(timeZone))
+        return "";
+    try {
+        if ((epochUnit === "milliseconds" && !isValidUnixMilliseconds(unix)) ||
+            (epochUnit === "seconds" && !isValidUnixSeconds(unix))) {
+            return "";
+        }
+        const instant = Temporal.Instant.fromEpochMilliseconds(epochUnit === "seconds" ? unix * 1000 : unix);
+        const zonedDateTime = instant.toZonedDateTimeISO(timeZone);
+        return zonedDateTime.toPlainTime().toString();
+    }
+    catch {
+        return "";
+    }
+}

package/dist/unix/convert/convertUnixToUtc.d.ts

@@ -0,0 +1,17 @@
+import { type UnixUnit } from "../validate/isValidUnixUnit.js";
+/**
+ * Convert a unix epoch value to a UTC Instant ISO string.
+ *
+ * - Converts to UTC Instant using Temporal.Instant.
+ * - Validates value and epoch unit ("seconds" | "milliseconds").
+ * - Returns "" for invalid input.
+ *
+ * @param value epoch value (number)
+ * @param unit optional unit, "seconds" or "milliseconds"
+ * @returns UTC Instant string or "" on invalid
+ *
+ * @example convertUnixToUtc(1709164800000) // "2024-02-29T00:00:00Z"
+ * @example convertUnixToUtc(1709164800, "seconds") // "2024-02-29T00:00:00Z"
+ * @example convertUnixToUtc(-1) // "1969-12-31T23:59:59.999Z"
+ */
+export declare function convertUnixToUtc(value: number, ...unitInput: [unit?: UnixUnit]): string;