@dereekb/date 13.4.0 → 13.4.1

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

@@ -30,24 +30,28 @@ export interface YearMonthDayCodePair {
  * Extracts the year component from a {@link YearMonthDayCode} by dividing out the month and day digits.
  *
  * @param yearMonthDayCode - Encoded YYYYMMDD value to extract the year from
+ * @returns the year component of the code
  */
 export declare function yearMonthDayCodeYear(yearMonthDayCode: YearMonthDayCode): YearNumber;
 /**
  * Extracts the month component (1-12) from a {@link YearMonthDayCode} by isolating the middle two digits.
  *
  * @param yearMonthDayCode - Encoded YYYYMMDD value to extract the month from
+ * @returns the month component (1-12) of the code
  */
 export declare function yearMonthDayCodeMonth(yearMonthDayCode: YearMonthDayCode): MonthOfYear;
 /**
  * Extracts the day-of-month component (1-31) from a {@link YearMonthDayCode} by isolating the last two digits.
  *
  * @param yearMonthDayCode - Encoded YYYYMMDD value to extract the day from
+ * @returns the day-of-month component (1-31) of the code
  */
 export declare function yearMonthDayCodeDay(yearMonthDayCode: YearMonthDayCode): DayOfMonth;
 /**
  * Decomposes a {@link YearMonthDayCode} into its individual year, month, and day components.
  *
  * @param yearMonthDayCode - Encoded YYYYMMDD value to decompose
+ * @returns a pair containing the individual year, month, and day components
  */
 export declare function yearMonthDayCodePair(yearMonthDayCode: YearMonthDayCode): YearMonthDayCodePair;
 /**
@@ -56,6 +60,7 @@ export declare function yearMonthDayCodePair(yearMonthDayCode: YearMonthDayCode)
  * that need timezone-aware conversion should use {@link yearMonthDayCodeFactory} instead.
  *
  * @param date - Date to extract components from using local timezone
+ * @returns a pair containing the year, month, and day from the date
  */
 export declare function yearMonthDayCodePairFromDate(date: Date): YearMonthDayCodePair;
 /**
@@ -63,6 +68,7 @@ export declare function yearMonthDayCodePairFromDate(date: Date): YearMonthDayCo
  * using the formula `year * 10000 + month * 100 + day`.
  *
  * @param pair - Decomposed date components to encode
+ * @returns the encoded YYYYMMDD integer
  */
 export declare function yearMonthDayCodeFromPair(pair: YearMonthDayCodePair): YearMonthDayCode;
 /**
@@ -70,6 +76,7 @@ export declare function yearMonthDayCodeFromPair(pair: YearMonthDayCodePair): Ye
  * using the system's local timezone. For timezone-aware conversion, use {@link yearMonthDayCodeFactory}.
  *
  * @param date - Date to encode using local timezone
+ * @returns the encoded YYYYMMDD integer for the given date
  */
 export declare function yearMonthDayCodeFromDate(date: Date): YearMonthDayCode;
 /**
@@ -101,6 +108,7 @@ export interface YearMonthDayCodeConfig {
  * falling back to the system timezone when no input is provided.
  *
  * @param input - Timezone configuration or existing instance to resolve
+ * @returns a DateTimezoneUtcNormalInstance, falling back to the system timezone
  */
 export declare function yearMonthDayCodeDateTimezoneInstance(input: YearMonthDayCodeDateTimezoneInput): DateTimezoneUtcNormalInstance;
 /**
@@ -116,6 +124,12 @@ export declare function yearMonthDayCodeDateTimezoneInstance(input: YearMonthDay
  * // From explicit components (year, month 1-12, day)
  * const code2 = yearMonthDayCode(2022, 1, 15); // 20220115
  * ```
+ *
+ * @param date - a Date to encode (first overload)
+ * @param dateOrYear - a Date to encode, or a year number when used with month and day
+ * @param month - the month (1-12), required when dateOrYear is a number
+ * @param day - the day of month (1-31), required when dateOrYear is a number
+ * @returns the encoded YYYYMMDD integer
  */
 export declare function yearMonthDayCode(date: Date): YearMonthDayCode;
 export declare function yearMonthDayCode(year: number, month: MonthOfYear, day: DayOfMonth): YearMonthDayCode;
@@ -135,6 +149,7 @@ export declare function yearMonthDayCode(year: number, month: MonthOfYear, day:
  * ```
  *
  * @param config - Optional timezone configuration; defaults to system timezone
+ * @returns a reusable factory function that converts dates to YearMonthDayCode values
  */
 export declare function yearMonthDayCodeFactory(config?: YearMonthDayCodeConfig): YearMonthDayCodeFactory;
 /**
@@ -158,6 +173,7 @@ export type YearMonthDayCodesForDateRangeFactory = (dateOrDateRange: DateOrDateR
  * ```
  *
  * @param dateOrDateRange - A single Date (expanded to its calendar month) or an explicit date range
+ * @returns an array of YearMonthDayCode values, one per day in the range
  */
 export declare function yearMonthDayCodesForDateRange(dateOrDateRange: DateOrDateRange): YearMonthDayCode[];
 /**
@@ -166,6 +182,7 @@ export declare function yearMonthDayCodesForDateRange(dateOrDateRange: DateOrDat
  * Shares timezone normalization with the provided factory for consistent day boundaries.
  *
  * @param factory - YearMonthDayCodeFactory to use for encoding; defaults to system timezone
+ * @returns a factory that produces arrays of YearMonthDayCode values for date ranges
  */
 export declare function yearMonthDayCodesForDateRangeFactory(factory?: YearMonthDayCodeFactory): YearMonthDayCodesForDateRangeFactory;
 /**
@@ -191,6 +208,7 @@ export type YearMonthDayCodeDateConfig = Pick<YearMonthDayCodeConfig, 'timezone'
  * ```
  *
  * @param config - Optional timezone configuration; defaults to system timezone
+ * @returns a factory that decodes YearMonthDayCode values back into Dates
  */
 export declare function yearMonthDayCodeDateFactory(config?: YearMonthDayCodeDateConfig): YearMonthDayCodeDateFactory;
 /**
@@ -246,5 +264,6 @@ export interface YearMonthDayCodeGroupFactoryConfig<B> {
  * ```
  *
  * @param config - Grouping configuration including the date reader and optional timezone
+ * @returns a factory that partitions items into day-based groups
  */
 export declare function yearMonthDayCodeGroupFactory<B>(config: YearMonthDayCodeGroupFactoryConfig<B>): YearMonthDayCodeGroupFactory<B>;

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

@@ -45,6 +45,7 @@ export type FormatDateRangeFunctionConfigInput = FormatDateFunction | FormatDate
  * Useful when the same range formatting logic needs to be applied repeatedly with consistent settings.
  *
  * @param inputConfig - format function or full configuration
+ * @returns a reusable function that formats date ranges into strings
  *
  * @example
  * ```ts
@@ -67,6 +68,7 @@ export declare function formatDateRangeFunction(inputConfig: FormatDateRangeFunc
  * @param range - date range to format
  * @param inputConfig - format function or full configuration
  * @param separator - optional separator override when inputConfig is a function
+ * @returns the formatted date range string
  *
  * @example
  * ```ts
@@ -113,6 +115,7 @@ export type FormatDateRangeDistanceFunctionConfig = {
  * (e.g., "3 hours", "about 2 days"). Delegates to date-fns `formatDistance` or `formatDistanceStrict`.
  *
  * @param inputConfig - controls distance formatting, optional transforms, and same-day handling
+ * @returns a reusable function that computes and formats date range distances
  *
  * @example
  * ```ts
@@ -137,6 +140,7 @@ export declare const formatDateDistance: FormatDateRangeFunction;
  *
  * @param range - date range to compute distance for
  * @param inputConfig - optional distance formatting configuration
+ * @returns the human-readable distance string
  *
  * @example
  * ```ts
@@ -169,6 +173,11 @@ export declare function formatDateRangeDistance(range: DateRange, inputConfig?:
  * formatToTimeRangeString({ start: new Date('2024-01-15T09:00:00'), end: new Date('2024-01-16T17:00:00') });
  * // "01/15/2024 9:00 AM - 01/16/2024 5:00 PM"
  * ```
+ *
+ * @param startOrDateRange - date range object or start date
+ * @param end - optional end date when a start date is provided
+ * @param onlyTimeRange - whether to force time-only formatting regardless of date span
+ * @returns the formatted time or date+time range string
  */
 export declare function formatToTimeRangeString(startOrDateRange: DateRange): string;
 export declare function formatToTimeRangeString(start: Date, end?: Maybe<Date>): string;
@@ -186,6 +195,10 @@ export declare function formatToTimeRangeString(startOrDateRange: DateRange | Da
  * formatToDayTimeRangeString({ start: new Date('2024-01-15T09:00:00'), end: new Date('2024-01-16T17:00:00') });
  * // "01/15/2024 9:00 AM - 01/16/2024 5:00 PM"
  * ```
+ *
+ * @param startOrDateRange - date range object or start date
+ * @param end - optional end date when a start date is provided
+ * @returns the formatted date+time range string
  */
 export declare function formatToDayTimeRangeString(startOrDateRange: DateRange): string;
 export declare function formatToDayTimeRangeString(start: Date, end?: Maybe<Date>): string;
@@ -205,6 +218,12 @@ export declare function formatToDayTimeRangeString(start: Date, end?: Maybe<Date
  * formatToDayRangeString({ start: new Date('2024-01-15'), end: new Date('2024-01-15') });
  * // "01/15/2024"
  * ```
+ *
+ * @param startOrDateRange - date range object or start date
+ * @param format - optional custom format function (when called with a DateRange)
+ * @param endOrFormat - optional end date or custom format function
+ * @param inputFormat - optional custom format function when end date is provided separately
+ * @returns the formatted day range string
  */
 export declare function formatToDayRangeString(startOrDateRange: DateRange, format?: FormatDateFunction): string;
 export declare function formatToDayRangeString(start: Date, end?: Maybe<Date>, format?: FormatDateFunction): string;
@@ -213,6 +232,7 @@ export declare function formatToDayRangeString(start: Date, end?: Maybe<Date>, f
  * instead of throwing.
  *
  * @param input - date, date string, or nullish value
+ * @returns the ISO 8601 date string, or `undefined` if the input is invalid or nullish
  *
  * @example
  * ```ts
@@ -233,6 +253,7 @@ export declare function safeFormatToISO8601DateString(input: Maybe<DateOrDateStr
  * Formats a Date to a full ISO 8601 date-time string via `Date.toISOString()`. Defaults to the current date/time.
  *
  * @param date - date to format; defaults to `new Date()`
+ * @returns the full ISO 8601 date-time string
  *
  * @example
  * ```ts
@@ -250,6 +271,7 @@ export declare function formatToISO8601DateString(date?: Date): ISO8601DayString
  * Use {@link toISO8601DayStringForUTC} when the UTC date is needed instead.
  *
  * @param dateOrString - date or existing day string
+ * @returns the ISO 8601 day string in system timezone
  *
  * @example
  * ```ts
@@ -268,6 +290,7 @@ export declare function toISO8601DayStringForSystem(dateOrString: DateOrDayStrin
  * Defaults to the current date.
  *
  * @param date - date to format; defaults to `new Date()`
+ * @returns the ISO 8601 day string in system timezone
  *
  * @example
  * ```ts
@@ -285,6 +308,7 @@ export declare function formatToISO8601DayStringForSystem(date?: Date): ISO8601D
  * Use {@link toISO8601DayStringForSystem} when the system-local date is needed instead.
  *
  * @param dateOrString - date or existing day string
+ * @returns the ISO 8601 day string in UTC
  *
  * @example
  * ```ts
@@ -304,6 +328,7 @@ export declare function toISO8601DayStringForUTC(dateOrString: DateOrDayString):
  * Defaults to the current date.
  *
  * @param date - date to format; defaults to `new Date()`
+ * @returns the ISO 8601 day string using UTC date components
  *
  * @example
  * ```ts
@@ -314,14 +339,19 @@ export declare function toISO8601DayStringForUTC(dateOrString: DateOrDayString):
  * ```
  */
 export declare function formatToISO8601DayStringForUTC(date?: Date): ISO8601DayString;
-/** date-fns format string for `MM/dd/yyyy` (e.g., `"01/15/2024"`). */
+/**
+ * date-fns format string for `MM/dd/yyyy` (e.g., `"01/15/2024"`).
+ */
 export declare const MONTH_DAY_SLASH_DATE_STRING_FORMAT = "MM/dd/yyyy";
-/** @deprecated use MONTH_DAY_SLASH_DATE_STRING_FORMAT instead. */
+/**
+ * @deprecated Use MONTH_DAY_SLASH_DATE_STRING_FORMAT instead.
+ */
 export declare const monthDaySlashDateStringFormat = "MM/dd/yyyy";
 /**
  * Formats a Date as a month/day/year slash-separated string (`MM/dd/yyyy`). Defaults to the current date.
  *
  * @param date - date to format; defaults to `new Date()`
+ * @returns the formatted `MM/dd/yyyy` string
  *
  * @example
  * ```ts
@@ -336,14 +366,19 @@ export declare function formatToMonthDaySlashDate(date?: Date): MonthDaySlashDat
  * @deprecated use formatToMonthDaySlashDate instead.
  */
 export declare const formatToShortDateString: typeof formatToMonthDaySlashDate;
-/** date-fns format string for `MM/dd` (e.g., `"01/15"`). */
+/**
+ * date-fns format string for `MM/dd` (e.g., `"01/15"`).
+ */
 export declare const DATE_MONTH_DAY_STRING_FORMAT = "MM/dd";
-/** @deprecated use DATE_MONTH_DAY_STRING_FORMAT instead. */
+/**
+ * @deprecated Use DATE_MONTH_DAY_STRING_FORMAT instead.
+ */
 export declare const dateMonthDayStringFormat = "MM/dd";
 /**
  * Formats a Date as a month/day string (`MM/dd`) without the year. Defaults to the current date.
  *
  * @param date - date to format; defaults to `new Date()`
+ * @returns the formatted `MM/dd` string
  *
  * @example
  * ```ts
@@ -358,6 +393,7 @@ export declare function formatToMonthDayString(date?: Date): ISO8601DayString;
  * Formats a Date as a human-friendly weekday and month/day string (e.g., `"Mon, Jan 15th"`).
  *
  * @param date - date to format
+ * @returns the formatted weekday and month/day string
  *
  * @example
  * ```ts
@@ -368,14 +404,19 @@ export declare function formatToMonthDayString(date?: Date): ISO8601DayString;
  * ```
  */
 export declare function formatToDateString(date: Date): string;
-/** date-fns format string for 12-hour time with AM/PM (e.g., `"9:00 AM"`). */
+/**
+ * date-fns format string for 12-hour time with AM/PM (e.g., `"9:00 AM"`).
+ */
 export declare const DATE_TIME_STRING_FORMAT = "h:mm a";
-/** @deprecated use DATE_TIME_STRING_FORMAT instead. */
+/**
+ * @deprecated Use DATE_TIME_STRING_FORMAT instead.
+ */
 export declare const dateTimeStringFormat = "h:mm a";
 /**
  * Formats a Date as a 12-hour time string with AM/PM (e.g., `"9:00 AM"`).
  *
  * @param date - date to format
+ * @returns the formatted 12-hour time string with AM/PM
  *
  * @example
  * ```ts
@@ -386,14 +427,19 @@ export declare const dateTimeStringFormat = "h:mm a";
  * ```
  */
 export declare function formatToTimeString(date: Date): string;
-/** Combined date-fns format string for `MM/dd/yyyy h:mm a` (e.g., `"01/15/2024 9:00 AM"`). */
+/**
+ * Combined date-fns format string for `MM/dd/yyyy h:mm a` (e.g., `"01/15/2024 9:00 AM"`).
+ */
 export declare const DATE_SHORT_DATE_AND_TIME_STRING_FORMAT = "MM/dd/yyyy h:mm a";
-/** @deprecated use DATE_SHORT_DATE_AND_TIME_STRING_FORMAT instead. */
+/**
+ * @deprecated Use DATE_SHORT_DATE_AND_TIME_STRING_FORMAT instead.
+ */
 export declare const dateShortDateAndTimeStringFormat = "MM/dd/yyyy h:mm a";
 /**
  * Formats a Date as a short date and time string (e.g., `"01/15/2024 9:00 AM"`).
  *
  * @param date - date to format
+ * @returns the formatted short date and time string
  *
  * @example
  * ```ts
@@ -410,6 +456,7 @@ export declare function formatToShortDateAndTimeString(date: Date): string;
  *
  * @param start - start date/time
  * @param end - end date/time
+ * @returns the formatted time string with an appended duration indicator
  *
  * @example
  * ```ts
@@ -444,6 +491,11 @@ export declare function formatToTimeAndDurationString(start: Date, end: Date): s
  * formatStartedEndedDistanceString(activeRange);
  * // "started about 1 hour ago"
  * ```
+ *
+ * @param dateRange - date range with start and end dates
+ * @param dateRange.start - the start date of the range
+ * @param dateRange.end - the end date of the range
+ * @returns the relative-time label describing the date range state
  */
 export declare function formatStartedEndedDistanceString({ start, end }: DateRange): string;
 /**
@@ -451,6 +503,7 @@ export declare function formatStartedEndedDistanceString({ start, end }: DateRan
  * Useful for converting heterogeneous date inputs into a consistent midnight-aligned Date.
  *
  * @param input - date or day string to normalize
+ * @returns a Date set to midnight of the corresponding day in the system timezone
  *
  * @example
  * ```ts
@@ -469,6 +522,7 @@ export declare function toJsDayDate(input: DateOrDayString): Date;
  * in the system timezone. Supports year formats with more than 4 digits but does not support negative years.
  *
  * @param dayString - ISO 8601 day or date string to parse
+ * @returns a Date at the start of the parsed day in the system timezone
  *
  * @example
  * ```ts

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

@@ -8,6 +8,9 @@ export interface DateRangeStart {
 /**
  * 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
@@ -41,6 +44,9 @@ export interface DateRange extends DateRangeStart {
  * 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 - the date range to measure
+ * @returns the number of days in the range, inclusive
+ *
  * @example
  * ```ts
  * const range = { start: new Date('2024-01-01'), end: new Date('2024-01-03') };
@@ -51,6 +57,9 @@ 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
+ *
  * @example
  * ```ts
  * isDateRange({ start: new Date(), end: new Date() }); // true
@@ -63,6 +72,10 @@ 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
+ *
  * @example
  * ```ts
  * const a = { start: new Date('2024-01-01'), end: new Date('2024-01-31') };
@@ -76,6 +89,10 @@ export declare function isSameDateRange(a: Maybe<Partial<DateRange>>, b: Maybe<P
  * 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') };
@@ -87,6 +104,9 @@ export declare function isSameDateDayRange(a: Maybe<Partial<DateRange>>, b: Mayb
 /**
  * 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
@@ -97,6 +117,9 @@ 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
@@ -107,6 +130,9 @@ export declare function isPartialDateRange(input: Partial<DateRange>): input is
 /**
  * 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
@@ -122,6 +148,10 @@ 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 - a Date or existing DateRange
+ * @param end - optional end date when the first argument is a plain Date
+ * @returns a DateRange
+ *
  * @example
  * ```ts
  * const range = dateOrDateRangeToDateRange(new Date('2024-01-01'), new Date('2024-01-31'));
@@ -231,6 +261,9 @@ export type DateRangeInput = (DateRangeTypedInput | DateRangeDistanceInput) & {
  * 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 a computed DateRange
  * @throws Error if the type is not a recognized {@link DateRangeType}
  *
  * @example
@@ -250,6 +283,9 @@ export declare function dateRange(input: DateRangeType | DateRangeInput, inputRo
  * 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 - the date whose full day range to return
+ * @returns a DateRange from start of day to end of day
+ *
  * @example
  * ```ts
  * const range = dateRangeFromStartAndEndOfDay(new Date('2024-06-15T14:30:00'));
@@ -308,6 +344,8 @@ 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 a step function for advancing between dates
+ * @returns a reusable iteration function
  * @throws Error if max iterations is exceeded and throwErrorOnMaxIterations is true
  *
  * @example
@@ -321,6 +359,11 @@ export declare function iterateDaysInDateRangeFunction(input: IterateDaysInDateR
 /**
  * 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[];
@@ -351,6 +394,8 @@ export type ExpandDaysForDateRangeFunction = FactoryWithRequiredInput<Date[], Da
  * 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 a function that expands a DateRange into an array of Dates
  * @throws Error if the range spans more days than the configured maxExpansionSize
  *
  * @example
@@ -365,6 +410,9 @@ export declare function expandDaysForDateRangeFunction(config?: ExpandDaysForDat
  * 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 - the date range to expand
+ * @returns an array of Dates, one per day in the range
+ *
  * @example
  * ```ts
  * const days = expandDaysForDateRange({ start: new Date('2024-01-01'), end: new Date('2024-01-03') });
@@ -375,6 +423,12 @@ 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 - the date range to compare against
+ * @param dateRange.start - the start of the range
+ * @param dateRange.end - the end of the range
+ * @param now - the reference date, defaults to the current moment
+ * @returns 'past', 'present', or 'future'
+ *
  * @example
  * ```ts
  * const range = { start: new Date('2024-01-01'), end: new Date('2024-12-31') };
@@ -392,6 +446,10 @@ export interface GroupDateRangesByDateRelativeStatesResult<T extends DateRange>
 /**
  * Groups an array of date ranges into past, present, and future buckets based on the current moment (or provided `now`).
  *
+ * @param dateRanges - the date ranges to group
+ * @param _now - the reference date, defaults to the current moment
+ * @returns an object with past, present, and future arrays
+ *
  * @example
  * ```ts
  * const ranges = [
@@ -402,7 +460,7 @@ export interface GroupDateRangesByDateRelativeStatesResult<T extends DateRange>
  * // grouped.past = [first range], grouped.present = [second range], grouped.future = []
  * ```
  */
-export declare function groupDateRangesByDateRelativeState<T extends DateRange>(dateRanges: T[], now?: Date): GroupDateRangesByDateRelativeStatesResult<T>;
+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;
 };
@@ -416,6 +474,10 @@ export type IsDateInDateRangeFunction<T extends Partial<DateRange> = DateRange>
  * Checks whether a date falls within a (possibly partial) date range.
  * Convenience wrapper around {@link isDateInDateRangeFunction}.
  *
+ * @param date - the date to test
+ * @param dateRange - the range to test against
+ * @returns true if the date falls within the range
+ *
  * @example
  * ```ts
  * const range = { start: new Date('2024-01-01'), end: new Date('2024-12-31') };
@@ -429,6 +491,9 @@ export declare function isDateInDateRange(date: Date, dateRange: Partial<DateRan
  * 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 - the boundary range to test against
+ * @returns a function that tests whether a date falls within the range
+ *
  * @example
  * ```ts
  * const isInQ1 = isDateInDateRangeFunction({
@@ -448,6 +513,10 @@ export type IsDateRangeInDateRangeFunction<T extends Partial<DateRange> = Partia
  * 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') };
@@ -460,6 +529,9 @@ export declare function isDateRangeInDateRange(compareDateRange: DateRange, date
  * 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 - the boundary range
+ * @returns a function that tests containment of other ranges
+ *
  * @example
  * ```ts
  * const isInYear = isDateRangeInDateRangeFunction({
@@ -479,6 +551,10 @@ export type DateRangeOverlapsDateRangeFunction<T extends DateRange = DateRange>
  * 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') };
@@ -491,6 +567,9 @@ export declare function dateRangeOverlapsDateRange(compareDateRange: DateRange,
  * 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 - the boundary range to test overlap against
+ * @returns a function that tests overlap of other ranges
+ *
  * @example
  * ```ts
  * const overlapsQ1 = dateRangeOverlapsDateRangeFunction({
@@ -512,6 +591,9 @@ export declare function dateRangeOverlapsDateRangeFunction<T extends DateRange =
  *
  * Operates in UTC, so daylight savings transitions are not considered.
  *
+ * @param dateRange - the date range to fit into a single day period
+ * @returns a new date range with the same start and an end within 24 hours of start
+ *
  * @example
  * ```ts
  * // 10AM to 1PM across 3 days becomes same-day 10AM to 1PM
@@ -530,6 +612,9 @@ export type ClampDateFunction = ((date: Date) => Date) & DateRangeFunctionDateRa
  * 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 - the boundary range for clamping
+ * @returns a function that clamps dates to the range
+ *
  * @example
  * ```ts
  * const clamp = clampDateFunction({
@@ -546,6 +631,10 @@ export declare function clampDateFunction(dateRange: Partial<DateRange>): ClampD
  * Clamps a single date to fall within the given range boundaries.
  * Convenience wrapper around {@link clampDateFunction}.
  *
+ * @param date - the date to clamp
+ * @param dateRange - the boundary range
+ * @returns the clamped date
+ *
  * @example
  * ```ts
  * const range = { start: new Date('2024-01-01'), end: new Date('2024-12-31') };
@@ -559,6 +648,10 @@ export type ClampDateRangeFunction = ((date: Partial<DateRange>, clampNullValues
  * 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({
@@ -575,6 +668,10 @@ export declare function clampDateRangeFunction(dateRange: Partial<DateRange>, de
  * Clamps a date range to fit within a boundary range.
  * Convenience wrapper around {@link clampDateRangeFunction}.
  *
+ * @param inputDateRange - the date range to clamp
+ * @param limitToDateRange - the boundary range
+ * @returns the clamped date range
+ *
  * @example
  * ```ts
  * const input = { start: new Date('2023-06-01'), end: new Date('2024-06-30') };
@@ -591,6 +688,9 @@ export type TransformDateRangeDatesFunction = (dateRange: DateRange) => DateRang
 /**
  * Creates a function that applies a date transformation to both start and end of a {@link DateRange}.
  *
+ * @param transform - the transformation to apply to both dates
+ * @returns a function that transforms both dates of a DateRange
+ *
  * @example
  * ```ts
  * import { startOfHour } from 'date-fns';
@@ -616,6 +716,9 @@ export interface DateRangeWithDateOrStringValue {
  * 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 - the date range to inspect
+ * @returns an array of unique day-of-week values present in the range
+ *
  * @example
  * ```ts
  * // Wednesday through Friday

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

@@ -32,5 +32,6 @@ export declare function fitDateRangeToDayPeriodFunction(timezone: DateTimezoneUt
  *
  * @param dateRange - the range to fit
  * @param timezone - the timezone for day boundary calculation
+ * @returns the date range fitted to a single day period
  */
 export declare function fitDateRangeToDayPeriod<T extends DateRange = DateRange>(dateRange: T, timezone: DateTimezoneUtcNormalFunctionInput): T;