@openmrs/esm-utils/dist/dates/date-util.d.ts

Helper utilities for OpenMRS

/**
 * @module
 * @category Date and Time
 */
import { type CalendarDate, type CalendarDateTime, type CalendarIdentifier, type ZonedDateTime } from '@internationalized/date';
import dayjs from 'dayjs';
export type DateInput = string | number | Date;
/**
 * This function checks whether a date string is the OpenMRS ISO format.
 * The format should be YYYY-MM-DDTHH:mm:ss.SSSZZ
 */
export declare function isOmrsDateStrict(omrsPayloadString: string): boolean;
/**
 * Checks if the provided date is today.
 *
 * @param date The date to check.
 * @returns `true` if the date is today, `false` otherwise.
 */
export declare function isOmrsDateToday(date: DateInput): boolean;
/**
 * Converts the object to a date object if it is an OpenMRS ISO date time string.
 * Otherwise returns null.
 */
export declare function toDateObjectStrict(omrsDateString: string): Date | null;
/**
 * Formats the input to OpenMRS ISO format: "YYYY-MM-DDTHH:mm:ss.SSSZZ".
 */
export declare function toOmrsIsoString(date: DateInput, toUTC?: boolean): string;
/**
 * Utility function to parse an arbitrary string into a date.
 * Uses `dayjs(dateString)`.
 */
export declare function parseDate(dateString: string): Date;
/**
 * Provides the name of the calendar to associate, as a default, with the given base locale.
 *
 * @example
 * ```
 * registerDefaultCalendar('en', 'buddhist') // sets the default calendar for the 'en' locale to Buddhist.
 * ```
 *
 * @param locale the locale to register this calendar for
 * @param calendar the calendar to use for this registration
 */
export declare function registerDefaultCalendar(locale: string, calendar: CalendarIdentifier): void;
/**
 * Retrieves the default calendar for the specified locale if any.
 *
 * @param locale the locale to look-up
 */
export declare function getDefaultCalendar(locale: Intl.Locale | string | undefined): CalendarIdentifier | undefined;
export type FormatDateMode = 'standard' | 'wide';
export type FormatDateOptions = {
    /**
     * The calendar to use when formatting this date.
     */
    calendar?: string;
    /**
     * The locale to use when formatting this date
     */
    locale?: string;
    /**
     * - `standard`: "03 Feb 2022"
     * - `wide`:     "03 — Feb — 2022"
     */
    mode: FormatDateMode;
    /**
     * Whether the time should be included in the output always (`true`),
     * never (`false`), or only when the input date is today (`for today`).
     */
    time: true | false | 'for today';
    /** Whether to include the day number */
    day: boolean;
    /** Whether to include the month number */
    month: boolean;
    /** Whether to include the year */
    year: boolean;
    /** The unicode numbering system to use */
    numberingSystem?: string;
    /**
     * Disables the special handling of dates that are today. If false
     * (the default), then dates that are today will be formatted as "Today"
     * in the locale language. If true, then dates that are today will be
     * formatted the same as all other dates.
     */
    noToday: boolean;
};
/**
 * Formats the string representing a date, including partial representations of dates, according to the current
 * locale and the given options.
 *
 * Default options:
 *  - mode: "standard",
 *  - time: "for today",
 *  - day: true,
 *  - month: true,
 *  - year: true
 *  - noToday: false
 *
 * If the date is today then "Today" is produced (in the locale language).
 * This behavior can be disabled with `noToday: true`.
 *
 * When time is included, it is appended with a comma and a space. This
 * agrees with the output of `Date.prototype.toLocaleString` for *most*
 * locales.
 *
 * @param dateString The date string to parse and format.
 * @param options Optional formatting options.
 * @returns The formatted date string, or `null` if the input cannot be parsed.
 */
export declare function formatPartialDate(dateString: string, options?: Partial<FormatDateOptions>): string | null;
/**
 * Formats the input date according to the current locale and the
 * given options.
 *
 * Default options:
 *  - mode: "standard",
 *  - time: "for today",
 *  - day: true,
 *  - month: true,
 *  - year: true
 *  - noToday: false
 *
 * If the date is today then "Today" is produced (in the locale language).
 * This behavior can be disabled with `noToday: true`.
 *
 * When time is included, it is appended with a comma and a space. This
 * agrees with the output of `Date.prototype.toLocaleString` for *most*
 * locales.
 *
 * @param date The date to format.
 * @param options Optional formatting options.
 * @returns The formatted date string.
 */
export declare function formatDate(date: Date, options?: Partial<FormatDateOptions>): string;
/**
 * Formats the input as a time, according to the current locale.
 * 12-hour or 24-hour clock depends on locale.
 *
 * @param date The date whose time portion should be formatted.
 * @returns The formatted time string (e.g., "2:30 PM" or "14:30").
 */
export declare function formatTime(date: Date): string;
/**
 * Formats the input into a string showing the date and time, according
 * to the current locale. The `mode` parameter is as described for
 * `formatDate`.
 *
 * This is created by concatenating the results of `formatDate`
 * and `formatTime` with a comma and space. This agrees with the
 * output of `Date.prototype.toLocaleString` for *most* locales.
 *
 * @param date The date to format.
 * @param options Optional formatting options (same as formatDate, except time is always included).
 * @returns The formatted date and time string.
 */
export declare function formatDatetime(date: Date, options?: Partial<Omit<FormatDateOptions, 'time'>>): string;
/**
 * Converts a calendar date to the equivalent locale calendar date.
 * @returns CalendarDate
 */
export declare function convertToLocaleCalendar(date: CalendarDate | CalendarDateTime | ZonedDateTime, locale: string | Intl.Locale): CalendarDate | CalendarDateTime | ZonedDateTime;
/**
 * Formats the input duration according to the current locale.
 *
 * @param duration The duration to format (DurationInput object).
 * @param options Optional options for formatting.
 * @returns The formatted duration string.
 */
export declare function formatDuration(duration: Intl.DurationInput, options?: Intl.DurationFormatOptions): string;
/**
 * Parses a date input into a dayjs object. String inputs are interpreted using
 * any-date-parser with corrections for its month/day representation differences
 * with dayjs. Non-string inputs are passed directly to dayjs.
 *
 * @param dateInput The date to parse.
 * @param referenceDate Used as the base when resolving partial string dates (e.g., '2000' resolves missing fields from this date).
 * @returns A dayjs object, or null if the string could not be parsed.
 */
export declare function parseDateInput(dateInput: dayjs.ConfigType, referenceDate: dayjs.Dayjs): dayjs.Dayjs | null;
type DurationUnitPlural = 'seconds' | 'minutes' | 'hours' | 'days' | 'months' | 'years';
type DurationUnitSingular = 'second' | 'minute' | 'hour' | 'day' | 'month' | 'year';
/** Accepts both singular ('year') and plural ('years') forms, mirroring Temporal.Duration.round(). */
export type DurationUnit = DurationUnitPlural | DurationUnitSingular;
export interface DurationOptions {
    /** Override auto-selection thresholds. Each value is in the unit's own terms (e.g., seconds: 30 means "use seconds if < 30 seconds"). */
    thresholds?: Partial<Record<DurationUnit, number>>;
    /**
     * Coarsest unit to include. Accepts 'auto' (default when smallestUnit is set),
     * which resolves to the largest non-zero unit or smallestUnit, whichever is greater.
     * Mirrors Temporal.Duration.round() behavior.
     */
    largestUnit?: DurationUnit | 'auto';
    /** Finest unit to include. Defaults to largestUnit when largestUnit is an explicit unit, giving a single-unit result. */
    smallestUnit?: DurationUnit;
}
export interface DurationOptionsWithFormat extends DurationOptions {
    /** Options passed to Intl.DurationFormat. Defaults to { style: 'short', localeMatcher: 'lookup' }. */
    formatOptions?: Intl.DurationFormatOptions;
}
/**
 * Calculates the duration between two dates as a structured duration object.
 *
 * When called with no options or a single unit string, the unit is auto-selected
 * using dayjs relativeTime thresholds:
 * - < 45 seconds → seconds
 * - < 45 minutes → minutes
 * - < 22 hours → hours
 * - < 26 days → days
 * - < 11 months → months
 * - otherwise → years
 *
 * With a {@link DurationOptions} object, you can override thresholds and/or request
 * a multi-unit decomposition via largestUnit/smallestUnit.
 *
 * @param startDate The start date. If null, returns null.
 * @param endDate Optional. Defaults to now.
 * @param options A unit string for single-unit output, or a DurationOptions object.
 * @returns A DurationInput object, or null if either date is null or unparseable.
 *
 * @example
 * // Auto-selects the appropriate unit
 * duration('2022-01-01', '2024-07-30') // => { years: 2 }
 *
 * @example
 * // Multi-unit decomposition
 * duration('2022-01-01', '2024-07-30', { largestUnit: 'year', smallestUnit: 'day' })
 * // => { years: 2, months: 6, days: 29 }
 */
export declare function duration(startDate: dayjs.ConfigType, endDate?: dayjs.ConfigType, options?: DurationUnit | DurationOptions): Intl.DurationInput | null;
/**
 * Calculates the duration between two dates and formats it as a locale-aware string.
 * Uses the same unit-selection logic as {@link duration} and delegates formatting
 * to {@link formatDuration}.
 *
 * @param startDate The start date. If null, returns null.
 * @param endDate Optional. Defaults to now.
 * @param options A unit string for single-unit output, or a {@link DurationOptionsWithFormat} object.
 *   The `formatOptions` field is passed to Intl.DurationFormat (defaults to short style).
 * @returns A formatted duration string, or null if either date is null or unparseable.
 *
 * @example
 * formatDurationBetween('2022-01-01', '2024-07-30') // => '2 yrs'
 *
 * @example
 * // Multi-unit with long-form formatting
 * formatDurationBetween('2022-01-01', '2024-07-30', {
 *   largestUnit: 'year',
 *   smallestUnit: 'day',
 *   formatOptions: { style: 'long' },
 * }) // => '2 years, 6 months, 29 days'
 */
export declare function formatDurationBetween(startDate: dayjs.ConfigType, endDate?: dayjs.ConfigType, options?: DurationUnit | DurationOptionsWithFormat): string | null;
export {};
//# sourceMappingURL=date-util.d.ts.map