Static
calendarCalculates 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 yearoptions.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:
options.noMinorFast
)options.noSpecialShabbat
)options.noModern
)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:
options.sedrot
)options.omer
)options.shabbatMevarchim
)options.molad
)options.yomKippurKatan
)options.yizkor
)Daily Study of texts are supported by the @hebcal/learning package, for example:
options.dailyLearning.dafYomi
)options.dailyLearning.yerushalmi
)options.dailyLearning.mishnaYomi
)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 candlesoptions.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 rangeoptions.addHebrewDatesForEvents
- print the Hebrew date for dates with some eventsLastly, 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
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());
}
Static
eruvEruv Tavshilin
Static
getCalculates 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]
Hebrew year
Gregorian or Hebrew date of event
anniversary occurring in hyear
Static
getLower-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.
Hebrew year
Static
getReturns an array of holidays for the year
Hebrew year
use the Israeli schedule for holidays
Static
getReturns an array of Events on this date (or undefined
if no events)
Hebrew Date, Gregorian date, or absolute R.D. day number
Optional
il: booleanuse the Israeli schedule for holidays
Static
getStatic
getCalculates 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:
Hebrew year
Gregorian or Hebrew date of death
anniversary occurring in hyear
Static
hallelReturn 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
Static
reformatHelper 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.
original time like "20:30"
"p" or "pm" or " P.M.". Add leading space if you want it
Static
tachanunReturn 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.
Static
version
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 thelocale
option.