@hebcal/core 6.8.2 → 6.9.1

package/dist/esm/zmanim.js

@@ -1,4 +1,4 @@
-/*! @hebcal/core v6.8.2, distributed under GPLv2 https://www.gnu.org/licenses/gpl-2.0.txt */
+/*! @hebcal/core v6.9.1, distributed under GPLv2 https://www.gnu.org/licenses/gpl-2.0.txt */
 import 'temporal-polyfill/global';
 import { NOAACalculator } from '@hebcal/noaa';
 import { HDate, isDate, getTimezoneOffset, pad2, getPseudoISO } from '@hebcal/hdate';
@@ -16,16 +16,16 @@ function zdtToDate(zdt) {
     return res;
 }
 /**
- * The zenith of astronomical sunrise and sunset. The sun is 90° from the vertical 0°
+ * The zenith of astronomical sunrise and sunset. The sun is 90° from the vertical 0°
  */
 const GEOMETRIC_ZENITH = 90;
 /**
- * The zenith of 1.583° below {@link GEOMETRIC_ZENITH geometric zenith} (90°). This calculation is used for
+ * The zenith of 1.583° below geometric zenith (90°). This calculation is used for
  * calculating _netz amiti_ (sunrise) and _shkiah amiti_ (sunset) based on the opinion of the
- * <a href="https://en.wikipedia.org/wiki/Shneur_Zalman_of_Liadi">Baal Hatanya</a>.
+ * [Baal Hatanya](https://en.wikipedia.org/wiki/Shneur_Zalman_of_Liadi).
  *
- * @see Zmanim.sunriseBaalHatanya()
- * @see Zmanim.sunsetBaalHatanya()
+ * @see Zmanim.sunriseBaalHatanya
+ * @see Zmanim.sunsetBaalHatanya
  */
 const ZENITH_1_POINT_583 = GEOMETRIC_ZENITH + 1.583;
 /**
@@ -44,7 +44,7 @@ const ZENITH_1_POINT_583 = GEOMETRIC_ZENITH + 1.583;
  * https://gml.noaa.gov/grad/solcalc/calcdetails.html
  *
  * @example
- * const {GeoLocation, Zmanim} = require('@hebcal/core');
+ * import {GeoLocation, Zmanim} from '@hebcal/core';
  * const latitude = 41.822232;
  * const longitude = -71.448292;
  * const tzid = 'America/New_York';
@@ -53,6 +53,7 @@ const ZENITH_1_POINT_583 = GEOMETRIC_ZENITH + 1.583;
  * const zmanim = new Zmanim(gloc, friday, false);
  * const candleLighting = zmanim.sunsetOffset(-18, true);
  * const timeStr = Zmanim.formatISOWithTimeZone(tzid, candleLighting);
+ * // '2023-09-08T18:49:00-04:00'
  */
 class Zmanim {
     hdate;
@@ -84,15 +85,19 @@ class Zmanim {
         this.useElevation = Boolean(useElevation);
     }
     /**
-     * Returns `true` if elevation adjustment is enabled
-     * for zmanim support elevation adjustment
+     * Returns `true` if this instance uses the location's elevation when
+     * calculating sunrise/sunset-based zmanim.
      */
     getUseElevation() {
         return this.useElevation;
     }
     /**
-     * Enables or disables elevation adjustment for zmanim support elevation adjustment
-     * @param useElevation
+     * Enables or disables elevation adjustment for sunrise/sunset-based zmanim.
+     *
+     * Degree-based zmanim (such as {@link alotHaShachar} or {@link tzeit})
+     * estimate the amount of light in the sky and are never affected by this
+     * setting.
+     * @param useElevation `true` to include the location's elevation
      */
     setUseElevation(useElevation) {
         this.useElevation = useElevation;
@@ -101,8 +106,10 @@ class Zmanim {
      * Convenience function to get the time when sun is above or below the horizon
      * for a certain angle (in degrees).
      * This function does not support elevation adjustment.
-     * @param angle
-     * @param rising
+     * @param angle degrees of solar depression below the horizon; for example
+     *  `8.5` means the center of the sun is 8.5° below the horizon
+     * @param rising `true` for the morning (before sunrise), `false` for the
+     *  evening (after sunset)
      */
     timeAtAngle(angle, rising) {
         const offsetZenith = GEOMETRIC_ZENITH + angle;
@@ -176,13 +183,19 @@ class Zmanim {
         return zman.sunset();
     }
     /**
-     * @private
+     * Length in milliseconds of one halachic hour of the night, calculated as
+     * one twelfth of the time between the previous day's sunset and this
+     * day's sunrise. Used internally by {@link chatzotNight}.
      */
     nightHour() {
         return (this.sunrise().getTime() - this.gregEve().getTime()) / 12; // ms in hour
     }
     /**
-     * Midday – Chatzot; Sunrise plus 6 halachic hours
+     * Midday – Chatzot; Sunrise plus 6 halachic hours.
+     *
+     * Unlike most sunrise/sunset-based zmanim, this is always computed from
+     * sea-level sunrise and sunset, so it is not affected by the
+     * `useElevation` setting.
      */
     chatzot() {
         const startOfDay = this.noaa.getSeaLevelSunrise();
@@ -212,6 +225,11 @@ class Zmanim {
     alotHaShachar72() {
         return this.sunriseOffset(-72, false, false);
     }
+    /**
+     * Same as {@link alotHaShachar72}, but returns a `Temporal.ZonedDateTime`
+     * with seconds precision (instead of a `Date` rounded to the minute), or
+     * `null` if sunrise cannot be calculated for this date and location.
+     */
     alotHaShachar72zdt() {
         const zdt = this.useElevation
             ? this.noaa.getSunrise()
@@ -245,8 +263,7 @@ class Zmanim {
     }
     /**
      * Utility method for using elevation-aware sunrise/sunset
-     * @private
-     * @param hours
+     * @param hours number of _shaos zmaniyos_ (solar hours) after sunrise
      */
     getShaahZmanisBasedZman(hours) {
         const startOfDay = this.useElevation
@@ -269,7 +286,7 @@ 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)
+     * This method returns the latest *zman tfila* (time to recite the morning prayers)
      * 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).
@@ -282,21 +299,23 @@ class Zmanim {
     }
     /**
      * This method returns the latest time for burning _chametz_ on _Erev Pesach_ according to the opinion
-     * of the <a href="https://en.wikipedia.org/wiki/Vilna_Gaon">GRA</a>. This time is 5 hours into the day based on the
-     * opinion of the <a href="https://en.wikipedia.org/wiki/Vilna_Gaon">GRA</a> that the day is calculated from
-     * sunrise to sunset. This returns the time 5 * {@link #getShaahZmanisGra()} after {@link #getSeaLevelSunrise() sea
-     * level sunrise}.
-     * @return the <code>Date</code> of the latest time for burning _chametz_ on _Erev Pesach_. If it is not
-     *         _erev Pesach_ or 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 <code>null</code> will be
-     *         returned.
+     * of the [GRA](https://en.wikipedia.org/wiki/Vilna_Gaon). This time is 5 halachic hours into the day, based on
+     * the opinion of the GRA that the day is calculated from sunrise to sunset.
+     *
+     * If elevation is enabled, this function will include elevation in the calculation.
+     * @return the `Date` of the latest time for burning _chametz_ on _Erev Pesach_. 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, an `Invalid Date` will be returned.
      */
     sofZmanBiurChametzGRA() {
         return this.getShaahZmanisBasedZman(5);
     }
     /**
-     * Returns an array with alot (Date) and ms in hour (number)
-     * @private
+     * Returns a 2-element array with alot (a `Date`, 72 minutes before sunrise)
+     * and the length in milliseconds of one halachic hour of the resulting day.
+     * Used internally by the Magen Avraham zmanim.
+     * @param forceSeaLevel ignore the `useElevation` setting and use sea-level
+     *  sunrise and sunset
      */
     getTemporalHour72(forceSeaLevel) {
         const alot72 = this.sunriseOffset(-72, false, forceSeaLevel);
@@ -305,8 +324,11 @@ class Zmanim {
         return [alot72, temporalHour];
     }
     /**
-     * Returns an array with alot (Date) and ms in hour (number)
-     * @private
+     * Returns a 2-element array with alot (a `Date`, when the sun is `angle`
+     * degrees below the horizon in the morning) and the length in milliseconds
+     * of one halachic hour of the resulting day. Used internally by the
+     * degree-based Magen Avraham zmanim.
+     * @param angle degrees of solar depression below the horizon
      */
     getTemporalHourByDeg(angle) {
         const alot = this.timeAtAngle(angle, true);
@@ -387,7 +409,7 @@ class Zmanim {
      * 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
+     * This method returns *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).
@@ -445,14 +467,24 @@ class Zmanim {
         return this.getShaahZmanisBasedZman(10.75);
     }
     /**
-     * @param [angle=8.5] optional time for solar depression.
-     *   Default is 8.5 degrees for 3 small stars, use 7.083 degrees for 3 medium-sized stars.
+     * Nightfall – Tzeit HaKochavim; the sun is `angle` degrees below the
+     * horizon in the evening.
+     *
      * Because degree-based functions estimate the amount of light in the sky,
      * the result is not impacted by elevation.
+     * @param [angle=8.5] optional time for solar depression.
+     *   Default is 8.5 degrees for 3 small stars, use 7.083 degrees for 3 medium-sized stars.
      */
     tzeit(angle = 8.5) {
         return this.timeAtAngle(angle, false);
     }
+    /**
+     * Nightfall – Tzeit HaKochavim; calculated as 72 minutes after sunset
+     * (or sea-level sunset, depending on the `useElevation` setting).
+     *
+     * Returns a `Temporal.ZonedDateTime` with seconds precision, or `null` if
+     * sunset cannot be calculated for this date and location.
+     */
     tzeit72() {
         const zdt = this.useElevation
             ? this.noaa.getSunset()
@@ -549,12 +581,13 @@ class Zmanim {
         return moladBasedTime.withTimeZone(this.gloc.getTimeZone());
     }
     /**
-     * Returns the latest time of Kiddush Levana according to the <a
-     * href="https://en.wikipedia.org/wiki/Yaakov_ben_Moshe_Levi_Moelin">Maharil's</a> opinion that it is calculated as
+     * Returns the latest time of Kiddush Levana according to the
+     * [Maharil's](https://en.wikipedia.org/wiki/Yaakov_ben_Moshe_Levi_Moelin) opinion that it is calculated as
      * halfway between _molad_ and _molad_. This adds half the 29 days, 12 hours and 793 chalakim time between
      * _molad_ and _molad_ (14 days, 18 hours, 22 minutes and 666 milliseconds) to the month's _molad_.
-     * The _sof zman Kiddush Levana_ will be returned even if it occurs during the day. To limit the time to between
-     * _tzais_ and _alos_, see {@link getSofZmanKidushLevanaBetweenMoldos}.
+     *
+     * The _sof zman Kiddush Levana_ will be returned even if it occurs during the day, unless both `alos` and
+     * `tzais` are supplied.
      *
      * @param alos
      *            the beginning of the Jewish day. If _Kidush Levana_ occurs during the day (starting at _alos_ and
@@ -564,9 +597,9 @@ class Zmanim {
      *            the end of the Jewish day. If Kidush Levana occurs during the day (starting at alos and ending at
      *            tzais), the time returned will be alos. If either the alos or tzais parameters are null, no daytime
      *            adjustment will be made.
-     * @return the Date representing the moment halfway between molad and molad. If the time occurs between
-     *         _alos_ and _tzais_, _alos_ will be returned. If the _zman_ will not occur on this
-     *         day, a `null` will be returned.
+     * @return the `Temporal.ZonedDateTime` representing the moment halfway between molad and molad. If the time
+     *         occurs between _alos_ and _tzais_, _alos_ will be returned. If the _zman_ will not occur on this
+     *         day, `null` will be returned.
      */
     getSofZmanKidushLevanaBetweenMoldos(alos = null, tzais = null) {
         const hd = this.hdate;
@@ -583,19 +616,25 @@ class Zmanim {
     /**
      * Returns the latest time of _Kiddush Levana_ calculated as 15 days after the molad. This is the opinion of
      * the Shulchan Aruch (Orach Chaim 426). It should be noted that some opinions hold that the
-     * <a href="https://en.wikipedia.org/wiki/Moses_Isserles">Rema</a> who brings down the opinion of the <a
-     * href="https://en.wikipedia.org/wiki/Yaakov_ben_Moshe_Levi_Moelin">Maharil's</a> of calculating
-     * {@link getSofZmanKidushLevanaBetweenMoldos half way between _molad_ and _molad_} is of
-     * the opinion that the Mechaber agrees to his opinion. Also see the Aruch Hashulchan. For additional details on the subject,
-     * See Rabbi Dovid Heber's very detailed write-up in Siman Daled (chapter 4) of <a href="https://hebrewbooks.org/53000">Shaarei
-     * Zmanim</a>. The _sof zman Kiddush Levana_ will be returned even if it occurs during the day. To limit the time to
-     * between _tzais_ and _alos_, see {@link getSofZmanKidushLevana15Days}.
-     *
-     * @return the Date representing the moment 15 days after the _molad_. If the time occurs between
-     *         _alos_ and _tzais_, _alos_ will be returned. If the _zman_ will not occur on this day, a
-     *         `null` will be returned.
+     * [Rema](https://en.wikipedia.org/wiki/Moses_Isserles), who brings down the opinion of the
+     * [Maharil](https://en.wikipedia.org/wiki/Yaakov_ben_Moshe_Levi_Moelin) of calculating
+     * {@link getSofZmanKidushLevanaBetweenMoldos half way between _molad_ and _molad_}, is of
+     * the opinion that the Mechaber agrees to his opinion. Also see the Aruch Hashulchan. For additional details on
+     * the subject, see Rabbi Dovid Heber's very detailed write-up in Siman Daled (chapter 4) of
+     * [Shaarei Zmanim](https://hebrewbooks.org/53000).
      *
+     * The _sof zman Kiddush Levana_ will be returned even if it occurs during the day, unless both `alos` and
+     * `tzais` are supplied.
      *
+     * @param alos
+     *            the beginning of the Jewish day. If either the _alos_ or _tzais_ parameters are null, no daytime
+     *            adjustment will be made.
+     * @param tzais
+     *            the end of the Jewish day. If either the _alos_ or _tzais_ parameters are null, no daytime
+     *            adjustment will be made.
+     * @return the `Temporal.ZonedDateTime` representing the moment 15 days after the _molad_. If the time occurs
+     *         between _alos_ and _tzais_, _alos_ will be returned. If the _zman_ will not occur on this day,
+     *         `null` will be returned.
      */
     getSofZmanKidushLevana15Days(alos = null, tzais = null) {
         const hd = this.hdate;
@@ -610,8 +649,8 @@ class Zmanim {
         return this.getMoladBasedTime(molad.getSofZmanKidushLevana15Days(), alos, tzais, false);
     }
     /**
-     * Returns the earliest time of _Kiddush Levana_ according to <a href=
-     * "https://en.wikipedia.org/wiki/Yonah_Gerondi">Rabbeinu Yonah</a>'s opinion that it can be said 3 days after the _molad_.
+     * Returns the earliest time of _Kiddush Levana_ according to
+     * [Rabbeinu Yonah](https://en.wikipedia.org/wiki/Yonah_Gerondi)'s opinion that it can be said 3 days after the _molad_.
      * If the time of _tchilas zman Kiddush Levana_ occurs during the day (between _alos_ and _tzais_ passed to
      * this method) it will return the following _tzais_. If null is passed for either _alos_ or _tzais_, the actual
      * _tchilas zman Kiddush Levana_ will be returned, regardless of if it is during the day or not.
@@ -625,8 +664,8 @@ class Zmanim {
      *            _tzais_), the time returned will be _tzais_. If either the _alos_ or _tzais_ parameters
      *            are null, no daytime adjustment will be made.
      *
-     * @return the Date representing the moment 3 days after the molad. If the time occurs between _alos_ and
-     *         _tzais_, _tzais_ will be returned. If the _zman_ will not occur on this day, a
+     * @return the `Temporal.ZonedDateTime` representing the moment 3 days after the molad. If the time occurs
+     *         between _alos_ and _tzais_, _tzais_ will be returned. If the _zman_ will not occur on this day,
      *         `null` will be returned.
      */
     getTchilasZmanKidushLevana3Days(alos = null, tzais = null) {
@@ -651,13 +690,11 @@ class Zmanim {
         return zman;
     }
     /**
-     * Returns the point in time of _Molad_ as a <code>Date</code> Object. For the traditional day of week, hour,
-     * minute and chalakim, {@link Molad.getInstant()} and the not yet completed
-     * {@link HebrewDateFormatter} that will have formatting for this.
-     *
-     * @return the Date representing the moment of the molad. If the _molad_ does not occur on this day, a
-     *         `null` will be returned.
+     * Returns the point in time of the _Molad_, if it occurs on this date. For the traditional day of week, hour,
+     * minute and chalakim, see {@link Molad} and its {@link Molad.render} method.
      *
+     * @return the `Temporal.ZonedDateTime` representing the moment of the molad. If the _molad_ does not occur on
+     *         this day, `null` will be returned.
      */
     getZmanMolad() {
         const hd = this.hdate;
@@ -680,10 +717,17 @@ class Zmanim {
     /**
      * Returns the earliest time of _Kiddush Levana_ according to the opinions that it should not be said until 7
      * days after the _molad_. The time will be returned even if it occurs during the day when _Kiddush Levana_
-     * can't be recited. Use {@link getTchilasZmanKidushLevana7Days} if you want to limit the time to night hours.
+     * can't be recited, unless both `alos` and `tzais` are supplied.
      *
-     * @return the Date representing the moment 7 days after the molad regardless of it is day or night. If the _zman_
-     *         will not occur on this day, a `null` will be returned.
+     * @param alos
+     *            the beginning of the Jewish day. If _Kidush Levana_ occurs during the day (starting at _alos_ and
+     *            ending at _tzais_), the time returned will be _tzais_. If either the _alos_ or _tzais_ parameters
+     *            are null, no daytime adjustment will be made.
+     * @param tzais
+     *            the end of the Jewish day. If either the _alos_ or _tzais_ parameters are null, no daytime
+     *            adjustment will be made.
+     * @return the `Temporal.ZonedDateTime` representing the moment 7 days after the molad. If the _zman_
+     *         will not occur on this day, `null` will be returned.
      */
     getTchilasZmanKidushLevana7Days(alos = null, tzais = null) {
         const hd = this.hdate;
@@ -699,41 +743,38 @@ class Zmanim {
         return this.getMoladBasedTime(molad.getTchilasZmanKidushLevana7Days(), alos, tzais, true);
     }
     /**
-     * A method that returns the <a href="https://en.wikipedia.org/wiki/Shneur_Zalman_of_Liadi">Baal Hatanya</a>'s
+     * A method that returns the [Baal Hatanya](https://en.wikipedia.org/wiki/Shneur_Zalman_of_Liadi)'s
      * _netz amiti_ (sunrise) without
      * elevation adjustment. This forms the base for the Baal Hatanya's dawn-based calculations that are
      * calculated as a dip below the horizon before sunrise.
      *
      * According to the Baal Hatanya, _netz amiti_, or true (halachic) sunrise, is when the top of the sun's
      * disk is visible at an elevation similar to the mountains of Eretz Yisrael. The time is calculated as the point at which
-     * the center of the sun's disk is 1.583&deg; below the horizon. This degree-based calculation can be found in Rabbi Shalom
-     * DovBer Levine's commentary on The <a href="https://www.chabadlibrary.org/books/pdf/Seder-Hachnosas-Shabbos.pdf">Baal
-     * Hatanya's Seder Hachnasas Shabbos</a>. From an elevation of 546 meters, the top of <a href=
-     * "https://en.wikipedia.org/wiki/Mount_Carmel">Har Hacarmel</a>, the sun disappears when it is 1&deg; 35' or 1.583&deg;
-     * below the sea level horizon. This in turn is based on the Gemara <a href=
-     * "https://hebrewbooks.org/shas.aspx?mesechta=2&daf=35">Shabbos 35a</a>. There are other opinions brought down by
+     * the center of the sun's disk is 1.583° below the horizon. This degree-based calculation can be found in Rabbi Shalom
+     * DovBer Levine's commentary on
+     * [The Baal Hatanya's Seder Hachnasas Shabbos](https://www.chabadlibrary.org/books/pdf/Seder-Hachnosas-Shabbos.pdf).
+     * From an elevation of 546 meters, the top of [Har Hacarmel](https://en.wikipedia.org/wiki/Mount_Carmel),
+     * the sun disappears when it is 1° 35' or 1.583° below the sea level horizon. This in turn is based on the Gemara
+     * [Shabbos 35a](https://hebrewbooks.org/shas.aspx?mesechta=2&daf=35). There are other opinions brought down by
      * Rabbi Levine, including Rabbi Yosef Yitzchok Feigelstock who calculates it as the degrees below the horizon 4 minutes after
-     * sunset in Yerushalayim (on the equinox). That is brought down as 1.583&deg;. This is identical to the 1&deg; 35' _zman_
-     * and is probably a typo and should be 1.683&deg;. These calculations are used by most <a href=
-     * "https://en.wikipedia.org/wiki/Chabad">Chabad</a> calendars that use the Baal Hatanya's _zmanim_. See
-     * <a href="https://www.chabad.org/library/article_cdo/aid/3209349/jewish/About-Our-Zmanim-Calculations.htm">About Our
-     * _Zmanim_ Calculations @ Chabad.org</a>.
+     * sunset in Yerushalayim (on the equinox). That is brought down as 1.583°. This is identical to the 1° 35' _zman_
+     * and is probably a typo and should be 1.683°. These calculations are used by most
+     * [Chabad](https://en.wikipedia.org/wiki/Chabad) calendars that use the Baal Hatanya's _zmanim_. See
+     * [About Our Zmanim Calculations @ Chabad.org](https://www.chabad.org/library/article_cdo/aid/3209349/jewish/About-Our-Zmanim-Calculations.htm).
      *
      * Note: _netz amiti_ is used only for calculating certain _zmanim_, and is intentionally unpublished. For
      * practical purposes, daytime _mitzvos_ like _shofar_ and _lulav_ should not be done until after the
      * published time for _netz_ / sunrise.
      *
-     * @return the <code>Date</code> representing the exact sea level _netz amiti_ (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 ZENITH_1_POINT_583
+     * @return the exact sea level _netz amiti_ (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, `null` will be returned.
      */
     getSunriseBaalHatanya() {
         return this.noaa.getSunriseOffsetByDegrees(ZENITH_1_POINT_583);
     }
     /**
-     * A method that returns the <a href="https://en.wikipedia.org/wiki/Shneur_Zalman_of_Liadi">Baal Hatanya</a>'s
+     * A method that returns the [Baal Hatanya](https://en.wikipedia.org/wiki/Shneur_Zalman_of_Liadi)'s
      * _shkiah amiti_ (sunset) without
      * elevation adjustment. This forms the base for the Baal Hatanya's dusk-based calculations that are calculated
      * as a dip below the horizon after sunset.
@@ -746,33 +787,31 @@ class Zmanim {
      * practical purposes, all daytime mitzvos should be completed before the published time for _shkiah_ / sunset.
      *
      * For further explanation of the calculations used for the Baal Hatanya's _zmanim_ in this library, see
-     * <a href="https://www.chabad.org/library/article_cdo/aid/3209349/jewish/About-Our-Zmanim-Calculations.htm">About Our
-     * _Zmanim_ Calculations @ Chabad.org</a>.
-     *
-     * @return the <code>Date</code> representing the exact sea level _shkiah amiti_ (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.
+     * [About Our Zmanim Calculations @ Chabad.org](https://www.chabad.org/library/article_cdo/aid/3209349/jewish/About-Our-Zmanim-Calculations.htm).
      *
-     * @see ZENITH_1_POINT_583
+     * @return the exact sea level _shkiah amiti_ (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, `null` will be returned.
      */
     getSunsetBaalHatanya() {
         return this.noaa.getSunsetOffsetByDegrees(ZENITH_1_POINT_583);
     }
     /**
-     * Returns the <a href="https://en.wikipedia.org/wiki/Shneur_Zalman_of_Liadi">Baal Hatanya</a>'s _alos_
-     * (dawn) calculated as the time when the sun is 16.9&deg; below the eastern {@link GEOMETRIC_ZENITH geometric horizon}
-     * before {@link getSunrise() sunrise}.
+     * Returns the [Baal Hatanya](https://en.wikipedia.org/wiki/Shneur_Zalman_of_Liadi)'s _alos_
+     * (dawn) calculated as the time when the sun is 16.9° below the eastern geometric horizon
+     * before {@link sunrise}.
      *
-     * The zenith of 16.9&deg; below is based on the calculation that the time between dawn
-     * and _netz amiti_ (sunrise) is 72 minutes, the time that is takes to walk 4 mil at 18 minutes
-     * a mil (<a href="https://en.wikipedia.org/wiki/Maimonides">Rambam</a> and others). The sun's position at 72
-     * minutes before {@link getSunriseBaalHatanya _netz amiti_ (sunrise)} in Jerusalem <a href=
-     * "https://kosherjava.com/2022/01/12/equinox-vs-equilux-zmanim-calculations/">around the equinox / equilux</a> is
-     * 16.9&deg; below {@link GEOMETRIC_ZENITH geometric zenith}.
+     * The zenith of 16.9° below is based on the calculation that the time between dawn
+     * and _netz amiti_ (sunrise) is 72 minutes, the time that it takes to walk 4 mil at 18 minutes
+     * a mil ([Rambam](https://en.wikipedia.org/wiki/Maimonides) and others). The sun's position at 72
+     * minutes before _netz amiti_ (sunrise) in Jerusalem
+     * [around the equinox / equilux](https://kosherjava.com/2022/01/12/equinox-vs-equilux-zmanim-calculations/)
+     * is 16.9° below geometric zenith.
      *
-     * @return The <code>Date</code> of dawn. If the calculation can't be computed such as northern and southern
+     * @return the `Date` of dawn. If the calculation can't be computed, such as in northern and southern
      *         locations even south of the Arctic Circle and north of the Antarctic Circle where the sun may not reach
-     *         low enough below the horizon for this calculation, a `null` will be returned.   */
+     *         low enough below the horizon for this calculation, an `Invalid Date` will be returned.
+     */
     alosBaalHatanya() {
         return this.timeAtAngle(16.9, true);
     }
@@ -782,86 +821,79 @@ class Zmanim {
     }
     /**
      * This method returns the latest _zman krias shema_ (time to recite Shema in the morning). This time is 3
-     * {@link shaahZmanisBaalHatanya() _shaos zmaniyos_} (solar hours) after {@link getSunriseBaalHatanya()
-     * _netz amiti_ (sunrise)} based on the opinion of the Baal Hatanya that the day is calculated from
-     * sunrise to sunset. This returns the time 3 * {@link getShaahZmanisBaalHatanya()} after {@link getSunriseBaalHatanya()
-     * _netz amiti_ (sunrise)}.
+     * _shaos zmaniyos_ (solar hours) after _netz amiti_ (sunrise), based on the opinion of the Baal Hatanya
+     * that the day is calculated from _netz amiti_ (sunrise) to _shkiah amiti_ (sunset).
      *
-     * @return the <code>Date</code> of the latest _zman shema_ according to the Baal Hatanya. 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.
+     * @return the `Date` of the latest _zman shema_ according to the Baal Hatanya. 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, an `Invalid Date` will be returned.
      */
     sofZmanShmaBaalHatanya() {
         return this.getShaahZmanisBaalHatanya(3);
     }
     /**
      * This method returns the latest _zman tfilah_ (time to recite the morning prayers). This time is 4
-     * hours into the day based on the opinion of the Baal Hatanya that the day is
-     * calculated from sunrise to sunset. This returns the time 4 * {@link getShaahZmanisBaalHatanya()} after
-     * {@link getSunriseBaalHatanya() _netz amiti_ (sunrise)}.
+     * halachic hours into the day, based on the opinion of the Baal Hatanya that the day is
+     * calculated from _netz amiti_ (sunrise) to _shkiah amiti_ (sunset).
      *
-     * @return the <code>Date</code> of the latest _zman tfilah_. 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.
+     * @return the `Date` of the latest _zman tfilah_. 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, an `Invalid Date` will be returned.
      */
     sofZmanTfilaBaalHatanya() {
         return this.getShaahZmanisBaalHatanya(4);
     }
     /**
      * This method returns the time of _mincha gedola_. _Mincha gedola_ is the earliest time one can pray
-     * _mincha_. The <a href="https://en.wikipedia.org/wiki/Maimonides">Rambam</a> is of the opinion that it is
-     * better to delay _mincha_ until {@link minchaKetanaBaalHatanya() _mincha ketana_} while the
-     * <a href="https://en.wikipedia.org/wiki/Asher_ben_Jehiel">Ra"sh</a>,
-     * <a href="https://en.wikipedia.org/wiki/Jacob_ben_Asher">Tur</a>, <a href=
-     * "https://en.wikipedia.org/wiki/Vilna_Gaon">GRA</a> and others are of the opinion that _mincha_ can be prayed
-     * _lechatchila_ starting at _mincha gedola_. This is calculated as 6.5 {@link getShaahZmanisBaalHatanya()
-     * sea level solar hours} after {@link getSunriseBaalHatanya() _netz amiti_ (sunrise)}. This calculation is based
-     * on the opinion of the Baal Hatanya that the day is calculated from sunrise to sunset. This returns the time 6.5
-     * * {@link getShaahZmanisBaalHatanya()} after {@link getSunriseBaalHatanya() _netz amiti_ ("real" sunrise)}.
-     * @return the <code>Date</code> of the time of _mincha gedola_ according to the Baal Hatanya. 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.
+     * _mincha_. The [Rambam](https://en.wikipedia.org/wiki/Maimonides) is of the opinion that it is
+     * better to delay _mincha_ until {@link minchaKetanaBaalHatanya | _mincha ketana_} while the
+     * [Ra"sh](https://en.wikipedia.org/wiki/Asher_ben_Jehiel),
+     * [Tur](https://en.wikipedia.org/wiki/Jacob_ben_Asher),
+     * [GRA](https://en.wikipedia.org/wiki/Vilna_Gaon) and others are of the opinion that _mincha_ can be prayed
+     * _lechatchila_ starting at _mincha gedola_. This is calculated as 6.5 sea level solar hours after
+     * _netz amiti_ (sunrise), based on the opinion of the Baal Hatanya that the day is calculated from
+     * _netz amiti_ (sunrise) to _shkiah amiti_ (sunset).
+     * @return the `Date` of the time of _mincha gedola_ according to the Baal Hatanya. 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, an `Invalid Date` will be returned.
      */
     minchaGedolaBaalHatanya() {
         return this.getShaahZmanisBaalHatanya(6.5);
     }
     /**
      * This method returns the time of _mincha ketana_. This is the preferred earliest time to pray
-     * _mincha_ in the opinion of the <a href="https://en.wikipedia.org/wiki/Maimonides">Rambam</a> and others.
-     * For more information on this see the documentation on {@link minchaGedolaBaalHatanya() _mincha gedola_}.
-     * This is calculated as 9.5 sea level solar hours after {@link getSunriseBaalHatanya
-     * _netz amiti_ (sunrise)}. This calculation is calculated based on the opinion of the Baal Hatanya that the
-     * day is calculated from sunrise to sunset. This returns the time 9.5 * after
-     * _netz amiti_ (sunrise).
+     * _mincha_ in the opinion of the [Rambam](https://en.wikipedia.org/wiki/Maimonides) and others.
+     * For more information on this see the documentation on {@link minchaGedolaBaalHatanya | _mincha gedola_}.
+     * This is calculated as 9.5 sea level solar hours after _netz amiti_ (sunrise), based on the opinion of
+     * the Baal Hatanya that the day is calculated from _netz amiti_ (sunrise) to _shkiah amiti_ (sunset).
      *
-     * @return the <code>Date</code> of the time of _mincha ketana_. 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.
+     * @return the `Date` of the time of _mincha ketana_. 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, an `Invalid Date` will be returned.
      */
     minchaKetanaBaalHatanya() {
         return this.getShaahZmanisBaalHatanya(9.5);
     }
     /**
-     * This method returns the time of _plag hamincha_. This is calculated as 10.75 hours after sunrise. This
-     * calculation is based on the opinion of the Baal Hatanya that the day is calculated
-     * from sunrise to sunset. This returns the time 10.75 * {@link getShaahZmanisBaalHatanya()} after
-     * {@link getSunriseBaalHatanya() _netz amiti_ (sunrise)}.
+     * This method returns the time of _plag hamincha_. This is calculated as 10.75 sea level solar hours
+     * after _netz amiti_ (sunrise), based on the opinion of the Baal Hatanya that the day is calculated
+     * from _netz amiti_ (sunrise) to _shkiah amiti_ (sunset).
      *
-     * @return the <code>Date</code> of the time of _plag hamincha_. 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.
+     * @return the `Date` of the time of _plag hamincha_ according to the Baal Hatanya. 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, an `Invalid Date` will be returned.
      */
     plagHaminchaBaalHatanya() {
         return this.getShaahZmanisBaalHatanya(10.75);
     }
     /**
-     * A method that returns _tzais_ (nightfall) when the sun is 6&deg; below the western geometric horizon
-     * (90&deg;) after {@link getSunset() sunset}. For information on the source of this calculation see
-     * {@link ZENITH_6_DEGREES}.
+     * A method that returns _tzais_ (nightfall) when the sun is 6° below the western geometric horizon
+     * (90°) after {@link sunset}. This is the time the Baal Hatanya calls _shkiah amiti_ plus the
+     * interval it takes the sun to descend a further 6°.
      *
-     * @return The <code>Date</code> of nightfall. If the calculation can't be computed such as northern and southern
-     *         locations even south of the Arctic Circle and north of the Antarctic Circle where the sun may not reach
-     *         low enough below the horizon for this calculation, a `null` will be returned.   * @see ZENITH_6_DEGREES
+     * @return the `Date` of nightfall. If the calculation can't be computed, such as in northern and southern
+     *         locations — even south of the Arctic Circle and north of the Antarctic Circle — where the sun may not
+     *         reach low enough below the horizon for this calculation, an `Invalid Date` will be returned.
      */
     tzaisBaalHatanya() {
         return this.timeAtAngle(6, false);
@@ -869,6 +901,9 @@ class Zmanim {
     /**
      * Uses timeFormat to return a date like '20:34'.
      * Returns `XX:XX` if the date is invalid.
+     * @param dt the time to format
+     * @param timeFormat formatter to use, e.g. from
+     *   {@link Location.getTimeFormatter}
      */
     static formatTime(dt, timeFormat) {
         if (isNaN(dt.getTime())) {
@@ -978,7 +1013,7 @@ class Zmanim {
      * (for example `2024-09-22T20:07`), this function would return a
      * Hebrew date of `20th of Elul, 5784`.
      * @example
-     * const {GeoLocation, Zmanim, HDate} = require('@hebcal/core');
+     * import {GeoLocation, Zmanim, HDate} from '@hebcal/core';
      * const latitude = 48.85341;
      * const longitude = 2.3488;
      * const timezone = 'Europe/Paris';