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 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
 * ```
 *
 * @__NO_SIDE_EFFECTS__
 */
export declare function logicalDateStringCodeDateFactory(logicalDateStringCode: LogicalDateStringCode): FactoryWithInput<Date, Date>;
/**
 * 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
 *
 * @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;