@dereekb/date 13.3.1 → 13.4.1

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[];
@@ -343,7 +386,7 @@ export interface ExpandDaysForDateRangeConfig {
      *
      * Defaults to 1500 days.
      */
-    maxExpansionSize?: number | 0 | false;
+    readonly maxExpansionSize?: number | 0 | false;
 }
 export declare const DEFAULT_EXPAND_DAYS_FOR_DATE_RANGE_MAX_EXPANSION_SIZE = 1500;
 export type ExpandDaysForDateRangeFunction = FactoryWithRequiredInput<Date[], DateRange>;
@@ -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;

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

@@ -63,6 +63,7 @@ export interface ValidDateFromTimestringResult extends Required<DateFromTimestri
  * guaranteeing that `raw` and `result` are defined.
  *
  * @param result - The parse result to check.
+ * @returns `true` if the result is valid, narrowing the type to {@link ValidDateFromTimestringResult}.
  *
  * @example
  * ```ts
@@ -99,6 +100,7 @@ export declare class DateTimeUtilityInstance {
      *
      * @param date - The date to check. Defaults to now.
      * @param timezone - Overrides the instance's configured timezone for this call.
+     * @returns {@link TimeAM.AM} or {@link TimeAM.PM} depending on the time of day.
      *
      * @example
      * ```ts
@@ -112,6 +114,7 @@ export declare class DateTimeUtilityInstance {
      *
      * @param date - The date to format.
      * @param timezone - Overrides the instance's configured timezone for this call.
+     * @returns The formatted time string (e.g., "1:30PM").
      *
      * @example
      * ```ts
@@ -163,6 +166,8 @@ export declare class DateTimeUtilityInstance {
 /**
  * Creates a {@link DateTimeUtilityInstance} configured for UTC.
  *
+ * @returns A new {@link DateTimeUtilityInstance} using the UTC timezone.
+ *
  * @example
  * ```ts
  * const utcInstance = dateTimeInstanceUtc();
@@ -175,6 +180,7 @@ export declare function dateTimeInstanceUtc(): DateTimeUtilityInstance;
  * Defaults to UTC when no timezone is provided.
  *
  * @param timezone - The IANA timezone identifier (e.g., 'America/New_York').
+ * @returns A new {@link DateTimeUtilityInstance} for the specified timezone.
  *
  * @example
  * ```ts
@@ -188,6 +194,7 @@ export declare function dateTimeInstance(timezone?: Maybe<TimezoneString>): Date
  *
  * @param date - The date to check. Defaults to now.
  * @param timezone - The IANA timezone to evaluate in. Defaults to UTC.
+ * @returns {@link TimeAM.AM} or {@link TimeAM.PM} depending on the time of day.
  *
  * @example
  * ```ts
@@ -203,6 +210,7 @@ export declare function getTimeAM(date?: Date, timezone?: Maybe<TimezoneString>)
  * unlike {@link toReadableTimeString} which defaults to UTC.
  *
  * @param date - The date to format.
+ * @returns The formatted time string in the system's local timezone.
  *
  * @example
  * ```ts
@@ -215,6 +223,7 @@ export declare function toLocalReadableTimeString(date: Date): ReadableTimeStrin
  *
  * @param date - The date to format.
  * @param timezone - The IANA timezone to format in. Defaults to UTC.
+ * @returns The formatted time string (e.g., "10:30AM").
  *
  * @example
  * ```ts
@@ -229,6 +238,7 @@ export declare function toReadableTimeString(date: Date, timezone?: Maybe<Timezo
  *
  * @param input - A time string such as "1:30PM", "13:30", or "1PM".
  * @param config - Optional configuration specifying the timezone and reference date.
+ * @returns The parsed time string result, or `undefined` if parsing failed.
  *
  * @example
  * ```ts
@@ -246,6 +256,7 @@ export declare function parseReadableTimeString(input: ReadableTimeString, confi
  *
  * @param input - A time string such as "1:30PM" or "13:30".
  * @param config - Optional configuration specifying the timezone and reference date.
+ * @returns The resolved date, or `undefined` if the input could not be parsed.
  *
  * @example
  * ```ts
@@ -257,6 +268,7 @@ export declare function readableTimeStringToDate(input: ReadableTimeString, conf
  * Creates a {@link LimitDateTimeInstance} for clamping and constraining dates to a configured range.
  *
  * @param config - The limit configuration specifying min/max bounds, future requirements, etc.
+ * @returns A new {@link LimitDateTimeInstance} configured with the given bounds.
  *
  * @example
  * ```ts

package/src/lib/date/date.time.limit.d.ts

@@ -78,6 +78,8 @@ export declare class LimitDateTimeInstance {
      * const limiter = new LimitDateTimeInstance({ limits: { isFuture: true } });
      * const range = limiter.dateRange(); // { start: <now>, end: undefined }
      * ```
+     *
+     * @returns A partial {@link DateRange} with `start` and/or `end` derived from the limits.
      */
     dateRange(): Partial<DateRange>;
     /**
@@ -85,6 +87,7 @@ export declare class LimitDateTimeInstance {
      * like "now" or relative future offsets to resolve against the given moment.
      *
      * @param instant - The reference point in time for resolving dynamic limits.
+     * @returns A partial {@link DateRange} resolved against the given instant.
      */
     dateRangeForInstant(instant: Date): {
         start: Date | undefined;
@@ -103,6 +106,8 @@ export declare class LimitDateTimeInstance {
      * });
      * const safe = limiter.clamp(new Date()); // at least 30 minutes from now
      * ```
+     *
+     * @returns The clamped date within the allowed range.
      */
     clamp(date: Date): Date;
     /**
@@ -117,6 +122,8 @@ export declare class LimitDateTimeInstance {
      * const clamped = limiter.clampDateRange({ start: pastDate, end: futureDate });
      * // clamped.start will be at least now
      * ```
+     *
+     * @returns The date range clamped to the allowed limits.
      */
     clampDateRange(dateRange: DateRange): DateRange;
 }
@@ -133,5 +140,7 @@ export declare class LimitDateTimeInstance {
  * });
  * const clamped = limiter.clamp(someDate);
  * ```
+ *
+ * @returns A new {@link LimitDateTimeInstance}.
  */
 export declare function limitDateTimeInstance(config: LimitDateTimeConfig): LimitDateTimeInstance;

package/src/lib/date/date.time.minute.d.ts

@@ -121,6 +121,8 @@ export declare class DateTimeMinuteInstance {
     set step(step: Minutes);
     /**
      * Returns the LimitDateTimeInstance. This does not take the schedule into consideration.
+     *
+     * @returns The underlying {@link LimitDateTimeInstance}.
      */
     get limitInstance(): LimitDateTimeInstance;
     /**
@@ -140,6 +142,8 @@ export declare class DateTimeMinuteInstance {
      * // true if June 15 is a weekday and overlaps the limit range
      * instance.dateDayContainsValidDateValue(new Date('2024-06-15'));
      * ```
+     *
+     * @returns `true` if the day contains at least one valid date/time value.
      */
     dateDayContainsValidDateValue(date: Date): boolean;
     /**
@@ -157,6 +161,8 @@ export declare class DateTimeMinuteInstance {
      *
      * instance.isInValidRange(new Date('2024-06-15T10:00:00')); // true if a weekday
      * ```
+     *
+     * @returns `true` if the date is within the min/max limits and on a scheduled day.
      */
     isInValidRange(date?: Date): boolean;
     /**
@@ -174,6 +180,8 @@ export declare class DateTimeMinuteInstance {
      *
      * instance.isValid(new Date('2099-03-15T10:00:00')); // true if all constraints pass
      * ```
+     *
+     * @returns `true` if the date passes all configured constraints.
      */
     isValid(date?: Date): boolean;
     /**
@@ -192,6 +200,8 @@ export declare class DateTimeMinuteInstance {
      * // status.isAfterMinimum === false (before min)
      * // status.inFuture === false (if date is in the past)
      * ```
+     *
+     * @returns A {@link DateTimeMinuteDateStatus} snapshot for the given date.
      */
     getStatus(date?: Date): DateTimeMinuteDateStatus;
     /**
@@ -208,6 +218,8 @@ export declare class DateTimeMinuteInstance {
      *
      * instance.dateIsInSchedule(new Date('2024-06-15')); // true (Saturday = false)
      * ```
+     *
+     * @returns `true` if the date is on a scheduled day or no schedule is configured.
      */
     dateIsInSchedule(date?: Date): boolean;
     /**
@@ -227,6 +239,8 @@ export declare class DateTimeMinuteInstance {
      * instance.round({ roundToSteps: true }); // 2024-06-15T09:00:00
      * instance.round({ roundToSteps: true, roundToBound: true }); // clamped to min if below
      * ```
+     *
+     * @returns The rounded (and optionally clamped) date.
      */
     round(round: RoundDateTimeMinute): Date;
     /**
@@ -245,6 +259,8 @@ export declare class DateTimeMinuteInstance {
      *
      * instance.clamp(new Date('2024-05-25')); // clamped to min, then nearest weekday
      * ```
+     *
+     * @returns The date clamped to both the limits and the schedule.
      */
     clamp(date?: Date, maxClampDistance?: Days): Date;
     /**
@@ -260,6 +276,8 @@ export declare class DateTimeMinuteInstance {
      *
      * instance.clampToLimit(new Date('2025-03-01')); // returns max (2024-12-31)
      * ```
+     *
+     * @returns The date clamped to the configured min/max limits.
      */
     clampToLimit(date?: Date): Date;
     /**
@@ -279,6 +297,8 @@ export declare class DateTimeMinuteInstance {
      * // If June 15, 2024 is a Saturday, returns the next Monday
      * instance.clampToSchedule(new Date('2024-06-15'));
      * ```
+     *
+     * @returns The nearest valid scheduled date, or the input date if already valid or no schedule is configured.
      */
     clampToSchedule(date?: Date, maxClampDistance?: Days): Date;
     /**
@@ -299,6 +319,8 @@ export declare class DateTimeMinuteInstance {
      * // Find the next weekday after a Saturday
      * instance.findNextAvailableDayInSchedule(new Date('2024-06-15'), 'future');
      * ```
+     *
+     * @returns The next valid schedule date, or `undefined` if none found within the max distance.
      */
     findNextAvailableDayInSchedule(date: DateCellScheduleDateFilterInput, direction: DateRelativeDirection, maxDistance?: Days): Maybe<Date>;
     /**
@@ -316,6 +338,8 @@ export declare class DateTimeMinuteInstance {
      * instance.isInSchedule(new Date('2024-06-17')); // true (Monday)
      * instance.isInSchedule(new Date('2024-06-16')); // false (Sunday)
      * ```
+     *
+     * @returns `true` if the date is on a scheduled day or no schedule is configured.
      */
     isInSchedule(date: DateCellScheduleDateFilterInput): boolean;
     protected _takeBoundedDate(date?: Date): Date;
@@ -338,6 +362,8 @@ export declare class DateTimeMinuteInstance {
  *
  * isValid(new Date('2024-06-17T10:00:00')); // true if future weekday after min
  * ```
+ *
+ * @returns A decision function that returns `true` for valid dates.
  */
 export declare function dateTimeMinuteDecisionFunction(config: DateTimeMinuteConfig): DecisionFunction<Date>;
 /**
@@ -366,5 +392,7 @@ export declare function dateTimeMinuteDecisionFunction(config: DateTimeMinuteCon
  * // true only if both 00:00 and 23:59 on June 15 pass all constraints
  * isFullDayValid(new Date('2024-06-15'));
  * ```
+ *
+ * @returns A decision function that returns `true` for valid days.
  */
 export declare function dateTimeMinuteWholeDayDecisionFunction(config: DateTimeMinuteConfig, startAndEndOfDayMustBeValid?: boolean): DecisionFunction<Date>;