import { type MapFunction, type Maybe, type Milliseconds, type TimezoneString, type ISO8601DayString, type YearNumber, type MapSameFunction, type Hours, type Minutes, type LogicalDate } from '@dereekb/util';
import { type DateRange, type TransformDateRangeDatesFunction } from './date.range';
/**
 * A Date whose UTC components represent "wall-clock" time in an arbitrary timezone.
 *
 * Inherited from the RRule library where RRule only deals with UTC date/times, dates going into it must always be in UTC.
 * We strip the timezone concept entirely: if it's 11 AM in Los Angeles, the BaseDateAsUTC reads 11:00 UTC.
 * This lets us perform date math (start-of-day, add-hours, etc.) without worrying about DST or offset changes,
 * then convert back to a real timezone-aware date when needed via {@link DateTimezoneUtcNormalInstance.baseDateToTargetDate}.
 *
 * Three date "spaces" exist in this module:
 * - **base** — wall-clock time encoded as UTC (`BaseDateAsUTC`). Safe for arithmetic.
 * - **target** — a real instant in the configured timezone.
 * - **system** — a real instant in the host machine's local timezone.
 */
export type BaseDateAsUTC = Date;
/**
 * Configuration for a DateTimezoneConversion instance.
 *
 * If no values are defined then no conversion occurs.
 */
export interface DateTimezoneConversionConfig {
    /**
     * Whether or not to use the system timezone/offset.
     *
     * This will convert between UTC and the current system's timezone.
     */
    readonly useSystemTimezone?: boolean;
    /**
     * Timezone to be relative to. If not defined, values are returned in UTC.
     *
     * Ignored if useSystemTimezone is true.
     */
    readonly timezone?: Maybe<TimezoneString>;
    /**
     * Custom timezone offset (in ms) between the "normal" and the base date.
     *
     * Ignored if useSystemTimezone is true.
     *
     * Examples:
     * - UTC-6 is negative 6 hours, in milliseconds.
     */
    readonly timezoneOffset?: Milliseconds;
    /**
     * Does not convert anything.
     */
    readonly noConversion?: true;
}
/**
 * Returns true if the config contains at least one meaningful conversion setting
 * (useSystemTimezone, timezone, timezoneOffset, or noConversion).
 *
 * Useful for guarding against empty/default configs before creating a converter instance.
 *
 * @param input - The conversion config to validate.
 * @returns True if the config has at least one meaningful conversion property set.
 *
 * @example
 * ```ts
 * isValidDateTimezoneConversionConfig({ timezone: 'America/Chicago' }); // true
 * isValidDateTimezoneConversionConfig({}); // false
 * ```
 */
export declare function isValidDateTimezoneConversionConfig(input: DateTimezoneConversionConfig): boolean;
/**
 * DateTimezoneConversionConfig only configured to use the system timezone.
 */
export type DateTimezoneConversionConfigUseSystemTimezone = {
    readonly useSystemTimezone: true;
};
/**
 * Compares two configs for logical equivalence, accounting for the fact that
 * `undefined` timezone and `'UTC'` timezone are treated as the same value.
 *
 * @param a - First conversion config to compare.
 * @param b - Second conversion config to compare.
 * @returns True if both configs are logically equivalent.
 *
 * @example
 * ```ts
 * isSameDateTimezoneConversionConfig({ timezone: 'UTC' }, { timezone: undefined }); // true
 * isSameDateTimezoneConversionConfig({ useSystemTimezone: true }, { timezone: 'America/Denver' }); // false
 * ```
 */
export declare function isSameDateTimezoneConversionConfig(a: DateTimezoneConversionConfig, b: DateTimezoneConversionConfig): boolean;
/**
 * Returns the system timezone's UTC offset for the given date, in milliseconds.
 *
 * Sign matches the UTC convention: UTC-6 returns a negative value (-21600000).
 * The date parameter is required because DST may change the offset throughout the year.
 *
 * Uses native `getTimezoneOffset()` to avoid a DST edge case in date-fns-tz's `toZonedTime`.
 *
 * @param date - Required to determine the correct offset for that instant (DST-aware)
 * @returns The system timezone UTC offset in milliseconds.
 *
 * @example
 * ```ts
 * // On a system in UTC-6 (no DST)
 * getCurrentSystemOffsetInMs(new Date('2024-06-15T12:00:00Z')); // -21600000
 * ```
 */
export declare function getCurrentSystemOffsetInMs(date: Date): Milliseconds;
/**
 * Returns the system timezone's UTC offset for the given date, truncated to whole hours.
 *
 * @param date - Required to determine the correct offset for that instant (DST-aware)
 * @returns The system timezone UTC offset truncated to whole hours.
 *
 * @example
 * ```ts
 * // On a system in UTC-6
 * getCurrentSystemOffsetInHours(new Date('2024-06-15T12:00:00Z')); // -6
 * ```
 */
export declare function getCurrentSystemOffsetInHours(date: Date): Hours;
/**
 * Returns the system timezone's UTC offset for the given date, in minutes.
 *
 * Sign matches the UTC convention: UTC-6 returns -360. Useful for timezones with
 * non-hour offsets (e.g. UTC+5:30 returns 330).
 *
 * @param date - Required to determine the correct offset for that instant (DST-aware)
 * @returns The system timezone UTC offset in minutes.
 *
 * @example
 * ```ts
 * // On a system in UTC-6
 * getCurrentSystemOffsetInMinutes(new Date('2024-06-15T12:00:00Z')); // -360
 * ```
 */
export declare function getCurrentSystemOffsetInMinutes(date: Date): Minutes;
/**
 * Computes the UTC offset for any IANA timezone at a given instant, in milliseconds.
 *
 * Preferred over `Date.getTimezoneOffset()` and date-fns-tz's `getTimezoneOffset()` because both
 * return incorrect values during the first two hours after a DST transition.
 * See: https://github.com/marnusw/date-fns-tz/issues/227
 *
 * Sign matches the UTC convention: GMT-5 returns -18000000.
 *
 * @param timezone - IANA timezone string (e.g. 'America/New_York')
 * @param date - The instant to evaluate, since DST may shift the offset.
 * @returns The UTC offset for the given timezone at the given instant, in milliseconds.
 *
 * @example
 * ```ts
 * calculateTimezoneOffset('America/Chicago', new Date('2024-06-15T12:00:00Z')); // -18000000 (UTC-5 CDT)
 * calculateTimezoneOffset('UTC', new Date()); // 0
 * ```
 */
export declare function calculateTimezoneOffset(timezone: TimezoneString, date: Date): Milliseconds;
export type DateTimezoneConversionTarget = 'target' | 'base' | 'system';
export type DateTimezoneOffsetFunction = (date: Date, from: DateTimezoneConversionTarget, to: DateTimezoneConversionTarget) => Milliseconds;
/**
 * Provides bidirectional conversions between the three date spaces: base, target, and system.
 *
 * See {@link BaseDateAsUTC} for an explanation of these spaces.
 */
export interface DateTimezoneBaseDateConverter {
    /**
     * Returns the offset in milliseconds required to convert a date from one space to another.
     */
    getCurrentOffset: DateTimezoneOffsetFunction;
    /**
     * Strips the target timezone offset, encoding the wall-clock time as a {@link BaseDateAsUTC}.
     *
     * Useful when you need to do date math (start-of-day, add-hours, etc.) without DST interference,
     * then convert back via {@link baseDateToTargetDate}.
     *
     * For example, if it is 2PM in the target timezone, the result will be 2PM UTC:
     * - Input: 2021-08-16T14:00:00.000-06:00
     * - Output: 2021-08-16T14:00:00.000Z
     */
    targetDateToBaseDate(date: Date): Date;
    /**
     * Re-interprets a target-timezone date as an instant in the system's local timezone.
     *
     * Needed when interfacing with browser/Node APIs that implicitly use the system timezone,
     * such as `startOfDay()` from date-fns.
     *
     * For example, 2PM target becomes 2PM in the system timezone:
     * - Input: 2021-08-16T14:00:00.000-06:00
     * - Output: 2021-08-16T14:00:00.000+02:00
     */
    targetDateToSystemDate(date: Date): Date;
    /**
     * Applies the target timezone offset to a {@link BaseDateAsUTC}, producing a real instant in the target timezone.
     */
    baseDateToTargetDate(date: Date): Date;
    /**
     * Converts a {@link BaseDateAsUTC} to the system's local timezone.
     */
    baseDateToSystemDate(date: Date): Date;
    /**
     * Converts a system-local date to the target timezone.
     */
    systemDateToTargetDate(date: Date): Date;
    /**
     * Converts a system-local date to a {@link BaseDateAsUTC}.
     */
    systemDateToBaseDate(date: Date): Date;
}
export type DateTimezoneConversionMap<T = number> = {
    [key: string]: T;
};
export type DateTimezoneConversionFunction<T> = MapFunction<Milliseconds, T>;
/**
 * Calculates offset values for every pair of conversion targets (target, base, system)
 * and returns them as a keyed map (e.g. `'target-base'`, `'base-system'`).
 *
 * @param date - The reference date used to compute offsets.
 * @param converter - The converter instance providing offset calculations.
 * @param map - Optional mapping function applied to each raw millisecond offset.
 * @returns Map keyed by `${from}-${to}` pairs mapping to their computed offsets.
 */
export declare function calculateAllConversions<T = number>(date: Date, converter: DateTimezoneBaseDateConverter, map?: DateTimezoneConversionFunction<T>): DateTimezoneConversionMap<T>;
export type DateTimezoneUtcNormalInstanceInput = Maybe<TimezoneString> | DateTimezoneConversionConfig;
export type DateTimezoneUtcNormalInstanceTransformType = 'targetDateToBaseDate' | 'targetDateToSystemDate' | 'baseDateToTargetDate' | 'baseDateToSystemDate' | 'systemDateToTargetDate' | 'systemDateToBaseDate';
/**
 * Returns the reverse transform type, so a round-trip conversion can be performed.
 *
 * @param input - The transform type to invert.
 * @returns The inverse transform type for round-trip conversion.
 * @throws {Error} When `input` is not a recognized transform type.
 *
 * @example
 * ```ts
 * inverseDateTimezoneUtcNormalInstanceTransformType('targetDateToBaseDate'); // 'baseDateToTargetDate'
 * inverseDateTimezoneUtcNormalInstanceTransformType('systemDateToTargetDate'); // 'targetDateToSystemDate'
 * ```
 */
export declare function inverseDateTimezoneUtcNormalInstanceTransformType(input: DateTimezoneUtcNormalInstanceTransformType): DateTimezoneUtcNormalInstanceTransformType;
/**
 * Configuration for {@link DateTimezoneUtcNormalInstance.safeMirroredConvertDate}.
 */
export interface SafeMirroredConvertDateConfig {
    /**
     * The base date. Should have been derived from the originalContextDate using convertDate().
     */
    readonly baseDate: BaseDateAsUTC;
    /**
     * Original date used to derive the baseDate.
     */
    readonly originalContextDate: Date;
    /**
     * The "type" of date the originalContextDate is.
     */
    readonly contextType: DateTimezoneConversionTarget;
    /**
     * Whether to apply safe DST correction. Defaults to true.
     */
    readonly safeConvert?: boolean;
}
/**
 * Central class for converting dates between the three date spaces (base, target, system).
 *
 * Wraps a timezone configuration and provides all conversion methods. Instances are typically
 * created via the {@link dateTimezoneUtcNormal} factory or by passing a config/timezone string
 * to the constructor.
 *
 * @example
 * ```ts
 * const normal = new DateTimezoneUtcNormalInstance('America/Denver');
 *
 * // Convert a target-timezone date to a BaseDateAsUTC for safe arithmetic
 * const base = normal.targetDateToBaseDate(new Date('2024-06-15T14:00:00-06:00'));
 * // base reads 14:00 UTC — the wall-clock time is preserved
 *
 * // Convert back when done
 * const target = normal.baseDateToTargetDate(base);
 * ```
 */
export declare class DateTimezoneUtcNormalInstance implements DateTimezoneBaseDateConverter {
    readonly config: DateTimezoneConversionConfig;
    readonly hasConversion: boolean;
    get hasConfiguredTimezoneString(): boolean;
    get usesSystemTimezone(): boolean;
    get configuredTimezoneString(): Maybe<TimezoneString>;
    private readonly _getOffset;
    private readonly _setOnDate;
    constructor(config: DateTimezoneUtcNormalInstanceInput);
    convertDate(date: Date, from: DateTimezoneConversionTarget, to: DateTimezoneConversionTarget): Date;
    /**
     * A "safer" conversion that will return a "mirrored" offset. Only functional with a "to" UTC value.
     *
     * This is required in cases where "reverse" offset will be used and must be consistent so they reverse in both directions the same amount compared to the base.
     *
     * For example, when daylight savings changed on November 3, 2024 the offset returned was 5 but to get back to the original an offset of 6 was required.
     * This is where some contextual data was not being used. This function uses that contextual data to make sure the reverse will be consistent.
     *
     * @param config - Configuration for the safe mirrored conversion.
     * @returns The converted date and the DST offset adjustment applied.
     */
    safeMirroredConvertDate(config: SafeMirroredConvertDateConfig): {
        date: Date;
        daylightSavingsOffset: number;
    };
    get setOnDate(): SetOnDateWithTimezoneNormalFunction;
    getCurrentOffset(date: Date, from: DateTimezoneConversionTarget, to: DateTimezoneConversionTarget): number;
    transform(date: Date, transform: DateTimezoneUtcNormalInstanceTransformType): Date;
    transformFunction(transform: DateTimezoneUtcNormalInstanceTransformType): MapFunction<Date, Date>;
    transformDateRangeToTimezoneFunction(transformType?: DateTimezoneUtcNormalInstanceTransformType): TransformDateRangeToTimezoneFunction;
    targetDateToBaseDate(date: Date): Date;
    baseDateToTargetDate(date: Date): Date;
    baseDateToSystemDate(date: Date): Date;
    systemDateToBaseDate(date: Date): Date;
    targetDateToSystemDate(date: Date): Date;
    systemDateToTargetDate(date: Date): Date;
    getOffset(date: Date, transform: DateTimezoneUtcNormalInstanceTransformType): Milliseconds;
    getOffsetInHours(date: Date, transform: DateTimezoneUtcNormalInstanceTransformType): Hours;
    offsetFunction(transform: DateTimezoneUtcNormalInstanceTransformType): MapFunction<Date, Milliseconds>;
    targetDateToBaseDateOffset(date: Date): Milliseconds;
    baseDateToTargetDateOffset(date: Date): Milliseconds;
    baseDateToSystemDateOffset(date: Date): Milliseconds;
    systemDateToBaseDateOffset(date: Date): Milliseconds;
    targetDateToSystemDateOffset(date: Date): Milliseconds;
    systemDateToTargetDateOffset(date: Date): Milliseconds;
    conversionOffset(date: Date, from: DateTimezoneConversionTarget, to: DateTimezoneConversionTarget): number;
    calculateAllOffsets<T = number>(date: Date, map?: DateTimezoneConversionFunction<T>): DateTimezoneConversionMap<T>;
    /**
     * Returns true if the input is midnight in the target timezone.
     *
     * @param date - Moment to evaluate.
     * @returns Whether the moment lands on midnight in the target timezone.
     */
    isStartOfDayInTargetTimezone(date: Date): boolean;
    /**
     * Start of the given day in the target timezone.
     *
     * @param date - The input is treated as an instant in time.
     * @returns The start-of-day date in the target timezone.
     */
    startOfDayInTargetTimezone(date?: Date | ISO8601DayString): Date;
    /**
     * Start of the given day in UTC.
     *
     * @param date - Moment or ISO8601 day string whose day boundary should be used.
     * @returns Start-of-day as a BaseDateAsUTC.
     */
    startOfDayInBaseDate(date?: Date | ISO8601DayString): BaseDateAsUTC;
    /**
     * End of the given day in UTC.
     *
     * @param date - Moment or ISO8601 day string whose day boundary should be used.
     * @returns End-of-day (23:59:59.999) as a BaseDateAsUTC.
     */
    endOfDayInBaseDate(date?: Date | ISO8601DayString): BaseDateAsUTC;
    /**
     * Start of the given day for the system.
     *
     * @param date - Moment or ISO8601 day string whose day boundary should be used.
     * @returns Start-of-day in the system timezone.
     */
    startOfDayInSystemDate(date?: Date | ISO8601DayString): Date;
    /**
     * End of the given day for the system.
     *
     * @param date - Moment or ISO8601 day string whose day boundary should be used.
     * @returns End-of-day in the system timezone.
     */
    endOfDayInSystemDate(date?: Date | ISO8601DayString): Date;
    /**
     * Whether or not the target timezone experiences daylight savings for the given year.
     *
     * @param year - The year to check, as a Date or number; defaults to the current year.
     * @returns True if the target timezone has different offsets in January and July.
     */
    targetTimezoneExperiencesDaylightSavings(year?: Date | YearNumber): boolean;
    /**
     * Creates a TransformDateInTimezoneNormalFunction using this normal instance.
     *
     * @param transformType
     * @returns
     */
    transformDateInTimezoneNormalFunction(transformType?: DateTimezoneUtcNormalInstanceTransformType): TransformDateInTimezoneNormalFunction;
    transformDateInTimezoneNormal(date: Date, transform: MapSameFunction<Date>, transformType?: DateTimezoneUtcNormalInstanceTransformType): Date;
    transformDateRangeInTimezoneNormalFunction(transform?: DateTimezoneUtcNormalInstanceTransformType): TransformDateRangeInTimezoneNormalFunction;
}
export type DateTimezoneUtcNormalFunctionInput = DateTimezoneUtcNormalInstanceInput | DateTimezoneUtcNormalInstance | TimezoneString | Milliseconds;
/**
 * Factory that creates or passes through a {@link DateTimezoneUtcNormalInstance}.
 *
 * Accepts a wide range of inputs for convenience: an existing instance (returned as-is),
 * a timezone string, a raw millisecond offset, or a full config object.
 *
 * @param config - Timezone input: an existing instance, timezone string, millisecond offset, or config object.
 * @returns DateTimezoneUtcNormalInstance resolved from the input.
 * @throws {Error} If the input type is not recognized.
 *
 * @example
 * ```ts
 * // From IANA timezone string
 * const denver = dateTimezoneUtcNormal('America/Denver');
 *
 * // From millisecond offset (UTC-6)
 * const utcMinus6 = dateTimezoneUtcNormal(-6 * 60 * 60 * 1000);
 *
 * // From config object
 * const system = dateTimezoneUtcNormal({ useSystemTimezone: true });
 *
 * // Pass-through if already an instance
 * const same = dateTimezoneUtcNormal(denver); // same reference
 * ```
 *
 * @__NO_SIDE_EFFECTS__
 */
export declare function dateTimezoneUtcNormal(config: DateTimezoneUtcNormalFunctionInput): DateTimezoneUtcNormalInstance;
/**
 * Singleton instance that converts between the host system's local timezone and base/target spaces.
 *
 * Uses `useSystemTimezone: true`, so offsets adjust automatically if the system timezone changes (e.g. DST).
 */
export declare const SYSTEM_DATE_TIMEZONE_UTC_NORMAL_INSTANCE: DateTimezoneUtcNormalInstance;
/**
 * Singleton instance configured for UTC. All conversions are identity (offset is always 0),
 * making it a safe no-op converter for code paths that require a {@link DateTimezoneUtcNormalInstance}.
 */
export declare const UTC_DATE_TIMEZONE_UTC_NORMAL_INSTANCE: DateTimezoneUtcNormalInstance;
/**
 * Returns the shared {@link SYSTEM_DATE_TIMEZONE_UTC_NORMAL_INSTANCE} singleton.
 *
 * Prefer this over constructing a new instance when you need system-timezone conversions,
 * as the singleton avoids unnecessary allocations.
 *
 * @returns The shared system-timezone DateTimezoneUtcNormalInstance singleton.
 */
export declare function systemDateTimezoneUtcNormal(): DateTimezoneUtcNormalInstance;
/**
 * Convenience function that applies the timezone offset to a {@link BaseDateAsUTC},
 * producing a real instant in the specified timezone.
 *
 * Creates a temporary {@link DateTimezoneUtcNormalInstance} internally; prefer
 * reusing an instance if calling this in a loop.
 *
 * @param date - The BaseDateAsUTC to convert.
 * @param timezone - The target IANA timezone string.
 * @returns A real instant in the specified timezone.
 *
 * @example
 * ```ts
 * const base = new Date('2024-06-15T14:00:00.000Z'); // wall-clock 2PM
 * const target = baseDateToTargetDate(base, 'America/Denver');
 * // target is 2024-06-15T14:00:00.000-06:00 (2PM MDT)
 * ```
 */
export declare function baseDateToTargetDate(date: Date, timezone: Maybe<TimezoneString>): Date;
/**
 * Convenience function that strips the timezone offset from a target-timezone date,
 * producing a {@link BaseDateAsUTC} whose UTC components match the original wall-clock time.
 *
 * Creates a temporary {@link DateTimezoneUtcNormalInstance} internally; prefer
 * reusing an instance if calling this in a loop.
 *
 * @param date - The target-timezone date to convert.
 * @param timezone - The IANA timezone the date is expressed in.
 * @returns A BaseDateAsUTC with wall-clock time preserved as UTC.
 *
 * @example
 * ```ts
 * const target = new Date('2024-06-15T14:00:00.000-06:00'); // 2PM MDT
 * const base = targetDateToBaseDate(target, 'America/Denver');
 * // base is 2024-06-15T14:00:00.000Z — wall-clock 2PM preserved as UTC
 * ```
 */
export declare function targetDateToBaseDate(date: Date, timezone: Maybe<TimezoneString>): Date;
/**
 * Converts a {@link BaseDateAsUTC} to a target date in the system's local timezone
 * using the shared system-timezone instance.
 *
 * @param date - Moment in base UTC space to project into system time.
 * @returns Moment translated to the system's local timezone.
 */
export declare function systemBaseDateToNormalDate(date: Date): BaseDateAsUTC;
/**
 * Converts a target date in the system's local timezone back to a {@link BaseDateAsUTC}
 * using the shared system-timezone instance.
 *
 * @param date - Moment in system-local space to project back to base UTC.
 * @returns Equivalent moment as a BaseDateAsUTC.
 */
export declare function systemNormalDateToBaseDate(date: BaseDateAsUTC): Date;
/**
 * Returns the millisecond offset needed to convert a {@link BaseDateAsUTC} to a target date
 * in the system's local timezone.
 *
 * @param date - Reference moment used to evaluate the offset.
 * @returns Offset in milliseconds from base UTC to system-local space.
 */
export declare function systemBaseDateToNormalDateOffset(date: Date): Milliseconds;
/**
 * Returns the millisecond offset needed to convert a target date in the system's
 * local timezone back to a {@link BaseDateAsUTC}.
 *
 * @param date - Reference moment used to evaluate the offset.
 * @returns Offset in milliseconds from system-local space back to base UTC.
 */
export declare function systemNormalDateToBaseDateOffset(date: Date): Milliseconds;
/**
 * Returns whether the system's local timezone observes daylight saving time in the given year.
 *
 * Compares the offset on January 1 and July 1; if they differ, DST is in effect for part of the year.
 *
 * @param year - The year to check, as a Date.
 * @returns True if the system timezone observes DST in the given year.
 */
export declare function systemExperiencesDaylightSavings(year: Date): boolean;
/**
 * Converts a date into a target date space, applies a transformation, then converts the result back.
 *
 * This pattern lets you use date-fns functions (startOfDay, addHours, etc.) as if the date were in
 * the target timezone, without timezone/DST artifacts.
 */
export type TransformDateInTimezoneNormalFunction = ((date: Date, transform: MapSameFunction<Date>) => Date) & {
    readonly _timezoneInstance: DateTimezoneUtcNormalInstance;
    readonly _transformType: DateTimezoneUtcNormalInstanceTransformType;
};
/**
 * Creates a {@link TransformDateInTimezoneNormalFunction} that converts a date into the
 * specified date space, applies a user-provided transformation, then converts back.
 *
 * @param timezoneInput - Timezone configuration for the conversion.
 * @param transformType - Defaults to `'systemDateToTargetDate'`
 * @returns Transformer that round-trips a date through the configured timezone normalization.
 *
 * @example
 * ```ts
 * const fn = transformDateInTimezoneNormalFunction('America/Denver', 'systemDateToTargetDate');
 *
 * // Get start-of-day in Denver, even if the system is in a different timezone
 * const result = fn(someDate, (d) => startOfDay(d));
 * ```
 *
 * @__NO_SIDE_EFFECTS__
 */
export declare function transformDateInTimezoneNormalFunction(timezoneInput: DateTimezoneUtcNormalFunctionInput, transformType?: DateTimezoneUtcNormalInstanceTransformType): TransformDateInTimezoneNormalFunction;
/**
 * Converts the start and end dates of a {@link DateRange} to a specific timezone,
 * retaining a reference to the instance and transform type used.
 */
export type TransformDateRangeToTimezoneFunction = TransformDateRangeDatesFunction & {
    readonly _timezoneInstance: DateTimezoneUtcNormalInstance;
    readonly _transformType: DateTimezoneUtcNormalInstanceTransformType;
};
/**
 * Creates a {@link TransformDateRangeToTimezoneFunction} that converts both dates in
 * a {@link DateRange} using the specified transform type.
 *
 * @param timezoneInput - Timezone configuration for the conversion.
 * @param transformType - Defaults to `'systemDateToTargetDate'`
 * @returns Range converter that applies the configured transform to both endpoints.
 *
 * @__NO_SIDE_EFFECTS__
 */
export declare function transformDateRangeToTimezoneFunction(timezoneInput: DateTimezoneUtcNormalFunctionInput, transformType?: DateTimezoneUtcNormalInstanceTransformType): TransformDateRangeToTimezoneFunction;
/**
 * Like {@link TransformDateInTimezoneNormalFunction} but operates on a {@link DateRange}.
 *
 * Converts the range into the target date space, applies a range transformation, then converts back.
 */
export type TransformDateRangeInTimezoneNormalFunction = ((dateRange: DateRange, transform: TransformDateRangeDatesFunction) => DateRange) & {
    readonly _timezoneInstance: DateTimezoneUtcNormalInstance;
    readonly _transformType: DateTimezoneUtcNormalInstanceTransformType;
};
/**
 * Creates a {@link TransformDateRangeInTimezoneNormalFunction} that converts a date range
 * into the specified date space, applies a user-provided range transformation, then converts back.
 *
 * @param timezoneInput - Timezone configuration for the conversion.
 * @param transformType - Defaults to `'systemDateToTargetDate'`
 * @returns Range transformer that round-trips a range through the configured normalization.
 *
 * @__NO_SIDE_EFFECTS__
 */
export declare function transformDateRangeInTimezoneNormalFunction(timezoneInput: DateTimezoneUtcNormalFunctionInput, transformType?: DateTimezoneUtcNormalInstanceTransformType): TransformDateRangeInTimezoneNormalFunction;
/**
 * Parses an {@link ISO8601DayString} (e.g. `'2024-06-15'`) and returns the start-of-day
 * instant in the configured timezone.
 */
export type StartOfDayInTimezoneDayStringFactory = (day: ISO8601DayString) => Date;
/**
 * Creates a {@link StartOfDayInTimezoneDayStringFactory} bound to the given timezone.
 *
 * @param timezone - Timezone configuration to bind the factory to.
 * @returns A factory that converts ISO8601 day strings to start-of-day dates.
 *
 * @example
 * ```ts
 * const startOfDayInDenver = startOfDayInTimezoneDayStringFactory('America/Denver');
 * const midnight = startOfDayInDenver('2024-06-15');
 * // midnight is 2024-06-15T06:00:00.000Z (midnight MDT = 6AM UTC)
 * ```
 *
 * @__NO_SIDE_EFFECTS__
 */
export declare function startOfDayInTimezoneDayStringFactory(timezone?: DateTimezoneUtcNormalFunctionInput): StartOfDayInTimezoneDayStringFactory;
/**
 * One-shot convenience that parses an {@link ISO8601DayString} and returns the start-of-day
 * instant in the given timezone. Creates a temporary instance internally; prefer
 * {@link startOfDayInTimezoneDayStringFactory} when processing multiple days.
 *
 * @param day - The ISO8601 day string to parse.
 * @param timezone - Timezone configuration for the start-of-day calculation.
 * @returns The start-of-day instant in the given timezone.
 *
 * @example
 * ```ts
 * const midnight = startOfDayInTimezoneFromISO8601DayString('2024-06-15', 'America/Denver');
 * ```
 */
export declare function startOfDayInTimezoneFromISO8601DayString(day: ISO8601DayString, timezone?: DateTimezoneUtcNormalFunctionInput): Date;
export interface SetOnDateWithTimezoneNormalFunctionInput {
    /**
     * Date to update
     *
     * If not defined, will use "now".
     */
    readonly date?: Maybe<Date>;
    /**
     * The input date target type of the date and copyFrom values.
     *
     * Defaults to "target"
     */
    readonly inputType?: DateTimezoneConversionTarget;
    /**
     * The return date target type.
     *
     * Defaults to to the inputType, or to "target" if neither are defined.
     */
    readonly outputType?: DateTimezoneConversionTarget;
    /**
     * Hours to set
     */
    readonly hours?: Maybe<number>;
    /**
     * Minutes to set
     */
    readonly minutes?: Maybe<number>;
    /**
     * (Optional) date value to copy from.
     *
     * If hours or minutes are set, those values take priority over the value read from this.
     */
    readonly copyFrom?: Maybe<LogicalDate>;
    /**
     * If true, will copy the hours from the input date.
     *
     * Defaults to true.
     */
    readonly copyHours?: Maybe<boolean>;
    /**
     * If true, will copy the minutes from the input date.
     *
     * Defaults to true.
     */
    readonly copyMinutes?: Maybe<boolean>;
    /**
     * Whether or not to round down to the nearest minute.
     *
     * Defaults to false.
     */
    readonly roundDownToMinute?: Maybe<boolean>;
}
/**
 * Sets the input values on the input date.
 */
export type SetOnDateWithTimezoneNormalFunction = ((input: SetOnDateWithTimezoneNormalFunctionInput) => Date) & {
    readonly _timezoneInstance: DateTimezoneUtcNormalInstance;
};
/**
 * Creates a {@link SetOnDateWithTimezoneNormalFunction} bound to the given timezone.
 *
 * The returned function sets hours/minutes on a date while correctly handling
 * timezone conversions and DST boundaries. It converts the input to base date space,
 * applies the hour/minute changes, then converts back to the requested output space.
 *
 * @param timezone - Timezone configuration the resulting function is bound to.
 * @returns Configured setter that applies hour/minute updates in the bound timezone.
 *
 * @example
 * ```ts
 * const setOnDate = setOnDateWithTimezoneNormalFunction('America/Denver');
 * const result = setOnDate({ date: someDate, hours: 14, minutes: 30, inputType: 'target' });
 * // result is someDate with hours set to 14:30 in Denver time
 * ```
 *
 * @__NO_SIDE_EFFECTS__
 */
export declare function setOnDateWithTimezoneNormalFunction(timezone: DateTimezoneUtcNormalFunctionInput): SetOnDateWithTimezoneNormalFunction;
/**
 * Copies the current wall-clock hours and minutes (from "now") onto the input date,
 * respecting the given timezone. Shorthand for calling
 * {@link copyHoursAndMinutesFromDateWithTimezoneNormal} with `'now'`.
 *
 * @param input - Date whose calendar day is preserved.
 * @param timezone - Timezone context used to interpret the wall-clock time.
 * @returns Copy of the input with hours and minutes overwritten by the current wall-clock time.
 */
export declare function copyHoursAndMinutesFromNowWithTimezoneNormal(input: Date, timezone: DateTimezoneUtcNormalFunctionInput): Date;
/**
 * Copies hours and minutes from `copyFrom` onto `input`, where both dates are interpreted
 * in the target timezone. Internally converts to base date space, applies the copy, and converts back.
 *
 * @param input - Date whose calendar day is preserved.
 * @param copyFrom - Source date (or `'now'`) whose hours/minutes are read.
 * @param timezone - Timezone context applied to both endpoints during the copy.
 * @returns Copy of the input with hours and minutes overwritten by the source.
 *
 * @example
 * ```ts
 * // Set the time on a Denver date to match another Denver date's time
 * const result = copyHoursAndMinutesFromDateWithTimezoneNormal(
 *   targetDate,
 *   sourceDate,
 *   'America/Denver'
 * );
 * ```
 */
export declare function copyHoursAndMinutesFromDateWithTimezoneNormal(input: Date, copyFrom: LogicalDate, timezone: DateTimezoneUtcNormalFunctionInput): Date;