declare enum EpochUnit {
    SECONDS = "seconds",
    MILLI_SECONDS = "milliseconds",
    MICRO_SECONDS = "microseconds",
    NANO_SECONDS = "nanoseconds"
}
declare const EpochThreshold: {
    SECONDS: number;
    MILLI_SECONDS: number;
    MICRO_SECONDS: number;
    NANO_SECONDS: number;
};
type DurationUnit = 'years' | 'months' | 'weeks' | 'days' | 'hours' | 'minutes' | 'seconds' | 'milliseconds';
type StartEndUnit = 'day' | 'week' | 'month' | 'year';
interface EpochToDate {
    epoch: number;
    epochUnit: string;
    timezone: string;
    dateTime: string;
    dateTimeInGMT: string;
    relative: string;
}
interface DateToEpoch {
    epochInSeconds: number;
    epochInMilliseconds: number;
    timezone: string;
    dateTime: string;
    dateTimeInGMT: string;
}
interface ParsedDuration {
    years: number;
    months: number;
    days: number;
    hours: number;
    minutes: number;
    seconds: number;
    milliseconds: number;
    totalMilliseconds: number;
    humanReadable: string;
}
interface EpochNow {
    seconds: number;
    milliseconds: number;
    iso: string;
    timezone: string;
}
interface TimezoneOffset {
    offset: string;
    offsetMinutes: number;
}
declare const MAX_EPOCH_MS = 8640000000000000;
declare const MIN_EPOCH_MS = -8640000000000000;
declare const MAX_INPUT_STRING_LENGTH = 256;
declare const MAX_FORMAT_STRING_LENGTH = 256;
declare const DEFAULT_FORMAT = "yyyy-MM-dd HH:mm:ss.SSS";
declare const SUPPORTED_FORMAT_TOKENS: ReadonlySet<string>;
type Result<T, E = Error> = {
    ok: true;
    value: T;
    error?: never;
} | {
    ok: false;
    value?: never;
    error: E;
};

declare enum EpochError {
    UndefinedOrNull = "Epoch Is Undefined Or Null",
    NotANumber = "Epoch Is Not A Number Or Cannot Be Parsed As A Number",
    NotAnInteger = "Epoch Must Be A Whole Number (Fractional Epochs Are Ambiguous \u2014 Pass Integer Seconds / Milliseconds / Microseconds / Nanoseconds)",
    OutOfRange = "Epoch Is Out Of The Valid Range",
    EpochUnit = "Invalid Epoch Unit",
    Empty = "Epoch Is Empty",
    DateError = "Invalid Date Format Or Value",
    TimezoneError = "Unknown Timezone",
    ParseError = "Cannot Parse The Provided Date String",
    RangeError = "Invalid Range: fromEpoch Must Be Less Than Or Equal To toEpoch",
    InputTooLong = "Input String Exceeds Maximum Allowed Length",
    FormatTooLong = "Format String Exceeds Maximum Allowed Length",
    FormatInvalid = "Format String Contains An Unsupported Token (See Supported Luxon Tokens In SUPPORTED_FORMAT_TOKENS)",
    ClockOutOfRange = "System Clock Returned A Value Outside JavaScript Date Range"
}
declare class EpochValidationError extends Error {
    constructor(message: EpochError);
}

/**
 * Safe predicate: returns `true` if the input is a recognized epoch
 * value in any supported unit, `false` otherwise. Never throws.
 *
 * Use this for cheap input validation when you don't need the Result-style API.
 *
 * @example
 * ```ts
 * isValidEpoch(1622547800000); // true
 * isValidEpoch(null);          // false
 * isValidEpoch(Infinity);      // false
 * isValidEpoch('not a num');   // false
 * ```
 */
declare function isValidEpoch(epoch: unknown): boolean;
/**
 * Safe predicate: returns `true` if the timezone is a recognized IANA name,
 * `false` otherwise. Never throws.
 *
 * @example
 * ```ts
 * isValidTimezone('UTC');           // true
 * isValidTimezone('Asia/Kolkata');  // true
 * isValidTimezone('Fake/Zone');     // false
 * ```
 */
declare function isValidTimezone(timezone: string): boolean;

/**
 * Render a duration (in milliseconds) as a human-readable string.
 * Pluralizes correctly ("1 second" vs "2 seconds") and omits zero parts.
 * Sub-second durations fall back to `"0 seconds"`. Negative input is
 * treated as positive (absolute value).
 *
 * @param milliseconds - Duration in milliseconds.
 * @returns A pluralization-aware string like `"1 hour, 1 minute, 1 second"`.
 *
 * @example
 * ```ts
 * formatDuration(3661000);  // "1 hour, 1 minute, 1 second"
 * formatDuration(86400000); // "1 day"
 * formatDuration(500);      // "0 seconds"  (below 1s resolution)
 * ```
 */
declare function formatDuration(milliseconds: number): string;

/**
 * Convert an epoch timestamp (any unit) to a human-readable date in the
 * caller's local timezone and GMT, with relative-time context.
 *
 * **Unique feature:** the unit (seconds / milliseconds / microseconds /
 * nanoseconds) is auto-detected from the magnitude — you do not need to
 * tell the library which unit your value is in.
 *
 * **Must be a whole number.** Auto-detection works on the integer magnitude;
 * fractional epochs (e.g. `1622547800.5`) are rejected with
 * {@link EpochError.NotAnInteger} rather than silently misclassified. Pass whole
 * seconds / ms / µs / ns. Auto-detection is unambiguous for the ranges callers
 * hit in practice (seconds up to year ~2286, ms from ~Apr 1970 onward); a
 * millisecond value before ~Apr 1970 or a seconds value past year 2286 falls in
 * an adjacent band — convert such out-of-band values to milliseconds yourself.
 *
 * @param epoch  - Integer epoch value in any unit (seconds, ms, µs, or ns).
 * @param format - Optional Luxon format string. Defaults to {@link DEFAULT_FORMAT}.
 *                 Must contain only tokens from {@link SUPPORTED_FORMAT_TOKENS};
 *                 unknown tokens throw {@link EpochError.FormatInvalid}.
 *
 * @returns Frozen {@link EpochToDate} object with both local and GMT renderings.
 *
 * @throws {EpochValidationError} If the input is null, undefined, NaN, Infinity,
 *   a non-numeric string, a non-integer (fractional) value, or outside the
 *   recognized epoch magnitude range.
 *
 * @example
 * ```ts
 * convertEpoch(1622547800);    // auto-detects: seconds
 * convertEpoch(1622547800000); // auto-detects: milliseconds
 * convertEpoch(1622547800000, 'yyyy-MM-dd HH:mm:ss');
 * ```
 */
declare function convertEpoch(epoch: number, format?: string): EpochToDate;
/**
 * Convert a JavaScript `Date` object to epoch values in the given timezone.
 *
 * @param date     - Any valid `Date` instance.
 * @param timezone - Optional IANA timezone (e.g. `"America/New_York"`).
 *                   Defaults to the runtime's local timezone.
 * @returns Frozen {@link DateToEpoch} with both epoch and human-readable forms.
 * @throws {EpochValidationError} For invalid dates or unknown timezones.
 *
 * @example
 * ```ts
 * convertDateToEpoch(new Date(), 'Asia/Kolkata');
 * ```
 */
declare function convertDateToEpoch(date: Date, timezone?: string): DateToEpoch;
/**
 * Format an epoch value in a specific IANA timezone. Auto-detects epoch unit.
 *
 * @param epoch    - Epoch in any unit (s / ms / µs / ns).
 * @param timezone - IANA timezone, e.g. `"Asia/Tokyo"`.
 * @param format   - Optional Luxon format string. Defaults to {@link DEFAULT_FORMAT}.
 * @returns The formatted date as a string.
 * @throws {EpochValidationError} For invalid epoch, timezone, or format token.
 *
 * @example
 * ```ts
 * convertEpochToTimezone(1622547800000, 'America/Los_Angeles', 'yyyy-MM-dd HH:mm:ss');
 * // "2021-06-01 04:43:20"
 * ```
 */
declare function convertEpochToTimezone(epoch: number, timezone: string, format?: string): string;
/**
 * Auto-detect the unit of an epoch value (seconds / milliseconds /
 * microseconds / nanoseconds) without performing the full conversion.
 * Useful for routing logic: classify the input once, then process with
 * a hot-path implementation.
 *
 * @param epoch - Numeric or numeric-string epoch value.
 * @returns The detected {@link EpochUnit}.
 * @throws {EpochValidationError} On invalid or out-of-range input.
 *
 * @example
 * ```ts
 * getEpochUnit(1622547800);          // EpochUnit.SECONDS
 * getEpochUnit(1622547800000);       // EpochUnit.MILLI_SECONDS
 * getEpochUnit(1622547800000000);    // EpochUnit.MICRO_SECONDS
 * getEpochUnit(1622547800000000000); // EpochUnit.NANO_SECONDS
 * ```
 */
declare function getEpochUnit(epoch: number | string): EpochUnit;
/**
 * Parse a date string into epoch values, with strict timezone-aware parsing.
 *
 * Security: the input is character-allowlisted before being passed to Luxon
 * (rejects HTML / XSS / shell metacharacters), capped at
 * {@link MAX_INPUT_STRING_LENGTH} characters, and parsed in strict mode
 * (no silent `Date()` fallback).
 *
 * @param input    - Date string to parse.
 * @param format   - Optional Luxon format. If omitted, strict ISO 8601 is used.
 * @param timezone - IANA timezone used to interpret the input. Defaults to local.
 * @returns Frozen {@link DateToEpoch} with both epoch and human-readable forms.
 * @throws {EpochValidationError} {@link EpochError.ParseError} for unparseable
 *   input, {@link EpochError.InputTooLong} for inputs exceeding the length cap,
 *   {@link EpochError.TimezoneError} for an unknown timezone, or
 *   {@link EpochError.FormatInvalid} for an unsupported format token.
 *
 * @example
 * ```ts
 * parseToEpoch('2024-12-25T00:00:00Z');                     // ISO 8601 auto
 * parseToEpoch('25/12/2024', 'dd/MM/yyyy', 'Europe/London'); // strict format
 * ```
 */
declare function parseToEpoch(input: string, format?: string, timezone?: string): DateToEpoch;
/**
 * Compute the calendar-accurate duration between two epochs.
 *
 * Years, months, days etc. are computed via Luxon's calendar-aware diff —
 * not by dividing milliseconds. Both epochs auto-detect their unit.
 *
 * @throws {EpochValidationError} {@link EpochError.RangeError} when
 *   `fromEpoch > toEpoch`.
 *
 * @example
 * ```ts
 * const d = getDurationBetween(1609459200000, 1622547800000);
 * d.humanReadable; // "5 months, 11 hours, 43 minutes, 20 seconds"
 * ```
 */
declare function getDurationBetween(fromEpoch: number, toEpoch: number): ParsedDuration;
/**
 * Get the UTC offset for an IANA timezone, DST-aware.
 *
 * @param timezone - IANA timezone name.
 * @param epoch    - Optional epoch (any unit) for a specific point in time.
 *                   When omitted, uses the current moment.
 * @returns Frozen {@link TimezoneOffset} with both string and minute forms.
 * @throws {EpochValidationError} For unknown timezones.
 *
 * @example
 * ```ts
 * getTimezoneOffset('Asia/Kolkata');               // { offset: '+05:30', offsetMinutes: 330 }
 * getTimezoneOffset('America/New_York');           // varies by DST
 * getTimezoneOffset('America/New_York', someEpoch); // DST as of that instant
 * ```
 */
declare function getTimezoneOffset(timezone: string, epoch?: number): TimezoneOffset;
/**
 * Returns a defensive copy of the supported IANA timezone names. The list is
 * sourced from `Intl.supportedValuesOf('timeZone')` augmented with modern
 * canonical names that older ICU bundles still return as legacy aliases.
 *
 * @returns A fresh array — safe to mutate without affecting subsequent calls.
 */
declare function getTimezoneList(): string[];
/**
 * Returns the current moment as epoch values plus ISO 8601 string and the
 * detected local timezone.
 *
 * @returns Frozen {@link EpochNow} with seconds, milliseconds, ISO, timezone.
 * @throws {EpochValidationError} {@link EpochError.ClockOutOfRange} if the
 *   system clock returns a value outside `±MAX_EPOCH_MS` — guards against
 *   clock corruption / sandbox edge cases.
 */
declare function getEpochNow(): EpochNow;

/**
 * Result-style variant of {@link convertEpoch}. Never throws for validation
 * errors — returns `{ ok: false, error }` instead. Ideal for handling
 * untrusted input (API endpoints, form data, batch jobs).
 *
 * @example
 * ```ts
 * const r = safeConvertEpoch(req.body.timestamp);
 * if (r.ok) {
 *   console.log(r.value.dateTime);
 * } else {
 *   res.status(400).json({ error: r.error.message });
 * }
 * ```
 */
declare function safeConvertEpoch(epoch: number, format?: string): Result<EpochToDate, EpochValidationError>;
/** Result-style variant of {@link convertDateToEpoch}. Never throws for validation errors. */
declare function safeConvertDateToEpoch(date: Date, timezone?: string): Result<DateToEpoch, EpochValidationError>;
/** Result-style variant of {@link convertEpochToTimezone}. Never throws for validation errors. */
declare function safeConvertEpochToTimezone(epoch: number, timezone: string, format?: string): Result<string, EpochValidationError>;
/** Result-style variant of {@link parseToEpoch}. Never throws for validation errors. */
declare function safeParseToEpoch(input: string, format?: string, timezone?: string): Result<DateToEpoch, EpochValidationError>;
/** Result-style variant of {@link getDurationBetween}. Never throws for validation errors. */
declare function safeGetDurationBetween(fromEpoch: number, toEpoch: number): Result<ParsedDuration, EpochValidationError>;
/** Result-style variant of {@link getTimezoneOffset}. Never throws for validation errors. */
declare function safeGetTimezoneOffset(timezone: string, epoch?: number): Result<TimezoneOffset, EpochValidationError>;
/** Result-style variant of {@link getEpochNow}. Never throws for clock-corruption errors. */
declare function safeGetEpochNow(): Result<EpochNow, EpochValidationError>;
/** Result-style variant of {@link getEpochUnit}. Never throws for validation errors. */
declare function safeGetEpochUnit(epoch: number | string): Result<EpochUnit, EpochValidationError>;

export { DEFAULT_FORMAT, EpochError, EpochThreshold, EpochUnit, EpochValidationError, MAX_EPOCH_MS, MAX_FORMAT_STRING_LENGTH, MAX_INPUT_STRING_LENGTH, MIN_EPOCH_MS, SUPPORTED_FORMAT_TOKENS, convertDateToEpoch, convertEpoch, convertEpochToTimezone, formatDuration, getDurationBetween, getEpochNow, getEpochUnit, getTimezoneList, getTimezoneOffset, isValidEpoch, isValidTimezone, parseToEpoch, safeConvertDateToEpoch, safeConvertEpoch, safeConvertEpochToTimezone, safeGetDurationBetween, safeGetEpochNow, safeGetEpochUnit, safeGetTimezoneOffset, safeParseToEpoch };
export type { DateToEpoch, DurationUnit, EpochNow, EpochToDate, ParsedDuration, Result, StartEndUnit, TimezoneOffset };