@dereekb/date 13.4.0 → 13.4.1

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@dereekb/date",
-  "version": "13.4.0",
+  "version": "13.4.1",
   "peerDependencies": {
-    "@dereekb/model": "13.4.0",
-    "@dereekb/rxjs": "13.4.0",
-    "@dereekb/util": "13.4.0",
+    "@dereekb/model": "13.4.1",
+    "@dereekb/rxjs": "13.4.1",
+    "@dereekb/util": "13.4.1",
     "@vvo/tzdb": "^6.0.0",
     "arktype": "^2.2.0",
     "date-fns": "^4.0.0",
@@ -14,7 +14,7 @@
   },
   "dependencies": {},
   "devDependencies": {
-    "@dereekb/rxjs": "13.4.0"
+    "@dereekb/rxjs": "13.4.1"
   },
   "exports": {
     "./package.json": "./package.json",

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

@@ -228,6 +228,11 @@ export declare function isValidDateCellTimingStartDate(date: Date): boolean;
  * The end date is used just to determine the number of days, but a minimum of 1 day is always enforced as a DateCellTiming must contain atleast 1 day.
  *
  * The start date from the inputDate is considered to to have the offset noted in DateCell, and will be retained.
+ *
+ * @param durationInput - the duration span containing the startsAt time and event duration in minutes
+ * @param rangeInput - specifies the date range: a number of days, a DateRange, or a DateRangeDayDistanceInput
+ * @param timezoneInput - optional timezone configuration; defaults to the system timezone if omitted
+ * @returns a fully computed FullDateCellTiming with start, startsAt, end, duration, and timezone
  */
 export declare function dateCellTiming(durationInput: DateDurationSpan, rangeInput: DateCellTimingRangeInput, timezoneInput?: DateCellTimingTimezoneInput): FullDateCellTiming;
 export interface DateCellTimingStartPair {

package/src/lib/date/date.cell.factory.d.ts

@@ -60,6 +60,9 @@ export type DateCellRangeOfTimingFactory = (input?: Maybe<DateCellRangeOfTimingI
  * When `limitToCompletedIndexes` is true, only indexes whose timing duration has fully elapsed are included,
  * with the max boundary lazily refreshed as time passes.
  *
+ * @param config - Configuration specifying the timing, range fit, and completion constraints.
+ * @returns A factory function that produces a clamped {@link DateCellRangeWithRange} from optional start/end input.
+ *
  * @example
  * ```ts
  * const timing = dateCellTiming({ startsAt, duration: 60 }, 5);
@@ -78,6 +81,10 @@ export declare function dateCellRangeOfTimingFactory(config: DateCallIndexRangeF
  * Computes a {@link DateCellRangeWithRange} from a timing and optional start/end input.
  *
  * Shorthand for creating a {@link dateCellRangeOfTimingFactory} and immediately invoking it.
+ *
+ * @param config - A {@link DateCellTiming} or full factory configuration.
+ * @param input - Optional start/end boundaries for the range.
+ * @returns A clamped {@link DateCellRangeWithRange} derived from the timing and input.
  */
 export declare function dateCellRangeOfTiming(config: DateCellTiming | DateCallIndexRangeFromDatesFactoryConfig, input?: Maybe<DateCellRangeOfTimingInput>): DateCellRangeWithRange;
 /**
@@ -89,12 +96,20 @@ export type DateCellTimingCompleteTimeRangeConfig = Pick<DateCallIndexRangeFromD
  * of the timing schedule. Useful for determining which days have already finished.
  *
  * By default fitToTimingRange is true.
+ *
+ * @param timing - The timing schedule to evaluate.
+ * @param config - Optional configuration for the current time reference and range fitting.
+ * @returns A {@link DateCellRangeWithRange} covering only the completed day indexes.
  */
 export declare function dateCellTimingCompletedTimeRange(timing: DateCellTiming, config?: DateCellTimingCompleteTimeRangeConfig): DateCellRangeWithRange;
 /**
  * Returns the latest completed day index for a {@link DateCellTiming}.
  *
  * Returns -1 if no days have been completed yet.
+ *
+ * @param timing - The timing schedule to evaluate.
+ * @param now - Optional reference time; defaults to the current time.
+ * @returns The zero-based index of the last fully completed day, or -1 if none.
  */
 export declare function dateCellTimingLatestCompletedIndex(timing: DateCellTiming, now?: Date): IndexNumber;
 /**
@@ -106,10 +121,16 @@ export declare function dateCellTimingLatestCompletedIndex(timing: DateCellTimin
 export type DateCellIndexRange = IndexRange;
 /**
  * Converts a {@link DateCellRange} (inclusive `to`) to a {@link DateCellIndexRange} (exclusive `maxIndex`).
+ *
+ * @param range - The inclusive date cell range to convert.
+ * @returns A {@link DateCellIndexRange} with exclusive `maxIndex`.
  */
 export declare function dateCellRangeToDateCellIndexRange(range: DateCellRange): DateCellIndexRange;
 /**
  * Converts a {@link DateCellIndexRange} (exclusive `maxIndex`) back to a {@link DateCellRangeWithRange} (inclusive `to`).
+ *
+ * @param range - The exclusive date cell index range to convert.
+ * @returns A {@link DateCellRangeWithRange} with inclusive `to`.
  */
 export declare function dateCellIndexRangeToDateCellRange(range: DateCellIndexRange): DateCellRangeWithRange;
 /**
@@ -117,6 +138,11 @@ export declare function dateCellIndexRangeToDateCellRange(range: DateCellIndexRa
  *
  * An arbitrary limit can also be applied. When `fitToTimingRange` is true (default),
  * the limit is intersected with the timing's own range; otherwise the limit is used as-is.
+ *
+ * @param timing - The timing schedule to derive the range from.
+ * @param limit - Optional range input to constrain the output.
+ * @param fitToTimingRange - Whether to intersect the limit with the timing's own range. Defaults to true.
+ * @returns A {@link DateCellIndexRange} representing the computed index bounds.
  */
 export declare function dateCellIndexRange(timing: DateCellTiming, limit?: DateCellTimingRangeInput, fitToTimingRange?: boolean): DateCellIndexRange;
 /**
@@ -124,12 +150,19 @@ export declare function dateCellIndexRange(timing: DateCellTiming, limit?: DateC
  * by combining its timing and blocks.
  *
  * Shorthand for calling {@link expandDateCellTiming} with `collection.timing` and `collection.blocks`.
+ *
+ * @param collection - The date cell collection containing timing and blocks to expand.
+ * @returns An array of {@link DateCellDurationSpan} values with concrete start times and durations.
  */
 export declare function expandDateCellCollection<B extends DateCell = DateCell>(collection: DateCellCollection<B>): DateCellDurationSpan<B>[];
 /**
  * Expands the given blocks into {@link DateCellDurationSpan} values using the provided timing.
  *
  * Shorthand for creating a {@link dateCellTimingExpansionFactory} and immediately invoking it.
+ *
+ * @param timing - The timing schedule providing start times and duration.
+ * @param blocks - The date cell blocks to expand into duration spans.
+ * @returns An array of {@link DateCellDurationSpan} values with concrete start times.
  */
 export declare function expandDateCellTiming<B extends DateCell = DateCell>(timing: DateCellTiming, blocks: B[]): DateCellDurationSpan<B>[];
 /**
@@ -186,6 +219,9 @@ export interface DateCellTimingExpansionFactoryConfig<B extends DateCell | DateC
  * Filtering is applied both at the block level and at the computed duration span level,
  * and evaluation can be capped for performance with large datasets.
  *
+ * @param config - Configuration specifying the timing, range limits, filters, and output caps.
+ * @returns A factory function that expands date cell blocks into {@link DateCellDurationSpan} arrays.
+ *
  * @example
  * ```ts
  * const timing = dateCellTiming({ startsAt, duration: 60 }, 5);
@@ -312,6 +348,9 @@ export type DateCellDayTimingInfoFactory = ((date: DateOrDateCellIndex, now?: Da
  * const dateInfo = infoFactory(someDate);
  * console.log(dateInfo.dayIndex);    // which day index this date falls on
  * ```
+ *
+ * @param config - Configuration providing the timing and optional range limit.
+ * @returns A factory that computes {@link DateCellDayTimingInfo} for any date or day index.
  */
 export declare function dateCellDayTimingInfoFactory(config: DateCellDayTimingInfoFactoryConfig): DateCellDayTimingInfoFactory;
 /**
@@ -337,6 +376,9 @@ export type DateCellTimingRelativeIndexFactory<T extends DateCellTimingStartsAt
  * Type guard that returns true if the input is a {@link DateCellTimingRelativeIndexFactory}.
  *
  * Checks for the presence of `_timing` and `_normalInstance` properties on a function.
+ *
+ * @param input - The value to check.
+ * @returns True if the input is a {@link DateCellTimingRelativeIndexFactory}.
  */
 export declare function isDateCellTimingRelativeIndexFactory<T extends DateCellTimingStartsAt = DateCellTimingStartsAt>(input: unknown): input is DateCellTimingRelativeIndexFactory<T>;
 /**
@@ -365,6 +407,9 @@ export declare function isDateCellTimingRelativeIndexFactory<T extends DateCellT
  * indexFactory._timing;         // the original timing
  * indexFactory._normalInstance;  // timezone normalizer
  * ```
+ *
+ * @param input - A timing configuration or an existing factory (returned as-is).
+ * @returns A factory that converts dates, ISO8601 day strings, or indexes to zero-based day offsets.
  */
 export declare function dateCellTimingRelativeIndexFactory<T extends DateCellTimingStartsAt = DateCellTimingStartsAt>(input: T | DateCellTimingRelativeIndexFactory<T>): DateCellTimingRelativeIndexFactory<T>;
 /**
@@ -382,6 +427,9 @@ export type DateCellTimingRelativeIndexArrayFactory<T extends DateCellTimingStar
  * dates, date ranges, and cell ranges into a flat array of day indexes.
  *
  * Date ranges and cell ranges are expanded to include every index within the range.
+ *
+ * @param indexFactory - The relative index factory used for date-to-index conversion.
+ * @returns A factory that flattens mixed date/range arrays into day index arrays.
  */
 export declare function dateCellTimingRelativeIndexArrayFactory<T extends DateCellTimingStartsAt = DateCellTimingStartsAt>(indexFactory: DateCellTimingRelativeIndexFactory<T>): DateCellTimingRelativeIndexArrayFactory<T>;
 /**
@@ -400,6 +448,10 @@ export declare function dateCellTimingRelativeIndexArrayFactory<T extends DateCe
  * // Get the index for a specific date
  * const index = getRelativeIndexForDateCellTiming(timing, someDate);
  * ```
+ *
+ * @param timing - The timing providing the start date and timezone context.
+ * @param date - A date or index to convert; defaults to the current date/time.
+ * @returns The zero-based day index relative to the timing's start.
  */
 export declare function getRelativeIndexForDateCellTiming(timing: DateCellTimingStartsAt, date?: DateOrDateCellIndex): DateCellIndex;
 /**
@@ -433,6 +485,9 @@ export type DateCellTimingDateFactory<T extends DateCellTimingStartsAt = DateCel
  * // Convert index 3 to a date with a specific reference time
  * const dateForDay3AtNoon = dateFactory(3, noonDate);
  * ```
+ *
+ * @param timing - The timing providing the start date and timezone context.
+ * @returns A factory that maps day indexes to calendar dates preserving the current time-of-day.
  */
 export declare function dateCellTimingDateFactory<T extends DateCellTimingStartsAt = DateCellTimingStartsAt>(timing: T): DateCellTimingDateFactory<T>;
 /**
@@ -446,6 +501,9 @@ export declare function dateCellTimingDateFactory<T extends DateCellTimingStarts
  * const timing = dateCellTiming({ startsAt, duration: 60 }, 5);
  * const lastIndex = dateCellTimingEndIndex(timing); // 4 (zero-based, 5 days)
  * ```
+ *
+ * @param input - A timing or an existing relative index factory.
+ * @returns The zero-based index of the last day in the schedule.
  */
 export declare function dateCellTimingEndIndex(input: DateCellTiming | DateCellTimingRelativeIndexFactory<DateCellTiming>): IndexNumber;
 /**
@@ -471,6 +529,9 @@ export type DateCellTimingUseSystemAndIgnoreEnforcement = DateTimezoneConversion
  * for any day index relative to the timing's start.
  *
  * The returned date represents the beginning of the day in the timing's timezone context.
+ *
+ * @param input - A timing or an existing relative index factory.
+ * @returns A factory that maps day indexes to the start-of-day date in the timing's timezone.
  */
 export declare function dateCellTimingStartDateFactory<T extends DateCellTimingStartsAt = DateCellTimingStartsAt>(input: T | DateCellTimingRelativeIndexFactory<T>): DateCellTimingStartDateFactory<T>;
 /**
@@ -502,6 +563,9 @@ export type DateCellTimingStartsAtDateFactory<T extends DateCellTimingStartsAt =
  * // Also works with dates
  * const startForDate = startsAtFactory(someDate);
  * ```
+ *
+ * @param input - A timing or an existing relative index factory.
+ * @returns A factory that computes the concrete event start time for any day index.
  */
 export declare function dateCellTimingStartsAtDateFactory<T extends DateCellTimingStartsAt = DateCellTimingStartsAt>(input: T | DateCellTimingRelativeIndexFactory<T>): DateCellTimingStartsAtDateFactory<T>;
 /**
@@ -525,11 +589,18 @@ export type DateCellTimingEndDateFactory<T extends DateCellTiming = DateCellTimi
  * // Get the end time for day 2 (startsAt time + 60 minutes on day 2)
  * const day2End = endFactory(2);
  * ```
+ *
+ * @param input - A timing or an existing relative index factory.
+ * @returns A factory that computes the end time (startsAt + duration) for any day index.
  */
 export declare function dateCellTimingEndDateFactory<T extends DateCellTiming = DateCellTiming>(input: T | DateCellTimingRelativeIndexFactory<T>): DateCellTimingEndDateFactory<T>;
 /**
  * Convenience function that returns the calendar date for a given day index or date
  * relative to the timing. Shorthand for creating a {@link dateCellTimingDateFactory} and invoking it.
+ *
+ * @param timing - The timing providing the start date and timezone context.
+ * @param input - A date or day index to convert.
+ * @returns The calendar date corresponding to the input, preserving current time-of-day.
  */
 export declare function getRelativeDateForDateCellTiming(timing: DateCellTimingStartsAt, input: DateOrDateCellIndex): Date;
 /**
@@ -598,6 +669,9 @@ export interface UpdateDateCellTimingWithDateCellTimingEventInput {
  * });
  * // result has the same start day and end day, but new time-of-day and 90-minute duration
  * ```
+ *
+ * @param input - Configuration specifying the timing to update, the event source, and which aspects to replace.
+ * @returns A new {@link FullDateCellTiming} with the requested aspects replaced.
  */
 export declare function updateDateCellTimingWithDateCellTimingEvent(input: UpdateDateCellTimingWithDateCellTimingEventInput): FullDateCellTiming;
 /**
@@ -650,5 +724,8 @@ export interface IsDateWithinDateCellRangeConfig {
  * isInRange(6);        // false - index 6 is outside [2, 5]
  * isInRange(someDate); // converts date to index, then checks containment
  * ```
+ *
+ * @param config - Configuration specifying the reference range and optional timezone context.
+ * @returns A predicate function that checks containment within the configured range.
  */
 export declare function isDateWithinDateCellRangeFunction(config: IsDateWithinDateCellRangeConfig): IsDateWithinDateCellRangeFunction;

package/src/lib/date/date.cell.filter.d.ts

@@ -12,6 +12,7 @@ export type DateCellDurationSpanFilterFunction<B extends DateCell = DateCell> =
  * Useful for identifying events or blocks that have already begun relative to a point in time.
  *
  * @param now - Reference time to compare against. Defaults to the current time.
+ * @returns a filter function that returns true for spans whose start time is at or before the reference time
  *
  * @example
  * ```ts
@@ -26,6 +27,7 @@ export declare function dateCellDurationSpanHasStartedFilterFunction<B extends D
  * The inverse of {@link dateCellDurationSpanHasStartedFilterFunction}. Useful for finding upcoming or future events.
  *
  * @param now - Reference time to compare against. Defaults to the current time.
+ * @returns a filter function that returns true for spans whose start time is strictly after the reference time
  *
  * @example
  * ```ts
@@ -41,6 +43,7 @@ export declare function dateCellDurationSpanHasNotStartedFilterFunction<B extend
  * Useful for identifying completed events.
  *
  * @param now - Reference time to compare against. Defaults to the current time.
+ * @returns a filter function that returns true for spans whose computed end time is at or before the reference time
  *
  * @example
  * ```ts
@@ -56,6 +59,7 @@ export declare function dateCellDurationSpanHasEndedFilterFunction<B extends Dat
  * still in progress or have not yet occurred.
  *
  * @param now - Reference time to compare against. Defaults to the current time.
+ * @returns a filter function that returns true for spans whose computed end time is strictly after the reference time
  *
  * @example
  * ```ts
@@ -79,6 +83,7 @@ export type ModifyDateCellsToFitRangeFunction = <B extends DateCell | DateCellRa
  * indices clamped to the range boundaries. Non-overlapping cells are excluded entirely.
  *
  * @param range - The target range to fit cells into.
+ * @returns a reusable function that clamps or filters date cells to the configured range
  *
  * @example
  * ```ts
@@ -95,6 +100,7 @@ export declare function modifyDateCellsToFitRangeFunction(range: DateCellRange):
  *
  * @param range - The target range to fit cells into.
  * @param input - The date cells to clamp or filter.
+ * @returns an array of date cells clamped to the range, with non-overlapping cells removed
  *
  * @example
  * ```ts
@@ -108,6 +114,7 @@ export declare function modifyDateCellsToFitRange<B extends DateCell | DateCellR
  *
  * @param range - The target range to fit the cell into.
  * @param input - The single date cell to clamp or exclude.
+ * @returns the clamped date cell, or `undefined` if it does not overlap the range
  *
  * @example
  * ```ts

package/src/lib/date/date.cell.index.d.ts

@@ -18,6 +18,7 @@ export interface DateCellRange extends DateCell {
  * Does not check validity. Use {@link isValidDateCellRange} for that.
  *
  * @param input - value to check
+ * @returns true if the input is a DateCellRange
  */
 export declare function isDateCellRange(input: unknown): input is DateCellRange;
 /**
@@ -31,6 +32,7 @@ export type DateCellOrDateCellIndexOrDateCellRange = DateCellIndex | DateCell |
  * that is greater than or equal to `i`.
  *
  * @param input - range to validate
+ * @returns true if the range has valid non-negative indexes and `to` (when defined) is greater than or equal to `i`
  */
 export declare function isValidDateCellRange(input: DateCellRange): boolean;
 /**
@@ -39,6 +41,7 @@ export declare function isValidDateCellRange(input: DateCellRange): boolean;
  * Validates that each range is individually valid and that no ranges overlap or appear out of order.
  *
  * @param input - array of ranges to validate as a non-overlapping ascending series
+ * @returns true if the array is sorted in ascending order with no overlapping or duplicate indexes
  */
 export declare function isValidDateCellRangeSeries(input: DateCellRange[]): boolean;
 /**
@@ -47,6 +50,7 @@ export declare function isValidDateCellRangeSeries(input: DateCellRange[]): bool
  * The input range is not expected to be sorted.
  *
  * @param input - unsorted array of date cell ranges to scan
+ * @returns the smallest starting index found, or 0 if the input is empty
  */
 export declare function getLeastDateCellIndexInDateCellRanges(input: (DateCell | DateCellRange)[]): DateCellIndex;
 /**
@@ -55,6 +59,7 @@ export declare function getLeastDateCellIndexInDateCellRanges(input: (DateCell |
  * The input range is not expected to be sorted.
  *
  * @param input - unsorted array of date cell ranges to scan
+ * @returns the largest ending index found, or 0 if the input is empty
  */
 export declare function getGreatestDateCellIndexInDateCellRanges(input: (DateCell | DateCellRange)[]): DateCellIndex;
 /**
@@ -62,13 +67,21 @@ export declare function getGreatestDateCellIndexInDateCellRanges(input: (DateCel
  * along with references to the items that contain those extreme indexes.
  */
 export interface LeastAndGreatestDateCellIndexResult<T> {
-    /** Smallest starting index found. */
+    /**
+     * Smallest starting index found.
+     */
     leastIndex: number;
-    /** The item containing the smallest starting index. */
+    /**
+     * The item containing the smallest starting index.
+     */
     leastIndexItem: T;
-    /** Largest ending index found (considers `to` values). */
+    /**
+     * Largest ending index found (considers `to` values).
+     */
     greatestIndex: number;
-    /** The item containing the largest ending index. */
+    /**
+     * The item containing the largest ending index.
+     */
     greatestIndexItem: T;
 }
 /**
@@ -77,6 +90,7 @@ export interface LeastAndGreatestDateCellIndexResult<T> {
  * The input range is not expected to be sorted.
  *
  * @param input - unsorted array of date cell ranges to scan
+ * @returns an object with the least and greatest indexes and their source items, or null if the input is empty
  */
 export declare function getLeastAndGreatestDateCellIndexInDateCellRanges<T extends DateCellRange>(input: T[]): Maybe<LeastAndGreatestDateCellIndexResult<T>>;
 /**
@@ -100,12 +114,14 @@ export type DateOrDateRangeOrDateCellIndexOrDateCellRange = DateRange | DateOrDa
  *
  * @param i - starting cell index
  * @param to - ending cell index (inclusive); defaults to `i`
+ * @returns a DateCellRangeWithRange spanning from `i` to `to`
  */
 export declare function dateCellRange(i: number, to?: Maybe<number>): DateCellRangeWithRange;
 /**
  * Creates a single-cell {@link DateCellRangeWithRange} where both `i` and `to` equal the given index.
  *
  * @param dateCellIndex - the index for both start and end of the range
+ * @returns a DateCellRangeWithRange where `i` and `to` both equal the given index
  */
 export declare function dateCellRangeWithRangeFromIndex(dateCellIndex: DateCellIndex): DateCellRangeWithRange;
 /**
@@ -113,6 +129,7 @@ export declare function dateCellRangeWithRangeFromIndex(dateCellIndex: DateCellI
  * ensuring the result always has an explicit `to` value.
  *
  * @param input - index, cell, or range to normalize
+ * @returns a DateCellRangeWithRange with an explicit `to` value
  */
 export declare function dateCellRangeWithRange(input: DateCellOrDateCellIndexOrDateCellRange): DateCellRangeWithRange;
 /**
@@ -124,6 +141,7 @@ export type DateCellRangeIncludedByRangeFunction = (range: DateCellOrDateCellInd
  * fully contains the configured `inputRange`.
  *
  * @param inputRange - the range that must be fully included
+ * @returns a function that returns true when its argument fully contains `inputRange`
  */
 export declare function dateCellRangeIncludedByRangeFunction(inputRange: DateCellOrDateCellIndexOrDateCellRange): DateCellRangeIncludedByRangeFunction;
 /**
@@ -135,6 +153,7 @@ export type DateCellRangeOverlapsRangeFunction = (range: DateCellOrDateCellIndex
  * has any overlap with the configured `inputRange`.
  *
  * @param inputRange - the range to test for overlap against
+ * @returns a function that returns true when its argument overlaps with `inputRange`
  */
 export declare function dateCellRangeOverlapsRangeFunction(inputRange: DateCellOrDateCellIndexOrDateCellRange): DateCellRangeOverlapsRangeFunction;
 /**
@@ -142,18 +161,22 @@ export declare function dateCellRangeOverlapsRangeFunction(inputRange: DateCellO
  *
  * @param rangeA - first range to compare
  * @param rangeB - second range to compare
+ * @returns true if the two ranges share at least one common index
  */
 export declare function dateCellRangeOverlapsRange(rangeA: DateCellOrDateCellIndexOrDateCellRange, rangeB: DateCellOrDateCellIndexOrDateCellRange): boolean;
 /**
  * Returns a sort comparator that orders ranges first by starting index (`i`), then by ending index (`to`).
  *
  * In many cases {@link sortAscendingIndexNumberRefFunction} may be preferential when `to` ordering is not needed.
+ *
+ * @returns a comparator function that sorts ranges by `i` then by `to`
  */
 export declare function sortDateCellRangeAndSizeFunction<T extends DateCellRange>(): SortCompareFunction<T>;
 /**
  * Sorts the input date ranges in-place by ascending index using {@link sortAscendingIndexNumberRefFunction}.
  *
  * @param input - array of ranges to sort (mutated in place)
+ * @returns the same array, sorted in ascending index order
  */
 export declare function sortDateCellRanges<T extends DateCellRange>(input: T[]): T[];
 /**
@@ -169,6 +192,7 @@ export type DateCellRangeWithRange = Omit<DateCellRange, 'to'> & {
  * The input is sorted internally before grouping.
  *
  * @param input - cells or ranges to merge into contiguous groups
+ * @returns an array of non-overlapping contiguous DateCellRangeWithRange values
  *
  * @example
  * ```ts
@@ -186,18 +210,21 @@ export declare function groupToDateCellRanges(input: (DateCell | DateCellRange)[
  * Returns an array containing every individual index in the given date cell range (inclusive of both `i` and `to`).
  *
  * @param input - range to expand into individual indexes
+ * @returns an array of every DateCellIndex from `i` to `to` inclusive
  */
 export declare function allIndexesInDateCellRange(input: DateCellRange): DateCellIndex[];
 /**
  * Flattens an array of indexes and/or ranges into a single array of individual {@link DateCellIndex} values.
  *
  * @param input - mix of raw indexes and ranges to flatten
+ * @returns a flat array of all individual DateCellIndex values
  */
 export declare function allIndexesInDateCellRangesToArray(input: (DateCellIndex | DateCellRange)[]): DateCellIndex[];
 /**
  * Returns a deduplicated {@link Set} of all indexes within the input ranges.
  *
  * @param input - mix of raw indexes and ranges to collect
+ * @returns a Set containing every unique DateCellIndex from the input
  */
 export declare function allIndexesInDateCellRanges(input: (DateCellIndex | DateCellRange)[]): Set<DateCellIndex>;
 /**
@@ -205,6 +232,7 @@ export declare function allIndexesInDateCellRanges(input: (DateCellIndex | DateC
  *
  * @param blocks - cells or ranges to filter
  * @param range - bounding range that blocks must fall within
+ * @returns only the blocks that fall entirely within the given range
  */
 export declare function filterDateCellsInDateCellRange<T extends DateCell | DateCellRange>(blocks: T[], range: DateCellRangeWithRange): T[];
 /**
@@ -220,6 +248,7 @@ export type IsDateCellWithinDateCellRangeFunction = (input: IsDateCellWithinDate
  * is fully contained within `inputRange`.
  *
  * @param inputRange - the bounding range to test containment against
+ * @returns a function that returns true when its argument is fully contained within `inputRange`
  */
 export declare function isDateCellWithinDateCellRangeFunction(inputRange: IsDateCellWithinDateCellRangeInput): IsDateCellWithinDateCellRangeFunction;
 /**
@@ -227,6 +256,7 @@ export declare function isDateCellWithinDateCellRangeFunction(inputRange: IsDate
  *
  * @param range - the outer bounding range
  * @param contains - the cell or range to test for containment
+ * @returns true if `contains` is fully within `range`
  */
 export declare function isDateCellWithinDateCellRange(range: IsDateCellWithinDateCellRangeInput, contains: IsDateCellWithinDateCellRangeInput): boolean;
 /**
@@ -252,6 +282,7 @@ export interface DateCellRangeBlockCountInfo {
  * Internally groups overlapping ranges before counting so each index is counted only once.
  *
  * @param inputDateCellRange - one or more cells/ranges to analyze
+ * @returns count, total, and average statistics for the given ranges
  */
 export declare function dateCellRangeBlocksCountInfo(inputDateCellRange: ArrayOrValue<DateCell | DateCellRange>): DateCellRangeBlockCountInfo;
 /**
@@ -260,6 +291,7 @@ export declare function dateCellRangeBlocksCountInfo(inputDateCellRange: ArrayOr
  * Shorthand for `dateCellRangeBlocksCountInfo(input).count`.
  *
  * @param inputDateCellRange - one or more cells/ranges to count
+ * @returns the total number of individual cell indexes
  *
  * @example
  * ```ts
@@ -277,6 +309,7 @@ export type DateCellRangesFullyCoverDateCellRangeFunction = (range: DateCellRang
  * grouped range from `ranges` fully covers a given input range.
  *
  * @param ranges - the covering ranges to test against
+ * @returns a function that returns true when any single grouped range fully covers the input range
  */
 export declare function dateCellRangesFullyCoverDateCellRangeFunction(ranges: ArrayOrValue<DateCellRange>): DateCellRangesFullyCoverDateCellRangeFunction;
 /**
@@ -330,6 +363,7 @@ export interface GetNextDateCellTimingIndexResult<T extends DateCellRange> {
  * nearest future range's starting index is used.
  *
  * @param input - the current index and ranges to evaluate
+ * @returns classification of ranges as past/present/future and the next upcoming index
  *
  * @example
  * ```ts
@@ -352,6 +386,7 @@ export declare function getNextDateCellTimingIndex<T extends DateCellRange>(inpu
  *
  * @param range - the date cell range to classify
  * @param nowIndex - the reference index representing "now"
+ * @returns 'past', 'present', or 'future' depending on the range's position relative to `nowIndex`
  */
 export declare function dateRelativeStateForDateCellRangeComparedToIndex(range: DateCellRange, nowIndex: DateCellIndex): DateRelativeState;
 /**
@@ -359,6 +394,7 @@ export declare function dateRelativeStateForDateCellRangeComparedToIndex(range:
  * from `i` to `to` (inclusive). Each copy retains all properties of the original block.
  *
  * @param block - the range to expand
+ * @returns an array of single-cell copies, one per index from `i` to `to`
  *
  * @example
  * ```ts
@@ -381,12 +417,14 @@ export interface UniqueDateCellRange extends UniqueDateCell, DateCellRange {
  * Returns true if the input spans more than one cell (i.e., has a `to` value strictly greater than `i`).
  *
  * @param input - range or cell to check
+ * @returns true if `to` is defined and strictly greater than `i`
  */
 export declare function dateCellRangeHasRange(input: DateCellRange | UniqueDateCell): input is DateCellRangeWithRange;
 /**
  * Returns the effective ending index of a range: `to` if defined, otherwise `i`.
  *
  * @param input - range or cell to read
+ * @returns the `to` index if defined, otherwise `i`
  */
 export declare function dateCellEndIndex(input: DateCellRange | UniqueDateCell): IndexNumber;
 /**
@@ -404,6 +442,7 @@ export interface UniqueDateCellRangeGroup<B extends DateCellRange | UniqueDateCe
  * and `to` is the maximum ending index across all blocks.
  *
  * @param input - cells or ranges to group
+ * @returns a UniqueDateCellRangeGroup containing the sorted blocks with `i` at 0
  */
 export declare function groupUniqueDateCells<B extends DateCellRange | UniqueDateCell>(input: B[]): UniqueDateCellRangeGroup<B>;
 /**
@@ -472,6 +511,7 @@ export type ExpandUniqueDateCellsFunction<B extends DateCellRange | UniqueDateCe
  * according to the provided configuration. Handles overlap resolution, gap filling, and boundary clamping.
  *
  * @param config - controls start/end bounds, fill strategy, and overlap retention behavior
+ * @returns a function that merges, fills, and resolves overlaps in date cell range arrays
  *
  * @example
  * ```ts

package/src/lib/date/date.cell.schedule.d.ts

@@ -555,6 +555,8 @@ export interface DateCellScheduleDateCellTimingFilterConfig {
  * Creates a DateCellScheduleDateCellTimingFilter that tests whether a DateCell block's index is allowed by the schedule within the given timing.
  *
  * @param config - timing and schedule to build the filter from
+ * @param config.timing - the DateCellTiming that defines the date range and event times for the filter
+ * @param config.schedule - the DateCellSchedule that controls which day codes and indices are included or excluded
  * @returns a decision function returning true for allowed blocks
  */
 export declare function dateCellScheduleDateCellTimingFilter<B extends DateCell = DateCell>({ timing, schedule }: DateCellScheduleDateCellTimingFilterConfig): DateCellScheduleDateCellTimingFilter<B>;

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

@@ -96,6 +96,8 @@ export declare function daysToMinutes(days?: number): Minutes;
  *
  * Useful as a default for "no expiration" comparisons.
  *
+ * @returns the MAX_FUTURE_DATE sentinel
+ *
  * @example
  * ```ts
  * const futureDate = maxFutureDate();
@@ -393,6 +395,10 @@ export declare function copyHoursAndMinutesFromUTCDate(target: Date, fromDate: D
  * Sets the hours and optionally minutes on a target date (defaults to now), with optional rounding to strip seconds/milliseconds.
  *
  * @param config - hours, optional minutes, and rounding options
+ * @param config.hours - the hours value to set
+ * @param config.minutes - optional minutes value to set
+ * @param config.removeSeconds - whether to zero out seconds
+ * @param config.roundDownToMinute - whether to zero out seconds and milliseconds (defaults to true)
  * @param target - date to modify (defaults to the current date/time)
  * @returns a new Date with the specified time values applied
  *