@hebcal/core
Advanced tools
Hebcal is a perpetual Jewish Calendar. This library converts between Hebrew and Gregorian dates, and generates lists of Jewish holidays for any year (past, present or future). Shabbat and holiday candle lighting and havdalah times are approximated based on location. Torah readings (Parashat HaShavua), Daf Yomi, and counting of the Omer can also be specified. Hebcal also includes algorithms to calculate yahrzeits, birthdays and anniversaries.
Hebcal was created in 1994 by Danny Sadinoff as a Unix/Linux program written in C, inspired by similar functionality written in Emacs Lisp. This ECMAScript 2015 implementation targets browser-based JavaScript and server-side Node.js.
Many users of this library will utilize the HebrewCalendar and HDate interfaces.
$ npm install @hebcal/core
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(), hd.toString());
}
Represents an Event with a title, date, and flags
Represents a Hebrew date
Daily Hebrew date ("11th of Sivan, 5780")
Class representing halachic times
Class representing Location
Havdalah after Shabbat or holiday
Candle lighting before Shabbat or holiday
Represents a molad, the moment when the new moon is "born"
Represents a Molad announcement on Shabbat Mevarchim
Represents a day 1-49 of counting the Omer from Pesach to Shavuot
Returns the Daf Yomi for given date
Event wrapper around a DafYomi instance
Represents Parashah HaShavua for an entire Hebrew year
Represents one of 54 weekly Torah portions, always on a Saturday
Represents a built-in holiday like Pesach, Purim or Tu BiShvat
Represents Rosh Chodesh, the beginning of a new month
Represents Mevarchim haChodesh, the announcement of the new month
objectGregorian date helper functions.
objectA locale in Hebcal is used for translations/transliterations of
holidays. @hebcal/core supports three locales by default
en - default, Sephardic transliterations (e.g. "Shabbat")ashkenazi - Ashkenazi transliterations (e.g. "Shabbos")he - Hebrew (e.g. "שַׁבָּת")Array.<string>The 54 parshiyot of the Torah as transilterated strings parshiot[0] == 'Bereshit', parshiot[1] == 'Noach', parshiot[53] == 'Ha'Azinu'.
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.
Represents an Event with a title, date, and flags
Kind: global class
numberObjectbooleanbooleanstringstringstringstringHDatestringConstructs Event
| Param | Type | Default | Description |
|---|---|---|---|
| date | HDate | Hebrew date event occurs | |
| desc | string | Description (not translated) | |
| [mask] | number | 0 | optional holiday flags |
| [attrs] | Object | {} |
numberKind: instance method of Event
ObjectKind: instance method of Event
booleanIs this event observed in Israel?
Kind: instance method of Event
booleanIs this event observed in the Diaspora?
Kind: instance method of Event
stringReturns (translated) description of this event
Kind: instance method of Event
| Param | Type | Description |
|---|---|---|
| [locale] | string | Optional locale name (defaults to active locale). |
stringReturns a brief (translated) description of this event. For most events, this is the same as render(). For some events, it procudes a shorter text (e.g. without a time or added description).
Kind: instance method of Event
| Param | Type | Description |
|---|---|---|
| [locale] | string | Optional locale name (defaults to active locale). |
stringReturns untranslated description of this event
Kind: instance method of Event
stringReturns a simplified (untranslated) description for this event. For example, "Erev Pesach" => "Pesach", and "Sukkot III (CH''M)" => "Sukkot". For many holidays the basename and the event description are the same.
Kind: instance method of Event
HDateReturns Hebrew date of this event
Kind: instance method of Event
stringKind: instance method of Event
Represents a Hebrew date
Kind: global class
numberbooleannumbernumbernumbernumbernumberHDateHDateHDateHDateDatenumberstringstringstringHDateHDateHDateHDateHDateHDateHDatebooleanstringnumberbooleannumbernumberstringnumbernumbernumberbooleanbooleannumbernumberCreate a Hebrew date. There are 3 basic forms for the HDate() constructor.
Date - represents the Hebrew date corresponding to the Gregorian date using
local time. Hours, minutes, seconds and milliseconds are ignored.HDate - clones a copy of the given Hebrew datenumber - Converts absolute Julian days to Hebrew date. The absolute Julian
date is the number of days elapsed since the (imaginary) Gregorian date
Sunday, December 31, 1 BC| Param | Type | Description |
|---|---|---|
| [day] | number | Date | HDate | Day of month (1-30) if a number. If a Date is specified, represents the Hebrew date corresponding to the Gregorian date using local time. If an HDate is specified, clones a copy of the given Hebrew date. |
| [month] | number | string | Hebrew month of year (1=NISAN, 7=TISHREI) |
| [year] | number | Hebrew year |
Example
import {HDate, months} from '@hebcal/core';
const hd1 = new HDate();
const hd2 = new HDate(new Date(2008, 10, 13));
const hd3 = new HDate(15, 'Cheshvan', 5769);
const hd4 = new HDate(15, months.CHESHVAN, 5769);
const hd5 = new HDate(733359); // ==> 15 Cheshvan 5769
const monthName = 'אייר';
const hd6 = new HDate(5, monthName, 5773);
numberGets the Hebrew year of this Hebrew date
Kind: instance method of HDate
booleanTests if this date occurs during a leap year
Kind: instance method of HDate
numberGets the Hebrew month (1=NISAN, 7=TISHREI) of this Hebrew date
Kind: instance method of HDate
numberThe Tishrei-based month of the date. 1 is Tishrei, 7 is Nisan, 13 is Elul in a leap year
Kind: instance method of HDate
numberNumber of days in the month of this Hebrew date
Kind: instance method of HDate
numberGets the day within the month (1-30)
Kind: instance method of HDate
numberGets the day of the week, using local time. 0=Sunday, 6=Saturday
Kind: instance method of HDate
HDateSets the year of the date. Returns the object it was called upon.
Kind: instance method of HDate
| Param | Type |
|---|---|
| year | number |
HDateSets the day of the month of the date. Returns the object it was called upon
Kind: instance method of HDate
| Param | Type |
|---|---|
| month | number |
HDateSets the Tishrei-based month of the date. Returns the object it was called upon
Kind: instance method of HDate
| Param | Type |
|---|---|
| month | number |
HDateKind: instance method of HDate
| Param | Type |
|---|---|
| date | number |
DateConverts to Gregorian date
Kind: instance method of HDate
numberReturns Julian absolute days
Kind: instance method of HDate
stringReturns a transliterated Hebrew month name, e.g. 'Elul' or 'Cheshvan'.
Kind: instance method of HDate
stringRenders this Hebrew date as a translated or transliterated string,
including ordinal e.g. '15th of Cheshvan, 5769'.
Kind: instance method of HDate
| Param | Type | Description |
|---|---|---|
| [locale] | string | Optional locale name (defaults to active locale). |
Example
import {HDate, months} from '@hebcal/core';
const hd = new HDate(15, months.CHESHVAN, 5769);
console.log(hd.render()); // '15th of Cheshvan, 5769'
console.log(hd.render('he')); // '15 חֶשְׁוָן, 5769'
stringRenders this Hebrew date in Hebrew gematriya, regardless of locale.
Kind: instance method of HDate
Example
import {HDate, months} from '@hebcal/core';
const hd = new HDate(15, months.CHESHVAN, 5769);
console.log(ev.renderGematriya()); // 'ט״ו חֶשְׁוָן תשס״ט'
HDateReturns an HDate representing the a dayNumber before the current date.
Sunday=0, Saturday=6
Kind: instance method of HDate
| Param | Type | Description |
|---|---|---|
| day | number | day of week |
Example
new HDate(new Date('Wednesday February 19, 2014')).before(6).greg() // Sat Feb 15 2014
HDateReturns an HDate representing the a dayNumber on or before the current date.
Sunday=0, Saturday=6
Kind: instance method of HDate
| Param | Type | Description |
|---|---|---|
| dow | number | day of week |
Example
new HDate(new Date('Wednesday February 19, 2014')).onOrBefore(6).greg() // Sat Feb 15 2014
new HDate(new Date('Saturday February 22, 2014')).onOrBefore(6).greg() // Sat Feb 22 2014
new HDate(new Date('Sunday February 23, 2014')).onOrBefore(6).greg() // Sat Feb 22 2014
HDateReturns an HDate representing the nearest dayNumber to the current date
Sunday=0, Saturday=6
Kind: instance method of HDate
| Param | Type | Description |
|---|---|---|
| dow | number | day of week |
Example
new HDate(new Date('Wednesday February 19, 2014')).nearest(6).greg() // Sat Feb 22 2014
new HDate(new Date('Tuesday February 18, 2014')).nearest(6).greg() // Sat Feb 15 2014
HDateReturns an HDate representing the a dayNumber on or after the current date.
Sunday=0, Saturday=6
Kind: instance method of HDate
| Param | Type | Description |
|---|---|---|
| dow | number | day of week |
Example
new HDate(new Date('Wednesday February 19, 2014')).onOrAfter(6).greg() // Sat Feb 22 2014
new HDate(new Date('Saturday February 22, 2014')).onOrAfter(6).greg() // Sat Feb 22 2014
new HDate(new Date('Sunday February 23, 2014')).onOrAfter(6).greg() // Sat Mar 01 2014
HDateReturns an HDate representing the a dayNumber after the current date.
Sunday=0, Saturday=6
Kind: instance method of HDate
| Param | Type | Description |
|---|---|---|
| day | number | day of week |
Example
new HDate(new Date('Wednesday February 19, 2014')).after(6).greg() // Sat Feb 22 2014
new HDate(new Date('Saturday February 22, 2014')).after(6).greg() // Sat Mar 01 2014
new HDate(new Date('Sunday February 23, 2014')).after(6).greg() // Sat Mar 01 2014
HDateReturns the next Hebrew date
Kind: instance method of HDate
HDateReturns the previous Hebrew date
Kind: instance method of HDate
booleanCompares this date to another date, returning true if the dates match.
Kind: instance method of HDate
| Param | Type | Description |
|---|---|---|
| other | HDate | Hebrew date to compare |
stringKind: instance method of HDate
numberConverts Hebrew date to absolute Julian days. The absolute date is the number of days elapsed since the (imaginary) Gregorian date Sunday, December 31, 1 BC.
Kind: static method of HDate
| Param | Type | Description |
|---|---|---|
| year | number | Hebrew year |
| month | number | Hebrew month |
| day | number | Hebrew date (1-30) |
booleanReturns true if Hebrew year is a leap year
Kind: static method of HDate
| Param | Type | Description |
|---|---|---|
| year | number | Hebrew year |
numberNumber of months in this Hebrew year (either 12 or 13 depending on leap year)
Kind: static method of HDate
| Param | Type | Description |
|---|---|---|
| year | number | Hebrew year |
numberNumber of days in Hebrew month in a given year (29 or 30)
Kind: static method of HDate
| Param | Type | Description |
|---|---|---|
| month | number | Hebrew month (e.g. months.TISHREI) |
| year | number | Hebrew year |
stringReturns a transliterated string name of Hebrew month in year, for example 'Elul' or 'Cheshvan'.
Kind: static method of HDate
| Param | Type | Description |
|---|---|---|
| month | number | Hebrew month (e.g. months.TISHREI) |
| year | number | Hebrew year |
numberReturns the Hebrew month number (NISAN=1, TISHREI=7)
Kind: static method of HDate
| Param | Type | Description |
|---|---|---|
| month | number | string | A number, or Hebrew month name string |
numberDays from sunday prior to start of Hebrew calendar to mean conjunction of Tishrei in Hebrew YEAR
Kind: static method of HDate
| Param | Type | Description |
|---|---|---|
| year | number | Hebrew year |
numberNumber of days in the hebrew YEAR
Kind: static method of HDate
| Param | Type | Description |
|---|---|---|
| year | number | Hebrew year |
booleantrue if Cheshvan is long in Hebrew year
Kind: static method of HDate
| Param | Type | Description |
|---|---|---|
| year | number | Hebrew year |
booleantrue if Kislev is short in Hebrew year
Kind: static method of HDate
| Param | Type | Description |
|---|---|---|
| year | number | Hebrew year |
numberConverts Hebrew month string name to numeric
Kind: static method of HDate
| Param | Type | Description |
|---|---|---|
| c | string | monthName |
numberNote: Applying this function to d+6 gives us the DAYNAME on or after an absolute day d. Similarly, applying it to d+3 gives the DAYNAME nearest to absolute date d, applying it to d-1 gives the DAYNAME previous to absolute date d, and applying it to d+7 gives the DAYNAME following absolute date d.
Kind: static method of HDate
| Param | Type |
|---|---|
| dayOfWeek | number |
| absdate | number |
Daily Hebrew date ("11th of Sivan, 5780")
Kind: global class
string| Param | Type |
|---|---|
| date | HDate |
stringKind: instance method of HebrewDateEvent
| Param | Type | Description |
|---|---|---|
| [locale] | string | Optional locale name (defaults to active locale). |
Example
import {HDate, HebrewDateEvent, months} from '@hebcal/core';
const hd = new HDate(15, months.CHESHVAN, 5769);
const ev = new HebrewDateEvent(hd);
console.log(ev.render()); // '15th of Cheshvan, 5769'
console.log(ev.render('he')); // 'ט״ו חֶשְׁוָן תשס״ט'
stringHelper function to render a Hebrew date
Kind: static method of HebrewDateEvent
| Param | Type |
|---|---|
| day | number |
| monthName | string |
| fullYear | number |
Class representing halachic times
Kind: global class
suncalc.GetTimesResultDateDatenumbernumberDatenumbernumberDateDateDateDateDateDateDateDateDateDateDateDateDateDateInitialize a Zmanim instance.
| Param | Type | Description |
|---|---|---|
| date | Date | HDate | Regular or Hebrew Date. If date is a regular Date, hours, minutes, seconds and milliseconds are ignored. |
| latitude | number | |
| longitude | number |
suncalc.GetTimesResultKind: instance method of Zmanim
DateKind: instance method of Zmanim
DateKind: instance method of Zmanim
numberKind: instance method of Zmanim
numberKind: instance method of Zmanim
DateKind: instance method of Zmanim
numberKind: instance method of Zmanim
numberKind: instance method of Zmanim
DateKind: instance method of Zmanim
| Param | Type |
|---|---|
| hours | number |
DateKind: instance method of Zmanim
DateKind: instance method of Zmanim
DateKind: instance method of Zmanim
DateKind: instance method of Zmanim
DateKind: instance method of Zmanim
DateKind: instance method of Zmanim
DateKind: instance method of Zmanim
DateKind: instance method of Zmanim
DateKind: instance method of Zmanim
DateKind: instance method of Zmanim
DateKind: instance method of Zmanim
DateKind: instance method of Zmanim
DateKind: instance method of Zmanim
Class representing Location
Kind: global class
numbernumberbooleanstringstringstringstringstringDateDatestringLocationstringstringstringbooleanInitialize a Location instance
| Param | Type | Description |
|---|---|---|
| latitude | number | Latitude as a decimal, valid range -90 thru +90 (e.g. 41.85003) |
| longitude | number | Longitude as a decimal, valid range -180 thru +180 (e.g. -87.65005) |
| il | boolean | in Israel (true) or Diaspora (false) |
| tzid | string | Olson timezone ID, e.g. "America/Chicago" |
| cityName | string | optional descriptive city name |
| countryCode | string | ISO 3166 alpha-2 country code (e.g. "FR") |
| geoid | string | optional string or numeric geographic ID |
numberKind: instance method of Location
numberKind: instance method of Location
booleanKind: instance method of Location
stringKind: instance method of Location
stringReturns the location name, up to the first comma
Kind: instance method of Location
stringKind: instance method of Location
stringKind: instance method of Location
stringKind: instance method of Location
DateKind: instance method of Location
| Param | Type |
|---|---|
| hdate | Date | HDate |
DateKind: instance method of Location
| Param | Type |
|---|---|
| hdate | Date | HDate |
stringKind: instance method of Location
LocationCreates a location object from one of 60 "classic" Hebcal city names. The following city names are supported: 'Ashdod', 'Atlanta', 'Austin', 'Baghdad', 'Beer Sheva', 'Berlin', 'Baltimore', 'Bogota', 'Boston', 'Budapest', 'Buenos Aires', 'Buffalo', 'Chicago', 'Cincinnati', 'Cleveland', 'Dallas', 'Denver', 'Detroit', 'Eilat', 'Gibraltar', 'Haifa', 'Hawaii', 'Helsinki', 'Houston', 'Jerusalem', 'Johannesburg', 'Kiev', 'La Paz', 'Livingston', 'Las Vegas', 'London', 'Los Angeles', 'Marseilles', 'Miami', 'Minneapolis', 'Melbourne', 'Mexico City', 'Montreal', 'Moscow', 'New York', 'Omaha', 'Ottawa', 'Panama City', 'Paris', 'Pawtucket', 'Petach Tikvah', 'Philadelphia', 'Phoenix', 'Pittsburgh', 'Providence', 'Portland', 'Saint Louis', 'Saint Petersburg', 'San Diego', 'San Francisco', 'Sao Paulo', 'Seattle', 'Sydney', 'Tel Aviv', 'Tiberias', 'Toronto', 'Vancouver', 'White Plains', 'Washington DC', 'Worcester'
Kind: static method of Location
| Param | Type |
|---|---|
| name | string |
stringConverts legacy Hebcal timezone to a standard Olson tzid.
Kind: static method of Location
| Param | Type | Description |
|---|---|---|
| tz | number | integer, GMT offset in hours |
| dst | string | 'none', 'eu', 'usa', or 'israel' |
stringConverts timezone info from Zip-Codes.com to a standard Olson tzid.
Kind: static method of Location
| Param | Type | Description |
|---|---|---|
| state | string | two-letter all-caps US state abbreviation like 'CA' |
| tz | number | positive number, 5=America/New_York, 8=America/Los_Angeles |
| dst | string | single char 'Y' or 'N' |
Example
Location.getUsaTzid('AZ', 7, 'Y') // 'America/Denver'
stringBuilds a city description from geonameid string components
Kind: static method of Location
| Param | Type | Description |
|---|---|---|
| cityName | string | e.g. 'Tel Aviv' or 'Chicago' |
| admin1 | string | e.g. 'England' or 'Massachusetts' |
| countryName | string | full country name, e.g. 'Israel' or 'United States' |
booleanAdds a location name for Location.lookup() only if the name isn't
already being used. Returns false if the name is already taken
and true if successfully added.
Kind: static method of Location
| Param | Type |
|---|---|
| cityName | string |
| location | Location |
Havdalah after Shabbat or holiday
Kind: global class
| Param | Type |
|---|---|
| date | HDate |
| mask | number |
| attrs | Object |
| [havdalahMins] | number |
stringKind: instance method of HavdalahEvent
| Param | Type | Description |
|---|---|---|
| [locale] | string | Optional locale name (defaults to active locale). |
stringReturns translation of "Havdalah" without the time.
Kind: instance method of HavdalahEvent
| Param | Type | Description |
|---|---|---|
| [locale] | string | Optional locale name (defaults to active locale). |
Candle lighting before Shabbat or holiday
Kind: global class
| Param | Type |
|---|---|
| date | HDate |
| mask | number |
| attrs | Object |
stringKind: instance method of CandleLightingEvent
| Param | Type | Description |
|---|---|---|
| [locale] | string | Optional locale name (defaults to active locale). |
stringReturns translation of "Candle lighting" without the time.
Kind: instance method of CandleLightingEvent
| Param | Type | Description |
|---|---|---|
| [locale] | string | Optional locale name (defaults to active locale). |
Represents a molad, the moment when the new moon is "born"
Kind: global class
numbernumberstringnumbernumbernumbernumberCalculates the molad for a Hebrew month
| Param | Type |
|---|---|
| year | number |
| month | number |
numberKind: instance method of Molad
numberKind: instance method of Molad
stringKind: instance method of Molad
numberKind: instance method of Molad
Returns: number - Day of Week (0=Sunday, 6=Saturday)
numberKind: instance method of Molad
Returns: number - hour of day (0-23)
numberKind: instance method of Molad
Returns: number - minutes past hour (0-59)
numberKind: instance method of Molad
Returns: number - parts of a minute (0-17)
Represents a Molad announcement on Shabbat Mevarchim
Kind: global class
| Param | Type | Description |
|---|---|---|
| date | HDate | Hebrew date event occurs |
| hyear | number | molad year |
| hmonth | number | molad month |
stringKind: instance method of MoladEvent
| Param | Type | Description |
|---|---|---|
| [locale] | string | Optional locale name (defaults to active locale). |
Represents a day 1-49 of counting the Omer from Pesach to Shavuot
Kind: global class
stringstring| Param | Type |
|---|---|
| date | HDate |
| omerDay | number |
stringKind: instance method of OmerEvent
Todo
| Param | Type | Description |
|---|---|---|
| [locale] | string | Optional locale name (defaults to active locale). |
stringReturns translation of "Omer 22" without ordinal numbers.
Kind: instance method of OmerEvent
| Param | Type | Description |
|---|---|---|
| [locale] | string | Optional locale name (defaults to active locale). |
Returns the Daf Yomi for given date
Kind: global class
numberstringstringInitializes a daf yomi instance
| Param | Type | Description |
|---|---|---|
| gregdate | Date | Gregorian date |
numberKind: instance method of DafYomi
stringKind: instance method of DafYomi
stringFormats (with translation) the dafyomi result as a string like "Pesachim 34"
Kind: instance method of DafYomi
| Param | Type | Description |
|---|---|---|
| [locale] | string | Optional locale name (defaults to active locale). |
Event wrapper around a DafYomi instance
Kind: global class
stringstringstring| Param | Type |
|---|---|
| date | HDate |
stringReturns Daf Yomi name including the 'Daf Yomi: ' prefix (e.g. "Daf Yomi: Pesachim 107").
Kind: instance method of DafYomiEvent
| Param | Type | Description |
|---|---|---|
| [locale] | string | Optional locale name (defaults to active locale). |
stringReturns Daf Yomi name without the 'Daf Yomi: ' prefix (e.g. "Pesachim 107").
Kind: instance method of DafYomiEvent
| Param | Type | Description |
|---|---|---|
| [locale] | string | Optional locale name (defaults to active locale). |
stringReturns a link to sefaria.org or dafyomi.org
Kind: instance method of DafYomiEvent
Represents Parashah HaShavua for an entire Hebrew year
Kind: global class
Array.<string>stringObjectbooleanArray.<Object>numberCaculates the Parashah HaShavua for an entire Hebrew year
| Param | Type | Description |
|---|---|---|
| hebYr | number | Hebrew year (e.g. 5749) |
| il | boolean | Use Israel sedra schedule (false for Diaspora) |
Array.<string>Returns the parsha (or parshiyot) read on Hebrew date
Kind: instance method of Sedra
| Param | Type | Description |
|---|---|---|
| hDate | HDate | number | Hebrew date or absolute days |
stringLooks up parsha for the date, then returns a (translated) string
Kind: instance method of Sedra
| Param | Type | Description |
|---|---|---|
| hDate | HDate | number | Hebrew date or absolute days |
ObjectReturns an object describing the parsha on the first Saturday on or after absdate
Kind: instance method of Sedra
| Param | Type | Description |
|---|---|---|
| hDate | HDate | number | Hebrew date or absolute days |
booleanChecks to see if this day would be a regular parasha HaShavua Torah reading or special holiday reading
Kind: instance method of Sedra
| Param | Type | Description |
|---|---|---|
| hDate | HDate | number | Hebrew date or absolute days |
Array.<Object>Kind: instance method of Sedra
numberKind: instance method of Sedra
Represents one of 54 weekly Torah portions, always on a Saturday
Kind: global class
stringstringstring| Param | Type | Description |
|---|---|---|
| date | HDate | |
| parsha | Array.<string> | untranslated name of single or double parsha, such as ['Bereshit'] or ['Achrei Mot', 'Kedoshim'] |
stringKind: instance method of ParshaEvent
| Param | Type | Description |
|---|---|---|
| [locale] | string | Optional locale name (i.e: 'he', 'fr'). Defaults to active locale. |
stringKind: instance method of ParshaEvent
stringKind: instance method of ParshaEvent
Represents a built-in holiday like Pesach, Purim or Tu BiShvat
Kind: global class
stringstringstringConstructs Holiday event
| Param | Type | Default | Description |
|---|---|---|---|
| date | HDate | Hebrew date event occurs | |
| desc | string | Description (not translated) | |
| [mask] | number | 0 | optional holiday flags |
| [attrs] | Object | {} |
stringKind: instance method of HolidayEvent
stringKind: instance method of HolidayEvent
| Param | Type |
|---|---|
| locale | string |
stringKind: instance method of HolidayEvent
Represents Rosh Chodesh, the beginning of a new month
Kind: global class
stringstringConstructs Rosh Chodesh event
| Param | Type | Description |
|---|---|---|
| date | HDate | Hebrew date event occurs |
| monthName | string | Hebrew month name (not translated) |
stringReturns (translated) description of this event
Kind: instance method of RoshChodeshEvent
| Param | Type | Description |
|---|---|---|
| [locale] | string | Optional locale name (defaults to active locale). |
stringKind: instance method of RoshChodeshEvent
Represents Mevarchim haChodesh, the announcement of the new month
Kind: global class
Constructs Mevarchim haChodesh event
| Param | Type | Description |
|---|---|---|
| date | HDate | Hebrew date event occurs |
| monthName | string | Hebrew month name (not translated) |
stringReturns (translated) description of this event
Kind: instance method of MevarchimChodeshEvent
| Param | Type | Description |
|---|---|---|
| [locale] | string | Optional locale name (defaults to active locale). |
stringReturns (translated) description of this event
Kind: instance method of MevarchimChodeshEvent
| Param | Type | Description |
|---|---|---|
| [locale] | string | Optional locale name (defaults to active locale). |
objectGregorian date helper functions.
Kind: global namespace
object
Array.<string>booleannumbernumbernumberDateArray.<string>Long names of the Gregorian months (1='January', 12='December')
Kind: static property of greg
Read only: true
booleanReturns true if the Gregorian year is a leap year
Kind: static method of greg
| Param | Type | Description |
|---|---|---|
| year | number | Gregorian year |
numberNumber of days in the Gregorian month for given year
Kind: static method of greg
| Param | Type | Description |
|---|---|---|
| month | number | Gregorian month (1=January, 12=December) |
| year | number | Gregorian year |
numberReturns number of days since January 1 of that year
Kind: static method of greg
| Param | Type | Description |
|---|---|---|
| date | Date | Gregorian date |
numberConverts Gregorian date to Julian Day Count
Kind: static method of greg
| Param | Type | Description |
|---|---|---|
| date | Date | Gregorian date |
DateConverts from Julian Day Count to Gregorian date. See the footnote on page 384 of ``Calendrical Calculations, Part II: Three Historical Calendars'' by E. M. Reingold, N. Dershowitz, and S. M. Clamen, Software--Practice and Experience, Volume 23, Number 4 (April, 1993), pages 383-404 for an explanation.
Kind: static method of greg
| Param | Type | Description |
|---|---|---|
| theDate | number | absolute Julian days |
objectA locale in Hebcal is used for translations/transliterations of
holidays. @hebcal/core supports three locales by default
en - default, Sephardic transliterations (e.g. "Shabbat")ashkenazi - Ashkenazi transliterations (e.g. "Shabbos")he - Hebrew (e.g. "שַׁבָּת")Kind: global namespace
object
stringstringLocaleDatastringstringstringstringReturns translation only if locale offers a non-empty translation for id.
Otherwise, returns undefined.
Kind: static method of Locale
| Param | Type | Description |
|---|---|---|
| id | string | Message ID to translate |
| [locale] | string | Optional locale name (i.e: 'he', 'fr'). Defaults to active locale. |
stringBy default, if no translation was found, returns id.
Kind: static method of Locale
| Param | Type | Description |
|---|---|---|
| id | string | Message ID to translate |
| [locale] | string | Optional locale name (i.e: 'he', 'fr'). Defaults to active locale. |
Register locale translations.
Kind: static method of Locale
| Param | Type | Description |
|---|---|---|
| locale | string | Locale name (i.e.: 'he', 'fr') |
| data | LocaleDate | parsed data from a .po file. |
LocaleDataActivates a locale. Throws an error if the locale has not been previously added. After setting the locale to be used, all strings marked for translations will be represented by the corresponding translation in the specified locale.
Kind: static method of Locale
| Param | Type | Description |
|---|---|---|
| locale | string | Locale name (i.e: 'he', 'fr') |
stringReturns the name of the active locale (i.e. 'he', 'ashkenazi', 'fr')
Kind: static method of Locale
stringKind: static method of Locale
| Param | Type |
|---|---|
| n | number |
stringRemoves nekudot from Hebrew string
Kind: static method of Locale
| Param | Type |
|---|---|
| str | string |
enumHoliday flags for Event
Kind: global enum
Read only: true
Properties
| Name | Type | Default | Description |
|---|---|---|---|
| CHAG | number | CHAG | Chag, yontiff, yom tov |
| LIGHT_CANDLES | number | LIGHT_CANDLES | Light candles 18 minutes before sundown |
| YOM_TOV_ENDS | number | YOM_TOV_ENDS | End of holiday (end of Yom Tov) |
| CHUL_ONLY | number | CHUL_ONLY | Observed only in the Diaspora (chutz l'aretz) |
| IL_ONLY | number | IL_ONLY | Observed only in Israel |
| LIGHT_CANDLES_TZEIS | number | LIGHT_CANDLES_TZEIS | Light candles in the evening at Tzeit time (3 small stars) |
| CHANUKAH_CANDLES | number | CHANUKAH_CANDLES | Candle-lighting for Chanukah |
| ROSH_CHODESH | number | ROSH_CHODESH | Rosh Chodesh, beginning of a new Hebrew month |
| MINOR_FAST | number | MINOR_FAST | Minor fasts like Tzom Tammuz, Ta'anit Esther, ... |
| SPECIAL_SHABBAT | number | SPECIAL_SHABBAT | Shabbat Shekalim, Zachor, ... |
| PARSHA_HASHAVUA | number | PARSHA_HASHAVUA | Weekly sedrot on Saturdays |
| DAF_YOMI | number | DAF_YOMI | Daily page of Talmud |
| OMER_COUNT | number | OMER_COUNT | Days of the Omer |
| MODERN_HOLIDAY | number | MODERN_HOLIDAY | Yom HaShoah, Yom HaAtzma'ut, ... |
| MAJOR_FAST | number | MAJOR_FAST | Yom Kippur and Tish'a B'Av |
| SHABBAT_MEVARCHIM | number | SHABBAT_MEVARCHIM | On the Saturday before Rosh Chodesh |
| MOLAD | number | MOLAD | Molad |
| USER_EVENT | number | USER_EVENT | Yahrzeit or Hebrew Anniversary |
| HEBREW_DATE | number | HEBREW_DATE | Daily Hebrew date ("11th of Sivan, 5780") |
enumHebrew months of the year (NISAN=1, TISHREI=7)
Kind: global enum
Read only: true
Properties
| Name | Type | Default | Description |
|---|---|---|---|
| NISAN | number | 1 | Nissan / ניסן |
| IYYAR | number | 2 | Iyyar / אייר |
| SIVAN | number | 3 | Sivan / סיון |
| TAMUZ | number | 4 | Tamuz (sometimes Tammuz) / תמוז |
| AV | number | 5 | Av / אב |
| ELUL | number | 6 | Elul / אלול |
| TISHREI | number | 7 | Tishrei / תִשְׁרֵי |
| CHESHVAN | number | 8 | Cheshvan / חשון |
| KISLEV | number | 9 | Kislev / כסלו |
| TEVET | number | 10 | Tevet / טבת |
| SHVAT | number | 11 | Sh'vat / שבט |
| ADAR_I | number | 12 | Adar or Adar Rishon / אדר |
| ADAR_II | number | 13 | Adar Sheini (only on leap years) / אדר ב׳ |
Array.<string>The 54 parshiyot of the Torah as transilterated strings parshiot[0] == 'Bereshit', parshiot[1] == 'Noach', parshiot[53] == 'Ha'Azinu'.
Kind: global constant
Read only: true
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.
Kind: global constant
Array.<Event>HDateHDateMap.<string, Array.<Event>>Array.<Event>stringObjectArray.<Event>Calculates holidays and other Hebrew calendar events based on options.
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.dafyomi)options.shabbatMevarchim)options.molad)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 artic 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) 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).
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 supressed when options.havdalahMins=0.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. @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 packageKind: static method of HebrewCalendar
| Param | Type | Default |
|---|---|---|
| [options] | Options | {} |
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(), hd.toString());
}
HDateCalculates 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]
Kind: static method of HebrewCalendar
Returns: HDate - anniversary occurring in hyear
| Param | Type | Description |
|---|---|---|
| hyear | number | Hebrew year |
| gdate | Date | HDate | Gregorian or Hebrew date of event |
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'
HDateCalculates 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:
Kind: static method of HebrewCalendar
Returns: HDate - anniversary occurring in hyear
| Param | Type | Description |
|---|---|---|
| hyear | number | Hebrew year |
| gdate | Date | HDate | Gregorian or Hebrew date of death |
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'
Map.<string, Array.<Event>>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.
Kind: static method of HebrewCalendar
| Param | Type | Description |
|---|---|---|
| year | number | Hebrew year |
Array.<Event>Returns an array of Events on this date (or undefined if no events)
Kind: static method of HebrewCalendar
| Param | Type | Description |
|---|---|---|
| date | HDate | Date | number | Hebrew Date, Gregorian date, or absolute Julian date |
stringHelper 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 HebrewCalendar.Options to determine
locale.
Kind: static method of HebrewCalendar
| Param | Type | Description |
|---|---|---|
| timeStr | string | original time like "20:30" |
| suffix | string | "p" or "pm" or " P.M.". Add leading space if you want it |
| options | Options |
ObjectOptions to configure which events are returned
Kind: static typedef of HebrewCalendar
Properties
| Name | Type | Description |
|---|---|---|
| location | Location | latitude/longitude/tzid used for candle-lighting |
| year | number | Gregorian or Hebrew year |
| isHebrewYear | boolean | to interpret year as Hebrew year |
| month | number | Gregorian or Hebrew month (to filter results to a single month) |
| numYears | number | generate calendar for multiple years (default 1) |
| start | Date | HDate | number | use specific start date (requires end date) |
| end | Date | HDate | number | use specific end date (requires start date) |
| candlelighting | boolean | calculate candle-lighting and havdalah times |
| candleLightingMins | number | minutes before sundown to light candles (default 18) |
| havdalahMins | number | minutes after sundown for Havdalah (typical values are 42, 50, or 72) |
| havdalahTzeit | boolean | calculate Havdalah according to Tzeit Hakochavim - Nightfall (the point when 3 small stars are observable in the night time sky with the naked eye). Defaults to true unless havdalahMins is specified |
| sedrot | boolean | calculate parashah hashavua on Saturdays |
| il | boolean | Israeli holiday and sedra schedule |
| noMinorFast | boolean | suppress minor fasts |
| noModern | boolean | suppress modern holidays |
| noRoshChodesh | boolean | suppress Rosh Chodesh |
| shabbatMevarchim | boolean | add Shabbat Mevarchim |
| noSpecialShabbat | boolean | suppress Special Shabbat |
| noHolidays | boolean | suppress regular holidays |
| dafyomi | boolean | include Daf Yomi |
| omer | boolean | include Days of the Omer |
| molad | boolean | include event announcing the molad |
| ashkenazi | boolean | use Ashkenazi transliterations for event titles (default Sephardi transliterations) |
| locale | string | translate event titles according to a locale (one of fi, fr, he, hu, pl, ru, ashkenazi, ashkenazi_litvish, ashkenazi_poylish, ashkenazi_standard) |
| hour12 | boolean | use 12-hour time (1-12) instead of default 24-hour time (0-23) |
| addHebrewDates | boolean | print the Hebrew date for the entire date range |
| addHebrewDatesForEvents | boolean | print the Hebrew date for dates with some events |
FAQs
A perpetual Jewish Calendar API
The npm package @hebcal/core receives a total of 2,612 weekly downloads. As such, @hebcal/core popularity was classified as popular.
We found that @hebcal/core demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
RubyGems.org has added a new "maintainer" role that allows for publishing new versions of gems. This new permission type is aimed at improving security for gem owners and the service overall.
Security News
Node.js will be enforcing stricter semver-major PR policies a month before major releases to enhance stability and ensure reliable release candidates.
Security News
Research
Socket's threat research team has detected five malicious npm packages targeting Roblox developers, deploying malware to steal credentials and personal data.