/**
 * @fileoverview High-precision time utilities
 * Handles nanoseconds, BigInt timestamps, sub-millisecond operations
 */
/**
 * Nanosecond precision timestamp
 * Uses BigInt for precision beyond milliseconds
 */
export interface NanosecondTimestamp {
    readonly milliseconds: number;
    readonly nanoseconds: number;
    readonly totalNanoseconds: bigint;
}
/**
 * High-resolution duration with nanosecond precision
 */
export interface HighResDuration {
    readonly seconds: number;
    readonly nanoseconds: number;
}
/**
 * Create a nanosecond timestamp from components
 */
export declare function createNanosecondTimestamp(milliseconds: number, nanoseconds?: number): NanosecondTimestamp;
/**
 * Create a nanosecond timestamp from BigInt
 */
export declare function fromNanoseconds(totalNs: bigint): NanosecondTimestamp;
/**
 * Create a nanosecond timestamp from a Date
 */
export declare function dateToNanoseconds(date: Date): NanosecondTimestamp;
/**
 * Convert nanosecond timestamp to Date (loses sub-millisecond precision)
 */
export declare function nanosecondsToDate(timestamp: NanosecondTimestamp): Date;
/**
 * Add two nanosecond timestamps
 */
export declare function addNanoseconds(a: NanosecondTimestamp, b: NanosecondTimestamp): NanosecondTimestamp;
/**
 * Subtract nanosecond timestamps
 */
export declare function subtractNanoseconds(a: NanosecondTimestamp, b: NanosecondTimestamp): NanosecondTimestamp;
/**
 * Compare nanosecond timestamps
 * @returns -1 if a < b, 0 if equal, 1 if a > b
 */
export declare function compareNanoseconds(a: NanosecondTimestamp, b: NanosecondTimestamp): -1 | 0 | 1;
/**
 * Get current time with nanosecond precision (if available)
 * Falls back to millisecond precision if performance.now() not available
 */
export declare function nowNanoseconds(): NanosecondTimestamp;
/**
 * Format nanosecond timestamp to ISO string with sub-millisecond precision
 */
export declare function formatNanoseconds(timestamp: NanosecondTimestamp): string;
/**
 * Parse ISO string with nanosecond precision
 */
export declare function parseNanoseconds(isoString: string): NanosecondTimestamp | null;
/**
 * Create a high-resolution duration
 */
export declare function createHighResDuration(seconds: number, nanoseconds?: number): HighResDuration;
/**
 * Add two high-resolution durations
 */
export declare function addHighResDuration(a: HighResDuration, b: HighResDuration): HighResDuration;
/**
 * Subtract high-resolution durations
 */
export declare function subtractHighResDuration(a: HighResDuration, b: HighResDuration): HighResDuration;
/**
 * Convert high-resolution duration to milliseconds
 */
export declare function highResDurationToMs(duration: HighResDuration): number;
/**
 * Convert milliseconds to high-resolution duration
 */
export declare function msToHighResDuration(ms: number): HighResDuration;
/**
 * Convert Unix epoch milliseconds to BigInt
 */
export declare function toBigIntMs(date: Date): bigint;
/**
 * Convert BigInt milliseconds to Date
 */
export declare function fromBigIntMs(ms: bigint): Date;
/**
 * Convert Unix epoch seconds to BigInt
 */
export declare function toBigIntSeconds(date: Date): bigint;
/**
 * Convert BigInt seconds to Date
 */
export declare function fromBigIntSeconds(seconds: bigint): Date;
/**
 * Add milliseconds (as BigInt) to a date
 */
export declare function addBigIntMs(date: Date, ms: bigint): Date;
/**
 * Subtract milliseconds (as BigInt) from a date
 */
export declare function subtractBigIntMs(date: Date, ms: bigint): Date;
/**
 * Calculate difference between dates in BigInt milliseconds
 */
export declare function diffBigIntMs(a: Date, b: Date): bigint;
/**
 * DST transition info
 */
export interface DSTTransition {
    /** Transition date/time (UTC) */
    readonly utc: Date;
    /** Transition date/time (local) */
    readonly local: Date;
    /** Whether transitioning to DST */
    readonly toDST: boolean;
    /** Offset before transition (minutes) */
    readonly offsetBefore: number;
    /** Offset after transition (minutes) */
    readonly offsetAfter: number;
    /** Gap or overlap duration (minutes) */
    readonly adjustmentMinutes: number;
}
/**
 * Check if a date falls in a DST transition gap (skipped time)
 * @param date - Date to check
 * @param timeZone - IANA timezone (optional, uses local if not provided)
 */
export declare function isInDSTGap(date: Date, timeZone?: string): boolean;
/**
 * Check if a date falls in a DST overlap (ambiguous time)
 * @param date - Date to check
 * @param timeZone - IANA timezone (optional, uses local if not provided)
 */
export declare function isInDSTOverlap(date: Date, timeZone?: string): boolean;
/**
 * Find DST transitions in a year for local timezone
 */
export declare function getDSTTransitionsInYear(year: number): DSTTransition[];
/**
 * Resolve ambiguous time in DST overlap
 * @param date - Potentially ambiguous date
 * @param prefer - Prefer 'earlier' or 'later' interpretation
 */
export declare function resolveAmbiguousTime(date: Date, prefer?: 'earlier' | 'later'): Date;
/**
 * Validated Date wrapper that guarantees a valid date
 */
export declare class ValidDate {
    private readonly _date;
    private constructor();
    /**
     * Create a ValidDate, throws if invalid
     */
    static from(date: Date): ValidDate;
    /**
     * Create a ValidDate, returns null if invalid
     */
    static tryFrom(date: Date): ValidDate | null;
    /**
     * Create from timestamp, throws if invalid
     */
    static fromTimestamp(ms: number): ValidDate;
    /**
     * Create from ISO string, throws if invalid
     */
    static fromISO(isoString: string): ValidDate;
    /**
     * Get the underlying Date object
     */
    get value(): Date;
    /**
     * Get timestamp
     */
    get time(): number;
    /**
     * Format to ISO string
     */
    toISOString(): string;
    /**
     * Format to locale string
     */
    toLocaleString(locale?: string, options?: Intl.DateTimeFormatOptions): string;
}
/**
 * Ensure a date is valid, with fallback
 */
export declare function ensureValidDate(date: Date, fallback?: Date): Date;
/**
 * Parse date with validation
 */
export declare function parseValidDate(input: string | number | Date): Date | null;
/**
 * Assert date is valid, throws if not
 */
export declare function assertValidDate(date: Date, message?: string): asserts date is Date & {
    getTime(): number;
};
/**
 * Known leap seconds (added at end of these dates, 23:59:60 UTC)
 * List from https://www.ietf.org/timezones/data/leap-seconds.list
 */
export declare const LEAP_SECONDS: readonly Date[];
/**
 * Get number of leap seconds between two dates
 */
export declare function leapSecondsBetween(start: Date, end: Date): number;
/**
 * Check if a date is near a leap second (within 1 second)
 */
export declare function isNearLeapSecond(date: Date): boolean;
/**
 * Convert TAI (International Atomic Time) to UTC
 * TAI = UTC + accumulated leap seconds + 10 (initial offset)
 */
export declare function taiToUtc(taiMs: number): Date;
/**
 * Convert UTC to TAI
 */
export declare function utcToTai(date: Date): number;
//# sourceMappingURL=precision.d.ts.map