From 6af73241773c80abc731333898e253f65ec8652c Mon Sep 17 00:00:00 2001 From: "Michael J. Radwin" Date: Tue, 4 Jun 2024 10:38:59 -0700 Subject: [PATCH] Add minchaKetanaMGA and minchaGedolaMGA to Zmanim #447 --- README.md | 562 ++++++++++++++++++++------------------------ package-lock.json | 28 +-- package.json | 2 +- src/index.ts | 1 + src/tachanun.ts | 3 + src/zmanim.ts | 83 +++++-- test/zmanim.spec.js | 8 + 7 files changed, 355 insertions(+), 332 deletions(-) diff --git a/README.md b/README.md index 74c2f508..f624c528 100644 --- a/README.md +++ b/README.md @@ -61,9 +61,6 @@ holidays. @hebcal/hdate supports four locales by default

HDate

Represents a Hebrew date

-
Sedra
-

Represents Parashah HaShavua for an entire Hebrew year

-
Event

Represents an Event with a title, date, and flags

@@ -104,12 +101,12 @@ conditions, observed values may vary from calculations.
TimedEvent

An event that has an eventTime and eventTimeStr

-
HavdalahEvent
-

Havdalah after Shabbat or holiday

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

@@ -119,19 +116,22 @@ conditions, observed values may vary from calculations.
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

-
RoshChodeshEvent
-

Represents Rosh Chodesh, the beginning of a new month

-
AsaraBTevetEvent

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

+
RoshChodeshEvent
+

Represents Rosh Chodesh, the beginning of a new month

+
MevarchimChodeshEvent

Represents Mevarchim haChodesh, the announcement of the new month

@@ -162,6 +162,9 @@ Event names can be rendered in several languges using the locale op

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 @@ -230,6 +233,9 @@ and vowels (nekudot).

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 @@ -250,16 +256,6 @@ Similar to string.padStart(2, '0').

-## Typedefs - -
-
CalOptions : Object
-

Options to configure which events are returned

-
-
TachanunResult : Object
-
-
- ## Locale @@ -332,7 +328,7 @@ Adds a translation to `locale`, replacing any previous translation. | --- | --- | --- | | locale | string | Locale name (i.e: `'he'`, `'fr'`). | | id | string | Message ID to translate | -| translation | string | Translation text | +| translation | string \| Array.<string> | Translation text | @@ -929,110 +925,6 @@ HDate.fromGematriyaString('כ״ז בְּתַמּוּז תשפ״ג') // 27 Tamuz HDate.fromGematriyaString('כ׳ סיון תש״ד') // 20 Sivan 5704 HDate.fromGematriyaString('ה׳ אִיָיר תש״ח') // 5 Iyyar 5708 ``` - - -## Sedra -Represents Parashah HaShavua for an entire Hebrew year - -**Kind**: global class - -* [Sedra](#Sedra) - * [new Sedra(hyear, il)](#new_Sedra_new) - * [.get(hd)](#Sedra+get) ⇒ Array.<string> - * [.getString(hd, [locale])](#Sedra+getString) ⇒ string - * [.isParsha(hd)](#Sedra+isParsha) ⇒ boolean - * [.find(parsha)](#Sedra+find) ⇒ [HDate](#HDate) \| null - * [.getSedraArray()](#Sedra+getSedraArray) ⇒ Array.<NumberOrString> - * [.getFirstSaturday()](#Sedra+getFirstSaturday) ⇒ number - * [.getYear()](#Sedra+getYear) ⇒ number - * [.lookup(hd)](#Sedra+lookup) ⇒ SedraResult - - - -### new Sedra(hyear, il) -Caculates the Parashah HaShavua for an entire Hebrew year - - -| Param | Type | Description | -| --- | --- | --- | -| hyear | number | Hebrew year (e.g. 5749) | -| il | boolean | Use Israel sedra schedule (false for Diaspora) | - - - -### sedra.get(hd) ⇒ Array.<string> -Returns the parsha (or parshiyot) read on Hebrew date - -**Kind**: instance method of [Sedra](#Sedra) - -| Param | Type | Description | -| --- | --- | --- | -| hd | [HDate](#HDate) \| number | Hebrew date or R.D. days | - - - -### sedra.getString(hd, [locale]) ⇒ string -Looks up parsha for the date, then returns a translated or transliterated string - -**Kind**: instance method of [Sedra](#Sedra) - -| Param | Type | Description | -| --- | --- | --- | -| hd | [HDate](#HDate) \| number | Hebrew date or R.D. days | -| [locale] | string | Optional locale name (i.e: `'he'`, `'fr'`). Defaults to active locale | - - - -### sedra.isParsha(hd) ⇒ boolean -Checks to see if this day would be a regular parasha HaShavua -Torah reading or special holiday reading - -**Kind**: instance method of [Sedra](#Sedra) - -| Param | Type | Description | -| --- | --- | --- | -| hd | [HDate](#HDate) \| number | Hebrew date or R.D. days | - - - -### sedra.find(parsha) ⇒ [HDate](#HDate) \| null -Returns the date that a parsha occurs -or `null` if the parsha doesn't occur this year - -**Kind**: instance method of [Sedra](#Sedra) - -| Param | Type | -| --- | --- | -| parsha | number \| string \| Array.<string> | - - - -### sedra.getSedraArray() ⇒ Array.<NumberOrString> -Returns the underlying annual sedra schedule. -Used by `@hebcal/triennial` - -**Kind**: instance method of [Sedra](#Sedra) - - -### sedra.getFirstSaturday() ⇒ number -R.D. date of the first Saturday on or after Rosh Hashana - -**Kind**: instance method of [Sedra](#Sedra) - - -### sedra.getYear() ⇒ number -**Kind**: instance method of [Sedra](#Sedra) - - -### sedra.lookup(hd) ⇒ SedraResult -Returns an object describing the parsha on the first Saturday on or after `hd` - -**Kind**: instance method of [Sedra](#Sedra) - -| Param | Type | Description | -| --- | --- | --- | -| hd | [HDate](#HDate) \| number | Hebrew date or R.D. days | - ## Event @@ -1047,9 +939,9 @@ Represents an Event with a title, date, and flags * [.getFlags()](#Event+getFlags) ⇒ number * [.render([locale])](#Event+render) ⇒ string * [.renderBrief([locale])](#Event+renderBrief) ⇒ string - * [.getEmoji()](#Event+getEmoji) ⇒ string + * [.getEmoji()](#Event+getEmoji) ⇒ string \| null * [.basename()](#Event+basename) ⇒ string - * [.url()](#Event+url) ⇒ string + * [.url()](#Event+url) ⇒ string \| undefined * [.observedInIsrael()](#Event+observedInIsrael) ⇒ boolean * [.observedInDiaspora()](#Event+observedInDiaspora) ⇒ boolean * [.observedIn(il)](#Event+observedIn) ⇒ boolean @@ -1120,7 +1012,7 @@ a shorter text (e.g. without a time or added description). -### event.getEmoji() ⇒ string +### event.getEmoji() ⇒ string \| null Optional holiday-specific Emoji or `null`. **Kind**: instance method of [Event](#Event) @@ -1135,7 +1027,7 @@ For many holidays the basename and the event description are the same. **Kind**: instance method of [Event](#Event) -### event.url() ⇒ string +### 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. @@ -1873,25 +1765,25 @@ Class representing Location **Kind**: global class * [Location](#Location) - * [new Location(latitude, longitude, il, tzid, cityName, countryCode, [geoid], [elevation])](#new_Location_new) + * [new Location(latitude, longitude, il, tzid, [cityName], [countryCode], [geoid], [elevation])](#new_Location_new) * _instance_ * [.getIsrael()](#Location+getIsrael) ⇒ boolean - * [.getName()](#Location+getName) ⇒ string - * [.getShortName()](#Location+getShortName) ⇒ string - * [.getCountryCode()](#Location+getCountryCode) ⇒ string + * [.getName()](#Location+getName) ⇒ string \| null + * [.getShortName()](#Location+getShortName) ⇒ string \| null + * [.getCountryCode()](#Location+getCountryCode) ⇒ string \| undefined * [.getTzid()](#Location+getTzid) ⇒ string * [.getTimeFormatter()](#Location+getTimeFormatter) ⇒ Intl.DateTimeFormat - * [.getGeoId()](#Location+getGeoId) ⇒ string + * [.getGeoId()](#Location+getGeoId) ⇒ string \| number \| undefined * [.toString()](#Location+toString) ⇒ string * _static_ - * [.lookup(name)](#Location.lookup) ⇒ [Location](#Location) - * [.legacyTzToTzid(tz, dst)](#Location.legacyTzToTzid) ⇒ string + * [.lookup(name)](#Location.lookup) ⇒ [Location](#Location) \| undefined + * [.legacyTzToTzid(tz, dst)](#Location.legacyTzToTzid) ⇒ string \| undefined * [.getUsaTzid(state, tz, dst)](#Location.getUsaTzid) ⇒ string * [.addLocation(cityName, location)](#Location.addLocation) ⇒ boolean -### new Location(latitude, longitude, il, tzid, cityName, countryCode, [geoid], [elevation]) +### new Location(latitude, longitude, il, tzid, [cityName], [countryCode], [geoid], [elevation]) Initialize a Location instance @@ -1901,9 +1793,9 @@ Initialize a Location instance | longitude | number | Longitude as a decimal, valid range -180 thru +180 (e.g. -87.65005) | | il | boolean | in Israel (true) or Diaspora (false) | | tzid | string | Olson timezone ID, e.g. "America/Chicago" | -| cityName | string | optional descriptive city name | -| countryCode | string | ISO 3166 alpha-2 country code (e.g. "FR") | -| [geoid] | string | optional string or numeric geographic ID | +| [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`) | @@ -1912,17 +1804,17 @@ Initialize a Location instance **Kind**: instance method of [Location](#Location) -### location.getName() ⇒ string +### location.getName() ⇒ string \| null **Kind**: instance method of [Location](#Location) -### location.getShortName() ⇒ string +### location.getShortName() ⇒ string \| null Returns the location name, up to the first comma **Kind**: instance method of [Location](#Location) -### location.getCountryCode() ⇒ string +### location.getCountryCode() ⇒ string \| undefined **Kind**: instance method of [Location](#Location) @@ -1936,7 +1828,7 @@ Gets a 24-hour time formatter (e.g. 07:41 or 20:03) for this location **Kind**: instance method of [Location](#Location) -### location.getGeoId() ⇒ string +### location.getGeoId() ⇒ string \| number \| undefined **Kind**: instance method of [Location](#Location) @@ -1944,7 +1836,7 @@ Gets a 24-hour time formatter (e.g. 07:41 or 20:03) for this location **Kind**: instance method of [Location](#Location) -### Location.lookup(name) ⇒ [Location](#Location) +### Location.lookup(name) ⇒ [Location](#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', @@ -1969,7 +1861,7 @@ The following city names are supported: -### Location.legacyTzToTzid(tz, dst) ⇒ string +### Location.legacyTzToTzid(tz, dst) ⇒ string \| undefined Converts legacy Hebcal timezone to a standard Olson tzid. **Kind**: static method of [Location](#Location) @@ -2056,7 +1948,9 @@ https://gml.noaa.gov/grad/solcalc/calcdetails.html * [.sofZmanTfillaMGA16Point1()](#Zmanim+sofZmanTfillaMGA16Point1) ⇒ Date * [.sofZmanTfillaMGA19Point8()](#Zmanim+sofZmanTfillaMGA19Point8) ⇒ Date * [.minchaGedola()](#Zmanim+minchaGedola) ⇒ Date + * [.minchaGedolaMGA()](#Zmanim+minchaGedolaMGA) ⇒ Date * [.minchaKetana()](#Zmanim+minchaKetana) ⇒ Date + * [.minchaKetanaMGA()](#Zmanim+minchaKetanaMGA) ⇒ Date * [.plagHaMincha()](#Zmanim+plagHaMincha) ⇒ Date * [.tzeit([angle])](#Zmanim+tzeit) ⇒ Date * [.neitzHaChama()](#Zmanim+neitzHaChama) ⇒ Date @@ -2225,6 +2119,12 @@ If elevation is enabled, this function will include elevation in the calculation ### zmanim.sofZmanTfilla() ⇒ Date Latest Shacharit (Gra); Sunrise plus 4 halachic hours, according to the Gra. + +This method returns the latest *zman tfila* (time to recite shema in the morning) +that is 4 *shaos zmaniyos* (solar hours) after sunrise or sea level sunrise +(depending on the `useElevation` setting), according +to the [GRA](https://en.wikipedia.org/wiki/Vilna_Gaon). + If elevation is enabled, this function will include elevation in the calculation. **Kind**: instance method of [Zmanim](#Zmanim) @@ -2286,9 +2186,29 @@ https://kosherjava.com/2022/01/12/equinox-vs-equilux-zmanim-calculations/ ### zmanim.minchaGedola() ⇒ Date -Earliest Mincha – Mincha Gedola; Sunrise plus 6.5 halachic hours. +Earliest Mincha – Mincha Gedola (GRA); Sunrise plus 6.5 halachic hours. If elevation is enabled, this function will include elevation in the calculation. +This method returns the latest mincha gedola, the earliest time one can pray mincha +that is 6.5 shaos zmaniyos (solar hours) after sunrise or sea level sunrise +(depending on the `useElevation` setting), according +to the [GRA](https://en.wikipedia.org/wiki/Vilna_Gaon). + +The Ramba"m is of the opinion that it is better to delay *mincha* until +*mincha ketana* while the Ra"sh, Tur, GRA and others are of the +opinion that *mincha* can be prayed *lechatchila* starting at *mincha gedola*. + +**Kind**: instance method of [Zmanim](#Zmanim) + + +### zmanim.minchaGedolaMGA() ⇒ Date +Earliest Mincha – Mincha Gedola (MGA); Sunrise plus 6.5 halachic hours. +If elevation is enabled, this function will include elevation in the calculation. + +This method returns the time of *mincha gedola* according to the Magen Avraham +with the day starting 72 minutes before sunrise and ending 72 minutes after sunset. +This is the earliest time to pray *mincha*. + **Kind**: instance method of [Zmanim](#Zmanim) @@ -2296,6 +2216,23 @@ If elevation is enabled, this function will include elevation in the calculation Preferable earliest time to recite Minchah – Mincha Ketana; Sunrise plus 9.5 halachic hours. If elevation is enabled, this function will include elevation in the calculation. +This method returns *mincha ketana*, the preferred earliest time to pray *mincha* in the +opinion of the [Rambam](https://en.wikipedia.org/wiki/Maimonides) and others, +that is 9.5 *shaos zmaniyos* (solar hours) after sunrise or sea level sunrise +(depending on the `useElevation` setting), according +to the [GRA](https://en.wikipedia.org/wiki/Vilna_Gaon). + +**Kind**: instance method of [Zmanim](#Zmanim) + + +### zmanim.minchaKetanaMGA() ⇒ Date +This method returns the time of *mincha ketana* according to the Magen Avraham +with the day starting 72 minutes before sunrise and ending 72 minutes after sunset. +This is the preferred earliest time to pray *mincha* according to the opinion of +the [Rambam](https://en.wikipedia.org/wiki/Maimonides) and others. + +If elevation is enabled, this function will include elevation in the calculation. + **Kind**: instance method of [Zmanim](#Zmanim) @@ -2421,24 +2358,18 @@ An event that has an `eventTime` and `eventTimeStr` **Kind**: global class * [TimedEvent](#TimedEvent) - * [new TimedEvent(date, desc, mask, eventTime, location, linkedEvent, options)](#new_TimedEvent_new) + * [new TimedEvent(desc)](#new_TimedEvent_new) * [.render([locale])](#TimedEvent+render) ⇒ string * [.renderBrief([locale])](#TimedEvent+renderBrief) ⇒ string * [.getCategories()](#TimedEvent+getCategories) ⇒ Array.<string> -### new TimedEvent(date, desc, mask, eventTime, location, linkedEvent, options) +### new TimedEvent(desc) | Param | Type | Description | | --- | --- | --- | -| date | [HDate](#HDate) | | | desc | string | Description (not translated) | -| mask | number | | -| eventTime | Date | | -| location | [Location](#Location) | | -| linkedEvent | [Event](#Event) | | -| options | [CalOptions](#CalOptions) | | @@ -2464,6 +2395,16 @@ Returns translation of "Candle lighting" without the time. ### timedEvent.getCategories() ⇒ Array.<string> **Kind**: instance method of [TimedEvent](#TimedEvent) + + +## CandleLightingEvent +Candle lighting before Shabbat or holiday + +**Kind**: global class + + +### candleLightingEvent.getEmoji() ⇒ string +**Kind**: instance method of [CandleLightingEvent](#CandleLightingEvent) ## HavdalahEvent @@ -2472,25 +2413,10 @@ Havdalah after Shabbat or holiday **Kind**: global class * [HavdalahEvent](#HavdalahEvent) - * [new HavdalahEvent(date, mask, eventTime, location, havdalahMins, linkedEvent, options)](#new_HavdalahEvent_new) * [.render([locale])](#HavdalahEvent+render) ⇒ string * [.renderBrief([locale])](#HavdalahEvent+renderBrief) ⇒ string * [.getEmoji()](#HavdalahEvent+getEmoji) ⇒ string - - -### new HavdalahEvent(date, mask, eventTime, location, havdalahMins, linkedEvent, options) - -| Param | Type | -| --- | --- | -| date | [HDate](#HDate) | -| mask | number | -| eventTime | Date | -| location | [Location](#Location) | -| havdalahMins | number | -| linkedEvent | [Event](#Event) | -| options | [CalOptions](#CalOptions) | - ### havdalahEvent.render([locale]) ⇒ string @@ -2515,34 +2441,6 @@ Returns translation of "Havdalah" without the time. ### havdalahEvent.getEmoji() ⇒ string **Kind**: instance method of [HavdalahEvent](#HavdalahEvent) - - -## CandleLightingEvent -Candle lighting before Shabbat or holiday - -**Kind**: global class - -* [CandleLightingEvent](#CandleLightingEvent) - * [new CandleLightingEvent(date, mask, eventTime, location, linkedEvent, options)](#new_CandleLightingEvent_new) - * [.getEmoji()](#CandleLightingEvent+getEmoji) ⇒ string - - - -### new CandleLightingEvent(date, mask, eventTime, location, linkedEvent, options) - -| Param | Type | -| --- | --- | -| date | [HDate](#HDate) | -| mask | number | -| eventTime | Date | -| location | [Location](#Location) | -| linkedEvent | [Event](#Event) | -| options | [CalOptions](#CalOptions) | - - - -### candleLightingEvent.getEmoji() ⇒ string -**Kind**: instance method of [CandleLightingEvent](#CandleLightingEvent) ## Molad @@ -2612,7 +2510,7 @@ Calculates the molad for a Hebrew month | Param | Type | Description | | --- | --- | --- | | [locale] | string | Optional locale name (defaults to active locale) | -| options | [CalOptions](#CalOptions) | | +| options | CalOptions | | @@ -2634,7 +2532,7 @@ Represents a Molad announcement on Shabbat Mevarchim | date | [HDate](#HDate) | Hebrew date event occurs | | hyear | number | molad year | | hmonth | number | molad month | -| options | [CalOptions](#CalOptions) | | +| options | CalOptions | | @@ -2730,6 +2628,110 @@ Returns translation of "Omer day 22" without ordinal numbers. ### omerEvent.url() ⇒ string **Kind**: instance method of [OmerEvent](#OmerEvent) + + +## Sedra +Represents Parashah HaShavua for an entire Hebrew year + +**Kind**: global class + +* [Sedra](#Sedra) + * [new Sedra(hyear, il)](#new_Sedra_new) + * [.get(hd)](#Sedra+get) ⇒ Array.<string> + * [.getString(hd, [locale])](#Sedra+getString) ⇒ string + * [.isParsha(hd)](#Sedra+isParsha) ⇒ boolean + * [.find(parsha)](#Sedra+find) ⇒ [HDate](#HDate) \| null + * [.getSedraArray()](#Sedra+getSedraArray) ⇒ Array.<NumberOrString> + * [.getFirstSaturday()](#Sedra+getFirstSaturday) ⇒ number + * [.getYear()](#Sedra+getYear) ⇒ number + * [.lookup(hd)](#Sedra+lookup) ⇒ SedraResult + + + +### new Sedra(hyear, il) +Caculates the Parashah HaShavua for an entire Hebrew year + + +| Param | Type | Description | +| --- | --- | --- | +| hyear | number | Hebrew year (e.g. 5749) | +| il | boolean | Use Israel sedra schedule (false for Diaspora) | + + + +### sedra.get(hd) ⇒ Array.<string> +Returns the parsha (or parshiyot) read on Hebrew date + +**Kind**: instance method of [Sedra](#Sedra) + +| Param | Type | Description | +| --- | --- | --- | +| hd | [HDate](#HDate) \| number | Hebrew date or R.D. days | + + + +### sedra.getString(hd, [locale]) ⇒ string +Looks up parsha for the date, then returns a translated or transliterated string + +**Kind**: instance method of [Sedra](#Sedra) + +| Param | Type | Description | +| --- | --- | --- | +| hd | [HDate](#HDate) \| number | Hebrew date or R.D. days | +| [locale] | string | Optional locale name (i.e: `'he'`, `'fr'`). Defaults to active locale | + + + +### sedra.isParsha(hd) ⇒ boolean +Checks to see if this day would be a regular parasha HaShavua +Torah reading or special holiday reading + +**Kind**: instance method of [Sedra](#Sedra) + +| Param | Type | Description | +| --- | --- | --- | +| hd | [HDate](#HDate) \| number | Hebrew date or R.D. days | + + + +### sedra.find(parsha) ⇒ [HDate](#HDate) \| null +Returns the date that a parsha occurs +or `null` if the parsha doesn't occur this year + +**Kind**: instance method of [Sedra](#Sedra) + +| Param | Type | +| --- | --- | +| parsha | number \| string \| Array.<string> | + + + +### sedra.getSedraArray() ⇒ Array.<NumberOrString> +Returns the underlying annual sedra schedule. +Used by `@hebcal/triennial` + +**Kind**: instance method of [Sedra](#Sedra) + + +### sedra.getFirstSaturday() ⇒ number +R.D. date of the first Saturday on or after Rosh Hashana + +**Kind**: instance method of [Sedra](#Sedra) + + +### sedra.getYear() ⇒ number +**Kind**: instance method of [Sedra](#Sedra) + + +### sedra.lookup(hd) ⇒ SedraResult +Returns an object describing the parsha on the first Saturday on or after `hd` + +**Kind**: instance method of [Sedra](#Sedra) + +| Param | Type | Description | +| --- | --- | --- | +| hd | [HDate](#HDate) \| number | Hebrew date or R.D. days | + ## ParshaEvent @@ -2738,22 +2740,22 @@ Represents one of 54 weekly Torah portions, always on a Saturday **Kind**: global class * [ParshaEvent](#ParshaEvent) - * [new ParshaEvent(date, parsha, il, num)](#new_ParshaEvent_new) + * [new ParshaEvent(date, parsha, [il], [num])](#new_ParshaEvent_new) * [.render([locale])](#ParshaEvent+render) ⇒ string * [.basename()](#ParshaEvent+basename) ⇒ string - * [.url()](#ParshaEvent+url) ⇒ string + * [.url()](#ParshaEvent+url) ⇒ string \| undefined * [.urlDateSuffix()](#ParshaEvent+urlDateSuffix) ⇒ string -### new ParshaEvent(date, parsha, il, num) +### new ParshaEvent(date, parsha, [il], [num]) -| Param | Type | Description | -| --- | --- | --- | -| date | [HDate](#HDate) | | -| parsha | Array.<string> | untranslated name of single or double parsha, such as ['Bereshit'] or ['Achrei Mot', 'Kedoshim'] | -| il | boolean | | -| num | number \| Array.<number> | | +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| date | [HDate](#HDate) | | | +| parsha | Array.<string> | | untranslated name of single or double parsha, such as ['Bereshit'] or ['Achrei Mot', 'Kedoshim'] | +| [il] | boolean | false | | +| [num] | number \| Array.<number> | | | @@ -2770,7 +2772,7 @@ Represents one of 54 weekly Torah portions, always on a Saturday **Kind**: instance method of [ParshaEvent](#ParshaEvent) -### parshaEvent.url() ⇒ string +### parshaEvent.url() ⇒ string \| undefined **Kind**: instance method of [ParshaEvent](#ParshaEvent) @@ -2785,12 +2787,13 @@ Represents a built-in holiday like Pesach, Purim or Tu BiShvat * [HolidayEvent](#HolidayEvent) * [.basename()](#HolidayEvent+basename) ⇒ string - * [.url()](#HolidayEvent+url) ⇒ string + * [.url()](#HolidayEvent+url) ⇒ string \| undefined * [.urlDateSuffix()](#HolidayEvent+urlDateSuffix) ⇒ string * [.getEmoji()](#HolidayEvent+getEmoji) ⇒ string * [.getCategories()](#HolidayEvent+getCategories) ⇒ Array.<string> * [.render([locale])](#HolidayEvent+render) ⇒ string * [.renderBrief([locale])](#HolidayEvent+renderBrief) ⇒ string + * [.clone()](#HolidayEvent+clone) ⇒ [Event](#Event) @@ -2798,7 +2801,7 @@ Represents a built-in holiday like Pesach, Purim or Tu BiShvat **Kind**: instance method of [HolidayEvent](#HolidayEvent) -### holidayEvent.url() ⇒ string +### holidayEvent.url() ⇒ string \| undefined **Kind**: instance method of [HolidayEvent](#HolidayEvent) @@ -2836,6 +2839,23 @@ a shorter text (e.g. without a time or added description). | --- | --- | --- | | [locale] | string | Optional locale name (defaults to active locale). | + + +### holidayEvent.clone() ⇒ [Event](#Event) +Makes a clone of this Event object + +**Kind**: instance method of [HolidayEvent](#HolidayEvent) + + +## AsaraBTevetEvent +Because Asara B'Tevet often occurs twice in the same Gregorian year, +we subclass HolidayEvent to override the `url()` method. + +**Kind**: global class + + +### asaraBTevetEvent.urlDateSuffix() ⇒ string +**Kind**: instance method of [AsaraBTevetEvent](#AsaraBTevetEvent) ## RoshChodeshEvent @@ -2879,17 +2899,6 @@ Returns (translated) description of this event ### roshChodeshEvent.getEmoji() ⇒ string **Kind**: instance method of [RoshChodeshEvent](#RoshChodeshEvent) - - -## AsaraBTevetEvent -Because Asara B'Tevet often occurs twice in the same Gregorian year, -we subclass HolidayEvent to override the `url()` method. - -**Kind**: global class - - -### asaraBTevetEvent.urlDateSuffix() ⇒ string -**Kind**: instance method of [AsaraBTevetEvent](#AsaraBTevetEvent) ## MevarchimChodeshEvent @@ -2992,22 +3001,22 @@ Event names can be rendered in several languges using the `locale` option. * [HebrewCalendar](#HebrewCalendar) * [.calendar([options])](#HebrewCalendar.calendar) ⇒ [Array.<Event>](#Event) - * [.getBirthdayOrAnniversary(hyear, gdate)](#HebrewCalendar.getBirthdayOrAnniversary) ⇒ [HDate](#HDate) - * [.getYahrzeit(hyear, gdate)](#HebrewCalendar.getYahrzeit) ⇒ [HDate](#HDate) - * [.getHolidaysForYear(year)](#HebrewCalendar.getHolidaysForYear) ⇒ Map.<string, Array.<Event>> - * [.getHolidaysForYearArray(year, il)](#HebrewCalendar.getHolidaysForYearArray) ⇒ [Array.<Event>](#Event) - * [.getHolidaysOnDate(date, [il])](#HebrewCalendar.getHolidaysOnDate) ⇒ [Array.<Event>](#Event) + * [.getBirthdayOrAnniversary(hyear, gdate)](#HebrewCalendar.getBirthdayOrAnniversary) ⇒ [HDate](#HDate) \| undefined + * [.getYahrzeit(hyear, gdate)](#HebrewCalendar.getYahrzeit) ⇒ [HDate](#HDate) \| undefined + * [.getHolidaysForYear(year)](#HebrewCalendar.getHolidaysForYear) ⇒ HolidayYearMap + * [.getHolidaysForYearArray(year, il)](#HebrewCalendar.getHolidaysForYearArray) ⇒ [Array.<HolidayEvent>](#HolidayEvent) + * [.getHolidaysOnDate(date, [il])](#HebrewCalendar.getHolidaysOnDate) ⇒ [Array.<HolidayEvent>](#HolidayEvent) \| undefined * [.eruvTavshilin(date, il)](#HebrewCalendar.eruvTavshilin) ⇒ boolean * [.reformatTimeStr(timeStr, suffix, options)](#HebrewCalendar.reformatTimeStr) ⇒ string * [.version()](#HebrewCalendar.version) ⇒ string * [.getSedra(hyear, il)](#HebrewCalendar.getSedra) ⇒ [Sedra](#Sedra) * [.hallel(hdate, il)](#HebrewCalendar.hallel) ⇒ number - * [.tachanun(hdate, il)](#HebrewCalendar.tachanun) ⇒ [TachanunResult](#TachanunResult) + * [.tachanun(hdate, il)](#HebrewCalendar.tachanun) ⇒ TachanunResult ### HebrewCalendar.calendar([options]) ⇒ [Array.<Event>](#Event) -Calculates holidays and other Hebrew calendar events based on [CalOptions](#CalOptions). +Calculates holidays and other Hebrew calendar events based on [CalOptions](CalOptions). Each holiday is represented by an [Event](#Event) object which includes a date, a description, flags and optional attributes. @@ -3100,7 +3109,7 @@ Additional locales (such as `ru` or `fr`) are supported by the | Param | Type | Default | | --- | --- | --- | -| [options] | [CalOptions](#CalOptions) | {} | +| [options] | CalOptions | {} | **Example** ```js @@ -3122,7 +3131,7 @@ for (const ev of events) { ``` -### HebrewCalendar.getBirthdayOrAnniversary(hyear, gdate) ⇒ [HDate](#HDate) +### HebrewCalendar.getBirthdayOrAnniversary(hyear, gdate) ⇒ [HDate](#HDate) \| undefined Calculates a birthday or anniversary (non-yahrzeit). `hyear` must be after original `gdate` of anniversary. Returns `undefined` when requested year preceeds or is same as original year. @@ -3141,7 +3150,7 @@ has his birthday postponed until the first of the following month in years where that day does not occur. [Calendrical Calculations p. 111] **Kind**: static method of [HebrewCalendar](#HebrewCalendar) -**Returns**: [HDate](#HDate) - anniversary occurring in `hyear` +**Returns**: [HDate](#HDate) \| undefined - anniversary occurring in `hyear` | Param | Type | Description | | --- | --- | --- | @@ -3157,7 +3166,7 @@ console.log(hd.greg().toLocaleDateString('en-US')); // '3/26/2020' ``` -### HebrewCalendar.getYahrzeit(hyear, gdate) ⇒ [HDate](#HDate) +### HebrewCalendar.getYahrzeit(hyear, gdate) ⇒ [HDate](#HDate) \| undefined Calculates yahrzeit. `hyear` must be after original `gdate` of death. Returns `undefined` when requested year preceeds or is same as original year. @@ -3184,7 +3193,7 @@ There are several cases: of the date of death. [Calendrical Calculations p. 113] **Kind**: static method of [HebrewCalendar](#HebrewCalendar) -**Returns**: [HDate](#HDate) - anniversary occurring in hyear +**Returns**: [HDate](#HDate) \| undefined - anniversary occurring in hyear | Param | Type | Description | | --- | --- | --- | @@ -3200,7 +3209,7 @@ console.log(hd.greg().toLocaleDateString('en-US')); // '2/25/2020' ``` -### HebrewCalendar.getHolidaysForYear(year) ⇒ Map.<string, Array.<Event>> +### HebrewCalendar.getHolidaysForYear(year) ⇒ HolidayYearMap Lower-level holidays interface, which returns a `Map` of `Event`s indexed by `HDate.toString()`. These events must filtered especially for `flags.IL_ONLY` or `flags.CHUL_ONLY` depending on Israel vs. Diaspora holiday scheme. @@ -3213,7 +3222,7 @@ or `flags.CHUL_ONLY` depending on Israel vs. Diaspora holiday scheme. -### HebrewCalendar.getHolidaysForYearArray(year, il) ⇒ [Array.<Event>](#Event) +### HebrewCalendar.getHolidaysForYearArray(year, il) ⇒ [Array.<HolidayEvent>](#HolidayEvent) Returns an array of holidays for the year **Kind**: static method of [HebrewCalendar](#HebrewCalendar) @@ -3225,7 +3234,7 @@ Returns an array of holidays for the year -### HebrewCalendar.getHolidaysOnDate(date, [il]) ⇒ [Array.<Event>](#Event) +### HebrewCalendar.getHolidaysOnDate(date, [il]) ⇒ [Array.<HolidayEvent>](#HolidayEvent) \| undefined Returns an array of Events on this date (or `undefined` if no events) **Kind**: static method of [HebrewCalendar](#HebrewCalendar) @@ -3251,7 +3260,7 @@ Eruv Tavshilin ### HebrewCalendar.reformatTimeStr(timeStr, suffix, options) ⇒ string Helper function to format a 23-hour (00:00-23:59) time in US format ("8:13pm") or -keep as "20:13" for any other locale/country. Uses [CalOptions](#CalOptions) to determine +keep as "20:13" for any other locale/country. Uses [CalOptions](CalOptions) to determine locale. If `options.hour12` is `false`, locale is ignored and always returns 24-hour time. If `options.hour12` is `true`, locale is ignored and always returns 12-hour time. @@ -3262,7 +3271,7 @@ If `options.hour12` is `true`, locale is ignored and always returns 12-hour time | --- | --- | --- | | timeStr | string | original time like "20:30" | | suffix | string | "p" or "pm" or " P.M.". Add leading space if you want it | -| options | [CalOptions](#CalOptions) | | +| options | CalOptions | | @@ -3306,7 +3315,7 @@ The number is one of the following values: -### HebrewCalendar.tachanun(hdate, il) ⇒ [TachanunResult](#TachanunResult) +### HebrewCalendar.tachanun(hdate, il) ⇒ TachanunResult Return details on what Tachanun (or Tzidchatcha on Shabbat) is said on `hdate`. Tachanun is not said on Rosh Chodesh, the month of Nisan, Lag Baomer, @@ -3485,13 +3494,6 @@ Transliterated names of holidays, used by `Event.getDesc()` | YOM_KIPPUR | string | "YOM_KIPPUR" | Yom Kippur | | YOM_YERUSHALAYIM | string | "YOM_YERUSHALAYIM" | Yom Yerushalayim | - - -## HolidayDesc : enum -Transliterated names of holidays, used by `Event.getDesc()` - -**Kind**: global enum -**Read only**: true ## parshiot : Array.<string> @@ -3500,6 +3502,12 @@ parshiot[0] == 'Bereshit', parshiot[1] == 'Noach', parshiot[52] == "Ha'azinu". **Kind**: global constant **Read only**: true + + +## version +DO NOT EDIT THIS AUTO-GENERATED FILE! + +**Kind**: global constant ## hebrew2abs(year, month, day) ⇒ number @@ -3711,6 +3719,12 @@ Returns an emoji number symbol with a circle, for example `㊲` | --- | --- | | omerDay | the day of the omer, 1-49 inclusive | + + +## molad() +Calculates the molad for a Hebrew month + +**Kind**: global function ## getPseudoISO(tzid, date) ⇒ string @@ -3763,57 +3777,3 @@ Similar to `string.padStart(2, '0')`. | --- | --- | | number | number | - - -## CalOptions : Object -Options to configure which events are returned - -**Kind**: global typedef -**Properties** - -| Name | Type | Description | -| --- | --- | --- | -| [location] | [Location](#Location) | latitude/longitude/tzid used for candle-lighting | -| [year] | number | Gregorian or Hebrew year | -| [isHebrewYear] | boolean | to interpret year as Hebrew year | -| [month] | number | Gregorian or Hebrew month (to filter results to a single month) | -| [numYears] | number | generate calendar for multiple years (default 1) | -| [start] | Date \| [HDate](#HDate) \| number | use specific start date (requires end date) | -| [end] | Date \| [HDate](#HDate) \| number | use specific end date (requires start date) | -| [candlelighting] | boolean | calculate candle-lighting and havdalah times | -| [candleLightingMins] | number | minutes before sundown to light candles (default 18) | -| [havdalahMins] | number | minutes after sundown for Havdalah (typical values are 42, 50, or 72). If `undefined` (the default), calculate Havdalah according to Tzeit Hakochavim - Nightfall (the point when 3 small stars are observable in the night time sky with the naked eye). If `0`, Havdalah times are suppressed. | -| [havdalahDeg] | number | degrees for solar depression for Havdalah. Default is 8.5 degrees for 3 small stars. use 7.083 degrees for 3 medium-sized stars (observed by Dr. Baruch (Berthold) Cohn in his luach published in France in 1899). If `0`, Havdalah times are suppressed. | -| [fastEndDeg] | number | degrees for solar depression for end of fast days. Default is 7.083 degrees for 3 medium-sized stars. Other commonly-used values include 6.45 degrees, as calculated by Rabbi Yechiel Michel Tucazinsky. | -| [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. | -| [sedrot] | boolean | calculate parashah hashavua on Saturdays | -| [il] | boolean | Israeli holiday and sedra schedule | -| [noMinorFast] | boolean | suppress minor fasts | -| [noModern] | boolean | suppress modern holidays | -| [noRoshChodesh] | boolean | suppress Rosh Chodesh | -| [shabbatMevarchim] | boolean | add Shabbat Mevarchim | -| [noSpecialShabbat] | boolean | suppress Special Shabbat | -| [noHolidays] | boolean | suppress regular holidays | -| [omer] | boolean | include Days of the Omer | -| [molad] | boolean | include event announcing the molad | -| [ashkenazi] | boolean | use Ashkenazi transliterations for event titles (default Sephardi transliterations) | -| [locale] | string | translate event titles according to a locale Default value is `en`, also built-in are `he` and `ashkenazi`. Additional locales (such as `ru` or `fr`) are provided by the [@hebcal/locales](https://github.com/hebcal/hebcal-locales) package | -| [addHebrewDates] | boolean | print the Hebrew date for the entire date range | -| [addHebrewDatesForEvents] | boolean | print the Hebrew date for dates with some events | -| [mask] | number | use bitmask from `flags` to filter events | -| [yomKippurKatan] | boolean | include Yom Kippur Katan (default `false`). יוֹם כִּפּוּר קָטָן is a minor day of atonement occurring monthly on the day preceeding each Rosh Chodesh. Yom Kippur Katan is omitted in Elul (on the day before Rosh Hashanah), Tishrei (Yom Kippur has just passed), Kislev (due to Chanukah) and Nisan (fasting not permitted during Nisan). When Rosh Chodesh occurs on Shabbat or Sunday, Yom Kippur Katan is observed on the preceding Thursday. See [Wikipedia Yom Kippur Katan practices](https://en.wikipedia.org/wiki/Yom_Kippur_Katan#Practices) | -| [hour12] | boolean | Whether to use 12-hour time (as opposed to 24-hour time). Possible values are `true` and `false`; the default is locale dependent. | -| [dailyLearning] | Object.<string, any> | map of options to enable daily study calendars such as `dafYomi`, `mishnaYomi`, `nachYomi` with value `true`. For `yerushalmi` the value should be a `number` for edition (`1` for Vilna, `2` for Schottenstein). | - - - -## TachanunResult : Object -**Kind**: global typedef -**Properties** - -| Name | Type | Description | -| --- | --- | --- | -| shacharit | boolean | Tachanun is said at Shacharit | -| mincha | boolean | Tachanun is said at Mincha | -| allCongs | boolean | All congregations say Tachanun on the day | - diff --git a/package-lock.json b/package-lock.json index cf063f2e..964bd12c 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "@hebcal/core", - "version": "5.4.2", + "version": "5.4.3", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@hebcal/core", - "version": "5.4.2", + "version": "5.4.3", "license": "GPL-2.0", "dependencies": { "@hebcal/hdate": "^0.10.1", @@ -2110,9 +2110,9 @@ } }, "node_modules/@eslint-community/regexpp": { - "version": "4.10.0", - "resolved": "https://registry.npmjs.org/@eslint-community/regexpp/-/regexpp-4.10.0.tgz", - "integrity": "sha512-Cu96Sd2By9mCNTx2iyKOmq10v22jUVQv0lQnlGNy16oE9589yE+QADPbrMGCkA51cKZSg3Pu/aTJVTGfL/qjUA==", + "version": "4.10.1", + "resolved": "https://registry.npmjs.org/@eslint-community/regexpp/-/regexpp-4.10.1.tgz", + "integrity": "sha512-Zm2NGpWELsQAD1xsJzGQpYfvICSsFkEpU0jxBjfdC6uNEWXcHnfs9hScFWtXVDVl+rBQJGrl4g1vcKIejpH9dA==", "dev": true, "engines": { "node": "^12.0.0 || ^14.0.0 || >=16.0.0" @@ -3605,9 +3605,9 @@ "dev": true }, "node_modules/@types/node": { - "version": "20.13.0", - "resolved": "https://registry.npmjs.org/@types/node/-/node-20.13.0.tgz", - "integrity": "sha512-FM6AOb3khNkNIXPnHFDYaHerSv8uN22C91z098AnGccVu+Pcdhi+pNUFDi0iLmPIsVE0JBD0KVS7mzUYt4nRzQ==", + "version": "20.14.1", + "resolved": "https://registry.npmjs.org/@types/node/-/node-20.14.1.tgz", + "integrity": "sha512-T2MzSGEu+ysB/FkWfqmhV3PLyQlowdptmmgD20C6QxsS8Fmv5SjpZ1ayXaEC0S21/h5UJ9iA6W/5vSNU5l00OA==", "dev": true, "dependencies": { "undici-types": "~5.26.4" @@ -4324,9 +4324,9 @@ } }, "node_modules/caniuse-lite": { - "version": "1.0.30001626", - "resolved": "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001626.tgz", - "integrity": "sha512-JRW7kAH8PFJzoPCJhLSHgDgKg5348hsQ68aqb+slnzuB5QFERv846oA/mRChmlLAOdEDeOkRn3ynb1gSFnjt3w==", + "version": "1.0.30001627", + "resolved": "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001627.tgz", + "integrity": "sha512-4zgNiB8nTyV/tHhwZrFs88ryjls/lHiqFhrxCW4qSTeuRByBVnPYpDInchOIySWknznucaf31Z4KYqjfbrecVw==", "dev": true, "funding": [ { @@ -4994,9 +4994,9 @@ "dev": true }, "node_modules/electron-to-chromium": { - "version": "1.4.788", - "resolved": "https://registry.npmjs.org/electron-to-chromium/-/electron-to-chromium-1.4.788.tgz", - "integrity": "sha512-ubp5+Ev/VV8KuRoWnfP2QF2Bg+O2ZFdb49DiiNbz2VmgkIqrnyYaqIOqj8A6K/3p1xV0QcU5hBQ1+BmB6ot1OA==", + "version": "1.4.789", + "resolved": "https://registry.npmjs.org/electron-to-chromium/-/electron-to-chromium-1.4.789.tgz", + "integrity": "sha512-0VbyiaXoT++Fi2vHGo2ThOeS6X3vgRCWrjPeO2FeIAWL6ItiSJ9BqlH8LfCXe3X1IdcG+S0iLoNaxQWhfZoGzQ==", "dev": true }, "node_modules/emittery": { diff --git a/package.json b/package.json index 435940e5..7733a1bf 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@hebcal/core", - "version": "5.4.3", + "version": "5.4.4", "author": "Michael J. Radwin (https://github.com/mjradwin)", "contributors": [ "Eyal Schachter (https://github.com/Scimonster)", diff --git a/src/index.ts b/src/index.ts index 96091279..20c20113 100644 --- a/src/index.ts +++ b/src/index.ts @@ -10,6 +10,7 @@ export {Zmanim} from './zmanim'; export {TimedEvent, CandleLightingEvent, HavdalahEvent} from './TimedEvent'; export {Molad, MoladEvent} from './molad'; export {OmerEvent} from './omer'; +export {TachanunResult} from './tachanun'; export {Sedra, parshiot} from './sedra'; export {ParshaEvent} from './ParshaEvent'; export {HolidayEvent, AsaraBTevetEvent, diff --git a/src/tachanun.ts b/src/tachanun.ts index c0279fee..17eff86a 100644 --- a/src/tachanun.ts +++ b/src/tachanun.ts @@ -9,6 +9,9 @@ function range(start: number, end: number): number[] { return arr; } +/** + * Is *tachanun* said today? + */ export type TachanunResult = { /** Tachanun is said at Shacharit */ shacharit: boolean; diff --git a/src/zmanim.ts b/src/zmanim.ts index ef3f7e72..f9c78a14 100644 --- a/src/zmanim.ts +++ b/src/zmanim.ts @@ -251,6 +251,12 @@ export class Zmanim { } /** * Latest Shacharit (Gra); Sunrise plus 4 halachic hours, according to the Gra. + * + * This method returns the latest *zman tfila* (time to recite shema in the morning) + * that is 4 *shaos zmaniyos* (solar hours) after sunrise or sea level sunrise + * (depending on the `useElevation` setting), according + * to the [GRA](https://en.wikipedia.org/wiki/Vilna_Gaon). + * * If elevation is enabled, this function will include elevation in the calculation. * @return {Date} */ @@ -260,21 +266,18 @@ export class Zmanim { /** * Returns an array with alot (Date) and ms in hour (number) * @private - * @return {any[]} */ - getTemporalHour72(): any[] { - const alot72 = this.sunriseOffset(-72, false, true); - const tzeit72 = this.sunsetOffset(72, false, true); + getTemporalHour72(forceSeaLevel: boolean): [Date, number] { + const alot72 = this.sunriseOffset(-72, false, forceSeaLevel); + const tzeit72 = this.sunsetOffset(72, false, forceSeaLevel); const temporalHour = (tzeit72.getTime() - alot72.getTime()) / 12; return [alot72, temporalHour]; } /** * Returns an array with alot (Date) and ms in hour (number) * @private - * @param {number} angle - * @return {any[]} */ - getTemporalHourByDeg(angle: number): any[] { + getTemporalHourByDeg(angle: number): [Date, number] { const alot = this.timeAtAngle(angle, true); const tzeit = this.timeAtAngle(angle, false); const temporalHour = (tzeit.getTime() - alot.getTime()) / 12; @@ -288,8 +291,9 @@ export class Zmanim { * @return {Date} */ sofZmanShmaMGA(): Date { // Magen Avraham - const [alot72, temporalHour] = this.getTemporalHour72(); - return new Date(alot72.getTime() + (3 * temporalHour)); + const [alot72, temporalHour] = this.getTemporalHour72(true); + const offset = Math.floor(3 * temporalHour); + return new Date(alot72.getTime() + offset); } /** * Latest Shema (MGA); Sunrise plus 3 halachic hours, according to Magen Avraham. @@ -299,7 +303,8 @@ export class Zmanim { */ sofZmanShmaMGA16Point1(): Date { const [alot, temporalHour] = this.getTemporalHourByDeg(16.1); - return new Date(alot.getTime() + (3 * temporalHour)); + const offset = Math.floor(3 * temporalHour); + return new Date(alot.getTime() + offset); } /** * Latest Shema (MGA); Sunrise plus 3 halachic hours, according to Magen Avraham. @@ -313,15 +318,17 @@ export class Zmanim { */ sofZmanShmaMGA19Point8(): Date { const [alot, temporalHour] = this.getTemporalHourByDeg(19.8); - return new Date(alot.getTime() + (3 * temporalHour)); + const offset = Math.floor(3 * temporalHour); + return new Date(alot.getTime() + offset); } /** * Latest Shacharit (MGA); Sunrise plus 4 halachic hours, according to Magen Avraham * @return {Date} */ sofZmanTfillaMGA(): Date { // Magen Avraham - const [alot72, temporalHour] = this.getTemporalHour72(); - return new Date(alot72.getTime() + (4 * temporalHour)); + const [alot72, temporalHour] = this.getTemporalHour72(true); + const offset = Math.floor(4 * temporalHour); + return new Date(alot72.getTime() + offset); } /** * Latest Shacharit (MGA); Sunrise plus 4 halachic hours, according to Magen Avraham. @@ -331,7 +338,8 @@ export class Zmanim { */ sofZmanTfillaMGA16Point1(): Date { const [alot, temporalHour] = this.getTemporalHourByDeg(16.1); - return new Date(alot.getTime() + (4 * temporalHour)); + const offset = Math.floor(4 * temporalHour); + return new Date(alot.getTime() + offset); } /** * Latest Shacharit (MGA); Sunrise plus 4 halachic hours, according to Magen Avraham. @@ -345,24 +353,67 @@ export class Zmanim { */ sofZmanTfillaMGA19Point8(): Date { const [alot, temporalHour] = this.getTemporalHourByDeg(19.8); - return new Date(alot.getTime() + (4 * temporalHour)); + const offset = Math.floor(4 * temporalHour); + return new Date(alot.getTime() + offset); } /** - * Earliest Mincha – Mincha Gedola; Sunrise plus 6.5 halachic hours. + * Earliest Mincha – Mincha Gedola (GRA); Sunrise plus 6.5 halachic hours. * If elevation is enabled, this function will include elevation in the calculation. + * + * This method returns the latest mincha gedola, the earliest time one can pray mincha + * that is 6.5 shaos zmaniyos (solar hours) after sunrise or sea level sunrise + * (depending on the `useElevation` setting), according + * to the [GRA](https://en.wikipedia.org/wiki/Vilna_Gaon). + * + * The Ramba"m is of the opinion that it is better to delay *mincha* until + * *mincha ketana* while the Ra"sh, Tur, GRA and others are of the + * opinion that *mincha* can be prayed *lechatchila* starting at *mincha gedola*. * @return {Date} */ minchaGedola(): Date { return this.getShaahZmanisBasedZman(6.5); } + /** + * Earliest Mincha – Mincha Gedola (MGA); Sunrise plus 6.5 halachic hours. + * If elevation is enabled, this function will include elevation in the calculation. + * + * This method returns the time of *mincha gedola* according to the Magen Avraham + * with the day starting 72 minutes before sunrise and ending 72 minutes after sunset. + * This is the earliest time to pray *mincha*. + * @return {Date} + */ + minchaGedolaMGA(): Date { + const [alot72, temporalHour] = this.getTemporalHour72(false); + const offset = Math.floor(6.5 * temporalHour); + return new Date(alot72.getTime() + offset); + } /** * Preferable earliest time to recite Minchah – Mincha Ketana; Sunrise plus 9.5 halachic hours. * If elevation is enabled, this function will include elevation in the calculation. + * + * This method returns *mincha ketana*, the preferred earliest time to pray *mincha* in the + * opinion of the [Rambam](https://en.wikipedia.org/wiki/Maimonides) and others, + * that is 9.5 *shaos zmaniyos* (solar hours) after sunrise or sea level sunrise + * (depending on the `useElevation` setting), according + * to the [GRA](https://en.wikipedia.org/wiki/Vilna_Gaon). * @return {Date} */ minchaKetana(): Date { return this.getShaahZmanisBasedZman(9.5); } + /** + * This method returns the time of *mincha ketana* according to the Magen Avraham + * with the day starting 72 minutes before sunrise and ending 72 minutes after sunset. + * This is the preferred earliest time to pray *mincha* according to the opinion of + * the [Rambam](https://en.wikipedia.org/wiki/Maimonides) and others. + * + * If elevation is enabled, this function will include elevation in the calculation. + * @return {Date} + */ + minchaKetanaMGA(): Date { + const [alot72, temporalHour] = this.getTemporalHour72(false); + return new Date(alot72.getTime() + Math.floor(9.5 * temporalHour)); + } /** * Plag haMincha; Sunrise plus 10.75 halachic hours. * If elevation is enabled, this function will include elevation in the calculation. diff --git a/test/zmanim.spec.js b/test/zmanim.spec.js index 643fbbc4..cb29713c 100644 --- a/test/zmanim.spec.js +++ b/test/zmanim.spec.js @@ -51,7 +51,9 @@ test('zmanim', () => { sofZmanTfillaMGA: '09:54', chatzot: '12:49', minchaGedola: '13:27', + minchaGedolaMGA: '13:33', minchaKetana: '17:13', + minchaKetanaMGA: '17:55', plagHaMincha: '18:48', sunset: '20:22', shkiah: '20:22', @@ -97,7 +99,9 @@ test('zmanim-tlv', () => { sofZmanTfilla: '03/06/2021, 09:55:38', chatzot: '03/06/2021, 11:52:19', minchaGedola: '03/06/2021, 12:21:29', + minchaGedolaMGA: '03/06/2021, 12:27:29', minchaKetana: '03/06/2021, 15:16:30', + minchaKetanaMGA: '03/06/2021, 15:58:30', plagHaMincha: '03/06/2021, 16:29:26', sunset: '03/06/2021, 17:42:22', shkiah: '03/06/2021, 17:42:22', @@ -178,8 +182,10 @@ test('zmanim-denver', () => { // "Chatzos": "2020-06-05T12:58:43-06:00", chatzot: '06/05/2020, 12:58:43', minchaGedola: '06/05/2020, 13:36:35', + minchaGedolaMGA: '06/05/2020, 13:42:34', // @TODO "MinchaKetana": "2020-06-05T17:19:04-06:00", minchaKetana: '06/05/2020, 17:23:42', + minchaKetanaMGA: '06/05/2020, 18:05:41', plagHaMincha: '06/05/2020, 18:58:19', seaLevelSunset: '06/05/2020, 20:25:01', // "Sunset": "2020-06-05T20:32:57-06:00", @@ -513,7 +519,9 @@ test('zmanim-UTC', () => { sofZmanTfillaMGA16Point1: '09:35:16', chatzot: '11:58:36', minchaGedola: '12:28:57', + minchaGedolaMGA: '12:34:56', minchaKetana: '15:31:06', + minchaKetanaMGA: '16:13:05', plagHaMincha: '16:47:00', seaLevelSunset: '18:02:15', sunset: '18:02:53',