@dereekb/date 13.0.7 → 13.1.0

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

@@ -2,24 +2,37 @@ import { type DateOrDateString, type DateOrDayString, type ISO8601DateString, ty
 import { formatDistance, formatDistanceStrict } from 'date-fns';
 import { type DateRange } from './date.range';
 import { type DateTimezoneUtcNormalFunctionInput } from './date.timezone';
+/**
+ * Maps a Date to a formatted string representation.
+ */
 export type FormatDateFunction = MapFunction<Date, string>;
+/**
+ * Formats a DateRange into a human-readable string. Only accepts a DateRange input.
+ */
 export type FormatStrictDateRangeFunction = (startOrDateRange: DateRange) => string;
+/**
+ * Formats a date range into a human-readable string. Accepts either a DateRange object
+ * or separate start/end Date arguments.
+ */
 export type FormatDateRangeFunction = FormatStrictDateRangeFunction & ((startOrDateRange: Date, inputEnd?: Date) => string);
+/**
+ * Configuration for creating a {@link FormatDateRangeFunction} via {@link formatDateRangeFunction}.
+ */
 export interface FormatDateRangeFunctionConfig {
     /**
-     * Formats function
+     * Function used to format each individual date in the range.
      */
     format: FormatDateFunction;
     /**
-     * Whether or not to modify the dates to be relative to UTC instead of the current.
+     * Whether to normalize dates to UTC before formatting.
      */
     normalizeToUTC?: boolean;
     /**
-     * Custom separator
+     * Separator string placed between the formatted start and end dates. Defaults to `'-'`.
      */
     separator?: string;
     /**
-     * Whether or not to allow only printing a single date if the date range is the same.
+     * Whether to output a single formatted date when both dates fall on the same day.
      *
      * False by default.
      */
@@ -27,18 +40,49 @@ export interface FormatDateRangeFunctionConfig {
 }
 export type FormatDateRangeFunctionConfigInput = FormatDateFunction | FormatDateRangeFunctionConfig;
 /**
- * Creates a FormatDateRangeFunction using the input config.
+ * Creates a reusable {@link FormatDateRangeFunction} from the given config or format function.
+ *
+ * Useful when the same range formatting logic needs to be applied repeatedly with consistent settings.
+ *
+ * @param inputConfig - format function or full configuration
  *
- * @param inputConfig
- * @returns
+ * @example
+ * ```ts
+ * import { formatDateRangeFunction, formatToTimeString } from '@dereekb/date';
+ *
+ * const formatRange = formatDateRangeFunction({
+ *   format: formatToTimeString,
+ *   separator: 'to',
+ *   simplifySameDate: true
+ * });
+ *
+ * const result = formatRange({ start: new Date('2024-01-15T09:00:00'), end: new Date('2024-01-15T17:00:00') });
+ * // "9:00 AM to 5:00 PM"
+ * ```
  */
 export declare function formatDateRangeFunction(inputConfig: FormatDateRangeFunctionConfigInput): FormatDateRangeFunction;
 /**
- * Formats the input date range using the start and end dates and a format function.
+ * Convenience function that formats a date range in a single call without creating a reusable function.
+ *
+ * @param range - date range to format
+ * @param inputConfig - format function or full configuration
+ * @param separator - optional separator override when inputConfig is a function
+ *
+ * @example
+ * ```ts
+ * import { formatDateRange, formatToTimeString } from '@dereekb/date';
+ *
+ * const result = formatDateRange(
+ *   { start: new Date('2024-01-15T09:00:00'), end: new Date('2024-01-15T17:00:00') },
+ *   formatToTimeString
+ * );
+ * // "9:00 AM - 5:00 PM"
+ * ```
  */
 export declare function formatDateRange(range: DateRange, inputConfig: FormatDateRangeFunctionConfigInput, separator?: string): string;
 /**
- * formatDateRangeDistanceFunction() configuration
+ * Configuration for {@link formatDateRangeDistanceFunction}. Extends date-fns `formatDistance`/`formatDistanceStrict` options
+ * to control how the human-readable distance string is produced.
  */
 export type FormatDateRangeDistanceFunctionConfig = {
     /**
@@ -65,93 +109,368 @@ export type FormatDateRangeDistanceFunctionConfig = {
     strict: true;
 }));
 /**
- * Formats the input date range using the start and end dates and distance format function
+ * Creates a reusable function that computes the human-readable distance between the start and end of a date range
+ * (e.g., "3 hours", "about 2 days"). Delegates to date-fns `formatDistance` or `formatDistanceStrict`.
+ *
+ * @param inputConfig - controls distance formatting, optional transforms, and same-day handling
+ *
+ * @example
+ * ```ts
+ * import { formatDateRangeDistanceFunction } from '@dereekb/date';
+ *
+ * const formatDist = formatDateRangeDistanceFunction({ strict: true, unit: 'hour' });
+ * const result = formatDist({ start: new Date('2024-01-15T09:00:00'), end: new Date('2024-01-15T17:00:00') });
+ * // "8 hours"
+ * ```
  */
 export declare function formatDateRangeDistanceFunction(inputConfig: FormatDateRangeDistanceFunctionConfig): FormatDateRangeFunction;
 /**
- * Legacy format date distance function that will format the input as start of day to end of day.
+ * Pre-configured {@link FormatDateRangeFunction} that computes the distance between the start-of-day
+ * representations of two dates. Returns `'Today'` or `'Same Day'` when both dates fall on the same calendar day.
+ *
+ * Primarily retained for backward compatibility; prefer building a custom function via
+ * {@link formatDateRangeDistanceFunction} for new use cases.
  */
 export declare const formatDateDistance: FormatDateRangeFunction;
 /**
- * Formats the range between the two dates into a string.
+ * Convenience function that computes the human-readable distance for a date range in a single call.
  *
- * @param range
- * @param inputConfig
- * @returns
+ * @param range - date range to compute distance for
+ * @param inputConfig - optional distance formatting configuration
+ *
+ * @example
+ * ```ts
+ * import { formatDateRangeDistance } from '@dereekb/date';
+ *
+ * const result = formatDateRangeDistance(
+ *   { start: new Date('2024-01-15T09:00:00'), end: new Date('2024-01-17T09:00:00') },
+ *   { addSuffix: true }
+ * );
+ * // "in 2 days"
+ * ```
  */
 export declare function formatDateRangeDistance(range: DateRange, inputConfig?: FormatDateRangeDistanceFunctionConfig): string;
 /**
- * Formats the input dates to be time start - end using formatToTimeString().
+ * Formats a date range as a time-only range string when both dates are on the same day,
+ * or falls back to a full date+time range when they span multiple days.
+ *
+ * Same day: `"12:00 AM - 4:00 PM"`
+ * Different days: `"01/01/2001 12:00 AM - 01/02/2001 4:00 PM"`
  *
- * I.E. 12:00AM - 4:00PM
+ * @example
+ * ```ts
+ * import { formatToTimeRangeString } from '@dereekb/date';
  *
- * If the input dates are on different days, then the format will come from formatToDayTimeRangeString().
+ * // Same day - time only
+ * formatToTimeRangeString({ start: new Date('2024-01-15T09:00:00'), end: new Date('2024-01-15T17:00:00') });
+ * // "9:00 AM - 5:00 PM"
  *
- * I.E. 1/1/2001 12:00AM - 1/2/2001 4:00PM
+ * // Different days - includes date
+ * formatToTimeRangeString({ start: new Date('2024-01-15T09:00:00'), end: new Date('2024-01-16T17:00:00') });
+ * // "01/15/2024 9:00 AM - 01/16/2024 5:00 PM"
+ * ```
  */
 export declare function formatToTimeRangeString(startOrDateRange: DateRange): string;
 export declare function formatToTimeRangeString(start: Date, end?: Maybe<Date>): string;
 export declare function formatToTimeRangeString(startOrDateRange: DateRange | Date, end?: Maybe<Date>, onlyTimeRange?: boolean): string;
 /**
- * Formats the input dates to be date start - end using formatToShortDateAndTimeString().
+ * Formats a date range as a full date+time range string, always including the date portion
+ * regardless of whether both dates fall on the same day.
  *
- * I.E. 1/1/2001 12:00AM - 1/2/2001 4:00PM
+ * Output: `"01/01/2001 12:00 AM - 01/02/2001 4:00 PM"`
+ *
+ * @example
+ * ```ts
+ * import { formatToDayTimeRangeString } from '@dereekb/date';
+ *
+ * formatToDayTimeRangeString({ start: new Date('2024-01-15T09:00:00'), end: new Date('2024-01-16T17:00:00') });
+ * // "01/15/2024 9:00 AM - 01/16/2024 5:00 PM"
+ * ```
  */
 export declare function formatToDayTimeRangeString(startOrDateRange: DateRange): string;
 export declare function formatToDayTimeRangeString(start: Date, end?: Maybe<Date>): string;
 /**
- * Formats the input dates to be date start - end using formatToShortDateString(). Can alternatively specify a custom format function.
+ * Formats a date range as a day-only range string using `MM/dd/yyyy` by default. When both dates
+ * fall on the same day, only a single date is printed. Accepts an optional custom format function.
+ *
+ * Output: `"02/01/1992 - 03/01/1992"` or `"02/01/1992"` if same day
  *
- * I.E. 02/01/1992 - 03/01/1992
+ * @example
+ * ```ts
+ * import { formatToDayRangeString } from '@dereekb/date';
+ *
+ * formatToDayRangeString({ start: new Date('2024-01-15'), end: new Date('2024-01-20') });
+ * // "01/15/2024 - 01/20/2024"
+ *
+ * formatToDayRangeString({ start: new Date('2024-01-15'), end: new Date('2024-01-15') });
+ * // "01/15/2024"
+ * ```
  */
 export declare function formatToDayRangeString(startOrDateRange: DateRange, format?: FormatDateFunction): string;
 export declare function formatToDayRangeString(start: Date, end?: Maybe<Date>, format?: FormatDateFunction): string;
 /**
- * Safely formats the input to an ISO8601DateString if possible, otherwise returns undefined.
+ * Safely formats the input to an ISO 8601 date string, returning `undefined` for invalid or nullish inputs
+ * instead of throwing.
+ *
+ * @param input - date, date string, or nullish value
+ *
+ * @example
+ * ```ts
+ * import { safeFormatToISO8601DateString } from '@dereekb/date';
+ *
+ * safeFormatToISO8601DateString(new Date('2024-01-15T12:00:00Z'));
+ * // "2024-01-15T12:00:00.000Z"
+ *
+ * safeFormatToISO8601DateString(null);
+ * // undefined
  *
- * @param input
- * @returns
+ * safeFormatToISO8601DateString('invalid');
+ * // undefined
+ * ```
  */
 export declare function safeFormatToISO8601DateString(input: Maybe<DateOrDateString | UTCDateString>): ISO8601DateString | undefined;
+/**
+ * Formats a Date to a full ISO 8601 date-time string via `Date.toISOString()`. Defaults to the current date/time.
+ *
+ * @param date - date to format; defaults to `new Date()`
+ *
+ * @example
+ * ```ts
+ * import { formatToISO8601DateString } from '@dereekb/date';
+ *
+ * formatToISO8601DateString(new Date('2024-01-15T12:00:00Z'));
+ * // "2024-01-15T12:00:00.000Z"
+ * ```
+ */
 export declare function formatToISO8601DateString(date?: Date): ISO8601DayString;
 /**
- * Converts the input Date or ISO8601DayString to an ISO8601DayString using the system's date (not UTC date).
+ * Converts a Date or day string to an ISO 8601 day string (`yyyy-MM-dd`) using the **system timezone**.
+ * If the input is already a string, it is returned as-is.
+ *
+ * Use {@link toISO8601DayStringForUTC} when the UTC date is needed instead.
  *
- * Use formatToISO8601DayStringForUTC() for using the UTC date.
+ * @param dateOrString - date or existing day string
  *
- * @param dateOrString
- * @returns
+ * @example
+ * ```ts
+ * import { toISO8601DayStringForSystem } from '@dereekb/date';
+ *
+ * toISO8601DayStringForSystem(new Date('2024-01-15T20:00:00'));
+ * // "2024-01-15" (in system timezone)
+ *
+ * toISO8601DayStringForSystem('2024-01-15');
+ * // "2024-01-15" (pass-through)
+ * ```
  */
 export declare function toISO8601DayStringForSystem(dateOrString: DateOrDayString): ISO8601DayString;
+/**
+ * Formats a Date to an ISO 8601 day string (`yyyy-MM-dd`) using the **system timezone**.
+ * Defaults to the current date.
+ *
+ * @param date - date to format; defaults to `new Date()`
+ *
+ * @example
+ * ```ts
+ * import { formatToISO8601DayStringForSystem } from '@dereekb/date';
+ *
+ * formatToISO8601DayStringForSystem(new Date('2024-01-15T20:00:00'));
+ * // "2024-01-15"
+ * ```
+ */
 export declare function formatToISO8601DayStringForSystem(date?: Date): ISO8601DayString;
 /**
- * Converts the input Date or ISO8601DayString to an ISO8601DayString using the UTC date.
+ * Converts a Date or day string to an ISO 8601 day string (`yyyy-MM-dd`) using the **UTC date**.
+ * If the input is already a string, it is returned as-is.
+ *
+ * Use {@link toISO8601DayStringForSystem} when the system-local date is needed instead.
+ *
+ * @param dateOrString - date or existing day string
  *
- * @param dateOrString
- * @returns
+ * @example
+ * ```ts
+ * import { toISO8601DayStringForUTC } from '@dereekb/date';
+ *
+ * // When system is UTC-5, this date is Jan 16 in UTC
+ * toISO8601DayStringForUTC(new Date('2024-01-16T02:00:00Z'));
+ * // "2024-01-16"
+ *
+ * toISO8601DayStringForUTC('2024-01-15');
+ * // "2024-01-15" (pass-through)
+ * ```
  */
 export declare function toISO8601DayStringForUTC(dateOrString: DateOrDayString): ISO8601DayString;
+/**
+ * Formats a Date to an ISO 8601 day string (`yyyy-MM-dd`) using the **UTC date** components.
+ * Defaults to the current date.
+ *
+ * @param date - date to format; defaults to `new Date()`
+ *
+ * @example
+ * ```ts
+ * import { formatToISO8601DayStringForUTC } from '@dereekb/date';
+ *
+ * formatToISO8601DayStringForUTC(new Date('2024-01-15T12:00:00Z'));
+ * // "2024-01-15"
+ * ```
+ */
 export declare function formatToISO8601DayStringForUTC(date?: Date): ISO8601DayString;
+/** date-fns format string for `MM/dd/yyyy` (e.g., `"01/15/2024"`). */
 export declare const monthDaySlashDateStringFormat = "MM/dd/yyyy";
+/**
+ * Formats a Date as a month/day/year slash-separated string (`MM/dd/yyyy`). Defaults to the current date.
+ *
+ * @param date - date to format; defaults to `new Date()`
+ *
+ * @example
+ * ```ts
+ * import { formatToMonthDaySlashDate } from '@dereekb/date';
+ *
+ * formatToMonthDaySlashDate(new Date('2024-01-15'));
+ * // "01/15/2024"
+ * ```
+ */
 export declare function formatToMonthDaySlashDate(date?: Date): MonthDaySlashDate;
 /**
  * @deprecated use formatToMonthDaySlashDate instead.
  */
 export declare const formatToShortDateString: typeof formatToMonthDaySlashDate;
+/** date-fns format string for `MM/dd` (e.g., `"01/15"`). */
 export declare const dateMonthDayStringFormat = "MM/dd";
+/**
+ * Formats a Date as a month/day string (`MM/dd`) without the year. Defaults to the current date.
+ *
+ * @param date - date to format; defaults to `new Date()`
+ *
+ * @example
+ * ```ts
+ * import { formatToMonthDayString } from '@dereekb/date';
+ *
+ * formatToMonthDayString(new Date('2024-01-15'));
+ * // "01/15"
+ * ```
+ */
 export declare function formatToMonthDayString(date?: Date): ISO8601DayString;
+/**
+ * Formats a Date as a human-friendly weekday and month/day string (e.g., `"Mon, Jan 15th"`).
+ *
+ * @param date - date to format
+ *
+ * @example
+ * ```ts
+ * import { formatToDateString } from '@dereekb/date';
+ *
+ * formatToDateString(new Date('2024-01-15'));
+ * // "Mon, Jan 15th"
+ * ```
+ */
 export declare function formatToDateString(date: Date): string;
+/** date-fns format string for 12-hour time with AM/PM (e.g., `"9:00 AM"`). */
 export declare const dateTimeStringFormat = "h:mm a";
+/**
+ * Formats a Date as a 12-hour time string with AM/PM (e.g., `"9:00 AM"`).
+ *
+ * @param date - date to format
+ *
+ * @example
+ * ```ts
+ * import { formatToTimeString } from '@dereekb/date';
+ *
+ * formatToTimeString(new Date('2024-01-15T14:30:00'));
+ * // "2:30 PM"
+ * ```
+ */
 export declare function formatToTimeString(date: Date): string;
+/** Combined date-fns format string for `MM/dd/yyyy h:mm a` (e.g., `"01/15/2024 9:00 AM"`). */
 export declare const dateShortDateAndTimeStringFormat = "MM/dd/yyyy h:mm a";
+/**
+ * Formats a Date as a short date and time string (e.g., `"01/15/2024 9:00 AM"`).
+ *
+ * @param date - date to format
+ *
+ * @example
+ * ```ts
+ * import { formatToShortDateAndTimeString } from '@dereekb/date';
+ *
+ * formatToShortDateAndTimeString(new Date('2024-01-15T14:30:00'));
+ * // "01/15/2024 2:30 PM"
+ * ```
+ */
 export declare function formatToShortDateAndTimeString(date: Date): string;
+/**
+ * Formats a start time with an appended duration indicator. For durations over 2 hours, uses
+ * a human-readable distance (e.g., `"about 3 hours"`); otherwise shows exact minutes.
+ *
+ * @param start - start date/time
+ * @param end - end date/time
+ *
+ * @example
+ * ```ts
+ * import { formatToTimeAndDurationString } from '@dereekb/date';
+ *
+ * // Short duration
+ * formatToTimeAndDurationString(new Date('2024-01-15T09:00:00'), new Date('2024-01-15T10:30:00'));
+ * // "9:00 AM (90 Minutes)"
+ *
+ * // Long duration
+ * formatToTimeAndDurationString(new Date('2024-01-15T09:00:00'), new Date('2024-01-15T14:00:00'));
+ * // "9:00 AM (about 5 hours)"
+ * ```
+ */
 export declare function formatToTimeAndDurationString(start: Date, end: Date): string;
+/**
+ * Produces a relative-time label describing a date range's state relative to now:
+ * past (`"ended 2 hours ago"`), present (`"started 30 minutes ago"`), or future (`"starting in 3 days"`).
+ *
+ * @example
+ * ```ts
+ * import { formatStartedEndedDistanceString } from '@dereekb/date';
+ *
+ * // Range in the past
+ * const pastRange = { start: new Date('2024-01-10'), end: new Date('2024-01-12') };
+ * formatStartedEndedDistanceString(pastRange);
+ * // "ended about 1 year ago"
+ *
+ * // Range currently active
+ * const now = new Date();
+ * const activeRange = { start: new Date(now.getTime() - 3600000), end: new Date(now.getTime() + 3600000) };
+ * formatStartedEndedDistanceString(activeRange);
+ * // "started about 1 hour ago"
+ * ```
+ */
 export declare function formatStartedEndedDistanceString({ start, end }: DateRange): string;
 /**
- * Returns the input date as the start of the day in the system timezone, or parses the input ISO8601DayString to the start of the day in the system timezone.
+ * Normalizes a Date or ISO 8601 day string to the start of the day in the system timezone.
+ * Useful for converting heterogeneous date inputs into a consistent midnight-aligned Date.
+ *
+ * @param input - date or day string to normalize
+ *
+ * @example
+ * ```ts
+ * import { toJsDayDate } from '@dereekb/date';
+ *
+ * toJsDayDate(new Date('2024-01-15T14:30:00'));
+ * // Date representing 2024-01-15T00:00:00 (system timezone)
  *
- * @param input
- * @returns
+ * toJsDayDate('2024-01-15');
+ * // Date representing 2024-01-15T00:00:00 (system timezone)
+ * ```
  */
 export declare function toJsDayDate(input: DateOrDayString): Date;
+/**
+ * Parses an ISO 8601 day string (e.g., `"2024-01-15"`) or full date string into a Date at the start of the day
+ * in the system timezone. Supports year formats with more than 4 digits but does not support negative years.
+ *
+ * @param dayString - ISO 8601 day or date string to parse
+ *
+ * @example
+ * ```ts
+ * import { parseISO8601DayStringToDate } from '@dereekb/date';
+ *
+ * parseISO8601DayStringToDate('2024-01-15');
+ * // Date representing 2024-01-15T00:00:00 (system timezone)
+ *
+ * parseISO8601DayStringToDate('2024-01-15T14:30:00Z');
+ * // Date representing 2024-01-15T00:00:00 (system timezone, time portion stripped)
+ * ```
+ */
 export declare function parseISO8601DayStringToDate(dayString: ISO8601DayString | ISO8601DateString): Date;

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

@@ -1,4 +1,15 @@
 import { HashSet } from '@dereekb/util';
+/**
+ * A {@link HashSet} specialized for Date values, using the millisecond timestamp as the hash key.
+ *
+ * Provides O(1) lookup, add, and delete for Date values based on exact time equality.
+ *
+ * @example
+ * ```ts
+ * const set = new DateSet([new Date('2024-01-01'), new Date('2024-01-02')]);
+ * set.has(new Date('2024-01-01')); // true (same timestamp)
+ * ```
+ */
 export declare class DateSet extends HashSet<number, Date> {
     constructor(values?: Date[]);
 }

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

@@ -1,23 +1,81 @@
 import { type DateNow, type Maybe, type FactoryWithInput } from '@dereekb/util';
+/**
+ * String code for the start of the current day.
+ */
 export declare const DATE_TODAY_START_VALUE = "today_start";
 export type DateTodayStart = typeof DATE_TODAY_START_VALUE;
+/**
+ * String code for the end of the current day.
+ */
 export declare const DATE_TODAY_END_VALUE = "today_end";
 export type DateTodayEnd = typeof DATE_TODAY_END_VALUE;
+/**
+ * String code for the start of the current week.
+ */
 export declare const DATE_WEEK_START_VALUE = "this_week_start";
 export type DateWeekStart = typeof DATE_WEEK_START_VALUE;
+/**
+ * String code for the end of the current week.
+ */
 export declare const DATE_WEEK_END_VALUE = "this_week_end";
 export type DateWeekEnd = typeof DATE_WEEK_END_VALUE;
+/**
+ * Union of all recognized logical date string codes.
+ */
 export type LogicalDateStringCode = DateNow | DateTodayStart | DateTodayEnd | DateWeekStart | DateWeekEnd;
 /**
- * A date that is characterized by either a known string value, or a Date.
+ * A date that is characterized by either a known string code or a concrete Date value.
+ *
+ * Used to express relative date references (e.g. "today_start") that resolve at evaluation time.
  */
 export type LogicalDate = Date | LogicalDateStringCode;
+/**
+ * Creates a factory function that resolves a {@link LogicalDateStringCode} to a concrete Date relative to an input reference date.
+ *
+ * @param logicalDateStringCode - the logical date code to resolve
+ * @returns a factory that accepts an optional reference date and returns the resolved Date
+ * @throws {Error} when the input code is not a recognized {@link LogicalDateStringCode}
+ *
+ * @example
+ * ```ts
+ * const factory = logicalDateStringCodeDateFactory('today_start');
+ * const startOfToday = factory(new Date('2024-06-15T14:30:00Z'));
+ * // startOfToday is 2024-06-15T00:00:00 in the system timezone
+ * ```
+ */
 export declare function logicalDateStringCodeDateFactory(logicalDateStringCode: LogicalDateStringCode): FactoryWithInput<Date, Date>;
 /**
- * Returns a Date value from the input LogicalDate.
+ * Resolves a {@link LogicalDate} to a concrete Date value.
+ *
+ * If the input is a string code, it is resolved relative to the given reference date (or now).
+ * If the input is already a Date, it is returned as-is.
+ *
+ * @param logicalDate - the logical date to resolve (string code or Date)
+ * @param now - optional reference date (defaults to current time)
+ * @returns the resolved Date, or undefined/null if input is nullish
  *
- * @param logicalDate
+ * @example
+ * ```ts
+ * const date = dateFromLogicalDate('today_end', new Date('2024-06-15T10:00:00Z'));
+ * // date is end of day 2024-06-15 in the system timezone
+ *
+ * const same = dateFromLogicalDate(new Date('2024-01-01'));
+ * // same is the exact Date passed in
+ * ```
  */
 export declare function dateFromLogicalDate(logicalDate: LogicalDate, now?: Date): Date;
 export declare function dateFromLogicalDate(logicalDate: Maybe<LogicalDate>, now?: Date): Maybe<Date>;
+/**
+ * Type guard that checks whether the input is a recognized {@link LogicalDateStringCode}.
+ *
+ * @param logicalDate - value to check
+ * @returns true if the value is one of the known logical date string codes
+ *
+ * @example
+ * ```ts
+ * isLogicalDateStringCode('today_start'); // true
+ * isLogicalDateStringCode('not_a_code');  // false
+ * isLogicalDateStringCode(new Date());    // false
+ * ```
+ */
 export declare function isLogicalDateStringCode(logicalDate: Maybe<string | LogicalDate>): logicalDate is LogicalDateStringCode;