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)
• 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)

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

Example

import {HebrewCalendar, HDate, Location, Event} from '@hebcal/core';
const options: CalOptions = {
  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());
}
Copy

Eruv Tavshilin

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'
Copy

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

Returns an array of holidays for the year

Returns an array of Events on this date (or undefined if no events)

Convenience function to create an instance of Sedra or reuse a previously created and cached instance.

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'
Copy

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

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 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.

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.