@northguild/gmt 1.14.2

package/dist/unix/interval/validate/index.js

@@ -0,0 +1 @@
+export * from "./isValidUnixInterval.js";

package/dist/unix/interval/validate/isValidUnixInterval.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Return true if `start` and `end` form a valid Unix interval — both finite numbers
+ * and `start <= end`.
+ *
+ * - Both inputs must be numbers (or numeric strings that coerce to finite numbers).
+ * - Equal `start === end` is valid.
+ * - Non-finite values (NaN, Infinity) return `false`.
+ *
+ * @param start Unix epoch value (seconds or milliseconds) — interval start
+ * @param end Unix epoch value (seconds or milliseconds) — interval end
+ * @returns true if start and end form a valid Unix interval, or false on invalid input
+ *
+ * @example isValidUnixInterval(0, 1700000000) // true
+ * @example isValidUnixInterval(1000, 1000) // true
+ * @example isValidUnixInterval(1700000000, 0) // false
+ * @example isValidUnixInterval("0", "1700000000") // true
+ */
+export declare function isValidUnixInterval(start: number | string, end: number | string): boolean;

package/dist/unix/interval/validate/isValidUnixInterval.js

@@ -0,0 +1,31 @@
+/**
+ * Return true if `start` and `end` form a valid Unix interval — both finite numbers
+ * and `start <= end`.
+ *
+ * - Both inputs must be numbers (or numeric strings that coerce to finite numbers).
+ * - Equal `start === end` is valid.
+ * - Non-finite values (NaN, Infinity) return `false`.
+ *
+ * @param start Unix epoch value (seconds or milliseconds) — interval start
+ * @param end Unix epoch value (seconds or milliseconds) — interval end
+ * @returns true if start and end form a valid Unix interval, or false on invalid input
+ *
+ * @example isValidUnixInterval(0, 1700000000) // true
+ * @example isValidUnixInterval(1000, 1000) // true
+ * @example isValidUnixInterval(1700000000, 0) // false
+ * @example isValidUnixInterval("0", "1700000000") // true
+ */
+export function isValidUnixInterval(start, end) {
+    if (typeof start !== "number" && typeof start !== "string") {
+        return false;
+    }
+    if (typeof end !== "number" && typeof end !== "string") {
+        return false;
+    }
+    const n1 = typeof start === "number" ? start : Number(start);
+    const n2 = typeof end === "number" ? end : Number(end);
+    if (!Number.isFinite(n1) || !Number.isFinite(n2)) {
+        return false;
+    }
+    return n1 <= n2;
+}

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

@@ -0,0 +1,12 @@
+export * from "./parseDateFromUnix.js";
+export * from "./parseDayFromUnix.js";
+export * from "./parseDayOfWeekFromUnix.js";
+export * from "./parseHourFromUnix.js";
+export * from "./parseMicrosecondFromUnix.js";
+export * from "./parseMonthFromUnix.js";
+export * from "./parseNanosecondFromUnix.js";
+export * from "./parseSecondFromUnix.js";
+export * from "./parseTimeFromUnix.js";
+export * from "./parseUnitFromUnix.js";
+export * from "./parseWeekFromUnix.js";
+export * from "./parseYearFromUnix.js";

package/dist/unix/parse/index.js

@@ -0,0 +1,12 @@
+export * from "./parseDateFromUnix.js";
+export * from "./parseDayFromUnix.js";
+export * from "./parseDayOfWeekFromUnix.js";
+export * from "./parseHourFromUnix.js";
+export * from "./parseMicrosecondFromUnix.js";
+export * from "./parseMonthFromUnix.js";
+export * from "./parseNanosecondFromUnix.js";
+export * from "./parseSecondFromUnix.js";
+export * from "./parseTimeFromUnix.js";
+export * from "./parseUnitFromUnix.js";
+export * from "./parseWeekFromUnix.js";
+export * from "./parseYearFromUnix.js";

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

@@ -0,0 +1,20 @@
+import { type UnixUnit } from "../validate/index.js";
+/**
+ * Extract the date portion from a unix epoch value.
+ *
+ * - Converts to ZonedDateTime then extracts the PlainDate.
+ * - Uses system timezone if not specified.
+ * - Returns "" for invalid input.
+ *
+ * @param value unix epoch in milliseconds or seconds (number)
+ * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA)
+ * @returns ISO date string (e.g., "2024-03-17") or "" on invalid input
+ *
+ * @example parseDateFromUnix(1700000000000) // "2023-11-15"
+ * @example parseDateFromUnix(1700000000, { epochUnit: "seconds" }) // "2023-11-15"
+ * @example parseDateFromUnix(-86400, { epochUnit: "seconds" }) // "1969-12-31"
+ */
+export declare function parseDateFromUnix(value: number, options?: {
+    epochUnit?: UnixUnit;
+    timeZone?: string;
+}): string;

package/dist/unix/parse/parseDateFromUnix.js

@@ -0,0 +1,45 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { getSystemTimeZone } from "../../zoned/get/index.js";
+import { convertUnixToZoned } from "../convert/index.js";
+import { isValidUnixMilliseconds, isValidUnixSeconds, } from "../validate/index.js";
+/**
+ * Extract the date portion from a unix epoch value.
+ *
+ * - Converts to ZonedDateTime then extracts the PlainDate.
+ * - Uses system timezone if not specified.
+ * - Returns "" for invalid input.
+ *
+ * @param value unix epoch in milliseconds or seconds (number)
+ * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA)
+ * @returns ISO date string (e.g., "2024-03-17") or "" on invalid input
+ *
+ * @example parseDateFromUnix(1700000000000) // "2023-11-15"
+ * @example parseDateFromUnix(1700000000, { epochUnit: "seconds" }) // "2023-11-15"
+ * @example parseDateFromUnix(-86400, { epochUnit: "seconds" }) // "1969-12-31"
+ */
+export function parseDateFromUnix(value, options) {
+    const epochUnit = options?.epochUnit ?? "milliseconds";
+    if (epochUnit === "seconds") {
+        if (!isValidUnixSeconds(value))
+            return "";
+    }
+    else {
+        if (!isValidUnixMilliseconds(value))
+            return "";
+    }
+    const timeZone = options?.timeZone ?? getSystemTimeZone();
+    if (!timeZone)
+        return "";
+    const zoned = epochUnit
+        ? convertUnixToZoned(value, timeZone, epochUnit)
+        : convertUnixToZoned(value, timeZone);
+    if (!zoned)
+        return "";
+    try {
+        const zdt = Temporal.ZonedDateTime.from(zoned);
+        return zdt.toPlainDate().toString();
+    }
+    catch {
+        return "";
+    }
+}

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

@@ -0,0 +1,18 @@
+import type { UnixUnit } from "../validate/index.js";
+/**
+ * Return the day of month (1-31) from a unix epoch value.
+ *
+ * - Delegates to {@link parseUnitFromUnix} with unit "day".
+ * - Returns "" for invalid input.
+ *
+ * @param value unix epoch in milliseconds or seconds (number or string)
+ * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA)
+ * @returns Day (01-31) or "" on invalid input
+ *
+ * @example parseDayFromUnix(1700000000000) // "15"
+ * @example parseDayFromUnix(-86400, { epochUnit: "seconds" }) // "31"
+ */
+export declare function parseDayFromUnix(value: number | string, options?: {
+    epochUnit?: UnixUnit;
+    timeZone?: string;
+}): string;

package/dist/unix/parse/parseDayFromUnix.js

@@ -0,0 +1,17 @@
+import { parseUnitFromUnix } from "./parseUnitFromUnix.js";
+/**
+ * Return the day of month (1-31) from a unix epoch value.
+ *
+ * - Delegates to {@link parseUnitFromUnix} with unit "day".
+ * - Returns "" for invalid input.
+ *
+ * @param value unix epoch in milliseconds or seconds (number or string)
+ * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA)
+ * @returns Day (01-31) or "" on invalid input
+ *
+ * @example parseDayFromUnix(1700000000000) // "15"
+ * @example parseDayFromUnix(-86400, { epochUnit: "seconds" }) // "31"
+ */
+export function parseDayFromUnix(value, options) {
+    return parseUnitFromUnix(value, "day", options);
+}

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

@@ -0,0 +1,18 @@
+import { type UnixUnit } from "../validate/index.js";
+/**
+ * Return the day of week (1-7) from a unix epoch value.
+ *
+ * - Monday=1 through Sunday=7.
+ * - Returns null for invalid input.
+ *
+ * @param value unix epoch in milliseconds or seconds (number or string)
+ * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA)
+ * @returns Day of week (1-7) or null on invalid input
+ *
+ * @example parseDayOfWeekFromUnix(1704067200000) // 1
+ * @example parseDayOfWeekFromUnix(-86400, { epochUnit: "seconds" }) // 2
+ */
+export declare function parseDayOfWeekFromUnix(value: number | string, options?: {
+    epochUnit?: UnixUnit;
+    timeZone?: string;
+}): number | null;

package/dist/unix/parse/parseDayOfWeekFromUnix.js

@@ -0,0 +1,44 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { getSystemTimeZone } from "../../zoned/get/index.js";
+import { convertUnixToZoned } from "../convert/index.js";
+import { isValidUnixMilliseconds, isValidUnixSeconds, } from "../validate/index.js";
+/**
+ * Return the day of week (1-7) from a unix epoch value.
+ *
+ * - Monday=1 through Sunday=7.
+ * - Returns null for invalid input.
+ *
+ * @param value unix epoch in milliseconds or seconds (number or string)
+ * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA)
+ * @returns Day of week (1-7) or null on invalid input
+ *
+ * @example parseDayOfWeekFromUnix(1704067200000) // 1
+ * @example parseDayOfWeekFromUnix(-86400, { epochUnit: "seconds" }) // 2
+ */
+export function parseDayOfWeekFromUnix(value, options) {
+    const numValue = typeof value === "string" ? Number(value) : value;
+    const epochUnit = options?.epochUnit ?? "milliseconds";
+    if (epochUnit === "seconds") {
+        if (!isValidUnixSeconds(numValue))
+            return null;
+    }
+    else {
+        if (!isValidUnixMilliseconds(numValue))
+            return null;
+    }
+    const timeZone = options?.timeZone ?? getSystemTimeZone();
+    if (!timeZone)
+        return null;
+    const zoned = typeof options?.epochUnit === "undefined"
+        ? convertUnixToZoned(numValue, timeZone)
+        : convertUnixToZoned(numValue, timeZone, options.epochUnit);
+    if (!zoned)
+        return null;
+    try {
+        const zdt = Temporal.ZonedDateTime.from(zoned);
+        return zdt.dayOfWeek;
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -0,0 +1,18 @@
+import type { UnixUnit } from "../validate/index.js";
+/**
+ * Return the hour (0-23) from a unix epoch value.
+ *
+ * - Delegates to {@link parseUnitFromUnix} with unit "hour".
+ * - Returns "" for invalid input.
+ *
+ * @param value unix epoch in milliseconds or seconds (number or string)
+ * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA)
+ * @returns Hour (00-23) or "" on invalid input
+ *
+ * @example parseHourFromUnix(1700000000000) // "05"
+ * @example parseHourFromUnix(-86400, { epochUnit: "seconds" }) // "00"
+ */
+export declare function parseHourFromUnix(value: number | string, options?: {
+    epochUnit?: UnixUnit;
+    timeZone?: string;
+}): string;

package/dist/unix/parse/parseHourFromUnix.js

@@ -0,0 +1,17 @@
+import { parseUnitFromUnix } from "./parseUnitFromUnix.js";
+/**
+ * Return the hour (0-23) from a unix epoch value.
+ *
+ * - Delegates to {@link parseUnitFromUnix} with unit "hour".
+ * - Returns "" for invalid input.
+ *
+ * @param value unix epoch in milliseconds or seconds (number or string)
+ * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA)
+ * @returns Hour (00-23) or "" on invalid input
+ *
+ * @example parseHourFromUnix(1700000000000) // "05"
+ * @example parseHourFromUnix(-86400, { epochUnit: "seconds" }) // "00"
+ */
+export function parseHourFromUnix(value, options) {
+    return parseUnitFromUnix(value, "hour", options);
+}

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

@@ -0,0 +1,18 @@
+import type { UnixUnit } from "../validate/index.js";
+/**
+ * Return the microsecond (0-999) from a unix epoch value.
+ *
+ * - Delegates to {@link parseUnitFromUnix} with unit "microsecond".
+ * - Returns "" for invalid input.
+ *
+ * @param value unix epoch in milliseconds or seconds (number or string)
+ * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA)
+ * @returns Microsecond (000-999) or "" on invalid input
+ *
+ * @example parseMicrosecondFromUnix(1700000000000) // "000"
+ * @example parseMicrosecondFromUnix(-86400, { epochUnit: "seconds" }) // "000"
+ */
+export declare function parseMicrosecondFromUnix(value: number | string, options?: {
+    epochUnit?: UnixUnit;
+    timeZone?: string;
+}): string;

package/dist/unix/parse/parseMicrosecondFromUnix.js

@@ -0,0 +1,17 @@
+import { parseUnitFromUnix } from "./parseUnitFromUnix.js";
+/**
+ * Return the microsecond (0-999) from a unix epoch value.
+ *
+ * - Delegates to {@link parseUnitFromUnix} with unit "microsecond".
+ * - Returns "" for invalid input.
+ *
+ * @param value unix epoch in milliseconds or seconds (number or string)
+ * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA)
+ * @returns Microsecond (000-999) or "" on invalid input
+ *
+ * @example parseMicrosecondFromUnix(1700000000000) // "000"
+ * @example parseMicrosecondFromUnix(-86400, { epochUnit: "seconds" }) // "000"
+ */
+export function parseMicrosecondFromUnix(value, options) {
+    return parseUnitFromUnix(value, "microsecond", options);
+}

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

@@ -0,0 +1,18 @@
+import type { UnixUnit } from "../validate/index.js";
+/**
+ * Return the millisecond (0-999) from a unix epoch value.
+ *
+ * - Delegates to {@link parseUnitFromUnix} with unit "millisecond".
+ * - Returns "" for invalid input.
+ *
+ * @param value unix epoch in milliseconds or seconds (number or string)
+ * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA)
+ * @returns Millisecond (000-999) or "" on invalid input
+ *
+ * @example parseMillisecondFromUnix(1700000000000) // "000"
+ * @example parseMillisecondFromUnix(-86400, { epochUnit: "seconds" }) // "000"
+ */
+export declare function parseMillisecondFromUnix(value: number | string, options?: {
+    epochUnit?: UnixUnit;
+    timeZone?: string;
+}): string;

package/dist/unix/parse/parseMillisecondFromUnix.js

@@ -0,0 +1,17 @@
+import { parseUnitFromUnix } from "./parseUnitFromUnix.js";
+/**
+ * Return the millisecond (0-999) from a unix epoch value.
+ *
+ * - Delegates to {@link parseUnitFromUnix} with unit "millisecond".
+ * - Returns "" for invalid input.
+ *
+ * @param value unix epoch in milliseconds or seconds (number or string)
+ * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA)
+ * @returns Millisecond (000-999) or "" on invalid input
+ *
+ * @example parseMillisecondFromUnix(1700000000000) // "000"
+ * @example parseMillisecondFromUnix(-86400, { epochUnit: "seconds" }) // "000"
+ */
+export function parseMillisecondFromUnix(value, options) {
+    return parseUnitFromUnix(value, "millisecond", options);
+}

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

@@ -0,0 +1,18 @@
+import type { UnixUnit } from "../validate/index.js";
+/**
+ * Return the minute (0-59) from a unix epoch value.
+ *
+ * - Delegates to {@link parseUnitFromUnix} with unit "minute".
+ * - Returns "" for invalid input.
+ *
+ * @param value unix epoch in milliseconds or seconds (number or string)
+ * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA)
+ * @returns Minute (00-59) or "" on invalid input
+ *
+ * @example parseMinuteFromUnix(1700000000000) // "26"
+ * @example parseMinuteFromUnix(-86400, { epochUnit: "seconds" }) // "00"
+ */
+export declare function parseMinuteFromUnix(value: number | string, options?: {
+    epochUnit?: UnixUnit;
+    timeZone?: string;
+}): string;

package/dist/unix/parse/parseMinuteFromUnix.js

@@ -0,0 +1,17 @@
+import { parseUnitFromUnix } from "./parseUnitFromUnix.js";
+/**
+ * Return the minute (0-59) from a unix epoch value.
+ *
+ * - Delegates to {@link parseUnitFromUnix} with unit "minute".
+ * - Returns "" for invalid input.
+ *
+ * @param value unix epoch in milliseconds or seconds (number or string)
+ * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA)
+ * @returns Minute (00-59) or "" on invalid input
+ *
+ * @example parseMinuteFromUnix(1700000000000) // "26"
+ * @example parseMinuteFromUnix(-86400, { epochUnit: "seconds" }) // "00"
+ */
+export function parseMinuteFromUnix(value, options) {
+    return parseUnitFromUnix(value, "minute", options);
+}

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

@@ -0,0 +1,19 @@
+import type { UnixUnit } from "../validate/index.js";
+/**
+ * Return the month (1-12) from a unix epoch value.
+ *
+ * - Delegates to {@link parseUnitFromUnix} with unit "month".
+ * - Returns "" for invalid input.
+ *
+ * @param value unix epoch in milliseconds or seconds (number or string)
+ * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA)
+ * @returns Month (01-12) or "" on invalid input
+ *
+ * @example parseMonthFromUnix(1700000000000) // "09"
+ * @example parseMonthFromUnix(1704067200000) // "01"
+ * @example parseMonthFromUnix(-86400, { epochUnit: "seconds" }) // "12"
+ */
+export declare function parseMonthFromUnix(value: number | string, options?: {
+    epochUnit?: UnixUnit;
+    timeZone?: string;
+}): string;

package/dist/unix/parse/parseMonthFromUnix.js

@@ -0,0 +1,18 @@
+import { parseUnitFromUnix } from "./parseUnitFromUnix.js";
+/**
+ * Return the month (1-12) from a unix epoch value.
+ *
+ * - Delegates to {@link parseUnitFromUnix} with unit "month".
+ * - Returns "" for invalid input.
+ *
+ * @param value unix epoch in milliseconds or seconds (number or string)
+ * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA)
+ * @returns Month (01-12) or "" on invalid input
+ *
+ * @example parseMonthFromUnix(1700000000000) // "09"
+ * @example parseMonthFromUnix(1704067200000) // "01"
+ * @example parseMonthFromUnix(-86400, { epochUnit: "seconds" }) // "12"
+ */
+export function parseMonthFromUnix(value, options) {
+    return parseUnitFromUnix(value, "month", options);
+}

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

@@ -0,0 +1,18 @@
+import type { UnixUnit } from "../validate/index.js";
+/**
+ * Return the nanosecond (0-999) from a unix epoch value.
+ *
+ * - Delegates to {@link parseUnitFromUnix} with unit "nanosecond".
+ * - Returns "" for invalid input.
+ *
+ * @param value unix epoch in milliseconds or seconds (number or string)
+ * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA)
+ * @returns Nanosecond (000-999) or "" on invalid input
+ *
+ * @example parseNanosecondFromUnix(1700000000000) // "000000000"
+ * @example parseNanosecondFromUnix(-86400, { epochUnit: "seconds" }) // "000000000"
+ */
+export declare function parseNanosecondFromUnix(value: number | string, options?: {
+    epochUnit?: UnixUnit;
+    timeZone?: string;
+}): string;

package/dist/unix/parse/parseNanosecondFromUnix.js

@@ -0,0 +1,17 @@
+import { parseUnitFromUnix } from "./parseUnitFromUnix.js";
+/**
+ * Return the nanosecond (0-999) from a unix epoch value.
+ *
+ * - Delegates to {@link parseUnitFromUnix} with unit "nanosecond".
+ * - Returns "" for invalid input.
+ *
+ * @param value unix epoch in milliseconds or seconds (number or string)
+ * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA)
+ * @returns Nanosecond (000-999) or "" on invalid input
+ *
+ * @example parseNanosecondFromUnix(1700000000000) // "000000000"
+ * @example parseNanosecondFromUnix(-86400, { epochUnit: "seconds" }) // "000000000"
+ */
+export function parseNanosecondFromUnix(value, options) {
+    return parseUnitFromUnix(value, "nanosecond", options);
+}

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

@@ -0,0 +1,18 @@
+import type { UnixUnit } from "../validate/index.js";
+/**
+ * Return the second (0-59) from a unix epoch value.
+ *
+ * - Delegates to {@link parseUnitFromUnix} with unit "second".
+ * - Returns "" for invalid input.
+ *
+ * @param value unix epoch in milliseconds or seconds (number or string)
+ * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA)
+ * @returns Second (00-59) or "" on invalid input
+ *
+ * @example parseSecondFromUnix(1700000000000) // "26"
+ * @example parseSecondFromUnix(-86400, { epochUnit: "seconds" }) // "00"
+ */
+export declare function parseSecondFromUnix(value: number | string, options?: {
+    epochUnit?: UnixUnit;
+    timeZone?: string;
+}): string;

package/dist/unix/parse/parseSecondFromUnix.js

@@ -0,0 +1,17 @@
+import { parseUnitFromUnix } from "./parseUnitFromUnix.js";
+/**
+ * Return the second (0-59) from a unix epoch value.
+ *
+ * - Delegates to {@link parseUnitFromUnix} with unit "second".
+ * - Returns "" for invalid input.
+ *
+ * @param value unix epoch in milliseconds or seconds (number or string)
+ * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA)
+ * @returns Second (00-59) or "" on invalid input
+ *
+ * @example parseSecondFromUnix(1700000000000) // "26"
+ * @example parseSecondFromUnix(-86400, { epochUnit: "seconds" }) // "00"
+ */
+export function parseSecondFromUnix(value, options) {
+    return parseUnitFromUnix(value, "second", options);
+}

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

@@ -0,0 +1,20 @@
+import { type UnixUnit } from "../validate/index.js";
+/**
+ * Extract the time portion from a unix epoch value.
+ *
+ * - Converts to ZonedDateTime then extracts the PlainTime.
+ * - Uses system timezone if not specified.
+ * - Returns "" for invalid input.
+ *
+ * @param value unix epoch in milliseconds or seconds (number)
+ * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA)
+ * @returns ISO time string (e.g., "14:30:45") or "" on invalid input
+ *
+ * @example parseTimeFromUnix(1700000000000) // "04:13:20"
+ * @example parseTimeFromUnix(1700000000, { epochUnit: "seconds" }) // "04:13:20"
+ * @example parseTimeFromUnix(-86400, { epochUnit: "seconds" }) // "00:00:00"
+ */
+export declare function parseTimeFromUnix(value: number, options?: {
+    epochUnit?: UnixUnit;
+    timeZone?: string;
+}): string;

package/dist/unix/parse/parseTimeFromUnix.js

@@ -0,0 +1,45 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { getSystemTimeZone } from "../../zoned/get/index.js";
+import { convertUnixToZoned } from "../convert/index.js";
+import { isValidUnixMilliseconds, isValidUnixSeconds, } from "../validate/index.js";
+/**
+ * Extract the time portion from a unix epoch value.
+ *
+ * - Converts to ZonedDateTime then extracts the PlainTime.
+ * - Uses system timezone if not specified.
+ * - Returns "" for invalid input.
+ *
+ * @param value unix epoch in milliseconds or seconds (number)
+ * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA)
+ * @returns ISO time string (e.g., "14:30:45") or "" on invalid input
+ *
+ * @example parseTimeFromUnix(1700000000000) // "04:13:20"
+ * @example parseTimeFromUnix(1700000000, { epochUnit: "seconds" }) // "04:13:20"
+ * @example parseTimeFromUnix(-86400, { epochUnit: "seconds" }) // "00:00:00"
+ */
+export function parseTimeFromUnix(value, options) {
+    const epochUnit = options?.epochUnit ?? "milliseconds";
+    if (epochUnit === "seconds") {
+        if (!isValidUnixSeconds(value))
+            return "";
+    }
+    else {
+        if (!isValidUnixMilliseconds(value))
+            return "";
+    }
+    const timeZone = options?.timeZone ?? getSystemTimeZone();
+    if (!timeZone)
+        return "";
+    const zoned = options?.epochUnit
+        ? convertUnixToZoned(value, timeZone, options.epochUnit)
+        : convertUnixToZoned(value, timeZone);
+    if (!zoned)
+        return "";
+    try {
+        const zdt = Temporal.ZonedDateTime.from(zoned);
+        return zdt.toPlainTime().toString();
+    }
+    catch {
+        return "";
+    }
+}

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

@@ -0,0 +1,25 @@
+import { type UnixUnit } from "../validate/index.js";
+export type PlainNowUnit = "year" | "month" | "week" | "day" | "dayOfWeek" | "hour" | "minute" | "second" | "millisecond" | "microsecond" | "nanosecond";
+/**
+ * Extract a unit from a unix epoch value.
+ *
+ * - Valid units: "year", "month", "week", "day", "dayOfWeek", "hour", "minute", "second", "millisecond", "microsecond", "nanosecond".
+ * - Converts to ZonedDateTime then extracts the unit.
+ * - Returns "" for invalid input.
+ *
+ * @param value unix epoch in milliseconds or seconds (number or string)
+ * @param unit unit to extract (e.g. "year", "month", "hour")
+ * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA), weekStartsOn ("monday" | "sunday")
+ * @returns extracted unit value as string, or "" on invalid input
+ *
+ * @example parseUnitFromUnix(1700000000000, "year") // "2023"
+ * @example parseUnitFromUnix(1700000000, "hour", { epochUnit: "seconds" }) // "12"
+ * @example parseUnitFromUnix(1704067200000, "week") // "1"
+ * @example parseUnitFromUnix(1704067200000, "week", { weekStartsOn: "sunday" }) // "1"
+ * @example parseUnitFromUnix(-86400, { epochUnit: "seconds" }, "year") // "1969"
+ */
+export declare function parseUnitFromUnix(value: number | string, unit: PlainNowUnit, options?: {
+    epochUnit?: UnixUnit;
+    timeZone?: string;
+    weekStartsOn?: "monday" | "sunday";
+}): string;