import { type DateOrDateString, type DateRelativeState, type FactoryWithRequiredInput, type MapFunction, type Maybe, type ISO8601DayString, type DayOfWeek } from '@dereekb/util';
/**
 * Anchors a value to a specific start date, useful as a base for ranges and scheduling.
 */
export interface DateRangeStart {
    start: Date;
}
/**
 * Type guard to check if a value conforms to the {@link DateRangeStart} interface.
 *
 * @param value - The value to check.
 * @returns True if the value has a valid Date `start` property.
 *
 * @example
 * ```ts
 * isDateRangeStart({ start: new Date() }); // true
 * isDateRangeStart({ start: 'not-a-date' }); // false
 * ```
 */
export declare function isDateRangeStart(value: unknown): value is DateRangeStart;
/**
 * Compare function for sorting {@link DateRangeStart} values in ascending chronological order by their start date.
 * Suitable for use with `Array.prototype.sort()`.
 *
 * @example
 * ```ts
 * const items: DateRangeStart[] = [
 *   { start: new Date('2024-03-01') },
 *   { start: new Date('2024-01-01') }
 * ];
 * items.sort(sortDateRangeStartAscendingCompareFunction);
 * // [{ start: 2024-01-01 }, { start: 2024-03-01 }]
 * ```
 */
export declare const sortDateRangeStartAscendingCompareFunction: <T extends DateRangeStart>(a: T, b: T) => number;
/**
 * Defines a bounded time period with a start and end date, used throughout the date module
 * for filtering, iteration, and comparison operations.
 */
export interface DateRange extends DateRangeStart {
    end: Date;
}
/**
 * Counts the total number of calendar days spanned by the range, inclusive of both endpoints.
 * Always returns at least 1, even for same-day ranges.
 *
 * @param dateRange - Range to measure.
 * @returns Inclusive count of calendar days covered by the range.
 *
 * @dbxUtil
 * @dbxUtilCategory date
 * @dbxUtilTags date, range, days, count, duration, span, length
 * @dbxUtilRelated is-date-range, is-same-date-range
 *
 * @example
 * ```ts
 * const range = { start: new Date('2024-01-01'), end: new Date('2024-01-03') };
 * dateRangeDaysCount(range); // 3
 * ```
 */
export declare function dateRangeDaysCount(dateRange: DateRange): number;
/**
 * Type guard to check if a value is a valid {@link DateRange} with both start and end as Date objects.
 *
 * @param input - The value to check.
 * @returns True if the value has valid Date `start` and `end` properties.
 *
 * @dbxUtil
 * @dbxUtilCategory date
 * @dbxUtilTags date, range, type-guard, check, validate
 * @dbxUtilRelated is-date-range-start, date-range-days-count
 *
 * @example
 * ```ts
 * isDateRange({ start: new Date(), end: new Date() }); // true
 * isDateRange({ start: new Date() }); // false
 * isDateRange('not-a-range'); // false
 * ```
 */
export declare function isDateRange(input: unknown): input is DateRange;
/**
 * Compares two date ranges for exact millisecond equality on both start and end.
 * Returns true if both are nullish.
 *
 * @param a - First date range to compare.
 * @param b - Second date range to compare.
 * @returns True if both ranges are equal or both are nullish.
 *
 * @dbxUtil
 * @dbxUtilCategory date
 * @dbxUtilTags date, range, equal, equality, same, compare
 * @dbxUtilRelated is-same-date-day-range, is-date-range
 *
 * @example
 * ```ts
 * const a = { start: new Date('2024-01-01'), end: new Date('2024-01-31') };
 * const b = { start: new Date('2024-01-01'), end: new Date('2024-01-31') };
 * isSameDateRange(a, b); // true
 * isSameDateRange(null, null); // true
 * ```
 */
export declare function isSameDateRange(a: Maybe<Partial<DateRange>>, b: Maybe<Partial<DateRange>>): boolean;
/**
 * Compares two date ranges for calendar-day equality, ignoring time-of-day differences.
 * Returns true if both are nullish.
 *
 * @param a - First date range to compare.
 * @param b - Second date range to compare.
 * @returns True if both ranges fall on the same calendar days or both are nullish.
 *
 * @example
 * ```ts
 * const a = { start: new Date('2024-01-01T08:00:00'), end: new Date('2024-01-31T10:00:00') };
 * const b = { start: new Date('2024-01-01T20:00:00'), end: new Date('2024-01-31T23:00:00') };
 * isSameDateDayRange(a, b); // true (same calendar days)
 * ```
 */
export declare function isSameDateDayRange(a: Maybe<Partial<DateRange>>, b: Maybe<Partial<DateRange>>): boolean;
/**
 * Checks whether the range is unbounded (neither start nor end is set), meaning it conceptually includes all dates.
 *
 * @param input - The partial date range to check.
 * @returns True if neither start nor end is set.
 *
 * @example
 * ```ts
 * isInfiniteDateRange({}); // true
 * isInfiniteDateRange({ start: new Date() }); // false
 * ```
 */
export declare function isInfiniteDateRange(input: Partial<DateRange>): boolean;
/**
 * Checks whether the range has only one of start or end set, but not both.
 *
 * @param input - The partial date range to check.
 * @returns True if exactly one of start or end is set.
 *
 * @example
 * ```ts
 * isPartialDateRange({ start: new Date() }); // true
 * isPartialDateRange({ start: new Date(), end: new Date() }); // false
 * ```
 */
export declare function isPartialDateRange(input: Partial<DateRange>): input is DateRange;
/**
 * Checks whether the range has both start and end set.
 *
 * @param input - The partial date range to check.
 * @returns True if both start and end are set.
 *
 * @example
 * ```ts
 * isFullDateRange({ start: new Date(), end: new Date() }); // true
 * isFullDateRange({ start: new Date() }); // false
 * ```
 */
export declare function isFullDateRange(input: Partial<DateRange>): input is DateRange;
/**
 * Union type representing either a single Date or a {@link DateRange}.
 */
export type DateOrDateRange = Date | DateRange;
/**
 * Normalizes a Date or {@link DateRange} into a DateRange. When given a single Date,
 * uses it as start and optionally uses the provided end date (defaults to the same date).
 *
 * @param startOrDateRange - Range or starting Date for the new range.
 * @param end - Optional end date when the first argument is a plain Date.
 * @returns Normalized range covering the inputs.
 *
 * @example
 * ```ts
 * const range = dateOrDateRangeToDateRange(new Date('2024-01-01'), new Date('2024-01-31'));
 * // { start: 2024-01-01, end: 2024-01-31 }
 *
 * const existing = { start: new Date('2024-01-01'), end: new Date('2024-01-31') };
 * dateOrDateRangeToDateRange(existing); // returns the same range
 * ```
 */
export declare function dateOrDateRangeToDateRange(startOrDateRange: DateOrDateRange, end?: Maybe<Date>): DateRange;
export declare enum DateRangeType {
    /**
     * Full day of the date. Ignores distance.
     */
    DAY = "day",
    /**
     * Full week of the date. Ignores distance.
     */
    WEEK = "week",
    /**
     * Full month of the date. Ignores distance.
     */
    MONTH = "month",
    /**
     * Full minute of the date. Ignores distance.
     */
    MINUTE = "minute",
    /**
     * Full hour of the date. Ignores distance.
     */
    HOUR = "hour",
    /**
     * Full minutes between the date and the target date in the given distance/direction.
     */
    MINUTES_RANGE = "minutes_range",
    /**
     * Full hours between the date and the target date in the given distance/direction.
     */
    HOURS_RANGE = "hours_range",
    /**
     * Days between the date and the target date in the given distance/direction.
     */
    DAYS_RANGE = "days_range",
    /**
     * Full weeks between the date and the target date in the given distance/direction.
     */
    WEEKS_RANGE = "weeks_range",
    /**
     * Full months between the date and the target date in the given distance/direction.
     */
    MONTHS_RANGE = "months_range",
    /**
     * Radius specified in minutes with the input.
     */
    MINUTES_RADIUS = "minutes_radius",
    /**
     * Radius specified in hours with the input.
     */
    HOURS_RADIUS = "hours_radius",
    /**
     * Radius specified in days with the input.
     */
    DAYS_RADIUS = "days_radius",
    /**
     * Radius specified in weeks with the input.
     */
    WEEKS_RADIUS = "weeks_radius",
    /**
     * All surrounding days that would appear on a calendar with this date.
     */
    CALENDAR_MONTH = "calendar_month"
}
/**
 * Params for building a date range.
 */
export interface DateRangeParams {
    /**
     * Type of range.
     */
    readonly type: DateRangeType;
    /**
     * Date to filter on. If not provided, assumes now.
     */
    readonly date: Date;
    readonly distance?: number;
}
export interface DateRangeTypedInput {
    type: DateRangeType;
    date?: Maybe<Date>;
    distance?: Maybe<number>;
}
/**
 * Simplified input for {@link dateRange} that treats distance as a number of days from the start date,
 * avoiding the need to specify a {@link DateRangeType}.
 */
export interface DateRangeDayDistanceInput {
    date?: Maybe<Date>;
    distance: number;
}
export interface DateRangeDistanceInput extends DateRangeDayDistanceInput {
    type?: DateRangeType;
}
export type DateRangeInput = (DateRangeTypedInput | DateRangeDistanceInput) & {
    roundToMinute?: boolean;
};
/**
 * Creates a {@link DateRange} from the given type and optional parameters. Supports many range
 * strategies including fixed periods (day, week, month), directional ranges, and radii.
 *
 * @param input - The range type or full configuration object.
 * @param inputRoundToMinute - Optional override to round the date to the start of its minute.
 * @returns Computed range satisfying the requested strategy.
 * @throws {Error} If the type is not a recognized {@link DateRangeType}.
 *
 * @example
 * ```ts
 * // Full day range for today
 * dateRange(DateRangeType.DAY);
 *
 * // 3 days forward from a specific date
 * dateRange({ type: DateRangeType.DAYS_RANGE, date: new Date('2024-01-01'), distance: 3 });
 *
 * // Calendar month view (includes surrounding weeks)
 * dateRange({ type: DateRangeType.CALENDAR_MONTH, date: new Date('2024-06-15') });
 * ```
 */
export declare function dateRange(input: DateRangeType | DateRangeInput, inputRoundToMinute?: boolean): DateRange;
/**
 * Returns a range spanning the full calendar day (first to last millisecond) of the given date.
 * Convenience wrapper around {@link dateRange} with {@link DateRangeType.DAY}.
 *
 * @param date - Reference date whose surrounding calendar day to capture.
 * @returns Range from start of day to end of day for the reference date.
 *
 * @example
 * ```ts
 * const range = dateRangeFromStartAndEndOfDay(new Date('2024-06-15T14:30:00'));
 * // { start: 2024-06-15T00:00:00, end: 2024-06-15T23:59:59.999 }
 * ```
 */
export declare function dateRangeFromStartAndEndOfDay(date: Date): DateRange;
/**
 * Function that iterates dates within a date range at a pre-configured iteration step.
 */
export type IterateDatesInDateRangeFunction = <T = void>(dateRange: DateRange, forEachFn: (date: Date) => T) => T[];
/**
 * Returns the next value to iterate on.
 */
export type IterateDaysGetNextValueFunction = MapFunction<Date, Date>;
/**
 * Configuration for creating an {@link IterateDatesInDateRangeFunction} via {@link iterateDaysInDateRangeFunction}.
 * Controls iteration limits and the step function used to advance between dates.
 */
export interface IterateDaysInDateRangeFunctionConfig {
    /**
     * (Optional) Max number of iterations allowed when iterating a date range.
     *
     * If the iteration count exceeds this size, behavior depends on {@link throwErrorOnMaxIterations}.
     *
     * If 0 or false, there is no max size.
     *
     * Defaults to 4000.
     */
    readonly maxIterations?: number | 0 | false;
    /**
     * Whether or not to throw an error when the max iteration size is reached.
     *
     * True by default.
     */
    readonly throwErrorOnMaxIterations?: boolean;
    readonly getNextDate: IterateDaysGetNextValueFunction;
}
export declare const DEFAULT_ITERATE_DAYS_IN_DATE_RANGE_MAX_ITERATIONS = 4000;
export type IterateDaysInDateRangeFunctionConfigInput = IterateDaysInDateRangeFunctionConfig | IterateDaysGetNextValueFunction;
/**
 * Sentinel error thrown by {@link endItreateDaysInDateRangeEarly} to signal early termination
 * of date range iteration. Caught internally by {@link iterateDaysInDateRangeFunction}.
 */
export declare class IterateDaysInDateRangeFunctionBailError extends Error {
    constructor(message?: string);
}
/**
 * Throws a {@link IterateDaysInDateRangeFunctionBailError} to stop date range iteration early
 * from within a forEach callback. Only works inside functions created by {@link iterateDaysInDateRangeFunction}.
 *
 * @throws {@link IterateDaysInDateRangeFunctionBailError} Always.
 */
export declare function endItreateDaysInDateRangeEarly(): void;
/**
 * Creates a reusable function that iterates over dates within a range using a configurable step function.
 * Supports max iteration limits and early bail-out via {@link endItreateDaysInDateRangeEarly}.
 *
 * @param input - Configuration or step function for advancing between dates.
 * @returns Reusable iterator bound to the configured stepping strategy.
 * @throws {Error} If max iterations is exceeded and throwErrorOnMaxIterations is true.
 *
 * @example
 * ```ts
 * // Iterate every 2 days
 * const iterateEvery2Days = iterateDaysInDateRangeFunction((date) => addDays(date, 2));
 * const results = iterateEvery2Days(range, (date) => date.toISOString());
 * ```
 *
 * @__NO_SIDE_EFFECTS__
 */
export declare function iterateDaysInDateRangeFunction(input: IterateDaysInDateRangeFunctionConfigInput): IterateDatesInDateRangeFunction;
/**
 * Iterates over dates within a {@link DateRange}, advancing by the provided getNextDate step function.
 * A simpler alternative to {@link iterateDaysInDateRangeFunction} for one-off usage.
 *
 * @param dateRange - the range to iterate over
 * @param forEachFn - callback invoked for each date in the range
 * @param getNextDate - step function that returns the next date from the current one
 * @returns an array of results from forEachFn, or void
 */
export declare function iterateDaysInDateRange(dateRange: DateRange, forEachFn: (date: Date) => void, getNextDate: (date: Date) => Date): void;
export declare function iterateDaysInDateRange<T>(dateRange: DateRange, forEachFn: (date: Date) => T, getNextDate: (date: Date) => Date): T[];
/**
 * Pre-built iteration function that steps one day at a time through a {@link DateRange}.
 * Calls the provided function for each day starting from the range's start date.
 */
export declare const forEachDayInDateRange: IterateDatesInDateRangeFunction;
/**
 * Configuration for {@link expandDaysForDateRangeFunction} controlling the safety limit
 * on how many days can be expanded from a single range.
 */
export interface ExpandDaysForDateRangeConfig {
    /**
     * (Optional) Max expansion size for expanding a date range.
     *
     * If the expected expansion is larger than this size, an exception is thrown.
     *
     * If 0 or false, there is no max size.
     *
     * Defaults to 1500 days.
     */
    readonly maxExpansionSize?: number | 0 | false;
}
export declare const DEFAULT_EXPAND_DAYS_FOR_DATE_RANGE_MAX_EXPANSION_SIZE = 1500;
export type ExpandDaysForDateRangeFunction = FactoryWithRequiredInput<Date[], DateRange>;
/**
 * Creates a reusable function that expands a {@link DateRange} into an array of individual day dates.
 * Includes a configurable safety limit to prevent accidental memory exhaustion from large ranges.
 *
 * @param config - Optional configuration for the max expansion size.
 * @returns Expander that produces one date per day inside the input range.
 * @throws {Error} If the range spans more days than the configured maxExpansionSize.
 *
 * @example
 * ```ts
 * const expand = expandDaysForDateRangeFunction({ maxExpansionSize: 365 });
 * const days = expand({ start: new Date('2024-01-01'), end: new Date('2024-01-03') });
 * // [2024-01-01, 2024-01-02, 2024-01-03]
 * ```
 *
 * @__NO_SIDE_EFFECTS__
 */
export declare function expandDaysForDateRangeFunction(config?: ExpandDaysForDateRangeConfig): ExpandDaysForDateRangeFunction;
/**
 * Expands a {@link DateRange} into an array of one Date per day. Uses the default max expansion size.
 * Convenience wrapper around {@link expandDaysForDateRangeFunction}.
 *
 * @param range - Range whose individual days should be produced.
 * @returns One Date per day in the range.
 *
 * @example
 * ```ts
 * const days = expandDaysForDateRange({ start: new Date('2024-01-01'), end: new Date('2024-01-03') });
 * // [2024-01-01, 2024-01-02, 2024-01-03]
 * ```
 */
export declare function expandDaysForDateRange(range: DateRange): Date[];
/**
 * Determines whether the current moment (or provided `now`) falls before, within, or after the given range.
 *
 * @param dateRange - Range whose endpoints classify the reference moment.
 * @param now - Reference moment, defaults to the current date/time.
 * @returns 'past', 'present', or 'future'.
 *
 * @example
 * ```ts
 * const range = { start: new Date('2024-01-01'), end: new Date('2024-12-31') };
 * dateRangeRelativeState(range, new Date('2024-06-15')); // 'present'
 * dateRangeRelativeState(range, new Date('2025-01-01')); // 'past'
 * dateRangeRelativeState(range, new Date('2023-12-31')); // 'future'
 * ```
 */
export declare function dateRangeRelativeState(dateRange: DateRange, now?: Date): DateRelativeState;
export interface GroupDateRangesByDateRelativeStatesResult<T extends DateRange> {
    readonly past: T[];
    readonly present: T[];
    readonly future: T[];
}
/**
 * Groups an array of date ranges into past, present, and future buckets based on the current moment (or provided `now`).
 *
 * @param dateRanges - Ranges to classify against the reference moment.
 * @param _now - Reference moment, defaults to the current date/time.
 * @returns Buckets of ranges separated into past, present, and future.
 *
 * @example
 * ```ts
 * const ranges = [
 *   { start: new Date('2023-01-01'), end: new Date('2023-12-31') },
 *   { start: new Date('2024-06-01'), end: new Date('2024-06-30') },
 * ];
 * const grouped = groupDateRangesByDateRelativeState(ranges, new Date('2024-06-15'));
 * // grouped.past = [first range], grouped.present = [second range], grouped.future = []
 * ```
 */
export declare function groupDateRangesByDateRelativeState<T extends DateRange>(dateRanges: T[], _now?: Date): GroupDateRangesByDateRelativeStatesResult<T>;
export type DateRangeFunctionDateRangeRef<T extends Partial<DateRange> = Partial<DateRange>> = {
    readonly _dateRange: T;
};
/**
 * Returns true if the input date is contained within the configured DateRange or DateRangeStart.
 *
 * A dateRange that has no start and end is considered to include all dates.
 */
export type IsDateInDateRangeFunction<T extends Partial<DateRange> = DateRange> = ((date: Date) => boolean) & DateRangeFunctionDateRangeRef<T>;
/**
 * Checks whether a date falls within a (possibly partial) date range.
 * Convenience wrapper around {@link isDateInDateRangeFunction}.
 *
 * @param date - Moment to test.
 * @param dateRange - Range to test the moment against.
 * @returns Whether the moment falls within the range.
 *
 * @example
 * ```ts
 * const range = { start: new Date('2024-01-01'), end: new Date('2024-12-31') };
 * isDateInDateRange(new Date('2024-06-15'), range); // true
 * isDateInDateRange(new Date('2025-01-01'), range); // false
 * ```
 */
export declare function isDateInDateRange(date: Date, dateRange: Partial<DateRange>): boolean;
/**
 * Creates a reusable function that tests whether dates fall within the given range.
 * Handles partial ranges: if only start is set, checks >= start; if only end, checks <= end;
 * if neither, all dates are considered in range.
 *
 * @param dateRange - Boundary range that candidate dates are compared against.
 * @returns Predicate that reports whether a date falls inside the configured range.
 *
 * @example
 * ```ts
 * const isInQ1 = isDateInDateRangeFunction({
 *   start: new Date('2024-01-01'),
 *   end: new Date('2024-03-31')
 * });
 * isInQ1(new Date('2024-02-15')); // true
 * isInQ1(new Date('2024-05-01')); // false
 * ```
 *
 * @__NO_SIDE_EFFECTS__
 */
export declare function isDateInDateRangeFunction<T extends Partial<DateRange>>(dateRange: T): IsDateInDateRangeFunction<T>;
/**
 * Returns true if the input DateRange is contained within the configured DateRange.
 */
export type IsDateRangeInDateRangeFunction<T extends Partial<DateRange> = Partial<DateRange>> = ((dateRange: DateRange) => boolean) & DateRangeFunctionDateRangeRef<T>;
/**
 * Checks whether a date range is fully contained within another (possibly partial) date range.
 * Convenience wrapper around {@link isDateRangeInDateRangeFunction}.
 *
 * @param compareDateRange - The range to test for containment.
 * @param dateRange - The boundary range.
 * @returns True if compareDateRange is fully within dateRange.
 *
 * @example
 * ```ts
 * const outer = { start: new Date('2024-01-01'), end: new Date('2024-12-31') };
 * const inner = { start: new Date('2024-03-01'), end: new Date('2024-06-30') };
 * isDateRangeInDateRange(inner, outer); // true
 * ```
 */
export declare function isDateRangeInDateRange(compareDateRange: DateRange, dateRange: Partial<DateRange>): boolean;
/**
 * Creates a reusable function that tests whether a given date range is fully contained within
 * the configured boundary range. Both start and end of the input must be within bounds.
 *
 * @param dateRange - Boundary range that candidate ranges must fit inside.
 * @returns Predicate that reports whether a candidate range is fully contained.
 *
 * @example
 * ```ts
 * const isInYear = isDateRangeInDateRangeFunction({
 *   start: new Date('2024-01-01'),
 *   end: new Date('2024-12-31')
 * });
 * isInYear({ start: new Date('2024-03-01'), end: new Date('2024-06-30') }); // true
 * isInYear({ start: new Date('2023-12-01'), end: new Date('2024-06-30') }); // false
 * ```
 *
 * @__NO_SIDE_EFFECTS__
 */
export declare function isDateRangeInDateRangeFunction<T extends Partial<DateRange> = DateRange>(dateRange: T): IsDateRangeInDateRangeFunction<T>;
/**
 * Returns true if the input DateRange overlaps the configured DateRange in any way.
 */
export type DateRangeOverlapsDateRangeFunction<T extends DateRange = DateRange> = ((dateRange: DateRangeStart & Partial<DateRange>) => boolean) & DateRangeFunctionDateRangeRef<T>;
/**
 * Checks whether two date ranges overlap in any way (partial or full).
 * Convenience wrapper around {@link dateRangeOverlapsDateRangeFunction}.
 *
 * @param compareDateRange - The range to test for overlap.
 * @param dateRange - The reference range.
 * @returns True if the ranges overlap.
 *
 * @example
 * ```ts
 * const a = { start: new Date('2024-01-01'), end: new Date('2024-06-30') };
 * const b = { start: new Date('2024-03-01'), end: new Date('2024-12-31') };
 * dateRangeOverlapsDateRange(a, b); // true
 * ```
 */
export declare function dateRangeOverlapsDateRange(compareDateRange: DateRange, dateRange: DateRange): boolean;
/**
 * Creates a reusable function that tests whether input ranges overlap the configured boundary range.
 * Two ranges overlap if one starts before the other ends, and vice versa.
 *
 * @param dateRange - Boundary range that candidates are tested for overlap against.
 * @returns Predicate that reports whether a candidate range overlaps the boundary.
 *
 * @example
 * ```ts
 * const overlapsQ1 = dateRangeOverlapsDateRangeFunction({
 *   start: new Date('2024-01-01'),
 *   end: new Date('2024-03-31')
 * });
 * overlapsQ1({ start: new Date('2024-03-15'), end: new Date('2024-04-15') }); // true
 * overlapsQ1({ start: new Date('2024-05-01'), end: new Date('2024-06-01') }); // false
 * ```
 *
 * @__NO_SIDE_EFFECTS__
 */
export declare function dateRangeOverlapsDateRangeFunction<T extends DateRange = DateRange>(dateRange: T): DateRangeOverlapsDateRangeFunction<T>;
/**
 * Collapses a multi-day UTC date range down to a single 24-hour period, preserving only the
 * time-of-day relationship between start and end. Useful for extracting a daily schedule window
 * from a range that may span multiple days.
 *
 * The order of times is retained. If start and end share the same time but span multiple days,
 * the result is a full 24-hour period.
 *
 * Operates in UTC, so daylight savings transitions are not considered.
 *
 * @param dateRange - Range whose endpoints should be collapsed onto a single day.
 * @returns Range with the same start whose end lies within 24 hours of start.
 *
 * @example
 * ```ts
 * // 10AM to 1PM across 3 days becomes same-day 10AM to 1PM
 * const range = { start: new Date('2024-01-01T10:00:00Z'), end: new Date('2024-01-03T13:00:00Z') };
 * const fitted = fitUTCDateRangeToDayPeriod(range);
 * // fitted.start = 2024-01-01T10:00:00Z, fitted.end = 2024-01-01T13:00:00Z
 * ```
 */
export declare function fitUTCDateRangeToDayPeriod<T extends DateRange = DateRange>(dateRange: T): T;
/**
 * Clamps the input range to the pre-configured date range.
 */
export type ClampDateFunction = ((date: Date) => Date) & DateRangeFunctionDateRangeRef;
/**
 * Creates a reusable function that clamps dates to fall within the given range boundaries.
 * Dates before start are clamped to start; dates after end are clamped to end.
 * Partial ranges clamp only on the side that is defined.
 *
 * @param dateRange - Boundary range that input dates are clamped against.
 * @returns Clamper that snaps each input into the configured range.
 *
 * @example
 * ```ts
 * const clamp = clampDateFunction({
 *   start: new Date('2024-01-01'),
 *   end: new Date('2024-12-31')
 * });
 * clamp(new Date('2023-06-15')); // 2024-01-01
 * clamp(new Date('2024-06-15')); // 2024-06-15 (unchanged)
 * clamp(new Date('2025-06-15')); // 2024-12-31
 * ```
 *
 * @__NO_SIDE_EFFECTS__
 */
export declare function clampDateFunction(dateRange: Partial<DateRange>): ClampDateFunction;
/**
 * Clamps a single date to fall within the given range boundaries.
 * Convenience wrapper around {@link clampDateFunction}.
 *
 * @param date - Moment to clamp.
 * @param dateRange - Boundary range that the moment is clamped against.
 * @returns Clamped moment inside the range.
 *
 * @example
 * ```ts
 * const range = { start: new Date('2024-01-01'), end: new Date('2024-12-31') };
 * clampDateToDateRange(new Date('2023-06-15'), range); // 2024-01-01
 * ```
 */
export declare function clampDateToDateRange(date: Date, dateRange: Partial<DateRange>): Date;
export type ClampPartialDateRangeFunction = ((date: Partial<DateRange>, clampNullValues?: boolean) => Partial<DateRange>) & DateRangeFunctionDateRangeRef;
export type ClampDateRangeFunction = ((date: Partial<DateRange>, clampNullValues?: boolean) => DateRange) & DateRangeFunctionDateRangeRef<DateRange>;
/**
 * Creates a reusable function that clamps an entire date range to fit within the configured boundaries.
 * When `clampNullValues` is true, missing start/end values on the input are replaced with the boundary values.
 *
 * @param dateRange - the boundary range for clamping
 * @param defaultClampNullValues - whether to fill missing values with boundary values
 * @returns a function that clamps date ranges
 *
 * @example
 * ```ts
 * const clamp = clampDateRangeFunction({
 *   start: new Date('2024-01-01'),
 *   end: new Date('2024-12-31')
 * });
 * const result = clamp({ start: new Date('2023-06-01'), end: new Date('2024-06-30') });
 * // { start: 2024-01-01, end: 2024-06-30 }
 * ```
 * @__NO_SIDE_EFFECTS__
 */
export declare function clampDateRangeFunction(dateRange: DateRange, defaultClampNullValues?: boolean): ClampDateRangeFunction;
export declare function clampDateRangeFunction(dateRange: Partial<DateRange>, defaultClampNullValues?: boolean): ClampPartialDateRangeFunction;
/**
 * Clamps a date range to fit within a boundary range.
 * Convenience wrapper around {@link clampDateRangeFunction}.
 *
 * @param inputDateRange - Range whose endpoints should be clamped.
 * @param limitToDateRange - Boundary range that the input is clamped against.
 * @returns Clamped range fitting inside the boundary.
 *
 * @example
 * ```ts
 * const input = { start: new Date('2023-06-01'), end: new Date('2024-06-30') };
 * const limit = { start: new Date('2024-01-01'), end: new Date('2024-12-31') };
 * clampDateRangeToDateRange(input, limit);
 * // { start: 2024-01-01, end: 2024-06-30 }
 * ```
 */
export declare function clampDateRangeToDateRange(inputDateRange: Partial<DateRange>, limitToDateRange: Partial<DateRange>): Partial<DateRange>;
/**
 * Transforms both of the dates in the date range function.
 */
export type TransformDateRangeDatesFunction = (dateRange: DateRange) => DateRange;
/**
 * Creates a function that applies a date transformation to both start and end of a {@link DateRange}.
 *
 * @param transform - Mapping applied to both endpoints of every input range.
 * @returns Transformer that returns a range with both endpoints mapped.
 *
 * @example
 * ```ts
 * import { startOfHour } from 'date-fns';
 * const roundToHour = transformDateRangeDatesFunction(startOfHour);
 * const range = { start: new Date('2024-01-01T10:30:00'), end: new Date('2024-01-01T14:45:00') };
 * roundToHour(range); // { start: 2024-01-01T10:00:00, end: 2024-01-01T14:00:00 }
 * ```
 *
 * @__NO_SIDE_EFFECTS__
 */
export declare function transformDateRangeDatesFunction(transform: MapFunction<Date, Date>): TransformDateRangeDatesFunction;
/**
 * Pre-built {@link TransformDateRangeDatesFunction} that rounds both start and end to the beginning of their respective days.
 */
export declare const transformDateRangeWithStartOfDay: TransformDateRangeDatesFunction;
/**
 * Variant of {@link DateRange} that accepts Date objects, ISO 8601 date-time strings, or ISO 8601 day strings
 * as values, useful for accepting serialized date range input before parsing.
 */
export interface DateRangeWithDateOrStringValue {
    start: DateOrDateString | ISO8601DayString;
    end: DateOrDateString | ISO8601DayString;
}
/**
 * Returns each unique day of the week present in the range, in the order they appear starting from
 * the range's start day. For ranges spanning 7+ days, returns all days of the week.
 *
 * @param dateRange - Range whose covered weekdays should be enumerated.
 * @returns Unique day-of-week values appearing in the range, in encounter order.
 *
 * @example
 * ```ts
 * // Wednesday through Friday
 * const range = { start: new Date('2024-01-03'), end: new Date('2024-01-05') };
 * getDaysOfWeekInDateRange(range); // [3, 4, 5] (Wed, Thu, Fri)
 * ```
 */
export declare function getDaysOfWeekInDateRange(dateRange: DateRange): DayOfWeek[];