@hebcal/core

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. The initial JavaScript port was released in 2014 by Eyal Schachter (age 15). This ECMAScript 2015 implementation was released in 2020 by Michael J. Radwin. @hebcal/core targets both browser-based JavaScript and server-side Node.js.

Many users of this library will utilize the HebrewCalendar and HDate interfaces.

Installation

$ npm install @hebcal/core

Synopsis

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());
}

Classes

greg

Gregorian date helper functions.

Locale

A locale in Hebcal is used for translations/transliterations of holidays. @hebcal/core supports four locales by default

• en - default, Sephardic transliterations (e.g. "Shabbat")
• ashkenazi - Ashkenazi transliterations (e.g. "Shabbos")
• he - Hebrew (e.g. "שַׁבָּת")
• he-x-NoNikud - Hebrew without nikud (e.g. "שבת")

HDate

Represents a Hebrew date

Event

Represents an Event with a title, date, and flags

HebrewDateEvent

Daily Hebrew date ("11th of Sivan, 5780")

Zmanim

Class representing halachic times

Location

Class representing Location

TimedEvent

An event that has an eventTime and eventTimeStr

HavdalahEvent

Havdalah after Shabbat or holiday

CandleLightingEvent

Candle lighting before Shabbat or holiday

Molad

Represents a molad, the moment when the new moon is "born"

MoladEvent

Represents a Molad announcement on Shabbat Mevarchim

OmerEvent

Represents a day 1-49 of counting the Omer from Pesach to Shavuot

DafYomi

Returns the Daf Yomi for given date

DafYomiEvent

Event wrapper around a DafYomi instance

Sedra

Represents Parashah HaShavua for an entire Hebrew year

ParshaEvent

Represents one of 54 weekly Torah portions, always on a Saturday

HolidayEvent

Represents a built-in holiday like Pesach, Purim or Tu BiShvat

RoshChodeshEvent

Represents Rosh Chodesh, the beginning of a new month

AsaraBTevetEvent

Because Asara B'Tevet often occurs twice in the same Gregorian year, we subclass HolidayEvent to override the url() method.

MevarchimChodeshEvent

Represents Mevarchim haChodesh, the announcement of the new month

MishnaYomiIndex

A program of daily learning in which participants study two Mishnahs each day in order to finish the entire Mishnah in ~6 years.

MishnaYomiEvent

Event wrapper around a Mishna Yomi instance

HebrewCalendar

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.

Constants

parshiot : Array.<string>

The 54 parshiyot of the Torah as transilterated strings parshiot[0] == 'Bereshit', parshiot[1] == 'Noach', parshiot[53] == "Ha'Azinu".

Functions

gematriya(number) ⇒ string

Converts a numerical value to a string of Hebrew letters.

When specifying years of the Hebrew calendar in the present millennium, we omit the thousands (which is presently 5 [ה]).

Typedefs

ZmanimTimesResult : Object

SedraResult : Object

Result of Sedra.lookup

MishnaYomi : Object

Describes a mishna to be read

CalOptions : Object

Options to configure which events are returned

TachanunResult : Object

greg

Gregorian date helper functions.

Kind: global class

• greg
  • .isLeapYear(year) ⇒ boolean
  • .daysInMonth(month, year) ⇒ number
  • .isDate(obj) ⇒ boolean
  • ~~.dayOfYear(date) ⇒ number~~
  • .greg2abs(date) ⇒ number
  • .abs2greg(theDate) ⇒ Date

greg.isLeapYear(year) ⇒ boolean

Returns true if the Gregorian year is a leap year

Kind: static method of greg

greg.daysInMonth(month, year) ⇒ number

Number of days in the Gregorian month for given year

Kind: static method of greg

greg.isDate(obj) ⇒ boolean

Returns true if the object is a Javascript Date

Kind: static method of greg

~~greg.dayOfYear(date) ⇒ number~~

Deprecated

Returns number of days since January 1 of that year

Kind: static method of greg

greg.greg2abs(date) ⇒ number

Converts Gregorian date to absolute R.D. (Rata Die) days

Kind: static method of greg

greg.abs2greg(theDate) ⇒ Date

Converts from Rata Die (R.D. number) 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

Locale

A locale in Hebcal is used for translations/transliterations of holidays. @hebcal/core supports four locales by default

• en - default, Sephardic transliterations (e.g. "Shabbat")
• ashkenazi - Ashkenazi transliterations (e.g. "Shabbos")
• he - Hebrew (e.g. "שַׁבָּת")
• he-x-NoNikud - Hebrew without nikud (e.g. "שבת")

Kind: global class

• Locale
  • .lookupTranslation(id, [locale]) ⇒ string
  • .gettext(id, [locale]) ⇒ string
  • .addLocale(locale, data)
  • .useLocale(locale) ⇒ LocaleData
  • .getLocaleName() ⇒ string
  • .getLocaleNames() ⇒ Array.<string>
  • .ordinal(n, [locale]) ⇒ string
  • .hebrewStripNikkud(str) ⇒ string

Locale.lookupTranslation(id, [locale]) ⇒ string

Returns translation only if locale offers a non-empty translation for id. Otherwise, returns undefined.

Kind: static method of Locale

Locale.gettext(id, [locale]) ⇒ string

By default, if no translation was found, returns id.

Kind: static method of Locale

Locale.addLocale(locale, data)

Register locale translations.

Kind: static method of Locale

Locale.useLocale(locale) ⇒ LocaleData

Activates 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

Locale.getLocaleName() ⇒ string

Returns the name of the active locale (i.e. 'he', 'ashkenazi', 'fr')

Kind: static method of Locale

Locale.getLocaleNames() ⇒ Array.<string>

Returns the names of registered locales

Kind: static method of Locale

Locale.ordinal(n, [locale]) ⇒ string

Kind: static method of Locale

Locale.hebrewStripNikkud(str) ⇒ string

Removes nekudot from Hebrew string

Kind: static method of Locale

HDate

Represents a Hebrew date

Kind: global class

• HDate
  • new HDate([day], [month], [year])
  • instance
    • .getFullYear() ⇒ number
    • .isLeapYear() ⇒ boolean
    • .getMonth() ⇒ number
    • .getTishreiMonth() ⇒ number
    • .daysInMonth() ⇒ number
    • .getDate() ⇒ number
    • .getDay() ⇒ number
    • .greg() ⇒ Date
    • .abs() ⇒ number
    • .getMonthName() ⇒ string
    • .render([locale], [showYear]) ⇒ string
    • .renderGematriya() ⇒ string
    • .before(day) ⇒ HDate
    • .onOrBefore(dow) ⇒ HDate
    • .nearest(dow) ⇒ HDate
    • .onOrAfter(dow) ⇒ HDate
    • .after(day) ⇒ HDate
    • .next() ⇒ HDate
    • .prev() ⇒ HDate
    • .add(number, [units]) ⇒ HDate
    • .subtract(number, [units]) ⇒ HDate
    • .deltaDays(other) ⇒ number
    • .isSameDate(other) ⇒ boolean
    • .toString() ⇒ string
  • static
    • .hebrew2abs(year, month, day) ⇒ number
    • .isLeapYear(year) ⇒ boolean
    • .monthsInYear(year) ⇒ number
    • .daysInMonth(month, year) ⇒ number
    • .getMonthName(month, year) ⇒ string
    • .monthNum(month) ⇒ number
    • .daysInYear(year) ⇒ number
    • .longCheshvan(year) ⇒ boolean
    • .shortKislev(year) ⇒ boolean
    • .monthFromName(monthName) ⇒ number
    • .dayOnOrBefore(dayOfWeek, absdate) ⇒ number
    • .isHDate(obj) ⇒ boolean

new HDate([day], [month], [year])

Create a Hebrew date. There are 3 basic forms for the HDate() constructor.

1. No parameters - represents the current Hebrew date at time of instantiation
2. One parameter
   • 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 date
   • number - Converts absolute R.D. days to Hebrew date. R.D. 1 == the imaginary date January 1, 1 (Gregorian)
3. Three parameters: Hebrew day, Hebrew month, Hebrew year. Hebrew day should be a number between 1-30, Hebrew month can be a number or string, and Hebrew year is always a number.

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

hDate.getFullYear() ⇒ number

Gets the Hebrew year of this Hebrew date

Kind: instance method of HDate

hDate.isLeapYear() ⇒ boolean

Tests if this date occurs during a leap year

Kind: instance method of HDate

hDate.getMonth() ⇒ number

Gets the Hebrew month (1=NISAN, 7=TISHREI) of this Hebrew date

Kind: instance method of HDate

hDate.getTishreiMonth() ⇒ number

The Tishrei-based month of the date. 1 is Tishrei, 7 is Nisan, 13 is Elul in a leap year

Kind: instance method of HDate

hDate.daysInMonth() ⇒ number

Number of days in the month of this Hebrew date

Kind: instance method of HDate

hDate.getDate() ⇒ number

Gets the day within the month (1-30)

Kind: instance method of HDate

hDate.getDay() ⇒ number

Gets the day of the week. 0=Sunday, 6=Saturday

Kind: instance method of HDate

hDate.greg() ⇒ Date

Converts to Gregorian date

Kind: instance method of HDate

hDate.abs() ⇒ number

Returns R.D. (Rata Die) fixed days. R.D. 1 == Monday, January 1, 1 (Gregorian) Note also that R.D. = Julian Date − 1,721,424.5 https://en.wikipedia.org/wiki/Rata_Die#Dershowitz_and_Reingold

Kind: instance method of HDate

hDate.getMonthName() ⇒ string

Returns a transliterated Hebrew month name, e.g. 'Elul' or 'Cheshvan'.

Kind: instance method of HDate

hDate.render([locale], [showYear]) ⇒ string

Renders this Hebrew date as a translated or transliterated string, including ordinal e.g. '15th of Cheshvan, 5769'.

Kind: instance method of HDate

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'

hDate.renderGematriya() ⇒ string

Renders 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(hd.renderGematriya()); // 'ט״ו חֶשְׁוָן תשס״ט'

hDate.before(day) ⇒ HDate

Returns an HDate representing the a dayNumber before the current date. Sunday=0, Saturday=6

Kind: instance method of HDate

Example

new HDate(new Date('Wednesday February 19, 2014')).before(6).greg() // Sat Feb 15 2014

hDate.onOrBefore(dow) ⇒ HDate

Returns an HDate representing the a dayNumber on or before the current date. Sunday=0, Saturday=6

Kind: instance method of HDate

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

hDate.nearest(dow) ⇒ HDate

Returns an HDate representing the nearest dayNumber to the current date Sunday=0, Saturday=6

Kind: instance method of HDate

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

hDate.onOrAfter(dow) ⇒ HDate

Returns an HDate representing the a dayNumber on or after the current date. Sunday=0, Saturday=6

Kind: instance method of HDate

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

hDate.after(day) ⇒ HDate

Returns an HDate representing the a dayNumber after the current date. Sunday=0, Saturday=6

Kind: instance method of HDate

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

hDate.next() ⇒ HDate

Returns the next Hebrew date

Kind: instance method of HDate

hDate.prev() ⇒ HDate

Returns the previous Hebrew date

Kind: instance method of HDate

hDate.add(number, [units]) ⇒ HDate

Returns a cloned HDate object with a specified amount of time added

Units are case insensitive, and support plural and short forms. Note, short forms are case sensitive.

Kind: instance method of HDate

hDate.subtract(number, [units]) ⇒ HDate

Returns a cloned HDate object with a specified amount of time subracted

Units are case insensitive, and support plural and short forms. Note, short forms are case sensitive.

Kind: instance method of HDate

Example

import {HDate, months} from '@hebcal/core';

const hd1 = new HDate(15, months.CHESHVAN, 5769);
const hd2 = hd1.add(1, 'weeks'); // 7 Kislev 5769
const hd3 = hd1.add(-3, 'M'); // 30 Av 5768

hDate.deltaDays(other) ⇒ number

Returns the difference in days between the two given HDates.

The result is positive if this date is comes chronologically after the other date, and negative if the order of the two dates is reversed.

The result is zero if the two dates are identical.

Kind: instance method of HDate

Example

import {HDate, months} from '@hebcal/core';

const hd1 = new HDate(25, months.KISLEV, 5770);
const hd2 = new HDate(15, months.CHESHVAN, 5769);
const days = hd1.deltaDays(hd2); // 394

hDate.isSameDate(other) ⇒ boolean

Compares this date to another date, returning true if the dates match.

Kind: instance method of HDate

hDate.toString() ⇒ string

Kind: instance method of HDate

HDate.hebrew2abs(year, month, day) ⇒ number

Converts Hebrew date to R.D. (Rata Die) fixed days. R.D. 1 is the imaginary date Monday, January 1, 1 on the Gregorian Calendar.

Kind: static method of HDate

HDate.isLeapYear(year) ⇒ boolean

Returns true if Hebrew year is a leap year

Kind: static method of HDate

HDate.monthsInYear(year) ⇒ number

Number of months in this Hebrew year (either 12 or 13 depending on leap year)

Kind: static method of HDate

HDate.daysInMonth(month, year) ⇒ number

Number of days in Hebrew month in a given year (29 or 30)

Kind: static method of HDate

HDate.getMonthName(month, year) ⇒ string

Returns a transliterated string name of Hebrew month in year, for example 'Elul' or 'Cheshvan'.

Kind: static method of HDate

HDate.monthNum(month) ⇒ number

Returns the Hebrew month number (NISAN=1, TISHREI=7)

Kind: static method of HDate

HDate.daysInYear(year) ⇒ number

Number of days in the hebrew YEAR

Kind: static method of HDate

HDate.longCheshvan(year) ⇒ boolean

true if Cheshvan is long in Hebrew year

Kind: static method of HDate

HDate.shortKislev(year) ⇒ boolean

true if Kislev is short in Hebrew year

Kind: static method of HDate

HDate.monthFromName(monthName) ⇒ number

Converts Hebrew month string name to numeric

Kind: static method of HDate

HDate.dayOnOrBefore(dayOfWeek, absdate) ⇒ number

Note: 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

HDate.isHDate(obj) ⇒ boolean

Tests if the object is an instance of HDate

Kind: static method of HDate

Event

Represents an Event with a title, date, and flags

Kind: global class

• Event
  • new Event(date, desc, [mask], [attrs])
  • .getDate() ⇒ HDate
  • .getDesc() ⇒ string
  • .getFlags() ⇒ number
  • .render([locale]) ⇒ string
  • .renderBrief([locale]) ⇒ string
  • .getEmoji() ⇒ string
  • .basename() ⇒ string
  • .url() ⇒ string
  • .observedInIsrael() ⇒ boolean
  • .observedInDiaspora() ⇒ boolean
  • .observedIn(il) ⇒ boolean
  • ~~.getAttrs() ⇒ Object~~
  • .clone() ⇒ Event

new Event(date, desc, [mask], [attrs])

Constructs Event

event.getDate() ⇒ HDate

Hebrew date of this event

Kind: instance method of Event

event.getDesc() ⇒ string

Untranslated description of this event

Kind: instance method of Event

event.getFlags() ⇒ number

Bitmask of optional event flags. See flags

Kind: instance method of Event

event.render([locale]) ⇒ string

Returns (translated) description of this event

Kind: instance method of Event

Example

const ev = new Event(new HDate(6, 'Sivan', 5749), 'Shavuot', flags.CHAG);
ev.render(); // 'Shavuot'
ev.render('he'); // 'שָׁבוּעוֹת'
ev.render('ashkenazi'); // 'Shavuos'

event.renderBrief([locale]) ⇒ string

Returns 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

event.getEmoji() ⇒ string

Optional holiday-specific Emoji or null.

Kind: instance method of Event

event.basename() ⇒ string

Returns a simplified (untranslated) description for this event. For example, the HolidayEvent class supports "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

event.url() ⇒ string

Returns a URL to hebcal.com or sefaria.org for more detail on the event. Returns undefined for events with no detail page.

Kind: instance method of Event

event.observedInIsrael() ⇒ boolean

Is this event observed in Israel?

Kind: instance method of Event
Example

const ev1 = new Event(new HDate(7, 'Sivan', 5749), 'Shavuot II', flags.CHAG | flags.CHUL_ONLY);
ev1.observedInIsrael(); // false
const ev2 = new Event(new HDate(26, 'Kislev', 5749), 'Chanukah: 3 Candles', 0);
ev2.observedInIsrael(); // true

event.observedInDiaspora() ⇒ boolean

Is this event observed in the Diaspora?

Kind: instance method of Event
Example

const ev1 = new Event(new HDate(7, 'Sivan', 5749), 'Shavuot II', flags.CHAG | flags.CHUL_ONLY);
ev1.observedInDiaspora(); // true
const ev2 = new Event(new HDate(26, 'Kislev', 5749), 'Chanukah: 3 Candles', 0);
ev2.observedInDiaspora(); // true

event.observedIn(il) ⇒ boolean

Is this event observed in Israel/Diaspora?

Kind: instance method of Event

Example

const ev1 = new Event(new HDate(7, 'Sivan', 5749), 'Shavuot II', flags.CHAG | flags.CHUL_ONLY);
ev1.observedIn(false); // true
ev1.observedIn(true); // false
const ev2 = new Event(new HDate(26, 'Kislev', 5749), 'Chanukah: 3 Candles', 0);
ev2.observedIn(false); // true
ev2.observedIn(true); // true

~~event.getAttrs() ⇒ Object~~

Deprecated

Kind: instance method of Event

event.clone() ⇒ Event

Makes a clone of this Event object

Kind: instance method of Event

HebrewDateEvent

Daily Hebrew date ("11th of Sivan, 5780")

Kind: global class

• HebrewDateEvent
  • new HebrewDateEvent(date)
  • instance
    • .render([locale]) ⇒ string
    • .renderBrief([locale]) ⇒ string
  • static
    • ~~.renderHebrew(day, monthName, fullYear) ⇒ string~~

new HebrewDateEvent(date)

hebrewDateEvent.render([locale]) ⇒ string

Kind: instance method of HebrewDateEvent

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')); // 'ט״ו חֶשְׁוָן תשס״ט'

hebrewDateEvent.renderBrief([locale]) ⇒ string

Kind: instance method of HebrewDateEvent

Example

import {HDate, HebrewDateEvent, months} from '@hebcal/core';

const hd = new HDate(15, months.CHESHVAN, 5769);
const ev = new HebrewDateEvent(hd);
console.log(ev.renderBrief()); // '15th of Cheshvan'
console.log(ev.renderBrief('he')); // 'ט״ו חֶשְׁוָן'

~~HebrewDateEvent.renderHebrew(day, monthName, fullYear) ⇒ string~~

Deprecated

Helper function to render a Hebrew date

Kind: static method of HebrewDateEvent

Zmanim

Class representing halachic times

Kind: global class

• Zmanim
  • new Zmanim(date, latitude, longitude)
  • instance
    • ~~.suntime() ⇒ ZmanimTimesResult~~
    • .sunrise() ⇒ Date
    • .sunset() ⇒ Date
    • .dawn() ⇒ Date
    • .dusk() ⇒ Date
    • .hour() ⇒ number
    • .hourMins() ⇒ number
    • .gregEve() ⇒ Date
    • .nightHour() ⇒ number
    • .nightHourMins() ⇒ number
    • .hourOffset(hours) ⇒ Date
    • .chatzot() ⇒ Date
    • .chatzotNight() ⇒ Date
    • .alotHaShachar() ⇒ Date
    • .misheyakir() ⇒ Date
    • .misheyakirMachmir() ⇒ Date
    • .sofZmanShma() ⇒ Date
    • .sofZmanTfilla() ⇒ Date
    • .sofZmanShmaMGA() ⇒ Date
    • .sofZmanTfillaMGA() ⇒ Date
    • .minchaGedola() ⇒ Date
    • .minchaKetana() ⇒ Date
    • .plagHaMincha() ⇒ Date
    • .tzeit([angle]) ⇒ Date
    • .neitzHaChama() ⇒ Date
    • .shkiah() ⇒ Date
    • .sunriseOffset(offset) ⇒ Date
    • .sunsetOffset(offset) ⇒ Date
    • ~~.sunsetOffsetTime(offset, timeFormat) ⇒ Array.<Object>~~
    • ~~.tzeitTime(angle, timeFormat) ⇒ Array.<Object>~~
  • static
    • .formatTime(dt, timeFormat) ⇒ string
    • .roundTime(dt) ⇒ Date
    • .timeZoneOffset(tzid, date) ⇒ string
    • .formatISOWithTimeZone(tzid, date) ⇒ string

new Zmanim(date, latitude, longitude)

Initialize a Zmanim instance.

~~zmanim.suntime() ⇒ ZmanimTimesResult~~

Deprecated

Kind: instance method of Zmanim

zmanim.sunrise() ⇒ Date

Upper edge of the Sun appears over the eastern horizon in the morning (0.833° above horizon)

Kind: instance method of Zmanim

zmanim.sunset() ⇒ Date

When the upper edge of the Sun disappears below the horizon (0.833° below horizon)

Kind: instance method of Zmanim

zmanim.dawn() ⇒ Date

Civil dawn; Sun is 6° below the horizon in the morning

Kind: instance method of Zmanim

zmanim.dusk() ⇒ Date

Civil dusk; Sun is 6° below the horizon in the evening

Kind: instance method of Zmanim

zmanim.hour() ⇒ number

Kind: instance method of Zmanim

zmanim.hourMins() ⇒ number

Kind: instance method of Zmanim

zmanim.gregEve() ⇒ Date

Kind: instance method of Zmanim

zmanim.nightHour() ⇒ number

Kind: instance method of Zmanim

zmanim.nightHourMins() ⇒ number

Kind: instance method of Zmanim

zmanim.hourOffset(hours) ⇒ Date

Kind: instance method of Zmanim

zmanim.chatzot() ⇒ Date

Midday – Chatzot; Sunrise plus 6 halachic hours

Kind: instance method of Zmanim

zmanim.chatzotNight() ⇒ Date

Midnight – Chatzot; Sunset plus 6 halachic hours

Kind: instance method of Zmanim

zmanim.alotHaShachar() ⇒ Date

Dawn – Alot haShachar; Sun is 16.1° below the horizon in the morning

Kind: instance method of Zmanim

zmanim.misheyakir() ⇒ Date

Earliest talis & tefillin – Misheyakir; Sun is 11.5° below the horizon in the morning

Kind: instance method of Zmanim

zmanim.misheyakirMachmir() ⇒ Date

Earliest talis & tefillin – Misheyakir Machmir; Sun is 10.2° below the horizon in the morning

Kind: instance method of Zmanim

zmanim.sofZmanShma() ⇒ Date

Latest Shema (Gra); Sunrise plus 3 halachic hours, according to the Gra

Kind: instance method of Zmanim

zmanim.sofZmanTfilla() ⇒ Date

Latest Shacharit (Gra); Sunrise plus 4 halachic hours, according to the Gra

Kind: instance method of Zmanim

zmanim.sofZmanShmaMGA() ⇒ Date

Latest Shema (MGA); Sunrise plus 3 halachic hours, according to Magen Avraham

Kind: instance method of Zmanim

zmanim.sofZmanTfillaMGA() ⇒ Date

Latest Shacharit (MGA); Sunrise plus 4 halachic hours, according to Magen Avraham

Kind: instance method of Zmanim

zmanim.minchaGedola() ⇒ Date

Earliest Mincha – Mincha Gedola; Sunrise plus 6.5 halachic hours

Kind: instance method of Zmanim

zmanim.minchaKetana() ⇒ Date

Preferable earliest time to recite Minchah – Mincha Ketana; Sunrise plus 9.5 halachic hours

Kind: instance method of Zmanim

zmanim.plagHaMincha() ⇒ Date

Plag haMincha; Sunrise plus 10.75 halachic hours

Kind: instance method of Zmanim

zmanim.tzeit([angle]) ⇒ Date

Kind: instance method of Zmanim

zmanim.neitzHaChama() ⇒ Date

Alias for sunrise

Kind: instance method of Zmanim

zmanim.shkiah() ⇒ Date

Alias for sunset

Kind: instance method of Zmanim

zmanim.sunriseOffset(offset) ⇒ Date

Returns sunrise + offset minutes (either positive or negative).

Kind: instance method of Zmanim

zmanim.sunsetOffset(offset) ⇒ Date

Returns sunset + offset minutes (either positive or negative).

Kind: instance method of Zmanim

~~zmanim.sunsetOffsetTime(offset, timeFormat) ⇒ Array.<Object>~~

Deprecated

Returns an array with sunset + offset Date object, and a 24-hour string formatted time.

Kind: instance method of Zmanim

~~zmanim.tzeitTime(angle, timeFormat) ⇒ Array.<Object>~~

Deprecated

Returns an array with tzeit Date object and a 24-hour string formatted time.

Kind: instance method of Zmanim

Zmanim.formatTime(dt, timeFormat) ⇒ string

Uses timeFormat to return a date like '20:34'

Kind: static method of Zmanim

Zmanim.roundTime(dt) ⇒ Date

Discards seconds, rounding to nearest minute.

Kind: static method of Zmanim

Zmanim.timeZoneOffset(tzid, date) ⇒ string

Get offset string (like "+05:00" or "-08:00") from tzid (like "Europe/Moscow")

Kind: static method of Zmanim

Zmanim.formatISOWithTimeZone(tzid, date) ⇒ string

Returns a string like "2022-04-01T13:06:00-11:00"

Kind: static method of Zmanim

Location

Class representing Location

Kind: global class

• Location
  • new Location(latitude, longitude, il, tzid, cityName, countryCode, geoid)
  • instance
    • .getLatitude() ⇒ number
    • .getLongitude() ⇒ number
    • .getIsrael() ⇒ boolean
    • .getName() ⇒ string
    • .getShortName() ⇒ string
    • .getCountryCode() ⇒ string
    • .getTzid() ⇒ string
    • .getTimeFormatter() ⇒ Intl.DateTimeFormat
    • .getGeoId() ⇒ string
    • ~~.sunset(hdate) ⇒ Date~~
    • ~~.tzeit(hdate, [angle]) ⇒ Date~~
    • .toString() ⇒ string
  • static
    • .lookup(name) ⇒ Location
    • .legacyTzToTzid(tz, dst) ⇒ string
    • .getUsaTzid(state, tz, dst) ⇒ string
    • ~~.geonameCityDescr(cityName, admin1, countryName) ⇒ string~~
    • .addLocation(cityName, location) ⇒ boolean

new Location(latitude, longitude, il, tzid, cityName, countryCode, geoid)

Initialize a Location instance

location.getLatitude() ⇒ number

Kind: instance method of Location

location.getLongitude() ⇒ number

Kind: instance method of Location

location.getIsrael() ⇒ boolean

Kind: instance method of Location

location.getName() ⇒ string

Kind: instance method of Location

location.getShortName() ⇒ string

Returns the location name, up to the first comma

Kind: instance method of Location

location.getCountryCode() ⇒ string

Kind: instance method of Location

location.getTzid() ⇒ string

Kind: instance method of Location

location.getTimeFormatter() ⇒ Intl.DateTimeFormat

Gets a 24-hour time formatter (e.g. 07:41 or 20:03) for this location

Kind: instance method of Location

location.getGeoId() ⇒ string

Kind: instance method of Location

~~location.sunset(hdate) ⇒ Date~~

Deprecated

Kind: instance method of Location

~~location.tzeit(hdate, [angle]) ⇒ Date~~

Deprecated

Kind: instance method of Location

location.toString() ⇒ string

Kind: instance method of Location

Location.lookup(name) ⇒ Location

Creates 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

Location.legacyTzToTzid(tz, dst) ⇒ string

Converts legacy Hebcal timezone to a standard Olson tzid.

Kind: static method of Location

Location.getUsaTzid(state, tz, dst) ⇒ string

Converts timezone info from Zip-Codes.com to a standard Olson tzid.

Kind: static method of Location

Example

Location.getUsaTzid('AZ', 7, 'Y') // 'America/Denver'

~~Location.geonameCityDescr(cityName, admin1, countryName) ⇒ string~~

Deprecated

Builds a city description from geonameid string components

Kind: static method of Location

Location.addLocation(cityName, location) ⇒ boolean

Adds 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

TimedEvent

An event that has an eventTime and eventTimeStr

Kind: global class

• TimedEvent
  • new TimedEvent(date, desc, mask, eventTime, location, linkedEvent)
  • .render([locale]) ⇒ string
  • .renderBrief([locale]) ⇒ string

new TimedEvent(date, desc, mask, eventTime, location, linkedEvent)

timedEvent.render([locale]) ⇒ string

Kind: instance method of TimedEvent

timedEvent.renderBrief([locale]) ⇒ string

Returns translation of "Candle lighting" without the time.

Kind: instance method of TimedEvent

HavdalahEvent

Havdalah after Shabbat or holiday

Kind: global class

• HavdalahEvent
  • new HavdalahEvent(date, mask, eventTime, location, havdalahMins, linkedEvent)
  • .render([locale]) ⇒ string
  • .renderBrief([locale]) ⇒ string
  • .getEmoji() ⇒ string

new HavdalahEvent(date, mask, eventTime, location, havdalahMins, linkedEvent)

havdalahEvent.render([locale]) ⇒ string

Kind: instance method of HavdalahEvent

havdalahEvent.renderBrief([locale]) ⇒ string

Returns translation of "Havdalah" without the time.

Kind: instance method of HavdalahEvent

havdalahEvent.getEmoji() ⇒ string

Kind: instance method of HavdalahEvent

CandleLightingEvent

Candle lighting before Shabbat or holiday

Kind: global class

• CandleLightingEvent
  • new CandleLightingEvent(date, mask, eventTime, location, linkedEvent)
  • .getEmoji() ⇒ string

new CandleLightingEvent(date, mask, eventTime, location, linkedEvent)

candleLightingEvent.getEmoji() ⇒ string

Kind: instance method of CandleLightingEvent

Molad

Represents a molad, the moment when the new moon is "born"

Kind: global class

• Molad
  • new Molad(year, month)
  • .getYear() ⇒ number
  • .getMonth() ⇒ number
  • .getMonthName() ⇒ string
  • .getDow() ⇒ number
  • .getHour() ⇒ number
  • .getMinutes() ⇒ number
  • .getChalakim() ⇒ number

new Molad(year, month)

Calculates the molad for a Hebrew month

molad.getYear() ⇒ number

Kind: instance method of Molad

molad.getMonth() ⇒ number

Kind: instance method of Molad

molad.getMonthName() ⇒ string

Kind: instance method of Molad

molad.getDow() ⇒ number

Kind: instance method of Molad
Returns: number - Day of Week (0=Sunday, 6=Saturday)

molad.getHour() ⇒ number

Kind: instance method of Molad
Returns: number - hour of day (0-23)

molad.getMinutes() ⇒ number

Kind: instance method of Molad
Returns: number - minutes past hour (0-59)

molad.getChalakim() ⇒ number

Kind: instance method of Molad
Returns: number - parts of a minute (0-17)

MoladEvent

Represents a Molad announcement on Shabbat Mevarchim

Kind: global class

• MoladEvent
  • new MoladEvent(date, hyear, hmonth)
  • .render([locale]) ⇒ string

new MoladEvent(date, hyear, hmonth)

moladEvent.render([locale]) ⇒ string

Kind: instance method of MoladEvent

OmerEvent

Represents a day 1-49 of counting the Omer from Pesach to Shavuot

Kind: global class

• OmerEvent
  • new OmerEvent(date, omerDay)
  • .sefira(lang) ⇒ string
  • .render([locale]) ⇒ string
  • .renderBrief([locale]) ⇒ string
  • .getEmoji() ⇒ string
  • .getWeeks() ⇒ number
  • .getDaysWithinWeeks() ⇒ number
  • .getTodayIs(locale) ⇒ string
  • .url() ⇒ string

new OmerEvent(date, omerDay)

omerEvent.sefira(lang) ⇒ string

Kind: instance method of OmerEvent

omerEvent.render([locale]) ⇒ string

Kind: instance method of OmerEvent
Todo

• [ ] use gettext()

omerEvent.renderBrief([locale]) ⇒ string

Returns translation of "Omer day 22" without ordinal numbers.

Kind: instance method of OmerEvent

omerEvent.getEmoji() ⇒ string

Kind: instance method of OmerEvent

omerEvent.getWeeks() ⇒ number

Kind: instance method of OmerEvent

omerEvent.getDaysWithinWeeks() ⇒ number

Kind: instance method of OmerEvent

omerEvent.getTodayIs(locale) ⇒ string

Kind: instance method of OmerEvent

omerEvent.url() ⇒ string

Kind: instance method of OmerEvent

DafYomi

Returns the Daf Yomi for given date

Kind: global class

• DafYomi
  • new DafYomi(gregdate)
  • .getBlatt() ⇒ number
  • .getName() ⇒ string
  • .render([locale]) ⇒ string

new DafYomi(gregdate)

Initializes a daf yomi instance

dafYomi.getBlatt() ⇒ number

Kind: instance method of DafYomi

dafYomi.getName() ⇒ string

Kind: instance method of DafYomi

dafYomi.render([locale]) ⇒ string

Formats (with translation) the dafyomi result as a string like "Pesachim 34"

Kind: instance method of DafYomi

DafYomiEvent

Event wrapper around a DafYomi instance

Kind: global class

• DafYomiEvent
  • new DafYomiEvent(date)
  • .render([locale]) ⇒ string
  • .renderBrief([locale]) ⇒ string
  • .url() ⇒ string

new DafYomiEvent(date)

dafYomiEvent.render([locale]) ⇒ string

Returns Daf Yomi name including the 'Daf Yomi: ' prefix (e.g. "Daf Yomi: Pesachim 107").

Kind: instance method of DafYomiEvent

dafYomiEvent.renderBrief([locale]) ⇒ string

Returns Daf Yomi name without the 'Daf Yomi: ' prefix (e.g. "Pesachim 107").

Kind: instance method of DafYomiEvent

dafYomiEvent.url() ⇒ string

Returns a link to sefaria.org or dafyomi.org

Kind: instance method of DafYomiEvent

Sedra

Represents Parashah HaShavua for an entire Hebrew year

Kind: global class

• Sedra
  • new Sedra(hebYr, il)
  • .get(hDate) ⇒ Array.<string>
  • .getString(hDate, [locale]) ⇒ string
  • .isParsha(hDate) ⇒ boolean
  • .find(parsha) ⇒ HDate
  • .getFirstSaturday() ⇒ number
  • .getYear() ⇒ number
  • .lookup(hDate) ⇒ SedraResult

new Sedra(hebYr, il)

Caculates the Parashah HaShavua for an entire Hebrew year

sedra.get(hDate) ⇒ Array.<string>

Returns the parsha (or parshiyot) read on Hebrew date

Kind: instance method of Sedra

sedra.getString(hDate, [locale]) ⇒ string

Looks up parsha for the date, then returns a translated or transliterated string

Kind: instance method of Sedra

sedra.isParsha(hDate) ⇒ boolean

Checks to see if this day would be a regular parasha HaShavua Torah reading or special holiday reading

Kind: instance method of Sedra

sedra.find(parsha) ⇒ HDate

Returns the date that a parsha occurs

Kind: instance method of Sedra

sedra.getFirstSaturday() ⇒ number

R.D. date of the first Saturday on or after Rosh Hashana

Kind: instance method of Sedra

sedra.getYear() ⇒ number

Kind: instance method of Sedra

sedra.lookup(hDate) ⇒ SedraResult

Returns an object describing the parsha on the first Saturday on or after absdate

Kind: instance method of Sedra

ParshaEvent

Represents one of 54 weekly Torah portions, always on a Saturday

Kind: global class

• ParshaEvent
  • new ParshaEvent(date, parsha, il, num)
  • .render([locale]) ⇒ string
  • .basename() ⇒ string
  • .url() ⇒ string
  • .urlDateSuffix() ⇒ string

new ParshaEvent(date, parsha, il, num)

parshaEvent.render([locale]) ⇒ string

Kind: instance method of ParshaEvent

parshaEvent.basename() ⇒ string

Kind: instance method of ParshaEvent

parshaEvent.url() ⇒ string

Kind: instance method of ParshaEvent

parshaEvent.urlDateSuffix() ⇒ string

Kind: instance method of ParshaEvent

HolidayEvent

Represents a built-in holiday like Pesach, Purim or Tu BiShvat

Kind: global class

• HolidayEvent
  • new HolidayEvent(date, desc, [mask], [attrs])
  • .basename() ⇒ string
  • .url() ⇒ string
  • .urlDateSuffix() ⇒ string
  • .getEmoji() ⇒ string

new HolidayEvent(date, desc, [mask], [attrs])

Constructs Holiday event

holidayEvent.basename() ⇒ string

Kind: instance method of HolidayEvent

holidayEvent.url() ⇒ string

Kind: instance method of HolidayEvent

holidayEvent.urlDateSuffix() ⇒ string

Kind: instance method of HolidayEvent

holidayEvent.getEmoji() ⇒ string

Kind: instance method of HolidayEvent

RoshChodeshEvent

Represents Rosh Chodesh, the beginning of a new month

Kind: global class

• RoshChodeshEvent
  • new RoshChodeshEvent(date, monthName)
  • .render([locale]) ⇒ string
  • .basename() ⇒ string
  • .getEmoji() ⇒ string

new RoshChodeshEvent(date, monthName)

Constructs Rosh Chodesh event

roshChodeshEvent.render([locale]) ⇒ string

Returns (translated) description of this event

Kind: instance method of RoshChodeshEvent

roshChodeshEvent.basename() ⇒ string

Kind: instance method of RoshChodeshEvent

roshChodeshEvent.getEmoji() ⇒ string

Kind: instance method of RoshChodeshEvent

AsaraBTevetEvent

Because Asara B'Tevet often occurs twice in the same Gregorian year, we subclass HolidayEvent to override the url() method.

Kind: global class

• AsaraBTevetEvent
  • new AsaraBTevetEvent(date, desc, [mask], [attrs])
  • .urlDateSuffix() ⇒ string

new AsaraBTevetEvent(date, desc, [mask], [attrs])

Constructs AsaraBTevetEvent

asaraBTevetEvent.urlDateSuffix() ⇒ string

Kind: instance method of AsaraBTevetEvent

MevarchimChodeshEvent

Represents Mevarchim haChodesh, the announcement of the new month

Kind: global class

• MevarchimChodeshEvent
  • new MevarchimChodeshEvent(date, monthName)
  • .basename() ⇒ string
  • .render([locale]) ⇒ string

new MevarchimChodeshEvent(date, monthName)

Constructs Mevarchim haChodesh event

mevarchimChodeshEvent.basename() ⇒ string

Kind: instance method of MevarchimChodeshEvent

mevarchimChodeshEvent.render([locale]) ⇒ string

Returns (translated) description of this event

Kind: instance method of MevarchimChodeshEvent

MishnaYomiIndex

A program of daily learning in which participants study two Mishnahs each day in order to finish the entire Mishnah in ~6 years.

Kind: global class

• MishnaYomiIndex
  • new MishnaYomiIndex()
  • .days : Array.<MishnaYomi>
  • .lookup(date) ⇒ Array.<MishnaYomi>

new MishnaYomiIndex()

Initializes a Mishna Yomi instance

mishnaYomiIndex.days : Array.<MishnaYomi>

Kind: instance property of MishnaYomiIndex

mishnaYomiIndex.lookup(date) ⇒ Array.<MishnaYomi>

Looks up a Mishna Yomi

Kind: instance method of MishnaYomiIndex

MishnaYomiEvent

Event wrapper around a Mishna Yomi instance

Kind: global class

• MishnaYomiEvent
  • new MishnaYomiEvent(date, mishnaYomi)
  • .render([locale]) ⇒ string
  • .url() ⇒ string

new MishnaYomiEvent(date, mishnaYomi)

mishnaYomiEvent.render([locale]) ⇒ string

Returns Mishna Yomi name (e.g. "Bava Metzia 10:5-6" or "Berakhot 9:5-Peah 1:1").

Kind: instance method of MishnaYomiEvent

mishnaYomiEvent.url() ⇒ string

Returns a link to sefaria.org

Kind: instance method of MishnaYomiEvent

HebrewCalendar

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 class

• HebrewCalendar
  • .calendar([options]) ⇒ Array.<Event>
  • .getBirthdayOrAnniversary(hyear, gdate) ⇒ HDate
  • .getYahrzeit(hyear, gdate) ⇒ HDate
  • .getHolidaysForYear(year) ⇒ Map.<string, Array.<Event>>
  • .getHolidaysForYearArray(year, il) ⇒ Array.<Event>
  • .getHolidaysOnDate(date, [il]) ⇒ Array.<Event>
  • .reformatTimeStr(timeStr, suffix, options) ⇒ string
  • .version() ⇒ string
  • .getSedra(hyear, il) ⇒ Sedra
  • .hallel(hdate, il) ⇒ number
  • .tachanun(hdate, il) ⇒ TachanunResult

HebrewCalendar.calendar([options]) ⇒ Array.<Event>

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)
• Daf Yomi (options.dafyomi)
• Mishna Yomi (options.mishnaYomi)
• Shabbat Mevarchim HaChodesh on Saturday before Rosh Chodesh (options.shabbatMevarchim)
• Molad announcement on Saturday before Rosh Chodesh (options.molad)
• Yom Kippur Katan (options.yomKippurKatan)

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) 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 supressed when options.havdalahMins=0.
• options.havdalahDeg - degrees for solar depression for Havdalah. Default is 8.5 degrees for 3 small stars. Use 7.083 degress for 3 medium-sized stars. Havdalah times are supressed 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 dusk (when the sun is 6.0° 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

Kind: static method of HebrewCalendar

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());
}

HebrewCalendar.getBirthdayOrAnniversary(hyear, gdate) ⇒ HDate

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]

Kind: static method of HebrewCalendar
Returns: HDate - anniversary occurring in hyear

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'

HebrewCalendar.getYahrzeit(hyear, gdate) ⇒ 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]

Kind: static method of HebrewCalendar
Returns: HDate - anniversary occurring in hyear

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'

HebrewCalendar.getHolidaysForYear(year) ⇒ 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

HebrewCalendar.getHolidaysForYearArray(year, il) ⇒ Array.<Event>

Returns an array of holidays for the year

Kind: static method of HebrewCalendar

HebrewCalendar.getHolidaysOnDate(date, [il]) ⇒ Array.<Event>

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

Kind: static method of HebrewCalendar

HebrewCalendar.reformatTimeStr(timeStr, suffix, options) ⇒ string

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.

Kind: static method of HebrewCalendar

HebrewCalendar.version() ⇒ string

Kind: static method of HebrewCalendar

HebrewCalendar.getSedra(hyear, il) ⇒ Sedra

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

Kind: static method of HebrewCalendar

HebrewCalendar.hallel(hdate, il) ⇒ number

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

Kind: static method of HebrewCalendar

HebrewCalendar.tachanun(hdate, il) ⇒ TachanunResult

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.

Kind: static method of HebrewCalendar

months : enum

Hebrew months of the year (NISAN=1, TISHREI=7)

Kind: global enum
Read only: true
Properties

flags : enum

Holiday flags for Event

Kind: global enum
Read only: true
Properties

parshiot : 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

gematriya(number) ⇒ string

Converts a numerical value to a string of Hebrew letters.

When specifying years of the Hebrew calendar in the present millennium, we omit the thousands (which is presently 5 [ה]).

Kind: global function

Example

gematriya(5774) // 'תשע״ד' - cropped to 774
gematriya(25) // 'כ״ה'
gematriya(60) // 'ס׳'
gematriya(3761) // 'ג׳תשס״א'
gematriya(1123) // 'א׳קכ״ג'

ZmanimTimesResult : Object

Kind: global typedef
Properties

SedraResult : Object

Result of Sedra.lookup

Kind: global typedef
Properties

MishnaYomi : Object

Describes a mishna to be read

Kind: global typedef
Properties

CalOptions : Object

Options to configure which events are returned

Kind: global typedef
Properties

TachanunResult : Object

Kind: global typedef
Properties