@dereekb/date 13.0.7 → 13.1.0

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

@@ -1,16 +1,55 @@
 import { type ISO8601DayString, type DateOrDayString } from '@dereekb/util';
 import { type DateRange } from './date.range';
+/**
+ * A start boundary expressed as an ISO 8601 day string (e.g. "2024-01-15").
+ */
 export interface ISO8601DayStringStart {
     start: ISO8601DayString;
 }
+/**
+ * A date range expressed as ISO 8601 day strings for both start and end.
+ */
 export interface ISO8601DayStringRange extends ISO8601DayStringStart {
     end: ISO8601DayString;
 }
+/**
+ * A start boundary that accepts either a Date object or an ISO 8601 day string.
+ */
 export interface DateOrDayStringStart {
     start: DateOrDayString;
 }
+/**
+ * A date range where start and end can each be a Date or an ISO 8601 day string.
+ */
 export interface DateOrDayStringRange extends DateOrDayStringStart {
     end: DateOrDayString;
 }
+/**
+ * Converts a {@link DateOrDayStringRange} to a {@link DateRange} by parsing any string values to the start of their respective days.
+ *
+ * @param range - the range with Date or string values
+ * @returns a DateRange with concrete Date objects
+ *
+ * @example
+ * ```ts
+ * const range = dateOrDayStringRangeToDateRange({ start: '2024-01-01', end: '2024-01-31' });
+ * // range.start and range.end are Date objects at start of day
+ * ```
+ */
 export declare function dateOrDayStringRangeToDateRange(range: DateOrDayStringRange): DateRange;
+/**
+ * Converts a {@link DateOrDayStringRange} to an {@link ISO8601DayStringRange} by formatting any Date values as ISO 8601 day strings using the system timezone.
+ *
+ * @param range - the range with Date or string values
+ * @returns a range with both start and end as ISO 8601 day strings
+ *
+ * @example
+ * ```ts
+ * const stringRange = dateOrDayStringRangeToISO8601DayStringRange({
+ *   start: new Date('2024-01-01T10:00:00Z'),
+ *   end: '2024-01-31'
+ * });
+ * // stringRange.start === '2024-01-01', stringRange.end === '2024-01-31'
+ * ```
+ */
 export declare function dateOrDayStringRangeToISO8601DayStringRange(range: DateOrDayStringRange): ISO8601DayStringRange;

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

@@ -9,16 +9,28 @@ export type FitDateRangeToDayPeriodFunction = (<T extends DateRange>(dateRange:
     readonly _timezoneInstance: DateTimezoneUtcNormalInstance;
 };
 /**
- * Creates a FitDateRangeToDayPeriodFunction
+ * Creates a {@link FitDateRangeToDayPeriodFunction} that collapses a multi-day date range into a single-day period within the given timezone.
  *
- * @param timezone
- * @returns
+ * The function first normalizes the range into the target timezone, fits it to a 24-hour period, then converts back.
+ *
+ * @param timezone - the timezone to use for the day period calculation
+ * @returns a function that fits any date range to a single day period
+ *
+ * @example
+ * ```ts
+ * const fit = fitDateRangeToDayPeriodFunction('America/Chicago');
+ * const range = { start: new Date('2024-01-01T10:00:00Z'), end: new Date('2024-01-03T14:00:00Z') };
+ * const fitted = fit(range);
+ * // fitted spans from 10:00 to 14:00 on the same day (4 hours)
+ * ```
  */
 export declare function fitDateRangeToDayPeriodFunction(timezone: DateTimezoneUtcNormalFunctionInput): FitDateRangeToDayPeriodFunction;
 /**
- * Fits the DateRange to a single "day" period from the start time.
+ * Fits the DateRange to a single "day" period from the start time within the given timezone.
+ *
+ * Convenience wrapper around {@link fitDateRangeToDayPeriodFunction}.
  *
- * @param dateRange
- * @param timezone
+ * @param dateRange - the range to fit
+ * @param timezone - the timezone for day boundary calculation
  */
 export declare function fitDateRangeToDayPeriod<T extends DateRange = DateRange>(dateRange: T, timezone: DateTimezoneUtcNormalFunctionInput): T;

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

@@ -1,14 +1,59 @@
+/**
+ * Options for rounding a date's time components down.
+ */
 export interface RoundTimeDown {
     roundDownToDay?: boolean;
     roundDownToMinute?: boolean;
 }
+/**
+ * Options for rounding a date to configured minute steps, then optionally rounding time components down.
+ */
 export interface StepRoundDateTimeDown extends RoundTimeDown {
     step?: number;
     roundToSteps?: boolean;
 }
+/**
+ * Rounds the date's minutes to the nearest step, then rounds remaining time components down.
+ *
+ * @param date - the date to round
+ * @param round - step and rounding configuration
+ * @returns the rounded date
+ *
+ * @example
+ * ```ts
+ * // Round to 15-minute steps and clear seconds
+ * const rounded = roundDateTimeDownToSteps(new Date('2024-01-01T10:07:30Z'), { step: 15 });
+ * // rounded minutes will be 15 (rounded up from 7), seconds cleared
+ * ```
+ */
 export declare function roundDateTimeDownToSteps(date: Date, round: StepRoundDateTimeDown): Date;
+/**
+ * Clears time components of the date based on rounding options (e.g. seconds/milliseconds, or hours/minutes for day rounding).
+ *
+ * @param date - the date to round
+ * @param round - which components to clear
+ * @returns the rounded date
+ *
+ * @example
+ * ```ts
+ * const result = roundDateTimeDown(new Date('2024-01-01T10:07:30.500Z'), { roundDownToMinute: true });
+ * // seconds and milliseconds are set to 0
+ * ```
+ */
 export declare function roundDateTimeDown(date: Date, round: RoundTimeDown): Date;
 /**
- * Rounds the current number of minutes on the date to the nearest step.
+ * Rounds the date's minutes up to the nearest multiple of the given step.
+ *
+ * If the step is 1 or less, the date is returned unchanged. If rounding pushes minutes to 60, the hour is incremented.
+ *
+ * @param date - the date to round
+ * @param step - the minute step to round to
+ * @returns the date with minutes rounded to the nearest step
+ *
+ * @example
+ * ```ts
+ * const result = roundToMinuteSteps(new Date('2024-01-01T10:07:00Z'), 15);
+ * // result minutes will be 15 (next step above 7)
+ * ```
  */
 export declare function roundToMinuteSteps(date: Date, step: number): Date;

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

@@ -1,6 +1,9 @@
 import { type FactoryWithRequiredInput, type IndexNumber, type Maybe, type Milliseconds } from '@dereekb/util';
 import { type Observable, type SchedulerLike } from 'rxjs';
 import { type LogicalDateStringCode } from './date.logical';
+/**
+ * Configuration for creating a periodic date-emitting Observable.
+ */
 export interface DateIntervalConfig {
     /**
      * How often to emit the date.
@@ -9,15 +12,15 @@ export interface DateIntervalConfig {
      */
     readonly period?: Maybe<Milliseconds>;
     /**
-     * Emits the given logical each interval.
+     * Emits the given logical date each interval (e.g. 'now', 'today_start').
      */
     readonly logicalDate?: Maybe<LogicalDateStringCode>;
     /**
-     * Factory to use for the date.
+     * Custom factory to use for producing each date value.
      */
     readonly factory?: FactoryWithRequiredInput<Date, IndexNumber>;
     /**
-     * Whether or not to only emit each value and not only when the date has changed. False by default.
+     * Whether to emit every interval tick regardless of whether the date changed. False by default.
      */
     readonly emitAll?: boolean;
     /**
@@ -26,13 +29,32 @@ export interface DateIntervalConfig {
     readonly scheduler?: SchedulerLike | undefined;
 }
 /**
- * Creates an Observable that emits a date given the configuration.
+ * Creates an Observable that emits a Date at regular intervals based on the given configuration.
+ *
+ * By default emits the current time every second and deduplicates consecutive equal dates.
+ *
+ * @param config - interval and date generation configuration
+ * @returns an Observable that emits Date values
+ *
+ * @example
+ * ```ts
+ * // Emit start-of-today every 5 seconds
+ * const today$ = dateInterval({ logicalDate: 'today_start', period: 5000 });
+ * ```
  */
 export declare function dateInterval(config: DateIntervalConfig): Observable<Date>;
 /**
- * Convenience function for dateInterval that returns the "now" logicalDate with an optional custom period.
+ * Convenience function for {@link dateInterval} that emits the current time at each interval tick.
+ *
+ * Unlike the default dateInterval, this always emits (no deduplication) since each "now" is unique.
+ *
+ * @param period - optional emission interval in milliseconds (defaults to 1 second)
+ * @returns an Observable that emits the current Date
  *
- * @param period
- * @returns
+ * @example
+ * ```ts
+ * const now$ = nowInterval(1000);
+ * now$.subscribe((date) => console.log('Current time:', date));
+ * ```
  */
 export declare function nowInterval(period?: Maybe<Milliseconds>): Observable<Date>;

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

@@ -1,27 +1,54 @@
 import { type SortingOrder, type SortCompareFunction } from '@dereekb/util';
 import { type ReadDateFunction, type ReadISO8601DateStringUTCFullFunction } from './date';
 /**
- * SortCompareFunction by Date
+ * A {@link SortCompareFunction} that sorts items by a Date value.
  */
 export type SortByDateFunction<T> = SortCompareFunction<T>;
 /**
- * Creates a SortByNumberFunction that sorts values in ascending order.
+ * Creates a sort comparison function that orders items in ascending date order using the provided reader.
+ *
+ * @param readDateFn - extracts a Date from each item
+ * @returns a comparison function for use with Array.sort()
+ *
+ * @example
+ * ```ts
+ * const events = [{ at: new Date('2024-03-01') }, { at: new Date('2024-01-01') }];
+ * events.sort(sortByDateFunction((e) => e.at));
+ * // events[0].at === '2024-01-01'
+ * ```
  */
 export declare function sortByDateFunction<T>(readDateFn: ReadDateFunction<T>): SortByDateFunction<T>;
 /**
- * SortCompareFunction by Date
+ * A {@link SortCompareFunction} that sorts items by an ISO 8601 date string.
  */
 export type SortByISO8601DateStringFunction<T> = SortCompareFunction<T>;
 /**
- * Creates a SortByNumberFunction that sorts values in ascending order.
+ * Creates a sort comparison function that orders items in ascending order by lexicographic comparison of ISO 8601 date strings.
+ *
+ * @param readDateFn - extracts an ISO 8601 date string from each item
+ * @returns a comparison function for use with Array.sort()
+ *
+ * @example
+ * ```ts
+ * const items = [{ d: '2024-03-01T00:00:00Z' }, { d: '2024-01-01T00:00:00Z' }];
+ * items.sort(sortByISO8601DateStringFunction((x) => x.d));
+ * // items[0].d === '2024-01-01T00:00:00Z'
+ * ```
  */
 export declare function sortByISO8601DateStringFunction<T>(readDateFn: ReadISO8601DateStringUTCFullFunction<T>): SortByISO8601DateStringFunction<T>;
 /**
- * Sorts the input values by ISO8601DateStringUTCFull values from the input models.
+ * Returns a sorted copy of the input array, ordered by ISO 8601 date strings extracted from each item.
+ *
+ * @param values - the items to sort
+ * @param readDate - extracts an ISO 8601 date string from each item
+ * @param order - optional sorting order ('asc' or 'desc', defaults to ascending)
+ * @returns a new sorted array (does not mutate the original)
  *
- * @param values
- * @param readDate
- * @param order
- * @returns
+ * @example
+ * ```ts
+ * const items = [{ d: '2024-03-01T00:00:00Z' }, { d: '2024-01-01T00:00:00Z' }];
+ * const sorted = sortByISO8601DateStrings(items, (x) => x.d);
+ * // sorted[0].d === '2024-01-01T00:00:00Z'
+ * ```
  */
 export declare function sortByISO8601DateStrings<T>(values: T[], readDate: ReadISO8601DateStringUTCFullFunction<T>, order?: SortingOrder): T[];

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

@@ -1,43 +1,55 @@
 import { type LogicalDateStringCode, type Maybe, type ReadableTimeString, TimeAM, type TimezoneString } from '@dereekb/util';
 import { type LimitDateTimeConfig, LimitDateTimeInstance } from './date.time.limit';
 import { type DateTimezoneConversionConfig, DateTimezoneUtcNormalInstance } from './date.timezone';
+/**
+ * Result of parsing a time string, containing both the raw UTC and timezone-adjusted dates
+ * along with computed time-of-day information.
+ */
 export interface ParsedTimeString {
     /**
-     * Parsed "raw" date in UTC.
+     * The parsed date normalized to UTC, preserving the wall-clock time.
+     * For example, parsing "1:00PM" yields 1:00PM UTC regardless of the source timezone.
      */
     utc: Date;
     /**
-     * Understood date, given the input.
+     * The timezone-adjusted date representing the actual moment in time the input refers to.
      */
     date: Date;
     /**
-     * The minute in the day.
+     * Number of minutes elapsed since midnight, used for time-of-day comparisons.
      */
     minutesSinceStartOfDay: number;
     /**
-     * AM or PM
+     * Whether the parsed time falls in the AM or PM half of the day.
      */
     am: TimeAM;
 }
+/**
+ * Configuration for parsing a time string relative to a specific date and timezone.
+ */
 export interface ParseTimeString extends DateTimezoneConversionConfig {
     /**
-     * Reference date to parse from.
+     * The reference date used as the base day for the parsed time.
+     * Defaults to the current date/time if not provided.
      */
     readonly date?: Date;
 }
+/**
+ * Result of converting a time string to a date, containing both the raw UTC interpretation
+ * and the timezone-adjusted result.
+ */
 export interface DateFromTimestringResult {
     /**
-     * The "raw" date. This occurs at the UTC time of the parsed result. For instance, 1PM for any timezone will return 1PM in UTC for the same date.
+     * The parsed date normalized to UTC wall-clock time. For instance, "1:00PM" in any timezone
+     * yields 1:00PM UTC, useful for timezone-independent time-of-day comparisons.
      */
     raw?: Maybe<Date>;
     /**
-     * The real, post-timezone-converted value.
+     * The actual moment in time after applying timezone conversion from the raw value.
      */
     result?: Maybe<Date>;
     /**
-     * Whether or not the value was parsed.
-     *
-     * If not value, raw and result may be undefined.
+     * Whether the input was successfully parsed. When false, `raw` and `result` may be undefined.
      */
     valid: boolean;
 }
@@ -46,53 +58,212 @@ export interface ValidDateFromTimestringResult extends Required<DateFromTimestri
     raw: Date;
     valid: true;
 }
+/**
+ * Type guard that narrows a {@link DateFromTimestringResult} to {@link ValidDateFromTimestringResult},
+ * guaranteeing that `raw` and `result` are defined.
+ *
+ * @param result - The parse result to check.
+ *
+ * @example
+ * ```ts
+ * const parseResult = instance.timeStringToDateResult('1:30PM');
+ * if (isValidDateFromTimestringResult(parseResult)) {
+ *   console.log(parseResult.result); // Date is guaranteed
+ * }
+ * ```
+ */
 export declare function isValidDateFromTimestringResult(result: ValidDateFromTimestringResult | DateFromTimestringResult): result is ValidDateFromTimestringResult;
 /**
- * A utility instance.
+ * Stateful utility for parsing and formatting time strings relative to a configured timezone.
+ *
+ * Handles the complexity of converting between wall-clock time representations and actual
+ * moments in time across timezones. Supports multiple input formats including "1:30PM",
+ * "13:30", "1PM", and logical date string codes.
+ *
+ * @example
+ * ```ts
+ * const instance = new DateTimeUtilityInstance('America/New_York');
+ * const date = instance.timeStringToDate('1:30PM');
+ * const timeStr = instance.toTimeString(new Date());
+ * ```
  */
 export declare class DateTimeUtilityInstance {
     readonly normalInstance: DateTimezoneUtcNormalInstance;
     /**
-     * The default timezone all inputs should be handled with.
-     *
-     * If the timezone is not defined, it defaults to UTC.
+     * @param timezone - The default timezone for all operations. Defaults to UTC if not provided.
      */
     constructor(timezone?: Maybe<TimezoneString>);
     get timezone(): TimezoneString;
+    /**
+     * Determines whether the given date falls in the AM or PM period for the specified timezone.
+     *
+     * @param date - The date to check. Defaults to now.
+     * @param timezone - Overrides the instance's configured timezone for this call.
+     *
+     * @example
+     * ```ts
+     * const instance = new DateTimeUtilityInstance('America/Chicago');
+     * const amPm = instance.getTimeAM(new Date()); // TimeAM.AM or TimeAM.PM
+     * ```
+     */
     getTimeAM(date?: Date, timezone?: TimezoneString): TimeAM;
+    /**
+     * Formats a date as a human-readable time string (e.g., "1:30PM") in the given timezone.
+     *
+     * @param date - The date to format.
+     * @param timezone - Overrides the instance's configured timezone for this call.
+     *
+     * @example
+     * ```ts
+     * const instance = new DateTimeUtilityInstance('UTC');
+     * instance.toTimeString(new Date('2024-01-15T13:30:00Z')); // '1:30PM'
+     * ```
+     */
     toTimeString(date: Date, timezone?: TimezoneString): ReadableTimeString;
+    /**
+     * Parses a readable time string into a {@link ParsedTimeString} with both UTC and
+     * timezone-adjusted dates, plus time-of-day metadata.
+     *
+     * @param input - A time string such as "1:30PM", "13:30", or "1PM".
+     * @param config - Optional parsing configuration with reference date and timezone overrides.
+     * @returns The parsed result, or undefined if the input could not be parsed.
+     *
+     * @example
+     * ```ts
+     * const instance = new DateTimeUtilityInstance('America/New_York');
+     * const parsed = instance.parseTimeString('2:30PM');
+     * if (parsed) {
+     *   console.log(parsed.minutesSinceStartOfDay); // 870
+     *   console.log(parsed.am); // TimeAM.PM
+     * }
+     * ```
+     */
     parseTimeString(input: ReadableTimeString, config?: ParseTimeString): Maybe<ParsedTimeString>;
     /**
-     * Returns a timestring parsed relative to the input config.
+     * Converts a time string or logical date code into an actual Date, applying timezone conversion.
      *
-     * @param input
-     * @param config
-     * @returns
+     * Supports many input formats: "1:30PM", "1:30 PM", "1PM", "1AM", "13:30", "1330", and
+     * logical date string codes.
+     *
+     * @param input - The time string or logical date code to parse.
+     * @param config - Optional parsing configuration with reference date and timezone overrides.
+     * @returns The resolved date, or undefined if the input could not be parsed.
+     *
+     * @example
+     * ```ts
+     * const instance = new DateTimeUtilityInstance('America/Denver');
+     * const date = instance.timeStringToDate('3:00PM');
+     * const dateWithRef = instance.timeStringToDate('3:00PM', { date: new Date('2024-06-15') });
+     * ```
      */
     timeStringToDate(input: ReadableTimeString | LogicalDateStringCode, config?: ParseTimeString): Maybe<Date>;
     _timeStringToDate(input: ReadableTimeString | LogicalDateStringCode, config?: ParseTimeString): DateFromTimestringResult | ValidDateFromTimestringResult;
     private _normalizeInstanceForConfig;
 }
+/**
+ * Creates a {@link DateTimeUtilityInstance} configured for UTC.
+ *
+ * @example
+ * ```ts
+ * const utcInstance = dateTimeInstanceUtc();
+ * const timeStr = utcInstance.toTimeString(new Date()); // e.g., '5:30PM'
+ * ```
+ */
 export declare function dateTimeInstanceUtc(): DateTimeUtilityInstance;
+/**
+ * Factory function that creates a {@link DateTimeUtilityInstance} for the given timezone.
+ * Defaults to UTC when no timezone is provided.
+ *
+ * @param timezone - The IANA timezone identifier (e.g., 'America/New_York').
+ *
+ * @example
+ * ```ts
+ * const nyInstance = dateTimeInstance('America/New_York');
+ * const date = nyInstance.timeStringToDate('9:00AM');
+ * ```
+ */
 export declare function dateTimeInstance(timezone?: Maybe<TimezoneString>): DateTimeUtilityInstance;
+/**
+ * Determines whether the given date falls in the AM or PM period for the specified timezone.
+ *
+ * @param date - The date to check. Defaults to now.
+ * @param timezone - The IANA timezone to evaluate in. Defaults to UTC.
+ *
+ * @example
+ * ```ts
+ * const amPm = getTimeAM(new Date(), 'America/Chicago');
+ * if (amPm === TimeAM.AM) {
+ *   console.log('Morning in Chicago');
+ * }
+ * ```
+ */
 export declare function getTimeAM(date?: Date, timezone?: Maybe<TimezoneString>): TimeAM;
 /**
- * Convenience function for toReadableTimeString that uses the current system timezone.
+ * Formats a date as a readable time string (e.g., "1:30PM") using the system's local timezone,
+ * unlike {@link toReadableTimeString} which defaults to UTC.
  *
- * @param date
- * @returns
+ * @param date - The date to format.
+ *
+ * @example
+ * ```ts
+ * const localTime = toLocalReadableTimeString(new Date()); // e.g., '9:45AM' in your local tz
+ * ```
  */
 export declare function toLocalReadableTimeString(date: Date): ReadableTimeString;
+/**
+ * Formats a date as a human-readable time string (e.g., "1:30PM") in the given timezone.
+ *
+ * @param date - The date to format.
+ * @param timezone - The IANA timezone to format in. Defaults to UTC.
+ *
+ * @example
+ * ```ts
+ * const time = toReadableTimeString(new Date(), 'America/New_York'); // e.g., '10:30AM'
+ * const utcTime = toReadableTimeString(new Date()); // UTC time
+ * ```
+ */
 export declare function toReadableTimeString(date: Date, timezone?: Maybe<TimezoneString>): ReadableTimeString;
 /**
- * Parses the input string relative to the timezone in the configuration.
+ * Parses a readable time string into a {@link ParsedTimeString} relative to the configured timezone.
+ * Falls back to UTC when no timezone is provided in the config.
  *
- * If no conversion timezone is provided, then it is parsed relative to UTC.
+ * @param input - A time string such as "1:30PM", "13:30", or "1PM".
+ * @param config - Optional configuration specifying the timezone and reference date.
  *
- * @param input
- * @param config
- * @returns
+ * @example
+ * ```ts
+ * const parsed = parseReadableTimeString('2:00PM', { timezone: 'America/Denver' });
+ * if (parsed) {
+ *   console.log(parsed.date); // 2:00PM Denver time as a Date
+ *   console.log(parsed.am);  // TimeAM.PM
+ * }
+ * ```
  */
 export declare function parseReadableTimeString(input: ReadableTimeString, config?: ParseTimeString): Maybe<ParsedTimeString>;
+/**
+ * Convenience function that parses a readable time string directly into a Date.
+ * Combines {@link dateTimeInstance} creation and {@link DateTimeUtilityInstance.timeStringToDate} in one call.
+ *
+ * @param input - A time string such as "1:30PM" or "13:30".
+ * @param config - Optional configuration specifying the timezone and reference date.
+ *
+ * @example
+ * ```ts
+ * const date = readableTimeStringToDate('9:00AM', { timezone: 'Europe/London' });
+ * ```
+ */
 export declare function readableTimeStringToDate(input: ReadableTimeString, config?: ParseTimeString): Maybe<Date>;
+/**
+ * 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.
+ *
+ * @example
+ * ```ts
+ * const limiter = limitDateTime({
+ *   limits: { isFuture: true, future: { hours: 1 } }
+ * });
+ * const clamped = limiter.clamp(someDate); // ensures date is at least 1 hour in the future
+ * ```
+ */
 export declare function limitDateTime(config: LimitDateTimeConfig): LimitDateTimeInstance;

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

@@ -45,7 +45,21 @@ export interface LimitDateTimeConfig {
     };
 }
 /**
- * Used for deriving a limit for the current instant in time.
+ * Derives min/max date boundaries from a {@link LimitDateTimeConfig} and provides clamping
+ * utilities for constraining dates and date ranges within those boundaries.
+ *
+ * Supports dynamic limits based on the current time (e.g., "must be in the future",
+ * "must be at least N minutes from now") as well as static min/max bounds.
+ *
+ * @example
+ * ```ts
+ * const limiter = new LimitDateTimeInstance({
+ *   limits: { isFuture: true, future: { hours: 2 } }
+ * });
+ *
+ * const range = limiter.dateRange(); // { start: <2 hours from now>, end: undefined }
+ * const clamped = limiter.clamp(someDate);
+ * ```
  */
 export declare class LimitDateTimeInstance {
     private readonly _config;
@@ -56,19 +70,68 @@ export declare class LimitDateTimeInstance {
     get min(): Maybe<LogicalDate>;
     get max(): Maybe<LogicalDate>;
     /**
-     * Creates a date range for now.
+     * Computes the allowed date range based on the configured limits, evaluated at the
+     * config's instant (or now if not set).
      *
-     * @returns
+     * @example
+     * ```ts
+     * const limiter = new LimitDateTimeInstance({ limits: { isFuture: true } });
+     * const range = limiter.dateRange(); // { start: <now>, end: undefined }
+     * ```
      */
     dateRange(): Partial<DateRange>;
+    /**
+     * Computes the allowed date range evaluated at a specific instant, allowing limits
+     * like "now" or relative future offsets to resolve against the given moment.
+     *
+     * @param instant - The reference point in time for resolving dynamic limits.
+     */
     dateRangeForInstant(instant: Date): {
         start: Date | undefined;
         end: Date | undefined;
     };
     /**
-     * Clamps the input date to the current range.
+     * Clamps the input date to the allowed range, optionally applying `takeNextUpcomingTime`
+     * (copies time to today, advancing to tomorrow if already past) or `roundDownToMinute`.
+     *
+     * @param date - The date to constrain.
+     *
+     * @example
+     * ```ts
+     * const limiter = new LimitDateTimeInstance({
+     *   limits: { isFuture: true, future: { minutes: 30 } }
+     * });
+     * const safe = limiter.clamp(new Date()); // at least 30 minutes from now
+     * ```
      */
     clamp(date: Date): Date;
+    /**
+     * Clamps an entire date range to fit within the allowed limits, constraining both
+     * start and end dates.
+     *
+     * @param dateRange - The date range to constrain.
+     *
+     * @example
+     * ```ts
+     * const limiter = new LimitDateTimeInstance({ limits: { isFuture: true } });
+     * const clamped = limiter.clampDateRange({ start: pastDate, end: futureDate });
+     * // clamped.start will be at least now
+     * ```
+     */
     clampDateRange(dateRange: DateRange): DateRange;
 }
+/**
+ * Factory function that creates a {@link LimitDateTimeInstance} from the given configuration.
+ *
+ * @param config - The limit configuration specifying bounds, future requirements, and rounding.
+ *
+ * @example
+ * ```ts
+ * const limiter = limitDateTimeInstance({
+ *   limits: { min: new Date('2024-01-01'), isFuture: true },
+ *   roundDownToMinute: true
+ * });
+ * const clamped = limiter.clamp(someDate);
+ * ```
+ */
 export declare function limitDateTimeInstance(config: LimitDateTimeConfig): LimitDateTimeInstance;