@resk/core
Version:
An innovative TypeScript framework that empowers developers to build applications with a fully decorator-based architecture for efficient resource management. By combining the power of decorators with a resource-oriented design, DecorRes enhances code cla
370 lines (369 loc) • 15.8 kB
TypeScript
import { IMomentFormat } from '../../types';
import isDateObj from "./isDateObj";
/**
* Result object returned by the date parser
*/
export interface IDateHelperResult {
/** The parsed Date object if successful */
date: Date | null;
/** The format that successfully parsed the date string, if any */
matchedFormat: string | null;
/** Whether the parsing was successful */
isValid: boolean;
/** Any error message if parsing failed */
error?: string;
}
export declare class DateHelper {
/**
* Comprehensive collection of date formats supported by Moment.js
*/
static DATE_FORMATS: Array<string>;
/**
* Parses a date string using an exhaustive list of commonly used date formats.
* The function attempts to parse the input string using multiple format patterns
* and returns the first successful match along with additional parsing information.
*
* @param dateString - The date string to parse
* @param preferredFormats - Optional array of preferred formats to try first
* @returns A {@link IDateHelperResult} object containing the parsing results
*
* @example
* ```typescript
* // Parse an ISO date string
* const result = parseDateString('2024-02-20');
* if (result.isValid) {
* console.log(result.date); // 2024-02-20T00:00:00.000Z
* console.log(result.matchedFormat); // 'YYYY-MM-DD'
* }
*
* // Parse with preferred formats
* const customResult = parseDateString('02/20/2024', ['MM/DD/YYYY']);
* ```
*
* @throws Will not throw errors, but returns error information in the result object
*
* @remarks
* The function tries formats in the following order:
* 1. Preferred formats (if provided)
* 2. ISO 8601 formats
* 3. US formats
* 4. European formats
* 5. Time formats
* 6. Relative formats
*/
static parseString(dateString: string, preferredFormats?: string[] | string): IDateHelperResult;
/**
* Converts a JavaScript Date object or string to ISO 8601 format in UTC (with 'Z' suffix).
*
* @param localDate - JavaScript Date object in local time
* @returns ISO 8601 formatted string in UTC (with 'Z' suffix)
*/
static toIsoString(localDate?: Date): string;
/**
* Converts an ISO string (in UTC) to a JavaScript Date object
*
* @param isoString - ISO 8601 formatted date string (e.g. "2025-02-25T12:00:00Z")
* @returns JavaScript Date object representing the specified time
*/
static isoStringToDate(isoString: string): Date;
/**
* Parses a date using the Moment.js library.
*
* @param {Date|string|number} date The date to parse.
* @param {string} [format] The format of the date, using Moment.js format. See https://momentjs.com/docs/#/parsing/string-format/
* @returns {Date|null} The parsed date, or null if the input is not a valid date.
*/
static parseDate(date: any, format?: IMomentFormat): Date | null;
/**
* Converts a date to SQL datetime format.
*
* @param {Date} datetime The date to convert.
* @returns {string} The date in SQL datetime format, or an empty string if the date is not valid.
*
* Example:
* ```ts
* const date = new Date();
* console.log(DateHelper.toSQLDateTimeFormat(date)); // Output: YYYY-MM-DD HH:MM:SS
* console.log(DateHelper.oSQLDateTimeFormat(null)); // Output: ""
* ```
*/
static toSQLDateTimeFormat(datetime: Date): string;
/**
* Get the default datetime format, according to the Moment.js library.
* it firstly tries to retrieve the default date time format from the translations (key: dates.defaultDateTimeFormat), and if it fails, it returns the default value.
*
* @description The format used to represent dates and times by default, as defined by the Moment.js library.
* @see https://momentjs.com/docs/#/parsing/string-format/
*/
static get DEFAULT_DATE_TIME_FORMAT(): IMomentFormat;
/**
* Get the default date format.
* It firstly tries to retrieve the default date time format from the translations (key: dates.defaultDateFormat), and if it fails, it returns the default value.
*
* @description The format used to represent dates by default.
*/
static get DEFAULT_DATE_FORMAT(): IMomentFormat;
/**
* Converts a date to SQL date format.
*
* @param {Date} datetime The date to convert.
* @returns {string} The date in SQL date format, or an empty string if the date is not valid.
*
* Example:
* ```ts
* const date = new Date();
* console.log(dateToSQLFormat(date)); // Output: YYYY-MM-DD
* console.log(dateToSQLFormat(null)); // Output: ""
* ```
*/
static toSQLDateFormat(datetime: Date): string;
/**
* Converts a date to SQL time format.
*
* @param {Date} datetime The date to convert.
* @returns {string} The date in SQL time format, or an empty string if the date is not valid.
*
* Example:
* ```ts
* const date = new Date();
* console.log(toSQLTimeFormat(date)); // Output: HH:MM:SS
* console.log(toSQLTimeFormat(null)); // Output: ""
* ```
*/
static toSQLTimeFormat(datetime: Date): string;
/**
* Get the default time format, according to the Moment.js library.
* It firstly tries to retrieve the default date time format from the translations (key: dates.defaultTimeFormat), and if it fails, it returns the default value.
*
* @description The format used to represent times by default, as defined by the Moment.js library.
* @see https://momentjs.com/docs/#/parsing/string-format/
*/
static get DEFAULT_TIME_FORMAT(): IMomentFormat;
/**
* Checks if the provided variable is a valid date, either in SQL format or as a Date object.
*
* @param {string|Date} sDate The date to test.
* @param {string} [format] The format of the date, using Moment.js format. See https://momentjs.com/docs/#/parsing/string-format/
* @returns {boolean} True if the date is valid, false otherwise.
*/
static isValidDate(sDate: any, format?: IMomentFormat): boolean;
/**
* The SQL date format, according to the Moment.js library.
* @description The format used to represent dates in SQL, as defined by the Moment.js library.
* @see https://momentjs.com/docs/#/parsing/string-format/
*/
static SQL_DATE_FORMAT: IMomentFormat;
/**
* The SQL datetime format, according to the Moment.js library.
*
* @description The format used to represent dates and times in SQL, as defined by the Moment.js library.
* @see https://momentjs.com/docs/#/parsing/
*/
static SQL_DATE_TIME_FORMAT: IMomentFormat;
/**
* The SQL time format, according to the Moment.js library.
*
* @description The format used to represent times in SQL, as defined by the Moment.js library.
* @see https://momentjs.com/docs/#/parsing/string-format/
*/
static SQL_TIME_FORMAT: IMomentFormat;
/**
* Adds days to a date.
*
* @param {number} days The number of days to add to the date.
* @param {Date|string} [date] The date to add days to. If not provided, the current date is used.
* @param {string} [setFunction] The type of date to add (e.g. 'FullYear', 'Month', 'Date', 'Hours', 'Minutes', 'Seconds', 'Milliseconds').
* @returns {Date|string} The date with the added days, either as a Date object or a string in the specified format.
*
* Example:
* ```ts
* console.log(DateHelper.addToDate(1)); // Output: Date object with 1 day added to the current date
* ```
*/
private static addToDate;
/**
* Adds the specified number of days to the date object.
*
* @param {number} days The number of days to add to the date.
* @param {Date|string} [date] The date object to add days to. If not provided, the current date is used.
* @returns {Date} The updated date.
*/
static addDays(days: number, date?: any): Date;
/**
* Adds the specified number of milliseconds to the date object.
*
* @param {number} milliseconds The number of milliseconds to add to the date.
* @param {Date} [dateObj] The date object to add milliseconds to. If not provided, the current date is used.
* @returns {Date} The updated date object with the added milliseconds.
*/
static addMilliseconds(milliseconds: number, dateObj?: Date): Date;
/**
* Adds the specified number of seconds to the date object.
*
* @param {number} seconds The number of seconds to add to the date.
* @param {Date} [dateObj] The date object to add seconds to. If not provided, the current date is used.
* @returns {Date} The updated date object with the added seconds.
*/
static addSeconds(seconds: number, dateObj?: any): Date;
/**
* Adds the specified number of minutes to the date object.
*
* @param {number} minutes The number of minutes to add to the date.
* @param {Date} [dateObj] The date object to add minutes to. If not provided, the current date is used.
* @returns {Date|string} The updated date object with the added minutes, or a string in the specified format.
*/
static addMinutes(minutes: number, dateObj?: any): Date;
/**
* Adds the specified number of hours to the date object.
*
* @param {number} hours The number of hours to add to the date.
* @param {Date} [dateObj] The date object to add hours to. If not provided, the current date is used.
* @returns {Date} The updated date object with the added hours.
*/
static addHours(hours: number, dateObj?: any): Date;
/**
* Adds the specified number of months to the date object.
*
* @param {number} months The number of months to add to the date.
* @param {Date|string} [date] The date object to add months to. If not provided, the current date is used.
* @returns {Date|string} The updated date, either as a Date object or a string in the specified format.
*/
static addMonths(months: number, date?: Date, format?: IMomentFormat): Date;
/**
* Adds the specified number of weeks to the date object.
*
* @param {number} weeks The number of weeks to add to the date.
* @param {Date|string} [date] The date object to add weeks to. If not provided, the current date is used.
* @returns {Date|string} The updated date, either as a Date object or a string in the specified format.
*/
static addWeeks(weeks: number, date?: Date): Date;
/**
* Adds the specified number of years to the date object.
*
* @param {number} years The number of years to add to the date.
* @param {Date|string} [date] The date object to add years to. If not provided, the current date is used.
* @returns {Date} The updated date.
*/
static addYears(years: number, date?: Date): Date;
/**
* Returns the first and last days of the current month.
*
* @param {Date} [date] The date object to use as the basis for the calculation. If not provided, the current date is used.
* @returns {{ first: Date, last: Date }} An object containing the first and last days of the month.
*
* Example:
* ```ts
* console.log(getCurrentMonthDaysRange()); // Output: { first: Date, last: Date }
* console.log(getCurrentMonthDaysRange(new Date("2022-01-15"))); // Output: { first: Date, last: Date }
* ```
*/
static getCurrentMonthDaysRange: (date?: any) => {
first: Date;
last: Date;
};
/**
* Returns the first and last days of the previous week.
*
* @param {Date} [date] The date object to use as the basis for the calculation. If not provided, the current date is used.
* @returns {{ first: Date, last: Date }} An object containing the first and last days of the previous week.
*
* Example:
* ```ts
* console.log(getPreviousWeekDaysRange()); // Output: { first: Date, last: Date }
* console.log(getPreviousWeekDaysRange(new Date("2022-01-15"))); // Output: { first: Date, last: Date }
* ```
*/
static getPreviousWeekDaysRange: (date?: any) => {
first: Date;
last: Date;
};
/**
* Returns the first and last days of the current week.
*
* @param {Date} [date] The date object to use as the basis for the calculation. If not provided, the current date is used.
* @returns {{ first: Date, last: Date }} An object containing the first and last days of the current week.
*
* Example:
* ```ts
* console.log(getCurrentWeekDaysRange()); // Output: { first: Date, last: Date }
* console.log(getCurrentWeekDaysRange(new Date("2022-01-15"))); // Output: { first: Date, last: Date }
* ```
*/
static getCurrentWeekDaysRange: (date?: any) => {
first: Date;
last: Date;
};
/**
* Formats a date to the specified moment format.
*
* @param {Date} [date] The date to format. If not provided, the current date is used.
* @param {string} [format] The moment format to use. If not provided, the default format is used.
* @returns {string} The formatted date string. If the input date is invalid, an empty string is returned.
*
* Example:
* ```ts
* console.log(formatDate()); // Output: Formatted current date
* console.log(formatDate(new Date("2022-01-15"))); // Output: Formatted date
* console.log(formatDate("2022-01-15", "YYYY-MM-DD")); // Output: Formatted date in YYYY-MM-DD format
* ```
*/
static formatDate(date?: Date, format?: IMomentFormat): string;
static isDateObj: typeof isDateObj;
/**
* Returns an object containing detailed information about a given date in UTC time.
*
* @param {Date} [date] - The date to get details from. If not provided, the current date will be used.
* @returns {Object} An object containing the year, day, month, month string, hours, date, minutes, seconds, month name, day name, and day name short in UTC time.
*
* @example
* const utcDateDetails = DateHelper.getUTCDateTimeDetails(new Date('2022-01-01'));
* console.log(utcDateDetails);
* // Output: { year: 2022, day: 6, month: 0, monthString: '01', hours: 0, date: 1, minutes: 0, seconds: 0, monthName: 'January', dayName: 'Saturday', dayNameShort: 'Sat' }
*/
static getUTCDateTimeDetails(date?: Date): {
/**
* The year of the date in UTC time.
*/
year: number;
/**
* The day of the week (0 = Sunday, 1 = Monday, ..., 6 = Saturday) in UTC time.
*/
day: number;
/**
* The month of the date (0 = January, 1 = February, ..., 11 = December) in UTC time.
*/
month: number;
/**
* The month of the date in the format 'MM' in UTC time.
*/
monthString: string;
/**
* The hours of the date in UTC time.
*/
hours: number;
/**
* The day of the month (1-31) in UTC time.
*/
date: number;
/**
* The minutes of the date in UTC time.
*/
minutes: number;
/**
* The seconds of the date in UTC time.
*/
seconds: number;
/**
* The full name of the month in UTC time.
*/
monthName: string;
/**
* The full name of the day in UTC time.
*/
dayName: string;
/**
* The short name of the day in UTC time.
*/
dayNameShort: string;
};
}