@hebcal/core

v5.3.5

Published

4 days ago

A perpetual Jewish Calendar API

Downloads

7,810

0High
0Medium
0Low

mjradwin

hebcal hebrew calendar jewish holidays chagim sedra date dafyomi zemanim zmanim

@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('en'), hd.toString());
}

Classes

Members

Constants

Functions

Typedefs

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)
- .addTranslation(locale, id, translation)
- .addTranslations(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

| Param | Type | Description | | --- | --- | --- | | id | string | Message ID to translate | | [locale] | string | Optional locale name (i.e: 'he', 'fr'). Defaults to active locale. |

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

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

Locale.addLocale(locale, data)

Kind: static method of Locale

| Param | Type | Description | | --- | --- | --- | | locale | string | Locale name (i.e.: 'he', 'fr') | | data | LocaleData | parsed data from a .po file. |

Locale.addTranslation(locale, id, translation)

Adds a translation to locale, replacing any previous translation.

Kind: static method of Locale

| Param | Type | Description | | --- | --- | --- | | locale | string | Locale name (i.e: 'he', 'fr'). | | id | string | Message ID to translate | | translation | string | Translation text |

Locale.addTranslations(locale, data)

Adds multiple translations to locale, replacing any previous translations.

Kind: static method of Locale

| Param | Type | Description | | --- | --- | --- | | locale | string | Locale name (i.e: 'he', 'fr'). | | data | LocaleData | parsed data from a .po file. |

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

| Param | Type | Description | | --- | --- | --- | | locale | string | Locale name (i.e: 'he', 'fr') |

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

| Param | Type | Description | | --- | --- | --- | | n | number | | | [locale] | string | Optional locale name (i.e: 'he', 'fr'). Defaults to active locale. |

Locale.hebrewStripNikkud(str) ⇒ string

Removes nekudot from Hebrew string

Kind: static method of Locale

| Param | Type | | --- | --- | | str | string |

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([suppressNikud]) ⇒ 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
  - .fromGematriyaString(str, currentThousands) ⇒ HDate

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 R.D. days to Hebrew date. R.D. 1 == the imaginary date January 1, 1 (Gregorian)
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, 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

| Param | Type | Default | Description | | --- | --- | --- | --- | | [locale] | string | null | Optional locale name (defaults to active locale). | | [showYear] | boolean | true | Display year (defaults to true). |

Example

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

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

hDate.renderGematriya([suppressNikud]) ⇒ string

Renders this Hebrew date in Hebrew gematriya, regardless of locale.

Kind: instance method of HDate

| Param | Type | Default | | --- | --- | --- | | [suppressNikud] | boolean | false |

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

| Param | Type | Description | | --- | --- | --- | | day | number | day of week |

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

| 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

hDate.nearest(dow) ⇒ HDate

Returns 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

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

| 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

hDate.after(day) ⇒ HDate

Returns 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

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.

| Unit | Shorthand | Description | --- | --- | --- | | day | d | days | | week | w | weeks | | month | M | months | | year | y | years |

Kind: instance method of HDate

| Param | Type | Default | | --- | --- | --- | | number | number | | | [units] | string | "d" |

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.

| Unit | Shorthand | Description | --- | --- | --- | | day | d | days | | week | w | weeks | | month | M | months | | year | y | years |

Kind: instance method of HDate

| Param | Type | Default | | --- | --- | --- | | number | number | | | [units] | string | "d" |

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

| Param | Type | Description | | --- | --- | --- | | other | HDate | Hebrew date to compare |

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

| Param | Type | Description | | --- | --- | --- | | other | HDate | Hebrew date to compare |

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

| Param | Type | Description | | --- | --- | --- | | year | number | Hebrew year | | month | number | Hebrew month | | day | number | Hebrew date (1-30) |

HDate.isLeapYear(year) ⇒ boolean

Returns true if Hebrew year is a leap year

Kind: static method of HDate

| Param | Type | Description | | --- | --- | --- | | year | number | Hebrew year |

HDate.monthsInYear(year) ⇒ number

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

HDate.daysInMonth(month, year) ⇒ number

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

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

| Param | Type | Description | | --- | --- | --- | | month | number | Hebrew month (e.g. months.TISHREI) | | year | number | Hebrew year |

HDate.monthNum(month) ⇒ number

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

HDate.daysInYear(year) ⇒ number

Number of days in the hebrew YEAR

Kind: static method of HDate

| Param | Type | Description | | --- | --- | --- | | year | number | Hebrew year |

HDate.longCheshvan(year) ⇒ boolean

true if Cheshvan is long in Hebrew year

Kind: static method of HDate

| Param | Type | Description | | --- | --- | --- | | year | number | Hebrew year |

HDate.shortKislev(year) ⇒ boolean

true if Kislev is short in Hebrew year

Kind: static method of HDate

| Param | Type | Description | | --- | --- | --- | | year | number | Hebrew year |

HDate.monthFromName(monthName) ⇒ number

Converts Hebrew month string name to numeric

Kind: static method of HDate

| Param | Type | Description | | --- | --- | --- | | monthName | string | number | monthName |

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

| Param | Type | | --- | --- | | dayOfWeek | number | | absdate | number |

HDate.isHDate(obj) ⇒ boolean

Tests if the object is an instance of HDate

Kind: static method of HDate

| Param | Type | | --- | --- | | obj | any |

HDate.fromGematriyaString(str, currentThousands) ⇒ HDate

Construct a new instance of HDate from a Gematriya-formatted string

Kind: static method of HDate

| Param | Type | Default | | --- | --- | --- | | str | string | | | currentThousands | number | 5000 |

Example

HDate.fromGematriyaString('כ״ז בְּתַמּוּז תשפ״ג') // 27 Tamuz 5783
 HDate.fromGematriyaString('כ׳ סיון תש״ד') // 20 Sivan 5704
 HDate.fromGematriyaString('ה׳ אִיָיר תש״ח') // 5 Iyyar 5708

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
- .clone() ⇒ Event
- .getCategories() ⇒ Array.<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 bitmask of holiday flags (see flags) | | [attrs] | Object | {} | optional additional attributes (e.g. eventTimeStr, cholHaMoedDay) |

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

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

Example

const ev = new Event(new HDate(6, 'Sivan', 5749), 'Shavuot', flags.CHAG);
ev.render('en'); // '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

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

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

| Param | Type | | --- | --- | | il | boolean |

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.clone() ⇒ Event

Makes a clone of this Event object

Kind: instance method of Event

event.getCategories() ⇒ Array.<string>

Returns a list of event categories

Kind: instance method of Event

HebrewDateEvent

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

Kind: global class

HebrewDateEvent
- new HebrewDateEvent(date)
- .render([locale]) ⇒ string
- .renderBrief([locale]) ⇒ string

new HebrewDateEvent(date)

| Param | Type | | --- | --- | | date | HDate |

hebrewDateEvent.render([locale]) ⇒ string

Kind: 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('en')); // '15th of Cheshvan, 5769'
console.log(ev.render('he')); // 'ט״ו חֶשְׁוָן תשס״ט'

hebrewDateEvent.renderBrief([locale]) ⇒ string

Kind: 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.renderBrief()); // '15th of Cheshvan'
console.log(ev.renderBrief('he')); // 'ט״ו חֶשְׁוָן'

GeoLocation

A class that contains location information such as latitude and longitude required for astronomical calculations. The elevation field may not be used by some calculation engines and would be ignored if set.

GeoLocation
- new GeoLocation(name, latitude, longitude, elevation, timeZoneId)
- .getElevation() ⇒ number
- .setElevation(elevation)
- .getLatitude() ⇒ number
- .getLongitude() ⇒ number
- .getLocationName() ⇒ string | null
- .setLocationName(name)
- .getTimeZone() ⇒ string
- .setTimeZone(timeZoneId)

new GeoLocation(name, latitude, longitude, elevation, timeZoneId)

GeoLocation constructor with parameters for all required fields.

| Param | Type | Description | | --- | --- | --- | | name | string | The location name for display use such as "Lakewood, NJ" | | latitude | number | the latitude in a double format such as 40.095965 for Lakewood, NJ. Note: For latitudes south of the equator, a negative value should be used. | | longitude | number | double the longitude in a double format such as -74.222130 for Lakewood, NJ. Note: For longitudes west of the Prime Meridian (Greenwich), a negative value should be used. | | elevation | number | the elevation above sea level in Meters. Elevation is not used in most algorithms used for calculating sunrise and set. | | timeZoneId | string | the TimeZone for the location. |

geoLocation.getElevation() ⇒ number

Method to get the elevation in Meters.

Kind: instance method of GeoLocation
Returns: number - Returns the elevation in Meters.

geoLocation.setElevation(elevation)

Method to set the elevation in Meters above sea level.

Kind: instance method of GeoLocation

| Param | Type | Description | | --- | --- | --- | | elevation | number | The elevation to set in Meters. An Error will be thrown if the value is a negative. |

geoLocation.getLatitude() ⇒ number

Kind: instance method of GeoLocation
Returns: number - Returns the latitude.

geoLocation.getLongitude() ⇒ number

Kind: instance method of GeoLocation
Returns: number - Returns the longitude.

geoLocation.getLocationName() ⇒ string | null

Kind: instance method of GeoLocation
Returns: string | null - Returns the location name.

geoLocation.setLocationName(name)

Kind: instance method of GeoLocation

| Param | Type | Description | | --- | --- | --- | | name | string | null | The setter method for the display name. |

geoLocation.getTimeZone() ⇒ string

Kind: instance method of GeoLocation
Returns: string - Returns the timeZone.

geoLocation.setTimeZone(timeZoneId)

Method to set the TimeZone.

Kind: instance method of GeoLocation

| Param | Type | Description | | --- | --- | --- | | timeZoneId | string | The timeZone to set. |

NOAACalculator

Implementation of sunrise and sunset methods to calculate astronomical times based on the NOAA algorithm. This calculator uses the Java algorithm based on the implementation by NOAA - National Oceanic and Atmospheric Administration's Surface Radiation Research Branch. NOAA's implementation is based on equations from Astronomical Algorithms by Jean Meeus. Added to the algorithm is an adjustment of the zenith to account for elevation. The algorithm can be found in the Wikipedia Sunrise Equation article.

NOAACalculator
- new NOAACalculator(geoLocation, date)
- instance
  - .CIVIL_ZENITH
  - .NAUTICAL_ZENITH
  - .ASTRONOMICAL_ZENITH
  - .getSunrise() ⇒ Temporal.ZonedDateTime | null
  - .getSeaLevelSunrise() ⇒ Temporal.ZonedDateTime | null
  - .getBeginCivilTwilight() ⇒ Temporal.ZonedDateTime | null
  - .getBeginNauticalTwilight() ⇒ Temporal.ZonedDateTime | null
  - .getBeginAstronomicalTwilight() ⇒ Temporal.ZonedDateTime | null
  - .getSunset() ⇒ Temporal.ZonedDateTime | null
  - .getSeaLevelSunset() ⇒ Temporal.ZonedDateTime | null
  - .getEndCivilTwilight() ⇒ Temporal.ZonedDateTime | null
  - .getEndNauticalTwilight() ⇒ Temporal.ZonedDateTime | null
  - .getEndAstronomicalTwilight() ⇒ Temporal.ZonedDateTime | null
  - .getSunriseOffsetByDegrees(offsetZenith) ⇒ Temporal.ZonedDateTime | null
  - .getSunsetOffsetByDegrees(offsetZenith) ⇒ Temporal.ZonedDateTime | null
  - .getUTCSunrise0(zenith) ⇒ number
  - .getUTCSeaLevelSunrise(zenith) ⇒ number
  - .getUTCSunset0(zenith) ⇒ number
  - .getUTCSeaLevelSunset(zenith) ⇒ number
  - .getElevationAdjustment(elevation) ⇒ number
  - .adjustZenith(zenith, elevation) ⇒ number
  - .getUTCSunrise(date, geoLocation, zenith, adjustForElevation) ⇒
  - .getUTCSunset(date, geoLocation, zenith, adjustForElevation) ⇒
  - .getTemporalHour(startOfDay, endOfDay) ⇒ number
  - .getSunTransit(startOfDay, endOfDay) ⇒ Temporal.ZonedDateTime | null
  - .getDateFromTime(time, isSunrise) ⇒ Temporal.ZonedDateTime | null
- static
  - .getTimeOffset(time, offset) ⇒ Temporal.ZonedDateTime | null
  - .getSolarElevation(date, lat, lon) ⇒ number
  - .getSolarAzimuth(date, latitude, lon) ⇒ number

new NOAACalculator(geoLocation, date)

A constructor that takes in geolocation information as a parameter.

| Param | Type | Description | | --- | --- | --- | | geoLocation | GeoLocation | The location information used for calculating astronomical sun times. | | date | Temporal.PlainDate | |

noaaCalculator.CIVIL_ZENITH

Sun's zenith at civil twilight (96°).

Kind: instance property of NOAACalculator

noaaCalculator.NAUTICAL_ZENITH

Sun's zenith at nautical twilight (102°).

Kind: instance property of NOAACalculator

noaaCalculator.ASTRONOMICAL_ZENITH

Sun's zenith at astronomical twilight (108°).

Kind: instance property of NOAACalculator

noaaCalculator.getSunrise() ⇒ Temporal.ZonedDateTime | null

The getSunrise method Returns a Date representing the elevation adjusted sunrise time. The zenith used for the calculation uses geometric zenith of 90° plus getElevationAdjustment. This is adjusted to add approximately 50/60 of a degree to account for 34 archminutes of refraction and 16 archminutes for the sun's radius for a total of 90.83333°.

Kind: instance method of NOAACalculator
Returns: Temporal.ZonedDateTime | null - the Date representing the exact sunrise time. If the calculation can't be computed such as in the Arctic Circle where there is at least one day a year where the sun does not rise, and one where it does not set, a null will be returned. See detailed explanation on top of the page.
See

adjustZenith
getSeaLevelSunrise()
getUTCSunrise

noaaCalculator.getSeaLevelSunrise() ⇒ Temporal.ZonedDateTime | null

A method that returns the sunrise without elevation adjustment. Non-sunrise and sunset calculations such as dawn and dusk, depend on the amount of visible light, something that is not affected by elevation. This method returns sunrise calculated at sea level. This forms the base for dawn calculations that are calculated as a dip below the horizon before sunrise.

Kind: instance method of NOAACalculator
Returns: Temporal.ZonedDateTime | null - the Date representing the exact sea-level sunrise time. If the calculation can't be computed such as in the Arctic Circle where there is at least one day a year where the sun does not rise, and one where it does not set, a null will be returned. See detailed explanation on top of the page.
See

getSunrise
getUTCSeaLevelSunrise
getSeaLevelSunset()

noaaCalculator.getBeginCivilTwilight() ⇒ Temporal.ZonedDateTime | null

A method that returns the beginning of civil twilight (dawn) using a zenith of 96°.

Kind: instance method of NOAACalculator
Returns: Temporal.ZonedDateTime | null - The Date of the beginning of civil twilight using a zenith of 96°. If the calculation can't be computed, null will be returned. See detailed explanation on top of the page.
See: CIVIL_ZENITH

noaaCalculator.getBeginNauticalTwilight() ⇒ Temporal.ZonedDateTime | null

A method that returns the beginning of nautical twilight using a zenith of 102°.

Kind: instance method of NOAACalculator
Returns: Temporal.ZonedDateTime | null - The Date of the beginning of nautical twilight using a zenith of 102°. If the calculation can't be computed null will be returned. See detailed explanation on top of the page.
See: NAUTICAL_ZENITH

noaaCalculator.getBeginAstronomicalTwilight() ⇒ Temporal.ZonedDateTime | null

A method that returns the beginning of astronomical twilight using a zenith of 108°.

Kind: instance method of NOAACalculator
Returns: Temporal.ZonedDateTime | null - The Date of the beginning of astronomical twilight using a zenith of 108°. If the calculation can't be computed, null will be returned. See detailed explanation on top of the page.
See: ASTRONOMICAL_ZENITH

noaaCalculator.getSunset() ⇒ Temporal.ZonedDateTime | null

The getSunset method Returns a Date representing the elevation adjusted sunset time. The zenith used for the calculation uses geometric zenith of 90° plus getElevationAdjustment. This is adjusted to add approximately 50/60 of a degree to account for 34 archminutes of refraction and 16 archminutes for the sun's radius for a total of 90.83333°. Note: In certain cases the calculates sunset will occur before sunrise. This will typically happen when a timezone other than the local timezone is used (calculating Los Angeles sunset using a GMT timezone for example). In this case the sunset date will be incremented to the following date.

Kind: instance method of NOAACalculator
Returns: Temporal.ZonedDateTime | null - The Date representing the exact sunset time. If the calculation can't be computed such as in the Arctic Circle where there is at least one day a year where the sun does not rise, and one where it does not set, a null will be returned. See detailed explanation on top of the page.
See

adjustZenith
getSeaLevelSunset()
getUTCSunset

noaaCalculator.getSeaLevelSunset() ⇒ Temporal.ZonedDateTime | null

A method that returns the sunset without elevation adjustment. Non-sunrise and sunset calculations such as dawn and dusk, depend on the amount of visible light, something that is not affected by elevation. This method returns sunset calculated at sea level. This forms the base for dusk calculations that are calculated as a dip below the horizon after sunset.

Kind: instance method of NOAACalculator
Returns: Temporal.ZonedDateTime | null - The Date representing the exact sea-level sunset time. If the calculation can't be computed such as in the Arctic Circle where there is at least one day a year where the sun does not rise, and one where it does not set, a null will be returned. See detailed explanation on top of the page.
See

getSunset
getUTCSeaLevelSunset

noaaCalculator.getEndCivilTwilight() ⇒ Temporal.ZonedDateTime | null

A method that returns the end of civil twilight using a zenith of 96°.

Kind: instance method of NOAACalculator
Returns: Temporal.ZonedDateTime | null - The Date of the end of civil twilight using a zenith of 96°. If the calculation can't be computed, null will be returned. See detailed explanation on top of the page.
See: CIVIL_ZENITH

noaaCalculator.getEndNauticalTwilight() ⇒ Temporal.ZonedDateTime | null

A method that returns the end of nautical twilight using a zenith of 102°.

Kind: instance method of NOAACalculator
Returns: Temporal.ZonedDateTime | null - The Date of the end of nautical twilight using a zenith of 102° . If the calculation can't be computed, null will be returned. See detailed explanation on top of the page.
See: NAUTICAL_ZENITH

noaaCalculator.getEndAstronomicalTwilight() ⇒ Temporal.ZonedDateTime | null

A method that returns the end of astronomical twilight using a zenith of 108°.

Kind: instance method of NOAACalculator
Returns: Temporal.ZonedDateTime | null - The Date of the end of astronomical twilight using a zenith of 108°. If the calculation can't be computed, null will be returned. See detailed explanation on top of the page.
See: ASTRONOMICAL_ZENITH

noaaCalculator.getSunriseOffsetByDegrees(offsetZenith) ⇒ Temporal.ZonedDateTime | null

A utility method that returns the time of an offset by degrees below or above the horizon of sunrise. Note that the degree offset is from the vertical, so for a calculation of 14° before sunrise, an offset of 14 + GEOMETRIC_ZENITH = 104 would have to be passed as a parameter.

Kind: instance method of NOAACalculator
Returns: Temporal.ZonedDateTime | null - The Date of the offset after (or before) getSunrise. If the calculation can't be computed such as in the Arctic Circle where there is at least one day a year where the sun does not rise, and one where it does not set, a null will be returned. See detailed explanation on top of the page.

| Param | Type | Description | | --- | --- | --- | | offsetZenith | number | the degrees before getSunrise to use in the calculation. For time after sunrise use negative numbers. Note that the degree offset is from the vertical, so for a calculation of 14° before sunrise, an offset of 14 + GEOMETRIC_ZENITH = 104 would have to be passed as a parameter. |

noaaCalculator.getSunsetOffsetByDegrees(offsetZenith) ⇒ Temporal.ZonedDateTime | null

A utility method that returns the time of an offset by degrees below or above the horizon of sunset. Note that the degree offset is from the vertical, so for a calculation of 14° after sunset, an offset of 14 + GEOMETRIC_ZENITH = 104 would have to be passed as a parameter.

Kind: instance method of NOAACalculator
Returns: Temporal.ZonedDateTime | null - The Dateof the offset after (or before) getSunset. If the calculation can't be computed such as in the Arctic Circle where there is at least one day a year where the sun does not rise, and one where it does not set, a null will be returned. See detailed explanation on top of the page.

| Param | Type | Description | | --- | --- | --- | | offsetZenith | number | the degrees after getSunset to use in the calculation. For time before sunset use negative numbers. Note that the degree offset is from the vertical, so for a calculation of 14° after sunset, an offset of 14 + GEOMETRIC_ZENITH = 104 would have to be passed as a parameter. |

noaaCalculator.getUTCSunrise0(zenith) ⇒ number

A method that returns the sunrise in UTC time without correction for time zone offset from GMT and without using daylight savings time.

Kind: instance method of NOAACalculator
Returns: number - The time in the format: 18.75 for 18:45:00 UTC/GMT. If the calculation can't be computed such as in the Arctic Circle where there is at least one day a year where the sun does not rise, and one where it does not set, NaN will be returned. See detailed explanation on top of the page.

| Param | Type | Description | | --- | --- | --- | | zenith | number | the degrees below the horizon. For time after sunrise use negative numbers. |

noaaCalculator.getUTCSeaLevelSunrise(zenith) ⇒ number

A method that returns the sunrise in UTC time without correction for time zone offset from GMT and without using daylight savings time. Non-sunrise and sunset calculations such as dawn and dusk, depend on the amount of visible light, something that is not affected by elevation. This method returns UTC sunrise calculated at sea level. This forms the base for dawn calculations that are calculated as a dip below the horizon before sunrise.

getUTCSunrise
getUTCSeaLevelSunset

| Param | Type | Description | | --- | --- | --- | | zenith | number | the degrees below the horizon. For time after sunrise use negative numbers. |

noaaCalculator.getUTCSunset0(zenith) ⇒ number

A method that returns the sunset in UTC time without correction for time zone offset from GMT and without using daylight savings time.

| Param | Type | Description | | --- | --- | --- | | zenith | number | the degrees below the horizon. For time after sunset use negative numbers. |

noaaCalculator.getUTCSeaLevelSunset(zenith) ⇒ number

A method that returns the sunset in UTC time without correction for elevation, time zone offset from GMT and without using daylight savings time. Non-sunrise and sunset calculations such as dawn and dusk, depend on the amount of visible light, something that is not affected by elevation. This method returns UTC sunset calculated at sea level. This forms the base for dusk calculations that are calculated as a dip below

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@hebcal/core

Installation

Synopsis

Classes

Members

Constants

Functions

Typedefs

Locale

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

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

Locale.addLocale(locale, data)

Locale.addTranslation(locale, id, translation)

Locale.addTranslations(locale, data)

Locale.useLocale(locale) ⇒ LocaleData

Locale.getLocaleName() ⇒ string

Locale.getLocaleNames() ⇒ Array.<string>

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

Locale.hebrewStripNikkud(str) ⇒ string

HDate

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

hDate.getFullYear() ⇒ number

hDate.isLeapYear() ⇒ boolean

hDate.getMonth() ⇒ number

hDate.getTishreiMonth() ⇒ number

hDate.daysInMonth() ⇒ number

hDate.getDate() ⇒ number

hDate.getDay() ⇒ number

hDate.greg() ⇒ Date

hDate.abs() ⇒ number

hDate.getMonthName() ⇒ string

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

hDate.renderGematriya([suppressNikud]) ⇒ string

hDate.before(day) ⇒ HDate

hDate.onOrBefore(dow) ⇒ HDate

hDate.nearest(dow) ⇒ HDate

hDate.onOrAfter(dow) ⇒ HDate

hDate.after(day) ⇒ HDate

hDate.next() ⇒ HDate

hDate.prev() ⇒ HDate

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

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

hDate.deltaDays(other) ⇒ number

hDate.isSameDate(other) ⇒ boolean

hDate.toString() ⇒ string

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

HDate.isLeapYear(year) ⇒ boolean

HDate.monthsInYear(year) ⇒ number

HDate.daysInMonth(month, year) ⇒ number

HDate.getMonthName(month, year) ⇒ string

HDate.monthNum(month) ⇒ number

HDate.daysInYear(year) ⇒ number

HDate.longCheshvan(year) ⇒ boolean

HDate.shortKislev(year) ⇒ boolean

HDate.monthFromName(monthName) ⇒ number

HDate.dayOnOrBefore(dayOfWeek, absdate) ⇒ number

HDate.isHDate(obj) ⇒ boolean

HDate.fromGematriyaString(str, currentThousands) ⇒ HDate

Event

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

event.getDate() ⇒ HDate

event.getDesc() ⇒ string

event.getFlags() ⇒ number

event.render([locale]) ⇒ string

event.renderBrief([locale]) ⇒ string

event.getEmoji() ⇒ string

event.basename() ⇒ string

event.url() ⇒ string

event.observedInIsrael() ⇒ boolean

event.observedInDiaspora() ⇒ boolean

event.observedIn(il) ⇒ boolean

event.clone() ⇒ Event

event.getCategories() ⇒ Array.<string>

HebrewDateEvent