@hebcal/core 5.3.12 → 5.4.0

package/dist/hebcal.d.ts

@@ -0,0 +1,451 @@
+/**
+ * Parse options object to determine start & end days
+ * @private
+ * @param {CalOptions} options
+ * @return {number[]}
+ */
+export function getStartAndEnd(options: CalOptions): number[];
+/**
+ * HebrewCalendar is the main interface to the `@hebcal/core` library.
+ * This namespace is used to calculate holidays, rosh chodesh, candle lighting & havdalah times,
+ * Parashat HaShavua, Daf Yomi, days of the omer, and the molad.
+ * Event names can be rendered in several languges using the `locale` option.
+ */
+export class HebrewCalendar {
+    /**
+     * Calculates holidays and other Hebrew calendar events based on {@link CalOptions}.
+     *
+     * Each holiday is represented by an {@link Event} object which includes a date,
+     * a description, flags and optional attributes.
+     * If given no options, returns holidays for the Diaspora for the current Gregorian year.
+     *
+     * The date range returned by this function can be controlled by:
+     * * `options.year` - Gregorian (e.g. 1993) or Hebrew year (e.g. 5749)
+     * * `options.isHebrewYear` - to interpret `year` as Hebrew year
+     * * `options.numYears` - generate calendar for multiple years (default 1)
+     * * `options.month` - Gregorian or Hebrew month (to filter results to a single month)
+     *
+     * Alternatively, specify start and end days with `Date` or {@link HDate} instances:
+     * * `options.start` - use specific start date (requires `end` date)
+     * * `options.end` - use specific end date (requires `start` date)
+     *
+     * Unless `options.noHolidays == true`, default holidays include:
+     * * Major holidays - Rosh Hashana, Yom Kippur, Pesach, Sukkot, etc.
+     * * Minor holidays - Purim, Chanukah, Tu BiShvat, Lag BaOmer, etc.
+     * * Minor fasts - Ta'anit Esther, Tzom Gedaliah, etc. (unless `options.noMinorFast`)
+     * * Special Shabbatot - Shabbat Shekalim, Zachor, etc. (unless `options.noSpecialShabbat`)
+     * * Modern Holidays - Yom HaShoah, Yom HaAtzma'ut, etc. (unless `options.noModern`)
+     * * Rosh Chodesh (unless `options.noRoshChodesh`)
+     *
+     * Holiday and Torah reading schedules differ between Israel and the Disapora.
+     * Set `options.il=true` to use the Israeli schedule.
+     *
+     * Additional non-default event types can be specified:
+     * * Parashat HaShavua - weekly Torah Reading on Saturdays (`options.sedrot`)
+     * * Counting of the Omer (`options.omer`)
+     * * Shabbat Mevarchim HaChodesh on Saturday before Rosh Chodesh (`options.shabbatMevarchim`)
+     * * Molad announcement on Saturday before Rosh Chodesh (`options.molad`)
+     * * Yom Kippur Katan (`options.yomKippurKatan`)
+     *
+     * Daily Study of texts are supported by the
+     * {@link https://github.com/hebcal/hebcal-learning @hebcal/learning} package,
+     * for example:
+     * * Babylonian Talmud Daf Yomi (`options.dailyLearning.dafYomi`)
+     * * Jerusalem Talmud (Yerushalmi) Yomi (`options.dailyLearning.yerushalmi`)
+     * * Mishna Yomi (`options.dailyLearning.mishnaYomi`)
+     * * Nach Yomi (`options.dailyLearning.nachYomi`)
+     *
+     * Candle-lighting and Havdalah times are approximated using latitude and longitude
+     * specified by the {@link Location} class. The `Location` class contains a small
+     * database of cities with their associated geographic information and time-zone information.
+     * If you ever have any doubts about Hebcal's times, consult your local halachic authority.
+     * If you enter geographic coordinates above the arctic circle or antarctic circle,
+     * the times are guaranteed to be wrong.
+     *
+     * To add candle-lighting options, set `options.candlelighting=true` and set
+     * `options.location` to an instance of `Location`. By default, candle lighting
+     * time is 18 minutes before sundown (40 minutes for Jerusalem,
+     * 30 minutes for Haifa and Zikhron Ya'akov) and Havdalah is
+     * calculated according to Tzeit Hakochavim - Nightfall (the point when 3 small stars
+     * are observable in the night time sky with the naked eye). The default Havdalah
+     * option (Tzeit Hakochavim) is calculated when the sun is 8.5° below the horizon.
+     * These defaults can be changed using these options:
+     * * `options.candleLightingMins` - minutes before sundown to light candles
+     * * `options.havdalahMins` - minutes after sundown for Havdalah (typical values are 42, 50, or 72).
+     *    Havdalah times are suppressed when `options.havdalahMins=0`.
+     * * `options.havdalahDeg` - degrees for solar depression for Havdalah.
+     *    Default is 8.5 degrees for 3 small stars. Use 7.083 degrees for 3 medium-sized stars.
+     *    Havdalah times are suppressed when `options.havdalahDeg=0`.
+     *
+     * If both `options.candlelighting=true` and `options.location` is specified,
+     * Chanukah candle-lighting times and minor fast start/end times will also be generated.
+     * Chanukah candle-lighting is at Bein HaShmashos (13.5 minutes before
+     * the sun is 7.083° below the horizon in the evening)
+     * on weekdays, at regular candle-lighting time on Fridays, and at regular Havdalah time on
+     * Saturday night (see above).
+     *
+     * Minor fasts begin at Alot HaShachar (sun is 16.1° below the horizon in the morning) and
+     * end when 3 medium-sized stars are observable in the night sky (sun is 7.083° below the horizon
+     * in the evening).
+     *
+     * Two options also exist for generating an Event with the Hebrew date:
+     * * `options.addHebrewDates` - print the Hebrew date for the entire date range
+     * * `options.addHebrewDatesForEvents` - print the Hebrew date for dates with some events
+     *
+     * Lastly, translation and transliteration of event titles is controlled by
+     * `options.locale` and the {@link Locale} API.
+     * `@hebcal/core` supports three locales by default:
+     * * `en` - default, Sephardic transliterations (e.g. "Shabbat")
+     * * `ashkenazi` - Ashkenazi transliterations (e.g. "Shabbos")
+     * * `he` - Hebrew (e.g. "שַׁבָּת")
+     *
+     * Additional locales (such as `ru` or `fr`) are supported by the
+     * {@link https://github.com/hebcal/hebcal-locales @hebcal/locales} package
+     *
+     * @example
+     * import {HebrewCalendar, HDate, Location, Event} from '@hebcal/core';
+     * const options = {
+     *   year: 1981,
+     *   isHebrewYear: false,
+     *   candlelighting: true,
+     *   location: Location.lookup('San Francisco'),
+     *   sedrot: true,
+     *   omer: true,
+     * };
+     * const events = HebrewCalendar.calendar(options);
+     * for (const ev of events) {
+     *   const hd = ev.getDate();
+     *   const date = hd.greg();
+     *   console.log(date.toLocaleDateString(), ev.render('en'), hd.toString());
+     * }
+     * @param {CalOptions} [options={}]
+     * @return {Event[]}
+     */
+    static calendar(options?: CalOptions | undefined): Event[];
+    /**
+     * Calculates a birthday or anniversary (non-yahrzeit).
+     * `hyear` must be after original `gdate` of anniversary.
+     * Returns `undefined` when requested year preceeds or is same as original year.
+     *
+     * Hebcal uses the algorithm defined in "Calendrical Calculations"
+     * by Edward M. Reingold and Nachum Dershowitz.
+     *
+     * The birthday of someone born in Adar of an ordinary year or Adar II of
+     * a leap year is also always in the last month of the year, be that Adar
+     * or Adar II. The birthday in an ordinary year of someone born during the
+     * first 29 days of Adar I in a leap year is on the corresponding day of Adar;
+     * in a leap year, the birthday occurs in Adar I, as expected.
+     *
+     * Someone born on the thirtieth day of Marcheshvan, Kislev, or Adar I
+     * has his birthday postponed until the first of the following month in
+     * years where that day does not occur. [Calendrical Calculations p. 111]
+     * @example
+     * import {HebrewCalendar} from '@hebcal/core';
+     * const dt = new Date(2014, 2, 2); // '2014-03-02' == '30 Adar I 5774'
+     * const hd = HebrewCalendar.getBirthdayOrAnniversary(5780, dt); // '1 Nisan 5780'
+     * console.log(hd.greg().toLocaleDateString('en-US')); // '3/26/2020'
+     * @param {number} hyear Hebrew year
+     * @param {Date|HDate} gdate Gregorian or Hebrew date of event
+     * @return {HDate} anniversary occurring in `hyear`
+     */
+    static getBirthdayOrAnniversary(hyear: number, gdate: Date | HDate): HDate;
+    /**
+     * Calculates yahrzeit.
+     * `hyear` must be after original `gdate` of death.
+     * Returns `undefined` when requested year preceeds or is same as original year.
+     *
+     * Hebcal uses the algorithm defined in "Calendrical Calculations"
+     * by Edward M. Reingold and Nachum Dershowitz.
+     *
+     * The customary anniversary date of a death is more complicated and depends
+     * also on the character of the year in which the first anniversary occurs.
+     * There are several cases:
+     *
+     * * If the date of death is Marcheshvan 30, the anniversary in general depends
+     *   on the first anniversary; if that first anniversary was not Marcheshvan 30,
+     *   use the day before Kislev 1.
+     * * If the date of death is Kislev 30, the anniversary in general again depends
+     *   on the first anniversary — if that was not Kislev 30, use the day before
+     *   Tevet 1.
+     * * If the date of death is Adar II, the anniversary is the same day in the
+     *   last month of the Hebrew year (Adar or Adar II).
+     * * If the date of death is Adar I 30, the anniversary in a Hebrew year that
+     *   is not a leap year (in which Adar only has 29 days) is the last day in
+     *   Shevat.
+     * * In all other cases, use the normal (that is, same month number) anniversary
+     *   of the date of death. [Calendrical Calculations p. 113]
+     * @example
+     * import {HebrewCalendar} from '@hebcal/core';
+     * const dt = new Date(2014, 2, 2); // '2014-03-02' == '30 Adar I 5774'
+     * const hd = HebrewCalendar.getYahrzeit(5780, dt); // '30 Sh\'vat 5780'
+     * console.log(hd.greg().toLocaleDateString('en-US')); // '2/25/2020'
+     * @param {number} hyear Hebrew year
+     * @param {Date|HDate} gdate Gregorian or Hebrew date of death
+     * @return {HDate} anniversary occurring in hyear
+     */
+    static getYahrzeit(hyear: number, gdate: Date | HDate): HDate;
+    /**
+     * Lower-level holidays interface, which returns a `Map` of `Event`s indexed by
+     * `HDate.toString()`. These events must filtered especially for `flags.IL_ONLY`
+     * or `flags.CHUL_ONLY` depending on Israel vs. Diaspora holiday scheme.
+     * @function
+     * @param {number} year Hebrew year
+     * @return {Map<string,Event[]>}
+     */
+    static getHolidaysForYear(year: number): Map<string, Event[]>;
+    /**
+     * Returns an array of holidays for the year
+     * @param {number} year Hebrew year
+     * @param {boolean} il use the Israeli schedule for holidays
+     * @return {Event[]}
+     */
+    static getHolidaysForYearArray(year: number, il: boolean): Event[];
+    /**
+     * Returns an array of Events on this date (or `undefined` if no events)
+     * @param {HDate|Date|number} date Hebrew Date, Gregorian date, or absolute R.D. day number
+     * @param {boolean} [il] use the Israeli schedule for holidays
+     * @return {Event[]}
+     */
+    static getHolidaysOnDate(date: HDate | Date | number, il?: boolean | undefined): Event[];
+    /**
+     * Eruv Tavshilin
+     * @param {Date | HDate} date
+     * @param {boolean} il
+     * @return {boolean}
+     */
+    static eruvTavshilin(date: Date | HDate, il: boolean): boolean;
+    /**
+     * Helper function to format a 23-hour (00:00-23:59) time in US format ("8:13pm") or
+     * keep as "20:13" for any other locale/country. Uses {@link CalOptions} to determine
+     * locale.
+     * If `options.hour12` is `false`, locale is ignored and always returns 24-hour time.
+     * If `options.hour12` is `true`, locale is ignored and always returns 12-hour time.
+     * @param {string} timeStr - original time like "20:30"
+     * @param {string} suffix - "p" or "pm" or " P.M.". Add leading space if you want it
+     * @param {CalOptions} options
+     * @return {string}
+     */
+    static reformatTimeStr(timeStr: string, suffix: string, options: CalOptions): string;
+    /** @return {string} */
+    static version(): string;
+    /**
+     * Convenience function to create an instance of `Sedra` or reuse a previously
+     * created and cached instance.
+     * @function
+     * @param {number} hyear
+     * @param {boolean} il
+     * @return {Sedra}
+     */
+    static getSedra(hyear: number, il: boolean): Sedra;
+    /**
+     * Return a number containing information on what Hallel is said on that day.
+     *
+     * Whole Hallel is said on Chanukah, the first Yom Tov of Pesach, Shavuot, Sukkot,
+     * Yom Ha'atzmaut, and Yom Yerushalayim.
+     *
+     * Half Hallel is said on Rosh Chodesh (not Rosh Hashanah), and the last 6 days of Pesach.
+     *
+     * The number is one of the following values:
+     *
+     * 0 - No Hallel
+     * 1 - Half Hallel
+     * 2 - Whole Hallel
+     *
+     * @param {HDate} hdate
+     * @param {boolean} il
+     * @return {number}
+     */
+    static hallel(hdate: HDate, il: boolean): number;
+    /**
+     * Return details on what Tachanun (or Tzidchatcha on Shabbat) is said on `hdate`.
+     *
+     * Tachanun is not said on Rosh Chodesh, the month of Nisan, Lag Baomer,
+     * Rosh Chodesh Sivan until Isru Chag, Tisha B'av, 15 Av, Erev Rosh Hashanah,
+     * Rosh Hashanah, Erev Yom Kippur until after Simchat Torah, Chanukah,
+     * Tu B'shvat, Purim and Shushan Purim, and Purim and Shushan Purim Katan.
+     *
+     * In some congregations Tachanun is not said until from Rosh Chodesh Sivan
+     * until 14th Sivan, Sukkot until after Rosh Chodesh Cheshvan, Pesach Sheini,
+     * Yom Ha'atzmaut, and Yom Yerushalayim.
+     *
+     * Tachanun is not said at Mincha on days before it is not said at Shacharit.
+     *
+     * Tachanun is not said at Shacharit on Shabbat, but is at Mincha, usually.
+     * @param {HDate} hdate
+     * @param {boolean} il
+     * @return {TachanunResult}
+     */
+    static tachanun(hdate: HDate, il: boolean): TachanunResult;
+}
+/**
+ * Options to configure which events are returned
+ */
+export type CalOptions = {
+    /**
+     * - latitude/longitude/tzid used for candle-lighting
+     */
+    location?: Location | undefined;
+    /**
+     * - Gregorian or Hebrew year
+     */
+    year?: number | undefined;
+    /**
+     * - to interpret year as Hebrew year
+     */
+    isHebrewYear?: boolean | undefined;
+    /**
+     * - Gregorian or Hebrew month (to filter results to a single month)
+     */
+    month?: number | undefined;
+    /**
+     * - generate calendar for multiple years (default 1)
+     */
+    numYears?: number | undefined;
+    /**
+     * - use specific start date (requires end date)
+     */
+    start?: number | HDate | Date | undefined;
+    /**
+     * - use specific end date (requires start date)
+     */
+    end?: number | HDate | Date | undefined;
+    /**
+     * - calculate candle-lighting and havdalah times
+     */
+    candlelighting?: boolean | undefined;
+    /**
+     * - minutes before sundown to light candles (default 18)
+     */
+    candleLightingMins?: number | undefined;
+    /**
+     * - minutes after sundown for Havdalah (typical values are 42, 50, or 72).
+     * If `undefined` (the default), calculate Havdalah according to Tzeit Hakochavim -
+     * Nightfall (the point when 3 small stars are observable in the night time sky with
+     * the naked eye). If `0`, Havdalah times are suppressed.
+     */
+    havdalahMins?: number | undefined;
+    /**
+     * - degrees for solar depression for Havdalah.
+     * Default is 8.5 degrees for 3 small stars. use 7.083 degrees for 3 medium-sized stars
+     * (observed by Dr. Baruch (Berthold) Cohn in his luach published in France in 1899).
+     * If `0`, Havdalah times are suppressed.
+     */
+    havdalahDeg?: number | undefined;
+    /**
+     * - degrees for solar depression for end of fast days.
+     * Default is 7.083 degrees for 3 medium-sized stars. Other commonly-used values include
+     * 6.45 degrees, as calculated by Rabbi Yechiel Michel Tucazinsky.
+     */
+    fastEndDeg?: number | undefined;
+    /**
+     * - use elevation for calculations (default `false`).
+     * If `true`, use elevation to affect the calculation of all sunrise/sunset based zmanim.
+     * Note: there are some zmanim such as degree-based zmanim that are driven by the amount
+     * of light in the sky and are not impacted by elevation.
+     * These zmanim intentionally do not support elevation adjustment.
+     */
+    useElevation?: boolean | undefined;
+    /**
+     * - calculate parashah hashavua on Saturdays
+     */
+    sedrot?: boolean | undefined;
+    /**
+     * - Israeli holiday and sedra schedule
+     */
+    il?: boolean | undefined;
+    /**
+     * - suppress minor fasts
+     */
+    noMinorFast?: boolean | undefined;
+    /**
+     * - suppress modern holidays
+     */
+    noModern?: boolean | undefined;
+    /**
+     * - suppress Rosh Chodesh
+     */
+    noRoshChodesh?: boolean | undefined;
+    /**
+     * - add Shabbat Mevarchim
+     */
+    shabbatMevarchim?: boolean | undefined;
+    /**
+     * - suppress Special Shabbat
+     */
+    noSpecialShabbat?: boolean | undefined;
+    /**
+     * - suppress regular holidays
+     */
+    noHolidays?: boolean | undefined;
+    /**
+     * - include Days of the Omer
+     */
+    omer?: boolean | undefined;
+    /**
+     * - include event announcing the molad
+     */
+    molad?: boolean | undefined;
+    /**
+     * - use Ashkenazi transliterations for event titles (default Sephardi transliterations)
+     */
+    ashkenazi?: boolean | undefined;
+    /**
+     * - translate event titles according to a locale
+     * Default value is `en`, also built-in are `he` and `ashkenazi`.
+     * Additional locales (such as `ru` or `fr`) are provided by the
+     * {@link https://github.com/hebcal/hebcal-locales @hebcal/locales} package
+     */
+    locale?: string | undefined;
+    /**
+     * - print the Hebrew date for the entire date range
+     */
+    addHebrewDates?: boolean | undefined;
+    /**
+     * - print the Hebrew date for dates with some events
+     */
+    addHebrewDatesForEvents?: boolean | undefined;
+    /**
+     * - use bitmask from `flags` to filter events
+     */
+    mask?: number | undefined;
+    /**
+     * - include Yom Kippur Katan (default `false`).
+     * יוֹם כִּפּוּר קָטָן is a minor day of atonement occurring monthly on the day preceeding each Rosh Chodesh.
+     * Yom Kippur Katan is omitted in Elul (on the day before Rosh Hashanah),
+     * Tishrei (Yom Kippur has just passed), Kislev (due to Chanukah)
+     * and Nisan (fasting not permitted during Nisan).
+     * When Rosh Chodesh occurs on Shabbat or Sunday, Yom Kippur Katan is observed on the preceding Thursday.
+     * See {@link https://en.wikipedia.org/wiki/Yom_Kippur_Katan#Practices Wikipedia Yom Kippur Katan practices}
+     */
+    yomKippurKatan?: boolean | undefined;
+    /**
+     * - Whether to use 12-hour time (as opposed to 24-hour time).
+     * Possible values are `true` and `false`; the default is locale dependent.
+     */
+    hour12?: boolean | undefined;
+    /**
+     * - map of options to enable daily study calendars
+     * such as `dafYomi`, `mishnaYomi`, `nachYomi` with value `true`. For `yerushalmi`
+     * the value should be a `number` for edition (`1` for Vilna, `2` for Schottenstein).
+     */
+    dailyLearning?: {
+        [x: string]: any;
+    } | undefined;
+};
+export type TachanunResult = {
+    /**
+     * Tachanun is said at Shacharit
+     */
+    shacharit: boolean;
+    /**
+     * Tachanun is said at Mincha
+     */
+    mincha: boolean;
+    /**
+     * All congregations say Tachanun on the day
+     */
+    allCongs: boolean;
+};
+export type Event = import('./event').Event;
+import { HDate } from '@hebcal/hdate';
+import { Location } from './location.js';

package/dist/holidays.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Lower-level holidays interface, which returns a `Map` of `Event`s indexed by
+ * `HDate.toString()`. These events must filtered especially for `flags.IL_ONLY`
+ * or `flags.CHUL_ONLY` depending on Israel vs. Diaspora holiday scheme.
+ * @private
+ * @param {number} year Hebrew year
+ * @return {Map<string,Event[]>}
+ */
+export function getHolidaysForYear_(year: number): Map<string, Event[]>;
+/** Represents a built-in holiday like Pesach, Purim or Tu BiShvat */
+export class HolidayEvent extends Event {
+    /** @return {string} */
+    urlDateSuffix(): string;
+}
+/** Represents Rosh Chodesh, the beginning of a new month */
+export class RoshChodeshEvent extends HolidayEvent {
+    /**
+     * Constructs Rosh Chodesh event
+     * @param {HDate} date Hebrew date event occurs
+     * @param {string} monthName Hebrew month name (not translated)
+     */
+    constructor(date: HDate, monthName: string);
+}
+/**
+ * Because Asara B'Tevet often occurs twice in the same Gregorian year,
+ * we subclass HolidayEvent to override the `url()` method.
+ */
+export class AsaraBTevetEvent extends HolidayEvent {
+}
+/** Represents Mevarchim haChodesh, the announcement of the new month */
+export class MevarchimChodeshEvent extends Event {
+    /**
+     * Constructs Mevarchim haChodesh event
+     * @param {HDate} date Hebrew date event occurs
+     * @param {string} monthName Hebrew month name (not translated)
+     * @param {string} [memo]
+     */
+    constructor(date: HDate, monthName: string, memo?: string | undefined);
+    monthName: string;
+    memo: string;
+}
+/** Represents Rosh Hashana, the Jewish New Year */
+export class RoshHashanaEvent extends HolidayEvent {
+    /**
+     * @private
+     * @param {HDate} date Hebrew date event occurs
+     * @param {number} hyear Hebrew year
+     * @param {number} mask optional holiday flags
+     */
+    private constructor();
+    hyear: number;
+}
+/** YKK is minor day of atonement on the day preceeding each Rosh Chodesh */
+export class YomKippurKatanEvent extends HolidayEvent {
+    /**
+     * @private
+     * @param {HDate} date Hebrew date event occurs
+     * @param {string} nextMonthName name of the upcoming month
+     */
+    private constructor();
+    nextMonthName: string;
+    memo: string;
+}
+import { Event } from './event.js';
+import { HDate } from '@hebcal/hdate';