Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More →

@hebcal/core

Package Overview

Dependencies

Advanced tools

Install Socket

Detect and block malicious and high-risk dependencies

Install

@hebcal/core

A perpetual Jewish Calendar API

1.2.2
Source
npm

Version published: 4 years ago

Weekly downloads: 3.1K; increased by120.65%

Maintainers: 1

Weekly downloads

Created: 4 years ago

Source

hebcal-es6

Hebcal, a perpetual Jewish Calendar (ES6)

Installation

$ npm install @hebcal/core

Synopsis

import {hebcal, 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 = hebcal.hebrewCalendar(options);

for (const ev of events) {
  const hd = ev.getDate();
  const date = hd.greg();
  console.log(date.toLocaleDateString(), ev.render(), hd.toString());
}

Classes

Event: Represents an Event with a title, date, and flags
HDate: Class representing a Hebrew date
HebrewDateEvent: Daily Hebrew date ("11th of Sivan, 5780")
Zmanim: Class representing halachic times
Location: Class representing Location
HavdalahEvent: Havdalah after Shabbat or holiday
CandleLightingEvent: Candle lighting before Shabbat or holiday
MoladEvent: Represents a Molad announcement on Shabbat Mevarchim
OmerEvent: Represents a day 1-49 of counting the Omer from Pesach to Shavuot
DafYomiEvent: For a Daf Yomi, the name is already translated attrs.dafyomi.name contains the untranslated string
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
MevarchimChodeshEvent: Represents Mevarchim haChodesh, the announcement of the new month

Objects

common : object: Common hebrew date routines
dafyomi$1 : object: Daf Yomi
greg : object: Gregorian date routines
holidays : object: Lower-level holidays interface
hebcal : object: Main interface to Hebcal

Functions

hebLeapYear(x) ⇒ boolean

Returns true if Hebrew year is a leap year

monthsInHebYear(x) ⇒ number

Number of months in Hebrew year

daysInHebMonth(month, year) ⇒ number

Number of days in Hebrew month in a given year

getMonthName(month, year) ⇒ string

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

monthNum(month) ⇒ number

Returns the Hebrew month number

hebElapsedDays(hYear) ⇒ number

Days from sunday prior to start of Hebrew calendar to mean conjunction of Tishrei in Hebrew YEAR

daysInYear(year) ⇒ number

Number of days in the hebrew YEAR

longCheshvan(year) ⇒ boolean

true if Cheshvan is long in Hebrew YEAR

shortKislev(year) ⇒ boolean

true if Kislev is short in Hebrew YEAR

monthFromName(c) ⇒ number

Converts Hebrew month string name to numeric

dayOnOrBefore(day_of_week, 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.

range(start, end, [step]) ⇒ Array.<number>

Returns an array from start to end

gregLeapYear(year) ⇒ boolean

Returns true if the Gregorian year is a leap year

daysInGregMonth(month, year) ⇒ number

Number of days in the Gregorian month for given year

dayOfYear(date) ⇒ number

Returns number of days since January 1 of that year

greg2abs(date) ⇒ number

Converts Gregorian date to Julian Day Count

abs2greg(theDate) ⇒ Date

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

lookupTranslation(id, [locale]) ⇒ string

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

gettext(id, [locale]) ⇒ string

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

addLocale(locale, data)

registerLocale(locale, data)

Alias for addLocale()

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.

hebrewStripNikkud(str) ⇒ string

Removes nekudot from Hebrew string

onOrBefore(day, t, offset) ⇒ HDate

hebrew2abs(d) ⇒ number

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

abs2hebrew(d) ⇒ SimpleHebrewDate

Converts absolute Julian days to Hebrew date

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]

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]

throwError(error)

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

formatTime(timeFormat, dt) ⇒ string

sunsetTime(hd, location, timeFormat, offset) ⇒ Array.<Object>

tzeitTime(hd, location, timeFormat) ⇒ Array.<Object>

makeCandleEvent(e, hd, dow, location, timeFormat, candlesOffset, [havdalahOffset]) ⇒ Event

getMolad(year, month) ⇒ Molad

Calculates the molad for a Hebrew month

dafyomi(gregdate) ⇒ DafYomiResult

Returns the Daf Yomi for given date

dafname(daf, [locale]) ⇒ string

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

D(p) ⇒ number

parsha doubler/undoubler

abs(year, absDate) ⇒ Object

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

chanukah(day) ⇒ string

getHolidaysForYear(year) ⇒ Map.<string, Array.<Event>>

Returns a Map for the year indexed by HDate.toString()

getHolidaysOnDate(date) ⇒ Array.<Event>

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

reformatTimeStr(timeStr, suffix, options) ⇒ string

Returns "8:13p" for US or "20:13" for any other locale/country

makeAnchor(s) ⇒ string

getCandleLightingMinutes(options) ⇒ number

getAbs(d) ⇒ number

Gets the Julian absolute days for a number, Date, or HDate

getStartAndEnd(options) ⇒ Array.<number>

Parse options object to determine start & end days

getOmerStartAndEnd(hyear) ⇒ Array.<number>

getMaskFromOptions(options) ⇒ number

Mask to filter Holiday array

hebrewCalendar(options) ⇒ Array.<Event>

Generates a list of holidays

Typedefs

SimpleHebrewDate : Object: A simple Hebrew date object with numeric fields yy, mm, and dd
Molad : Object: Represents a Molad
DafYomiResult : Object: A Daf Yomi result
HebcalOptions : Object: Options to configure which events are returned

Event

Represents an Event with a title, date, and flags

Kind: global class

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

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

Constructs Event

Param	Type	Default	Description
date	`HDate`		Hebrew date event occurs
desc	`string`		Description (not translated)
[mask]	`number`	`0`	optional holiday flags
[attrs]	`Object`	`{}`

event.getFlags() ⇒ `number`

Kind: instance method of Event

event.getAttrs() ⇒ `Object`

Kind: instance method of Event

event.observedInIsrael() ⇒ `boolean`

Is this event observed in Israel?

Kind: instance method of Event

event.observedInDiaspora() ⇒ `boolean`

Is this event observed in the Diaspora?

Kind: instance method of Event

event.render([locale]) ⇒ `string`

Returns (translated) description of this event

Kind: instance method of Event

Param	Type	Description
[locale]	`string`	Optional locale name (defaults to active locale).

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

Param	Type	Description
[locale]	`string`	Optional locale name (defaults to active locale).

event.getDesc() ⇒ `string`

Returns untranslated description of this event

Kind: instance method of Event

event.basename() ⇒ `string`

Returns 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

event.getDate() ⇒ `HDate`

Returns Hebrew date of this event

Kind: instance method of Event

event.url() ⇒ `string`

Kind: instance method of Event

HDate

Class representing a Hebrew date

Kind: global class

HDate
- new HDate([day], [month], [year])
- .getFullYear() ⇒ number
- .isLeapYear() ⇒ boolean
- .getMonth() ⇒ number
- .getTishreiMonth() ⇒ number
- .daysInMonth() ⇒ number
- .getDate() ⇒ number
- .getDay() ⇒ number
- .setFullYear(year) ⇒ HDate
- .setMonth(month) ⇒ HDate
- .setTishreiMonth(month) ⇒ HDate
- .setDate(date) ⇒ HDate
- .greg() ⇒ Date
- .abs() ⇒ number
- .getMonthName() ⇒ string
- .render([locale]) ⇒ string
- .before(day) ⇒ HDate
- .onOrBefore(day) ⇒ HDate
- .nearest(day) ⇒ HDate
- .onOrAfter(day) ⇒ HDate
- .after(day) ⇒ HDate
- .next() ⇒ HDate
- .prev() ⇒ HDate
- .isSameDate(other) ⇒ boolean
- .toString() ⇒ string

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

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

No parameters - represents the current Hebrew date at time of instantiation
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 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
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.

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, common} 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, common.months.CHESHVAN, 5769);
const hd5 = new HDate(733359); // ==> 15 Cheshvan 5769
const monthName = 'אייר';
const hd6 = new HDate(5, monthName, 5773);