@dereekb/util 13.11.14 → 13.11.15

package/src/lib/contact/random.d.ts

@@ -11,15 +11,15 @@ export interface RandomEmailFactoryConfig {
     /**
      * Set of email prefixes to use
      */
-    prefixes?: ArrayOrValue<string>;
+    readonly prefixes?: ArrayOrValue<string>;
     /**
      * domains to use
      */
-    domains?: ArrayOrValue<EmailAddressDomain>;
+    readonly domains?: ArrayOrValue<EmailAddressDomain>;
     /**
      * Random number generator. Negative numbers are treated as an "ignored" value.
      */
-    numberFactory?: NumberFactory;
+    readonly numberFactory?: NumberFactory;
 }
 /**
  * Default configuration that uses incrementing numbers and a test domain for safety in tests.
@@ -29,14 +29,15 @@ export type RandomEmailFactory = Factory<EmailAddress>;
 /**
  * Creates a factory that generates random email addresses using configurable prefixes, domains, and number generators.
  *
+ * @param inputConfig - Optional configuration overrides.
+ * @returns A factory function that produces random email address strings.
+ *
  * @dbxUtil
  * @dbxUtilCategory contact
  * @dbxUtilKind factory
  * @dbxUtilTags contact, email, random, factory, generate
  * @dbxUtilRelated random-phone-number-factory, incrementing-number-factory
  *
- * @param inputConfig - Optional configuration overrides
- * @returns A factory function that produces random email address strings
  * @__NO_SIDE_EFFECTS__
  */
 export declare function randomEmailFactory(inputConfig?: RandomEmailFactoryConfig): RandomEmailFactory;
@@ -47,11 +48,11 @@ export interface RandomPhoneNumberFactoryConfig {
     /**
      * Set of interntional numbers to use.
      */
-    internationalAreaCodes?: ArrayOrValue<number>;
+    readonly internationalAreaCodes?: ArrayOrValue<number>;
     /**
      * Random number generator. Should generate a 10-digit number. Generated numbers are not validated.
      */
-    numberFactory?: NumberFactory;
+    readonly numberFactory?: NumberFactory;
 }
 /**
  * Default configuration using US area codes and random 7-digit number generation.
@@ -61,14 +62,15 @@ export type RandomPhoneNumberFactory = Factory<E164PhoneNumber>;
 /**
  * Creates a factory that generates random E.164 phone numbers using configurable area codes and number generators.
  *
+ * @param inputConfig - Optional configuration overrides.
+ * @returns A factory function that produces random E.164 phone number strings.
+ *
  * @dbxUtil
  * @dbxUtilCategory contact
  * @dbxUtilKind factory
  * @dbxUtilTags contact, phone, e164, random, factory, generate
  * @dbxUtilRelated random-email-factory, random-number-factory
  *
- * @param inputConfig - Optional configuration overrides
- * @returns A factory function that produces random E.164 phone number strings
  * @__NO_SIDE_EFFECTS__
  */
 export declare function randomPhoneNumberFactory(inputConfig?: RandomPhoneNumberFactoryConfig): RandomPhoneNumberFactory;

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

@@ -44,13 +44,13 @@ export declare const ISO_8601_DATE_STRING_REGEX: RegExp;
 /**
  * Determines if a string is a valid ISO8601 date string.
  *
+ * @param input - Value to test against the ISO8601 date string pattern.
+ * @returns True when the input matches the canonical ISO8601 date layout.
+ *
  * @dbxUtil
  * @dbxUtilCategory date
  * @dbxUtilTags date, iso8601, string, predicate, validate
  * @dbxUtilRelated is-iso8601-day-string, is-utc-date-string, iso-8601-date-string-regex
- *
- * @param input - The string to test
- * @returns True if the input is a valid ISO8601 date string
  */
 export declare function isISO8601DateString(input: string): input is ISO8601DateString;
 /**
@@ -80,13 +80,13 @@ export declare const UTC_DATE_STRING_REGEX: RegExp;
 /**
  * Determines if a string is a valid UTC date string.
  *
+ * @param input - Value to test against the UTC-formatted date string pattern.
+ * @returns True when the input matches the canonical UTC date layout.
+ *
  * @dbxUtil
  * @dbxUtilCategory date
  * @dbxUtilTags date, utc, string, predicate, validate
  * @dbxUtilRelated is-iso8601-date-string, utc-date-string-regex
- *
- * @param input - The string to test
- * @returns True if the input is a valid UTC date string
  */
 export declare function isUTCDateString(input: string): boolean;
 /**
@@ -126,14 +126,14 @@ export interface TimezoneStringRef {
 /**
  * Returns true only if the inputs have the same timezone, or both do not have a timezone set.
  *
+ * @param a - First object that may contain a timezone reference.
+ * @param b - Second object that may contain a timezone reference.
+ * @returns True if both objects have the same timezone or neither has a timezone set.
+ *
  * @dbxUtil
  * @dbxUtilCategory date
  * @dbxUtilTags date, timezone, compare, equal, predicate
  * @dbxUtilRelated is-considered-utc-timezone-string
- *
- * @param a - First object that may contain a timezone reference
- * @param b - Second object that may contain a timezone reference
- * @returns True if both objects have the same timezone or neither has a timezone set
  */
 export declare function hasSameTimezone(a: Maybe<Partial<TimezoneStringRef>>, b: Maybe<Partial<TimezoneStringRef>>): boolean;
 /**
@@ -214,13 +214,13 @@ export declare const ISO8601_DAY_STRING_START_REGEX: RegExp;
  *
  * I.E. 2022-01-02T04:00:00.000Z in GMT-6 returns 2022-01-02
  *
+ * @param date - Reference instant whose UTC calendar day should be anchored.
+ * @returns Midnight UTC of the same UTC day as `date`.
+ *
  * @dbxUtil
  * @dbxUtilCategory date
  * @dbxUtilTags date, utc, start-of-day, day, normalize
  * @dbxUtilRelated start-of-day-for-system-date-in-utc, parse-iso8601-day-string-to-utc-date
- *
- * @param date - The date to get the start of day for
- * @returns A new Date set to midnight UTC of the input date's UTC day
  */
 export declare function startOfDayForUTCDateInUTC(date: Date): Date;
 /**
@@ -228,49 +228,49 @@ export declare function startOfDayForUTCDateInUTC(date: Date): Date;
  *
  * I.E. 2022-01-02T04:00:00.000Z in GMT-6 (10PM Jan 1st CST) returns 2022-01-01
  *
+ * @param date - Reference instant whose system-local calendar day should be anchored.
+ * @returns Midnight UTC corresponding to the local-time start of `date`.
+ *
  * @dbxUtil
  * @dbxUtilCategory date
  * @dbxUtilTags date, utc, start-of-day, system, local
  * @dbxUtilRelated start-of-day-for-utc-date-in-utc
- *
- * @param date - The date to get the start of local day for
- * @returns A new Date set to midnight UTC of the input date's local day
  */
 export declare function startOfDayForSystemDateInUTC(date: Date): Date;
 /**
  * Parses an ISO8601DayString (YYYY-MM-DD) to a UTC Date at midnight.
  *
+ * @param inputDateString - ISO8601 day string to parse (e.g. '2022-01-15').
+ * @returns Midnight UTC of the calendar day named by `inputDateString`.
+ *
  * @dbxUtil
  * @dbxUtilCategory date
  * @dbxUtilTags date, iso8601, day, parse, utc, convert
  * @dbxUtilRelated is-iso8601-day-string, start-of-day-for-utc-date-in-utc
- *
- * @param inputDateString - The ISO8601 day string to parse (e.g., '2022-01-15')
- * @returns A Date object set to midnight UTC on the specified day
  */
 export declare function parseISO8601DayStringToUTCDate(inputDateString: ISO8601DayString): Date;
 /**
  * Determines if a string is a valid ISO8601 day string (YYYY-MM-DD format).
  *
+ * @param input - Value to test against the ISO8601 day-string pattern.
+ * @returns True when the input is exactly a YYYY-MM-DD value.
+ *
  * @dbxUtil
  * @dbxUtilCategory date
  * @dbxUtilTags date, iso8601, day, string, predicate, validate
  * @dbxUtilRelated is-iso8601-day-string-start, parse-iso8601-day-string-to-utc-date, iso8601-day-string-regex
- *
- * @param input - The string to test
- * @returns True if the input is a valid ISO8601 day string
  */
 export declare function isISO8601DayString(input: string): input is ISO8601DayString;
 /**
  * Determines if a string starts with a valid ISO8601 day string pattern (YYYY-MM-DD).
  *
+ * @param input - Value to test for an ISO8601 day-string prefix.
+ * @returns True when the input begins with a YYYY-MM-DD prefix.
+ *
  * @dbxUtil
  * @dbxUtilCategory date
  * @dbxUtilTags date, iso8601, day, string, predicate, prefix
  * @dbxUtilRelated is-iso8601-day-string, iso8601-day-string-start-regex
- *
- * @param input - The string to test
- * @returns True if the input starts with a valid ISO8601 day string pattern
  */
 export declare function isISO8601DayStringStart(input: string): input is ISO8601DayString;
 /**
@@ -294,13 +294,13 @@ export declare const MONTH_DAY_SLASH_DATE_STRING_REGEX: RegExp;
 /**
  * Determines if a string is a valid Month/Day/Year slash date format.
  *
+ * @param input - Value to test against the slash-separated date pattern.
+ * @returns True when the input matches the Month/Day/Year slash format.
+ *
  * @dbxUtil
  * @dbxUtilCategory date
  * @dbxUtilTags date, slash, month, day, string, predicate, validate
  * @dbxUtilRelated month-day-slash-date-to-date-string, month-day-slash-date-string-regex
- *
- * @param input - The string to test
- * @returns True if the input is a valid Month/Day/Year slash date
  */
 export declare function isMonthDaySlashDate(input: string): input is MonthDaySlashDate;
 /**
@@ -308,13 +308,13 @@ export declare function isMonthDaySlashDate(input: string): input is MonthDaySla
  * Handles single digit months and days by adding leading zeros.
  * If year is only 2 digits, prepends '20' to make a 4-digit year.
  *
+ * @param slashDate - The slash date string to convert (e.g., '1/1/20' or '11/15/2022')
+ * @returns An ISO8601 formatted day string (YYYY-MM-DD)
+ *
  * @dbxUtil
  * @dbxUtilCategory date
  * @dbxUtilTags date, slash, day, string, convert, parse
  * @dbxUtilRelated is-month-day-slash-date
- *
- * @param slashDate - The slash date string to convert (e.g., '1/1/20' or '11/15/2022')
- * @returns An ISO8601 formatted day string (YYYY-MM-DD)
  */
 export declare function monthDaySlashDateToDateString(slashDate: MonthDaySlashDate): ISO8601DayString;
 /**
@@ -348,13 +348,13 @@ export declare function dateFromDateOrTimeMillisecondsNumber(input: Maybe<DateOr
 /**
  * Converts a unix timestamp number to a Date object.
  *
+ * @param dateTimeNumber - Unix timestamp number to convert.
+ * @returns Date object if timestamp is valid, null/undefined if timestamp is null/undefined.
+ *
  * @dbxUtil
  * @dbxUtilCategory date
  * @dbxUtilTags date, milliseconds, unix, convert, parse
  * @dbxUtilRelated date-from-date-or-time-milliseconds-number, unix-date-time-seconds-number-to-date
- *
- * @param dateTimeNumber - Unix timestamp number to convert
- * @returns Date object if timestamp is valid, null/undefined if timestamp is null/undefined
  */
 export declare function unixMillisecondsNumberToDate(dateTimeNumber: Maybe<UnixDateTimeMillisecondsNumber>): Maybe<Date>;
 /**
@@ -377,14 +377,14 @@ export type DateOrMilliseconds = Date | Milliseconds;
  *
  * If the input is a number of milliseconds, it is added to the current date.
  *
+ * @param dateOrMilliseconds - Either a concrete Date or a millisecond offset from `now`.
+ * @param now - Anchor used to resolve a millisecond offset; defaults to the current time.
+ * @returns Resolved Date for either a direct value or the offset-from-now case.
+ *
  * @dbxUtil
  * @dbxUtilCategory date
  * @dbxUtilTags date, milliseconds, convert, normalize, offset
  * @dbxUtilRelated add-milliseconds, date-from-date-or-time-milliseconds-number
- *
- * @param dateOrMilliseconds - The date or milliseconds to convert to a Date.
- * @param now - The current date to use when adding milliseconds. Defaults to the current time.
- * @returns The Date representation of the input.
  */
 export declare function dateOrMillisecondsToDate(dateOrMilliseconds: DateOrMilliseconds, now?: Maybe<Date>): Date;
 /**
@@ -584,13 +584,13 @@ export type DateMonth = number;
  *
  * Converts JavaScript's 0-based month (0-11) to a 1-based month (1-12).
  *
+ * @param date - Reference instant whose local month should be reported.
+ * @returns One-based local month-of-year, ready for human-facing display.
+ *
  * @dbxUtil
  * @dbxUtilCategory date
  * @dbxUtilTags date, month, year, accessor, system, local
  * @dbxUtilRelated month-of-year-from-date-month, month-of-year-from-utc-date
- *
- * @param date - The date to extract the month from
- * @returns The month of year as a number from 1-12
  */
 export declare function monthOfYearFromDate(date: Date): MonthOfYear;
 /**
@@ -598,37 +598,38 @@ export declare function monthOfYearFromDate(date: Date): MonthOfYear;
  *
  * Converts JavaScript's 0-based month (0-11) to a 1-based month (1-12).
  *
+ * @param date - Reference instant whose UTC month should be reported.
+ * @returns One-based UTC month-of-year, ready for human-facing display.
+ *
  * @dbxUtil
  * @dbxUtilCategory date
  * @dbxUtilTags date, month, year, accessor, utc
  * @dbxUtilRelated month-of-year-from-date, month-of-year-from-date-month
- *
- * @param date - The date to extract the month from
- * @returns The month of year as a number from 1-12
  */
 export declare function monthOfYearFromUTCDate(date: Date): MonthOfYear;
 /**
  * Converts a JavaScript Date month (0-11) to a MonthOfYear (1-12).
  *
+ * @param dateMonth - JavaScript Date month (0-11)
+ * @returns The month of year as a number from 1-12.
+ *
  * @dbxUtil
  * @dbxUtilCategory date
  * @dbxUtilTags date, month, year, convert, javascript
  * @dbxUtilRelated make-date-month-for-month-of-year, month-of-year-from-date
- *
- * @param dateMonth - JavaScript Date month (0-11)
- * @returns The month of year as a number from 1-12
  */
 export declare function monthOfYearFromDateMonth(dateMonth: DateMonth): MonthOfYear;
 /**
  * Converts a MonthOfYear (1-12) to a JavaScript Date month (0-11).
  *
+ * @param monthOfYear - Month of year (1-12)
+ * @returns JavaScript Date month (0-11)
+ *
  * @dbxUtil
  * @dbxUtilCategory date
  * @dbxUtilTags date, month, convert, javascript
  * @dbxUtilRelated month-of-year-from-date-month, month-of-year-from-date
  *
- * @param monthOfYear - Month of year (1-12)
- * @returns JavaScript Date month (0-11)
  * @__NO_SIDE_EFFECTS__
  */
 export declare function makeDateMonthForMonthOfYear(monthOfYear: MonthOfYear): DateMonth;
@@ -648,39 +649,39 @@ export type DateRelativeState = DateRelativeDirection | 'present';
  * Returns true if the value is a Date object.
  * Uses both instanceof and Object.prototype.toString for reliable type checking.
  *
+ * @param value - The value to check.
+ * @returns True if the value is a Date object.
+ *
  * @dbxUtil
  * @dbxUtilCategory date
  * @dbxUtilTags date, predicate, type-guard, validate
  * @dbxUtilRelated is-equal-date, is-past
- *
- * @param value - The value to check
- * @returns True if the value is a Date object
  */
 export declare function isDate(value: unknown): value is Date;
 /**
  * Returns true if the two input dates represent the same point in time.
  * Compares the timestamp values rather than the object references.
  *
+ * @param a - First date to compare.
+ * @param b - Second date to compare.
+ * @returns True if the dates represent the same point in time.
+ *
  * @dbxUtil
  * @dbxUtilCategory date
  * @dbxUtilTags date, equal, compare, predicate
  * @dbxUtilRelated is-date, is-past
- *
- * @param a - First date to compare
- * @param b - Second date to compare
- * @returns True if the dates represent the same point in time
  */
 export declare function isEqualDate(a: Date, b: Date): boolean;
 /**
  * Returns true if the input date is in the past relative to the current time.
  *
+ * @param input - Instant to compare against the system clock.
+ * @returns True when `input` is strictly before the current time.
+ *
  * @dbxUtil
  * @dbxUtilCategory date
  * @dbxUtilTags date, past, compare, predicate, time
  * @dbxUtilRelated is-equal-date, is-date
- *
- * @param input - The date to check
- * @returns True if the date is in the past
  */
 export declare function isPast(input: Date): boolean;
 /**

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

@@ -52,7 +52,7 @@ export declare function dateFromLogicalDate(logicalDate: Maybe<LogicalDate>): Ma
  * Determines if the input value is a recognized LogicalDateStringCode.
  * Currently, only the 'now' value is recognized as a LogicalDateStringCode.
  *
- * @param logicalDate - The value to check
- * @returns True if the value is a recognized LogicalDateStringCode
+ * @param logicalDate - The value to check.
+ * @returns True if the value is a recognized LogicalDateStringCode.
  */
 export declare function isLogicalDateStringCode(logicalDate: Maybe<string | LogicalDate>): logicalDate is LogicalDateStringCode;

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

@@ -18,24 +18,24 @@ export type DateOrUnixDateTimeSecondsNumber = Date | UnixDateTimeSecondsNumber;
 /**
  * Converts a Date object or unix timestamp number to a unix timestamp number.
  *
+ * @param input - Date object or unix timestamp number to convert.
+ * @returns Unix timestamp number if input is valid, null/undefined if input is null/undefined.
+ *
  * @dbxUtil
  * @dbxUtilCategory date
  * @dbxUtilTags date, unix, seconds, timestamp, convert, normalize
  * @dbxUtilRelated unix-date-time-seconds-number-from-date, date-from-date-or-time-seconds-number
- *
- * @param input - Date object or unix timestamp number to convert
- * @returns Unix timestamp number if input is valid, null/undefined if input is null/undefined
  */
 export declare function unixDateTimeSecondsNumberFromDateOrTimeNumber(input: Maybe<DateOrUnixDateTimeSecondsNumber>): Maybe<UnixDateTimeSecondsNumber>;
 /**
  * Gets the current time as a unix timestamp number.
  *
+ * @returns Current time as unix timestamp number.
+ *
  * @dbxUtil
  * @dbxUtilCategory date
  * @dbxUtilTags date, unix, seconds, timestamp, now, current, time
  * @dbxUtilRelated unix-date-time-seconds-number-from-date
- *
- * @returns Current time as unix timestamp number
  */
 export declare function unixDateTimeSecondsNumberForNow(): UnixDateTimeSecondsNumber;
 /**
@@ -63,12 +63,12 @@ export declare function dateFromDateOrTimeSecondsNumber(input: Maybe<DateOrUnixD
 /**
  * Converts a unix timestamp number to a Date object.
  *
+ * @param dateTimeNumber - Unix timestamp number to convert.
+ * @returns Date object if timestamp is valid, null/undefined if timestamp is null/undefined.
+ *
  * @dbxUtil
  * @dbxUtilCategory date
  * @dbxUtilTags date, unix, seconds, timestamp, convert, parse
  * @dbxUtilRelated unix-date-time-seconds-number-from-date, date-from-date-or-time-seconds-number
- *
- * @param dateTimeNumber - Unix timestamp number to convert
- * @returns Date object if timestamp is valid, null/undefined if timestamp is null/undefined
  */
 export declare function unixDateTimeSecondsNumberToDate(dateTimeNumber: Maybe<UnixDateTimeSecondsNumber>): Maybe<Date>;

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

@@ -26,9 +26,9 @@ export declare const TIME_UNIT_SHORT_LABEL_MAP: Readonly<Record<TimeUnit, string
 /**
  * Converts an amount in the given time unit to milliseconds.
  *
- * @param amount - The numeric amount in the given unit
- * @param unit - The time unit of the amount
- * @returns The equivalent number of milliseconds
+ * @param amount - The numeric amount in the given unit.
+ * @param unit - The time unit of the amount.
+ * @returns The equivalent number of milliseconds.
  *
  * @example
  * ```typescript
@@ -40,9 +40,9 @@ export declare function timeUnitToMilliseconds(amount: number, unit: TimeUnit):
 /**
  * Converts milliseconds to an amount in the given time unit.
  *
- * @param ms - The number of milliseconds
- * @param unit - The target time unit
- * @returns The equivalent amount in the target unit
+ * @param ms - Source duration measured in milliseconds.
+ * @param unit - Time unit to express the duration in.
+ * @returns Same duration rescaled to the requested unit.
  *
  * @example
  * ```typescript
@@ -56,10 +56,10 @@ export declare function millisecondsToTimeUnit(ms: Milliseconds, unit: TimeUnit)
  *
  * Goes through milliseconds as an intermediary for the conversion.
  *
- * @param amount - The numeric amount in the source unit
- * @param fromUnit - The source time unit
- * @param toUnit - The target time unit
- * @returns The equivalent amount in the target unit
+ * @param amount - The numeric amount in the source unit.
+ * @param fromUnit - The source time unit.
+ * @param toUnit - The target time unit.
+ * @returns The equivalent amount in the target unit.
  *
  * @example
  * ```typescript
@@ -79,8 +79,8 @@ export interface TimeDuration {
 /**
  * Converts a TimeDuration to milliseconds.
  *
- * @param duration - The duration to convert
- * @returns The equivalent number of milliseconds
+ * @param duration - The duration to convert.
+ * @returns The equivalent number of milliseconds.
  *
  * @example
  * ```typescript
@@ -93,8 +93,8 @@ export declare function timeDurationToMilliseconds(duration: TimeDuration): Mill
  *
  * First converts to total minutes, then splits into hours and minutes.
  *
- * @param duration - The duration to convert
- * @returns An HoursAndMinutes object
+ * @param duration - The duration to convert.
+ * @returns An HoursAndMinutes object.
  *
  * @example
  * ```typescript
@@ -106,9 +106,9 @@ export declare function timeDurationToHoursAndMinutes(duration: TimeDuration): H
 /**
  * Converts an HoursAndMinutes object to a total number in the specified time unit.
  *
- * @param hoursAndMinutes - The hours and minutes to convert
- * @param toUnit - The target time unit
- * @returns The equivalent amount in the target unit
+ * @param hoursAndMinutes - The hours and minutes to convert.
+ * @param toUnit - The target time unit.
+ * @returns The equivalent amount in the target unit.
  *
  * @example
  * ```typescript

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

@@ -92,46 +92,48 @@ export interface ExpirationDetails<T extends Expires = Expires> {
  * - **TTL / throttle**: `expirationDetails({ expiresFromDate: lastRunAt, expiresIn: throttleMs })` — see {@link isThrottled}
  * - **Pre-emptive refresh**: `expirationDetails({ expiresFromDate: expiresAt, expiresIn: -bufferMs })` — treat as expired `bufferMs` before the real expiration, e.g. to refresh a token before it actually dies
  *
+ * @param input - Configuration for calculating expiration.
+ * @returns An ExpirationDetails object that can determine expiration state.
+ *
  * @dbxUtil
  * @dbxUtilCategory date
  * @dbxUtilTags expiration, expires, expiry, ttl, throttle, refresh, time-to-live
  * @dbxUtilRelated is-expired, is-throttled, calculate-expiration-date, is-under-threshold, check-atleast-one-not-expired, check-any-have-expired
- *
  * @template T - The type of Expires object
- * @param input - Configuration for calculating expiration
- * @returns An ExpirationDetails object that can determine expiration state
  */
 export declare function expirationDetails<T extends Expires = Expires>(input: ExpirationDetailsInput<T>): ExpirationDetails<T>;
 /**
  * Convenience function for calculating and returning the expiration date given the input.
  * This is a shorthand for expirationDetails(input).getExpirationDate().
  *
+ * @param input - Input configuration used to calculate the expiration date.
+ * @returns The calculated expiration date, or null if no expiration is defined.
+ *
  * @dbxUtil
  * @dbxUtilCategory date
  * @dbxUtilTags expiration, expires, expiry, ttl, calculate, date
  * @dbxUtilRelated expiration-details, is-expired
- *
- * @param input - Input configuration used to calculate the expiration date
- * @returns The calculated expiration date, or null if no expiration is defined
  */
 export declare function calculateExpirationDate(input: ExpirationDetailsInput<Expires>): Maybe<Date>;
 /**
  * Convenience wrapper around {@link expirationDetails}().hasExpired() that treats null/undefined input or no expiration date as expired.
  *
+ * @param input - Expiration configuration. Null/undefined is treated as expired.
+ * @param now - Optional override for the current time. Defaults to the current time. Apply any buffer (e.g. for clock skew or pre-emptive refresh) by shifting this value forward.
+ * @returns True when the input is null/undefined or its expiration date has passed; otherwise false.
+ *
  * @dbxUtil
  * @dbxUtilCategory date
  * @dbxUtilTags expiration, expires, expiry, expired, has-expired, is-expired, ttl
  * @dbxUtilRelated expiration-details, is-throttled, calculate-expiration-date
  *
- * @param input - Expiration configuration. Null/undefined is treated as expired.
- * @param now - Optional override for the current time. Defaults to the current time. Apply any buffer (e.g. for clock skew or pre-emptive refresh) by shifting this value forward.
- * @returns True when the input is null/undefined or its expiration date has passed; otherwise false.
- *
  * @example
+ * ```ts
  * isExpired(null); // true
  * isExpired({ expiresAt: pastDate }); // true
  * isExpired({ expiresAt: futureDate }); // false
  * isExpired({ expiresAt: futureDate }, addMilliseconds(new Date(), 60_000)); // true (when within buffer)
+ * ```
  */
 export declare function isExpired<T extends Expires = Expires>(input: Maybe<ExpirationDetailsInput<T>>, now?: Maybe<Date>): boolean;
 /**
@@ -142,15 +144,15 @@ export declare function isExpired<T extends Expires = Expires>(input: Maybe<Expi
  * Example:
  * - Should send a notification at max every 2 days. The threshold is 2 days in milliseconds, and "nextRunAt" is the previously calculated date that was originally "now" + "threshold".
  *
+ * @param threshold - The threshold time. Typically this is amount of time that was used to calculate the original "nextRunAt" time.
+ * @param nextRunAt - Time the next run will occur. If null/undefined, then this function will return false.
+ * @param now - Optional override for the current time. Defaults to the current time.
+ * @returns True if the threshold has not passed since the next run time, compared to now.
+ *
  * @dbxUtil
  * @dbxUtilCategory date
  * @dbxUtilTags threshold, throttle, ttl, time-window, rate-limit
  * @dbxUtilRelated is-throttled, expiration-details
- *
- * @param threshold The threshold time. Typically this is amount of time that was used to calculate the original "nextRunAt" time.
- * @param nextRunAt Time the next run will occur. If null/undefined, then this function will return false.
- * @param now Optional override for the current time. Defaults to the current time.
- * @returns True if the threshold has not passed since the next run time, compared to now.
  */
 export declare function isUnderThreshold(threshold: Milliseconds, nextRunAt: Maybe<DateOrUnixDateTimeMillisecondsNumber>, now?: Maybe<Date>): boolean;
 /**
@@ -159,15 +161,15 @@ export declare function isUnderThreshold(threshold: Milliseconds, nextRunAt: May
  * Returns true if the throttle time has not passed since the last run time, compared to now.
  * This is useful for rate limiting operations (e.g., "only allow this action once every X milliseconds").
  *
+ * @param throttleTime - Minimum time in milliseconds that must pass between operations.
+ * @param lastRunAt - Timestamp when the operation was last performed.
+ * @param now - Optional override for the current time (defaults to the current time)
+ * @returns True if the operation should be throttled (not enough time has passed), false otherwise.
+ *
  * @dbxUtil
  * @dbxUtilCategory date
  * @dbxUtilTags throttle, throttled, rate-limit, debounce, ttl, expiration
  * @dbxUtilRelated expiration-details, is-under-threshold, is-expired
- *
- * @param throttleTime - Minimum time in milliseconds that must pass between operations
- * @param lastRunAt - Timestamp when the operation was last performed
- * @param now - Optional override for the current time (defaults to the current time)
- * @returns True if the operation should be throttled (not enough time has passed), false otherwise
  */
 export declare function isThrottled(throttleTime: Maybe<Milliseconds>, lastRunAt: Maybe<DateOrUnixDateTimeMillisecondsNumber>, now?: Maybe<Date>): boolean;
 /**
@@ -176,13 +178,13 @@ export declare function isThrottled(throttleTime: Maybe<Milliseconds>, lastRunAt
  *
  * If the list is empty, returns false.
  *
+ * @param details - Collection of ExpirationDetails to check.
+ * @returns True if at least one item has not expired, false otherwise.
+ *
  * @dbxUtil
  * @dbxUtilCategory date
  * @dbxUtilTags expiration, valid, collection, any
  * @dbxUtilRelated expiration-details, check-any-have-expired
- *
- * @param details - Collection of ExpirationDetails to check
- * @returns True if at least one item has not expired, false otherwise
  */
 export declare function checkAtleastOneNotExpired(details: ExpirationDetails<Expires>[]): boolean;
 /**
@@ -191,13 +193,13 @@ export declare function checkAtleastOneNotExpired(details: ExpirationDetails<Exp
  *
  * If the list is empty, returns the value specified by defaultIfEmpty.
  *
+ * @param details - Collection of ExpirationDetails to check.
+ * @param defaultIfEmpty - Default value to return if the list is empty (defaults to true)
+ * @returns True if any item has expired, or the defaultIfEmpty value for an empty list.
+ *
  * @dbxUtil
  * @dbxUtilCategory date
  * @dbxUtilTags expiration, refresh, collection, any
  * @dbxUtilRelated expiration-details, check-atleast-one-not-expired
- *
- * @param details - Collection of ExpirationDetails to check
- * @param defaultIfEmpty - Default value to return if the list is empty (defaults to true)
- * @returns True if any item has expired, or the defaultIfEmpty value for an empty list
  */
 export declare function checkAnyHaveExpired(details: ExpirationDetails<Expires>[], defaultIfEmpty?: boolean): boolean;