@dereekb/date 13.0.7 → 13.1.0

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

@@ -1,115 +1,407 @@
 import { type DayOfWeekNameFunction, type DateOrDateString, type ISO8601DateString, type Maybe, type Minutes, type Seconds, type TimezoneString, type ArrayOrValue, type MapFunction, type ISO8601DateStringUTCFull, type UTCDateString, type DayOfWeek, type UnixDateTimeMillisecondsNumber, type DateOrUnixDateTimeMillisecondsNumber, type DateHourMinuteOrSecond, type FloorOrCeilRounding } from '@dereekb/util';
+/**
+ * Sentinel date representing the maximum future date (January 1, 9999 UTC).
+ *
+ * Used as a placeholder for "no expiration" or "indefinite" scenarios.
+ */
 export declare const MAX_FUTURE_DATE: Date;
 /**
- * Reads a date from the input value
+ * Extracts a Date from an arbitrary input value.
  */
 export type ReadDateFunction<T> = MapFunction<T, Date>;
 /**
- * Reads a ISO8601DateStringUTCFull value from the input value.
+ * Extracts an ISO8601 UTC full date string from an arbitrary input value.
  */
 export type ReadISO8601DateStringUTCFullFunction<T> = MapFunction<T, ISO8601DateStringUTCFull>;
 /**
- * Returns true if the input is a date.
+ * Type guard that checks whether the input is a Date instance.
+ *
+ * @param input - value to check
+ * @returns whether the input is a Date
  *
- * @param input
- * @returns
+ * @example
+ * ```ts
+ * isDate(new Date()); // true
+ * isDate('2020-01-01'); // false
+ * ```
  */
 export declare function isDate(input: unknown): input is Date;
+/**
+ * Converts milliseconds to minutes.
+ *
+ * @param milliseconds - duration in milliseconds
+ * @returns equivalent duration in minutes
+ *
+ * @example
+ * ```ts
+ * msToMinutes(60000); // 1
+ * msToMinutes(120000); // 2
+ * ```
+ */
 export declare function msToMinutes(milliseconds: number): Minutes;
+/**
+ * Converts milliseconds to seconds.
+ *
+ * @param milliseconds - duration in milliseconds
+ * @returns equivalent duration in seconds
+ *
+ * @example
+ * ```ts
+ * msToSeconds(1000); // 1
+ * msToSeconds(2500); // 2.5
+ * ```
+ */
 export declare function msToSeconds(milliseconds: number): Seconds;
+/**
+ * Converts hours to milliseconds.
+ *
+ * @param hours - number of hours (defaults to 1)
+ * @returns equivalent duration in milliseconds
+ *
+ * @example
+ * ```ts
+ * hoursToMs(1); // 3600000
+ * hoursToMs(2); // 7200000
+ * ```
+ */
 export declare function hoursToMs(hours?: number): Minutes;
+/**
+ * Converts minutes to milliseconds.
+ *
+ * @param minutes - number of minutes (defaults to 1)
+ * @returns equivalent duration in milliseconds
+ *
+ * @example
+ * ```ts
+ * minutesToMs(1); // 60000
+ * minutesToMs(5); // 300000
+ * ```
+ */
 export declare function minutesToMs(minutes?: number): Minutes;
+/**
+ * Converts days to minutes.
+ *
+ * @param days - number of days (defaults to 1)
+ * @returns equivalent duration in minutes
+ *
+ * @example
+ * ```ts
+ * daysToMinutes(1); // 1440
+ * daysToMinutes(7); // 10080
+ * ```
+ */
 export declare function daysToMinutes(days?: number): Minutes;
+/**
+ * Returns the {@link MAX_FUTURE_DATE} sentinel value (January 1, 9999 UTC).
+ *
+ * Useful as a default for "no expiration" comparisons.
+ *
+ * @example
+ * ```ts
+ * const futureDate = maxFutureDate();
+ * // futureDate === MAX_FUTURE_DATE
+ * ```
+ */
 export declare function maxFutureDate(): Date;
+/**
+ * Checks whether the given date matches the {@link MAX_FUTURE_DATE} sentinel.
+ *
+ * @param date - date to check
+ * @returns whether the date is the max future sentinel
+ *
+ * @example
+ * ```ts
+ * isMaxFutureDate(MAX_FUTURE_DATE); // true
+ * isMaxFutureDate(new Date()); // false
+ * ```
+ */
 export declare function isMaxFutureDate(date: Date): boolean;
+/**
+ * Returns the start of the current minute for the given time, effectively truncating seconds and milliseconds.
+ *
+ * Defaults to the current time if no input is provided.
+ *
+ * @param time - date to truncate (defaults to now)
+ * @returns date rounded down to the start of the minute
+ *
+ * @example
+ * ```ts
+ * const date = new Date('2024-01-01T12:30:45.123Z');
+ * const result = latestMinute(date);
+ * // result === 2024-01-01T12:30:00.000Z
+ * ```
+ */
 export declare function latestMinute(time?: Date): Date;
+/**
+ * Converts the input to an ISO 8601 date string.
+ *
+ * @param input - date or date string to convert
+ * @returns the ISO 8601 string representation
+ * @throws {Error} When the input cannot be parsed as a valid date.
+ *
+ * @example
+ * ```ts
+ * toISODateString(new Date('2024-01-01T00:00:00.000Z'));
+ * // '2024-01-01T00:00:00.000Z'
+ * ```
+ */
 export declare function toISODateString(input: DateOrDateString): ISO8601DateString;
 /**
- * Guesses the current system's timezone.
+ * Guesses the current system's timezone using the Intl API.
+ *
+ * @returns the IANA timezone string (e.g. "America/Chicago"), or undefined if detection fails
  *
- * @returns
+ * @example
+ * ```ts
+ * const tz = guessCurrentTimezone();
+ * // tz === 'America/New_York' (or similar)
+ * ```
  */
 export declare function guessCurrentTimezone(): TimezoneString | undefined;
 /**
- * Convenience function for getCurrentTimezone() that asserts a timezone is returned.
+ * Returns the current system's timezone, throwing if detection fails.
  *
- * @returns
+ * Convenience wrapper around {@link guessCurrentTimezone} for contexts where a timezone is required.
+ *
+ * @returns the IANA timezone string
+ * @throws {Error} When the timezone cannot be detected from the Intl API.
+ *
+ * @example
+ * ```ts
+ * const tz = requireCurrentTimezone();
+ * // tz === 'America/New_York' (guaranteed non-undefined)
+ * ```
  */
 export declare function requireCurrentTimezone(): TimezoneString;
+/**
+ * Null-safe variant of {@link toJsDate} that returns undefined for null/undefined input.
+ *
+ * @param input - date, date string, or null/undefined
+ * @returns the parsed Date or undefined if input was nullish
+ *
+ * @example
+ * ```ts
+ * safeToJsDate('2024-01-01T00:00:00.000Z'); // Date instance
+ * safeToJsDate(undefined); // undefined
+ * ```
+ */
 export declare function safeToJsDate(input: Maybe<DateOrDateString | UTCDateString>): Maybe<Date>;
 /**
- * Converts the input DateOrDateString to a Date value.
+ * Converts the input to a JavaScript Date instance. Accepts Date objects, ISO 8601 strings, UTC date strings, and unix millisecond timestamps.
+ *
+ * @param input - value to convert
+ * @returns the parsed Date
  *
- * @param input
- * @returns
+ * @example
+ * ```ts
+ * toJsDate('2024-01-01T00:00:00.000Z'); // Date instance
+ * toJsDate(new Date()); // same Date returned
+ * toJsDate(1704067200000); // Date from unix ms
+ * ```
  */
 export declare function toJsDate(input: DateOrDateString | UTCDateString | UnixDateTimeMillisecondsNumber): Date;
+/**
+ * Parses a date string or unix milliseconds timestamp into a Date, returning undefined if the result is invalid.
+ *
+ * Prefers `parseISO` for ISO 8601 strings to avoid browser inconsistencies with `new Date()`.
+ *
+ * @param input - ISO 8601 string, UTC date string, or unix milliseconds
+ * @returns the parsed Date, or undefined if invalid
+ *
+ * @example
+ * ```ts
+ * parseJsDateString('2020-04-30T00:00:00.000'); // Date instance
+ * parseJsDateString('Sat, 03 Feb 2001 04:05:06 GMT'); // Date instance
+ * parseJsDateString('not-a-date'); // undefined
+ * ```
+ */
 export declare function parseJsDateString(input: ISO8601DateString | UTCDateString | UnixDateTimeMillisecondsNumber): Maybe<Date>;
 /**
- * Returns the earliest date from the input array.
+ * Returns the earliest (minimum) date from the input array, ignoring null/undefined entries.
+ *
+ * @param dates - array of dates that may contain null/undefined
+ * @param defaultDate - fallback if no valid dates exist
+ * @returns the earliest date, or the default if the array has no valid dates
+ *
+ * @example
+ * ```ts
+ * const a = new Date('2024-01-01');
+ * const b = new Date('2024-06-01');
+ * earliestDate([a, b]); // a
+ * earliestDate([null, undefined], new Date()); // falls back to default
+ * ```
  */
 export declare function earliestDate(dates: Maybe<Date>[]): Maybe<Date>;
 export declare function earliestDate(dates: Maybe<Date>[], defaultDate: Date): Date;
 /**
- * Returns the latest date from the input array.
+ * Returns the latest (maximum) date from the input array, ignoring null/undefined entries.
+ *
+ * @param dates - array of dates that may contain null/undefined
+ * @param defaultDate - fallback if no valid dates exist
+ * @returns the latest date, or the default if the array has no valid dates
+ *
+ * @example
+ * ```ts
+ * const a = new Date('2024-01-01');
+ * const b = new Date('2024-06-01');
+ * latestDate([a, b]); // b
+ * latestDate([null], new Date()); // falls back to default
+ * ```
  */
 export declare function latestDate(dates: Maybe<Date>[]): Maybe<Date>;
 export declare function latestDate(dates: Maybe<Date>[], defaultDate: Date): Date;
 /**
- * Returns true if a and b are defined and a is after b, otherwise returns the default value.
+ * Null-safe date comparison that returns true when `a` is chronologically after `b`.
+ *
+ * If either date is null/undefined, returns the default value instead.
+ *
+ * @param a - first date
+ * @param b - second date to compare against
+ * @param defaultValue - returned when either date is nullish
+ * @returns whether `a` is after `b`, or the default
+ *
+ * @example
+ * ```ts
+ * const jan = new Date('2024-01-01');
+ * const feb = new Date('2024-02-01');
+ * isAfter(feb, jan); // true
+ * isAfter(null, jan); // undefined
+ * isAfter(null, jan, false); // false
+ * ```
  */
 export declare function isAfter(a: Maybe<Date>, b: Maybe<Date>): Maybe<boolean>;
 export declare function isAfter(a: Maybe<Date>, b: Maybe<Date>, defaultValue: boolean): boolean;
 /**
- * Returns true if a and b are defined and a is before b, otherwise returns the default value.
+ * Null-safe date comparison that returns true when `a` is chronologically before `b`.
+ *
+ * If either date is null/undefined, returns the default value instead.
+ *
+ * @param a - first date
+ * @param b - second date to compare against
+ * @param defaultValue - returned when either date is nullish
+ * @returns whether `a` is before `b`, or the default
+ *
+ * @example
+ * ```ts
+ * const jan = new Date('2024-01-01');
+ * const feb = new Date('2024-02-01');
+ * isBefore(jan, feb); // true
+ * isBefore(null, feb); // undefined
+ * isBefore(null, feb, false); // false
+ * ```
  */
 export declare function isBefore(a: Maybe<Date>, b: Maybe<Date>): Maybe<boolean>;
 export declare function isBefore(a: Maybe<Date>, b: Maybe<Date>, defaultValue: boolean): boolean;
 /**
- * Returns true if both a and b are defined and a is equal to b, otherwise returns the default value.
+ * Null-safe exact date equality check (millisecond precision).
  *
- * The default value is true if a and b are null/undefined.
+ * When both dates are null/undefined and no default is provided, returns true (treating two absent values as equal).
  *
- * @param a
- * @param b
+ * @param a - first date
+ * @param b - second date
+ * @param defaultValue - returned when either date is nullish (defaults to `a == b` if not provided)
+ * @returns whether the dates are exactly equal
+ *
+ * @example
+ * ```ts
+ * const d = new Date('2024-01-01T00:00:00.000Z');
+ * isSameDate(d, new Date(d.getTime())); // true
+ * isSameDate(null, null); // true
+ * isSameDate(null, d); // false
+ * ```
  */
 export declare function isSameDate(a: Maybe<Date>, b: Maybe<Date>): boolean;
 export declare function isSameDate(a: Maybe<Date>, b: Maybe<Date>, defaultValue: boolean): boolean;
 export declare function isSameDate(a: Maybe<Date>, b: Maybe<Date>, defaultValue: Maybe<boolean>): Maybe<boolean>;
 /**
- * Returns true if both a and b are the same time down to the rounded down minute.
+ * Null-safe date equality check that compares only down to the minute (ignoring seconds and milliseconds).
+ *
+ * Rounds both dates down to the start of their respective minutes before comparing.
  *
- * @param a
- * @param b
+ * @param a - first date
+ * @param b - second date
+ * @param defaultValue - returned when either date is nullish
+ * @returns whether both dates fall within the same minute
+ *
+ * @example
+ * ```ts
+ * const a = new Date('2024-01-01T12:30:00.000Z');
+ * const b = new Date('2024-01-01T12:30:45.999Z');
+ * isSameDateHoursAndMinutes(a, b); // true
+ * ```
  */
 export declare function isSameDateHoursAndMinutes(a: Maybe<Date>, b: Maybe<Date>): boolean;
 export declare function isSameDateHoursAndMinutes(a: Maybe<Date>, b: Maybe<Date>, defaultValue: boolean): boolean;
 export declare function isSameDateHoursAndMinutes(a: Maybe<Date>, b: Maybe<Date>, defaultValue: Maybe<boolean>): Maybe<boolean>;
 /**
- * Returns true if both a and b are defined and a is on the same day/month/year as b, otherwise returns the default value.
+ * Null-safe day-level date equality check (same year, month, and day, ignoring time).
+ *
+ * When both dates are null/undefined and no default is provided, returns true (treating two absent values as equal).
  *
- * The default value is true if a and b are null/undefined.
+ * @param a - first date
+ * @param b - second date
+ * @param defaultValue - returned when either date is nullish
+ * @returns whether both dates fall on the same calendar day
  *
- * @param a
- * @param b
+ * @example
+ * ```ts
+ * const morning = new Date('2024-01-01T08:00:00.000Z');
+ * const evening = new Date('2024-01-01T20:00:00.000Z');
+ * isSameDateDay(morning, evening); // true
+ * isSameDateDay(null, null); // true
+ * ```
  */
 export declare function isSameDateDay(a: Maybe<Date>, b: Maybe<Date>): boolean;
 export declare function isSameDateDay(a: Maybe<Date>, b: Maybe<Date>, defaultValue: boolean): boolean;
 export declare function isSameDateDay(a: Maybe<Date>, b: Maybe<Date>, defaultValue: Maybe<boolean>): Maybe<boolean>;
 /**
- * Converts the input date to represent the "day" represented in the time.
+ * Converts a local date to a UTC date representing the same calendar day at midnight.
+ *
+ * Useful for normalizing dates to UTC day boundaries when comparing calendar days across timezones.
  *
- * For example, 1/1/2021 should be represented as a UTC-offset date for 1/1/2021 for the first instant of the day.
+ * @param date - local date to convert
+ * @returns a UTC Date at midnight for the same calendar day
+ *
+ * @example
+ * ```ts
+ * const local = new Date(2021, 0, 1, 15, 30); // Jan 1, 2021 3:30 PM local
+ * const utcDay = utcDayForDate(local);
+ * // utcDay === 2021-01-01T00:00:00.000Z
+ * ```
  */
 export declare function utcDayForDate(date: Date): Date;
 /**
- * Creates a new date using UTC and copies the hours/minutes from the input date using the UTC values to the target date.
+ * Creates a new UTC date by copying the UTC hours and minutes from `fromDate` onto the `target` date's UTC year/month/day.
+ *
+ * Optionally zeroes out seconds and milliseconds when `roundDownToMinute` is true.
+ *
+ * @param target - date providing the UTC year/month/day
+ * @param fromDate - date providing the UTC hours/minutes
+ * @param roundDownToMinute - whether to zero out seconds and milliseconds
+ * @returns a new UTC Date combining the target's day with the source's time
+ *
+ * @example
+ * ```ts
+ * const target = new Date('2024-03-15T00:00:00.000Z');
+ * const source = new Date('2024-01-01T14:30:45.000Z');
+ * const result = copyHoursAndMinutesFromUTCDate(target, source, true);
+ * // result === 2024-03-15T14:30:00.000Z
+ * ```
  */
 export declare function copyHoursAndMinutesFromUTCDate(target: Date, fromDate: Date, roundDownToMinute?: boolean): Date;
 /**
- * Creates a new date and copies the hours/minutes from the input onto the target date, if provided. Defaults to now/today otherwise.
+ * Sets the hours and optionally minutes on a target date (defaults to now), with optional rounding to strip seconds/milliseconds.
  *
- * Also rounds the seconds and milliseconds.
+ * @param config - hours, optional minutes, and rounding options
+ * @param target - date to modify (defaults to the current date/time)
+ * @returns a new Date with the specified time values applied
+ *
+ * @example
+ * ```ts
+ * const target = new Date('2024-01-01T00:00:00.000Z');
+ * const result = copyHoursAndMinutesToDate({ hours: 14, minutes: 30 }, target);
+ * // result has hours=14, minutes=30, seconds=0, milliseconds=0
+ * ```
  */
 export declare function copyHoursAndMinutesToDate({ hours, minutes, removeSeconds, roundDownToMinute }: {
     hours: number;
@@ -117,65 +409,200 @@ export declare function copyHoursAndMinutesToDate({ hours, minutes, removeSecond
     removeSeconds?: boolean;
     roundDownToMinute?: boolean;
 }, target?: Maybe<Date>): Date;
+/**
+ * Alias for {@link copyHoursAndMinutesToDate}.
+ */
 export declare const copyHoursAndMinutesToToday: typeof copyHoursAndMinutesToDate;
 /**
- * Removes the seconds and milliseconds from the input date, or returns the current date with no seconds or milliseconds.
+ * Truncates seconds and milliseconds from the input date, effectively rounding down to the start of the minute.
+ *
+ * @param date - date to round (defaults to now)
+ * @returns the date with seconds and milliseconds set to zero
+ *
+ * @example
+ * ```ts
+ * const date = new Date('2024-01-01T12:30:45.123Z');
+ * roundDownToMinute(date); // 2024-01-01T12:30:00.000Z
+ * ```
  */
 export declare function roundDownToMinute(date?: Date): Date;
 /**
- * Removes the minutes, seconds and milliseconds from the input date, or returns the current date with no mkinutes, seconds or milliseconds.
+ * Truncates minutes, seconds, and milliseconds from the input date, effectively rounding down to the start of the hour.
+ *
+ * @param date - date to round (defaults to now)
+ * @returns the date with minutes, seconds, and milliseconds set to zero
+ *
+ * @example
+ * ```ts
+ * const date = new Date('2024-01-01T12:30:45.123Z');
+ * roundDownToHour(date); // 2024-01-01T12:00:00.000Z
+ * ```
  */
 export declare function roundDownToHour(date?: Date): Date;
+/**
+ * Convenience function that rounds a date down (floor) to the specified unit.
+ *
+ * @param date - date to round
+ * @param roundToUnit - time unit to round to ('hour', 'minute', or 'second')
+ * @returns a new Date rounded down to the unit boundary
+ */
 export declare function roundDateDownTo(date: Date, roundToUnit: DateHourMinuteOrSecond): Date;
+/**
+ * Rounds a date or unix timestamp to the nearest unit boundary using the specified rounding direction.
+ *
+ * Preserves the input type: Date inputs return Date, number inputs return number.
+ *
+ * @param date - date or unix millisecond timestamp to round
+ * @param roundToUnit - time unit to round to ('hour', 'minute', or 'second')
+ * @param roundType - rounding direction ('floor' or 'ceil', defaults to 'floor')
+ * @returns the rounded value in the same type as the input
+ */
 export declare function roundDateTo(date: Date, roundToUnit: DateHourMinuteOrSecond, roundType?: FloorOrCeilRounding): Date;
 export declare function roundDateTo(unixDateTimeNumber: UnixDateTimeMillisecondsNumber, roundToUnit: DateHourMinuteOrSecond, roundType?: FloorOrCeilRounding): UnixDateTimeMillisecondsNumber;
+/**
+ * Rounds a date or unix timestamp to the nearest unit boundary, always returning a Date.
+ *
+ * @param date - date or unix millisecond timestamp to round
+ * @param roundToUnit - time unit to round to ('hour', 'minute', or 'second')
+ * @param roundType - rounding direction ('floor' or 'ceil', defaults to 'floor')
+ * @returns a new Date rounded to the unit boundary
+ *
+ * @example
+ * ```ts
+ * const date = new Date('2024-01-01T01:05:07.123Z');
+ * roundDateToDate(date, 'hour', 'floor'); // 2024-01-01T01:00:00.000Z
+ * roundDateToDate(date, 'minute', 'ceil'); // 2024-01-01T01:06:00.000Z
+ * ```
+ */
 export declare function roundDateToDate(date: DateOrUnixDateTimeMillisecondsNumber, roundToUnit: DateHourMinuteOrSecond, roundType?: FloorOrCeilRounding): Date;
 /**
- * Rounds the input Date value down to the nearest hour, minute, or second.
+ * Rounds a date or unix timestamp to the nearest hour, minute, or second boundary using pure arithmetic on the millisecond value.
+ *
+ * This approach avoids DST issues that can occur with date-fns `set()` or native `Date.setMinutes()`, which may produce
+ * incorrect results during fall-back transitions.
  *
- * @param date
- * @param roundToUnit
- * @param roundType
- * @returns
+ * @param date - date or unix millisecond timestamp to round
+ * @param roundToUnit - time unit to round to ('hour', 'minute', or 'second')
+ * @param roundType - rounding direction ('floor' truncates, 'ceil' rounds up)
+ * @returns the rounded unix millisecond timestamp
+ *
+ * @example
+ * ```ts
+ * const date = new Date('2024-01-01T01:05:07.123Z');
+ * roundDateToUnixDateTimeNumber(date, 'hour', 'floor'); // ms for 2024-01-01T01:00:00.000Z
+ * roundDateToUnixDateTimeNumber(date, 'minute', 'ceil'); // ms for 2024-01-01T01:06:00.000Z
+ * ```
  */
 export declare function roundDateToUnixDateTimeNumber(date: DateOrUnixDateTimeMillisecondsNumber, roundToUnit: DateHourMinuteOrSecond, roundType?: FloorOrCeilRounding): UnixDateTimeMillisecondsNumber;
+/**
+ * Function that reduces an array (or single value) of possibly-null dates into a single Date result.
+ */
 export type ReduceDatesFunction = (inputDates: ArrayOrValue<Maybe<Date>>) => Maybe<Date>;
+/**
+ * Creates a {@link ReduceDatesFunction} that filters out null/undefined values, then applies the given reducer to the remaining dates.
+ *
+ * Returns undefined if no valid dates are present in the input.
+ *
+ * @param reduceDates - reducer function applied to the non-null dates array
+ * @returns a function that accepts an array or single date value and returns the reduced result
+ *
+ * @example
+ * ```ts
+ * import { min } from 'date-fns';
+ * const findMin = reduceDatesFunction(min);
+ * findMin([new Date('2024-01-01'), new Date('2024-06-01')]); // Jan 1
+ * findMin([null, undefined]); // undefined
+ * ```
+ */
 export declare function reduceDatesFunction(reduceDates: (dates: Date[]) => Maybe<Date>): ReduceDatesFunction;
 /**
- * Finds the minimum date in the input. If no dates are input, returns undefined.
+ * Finds the minimum (earliest) date from the input, ignoring null/undefined values. Returns undefined if no valid dates are provided.
+ *
+ * @example
+ * ```ts
+ * findMinDate([new Date('2024-06-01'), new Date('2024-01-01')]); // Jan 1
+ * findMinDate([null]); // undefined
+ * ```
  */
 export declare const findMinDate: ReduceDatesFunction;
 /**
- * Finds the maximum date in the input. If no dates are input, returns undefined.
+ * Finds the maximum (latest) date from the input, ignoring null/undefined values. Returns undefined if no valid dates are provided.
+ *
+ * @example
+ * ```ts
+ * findMaxDate([new Date('2024-01-01'), new Date('2024-06-01')]); // Jun 1
+ * findMaxDate([null]); // undefined
+ * ```
  */
 export declare const findMaxDate: ReduceDatesFunction;
 /**
- * Reads the unique days of the week from the given dates, until all the unique dates are returned.
+ * Collects the unique days of the week present among the given values, short-circuiting once all 7 days are found.
+ *
+ * @param values - items to extract dates from
+ * @param readDate - function to extract a Date from each value
+ * @returns a Set of DayOfWeek values (0=Sunday through 6=Saturday)
  *
- * @param values
- * @param readDate
+ * @example
+ * ```ts
+ * const dates = [new Date('2024-01-01'), new Date('2024-01-02')]; // Mon, Tue
+ * const days = readDaysOfWeek(dates, (d) => d);
+ * // days contains DayOfWeek.MONDAY and DayOfWeek.TUESDAY
+ * ```
  */
 export declare function readDaysOfWeek<T>(values: T[], readDate: ReadDateFunction<T>): Set<DayOfWeek>;
+/**
+ * Returns the display names of the unique days of the week present among the values, sorted by day number (Sunday first).
+ *
+ * @param values - items to extract dates from
+ * @param readDate - function to extract a Date from each value
+ * @param nameFunction - function that converts a DayOfWeek to its display name
+ * @returns sorted array of day name strings
+ *
+ * @example
+ * ```ts
+ * const dates = [new Date('2024-01-02'), new Date('2024-01-01')]; // Tue, Mon
+ * const names = readDaysOfWeekNames(dates, (d) => d, (day) => ['Sun','Mon','Tue','Wed','Thu','Fri','Sat'][day]);
+ * // names === ['Mon', 'Tue']
+ * ```
+ */
 export declare function readDaysOfWeekNames<T>(values: T[], readDate: ReadDateFunction<T>, nameFunction: DayOfWeekNameFunction): string[];
 /**
- * Returns true if the input date is at midnight for UTC.
+ * Checks whether the given date falls exactly at midnight (00:00:00.000) in UTC.
  *
- * @param date
- * @returns
+ * @param date - date to check
+ * @returns whether all UTC time components are zero
+ *
+ * @example
+ * ```ts
+ * isStartOfDayInUTC(new Date('2024-01-01T00:00:00.000Z')); // true
+ * isStartOfDayInUTC(new Date('2024-01-01T00:00:01.000Z')); // false
+ * ```
  */
 export declare function isStartOfDayInUTC(date: Date): boolean;
 /**
- * Returns true if the input date is the last millisecond.
+ * Checks whether the given date falls at the end of the day (23:59:59.999) in UTC.
+ *
+ * @param date - date to check
+ * @param minutesOnly - if true, only checks hours and minutes (23:59), ignoring seconds and milliseconds
+ * @returns whether the date represents end-of-day in UTC
  *
- * @param date
- * @param minutesOnly if true, only considers the hour and minute
- * @returns
+ * @example
+ * ```ts
+ * isEndOfDayInUTC(new Date('2024-01-01T23:59:59.999Z')); // true
+ * isEndOfDayInUTC(new Date('2024-01-01T23:59:00.000Z'), true); // true (minutes-only mode)
+ * ```
  */
 export declare function isEndOfDayInUTC(date: Date, minutesOnly?: boolean): boolean;
 /**
- * Returns true if the input date is at midnight for the system.
+ * Checks whether the given date falls exactly at midnight (00:00:00.000) in the system's local timezone.
+ *
+ * @param date - date to check
+ * @returns whether all local time components are zero
  *
- * @param date
- * @returns
+ * @example
+ * ```ts
+ * const midnight = new Date(2024, 0, 1, 0, 0, 0, 0);
+ * isStartOfDayForSystem(midnight); // true
+ * ```
  */
 export declare function isStartOfDayForSystem(date: Date): boolean;