@dereekb/date 13.0.7 → 13.1.0

package/package.json

@@ -1,12 +1,11 @@
 {
   "name": "@dereekb/date",
-  "version": "13.0.7",
+  "version": "13.1.0",
   "peerDependencies": {
-    "@dereekb/rxjs": "13.0.7",
-    "@dereekb/util": "13.0.7",
+    "@dereekb/rxjs": "13.1.0",
+    "@dereekb/util": "13.1.0",
     "@vvo/tzdb": "^6.0.0",
-    "class-transformer": "^0.5.1",
-    "class-validator": "^0.15.1",
+    "arktype": "^2.2.0",
     "date-fns": "^4.0.0",
     "date-fns-tz": "^3.2.0",
     "rrule": "git+https://git@github.com/dereekb/rrule#2b13b1ea881059ba2ecfec380e12ef244ef54570",
@@ -14,7 +13,7 @@
   },
   "dependencies": {},
   "devDependencies": {
-    "@dereekb/rxjs": "13.0.7"
+    "@dereekb/rxjs": "13.1.0"
   },
   "exports": {
     "./package.json": "./package.json",

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

@@ -1,7 +1,7 @@
 import { type ISO8601DayString } from '@dereekb/util';
-import { DateDurationSpan } from './date.duration';
+import { type DateDurationSpan } from './date.duration';
 /**
- * CalendarDateType
+ * Distinguishes between time-based calendar events and all-day/multi-day events.
  */
 export declare enum CalendarDateType {
     /**
@@ -14,18 +14,23 @@ export declare enum CalendarDateType {
     DAYS = "days"
 }
 /**
- * Represents a date on a calendar.
+ * A calendar entry that combines a {@link DateDurationSpan} with a {@link CalendarDateType} to distinguish
+ * between timed events and all-day/multi-day events.
  */
 export interface CalendarDate extends DateDurationSpan {
     type: CalendarDateType;
 }
-export declare class CalendarDate extends DateDurationSpan {
-    /**
-     * The type of event date.
-     */
+/**
+ * ArkType schema for {@link CalendarDate}.
+ */
+export declare const calendarDateType: import("arktype/internal/variants/object.ts").ObjectType<{
+    startsAt: Date;
+    duration: number;
     type: CalendarDateType;
-    constructor(template?: CalendarDate);
-}
+}, {}>;
+/**
+ * Configuration for creating calendar dates with timezone handling.
+ */
 export interface CalendarDateConfig {
     /**
      * The timezone to generate the calendar day on.
@@ -36,7 +41,56 @@ export interface CalendarDateConfig {
      */
     timezone?: string | false;
 }
+/**
+ * Creates a {@link CalendarDate} from a day string and optional multi-day span.
+ */
 export type CalendarDateFactory = (day: ISO8601DayString, days?: number) => CalendarDate;
+/**
+ * Creates a {@link CalendarDateFactory} that produces all-day calendar events with timezone-aware start times.
+ *
+ * The factory converts an ISO 8601 day string to a UTC date, then applies timezone normalization
+ * so the resulting `startsAt` represents the correct moment for the target timezone.
+ *
+ * @param config - optional timezone configuration
+ * @returns a factory function that creates CalendarDate objects
+ *
+ * @example
+ * ```ts
+ * const factory = calendarDateFactory({ timezone: 'America/Denver' });
+ * const event = factory('2024-01-15', 3);
+ * // event.type === CalendarDateType.DAYS
+ * // event.duration === daysToMinutes(3)
+ * ```
+ */
 export declare function calendarDateFactory(config?: CalendarDateConfig): CalendarDateFactory;
+/**
+ * Convenience function that creates a single all-day {@link CalendarDate} with optional timezone.
+ *
+ * Shorthand for creating a factory and immediately invoking it.
+ *
+ * @param day - ISO 8601 day string (e.g. '2024-01-15')
+ * @param days - number of days the event spans
+ * @param timezone - IANA timezone string, false for UTC, or undefined for system timezone
+ * @returns a CalendarDate with type DAYS
+ *
+ * @example
+ * ```ts
+ * const event = calendarDate('2024-01-15', 1, 'America/Denver');
+ * // event.type === CalendarDateType.DAYS
+ * ```
+ */
 export declare function calendarDate(day: ISO8601DayString, days?: number, timezone?: string | false): CalendarDate;
+/**
+ * Wraps an existing {@link DateDurationSpan} as a time-based {@link CalendarDate}.
+ *
+ * @param dateDurationSpan - the duration span to wrap
+ * @returns a CalendarDate with type TIME
+ *
+ * @example
+ * ```ts
+ * const span: DateDurationSpan = { startsAt: new Date(), duration: 60 };
+ * const event = calendarDateForDateDurationSpan(span);
+ * // event.type === CalendarDateType.TIME
+ * ```
+ */
 export declare function calendarDateForDateDurationSpan(dateDurationSpan: DateDurationSpan): CalendarDate;

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

@@ -1,6 +1,6 @@
 import { type IndexRef, type Maybe, type TimezoneString, type Minutes, type FractionalHour, type TimezoneStringRef, type ISO8601DayString } from '@dereekb/util';
 import { type DateRange, type DateRangeDayDistanceInput } from './date.range';
-import { DateDurationSpan } from './date.duration';
+import { type DateDurationSpan } from './date.duration';
 import { type DateTimezoneUtcNormalFunctionInput, type DateTimezoneUtcNormalInstance } from './date.timezone';
 /**
  * Index from 0 of which day this block represents.
@@ -11,9 +11,18 @@ import { type DateTimezoneUtcNormalFunctionInput, type DateTimezoneUtcNormalInst
  */
 export type DateCellIndex = number;
 /**
- * Returns true if the index is a non-negative integer.
+ * Returns true if the index is a non-negative integer, which is required for valid date cell indexing.
  *
- * @param input
+ * @param input - the index to validate
+ * @returns whether the input is a valid date cell index (>= 0 and an integer)
+ *
+ * @example
+ * ```ts
+ * isValidDateCellIndex(0); // true
+ * isValidDateCellIndex(5); // true
+ * isValidDateCellIndex(-1); // false
+ * isValidDateCellIndex(0.5); // false
+ * ```
  */
 export declare function isValidDateCellIndex(input: DateCellIndex): boolean;
 /**
@@ -32,15 +41,23 @@ export interface DateCellIndexDatePair extends Readonly<IndexRef> {
 export interface DateCell extends IndexRef {
     i: DateCellIndex;
 }
-export declare class DateCell {
-    i: DateCellIndex;
-    constructor(template?: DateCell);
-}
 /**
- * Converts the input number or DateCell to a DateCell.
+ * ArkType schema for {@link DateCell}.
+ */
+export declare const dateCellType: import("arktype/internal/variants/object.ts").ObjectType<{
+    i: number;
+}, {}>;
+/**
+ * Normalizes a number or {@link DateCell} to a DateCell object.
+ *
+ * @param dateCellOrIndex - a numeric index or existing DateCell
+ * @returns a DateCell object with the `i` property set
  *
- * @param dateCellOrIndex
- * @returns
+ * @example
+ * ```ts
+ * dateCell(3); // { i: 3 }
+ * dateCell({ i: 3 }); // { i: 3 } (returned as-is)
+ * ```
  */
 export declare function dateCell(dateCellOrIndex: DateCellIndex | DateCell): DateCell;
 /**
@@ -73,10 +90,18 @@ export interface DateCellTimingStartsAtForStartOfDayInput {
     readonly timezone?: TimezoneString;
 }
 /**
- * Creates a new DateCellTimingStartsAt for the given time and timezone.
+ * Creates a {@link DateCellTimingStartsAt} positioned at the start of the current day in the given timezone.
+ *
+ * Useful for initializing a timing range that begins "today" in a particular timezone.
  *
- * @param now
- * @returns
+ * @param input - optional timezone and "now" override
+ * @returns a DateCellTimingStartsAt with startsAt at midnight and the resolved timezone
+ *
+ * @example
+ * ```ts
+ * const timing = dateCellTimingStartsAtForStartOfDay({ timezone: 'America/Denver' });
+ * // timing.startsAt is midnight today in Denver, timing.timezone === 'America/Denver'
+ * ```
  */
 export declare function dateCellTimingStartsAtForStartOfDay(input?: DateCellTimingStartsAtForStartOfDayInput): DateCellTimingStartsAt;
 /**
@@ -108,11 +133,15 @@ export interface DateCellTimingDateRange extends DateRange, TimezoneStringRef {
  * A DateCellTimingDateRange, but the start time is the startsAt time for the first event.
  */
 export type DateCellTimingEventRange = DateCellTimingDateRange;
-export declare class DateCellTiming extends DateDurationSpan {
+/**
+ * ArkType schema for {@link DateCellTiming}.
+ */
+export declare const dateCellTimingType: import("arktype/internal/variants/object.ts").ObjectType<{
+    startsAt: Date;
+    duration: number;
     end: Date;
-    timezone: TimezoneString;
-    constructor(template?: DateCellTiming);
-}
+    timezone: string;
+}, {}>;
 /**
  * Reference to a DateCellTiming
  */
@@ -137,12 +166,19 @@ export type DateCellTimingRangeInput = DateRangeDayDistanceInput | DateRange | n
  */
 export type DateCellTimingTimezoneInput = Omit<DateTimezoneUtcNormalFunctionInput, 'number'>;
 /**
- * Creates a DateTimezoneUtcNormalInstance from the input. Asserts and gurantees that a timezone string is provided.
+ * Creates a {@link DateTimezoneUtcNormalInstance} from the input, guaranteeing that a timezone string is configured.
+ *
+ * Falls back to the system timezone if no input is provided.
  *
- * If null/undefined is passed, returns a normal for the system time.
+ * @param timezoneInput - timezone configuration or undefined for system timezone
+ * @returns a DateTimezoneUtcNormalInstance with a guaranteed configured timezone
+ * @throws {Error} When the timezone cannot be resolved to a known timezone string.
  *
- * @param timezoneInput
- * @returns
+ * @example
+ * ```ts
+ * const instance = dateCellTimingTimezoneNormalInstance('America/Denver');
+ * instance.configuredTimezoneString; // 'America/Denver'
+ * ```
  */
 export declare function dateCellTimingTimezoneNormalInstance(timezoneInput?: DateCellTimingTimezoneInput): DateTimezoneUtcNormalInstance;
 /**
@@ -155,10 +191,17 @@ export interface FullDateCellTiming extends DateCellTiming, DateCellTimingDateRa
  */
 export type FullDateCellTimingStart = Pick<FullDateCellTiming, 'start'>;
 /**
- * Creates a FullDateCellTiming from the input timing.
+ * Derives a {@link FullDateCellTiming} from a {@link DateCellTiming} by computing the `start` date (midnight in the timing's timezone).
  *
- * @param timing
- * @returns
+ * @param timing - the base timing to expand
+ * @returns the timing with the `start` field populated
+ *
+ * @example
+ * ```ts
+ * const timing: DateCellTiming = { startsAt, end, duration: 60, timezone: 'America/Denver' };
+ * const full = fullDateCellTiming(timing);
+ * // full.start is midnight for the startsAt day in Denver
+ * ```
  */
 export declare function fullDateCellTiming(timing: DateCellTiming): FullDateCellTiming;
 export interface FullDateCellTimingTimezonePair {
@@ -166,17 +209,25 @@ export interface FullDateCellTimingTimezonePair {
     readonly normalInstance: DateTimezoneUtcNormalInstance;
 }
 /**
- * Creates a FullDateCellTimingTimezonePair from the input timing.
+ * Creates a {@link FullDateCellTimingTimezonePair} containing both the expanded timing and the timezone normal instance.
  *
- * @param timing
- * @returns
+ * Useful when both the full timing and the timezone conversion utilities are needed together.
+ *
+ * @param timing - the base timing to expand
+ * @returns the full timing paired with its timezone normal instance
  */
 export declare function fullDateCellTimingTimezonePair(timing: DateCellTiming): FullDateCellTimingTimezonePair;
 /**
- * Returns true if the start date has no minutes/seconds/milliseconds. It should be midnight for it's target timezone.
+ * Validates that a date has zero minutes, seconds, and milliseconds, which is required for a valid DateCellTiming start date (midnight in the target timezone).
  *
- * @param date
- * @returns
+ * @param date - the start date to validate
+ * @returns whether the date is at a valid hour boundary
+ *
+ * @example
+ * ```ts
+ * isValidDateCellTimingStartDate(new Date('2024-01-01T06:00:00.000Z')); // true
+ * isValidDateCellTimingStartDate(new Date('2024-01-01T06:30:00.000Z')); // false
+ * ```
  */
 export declare function isValidDateCellTimingStartDate(date: Date): boolean;
 /**
@@ -199,16 +250,17 @@ export interface DateCellTimingStartPair {
     readonly normalInstance: DateTimezoneUtcNormalInstance;
 }
 /**
- * Convenience function of dateCellTimingStart() that also returns the DateTimezoneUtcNormalInstance.
+ * Computes the start-of-day date for a timing and returns it paired with the timezone normal instance.
  *
- * @param timing
- * @returns
+ * @param timing - timing with startsAt and timezone
+ * @returns the midnight start date and the timezone normal instance used to compute it
  */
 export declare function dateCellTimingStartPair(timing: DateCellTimingStartsAt): DateCellTimingStartPair;
 /**
- * Start date value for a DateCellTiming.
+ * Computes the start-of-day (midnight) date for a {@link DateCellTimingStartsAt} in its configured timezone.
  *
- * This is the midnight date instance for the timezone.
+ * @param timing - timing with startsAt and timezone
+ * @returns the midnight Date for the timing's first day in its timezone
  */
 export declare function dateCellTimingStart(timing: DateCellTimingStartsAt): Date;
 /**
@@ -224,70 +276,77 @@ export type DateCellTimingEventStartsAt = Pick<DateCellTiming, 'startsAt'>;
  */
 export type DateCellTimingEvent = Pick<DateCellTiming, 'startsAt' | 'duration'>;
 /**
- * Returns true if the two DateCellTimingStartsAtEndRange values are the same.
+ * Null-safe equality check for two {@link DateCellTimingStartsAtEndRange} values, comparing timezone, startsAt, and end.
  *
- * @param a
- * @param b
+ * @param a - first range
+ * @param b - second range
+ * @returns whether the two ranges are equivalent
  */
 export declare function isSameDateCellTimingEventStartsAtEndRange(a: Maybe<DateCellTimingStartsAtEndRange>, b: Maybe<DateCellTimingStartsAtEndRange>): boolean;
 /**
- * Returns true if the two timings are equivalent.
+ * Null-safe equality check for two {@link DateCellTiming} values, comparing duration and the starts-at/end range.
  *
- * @param a
- * @param b
+ * @param a - first timing
+ * @param b - second timing
+ * @returns whether the two timings are equivalent
  */
 export declare function isSameDateCellTiming(a: Maybe<DateCellTiming>, b: Maybe<DateCellTiming>): boolean;
 /**
- * Returns true if all variables in the input FullDateCellTimings are exact.
+ * Strict equality check for {@link FullDateCellTiming} values, including the derived `start` date.
  *
- * In most cases this comparison is unnecessary, as the start date is derived from the startsAt time.
+ * In most cases {@link isSameDateCellTiming} is sufficient since `start` is derived from `startsAt`.
  *
- * @param a
- * @param b
- * @returns
+ * @param a - first full timing
+ * @param b - second full timing
+ * @returns whether all fields are exactly equal
  */
 export declare function isSameFullDateCellTiming(a: Maybe<FullDateCellTiming>, b: Maybe<FullDateCellTiming>): boolean;
 /**
- * Returns true if the input is a DateCellTiming.
+ * Type guard that checks whether the input has the shape of a {@link DateCellTiming} (startsAt, end, timezone, duration).
  *
- * Does not check if it is a valid DateCellTiming.
+ * Does not validate correctness (e.g. end after start). Use {@link isValidDateCellTiming} for validation.
  *
- * @param input
+ * @param input - value to check
+ * @returns whether the input matches the DateCellTiming shape
  */
 export declare function isDateCellTiming(input: unknown): input is DateCellTiming;
 /**
- * Returns true if the input is possibly a FullDateCellTiming.
+ * Type guard that checks whether the input has the shape of a {@link FullDateCellTiming} (includes `start` field plus all DateCellTiming fields).
  *
- * Does not check if it is a valid FullDateCellTiming.
+ * Does not validate correctness. Use {@link isValidFullDateCellTiming} for validation.
  *
- * @param input
+ * @param input - value to check
+ * @returns whether the input matches the FullDateCellTiming shape
  */
 export declare function isFullDateCellTiming(input: unknown): input is FullDateCellTiming;
 /**
- * Creates a DateCellTimingDateRange from the input timing. Contains the start of the day in that timezone as the start date, and the end time for the final event.
+ * Derives a {@link DateCellTimingDateRange} from a timing, using midnight in the timing's timezone as the start and the event's end time as the end.
  *
- * @param timing
- * @returns
+ * @param timing - timing with startsAt, end, and timezone
+ * @returns a date range spanning from midnight of the first day to the end of the last event
  */
 export declare function dateCellTimingDateRange(timing: DateCellTimingStartsAtEndRange): DateCellTimingDateRange;
 /**
- * Returns the date range from the start of the first event to the end time of the last event.
+ * Returns a {@link DateCellTimingEventRange} spanning from the first event's startsAt to the last event's end time.
  *
- * @param timing
- * @returns
+ * Unlike {@link dateCellTimingDateRange}, the start is the event time rather than midnight.
+ *
+ * @param timing - timing with startsAt, end, and timezone
+ * @returns the event range
  */
 export declare function dateCellTimingEventRange(timing: Pick<DateCellTiming, 'startsAt' | 'end' | 'timezone'>): DateCellTimingEventRange;
 /**
- * Returns the total minutes between the start of the first event and the end of the last event.
+ * Returns the date range of the first event only (from startsAt to startsAt + duration).
  *
- * @param timing
- * @returns
+ * @param timing - timing to extract the first event from
+ * @returns date range of the first event
  */
 export declare function getDateCellTimingFirstEventDateRange(timing: DateCellTimingStartsAtEndRange): DateRange;
 /**
- * Returns the number of hours in a DateCellTiming's duration.
+ * Converts a timing's duration from minutes to fractional hours.
  *
- * @param timing
+ * @param timing - timing with a duration in minutes
+ * @returns the duration expressed as fractional hours (e.g. 90 minutes = 1.5)
  */
 export declare function getDateCellTimingHoursInEvent(timing: Pick<DateCellTiming, 'duration'>): FractionalHour;
 /**
@@ -299,32 +358,36 @@ export type UpdateDateCellTimingToTimezoneFunction = (<T extends DateCellTimingS
     readonly _timezone: TimezoneString;
 };
 /**
- * Creates a ChangeDateCellTimingToTimezoneFunction from the input.
+ * Creates a function that updates a timing's timezone and recalculates the `start` date, while preserving the original `startsAt` instant.
+ *
+ * The event occurs at the same absolute moment in time, but is now associated with a different timezone.
  *
- * @param input
- * @returns
+ * @param timezone - the new IANA timezone to apply
+ * @returns a function that updates timings to the new timezone
  */
 export declare function updateDateCellTimingToTimezoneFunction(timezone: TimezoneString): UpdateDateCellTimingToTimezoneFunction;
 /**
- * Convenience function for calling updateDateCellTimingToTimezone() with the system timezone.
+ * Updates the timing's timezone to the system timezone while preserving the absolute startsAt instant.
  *
- * @param timing
- * @returns
+ * @param timing - timing to update
+ * @returns the timing with the system timezone applied
  */
 export declare function updateDateCellTimingToSystemTimezone<T extends DateCellTimingStartsAtEndRange>(timing: T): T;
 /**
- * Convenience function for calling updateDateCellTimingToTimezone() with the UTC timezone.
+ * Updates the timing's timezone to UTC while preserving the absolute startsAt instant.
  *
- * @param timing
- * @returns
+ * @param timing - timing to update
+ * @returns the timing with UTC timezone applied
  */
 export declare function updateDateCellTimingToUTCTimezone<T extends DateCellTimingStartsAtEndRange>(timing: T): T;
 /**
- * Convenience function for calling updateDateCellTimingToTimezoneFunction() and passing the timing.
+ * Updates a timing's timezone while preserving the absolute startsAt instant.
  *
- * @param timing
- * @param timezone
- * @returns
+ * Shorthand for creating an {@link updateDateCellTimingToTimezoneFunction} and immediately invoking it.
+ *
+ * @param timing - timing to update
+ * @param timezone - the new IANA timezone
+ * @returns the timing with the new timezone applied
  */
 export declare function updateDateCellTimingToTimezone<T extends DateCellTimingStartsAtEndRange>(timing: T, timezone: TimezoneString): T;
 /**
@@ -338,32 +401,37 @@ export type ShiftDateCellTimingToTimezoneFunction = (<T extends DateCellTimingSt
     readonly _normalInstance: DateTimezoneUtcNormalInstance;
 };
 /**
- * Creates a ChangeDateCellTimingToTimezoneFunction from the input.
+ * Creates a function that shifts a timing's startsAt and end to represent the same "wall clock time" in a new timezone.
+ *
+ * Unlike {@link updateDateCellTimingToTimezoneFunction}, which preserves the absolute instant, this shifts the absolute times
+ * so the local time appearance remains the same (e.g. 8AM UTC becomes 8AM Denver).
  *
- * @param input
- * @returns
+ * @param timezoneInput - the target timezone to shift into
+ * @returns a function that shifts timings into the new timezone
  */
 export declare function shiftDateCellTimingToTimezoneFunction(timezoneInput: DateCellTimingTimezoneInput): ShiftDateCellTimingToTimezoneFunction;
 /**
- * Convenience function for calling shiftDateCellTimingToTimezone() with the system timezone.
+ * Shifts a timing to the system timezone, preserving the wall clock time appearance.
  *
- * @param timing
- * @returns
+ * @param timing - timing to shift
+ * @returns the timing shifted to the system timezone
  */
 export declare function shiftDateCellTimingToSystemTimezone<T extends DateCellTimingStartsAtEndRange>(timing: T): T;
 /**
- * Convenience function for calling shiftDateCellTimingToTimezone() with the UTC timezone.
+ * Shifts a timing to UTC, preserving the wall clock time appearance.
  *
- * @param timing
- * @returns
+ * @param timing - timing to shift
+ * @returns the timing shifted to UTC
  */
 export declare function shiftDateCellTimingToUTCTimezone<T extends DateCellTimingStartsAtEndRange>(timing: T): T;
 /**
- * Convenience function for calling shiftDateCellTimingToTimezoneFunction() and passing the timing.
+ * Shifts a timing to a new timezone, preserving the wall clock time appearance.
  *
- * @param timing
- * @param timezone
- * @returns
+ * Shorthand for creating a {@link shiftDateCellTimingToTimezoneFunction} and immediately invoking it.
+ *
+ * @param timing - timing to shift
+ * @param timezone - the target timezone
+ * @returns the timing shifted to the new timezone
  */
 export declare function shiftDateCellTimingToTimezone<T extends DateCellTimingStartsAtEndRange>(timing: T, timezone: DateCellTimingTimezoneInput): T;
 export interface CalculateExpectedDateCellTimingDurationPair {
@@ -371,33 +439,36 @@ export interface CalculateExpectedDateCellTimingDurationPair {
     readonly expectedFinalStartsAt: Date;
 }
 /**
- * Returns the expected duration from the input.
+ * Calculates the expected duration and the final event's startsAt from a timing range, accounting for DST transitions.
  *
- * @param timing DateCellTimingStartsAtEndRange
- * @returns CalculateExpectedDateCellTimingDurationPair
+ * @param timing - the timing range to analyze
+ * @returns the computed duration in minutes and the expected startsAt of the last event
  */
 export declare function calculateExpectedDateCellTimingDurationPair(timing: DateCellTimingStartsAtEndRange): CalculateExpectedDateCellTimingDurationPair;
 /**
- * Returns the duration calculated from the input.
+ * Calculates the expected event duration in minutes from a timing range by analyzing the gap between startsAt and end.
  *
- * @param timing DateCellTimingStartsAtEndRange
- * @returns Minutes
+ * @param timing - the timing range to analyze
+ * @returns the duration in minutes
  */
 export declare function calculateExpectedDateCellTimingDuration(timing: DateCellTimingStartsAtEndRange): Minutes;
 /**
- * Creates a DateCellTiming from the input timing by using calculateExpectedDateCellTimingDuration()
+ * Converts a {@link DateCellTimingStartsAtEndRange} to a full {@link DateCellTiming} by computing the duration from the range.
  *
- * @param timing DateCellTimingStartsAtEndRange
- * @returns DateCellTiming
+ * @param timing - the starts-at/end range to convert
+ * @returns a DateCellTiming with the calculated duration
  */
 export declare function dateCellTimingFromDateCellTimingStartsAtEndRange(timing: DateCellTimingStartsAtEndRange): DateCellTiming;
 /**
- * Returns the final StartsAt time.
+ * Computes the startsAt time and duration for the final event in a timing range.
  *
- * @param timing DateCellTimingStartsAtEndRange
- * @returns DateCellTimingEvent
+ * @param timing - the timing range to analyze
+ * @returns a DateCellTimingEvent representing the last scheduled event
  */
 export declare function dateCellTimingFinalStartsAtEvent(timing: DateCellTimingStartsAtEndRange): DateCellTimingEvent;
+/**
+ * Detailed validation result for a {@link DateCellTiming}, with individual boolean flags for each validation rule.
+ */
 export interface IsValidDateCellTimingInfo {
     readonly isValid: boolean;
     readonly startsAtHasZeroSeconds: boolean;
@@ -407,14 +478,27 @@ export interface IsValidDateCellTimingInfo {
     readonly isExpectedValidEnd: boolean;
     readonly normalInstance: DateTimezoneUtcNormalInstance;
 }
+/**
+ * Performs detailed validation of a {@link DateCellTiming}, returning an info object with individual check results.
+ *
+ * Validates that end is after startsAt, duration is within bounds, startsAt has no fractional seconds, and the computed duration matches the expected value.
+ *
+ * @param timing - the timing to validate
+ * @returns detailed validation info with individual boolean flags
+ */
 export declare function isValidDateCellTimingInfo(timing: DateCellTiming): IsValidDateCellTimingInfo;
 /**
- * Convenience function for checking whether or not DateCellTiming is valid.
+ * Returns true if the {@link DateCellTiming} passes all validation checks.
  *
- * @param timing
- * @returns
+ * Shorthand for {@link isValidDateCellTimingInfo} when only the boolean result is needed.
+ *
+ * @param timing - the timing to validate
+ * @returns whether the timing is valid
  */
 export declare function isValidDateCellTiming(timing: DateCellTiming): boolean;
+/**
+ * Extended validation result for a {@link FullDateCellTiming}, adding checks for the derived `start` date alignment.
+ */
 export interface IsValidFullDateCellTimingInfo extends IsValidDateCellTimingInfo {
     readonly isStartRoundedToSeconds: boolean;
     readonly startIsAtMidnight: boolean;
@@ -422,5 +506,20 @@ export interface IsValidFullDateCellTimingInfo extends IsValidDateCellTimingInfo
     readonly startsAtIsAfterStart: boolean;
     readonly startsAtIsLessThan24HoursAfterStart: boolean;
 }
+/**
+ * Performs detailed validation of a {@link FullDateCellTiming}, including all {@link isValidDateCellTimingInfo} checks
+ * plus additional checks that the `start` date is at midnight and properly aligned with `startsAt`.
+ *
+ * @param timing - the full timing to validate
+ * @returns detailed validation info with individual boolean flags
+ */
 export declare function isValidFullDateCellTimingInfo(timing: FullDateCellTiming): IsValidFullDateCellTimingInfo;
+/**
+ * Returns true if the {@link FullDateCellTiming} passes all validation checks, including start date alignment.
+ *
+ * Shorthand for {@link isValidFullDateCellTimingInfo} when only the boolean result is needed.
+ *
+ * @param timing - the full timing to validate
+ * @returns whether the timing is valid
+ */
 export declare function isValidFullDateCellTiming(timing: FullDateCellTiming): boolean;