@burglekitt/gmt/dist/unix/format/formatCalendarUnix.d.ts

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

export interface FormatCalendarUnixOptions {
    epochUnit?: "milliseconds" | "seconds";
    reference?: string | number;
    /**
     * IANA timezone used for both the calendar-day comparison and the
     * rendered clock time. Resolved via `normalizeTimeZone` — `"local"` for
     * the system zone, an invalid/omitted value falls back to `"UTC"`.
     */
    timeZone?: string;
    /** `Intl.DateTimeFormatOptions` `timeStyle` for the time-of-day half. */
    timeStyle?: "short" | "medium" | "full";
}
/**
 * Format a unix epoch value as a relative day label plus time-of-day, e.g.
 * "Tomorrow at 2:30 PM" — the unix counterpart of `formatCalendar`. See
 * that function's JSDoc for the day-label/threshold/connector design; this
 * variant compares calendar days and renders the clock time in `timeZone`
 * (default `"UTC"`).
 *
 * @param value unix epoch (string or number, per `epochUnit`) to format
 * @param locale optional: BCP 47 locale tag
 * @param options optional: { epochUnit, reference, timeZone, timeStyle }
 * @returns the formatted calendar string, or "" on invalid input
 *
 * @example formatCalendarUnix(1710685845000, "en-US", { epochUnit: "milliseconds", timeZone: "America/New_York" }) // day label + time relative to "now", or the absolute fallback beyond the ±6-day threshold
 * @example formatCalendarUnix(value, "en-US", { reference: 1710685000000 }) // e.g. "tomorrow at 2:30 PM"
 * @example formatCalendarUnix("not-a-number") // ""
 */
export declare function formatCalendarUnix(value: string | number, locale?: string, options?: FormatCalendarUnixOptions): string;