persidate/dist/index.d.ts

persidate is a lightweight package for converting and managing Shamsi (Jalali) and Gregorian dates in JavaScript/TypeScript.

declare global {
    interface Date {
        addDaysToDate(days: number): Date;
    }
}
/**
 * Converts date to ISO format in local time.
 * @param {Date} date - The input date.
 * @returns {string} Local ISO date string.
 */
export declare const convertToStandardDateTime: (date: Date) => string;
/**
 * Converts date to ISO format with a timezone offset adjustment.
 * @param {Date | string | number} date - The input date.
 * @returns {string} Adjusted ISO date string.
 */
export declare const convertToISODateTime: (date: Date | string | number) => string;
/**
 * Converts Jalali date string to Gregorian Date object.
 * @param {string} jalaliDate - Jalali date string in the format YYYY/MM/DD or YYYY-MM-DD.
 * @returns {Date} Gregorian Date object.
 */
export declare const convertToGregorianDate: (jalaliDate: string) => Date;
/**
 * Converts Jalali date string to Gregorian date string in the format YYYY/MM/DD.
 * @param {string} jalaliDate - Jalali date string in the format YYYY/MM/DD or YYYY-MM-DD.
 * @returns {string} Gregorian date string in the format YYYY/MM/DD.
 */
export declare const convertToGregorianDateString: (jalaliDate: string) => string;
/**
 * Converts a Gregorian date to a Jalali date in a specified format.
 *
 * @param {Date | string | number} date - The Gregorian date input.
 * @param { "day" | "weekday" | "month" | "dayMonth" | "dayMonthYear" | "weekdayDayMonth" | "weekdayDayMonthYear" } [format] -
 *   Optional format for the output:
 *   - If omitted, returns "YYYY-MM-DD"
 *   - "day": Returns day (e.g. "26")
 *   - "weekday": Returns weekday (e.g. "جمعه")
 *   - "month": Returns month (e.g. "مهر")
 *   - "dayMonth": Returns day and month (e.g. "26 مهر")
 *   - "dayMonthYear": Returns full date (e.g. "26 مهر 1403")
 *   - "weekdayDayMonth": Returns weekday + day + month (e.g. "جمعه 26 مهر")
 *   - "weekdayDayMonthYear": Full format (e.g. "جمعه 26 مهر 1403")
 *
 * @returns {string} Jalali date in desired format or "YYYY-MM-DD" by default.
 *
 * @example
 * convertToJalaliDate("2024-10-18"); // → "1403-07-27"
 * convertToJalaliDate("2024-10-18", "dayMonthYear"); // → "27 مهر 1403"
 * convertToJalaliDate(new Date(), "weekday"); // → "دوشنبه"
 */
export declare const convertToJalaliDate: (date: Date | string | number, format?: "day" | "weekday" | "month" | "year" | "dayMonth" | "dayMonthYear" | "weekdayDayMonth" | "weekdayDayMonthYear") => string;
/**
 * Converts a given timestamp or Date object to a Gregorian date string in the format YYYY-MM-DD.
 * @param {number | Date} date - Unix timestamp or Date object.
 * @returns {string} Gregorian date string in the format YYYY-MM-DD.
 */
export declare const formatToGregorianDate: (date: number | Date) => string;
/**
 * Converts Jalali date and time to Gregorian date string with time.
 * @param {number | Date} date - Unix timestamp or Date object.
 * @returns {string} Gregorian date string with time in the format YYYY-MM-DDTHH:mm.
 */
export declare const formatToGregorianDateTime: (date: number | Date, time: string) => string;
/**
 * Converts a Gregorian date to a formatted Jalali date with padded month and day.
 * @param {Date | string | number} date - Gregorian date object.
 * @returns {string} Jalali date in the format YYYY-MM-DD with zero-padded month and day.
 */
export declare const formatToJalaliDatePadded: (date: Date | string | number) => string;
type ISupportedDateFormats = "jYYYY-jM-jD" | "jYYYY-jMM-jDD" | "jMMMM" | "jD" | "jDDD" | "jDDD-jMM-jYY" | "YYYY-MM-DD" | "YYYY/MM/DD" | "YYYY/MM/DD HH:mm" | "HH:mm" | "YYYY/MM/DDTHH:mm:ss";
/**
 * Formats a date string according to the specified format.
 * @param {string | Date} date - The input date string or Date object.
 * @param {SupportedDateFormats} format - The desired output format.
 * @returns {string | null} Formatted date string or null if invalid.
 */
export declare const formatToLocalizedDate: (date: string | Date, format: ISupportedDateFormats) => string | null;
/**
 * Gets today's date in ISO format (YYYY-MM-DD).
 * @returns {string} Today's date in "YYYY-MM-DD" format.
 */
export declare const getToday: () => string;
/**
 * Extracts time from a date string or Date object in the format HH:mm.
 * @param {string | number | Date} date - Date as string (YYYY-MM-DDTHH:mm:ss) or Date object.
 * @returns {string} Time in the format HH:mm.
 */
export declare const getTimeFromDate: (date?: string | number | Date) => string;
/**
 * Calculates the number of days between now and a given date.
 * @param {string | Date | number} inputDate - A Date object or a string parsable by `new Date() or timeStamp`.
 * @returns {number} Number of days until the date (can be negative if in the past).
 */
export declare const getDaysFromNow: (inputDate: string | Date) => number;
/**
 * Get Jalali (Persian) date string to a Unix timestamp in milliseconds.
 * @param {string} jalaliDate - Jalali date in the format "YYYY-MM-DD"
 * @returns {number} Unix timestamp (milliseconds since 1970-01-01)
 */
export declare const getJalaliTimeStamp: (jalaliDate: string) => number;
/**
 * Returns a string indicating how long ago the given date was,
 * in Persian language format.
 *
 * @param {Date | string | number} date - The input date, either a Date object or a string parsable by `new Date()`.
 * @param {string} [suffix='پیش'] - Optional string to append, like 'پیش', 'قبل', or custom. Defaults to 'پیش'.
 * @returns {string} A Persian relative time string such as "۵ دقیقه پیش"
 */
export declare const getTimeAgo: (date: Date | string | number, suffix?: string) => string;
/**
 * Adds a specific number of days to the given date.
 * @param {Date} date - Input date.
 * @param {number} daysCount - Number of days to add.
 * @returns {Date} Updated date.
 */
export declare const addDaysToDate: (date: Date, daysCount: number) => Date;
/**
 * Compares two date strings and checks if the first date is before the second.
 * @param {string} first - First date string.
 * @param {string} second - Second date string.
 * @returns {boolean} True if first date is before second date.
 */
export declare const isBeforeDate: (first: string, second: string) => boolean;
/**
 * Check if the given Jalali year is a leap year.
 * @param {number} jalaliYear - Jalali year.
 * @returns {boolean} True if the Jalali year is a leap year.
 */
export declare const isLeapYearJalali: (jalaliYear: number) => boolean;
export declare const jalaliMonthNames: string[];
export declare const jalaliWeekdayNames: string[];
export {};