daily-toolset/dist/dateUtils.d.ts

A lightweight, versatile collection of TypeScript utility functions for everyday development needs. Simplify and streamline your Node.js, React, and Next.js projects with a powerful suite of well-organized helpers for strings, arrays, dates, objects, and

type FormatDateParams = {
    format?: "YYYY-MM-DD" | "DD-MM-YYYY" | "MM-DD-YYYY" | "YYYY/MM/DD" | "DD/MM/YYYY" | "Month DD, YYYY" | "DD Month YYYY" | "YYYY" | "MM" | "mm" | "M" | "DD" | "dd" | "D" | "d";
    monthFormat?: Format;
    dayFormat?: Format;
};
type Format = "short" | "long";
type FixedDate = string;
/**
 * Formats a given date object into a specified date format string.
 *
 * @param date The date object to format. If a string is passed, it must be a valid
 *             date in the format "YYYY-MM-DD". If null is passed, the function
 *             will format the current date.
 * @param opts An object containing options for the formatter. The following
 *             options are available:
 *              - format: The desired output format. Defaults to "DD/MM/YYYY".
 *              - monthFormat: The format for the month. Defaults to "short". Can
 *              be either "short" or "long". If "long", the full month name
 *              will be used. If "short", the abbreviated month name will be
 *              used.
 *              - dayFormat: The format for the day. Defaults to "short". Can
 *              be either "short" or "long". If "long", the full day name
 *              will be used. If "short", the abbreviated day name will be
 *              used.
 * @returns A string representing the formatted date.
 *
 * Supported formats include:
 * - "YYYY-MM-DD"
 * - "DD-MM-YYYY"
 * - "MM-DD-YYYY"
 * - "YYYY/MM/DD"
 * - "DD/MM/YYYY"
 * - "Month DD, YYYY"
 * - "DD Month YYYY"
 * - "YYYY"
 * - "MM"
 * - "mm"
 * - "M"
 * - "DD"
 * - "dd"
 * - "D"
 */
export declare function formatDate(date?: Date | FixedDate | null, { format, monthFormat, dayFormat, }?: FormatDateParams): string;
/**
 * Retrieves the day of the week from a given date as a string.
 *
 * @param {Date | FixedDate | null} date - The date to retrieve the day from. Defaults to the current date.
 * @param {"short" | "long"} [format="short"] - The format of the day name to return. Defaults to "short".
 * @returns {string} The day name as a string (e.g. "Mon" or "Monday").
 */
export declare function getDayName(date?: Date | FixedDate | null, format?: FormatDateParams["dayFormat"]): string;
/**
 * Retrieves the day of the month from a given date as a zero-padded two-digit string.
 *
 * @param {Date | FixedDate | null} date - The date to retrieve the day from. Defaults to the current date.
 * @returns {string} A two-digit string representing the day of the month (01-31).
 */
export declare function getDay(date?: Date | FixedDate | null): string;
/**
 * Retrieves the month from a given date as a formatted string.
 *
 * @example
 * const result = getMonthName();
 * console.log(result);
 * // Output: "Jan" (or the current month)
 *
 * const result = getMonthName(new Date(), "long");
 * console.log(result);
 * // Output: "August" (or the current month)
 *
 * @param {Date | FixedDate | null} [date] - The date to retrieve the month from.
 * @param {FormatDateParams["monthFormat"]} [format] - The format of the month string.
 * @returns {string} The month as a formatted string.
 */
export declare function getMonthName(date?: Date | FixedDate | null, format?: FormatDateParams["monthFormat"]): string;
/**
 * Retrieves the month from a given date as a formatted string.
 *
 * This function takes a Date object, a FixedDate object, or null and returns
 * the month in the specified format. If no date is provided, the current date is used.
 *
 * @param {Date | FixedDate | null} [date=new Date()] - The date from which to extract the month.
 * @param {FormatDateParams["monthFormat"]} [format="short"] - The format to use for the month.
 * @returns {string} The month extracted from the date, formatted as a number.
 */
export declare function getMonth(date?: Date | FixedDate | null): number;
/**
 * Retrieves the year from a given date as a string.
 *
 * This function takes a Date object, a FixedDate object, or null and returns
 * the year in the "YYYY" format. If no date is provided, the current date is used.
 *
 * @param {Date | FixedDate | null} [date=new Date()] - The date from which to extract the year.
 * @returns {string} The year extracted from the date, formatted as a string.
 */
export declare function getYear(date?: Date | FixedDate | null): number;
type FormatTimeParams = {
    format?: "HH:mm:ss" | "HH:mm" | "hh:mmA" | "hh:mm:ssA" | "HH:mm:ss.SSS";
};
/**
 * Formats a `Date` object into a readable time string according to the given format.
 *
 * The following formats are supported:
 *
 * - `HH:mm:ss` (24-hour format with seconds)
 * - `HH:mm` (24-hour format without seconds)
 * - `hh:mmA` (12-hour format with AM/PM)
 * - `hh:mm:ssA` (12-hour format with seconds and AM/PM)
 * - `HH:mm:ss.SSS` (24-hour format with milliseconds)
 *
 * If an unsupported format string is provided, an error will be thrown with a message indicating the unsupported format.
 *
 * @param {Date} date The `Date` object to format.
 * @param {string} [format="hh:mmA"] The format string to use.
 * @returns {string} A `string` representing the formatted time.
 * @throws {TypeError} If the `date` parameter is not a `Date` object.
 * @throws {Error} If the `format` parameter is not a supported format string.
 */
export declare function formatTime(date?: Date, { format }?: FormatTimeParams): string;
type FormatDateAndTimeParams = {
    dateFormat?: FormatDateParams["format"];
    timeFormat?: FormatTimeParams["format"];
    seperator?: string;
};
/**
 * Formats a `Date` object into a string combining both date and time according to specified formats.
 *
 * This function allows customization of the date and time formats and returns a single string
 * that includes both, separated by a specified separator.
 *
 * @param {Date} date - The `Date` object to format.
 * @param {string} [dateFormat="YYYY-MM-DD"] - The format string for the date portion.
 * @param {string} [timeFormat="hh:mmA"] - The format string for the time portion.
 * @param {string} [seperator=" "] - The separator to use between the formatted date and time.
 * @returns {string} A `string` representing the formatted date and time.
 * @throws {TypeError} If the `date` parameter is not a `Date` object.
 */
export declare function formatDateTime(date?: Date, { dateFormat, timeFormat, seperator, }?: FormatDateAndTimeParams): string;
/**
 * Returns a human-readable string representing the time elapsed since the given date.
 *
 * This function takes a date and calculates the time difference between the current
 * time and the given date. It returns a string representing the time elapsed in a
 * human-readable format such as "a few seconds ago", "1 minute ago", or "2 hours ago".
 * If the difference is in days, weeks, months, or years, it returns the corresponding
 * string format.
 *
 * @param {Date | null | undefined} date - The date to calculate the time elapsed from.
 * @returns {string} - A human-readable string representing the time elapsed since the given date.
 * @throws {Error} - Throws an error if the date is null, undefined, or in the future.
 */
export declare function timeAgo(date: Date | null | undefined): string;
/**
 * Adds the given number of days to the given date and returns a new Date object.
 *
 * @param {number} days - The number of days to add to the date.
 * @param {Date} [date=new Date()] - The date to add the days to. Defaults to the current date.
 * @returns {Date} - A new Date object with the given number of days added.
 */
export declare function addDays(days: number, date?: Date): Date;
/**
 * Adds the given number of months to the given date and returns a new Date object.
 *
 * @param {number} months - The number of months to add to the date.
 * @param {Date} [date=new Date()] - The date to add the months to. Defaults to the current date.
 * @returns {Date} - A new Date object with the given number of months added.
 */
export declare function addMonths(months: number, date?: Date): Date;
/**
 * Adds the given number of years to the given date and returns a new Date object.
 *
 * @param {number} years - The number of years to add to the date.
 * @param {Date} [date=new Date()] - The date to add the years to. Defaults to the current date.
 * @returns {Date} - A new Date object with the given number of years added.
 */
export declare function addYears(years: number, date?: Date): Date;
/**
 * Adds the given number of hours to the given date and returns a new Date object.
 *
 * @param {number} hours - The number of hours to add to the date.
 * @param {Date} [date=new Date()] - The date to add the hours to. Defaults to the current date.
 * @returns {Date} - A new Date object with the given number of hours added.
 */
export declare function addHours(hours: number, date?: Date): Date;
/**
 * Adds the given number of minutes to the given date and returns a new Date object.
 *
 * @param {number} minutes - The number of minutes to add to the date.
 * @param {Date} [date=new Date()] - The date to add the minutes to. Defaults to the current date.
 * @returns {Date} - A new Date object with the given number of minutes added.
 */
export declare function addMinutes(minutes: number, date?: Date): Date;
/**
 * Adds the specified number of seconds to a given date and returns a new Date object.
 *
 * @param {number} seconds - The number of seconds to add to the date.
 * @param {Date} [date=new Date()] - The date to which the seconds will be added. Defaults to the current date.
 * @returns {Date} A new Date object with the specified number of seconds added.
 */
export declare function addSeconds(seconds: number, date?: Date): Date;
/**
 * Retrieves the number of days in a given month.
 *
 * This function takes a Date object and returns the number of days in its
 * corresponding month. If no Date object is provided, it defaults to the
 * current month.
 *
 * @param {Date} [date=new Date()] - The date to retrieve the days in month from.
 * @returns {number} The number of days in the month.
 */
export declare function daysInMonth(date?: Date): number;
/**
 * Returns true if the given date is today, false otherwise.
 *
 * @param {Date} date The date to check.
 * @returns {boolean} True if the given date is today.
 */
export declare function isToday(date: Date): boolean;
/**
 * Returns true if the given date is tomorrow, false otherwise.
 *
 * @param {Date} date The date to check.
 * @returns {boolean} True if the given date is tomorrow.
 */
export declare function isTomorrow(date: Date): boolean;
/**
 * Checks if a given date is yesterday.
 *
 * This function determines whether the provided date corresponds to the day
 * before the current date. It returns true if the date is yesterday, otherwise
 * it returns false.
 *
 * @param {Date} date - The date to check.
 * @returns {boolean} - `true` if the date is yesterday, `false` otherwise.
 */
export declare function isYesterday(date: Date): boolean;
type IsPastOptions = {
    includeTime?: boolean;
};
/**
 * Checks if a given date is in the past.
 *
 * Takes a Date object and determines if it is earlier than the current date.
 * Returns a boolean indicating whether the date is in the past.
 *
 * @param {Date} date The date to check.
 * @param {IsPastOptions} options Configuration options
 * @param {boolean} [options.includeTime=true] Whether to include time in the comparison
 * @returns {boolean} `true` if the date is in the past.
 */
export declare function isPast(date: Date, options?: IsPastOptions): boolean;
type IsFutureOptions = {
    includeTime?: boolean;
};
/**
 * Checks if a given date is in the future.
 *
 * Takes a Date object and determines if it is later than the current date.
 * Returns a boolean indicating whether the date is in the future.
 *
 * @param {Date} date The date to check.
 * @param {IsFutureOptions} options Configuration options
 * @param {boolean} [options.includeTime=true] Whether to include time in the comparison
 * @returns {boolean} `true` if the date is in the future.
 */
export declare function isFuture(date: Date, options?: IsFutureOptions): boolean;
/**
 * Returns the number of days between two dates.
 *
 * This function takes two dates and calculates the number of days
 * between them. It returns the difference in days as an integer.
 *
 * @param {Date} date1 - The first date to compare.
 * @param {Date} date2 - The second date to compare.
 * @returns {number} - The number of days between the two dates.
 */
export declare function daysBetween(date1: Date, date2: Date): number;
/**
 * Returns the number of hours between two dates.
 *
 * This function takes two dates and calculates the number of hours
 * between them. The returned value is an integer and is always
 * positive (i.e., the order of the dates does not matter).
 */
export declare function hoursBetween(date1: Date, date2: Date): number;
/**
 * Returns the number of minutes between two dates.
 *
 * This function takes two dates and calculates the number of minutes
 * between them. It returns the difference in minutes as an integer.
 *
 * @param {Date} date1 - The first date to compare.
 * @param {Date} date2 - The second date to compare.
 * @returns {number} - The number of minutes between the two dates.
 */
export declare function minutesBetween(date1: Date, date2: Date): number;
/**
 * Returns the number of days since the given date.
 *
 * This function takes a date and calculates the number of days that have
 * passed since that date. If the given date is in the future, it returns 0.
 *
 * @param {Date} date - The date to calculate the number of days since.
 * @returns {number} - The number of days since the given date.
 */
export declare function daysSince(date: Date): number;
/**
 * Returns the number of days until the given date from today.
 *
 * @param {Date} date - The date to calculate the number of days until.
 * @returns {number} - The number of days until the given date from today.
 * @throws {Error} - Throws an error if the date is null, undefined, or in the past.
 */
export declare function daysUntil(date: Date): number;
/**
 * Calculates the number of hours since the given date.
 *
 * @param {Date} date - The date to calculate the hours since.
 * @returns {number} The number of hours since the given date.
 */
export declare function hoursSince(date: Date): number;
/**
 * Calculates the number of hours until the given date.
 *
 * @param {Date} date - The date to calculate the hours until.
 * @returns {number} The number of hours until the given date.
 */
export declare function hoursUntil(date: Date): number;
/**
 * Retrieves the day of the year from a given date.
 *
 * @param {Date | FixedDate | null} date - The date to retrieve the day from. Defaults to the current date.
 * @returns {number} The day of the year (1-365) as per ISO 8601.
 */
export declare function dayOfYear(date?: Date): number;
/**
 * Retrieves the week of the year from a given date.
 *
 * @param {Date | FixedDate | null} date - The date to retrieve the week from. Defaults to the current date.
 * @returns {number} The week of the year (1-52) as per ISO 8601.
 */
export declare function weekOfYear(date?: Date): number;
/**
 * Validates if the provided string is a valid ISO date.
 *
 * This function checks if a given string matches the ISO date format
 * using a regular expression. It then attempts to parse it into a
 * JavaScript Date object to ensure it represents a valid date.
 *
 * @param {string} value - The string to validate as a date.
 * @returns {boolean} - True if the string is a valid date, false otherwise.
 */
export declare function isValidDate(value: string): boolean;
/**
 * Extracts the years, months, and days from a given date of birth.
 *
 * This function takes a Date object and returns an object with the years,
 * months, and days properties.
 *
 * @param {Date} dateOfBirth - The date of birth to extract the years, months, and days from.
 * @returns {object} An object with the years, months, and days properties.
 */
export declare function ageFromDOB(dateOfBirth: Date | string): {
    years: number;
    months: number;
    days: number;
};
export {};