jewish-holidays/dist/index.d.ts

Jewish holidays

import { BasicJewishDate, JewishMonthType } from 'jewish-date';

/**
 * Determines whether the given date falls within Chol HaMoed.
 *
 * Chol HaMoed refers to the intermediate days of Passover and Sukkot,
 * which are considered semi-festive days. This function can handle both
 * Gregorian dates and basic Jewish dates.
 *
 * @param date - The date to check, which can be a JavaScript Date object
 *               or a BasicJewishDate.
 * @param isChutzLaaretz - A boolean indicating whether the date is in
 *                         the diaspora (false for Israel). Defaults to false.
 *
 * @returns A boolean indicating whether the specified date is during
 *          Chol HaMoed.
 * @public
 */
declare const isCholHaMoed: (date: Date | BasicJewishDate, isChutzLaaretz?: boolean) => boolean;

/**
 * Represents a Jewish holiday.
 * @public
 */
interface Holiday {
    /**
     * The day of the month on which the holiday occurs.
     *
     * @remarks
     * This value should be a number between 1 and 30, depending on the month.
     *
     * @example
     * // Example: 15th of the month
     * const holiday: Holiday = \{ day: 15, monthName: "Nisan", name: "Passover" \};
     */
    day: number;
    /**
     * The name of the month in which the holiday falls.
     *
     * @remarks
     * This should be of type `JewishMonthType`, representing the specific month in the Jewish calendar.
     *
     * @example
     * // Example: Nisan
     * const holiday: Holiday = \{ day: 15, monthName: "Nisan", name: "Passover" \};
     */
    monthName: JewishMonthType;
    /**
     * The official name of the holiday.
     *
     * @remarks
     * This should be a string representing the name of the holiday, such as "Passover" or "Rosh Hashanah".
     *
     * @example
     * // Example: "Passover"
     * const holiday: Holiday = \{ day: 15, monthName: "Nisan", name: "Passover" \};
     */
    name: string;
}

/**
 * Checks if a given Jewish date exists in a holiday list
 * @public
 */
declare const isDateInHolidayList: (jewishDate: BasicJewishDate, holidayList: Holiday[]) => boolean;

/**
 *Determines whether a given date falls during Chanukah.
 *
 * Chanukah is an eight-day Jewish holiday that begins on the 25th of Kislev.
 * It commemorates the rededication of the Second Temple in Jerusalem and the miracle
 * of the oil that burned for eight days.
 *
 * @param date - The date to check, which can be either:
 *   - A Gregorian date object, or
 *   - An object representing a Jewish date with properties `day`, `monthName`, and `year`.
 *
 * @returns Returns `true` if the given date falls during Chanukah,
 *   and `false` otherwise.
 *
 * @example
 * const isChanukah = isChanukah(new Date(2024, 12, 25)); // true
 *
 * @public
 */
declare const isChanukah: (date: Date | BasicJewishDate) => boolean;

/**
 * Determines whether a given date is Erev Shabbat (the day before Shabbat).
 *
 * @param date - The date to check, which can be a JavaScript Date object
 *               or a BasicJewishDate.
 * @returns A boolean indicating whether the specified date is Erev Shabbat.
 *
 * @public
 */
declare const isErevShabbat: (date: Date | BasicJewishDate) => boolean;

/**
 * Checks if a given date is Shabbat (the Jewish Sabbath).
 *
 * @param date - The date to check, which can be a JavaScript `Date` object
 *               or a `BasicJewishDate` object.
 *
 * @returns A boolean indicating whether the provided date falls on Shabbat.
 *
 * @remarks
 * Shabbat begins at sundown on Friday and ends at nightfall on Saturday.
 * In the Gregorian calendar, Shabbat corresponds to Saturday, which is
 * represented by `getDay() === 6`.
 *
 * @example
 * // Example: Check if a specific date is Shabbat
 * const date = new Date('2023-10-21'); // Saturday
 * const result = isShabbat(date); // true
 *
 * @public
 */
declare const isShabbat: (date: Date | BasicJewishDate) => boolean;

/**
 * Determines if a given date is a Yom Tov (Jewish holiday).
 *
 * This function accepts either a Gregorian date or a BasicJewishDate object
 * and checks if it corresponds to a Yom Tov in either Israel or Chutz Laaretz (the diaspora).
 *
 * @param  date - The date to check, which can be either:
 *   - A Gregorian date object, or
 *   - An object representing a Jewish date with properties `day`, `monthName`, and `year`.
 * @param isChutzLaaretz - A boolean indicating whether to check against Yom Tov dates
 *   observed in Chutz Laaretz. Defaults to `false`, meaning it checks only for Israeli holidays.
 *
 * @returns  Returns `true` if the given date is a Yom Tov,
 *   and `false` otherwise.
 *
 * @example
 * const isRoshHashanah = isYomTov(new Date(2024, 9, 3)); // true
 * const isSukkotInChutzLaaretz = isYomTov(\{ day: 16, monthName: "Tishri", year: 5785 \}, true); // true
 *
 * @public
 */
declare const isYomTov: (date: Date | BasicJewishDate, isChutzLaaretz?: boolean) => boolean;

/**
 * DDetermines whether a given date is a Erev Yom Tov (the day before a Jewish holiday).
 *
 * This function accepts either a Gregorian date or a BasicJewishDate object
 * and checks if it corresponds to a Erev Yom Tov
 *
 * @param  date - The date to check, which can be either:
 *   - A Gregorian date object, or
 *   - An object representing a Jewish date with properties `day`, `monthName`, and `year`.
 * @returns  Returns `true` if the given date is a Yom Tov,
 *   and `false` otherwise.
 *
 * @example
 * const isRoshHashanah = isYomTov(new Date(2024, 9, 3)); // true
 * const isSukkotInChutzLaaretz = isYomTov(\{ day: 16, monthName: "Tishri", year: 5785 \}); // true
 *
 * @public
 */
declare const isErevYomTov: (date: Date | BasicJewishDate) => boolean;

/**
 * Determines whether a given date falls on Purim.
 *
 * Purim is a Jewish holiday celebrated on the 14th of Adar, with Shushan Purim on the 15th of Adar.
 * The holiday commemorates the salvation of the Jewish people from Haman's plot in ancient Persia.
 *
 * @param date - The date to check, which can be either:
 *   - A Gregorian date object (Date), or
 *   - An object representing a Jewish date with properties `day`, `monthName`, and `year`.
 *
 * @returns Returns `true` if the given date falls on Purim or Shushan Purim,
 *   and `false` otherwise.
 *
 * @example
 * const isPurimToday = isPurim(new Date(2024, 2, 24)); // true
 *
 * @public
 */
declare const isPurim: (date: Date | BasicJewishDate) => boolean;

/**
 * Determines whether a given date falls on any Jewish fast day (Tzom).
 *
 * The Jewish fast days include:
 * - Tzom Gdalia (3rd of Tishri)
 * - Yom Kippur (10th of Tishri)
 * - Asara BeTevet (10th of Tevet)
 * - Taanit Esther (13th of Adar)
 * - Taanit Bechorot (14th of Nisan)
 * - Shiva Asar BeTamuz (17th of Tammuz)
 * - Tisha BeAv (9th of Av)
 *
 * @param date - The date to check, which can be either:
 *   - A Gregorian date object (Date), or
 *   - An object representing a Jewish date with properties `day`, `monthName`, and `year`
 *
 * @returns Returns `true` if the given date falls on any fast day, `false` otherwise
 *
 * @public
 */
declare const isTzom: (date: Date | BasicJewishDate) => boolean;

export { type Holiday, isChanukah, isCholHaMoed, isDateInHolidayList, isErevShabbat, isErevYomTov, isPurim, isShabbat, isTzom, isYomTov };