Class HebrewCalendar

Calculates holidays and other Hebrew calendar events based on CalOptions.

Each holiday is represented by an 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, maximum 2000)
• options.month - Gregorian or Hebrew month (to filter results to a single month)

Alternatively, specify start and end days with Date or 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)
• Yizkor (options.yizkor)

Daily Study of texts are supported by the @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 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 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 @hebcal/locales package

Returns true if Eruv Tavshilin should be prepared on the given date.

Eruv Tavshilin is prepared when a Yom Tov falls on Friday (so cooking for Shabbat that begins Friday night may continue from Yom Tov into Shabbat). This requires the day before to be a weekday (Wednesday or Thursday), the following Friday to be Yom Tov, and the day after Friday (Shabbat) to also be a sacred day.

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]

Lower-level holidays interface, which returns a Map of Events indexed by HDate.toString(). These events must be filtered for flags.IL_ONLY or flags.CHUL_ONLY depending on Israel vs. Diaspora holiday scheme.

Includes Rosh Chodesh, fasts, Yom Kippur Katan, Special Shabbatot, etc., but does not generate candle-lighting times, Torah readings, or Omer days. The result is cached in an internal LRU.

Returns a sorted array of holidays observed during the given Hebrew year.

Events are pre-filtered by Israel vs. Diaspora schedule, so callers do not need to inspect flags.IL_ONLY / flags.CHUL_ONLY themselves. Includes Rosh Chodesh, fasts, modern holidays, special Shabbatot, etc., but does not generate candle-lighting times, Torah readings, or Omer days.

Returns an array of holiday Events that occur on the given date, or undefined if no holidays occur that day.

When il is omitted, both Diaspora-only and Israel-only events are returned; pass true or false to filter to a single schedule.

Convenience function to create an instance of Sedra or reuse a previously created and cached instance for the same year + schedule.

Use this in preference to new Sedra(...) when calling repeatedly, since an internal LRU cache (~120 entries) avoids recomputing the keviyah-specific reading pattern.

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]

Determines which form of Hallel (if any) is recited on a given Hebrew date.

Returns 0 (none), 1 (half Hallel), or 2 (whole Hallel).

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.

Helper function to format a 24-hour (00:00-23:59) time string in either 12-hour US format (e.g. "8:13pm") or keep it in 24-hour format (e.g. "20:13") for any other locale or country.

The locale (and therefore default behavior) is derived from options.location / options.locale. The options.hour12 override takes precedence: if false, locale is ignored and the result is always 24-hour; if true, locale is ignored and the result is always 12-hour.

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.

Returns the semantic version string of the @hebcal/core package (e.g. "5.10.0"). Useful for logging or feature detection.