@burglekitt/gmt/dist/unix/calculate/roundUnix.d.ts

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

import { Temporal } from "@js-temporal/polyfill";
/**
 * Round a Unix timestamp to the specified unit.
 *
 * - Converts to ZonedDateTime, rounds, converts back to epoch.
 * - Supports: "day", "hour", "minute", "second", "millisecond", "microsecond", "nanosecond".
 * - Date units ("year", "month", "week") are not supported by the Temporal polyfill's ZonedDateTime.round() — they return null.
 * - Returns null for invalid input.
 *
 * @param value Unix timestamp (number)
 * @param options Rounding options: smallestUnit, optional roundingIncrement, roundingMode, epochUnit, timeZone
 * @returns Rounded Unix epoch number, or null on invalid input
 *
 * @example roundUnix(1706659200000, { smallestUnit: "hour" }) // 1706662800000 (rounded up to next hour)
 * @example roundUnix(1706659200000, { smallestUnit: "day", epochUnit: "seconds" }) // 1706640000 (start of day in seconds)
 * @example roundUnix(1706659200000, { smallestUnit: "hour", roundingIncrement: 2 }) // 1706662800000 (rounded to nearest 2-hour mark)
 * @example roundUnix(-86400000, { smallestUnit: "day" }) // -86400000 (start of day for negative timestamp)
 * @example roundUnix("invalid", { smallestUnit: "hour" }) // null
 * @example roundUnix(NaN, { smallestUnit: "hour" }) // null
 */
export declare function roundUnix(value: number, options: {
    smallestUnit: Temporal.SmallestUnit<"day" | "hour" | "minute" | "second" | "millisecond" | "microsecond" | "nanosecond">;
    roundingIncrement?: number;
    roundingMode?: Temporal.RoundingMode;
    epochUnit?: "seconds" | "milliseconds";
    timeZone?: string;
}): number | null;