@burglekitt/gmt/dist/unix/parse/parseUnitFromUnix.d.ts

Temporal-based date and time utilities with timezone support and polyfill integration

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;