@villedemontreal/general-utils/dist/src/dateUtils.d.ts

General utilities library

import { Zone } from 'luxon';
import { Moment } from 'moment';
export declare function isDateEqual(value: DateDefinition, expectedDate: DateDefinition): boolean;
/** @see https://momentjs.com/docs/#/query/is-between/ */
export declare function isDateBetween(value: DateDefinition, expectedDate: DateRangeDefinition, inclusivity?: '()' | '[)' | '(]' | '[]'): boolean;
export type DateDefinition = string | Date | Moment;
export type DateRangeDefinition = [DateDefinition, DateDefinition];
export type CompatibleDateDefinition = DateDefinition | DateRangeDefinition;
/**
 * Tells whether the provided value is a date range.
 *
 * Valid date ranges are either:
 * - `[null, null]`: Open date range.
 * - `[Date, null]`: Date range with low boundary, without high boundary.
 * - `[null, Date]`: Date range without low boundary, with high boundary.
 * - `[Date, Date]`: Date range with both low and high boundaries.
 */
export declare function isDateRange(value: any[]): boolean;
/**
 * Returns a "safe" date from the given definition.
 *
 * - `String` values are not considered "safe" since they can contain anything, including invalid dates.
 * - `Moment` values are not considered "safe" since they tolerate exceptions and advanced
 * features that `Date` doesn't support.
 */
export declare function getSafeDate(dateDefinition: DateDefinition): Date;
/**
 * Returns a "safe" date range from the given definition.
 *
 * @see `#getSafeDate`
 */
export declare function getSafeDateRange(dateRangeDefinition: DateRangeDefinition): [Date, Date];
/**
 * Tells whether the provided date is compatible with the specified date definition.
 *
 * Possible cases:
 * - `value`: `Date` & `expectedDate`: `Date` → whether `value` = `expectedDate`.
 * - `value`: `Date` & `expectedDate`: `DateRange` → whether `value` is within `expectedDate`.
 */
export declare function isDateCompatible(value: DateDefinition, expectedDate: CompatibleDateDefinition): boolean;
export type TimeUnitSymbol = 'ms' | 's' | 'm' | 'h' | 'd' | 'w';
export declare function getDateRangeAround(value: DateDefinition, marginValue: number, marginUnit: TimeUnitSymbol): DateRangeDefinition;
/**
 * Pattern matching most ISO 8601 date representations (including time), and which can be used for any kind of validation.
 * @example `2018-07-31T12:34:56.789+10:11`
 */
export declare const ISO_DATE_PATTERN: RegExp;
/**
 * Tells whether the provided date representation is valid as per ISO 8601.
 *
 * @see `ISO_DATE_PATTERN`
 */
export declare function isValidIso8601Date(representation: string): boolean;
/**
 * Format used to represent dates, and which is compatible with Moment.js & others.
 * Note: It produces ISO-compatible dates, and which also works well with T-SQL.
 * @see `#parseDate`
 * @see `#formatDate`
 * @see https://momentjs.com/docs/#/displaying/format/
 */
export declare const DEFAULT_DATE_FORMAT = "YYYY-MM-DDTHH:mm:ss.SSSZ";
/**
 * Parses the given date representation using the provided format (or the default ISO format).
 * @see `#formatDate`
 */
export declare function parseDate(representation: string, format?: string | string[]): Date;
/**
 * Formats the given date using the provided format (or the default ISO format).
 *
 * @see `#parseDate`
 */
export declare function formatDate(date: DateDefinition, format?: string): string;
/**
 * Formats the UTC version of the given date using the provided format (or the default ISO format).
 *
 * @see `#formatDate`
 */
export declare function formatUtcDate(date: DateDefinition, format?: string): string;
/**
 * Return the specified date at its very beginning
 * "00:00:00.000".
 *
 * IMPORTANT: this function is very timezone sensitive!
 * If you want to start of day in another timezone than
 * 'America/Montreal', you *need* to specify it.
 * Here's why:
 *
 * Let say the specofoed ISO date is "2017-11-02T02:07:11.123Z".
 * If we are located in a UTC timezone, the end of day for
 * this date is "2017-11-02T23:59:59", it would be the same day
 * as the one displayed in the ISO string.
 * But if we are in Montreal, and the current timezone offset is "-4",
 * then the ISO date actually referes to the "2017-11-01" day and
 * start of day would need to be "2017-11-01T23:59:59", not
 * "2017-11-02T23:59:59"!
 *
 * By default, the handling of dates, by Node itself or by various
 * third-party, all use the timezone of the server to make calculations
 * such as "start of day". This is error-prone as the result depends
 * on how the server is configured. This is why a timezone must be
 * specified here.
 */
export declare function startOfDay(isoDate: Date | string, timezone?: string | Zone): Date;
/**
 * Return the specified date at its last milliseconds:
 * "23:59:59.999".
 *
 * IMPORTANT: this function is very timezone sensitive!
 * If you want to start of day in another timezone than
 * 'America/Montreal', you *need* to specify it.
 *
 * Please read the comments of the `startOfDay` for more
 * information.
 *
 */
export declare function endOfDay(isoDate: Date | string, timezone?: string | Zone): Date;
//# sourceMappingURL=dateUtils.d.ts.map