@burglekitt/gmt/dist/zoned/format/formatRelativeZoned.d.ts

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

import type { RelativeRoundingMethod } from "../../types/index.js";
type RelativeUnit = "year" | "month" | "week" | "day" | "hour" | "minute" | "second";
export interface FormatRelativeZonedOptions {
    style?: "long" | "short" | "narrow";
    numeric?: "always" | "auto";
    largestUnit?: RelativeUnit;
    /**
     * How the computed distance rounds to the display unit: "floor" rounds toward the
     * earlier boundary, "ceil" toward the later boundary, "round" (default) to the nearest —
     * matches current behavior when omitted.
     */
    roundingMethod?: RelativeRoundingMethod;
    /**
     * Anchor point for the relative diff.
     *
     * - ZonedDateTime ISO string: kept in its own zone; Temporal handles
     *   cross-zone diffs correctly. The label is therefore zone-aware — a value
     *   and reference in different zones can produce a non-zero diff even when
     *   they describe the same absolute instant.
     * - UTC ISO string: placed into `value`'s timezone before diffing so the
     *   calendar anchor matches the value's wall clock.
     * - Numeric epoch (ms): same — placed into `value`'s timezone.
     * - Omitted: "now" in `value`'s own timezone.
     */
    reference?: string | number;
}
/**
 * Format the relative time between a zoned date-time and a reference instant.
 *
 * - Auto-picks the display unit (second through year) based on the distance, unless
 *   `largestUnit` forces one.
 * - `roundingMethod` controls how the distance rounds to the display unit.
 *
 * @param value ZonedDateTime ISO string to format
 * @param locale optional: BCP 47 locale tag
 * @param options optional: { style, numeric, largestUnit, roundingMethod, reference }
 * @returns the formatted relative-time string, or "" on invalid input
 *
 * @example formatRelativeZoned("2026-03-08T01:00:00-05:00[America/New_York]", "en-US") // "tomorrow"
 * @example formatRelativeZoned(value, "en-US", { roundingMethod: "floor" }) // rounds toward the earlier boundary
 * @example formatRelativeZoned("not-a-date") // ""
 */
export declare function formatRelativeZoned(value: string, locale?: string, options?: FormatRelativeZonedOptions): string;
export {};