import { type MaybeNot, type Maybe } from '../value/maybe.type';
/**
 * The past or future direction.
 */
export type DateRelativeDirection = 'past' | 'future';
/**
 * Hour, minute, or second as a string.
 */
export type DateHourMinuteOrSecond = 'hour' | 'minute' | 'second';
/**
 * A valid RFC3339 formatted date string.
 *
 * I.E. "2020-04-30 00:00:00.000Z" and "2020-04-30T00:00:00.000Z"
 *
 * The only difference between this and an ISO8601DateString is the spacing between the date and time is allowed, while in ISO8601DateString it is not.
 */
export type RFC3339DateString = string;
/**
 * A valid ISO8601 formatted date string.
 *
 * I.E. "2020-04-30T00:00:00.000Z"
 */
export type ISO8601DateString = string;
/**
 * Regular expression for validating ISO8601 date strings.
 *
 * TODO(FUTURE): Need to improve to support negative years.
 */
export declare const ISO_8601_DATE_STRING_REGEX: RegExp;
/**
 * Determines if a string is a valid ISO8601 date string.
 *
 * @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;
/**
 * A UTC date string.
 *
 * I.E. "Sat, 03 Feb 2001 04:05:06 GMT"
 */
export type UTCDateString = string;
/**
 * Match examples:
 *
 * Sat, 03 Feb 2001 04:05:06 GMT
 * Tue, 14 Mar 2023 12:34:56 UTC
 * Wed, 25 May 2024 20:45:07 EST
 */
export declare const UTC_DATE_STRING_REGEX: RegExp;
/**
 * Determines if a string is a valid UTC date string.
 *
 * @param input - The string to test
 * @returns True if the input is a valid UTC date string
 */
export declare function isUTCDateString(input: string): boolean;
/**
 * A full ISO8601 date string that is in UTC.
 *
 * I.E. "2020-04-30T00:00:00.000Z"
 */
export type ISO8601DateStringUTCFull = string;
/**
 * A valid timezone string.
 *
 * I.E. "UTC", "America/Denver", etc.
 */
export type TimezoneString = string;
/**
 * A timezone abbreviation (UTC, EST, etc).
 */
export type TimezoneAbbreviation = string;
/**
 * Object that references a TimezoneString.
 */
export interface TimezoneStringRef {
    timezone: TimezoneString;
}
/**
 * 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
 */
export declare function hasSameTimezone(a: Maybe<Partial<TimezoneStringRef>>, b: Maybe<Partial<TimezoneStringRef>>): boolean;
/**
 * Constant for the UTC timezone string, "UTC".
 */
export declare const UTC_TIMEZONE_STRING = "UTC";
/**
 * UTC
 */
export type UTCTimezoneAbbreviation = typeof UTC_TIMEZONE_STRING;
/**
 * Determines whether the input timezone string is considered UTC.
 * Returns true for null, undefined, or the string 'UTC'.
 *
 * @param timezone - The timezone string to check
 * @returns True if the timezone is considered UTC
 */
export declare function isConsideredUtcTimezoneString(timezone: Maybe<TimezoneString>): boolean;
export declare function isConsideredUtcTimezoneString(timezone: TimezoneString): boolean;
export declare function isConsideredUtcTimezoneString(timezone: 'UTC'): true;
export declare function isConsideredUtcTimezoneString(timezone: null): true;
export declare function isConsideredUtcTimezoneString(timezone: undefined): true;
/**
 * A Date or an ISO8601DateString.
 */
export type DateOrDateString = Date | ISO8601DateString;
/**
 * A full date string Formatted as ISO8601 with 4 digits for the year.
 *
 * Year, Month, Day
 *
 * I.E. 1921-06-23
 *
 * NOTE: Negative years and years with more than 4 digits are not supported/expected. Support can be added later, but will require adding a more complex regex, and improved parsing in @dereekb/date
 */
export type ISO8601DayString = string;
/**
 * A Date or an ISO8601DayString.
 */
export type DateOrDayString = Date | ISO8601DayString;
/**
 * Regex for an ISO8601DayString.
 */
export declare const ISO8601_DAY_STRING_REGEX: RegExp;
/**
 * Regex for a string that starts as an ISO8601DayString.
 */
export declare const ISO8601_DAY_STRING_START_REGEX: RegExp;
/**
 * Returns the start of the input date's UTC time in UTC.
 *
 * I.E. 2022-01-02T04:00:00.000Z in GMT-6 returns 2022-01-02
 *
 * @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;
/**
 * Returns the start of the system's local date in UTC.
 *
 * I.E. 2022-01-02T04:00:00.000Z in GMT-6 (10PM Jan 1st CST) returns 2022-01-01
 *
 * @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 - 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 - 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 - 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;
/**
 * Date that is represented by slashes. Is considered in the Month/Day/Year format.
 */
export type MonthDaySlashDate = string;
/**
 * Regex for a MonthDaySlashDate.
 */
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 - 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;
/**
 * Converts the input MonthDaySlashDate (MM/DD/YYYY) to an ISO8601DayString (YYYY-MM-DD).
 * 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)
 */
export declare function monthDaySlashDateToDateString(slashDate: MonthDaySlashDate): ISO8601DayString;
/**
 * Time in milliseconds since the epoch.
 *
 * Returned by Date.getTime().
 */
export type UnixDateTimeMillisecondsNumber = number;
/**
 * A date or a unix timestamp (in milliseconds)
 */
export type DateOrUnixDateTimeMillisecondsNumber = Date | UnixDateTimeMillisecondsNumber;
/**
 * Converts a Date object or unix timestamp (in milliseconds) to a Date object.
 *
 * @param input - Date object or unix timestamp (in milliseconds) to convert
 * @returns Date object if input is valid. Returns null/undefined if input is null/undefined
 */
export declare function dateFromDateOrTimeMillisecondsNumber(input: DateOrUnixDateTimeMillisecondsNumber): Date;
export declare function dateFromDateOrTimeMillisecondsNumber(input: MaybeNot): MaybeNot;
export declare function dateFromDateOrTimeMillisecondsNumber(input: Maybe<DateOrUnixDateTimeMillisecondsNumber>): Maybe<Date>;
/**
 * 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
 */
export declare function unixMillisecondsNumberToDate(dateTimeNumber: Maybe<UnixDateTimeMillisecondsNumber>): Maybe<Date>;
/**
 * Number of milliseconds.
 */
export type Milliseconds = number;
/**
 * A date or a number of milliseconds.
 */
export type DateOrMilliseconds = Date | Milliseconds;
/**
 * Converts the input DateOrMilliseconds to a Date.
 *
 * If the input is a Date, it is returned as is.
 *
 * If the input is a number of milliseconds, it is added to the current date.
 *
 * @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;
/**
 * Number of seconds.
 */
export type Seconds = number;
/**
 * Number of minutes.
 */
export type Minutes = number;
/**
 * Number of hours.
 */
export type Hours = number;
/**
 * Number of days.
 */
export type Days = number;
/**
 * Number of days in a year (ignoring leap years, which are 366 days).
 */
export declare const DAYS_IN_YEAR: Days;
/**
 * Number of hours in a day.
 */
export declare const HOURS_IN_DAY: Hours;
/**
 * Number of seconds in a minute.
 */
export declare const SECONDS_IN_MINUTE: Seconds;
/**
 * Number of minutes in a day.
 */
export declare const MINUTES_IN_DAY: Minutes;
/**
 * Number of minutes in an hour.
 */
export declare const MINUTES_IN_HOUR: Minutes;
/**
 * Number of seconds in an hour.
 */
export declare const SECONDS_IN_HOUR: Minutes;
/**
 * Number of milliseconds in a second.
 */
export declare const MS_IN_SECOND: Milliseconds;
/**
 * Number of milliseconds in a minute.
 */
export declare const MS_IN_MINUTE: Milliseconds;
/**
 * Number of milliseconds in an hour.
 */
export declare const MS_IN_HOUR: Milliseconds;
/**
 * Number of milliseconds in a day.
 */
export declare const MS_IN_DAY: Milliseconds;
/**
 * Number of days in a week.
 */
export declare const DAYS_IN_WEEK: Days;
/**
 * Number of milliseconds in a week.
 */
export declare const MS_IN_WEEK: Milliseconds;
/**
 * Day of the month, 1-31
 */
export type DayOfMonth = number;
/**
 * Month of the year, 1-12.
 *
 * NOTE: The month from Date.getMonth() is from 0-11. Use monthOfYearFromDate() to get the MonthOfYear value.
 */
export type MonthOfYear = number;
/**
 * Javascript Date month number. 0-11.
 */
export type DateMonth = number;
/**
 * Retrieves the MonthOfYear value (1-12) from the input Date in the current system timezone.
 *
 * Converts JavaScript's 0-based month (0-11) to a 1-based month (1-12).
 *
 * @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;
/**
 * Retrieves the MonthOfYear value (1-12) from the input Date in the UTC timezone.
 *
 * Converts JavaScript's 0-based month (0-11) to a 1-based month (1-12).
 *
 * @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
 */
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)
 */
export declare function makeDateMonthForMonthOfYear(monthOfYear: MonthOfYear): DateMonth;
/**
 * Year number. I.E. 2022
 */
export type YearNumber = number;
/**
 * Current state of the date relative to another date.
 */
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
 */
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
 */
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 - The date to check
 * @returns True if the date is in the past
 */
export declare function isPast(input: Date): boolean;
/**
 * Adds milliseconds to the input date, returning a new Date object.
 * If no date is input, then returns the input unchanged.
 *
 * @param input - The date to add milliseconds to
 * @param ms - The number of milliseconds to add (defaults to 0 if null or undefined)
 * @returns A new Date with the added milliseconds, or the original input if not a Date
 */
export declare function addMilliseconds(input: Date, ms: Maybe<Milliseconds>): Date;
export declare function addMilliseconds(input: MaybeNot, ms: Maybe<Milliseconds>): MaybeNot;
export declare function addMilliseconds(input: Maybe<Date>, ms: Maybe<Milliseconds>): Maybe<Date>;