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

5.4.7
Source
npm

Version published: 4 months ago

Maintainers: 1

Created: 4 years ago

Source

@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: CalOptions = {
  year: 1981,
  isHebrewYear: false,
  candlelighting: true,
  location: Location.lookup('San Francisco'),
  sedrot: true,
  omer: true,
};
const events = HebrewCalendar.calendar(options);

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

Classes

Locale

A locale in Hebcal is used for translations/transliterations of holidays. @hebcal/hdate 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")

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.

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.

Location

Class representing Location

Zmanim

Calculate halachic times (zmanim / זְמַנִּים) for a given day and location. Calculations are available for tzeit / tzais (nightfall), shkiah (sunset) and more.

Zmanim are estimated using an algorithm published by the US National Oceanic and Atmospheric Administration. The NOAA solar calculator is based on equations from Astronomical Algorithms by Jean Meeus.

The sunrise and sunset results are theoretically accurate to within a minute for locations between +/- 72° latitude, and within 10 minutes outside of those latitudes. However, due to variations in atmospheric composition, temperature, pressure and conditions, observed values may vary from calculations. https://gml.noaa.gov/grad/solcalc/calcdetails.html

TimedEvent

An event that has an eventTime and eventTimeStr

CandleLightingEvent

Candle lighting before Shabbat or holiday

HavdalahEvent

Havdalah after 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

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

AsaraBTevetEvent

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

RoshChodeshEvent

Represents Rosh Chodesh, the beginning of a new month

MevarchimChodeshEvent

Represents Mevarchim haChodesh, the announcement of the new month

DailyLearning

Plug-ins for daily learning calendars such as Daf Yomi, Mishna Yomi, Nach Yomi, etc.

Learning schedules are provided by the @hebcal/learning package.

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.

Members

greg: Gregorian date helper functions.

Constants

parshiot : Array.<string>: The 54 parshiyot of the Torah as transilterated strings parshiot[0] == 'Bereshit', parshiot[1] == 'Noach', parshiot[52] == "Ha'azinu".
version: DO NOT EDIT THIS AUTO-GENERATED FILE!

Functions

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.

abs2hebrew(abs) ⇒ SimpleHebrewDate

Converts absolute R.D. days to Hebrew date

isLeapYear(year) ⇒ boolean

Returns true if Hebrew year is a leap year

monthsInYear(year) ⇒ number

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

daysInMonth(month, year) ⇒ number

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

getMonthName(month, year)

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

elapsedDays(year) ⇒ 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. A common Hebrew calendar year can have a length of 353, 354 or 355 days A leap Hebrew calendar year can have a length of 383, 384 or 385 days

longCheshvan(year) ⇒ boolean

true if Cheshvan is long in Hebrew year

shortKislev(year) ⇒ boolean

true if Kislev is short in Hebrew year

monthFromName(monthName) ⇒ number

Converts Hebrew month string name to numeric

gematriya(num) ⇒ 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 [ה]).

gematriyaStrToNum(str) ⇒ number

Converts a string of Hebrew letters to a numerical value.

Only considers the value of Hebrew letters א through ת. Ignores final Hebrew letters such as ך (kaf sofit) or ם (mem sofit) and vowels (nekudot).

omerSefira(omerDay, lang) ⇒

Returns the sefira. For example, on day 8 חֶֽסֶד שֶׁבִּגְבוּרָה Chesed shebiGevurah Lovingkindness within Might

omerTodayIs(omerDay, lang) ⇒

Returns a sentence with that evening's omer count

omerEmoji(omerDay) ⇒

Returns an emoji number symbol with a circle, for example ㊲ from the “Enclosed CJK Letters and Months” block of the Unicode standard

molad()

Calculates the molad for a Hebrew month

getPseudoISO(tzid, date) ⇒ string

Returns a string similar to Date.toISOString() but in the timezone tzid. Contrary to the typical meaning of Z at the end of the string, this is not actually a UTC date.

getTimezoneOffset(tzid, date) ⇒ number

Returns number of minutes tzid is offset from UTC on date date.

pad4(number) ⇒ string

Formats a number with leading zeros so the resulting string is 4 digits long. Similar to string.padStart(4, '0') but will also format negative numbers similar to how the JavaScript date formats negative year numbers (e.g. -37 is formatted as -000037).

pad2(number) ⇒ string

Formats a number with leading zeros so the resulting string is 2 digits long. Similar to string.padStart(2, '0').

Locale

A locale in Hebcal is used for translations/transliterations of holidays. @hebcal/hdate 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)
- .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` \| `Array.<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)

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(dow) ⇒ HDate
  - .onOrBefore(dow) ⇒ HDate
  - .nearest(dow) ⇒ HDate
  - .onOrAfter(dow) ⇒ HDate
  - .after(dow) ⇒ HDate
  - .next() ⇒ HDate
  - .prev() ⇒ HDate
  - .add(amount, [units]) ⇒ HDate
  - .subtract(amount, [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/hdate';

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`		Optional locale name (defaults to active locale).
[showYear]	`boolean`	`true`	Display year (defaults to true).

Example

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

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/hdate';
const hd = new HDate(15, months.CHESHVAN, 5769);
console.log(hd.renderGematriya()); // 'ט״ו חֶשְׁוָן תשס״ט'

hDate.before(dow) ⇒ `HDate`

Returns an HDate representing the a dayNumber 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')).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(dow) ⇒ `HDate`

Returns an HDate representing the a dayNumber 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')).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(amount, [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
amount	`number`
[units]	`string`	`"d"`

hDate.subtract(amount, [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
amount	`number`
[units]	`string`	`"d"`

Example

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

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/hdate';

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 | null
- .basename() ⇒ string
- .url() ⇒ string | undefined
- .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` | `null`

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` | `undefined`

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

Kind: global class
Version: 1.1
Author: © Eliyahu Hershfeld 2004 - 2016

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

Kind: global class
Author: © Eliyahu Hershfeld 2011 - 2019

NOAACalculator
- new NOAACalculator(geoLocation, date)
- instance
  - .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
  - .CIVIL_ZENITH
  - .NAUTICAL_ZENITH
  - .ASTRONOMICAL_ZENITH
  - .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.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 the horizon after sunset.

getUTCSunset
getUTCSeaLevelSunrise

Param	Type	Description
zenith	`number`	the degrees below the horizon. For time before sunset use negative numbers.

noaaCalculator.getElevationAdjustment(elevation) ⇒ `number`

Method to return the adjustment to the zenith required to account for the elevation. Since a person at a higher elevation can see farther below the horizon, the calculation for sunrise / sunset is calculated below the horizon used at sea level. This is only used for sunrise and sunset and not times before or after it such as nautical twilight since those calculations are based on the level of available light at the given dip below the horizon, something that is not affected by elevation, the adjustment should only made if the zenith == 90° adjusted for refraction and solar radius. The algorithm used is

elevationAdjustment = Math.toDegrees(Math.acos(earthRadiusInMeters / (earthRadiusInMeters + elevationMeters)));

The source of this algorithm is Calendrical Calculations by Edward M. Reingold and Nachum Dershowitz. An alternate algorithm that produces an almost identical (but not accurate) result found in Ma'aglay Tzedek by Moishe Kosower and other sources is:

elevationAdjustment = 0.0347 * Math.sqrt(elevationMeters);

Kind: instance method of NOAACalculator
Returns: number - the adjusted zenith

Param	Type	Description
elevation	`number`	elevation in Meters.

noaaCalculator.adjustZenith(zenith, elevation) ⇒ `number`

Adjusts the zenith of astronomical sunrise and sunset to account for solar refraction, solar radius and elevation. The value for Sun's zenith and true rise/set Zenith (used in this class and subclasses) is the angle that the center of the Sun makes to a line perpendicular to the Earth's surface. If the Sun were a point and the Earth were without an atmosphere, true sunset and sunrise would correspond to a 90° zenith. Because the Sun is not a point, and because the atmosphere refracts light, this 90° zenith does not, in fact, correspond to true sunset or sunrise, instead the centre of the Sun's disk must lie just below the horizon for the upper edge to be obscured. This means that a zenith of just above 90° must be used. The Sun subtends an angle of 16 minutes of arc, and atmospheric refraction accounts for 34 minutes or so, giving a total of 50 arcminutes. The total value for ZENITH is 90+(5/6) or 90.8333333° for true sunrise/sunset. Since a person at an elevation can see blow the horizon of a person at sea level, this will also adjust the zenith to account for elevation if available. Note that this will only adjust the value if the zenith is exactly 90 degrees. For values below and above this no correction is done. As an example, astronomical twilight is when the sun is 18° below the horizon or 108° below the zenith. This is traditionally calculated with none of the above mentioned adjustments. The same goes for various tzais and alos times such as the 16.1° dip used in ComplexZmanimCalendar#getAlos16Point1Degrees.

Kind: instance method of NOAACalculator
Returns: number - The zenith adjusted to include the sun's radius, refracton and elevation adjustment. This will only be adjusted for sunrise and sunset (if the zenith == 90°)
See: getElevationAdjustment

Param	Type	Description
zenith	`number`	the azimuth below the vertical zenith of 90°. For sunset typically the zenith used for the calculation uses geometric zenith of 90° and adjusts this slightly to account for solar refraction and the sun's radius. Another example would be getEndNauticalTwilight that passes NAUTICAL_ZENITH to this method.
elevation	`number`	elevation in Meters.

noaaCalculator.getUTCSunrise(date, geoLocation, zenith, adjustForElevation) ⇒

A method that calculates UTC sunrise as well as any time based on an angle above or below sunrise.

Kind: instance method of NOAACalculator
Returns: The UTC time of sunrise in 24 hour format. 5:45:00 AM will return 5.75.0. If an error was encountered in the calculation (expected behavior for some locations such as near the poles, NaN will be returned.

Param	Description
date	Used to calculate day of year.
geoLocation	The location information used for astronomical calculating sun times.
zenith	the azimuth below the vertical zenith of 90 degrees. for sunrise typically the zenith used for the calculation uses geometric zenith of 90° and adjusts this slightly to account for solar refraction and the sun's radius. Another example would be getBeginNauticalTwilight that passes NAUTICAL_ZENITH to this method.
adjustForElevation	Should the time be adjusted for elevation

noaaCalculator.getUTCSunset(date, geoLocation, zenith, adjustForElevation) ⇒

A method that calculates UTC sunset as well as any time based on an angle above or below sunset.

Kind: instance method of NOAACalculator
Returns: The UTC time of sunset in 24 hour format. 5:45:00 AM will return 5.75.0. If an error was encountered in the calculation (expected behavior for some locations such as near the poles, NaN will be returned.

Param	Description
date	Used to calculate day of year.
geoLocation	The location information used for astronomical calculating sun times.
zenith	the azimuth below the vertical zenith of 90°. For sunset typically the zenith used for the calculation uses geometric zenith of 90° and adjusts this slightly to account for solar refraction and the sun's radius. Another example would be getEndNauticalTwilight that passes NAUTICAL_ZENITH to this method.
adjustForElevation	Should the time be adjusted for elevation

noaaCalculator.getTemporalHour(startOfDay, endOfDay) ⇒ `number`

A utility method that will allow the calculation of a temporal (solar) hour based on the sunrise and sunset passed as parameters to this method. An example of the use of this method would be the calculation of a non-elevation adjusted temporal hour by passing in sea level sunrise and sea level sunset as parameters.

Kind: instance method of NOAACalculator
Returns: number - the long millisecond length of the temporal hour. If the calculation can't be computed a NaN will be returned. See detailed explanation on top of the page.
See: getTemporalHour()

Param	Type	Description
startOfDay	`Temporal.ZonedDateTime` \| `null`	The start of the day.
endOfDay	`Temporal.ZonedDateTime` \| `null`	The end of the day.

noaaCalculator.getSunTransit(startOfDay, endOfDay) ⇒ `Temporal.ZonedDateTime` | `null`

A method that returns sundial or solar noon. It occurs when the Sun is transiting the celestial meridian. In this class it is calculated as halfway between the sunrise and sunset passed to this method. This time can be slightly off the real transit time due to changes in declination (the lengthening or shortening day).

Kind: instance method of NOAACalculator
Returns: Temporal.ZonedDateTime | null - The Date representing Sun's transit. 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, null will be returned. See detailed explanation on top of the page.

Param	Type	Description
startOfDay	`Temporal.ZonedDateTime` \| `null`	the start of day for calculating the sun's transit. This can be sea level sunrise, visual sunrise (or any arbitrary start of day) passed to this method.
endOfDay	`Temporal.ZonedDateTime` \| `null`	the end of day for calculating the sun's transit. This can be sea level sunset, visual sunset (or any arbitrary end of day) passed to this method.

noaaCalculator.getDateFromTime(time, isSunrise) ⇒ `Temporal.ZonedDateTime` | `null`

A method that returns a Date from the time passed in as a parameter.

Kind: instance method of NOAACalculator
Returns: Temporal.ZonedDateTime | null - The Date.
Access: protected

Param	Type	Description
time	`number`	The time to be set as the time for the `Date`. The time expected is in the format: 18.75 for 6:45:00 PM.
isSunrise	`boolean`	true if the time is sunrise, and false if it is sunset

NOAACalculator.CIVIL_ZENITH

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

Kind: static property of NOAACalculator

NOAACalculator.NAUTICAL_ZENITH

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

Kind: static property of NOAACalculator

NOAACalculator.ASTRONOMICAL_ZENITH

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

Kind: static property of NOAACalculator

NOAACalculator.getTimeOffset(time, offset) ⇒ `Temporal.ZonedDateTime` | `null`

A utility method that returns a date offset by the offset time passed in. Please note that the level of light during twilight is not affected by elevation, so if this is being used to calculate an offset before sunrise or after sunset with the intent of getting a rough "level of light" calculation, the sunrise or sunset time passed to this method should be sea level sunrise and sunset.

Kind: static method of NOAACalculator
Returns: Temporal.ZonedDateTime | null - the Date with the offset in milliseconds added to it

Param	Type	Description
time	`Temporal.ZonedDateTime` \| `null`	the start time
offset	`number`	the offset in milliseconds to add to the time.

NOAACalculator.getSolarElevation(date, lat, lon) ⇒ `number`

Return the Solar Elevation for the horizontal coordinate system at the given location at the given time. Can be negative if the sun is below the horizon. Not corrected for altitude.

Kind: static method of NOAACalculator
Returns: number - solar elevation in degrees - horizon is 0 degrees, civil twilight is -6 degrees

Param	Type	Description
date	`Temporal.ZonedDateTime`	time of calculation
lat	`number`	latitude of location for calculation
lon	`number`	longitude of location for calculation

NOAACalculator.getSolarAzimuth(date, latitude, lon) ⇒ `number`

Return the Solar Azimuth for the horizontal coordinate system at the given location at the given time. Not corrected for altitude. True south is 0 degrees.

Kind: static method of NOAACalculator

Param	Type	Description
date	`Temporal.ZonedDateTime`	time of calculation
latitude	`number`	latitude of location for calculation
lon	`number`	longitude of location for calculation

Location

Class representing Location

Kind: global class

Location
- new Location(latitude, longitude, il, tzid, [cityName], [countryCode], [geoid], [elevation])
- instance
  - .getIsrael() ⇒ boolean
  - .getName() ⇒ string | null
  - .getShortName() ⇒ string | null
  - .getCountryCode() ⇒ string | undefined
  - .getTzid() ⇒ string
  - .getTimeFormatter() ⇒ Intl.DateTimeFormat
  - .getGeoId() ⇒ string | number | undefined
  - .toString() ⇒ string
- static
  - .lookup(name) ⇒ Location | undefined
  - .legacyTzToTzid(tz, dst) ⇒ string | undefined
  - .getUsaTzid(state, tz, dst) ⇒ string
  - .addLocation(cityName, location) ⇒ boolean

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

Initialize a Location instance

Param	Type	Description
latitude	`number`	Latitude as a decimal, valid range -90 thru +90 (e.g. 41.85003)
longitude	`number`	Longitude as a decimal, valid range -180 thru +180 (e.g. -87.65005)
il	`boolean`	in Israel (true) or Diaspora (false)
tzid	`string`	Olson timezone ID, e.g. "America/Chicago"
[cityName]	`string`	optional descriptive city name
[countryCode]	`string`	ISO 3166 alpha-2 country code (e.g. "FR")
[geoid]	`string` \| `number`	optional string or numeric geographic ID
[elevation]	`number`	in meters (default `0`)

location.getIsrael() ⇒ `boolean`

Kind: instance method of Location

location.getName() ⇒ `string` | `null`

Kind: instance method of Location

location.getShortName() ⇒ `string` | `null`

Returns the location name, up to the first comma

Kind: instance method of Location

location.getCountryCode() ⇒ `string` | `undefined`

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` | `number` | `undefined`

Kind: instance method of Location

location.toString() ⇒ `string`

Kind: instance method of Location

Location.lookup(name) ⇒ `Location` | `undefined`

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

Param	Type
name	`string`

Location.legacyTzToTzid(tz, dst) ⇒ `string` | `undefined`

Converts legacy Hebcal timezone to a standard Olson tzid.

Kind: static method of Location

Param	Type	Description
tz	`number`	integer, GMT offset in hours
dst	`string`	'none', 'eu', 'usa', or 'israel'

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

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

Kind: static method of Location

Param	Type	Description
state	`string`	two-letter all-caps US state abbreviation like 'CA'
tz	`number`	positive number, 5=America/New_York, 8=America/Los_Angeles
dst	`string`	single char 'Y' or 'N'

Example

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

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

Param	Type
cityName	`string`
location	`Location`

Zmanim

Calculate halachic times (zmanim / זְמַנִּים) for a given day and location. Calculations are available for tzeit / tzais (nightfall), shkiah (sunset) and more.

Kind: global class

Zmanim
- new Zmanim(gloc, date, useElevation)
- instance
  - .getUseElevation() ⇒ boolean
  - .setUseElevation(useElevation)
  - .timeAtAngle(angle, rising) ⇒ Date
  - .sunrise() ⇒ Date
  - .seaLevelSunrise() ⇒ Date
  - .sunset() ⇒ Date
  - .seaLevelSunset() ⇒ Date
  - .dawn() ⇒ Date
  - .dusk() ⇒ Date
  - .gregEve() ⇒ Date
  - .chatzot() ⇒ Date
  - .chatzotNight() ⇒ Date
  - .alotHaShachar() ⇒ Date
  - .misheyakir() ⇒ Date
  - .misheyakirMachmir() ⇒ Date
  - .sofZmanShma() ⇒ Date
  - .sofZmanTfilla() ⇒ Date
  - .sofZmanShmaMGA() ⇒ Date
  - .sofZmanShmaMGA16Point1() ⇒ Date
  - .sofZmanShmaMGA19Point8() ⇒ Date
  - .sofZmanTfillaMGA() ⇒ Date
  - .sofZmanTfillaMGA16Point1() ⇒ Date
  - .sofZmanTfillaMGA19Point8() ⇒ Date
  - .minchaGedola() ⇒ Date
  - .minchaGedolaMGA() ⇒ Date
  - .minchaKetana() ⇒ Date
  - .minchaKetanaMGA() ⇒ Date
  - .plagHaMincha() ⇒ Date
  - .tzeit([angle]) ⇒ Date
  - .neitzHaChama() ⇒ Date
  - .shkiah() ⇒ Date
  - .beinHaShmashos() ⇒ Date
  - .sunriseOffset(offset, roundMinute, forceSeaLevel) ⇒ Date
  - .sunsetOffset(offset, roundMinute, forceSeaLevel) ⇒ Date
- static
  - .formatTime(dt, timeFormat) ⇒ string
  - .roundTime(dt) ⇒ Date
  - .timeZoneOffset(tzid, date) ⇒ string
  - .formatISOWithTimeZone(tzid, date) ⇒ string

new Zmanim(gloc, date, useElevation)

Initialize a Zmanim instance.

Param	Type	Description
gloc	`GeoLocation`	GeoLocation including latitude, longitude, and timezone
date	`Date` \| `HDate`	Regular or Hebrew Date. If `date` is a regular `Date`, hours, minutes, seconds and milliseconds are ignored.
useElevation	`boolean`	use elevation for calculations (default `false`). If `true`, use elevation to affect the calculation of all sunrise/sunset based zmanim. Note: there are some zmanim such as degree-based zmanim that are driven by the amount of light in the sky and are not impacted by elevation. These zmanim intentionally do not support elevation adjustment.

Example

const {GeoLocation, Zmanim} = require('@hebcal/core');
const latitude = 41.822232;
const longitude = -71.448292;
const tzid = 'America/New_York';
const friday = new Date(2023, 8, 8);
const gloc = new GeoLocation(null, latitude, longitude, 0, tzid);
const zmanim = new Zmanim(gloc, friday, false);
const candleLighting = zmanim.sunsetOffset(-18, true);
const timeStr = Zmanim.formatISOWithTimeZone(tzid, candleLighting);