@dereekb/date 13.4.0 → 13.4.1

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>;

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

@@ -57,6 +57,9 @@ export interface DateTimezoneConversionConfig {
  * isValidDateTimezoneConversionConfig({ timezone: 'America/Chicago' }); // true
  * isValidDateTimezoneConversionConfig({}); // false
  * ```
+ *
+ * @param input - the conversion config to validate
+ * @returns true if the config has at least one meaningful conversion property set
  */
 export declare function isValidDateTimezoneConversionConfig(input: DateTimezoneConversionConfig): boolean;
 /**
@@ -74,6 +77,10 @@ export type DateTimezoneConversionConfigUseSystemTimezone = {
  * isSameDateTimezoneConversionConfig({ timezone: 'UTC' }, { timezone: undefined }); // true
  * isSameDateTimezoneConversionConfig({ useSystemTimezone: true }, { timezone: 'America/Denver' }); // false
  * ```
+ *
+ * @param a - first conversion config to compare
+ * @param b - second conversion config to compare
+ * @returns true if both configs are logically equivalent
  */
 export declare function isSameDateTimezoneConversionConfig(a: DateTimezoneConversionConfig, b: DateTimezoneConversionConfig): boolean;
 /**
@@ -91,6 +98,7 @@ export declare function isSameDateTimezoneConversionConfig(a: DateTimezoneConver
  * ```
  *
  * @param date - required to determine the correct offset for that instant (DST-aware)
+ * @returns the system timezone UTC offset in milliseconds
  */
 export declare function getCurrentSystemOffsetInMs(date: Date): Milliseconds;
 /**
@@ -103,6 +111,7 @@ export declare function getCurrentSystemOffsetInMs(date: Date): Milliseconds;
  * ```
  *
  * @param date - required to determine the correct offset for that instant (DST-aware)
+ * @returns the system timezone UTC offset truncated to whole hours
  */
 export declare function getCurrentSystemOffsetInHours(date: Date): Hours;
 /**
@@ -118,6 +127,7 @@ export declare function getCurrentSystemOffsetInHours(date: Date): Hours;
  * ```
  *
  * @param date - required to determine the correct offset for that instant (DST-aware)
+ * @returns the system timezone UTC offset in minutes
  */
 export declare function getCurrentSystemOffsetInMinutes(date: Date): Minutes;
 /**
@@ -137,6 +147,7 @@ export declare function getCurrentSystemOffsetInMinutes(date: Date): Minutes;
  *
  * @param timezone - IANA timezone string (e.g. 'America/New_York')
  * @param date - the instant to evaluate, since DST may shift the offset
+ * @returns the UTC offset for the given timezone at the given instant, in milliseconds
  */
 export declare function calculateTimezoneOffset(timezone: TimezoneString, date: Date): Milliseconds;
 export type DateTimezoneConversionTarget = 'target' | 'base' | 'system';
@@ -194,6 +205,15 @@ export type DateTimezoneConversionMap<T = number> = {
     [key: string]: T;
 };
 export type DateTimezoneConversionFunction<T> = MapFunction<Milliseconds, T>;
+/**
+ * Calculates offset values for every pair of conversion targets (target, base, system)
+ * and returns them as a keyed map (e.g. `'target-base'`, `'base-system'`).
+ *
+ * @param date - the reference date used to compute offsets
+ * @param converter - the converter instance providing offset calculations
+ * @param map - optional mapping function applied to each raw millisecond offset
+ * @returns a map of conversion-pair keys to their computed offset values
+ */
 export declare function calculateAllConversions<T = number>(date: Date, converter: DateTimezoneBaseDateConverter, map?: DateTimezoneConversionFunction<T>): DateTimezoneConversionMap<T>;
 export type DateTimezoneUtcNormalInstanceInput = Maybe<TimezoneString> | DateTimezoneConversionConfig;
 export type DateTimezoneUtcNormalInstanceTransformType = 'targetDateToBaseDate' | 'targetDateToSystemDate' | 'baseDateToTargetDate' | 'baseDateToSystemDate' | 'systemDateToTargetDate' | 'systemDateToBaseDate';
@@ -205,8 +225,32 @@ export type DateTimezoneUtcNormalInstanceTransformType = 'targetDateToBaseDate'
  * inverseDateTimezoneUtcNormalInstanceTransformType('targetDateToBaseDate'); // 'baseDateToTargetDate'
  * inverseDateTimezoneUtcNormalInstanceTransformType('systemDateToTargetDate'); // 'targetDateToSystemDate'
  * ```
+ *
+ * @param input - the transform type to invert
+ * @returns the inverse transform type for round-trip conversion
  */
 export declare function inverseDateTimezoneUtcNormalInstanceTransformType(input: DateTimezoneUtcNormalInstanceTransformType): DateTimezoneUtcNormalInstanceTransformType;
+/**
+ * Configuration for {@link DateTimezoneUtcNormalInstance.safeMirroredConvertDate}.
+ */
+export interface SafeMirroredConvertDateConfig {
+    /**
+     * The base date. Should have been derived from the originalContextDate using convertDate().
+     */
+    readonly baseDate: BaseDateAsUTC;
+    /**
+     * Original date used to derive the baseDate.
+     */
+    readonly originalContextDate: Date;
+    /**
+     * The "type" of date the originalContextDate is.
+     */
+    readonly contextType: DateTimezoneConversionTarget;
+    /**
+     * Whether to apply safe DST correction. Defaults to true.
+     */
+    readonly safeConvert?: boolean;
+}
 /**
  * Central class for converting dates between the three date spaces (base, target, system).
  *
@@ -244,11 +288,10 @@ export declare class DateTimezoneUtcNormalInstance implements DateTimezoneBaseDa
      * For example, when daylight savings changed on November 3, 2024 the offset returned was 5 but to get back to the original an offset of 6 was required.
      * This is where some contextual data was not being used. This function uses that contextual data to make sure the reverse will be consistent.
      *
-     * @param baseDate The base date. Should have been derived from the originalContextDate using the convertDate() function
-     * @param originalContextDate Original date used to derive the baseDate.
-     * @param fromOrTo the "type" of date the originalContextDate is
+     * @param config - configuration for the safe mirrored conversion
+     * @returns the converted date and the DST offset adjustment applied
      */
-    safeMirroredConvertDate(baseDate: BaseDateAsUTC, originalContextDate: Date, contextType: DateTimezoneConversionTarget, safeConvert?: boolean): {
+    safeMirroredConvertDate(config: SafeMirroredConvertDateConfig): {
         date: Date;
         daylightSavingsOffset: number;
     };
@@ -277,46 +320,50 @@ export declare class DateTimezoneUtcNormalInstance implements DateTimezoneBaseDa
     /**
      * Returns true if the input is midnight in the target timezone.
      *
-     * @param date
+     * @param date - the date to check
+     * @returns true if the date is at the start of the day in the target timezone
      */
     isStartOfDayInTargetTimezone(date: Date): boolean;
     /**
      * Start of the given day in the target timezone.
      *
-     * @param date The input is treated as an instant in time.
+     * @param date - the input is treated as an instant in time
+     * @returns the start-of-day date in the target timezone
      */
     startOfDayInTargetTimezone(date?: Date | ISO8601DayString): Date;
     /**
      * Start of the given day in UTC.
      *
-     * @param date
+     * @param date - the date or ISO8601 day string to get the start of day for
+     * @returns the start of the day as a BaseDateAsUTC
      */
     startOfDayInBaseDate(date?: Date | ISO8601DayString): BaseDateAsUTC;
     /**
      * End of the given day in UTC.
      *
-     * @param date
-     * @returns
+     * @param date - the date or ISO8601 day string to get the end of day for
+     * @returns the end of the day as a BaseDateAsUTC (23:59:59.999)
      */
     endOfDayInBaseDate(date?: Date | ISO8601DayString): BaseDateAsUTC;
     /**
      * Start of the given day for the system.
      *
-     * @param date
-     * @returns
+     * @param date - the date or ISO8601 day string to get the start of day for
+     * @returns the start of the day in the system timezone
      */
     startOfDayInSystemDate(date?: Date | ISO8601DayString): Date;
     /**
      * End of the given day for the system.
      *
-     * @param date
-     * @returns
+     * @param date - the date or ISO8601 day string to get the end of day for
+     * @returns the end of the day in the system timezone
      */
     endOfDayInSystemDate(date?: Date | ISO8601DayString): Date;
     /**
-     * Whether or not the system experiences daylight savings for the given year.
+     * Whether or not the target timezone experiences daylight savings for the given year.
      *
-     * @param year
+     * @param year - the year to check, as a Date or number; defaults to the current year
+     * @returns true if the target timezone has different offsets in January and July
      */
     targetTimezoneExperiencesDaylightSavings(year?: Date | YearNumber): boolean;
     /**
@@ -351,6 +398,8 @@ export type DateTimezoneUtcNormalFunctionInput = DateTimezoneUtcNormalInstanceIn
  * const same = dateTimezoneUtcNormal(denver); // same reference
  * ```
  *
+ * @param config - timezone input: an existing instance, timezone string, millisecond offset, or config object
+ * @returns a DateTimezoneUtcNormalInstance for the given input
  * @throws Error if the input type is not recognized
  */
 export declare function dateTimezoneUtcNormal(config: DateTimezoneUtcNormalFunctionInput): DateTimezoneUtcNormalInstance;
@@ -370,6 +419,8 @@ export declare const UTC_DATE_TIMEZONE_UTC_NORMAL_INSTANCE: DateTimezoneUtcNorma
  *
  * Prefer this over constructing a new instance when you need system-timezone conversions,
  * as the singleton avoids unnecessary allocations.
+ *
+ * @returns the shared system-timezone DateTimezoneUtcNormalInstance singleton
  */
 export declare function systemDateTimezoneUtcNormal(): DateTimezoneUtcNormalInstance;
 /**
@@ -385,6 +436,10 @@ export declare function systemDateTimezoneUtcNormal(): DateTimezoneUtcNormalInst
  * const target = baseDateToTargetDate(base, 'America/Denver');
  * // target is 2024-06-15T14:00:00.000-06:00 (2PM MDT)
  * ```
+ *
+ * @param date - the BaseDateAsUTC to convert
+ * @param timezone - the target IANA timezone string
+ * @returns a real instant in the specified timezone
  */
 export declare function baseDateToTargetDate(date: Date, timezone: Maybe<TimezoneString>): Date;
 /**
@@ -400,32 +455,51 @@ export declare function baseDateToTargetDate(date: Date, timezone: Maybe<Timezon
  * const base = targetDateToBaseDate(target, 'America/Denver');
  * // base is 2024-06-15T14:00:00.000Z — wall-clock 2PM preserved as UTC
  * ```
+ *
+ * @param date - the target-timezone date to convert
+ * @param timezone - the IANA timezone the date is expressed in
+ * @returns a BaseDateAsUTC with wall-clock time preserved as UTC
  */
 export declare function targetDateToBaseDate(date: Date, timezone: Maybe<TimezoneString>): Date;
 /**
  * Converts a {@link BaseDateAsUTC} to a target date in the system's local timezone
  * using the shared system-timezone instance.
+ *
+ * @param date - the BaseDateAsUTC to convert
+ * @returns the date converted to the system's local timezone
  */
 export declare function systemBaseDateToNormalDate(date: Date): BaseDateAsUTC;
 /**
  * Converts a target date in the system's local timezone back to a {@link BaseDateAsUTC}
  * using the shared system-timezone instance.
+ *
+ * @param date - the system-timezone target date to convert back to base
+ * @returns the corresponding BaseDateAsUTC
  */
 export declare function systemNormalDateToBaseDate(date: BaseDateAsUTC): Date;
 /**
  * Returns the millisecond offset needed to convert a {@link BaseDateAsUTC} to a target date
  * in the system's local timezone.
+ *
+ * @param date - the date to compute the offset for
+ * @returns the offset in milliseconds
  */
 export declare function systemBaseDateToNormalDateOffset(date: Date): Milliseconds;
 /**
  * Returns the millisecond offset needed to convert a target date in the system's
  * local timezone back to a {@link BaseDateAsUTC}.
+ *
+ * @param date - the date to compute the offset for
+ * @returns the offset in milliseconds
  */
 export declare function systemNormalDateToBaseDateOffset(date: Date): Milliseconds;
 /**
  * Returns whether the system's local timezone observes daylight saving time in the given year.
  *
  * Compares the offset on January 1 and July 1; if they differ, DST is in effect for part of the year.
+ *
+ * @param year - the year to check, as a Date
+ * @returns true if the system timezone observes DST in the given year
  */
 export declare function systemExperiencesDaylightSavings(year: Date): boolean;
 /**
@@ -450,7 +524,9 @@ export type TransformDateInTimezoneNormalFunction = ((date: Date, transform: Map
  * const result = fn(someDate, (d) => startOfDay(d));
  * ```
  *
+ * @param timezoneInput - timezone configuration for the conversion
  * @param transformType - defaults to `'systemDateToTargetDate'`
+ * @returns a function that transforms dates within the specified timezone normalization
  */
 export declare function transformDateInTimezoneNormalFunction(timezoneInput: DateTimezoneUtcNormalFunctionInput, transformType?: DateTimezoneUtcNormalInstanceTransformType): TransformDateInTimezoneNormalFunction;
 /**
@@ -465,7 +541,9 @@ export type TransformDateRangeToTimezoneFunction = TransformDateRangeDatesFuncti
  * Creates a {@link TransformDateRangeToTimezoneFunction} that converts both dates in
  * a {@link DateRange} using the specified transform type.
  *
+ * @param timezoneInput - timezone configuration for the conversion
  * @param transformType - defaults to `'systemDateToTargetDate'`
+ * @returns a function that converts DateRange dates using the specified transform
  */
 export declare function transformDateRangeToTimezoneFunction(timezoneInput: DateTimezoneUtcNormalFunctionInput, transformType?: DateTimezoneUtcNormalInstanceTransformType): TransformDateRangeToTimezoneFunction;
 /**
@@ -481,7 +559,9 @@ export type TransformDateRangeInTimezoneNormalFunction = ((dateRange: DateRange,
  * Creates a {@link TransformDateRangeInTimezoneNormalFunction} that converts a date range
  * into the specified date space, applies a user-provided range transformation, then converts back.
  *
+ * @param timezoneInput - timezone configuration for the conversion
  * @param transformType - defaults to `'systemDateToTargetDate'`
+ * @returns a function that transforms date ranges within the specified timezone normalization
  */
 export declare function transformDateRangeInTimezoneNormalFunction(timezoneInput: DateTimezoneUtcNormalFunctionInput, transformType?: DateTimezoneUtcNormalInstanceTransformType): TransformDateRangeInTimezoneNormalFunction;
 /**
@@ -498,6 +578,9 @@ export type StartOfDayInTimezoneDayStringFactory = (day: ISO8601DayString) => Da
  * const midnight = startOfDayInDenver('2024-06-15');
  * // midnight is 2024-06-15T06:00:00.000Z (midnight MDT = 6AM UTC)
  * ```
+ *
+ * @param timezone - timezone configuration to bind the factory to
+ * @returns a factory that converts ISO8601 day strings to start-of-day dates
  */
 export declare function startOfDayInTimezoneDayStringFactory(timezone?: DateTimezoneUtcNormalFunctionInput): StartOfDayInTimezoneDayStringFactory;
 /**
@@ -509,6 +592,10 @@ export declare function startOfDayInTimezoneDayStringFactory(timezone?: DateTime
  * ```ts
  * const midnight = startOfDayInTimezoneFromISO8601DayString('2024-06-15', 'America/Denver');
  * ```
+ *
+ * @param day - the ISO8601 day string to parse
+ * @param timezone - timezone configuration for the start-of-day calculation
+ * @returns the start-of-day instant in the given timezone
  */
 export declare function startOfDayInTimezoneFromISO8601DayString(day: ISO8601DayString, timezone?: DateTimezoneUtcNormalFunctionInput): Date;
 export interface SetOnDateWithTimezoneNormalFunctionInput {
@@ -582,6 +669,9 @@ export type SetOnDateWithTimezoneNormalFunction = ((input: SetOnDateWithTimezone
  * const result = setOnDate({ date: someDate, hours: 14, minutes: 30, inputType: 'target' });
  * // result is someDate with hours set to 14:30 in Denver time
  * ```
+ *
+ * @param timezone - the timezone configuration to bind to
+ * @returns a function that sets hours/minutes on dates in the given timezone
  */
 export declare function setOnDateWithTimezoneNormalFunction(timezone: DateTimezoneUtcNormalFunctionInput): SetOnDateWithTimezoneNormalFunction;
 /**
@@ -591,6 +681,7 @@ export declare function setOnDateWithTimezoneNormalFunction(timezone: DateTimezo
  *
  * @param input - the date whose day is preserved
  * @param timezone - the timezone context for the hour/minute interpretation
+ * @returns the input date with hours and minutes set to the current time in the given timezone
  */
 export declare function copyHoursAndMinutesFromNowWithTimezoneNormal(input: Date, timezone: DateTimezoneUtcNormalFunctionInput): Date;
 /**
@@ -610,5 +701,6 @@ export declare function copyHoursAndMinutesFromNowWithTimezoneNormal(input: Date
  * @param input - the date whose day is preserved
  * @param copyFrom - the date (or `'now'`) whose hours/minutes are copied
  * @param timezone - the timezone context for interpreting both dates
+ * @returns the input date with hours and minutes copied from the source
  */
 export declare function copyHoursAndMinutesFromDateWithTimezoneNormal(input: Date, copyFrom: LogicalDate, timezone: DateTimezoneUtcNormalFunctionInput): Date;

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

@@ -118,6 +118,9 @@ export declare function yearWeekCodeDateTimezoneInstance(input: YearWeekCodeDate
 /**
  * Computes the {@link YearWeekCode} from a Date (using system timezone) or from explicit year and week values.
  *
+ * @param date - the date to compute the week code for
+ * @returns the encoded year+week code
+ *
  * @example
  * ```ts
  * yearWeekCode(new Date('2024-04-15')); // 202416
@@ -158,6 +161,7 @@ export declare function yearWeekCodeForDateRange(dateRange: DateRange): YearWeek
  *
  * @param dateRange - the range to compute week codes for
  * @param dateRangeTimezone - the timezone context for accurate week boundary calculation
+ * @returns an array of YearWeekCode values covering the range
  */
 export declare function yearWeekCodeForDateRangeInTimezone(dateRange: DateRange, dateRangeTimezone: YearWeekCodeDateTimezoneInput): YearWeekCode[];
 /**
@@ -175,6 +179,7 @@ export type YearWeekCodeForCalendarMonthFactory = (date: Date) => YearWeekCode[]
  * Returns all {@link YearWeekCode} values for the calendar month containing the given date, using the system timezone.
  *
  * @param date - a date within the target month
+ * @returns an array of YearWeekCode values for the month
  */
 export declare function yearWeekCodeForCalendarMonth(date: Date): YearWeekCode[];
 /**

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

@@ -4,7 +4,6 @@ export * from './date.cell.index';
 export * from './date.cell.schedule';
 export * from './date.cell.schedule.day';
 export * from './date.cell';
-export * from './date.cell.validator';
 export * from './date.cell.week';
 export * from './date.calendar';
 export * from './date.duration';

package/src/lib/query/query.builder.mongo.d.ts

@@ -5,11 +5,17 @@ import { type DateQueryBuilder } from './query.builder';
  * used by {@link makeMongoDBLikeDateQueryBuilder} to produce query filters.
  */
 export interface TimeFieldsNameSet {
-    /** Field name storing the start (or combined start+end) timestamp. */
+    /**
+     * Field name storing the start (or combined start+end) timestamp.
+     */
     start: string;
-    /** Field name storing the end timestamp. Ignored when `singleFieldForStartAndEnd` is true. */
+    /**
+     * Field name storing the end timestamp. Ignored when `singleFieldForStartAndEnd` is true.
+     */
     end?: string;
-    /** When true, a single field represents both start and end so range bounds are merged. */
+    /**
+     * When true, a single field represents both start and end so range bounds are merged.
+     */
     singleFieldForStartAndEnd?: boolean;
 }
 /**