@dereekb/date 13.0.7 → 13.2.0

package/src/lib/date/date.range.d.ts

@@ -1,62 +1,143 @@
 import { type DateOrDateString, type DateRelativeState, type FactoryWithRequiredInput, type MapFunction, type Maybe, type ISO8601DayString, type DayOfWeek } from '@dereekb/util';
 /**
- * Represents a start date.
+ * Anchors a value to a specific start date, useful as a base for ranges and scheduling.
  */
 export interface DateRangeStart {
     start: Date;
 }
 /**
- * Returns true if the input is a DateRangeStart.
+ * Type guard to check if a value conforms to the {@link DateRangeStart} interface.
  *
- * @param value
- * @returns
+ * @example
+ * ```ts
+ * isDateRangeStart({ start: new Date() }); // true
+ * isDateRangeStart({ start: 'not-a-date' }); // false
+ * ```
  */
 export declare function isDateRangeStart(value: unknown): value is DateRangeStart;
 /**
- * Sorts the input DateRangeStart values in ascending order by start Date.
+ * Compare function for sorting {@link DateRangeStart} values in ascending chronological order by their start date.
+ * Suitable for use with `Array.prototype.sort()`.
  *
- * @param a
- * @param b
- * @returns
+ * @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;
 /**
- * Represents a start and end date.
+ * 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;
 }
-export declare class DateRange {
+/**
+ * ArkType schema for {@link DateRange}.
+ */
+export declare const dateRangeType: import("arktype/internal/variants/object.ts").ObjectType<{
     start: Date;
     end: Date;
-    constructor(template: DateRange);
-}
+}, {}>;
 /**
- * Total number of days in the range. Minimum of 1 day.
+ * 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
- * @returns
+ * @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;
 /**
- * Returns true if the input is a DateRange.
+ * Type guard to check if a value is a valid {@link DateRange} with both start and end as Date objects.
  *
- * @param input
- * @returns
+ * @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.
+ *
+ * @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.
+ *
+ * @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;
 /**
- * Returns true if the date range has no start or end.
+ * Checks whether the range is unbounded (neither start nor end is set), meaning it conceptually includes all dates.
  *
- * @param input
- * @returns
+ * @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.
+ *
+ * @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.
+ *
+ * @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).
+ *
+ * @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 {
     /**
@@ -123,7 +204,7 @@ export declare enum DateRangeType {
 /**
  * Params for building a date range.
  */
-export declare class DateRangeParams {
+export interface DateRangeParams {
     /**
      * Type of range.
      */
@@ -133,15 +214,23 @@ export declare class DateRangeParams {
      */
     date: Date;
     distance?: number;
-    constructor(template: DateRangeParams);
 }
+/**
+ * ArkType schema for {@link DateRangeParams}.
+ */
+export declare const dateRangeParamsType: import("arktype/internal/variants/object.ts").ObjectType<{
+    type: DateRangeType;
+    date: Date;
+    distance?: number | undefined;
+}, {}>;
 export interface DateRangeTypedInput {
     type: DateRangeType;
     date?: Maybe<Date>;
     distance?: Maybe<number>;
 }
 /**
- * dateRange() input that infers duration to be a number of days, starting from the input date if applicable.
+ * 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>;
@@ -154,18 +243,33 @@ export type DateRangeInput = (DateRangeTypedInput | DateRangeDistanceInput) & {
     roundToMinute?: boolean;
 };
 /**
- * Creates a DateRange from the input DateRangeParams
+ * 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.
+ *
+ * @throws Error if the type is not a recognized {@link DateRangeType}
+ *
+ * @example
+ * ```ts
+ * // Full day range for today
+ * dateRange(DateRangeType.DAY);
  *
- * @param param0
- * @param roundToMinute
- * @returns
+ * // 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;
 /**
- * Convenience function that calls dateRange() to return the first millisecond and last millisecond of the input date.
+ * 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
- * @returns
+ * @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;
 /**
@@ -176,15 +280,19 @@ export type IterateDatesInDateRangeFunction = <T = void>(dateRange: DateRange, f
  * 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 {
     /**
-     * (Optiona) Max expansion size for expanding a date range.
+     * (Optional) Max number of iterations allowed when iterating a date range.
      *
-     * If the expected expansion is larger than this size, an exception is thrown.
+     * If the iteration count exceeds this size, behavior depends on {@link throwErrorOnMaxIterations}.
      *
      * If 0 or false, there is no max size.
      *
-     * Defaults to 4000 days.
+     * Defaults to 4000.
      */
     readonly maxIterations?: number | 0 | false;
     /**
@@ -197,35 +305,52 @@ export interface IterateDaysInDateRangeFunctionConfig {
 }
 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);
 }
 /**
- * Call to end iterating days in a date range early.
+ * 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 an IterateDaysInDateRangeFunction
+ * 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 getNextDate
- * @returns
+ * @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());
+ * ```
  */
 export declare function iterateDaysInDateRangeFunction(input: IterateDaysInDateRangeFunctionConfigInput): IterateDatesInDateRangeFunction;
 /**
- * Iterates date values within the given DateRange.
+ * Iterates over dates within a {@link DateRange}, advancing by the provided getNextDate step function.
+ * A simpler alternative to {@link iterateDaysInDateRangeFunction} for one-off usage.
  */
 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[];
 /**
- * Iterates each day in the date range, starting from the start date.
- *
- * @param dateRange
- * @param forEachFn
+ * 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 {
     /**
-     * (Optiona) Max expansion size for expanding a date range.
+     * (Optional) Max expansion size for expanding a date range.
      *
      * If the expected expansion is larger than this size, an exception is thrown.
      *
@@ -238,23 +363,40 @@ export interface ExpandDaysForDateRangeConfig {
 export declare const DEFAULT_EXPAND_DAYS_FOR_DATE_RANGE_MAX_EXPANSION_SIZE = 1500;
 export type ExpandDaysForDateRangeFunction = FactoryWithRequiredInput<Date[], DateRange>;
 /**
- * Expands the input range into dates.
+ * 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 param0
+ * @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]
+ * ```
  */
 export declare function expandDaysForDateRangeFunction(config?: ExpandDaysForDateRangeConfig): ExpandDaysForDateRangeFunction;
 /**
- * Expands the input range to the days.
+ * 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
- * @returns
+ * @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[];
 /**
- * Returns the DateRelativeState from the input DateRange.
+ * Determines whether the current moment (or provided `now`) falls before, within, or after the given range.
  *
- * @param param0
- * @returns
+ * @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({ start, end }: DateRange, now?: Date): DateRelativeState;
 export interface GroupDateRangesByDateRelativeStatesResult<T extends DateRange> {
@@ -262,6 +404,19 @@ export interface GroupDateRangesByDateRelativeStatesResult<T extends DateRange>
     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`).
+ *
+ * @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;
@@ -272,92 +427,215 @@ export type DateRangeFunctionDateRangeRef<T extends Partial<DateRange> = Partial
  * 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}.
+ *
+ * @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 an IsDateInDateRangeFunction
+ * 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
- * @returns
+ * @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
+ * ```
  */
 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}.
+ *
+ * @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 an IsDateRangeInDateRangeFunction
+ * 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
- * @returns
+ * @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
+ * ```
  */
 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}.
+ *
+ * @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 an DateRangeOverlapsDateRangeFunction
+ * 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
- * @returns
+ * @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
+ * ```
  */
 export declare function dateRangeOverlapsDateRangeFunction<T extends DateRange = DateRange>(dateRange: T): DateRangeOverlapsDateRangeFunction<T>;
 /**
- * Reduces the UTC date range to represent a 24 hour period.
+ * 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.
  *
- * For example, a range of 10AM one day to 1PM three days later will be simplified to 10AM to 1PM.
+ * 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.
  *
- * The order of times is retained. Date ranges that are 1PM to 10AM three days later will be simplified to 1PM to 10AM.
+ * Operates in UTC, so daylight savings transitions are not considered.
  *
- * For the UTC timezone, meaning changes in daylight savings are not considered.
+ * @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.
+ *
+ * @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
+ * ```
+ */
 export declare function clampDateFunction(dateRange: Partial<DateRange>): ClampDateFunction;
 /**
- * Clamps the date to the date range. Convenience function for clampDateFunction().
+ * Clamps a single date to fall within the given range boundaries.
+ * Convenience wrapper around {@link clampDateFunction}.
  *
- * @param date
- * @param dateRange
- * @returns
+ * @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.
+ *
+ * @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 }
+ * ```
+ */
 export declare function clampDateRangeFunction(dateRange: DateRange, defaultClampNullValues?: boolean): ClampDateRangeFunction;
 export declare function clampDateRangeFunction(dateRange: Partial<DateRange>, defaultClampNullValues?: boolean): ClampPartialDateRangeFunction;
 /**
- * Clamps the input range to the second date range. Convenience function for clampDateRangeFunction().
+ * Clamps a date range to fit within a boundary range.
+ * Convenience wrapper around {@link clampDateRangeFunction}.
  *
- * @param inputDateRange
- * @param limitToDateRange
- * @returns
+ * @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}.
+ *
+ * @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 }
+ * ```
+ */
 export declare function transformDateRangeDatesFunction(transform: MapFunction<Date, Date>): TransformDateRangeDatesFunction;
 /**
- * TransformDateRangeDatesFunction that transforms the input dates to the start of the day.
+ * Pre-built {@link TransformDateRangeDatesFunction} that rounds both start and end to the beginning of their respective days.
  */
 export declare const transformDateRangeWithStartOfDay: TransformDateRangeDatesFunction;
 /**
- * DateRange that has values comprised of either a Date, ISO8601DateString, or ISO8601DayString
+ * 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 in the date range in the order they appear.
+ * 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
+ * @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[];