@hebcal/core 4.4.1 → 4.5.1

package/dist/index.mjs

@@ -1,4 +1,4 @@
-/*! @hebcal/core v4.4.1 */
+/*! @hebcal/core v4.5.1 */
 /*
  * More minimal greg routines
  */
@@ -1571,6 +1571,7 @@ class HDate {
           case 'h':
             return months.SHVAT;
         }
+        break;
       case 't':
         switch (c[1]) {
           case 'a':
@@ -2433,7 +2434,30 @@ function pad2(number) {
  * @property {Date} tzeit
 */
 
-/** Class representing halachic times */
+/**
+ * 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
+ *
+ * @example
+ * const {Zmanim} = require('@hebcal/core');
+ * const latitude = 41.822232;
+ * const longitude = -71.448292;
+ * const friday = new Date(2023, 8, 8);
+ * const zmanim = new Zmanim(friday, latitude, longitude);
+ * const candleLighting = zmanim.sunsetOffset(-18, true);
+ * const timeStr = Zmanim.formatISOWithTimeZone('America/New_York', candleLighting);
+ */
 class Zmanim {
   /**
      * Initialize a Zmanim instance.
@@ -2483,6 +2507,16 @@ class Zmanim {
       tzeit: this.tzeit()
     };
   }
+  /**
+   * Convenience function to get the time when sun is above or below the horizon
+   * for a certain angle (in degrees).
+   * @param {number} angle
+   * @param {boolean} rising
+   * @return {Date}
+   */
+  timeAtAngle(angle, rising) {
+    return this.sun.timeAtAngle(angle, rising);
+  }
   /**
    * Upper edge of the Sun appears over the eastern horizon in the morning (0.833° above horizon)
    * @return {Date}
@@ -2639,7 +2673,7 @@ class Zmanim {
   }
   /**
    * @param {number} [angle=8.5] optional time for solar depression.
-   *   Default is 8.5 degrees for 3 small stars, use 7.083 degress for 3 medium-sized stars.
+   *   Default is 8.5 degrees for 3 small stars, use 7.083 degrees for 3 medium-sized stars.
    * @return {Date}
    */
   tzeit(angle = 8.5) {
@@ -2786,7 +2820,7 @@ class Zmanim {
    * Returns an array with tzeit Date object and a 24-hour string formatted time.
    * @deprecated
    * @param {number} angle degrees for solar depression.
-   *   Default is 8.5 degrees for 3 small stars, use 7.083 degress for 3 medium-sized stars.
+   *   Default is 8.5 degrees for 3 small stars, use 7.083 degrees for 3 medium-sized stars.
    * @param {Intl.DateTimeFormat} timeFormat
    * @return {Object[]}
    */
@@ -3119,17 +3153,6 @@ const days = {
   SAT: 6
 };
 
-/**
- * @private
- * @constant
- * This method returns the tzais (nightfall) based on the opinion of the
- * Geonim calculated as 30 minutes after sunset during the equinox
- * (on March 16, about 4 days before the astronomical equinox, the day that
- * a solar hour is 60 minutes) in Yerushalayim.
- * @see {https://kosherjava.com/zmanim/docs/api/com/kosherjava/zmanim/ComplexZmanimCalendar.html#getTzaisGeonim7Point083Degrees()}
- */
-const TZEIT_3MEDIUM_STARS = 7.083;
-
 /**
  * @private
  * @param {Event} e
@@ -3289,10 +3312,10 @@ class CandleLightingEvent extends TimedEvent {
  * Makes a pair of events representing fast start and end times
  * @private
  * @param {Event} ev
- * @param {Location} location
+ * @param {CalOptions} options
  * @return {Event}
  */
-function makeFastStartEnd(ev, location) {
+function makeFastStartEnd(ev, options) {
   const desc = ev.getDesc();
   if (desc === 'Yom Kippur') {
     return ev;
@@ -3300,17 +3323,19 @@ function makeFastStartEnd(ev, location) {
   ev = ev.clone();
   const hd = ev.getDate();
   const dt = hd.greg();
+  const location = options.location;
+  const fastEndDeg = options.fastEndDeg;
   const zmanim = new Zmanim(dt, location.getLatitude(), location.getLongitude());
   if (desc === 'Erev Tish\'a B\'Av') {
     const sunset = zmanim.sunset();
     ev.startEvent = makeTimedEvent(hd, sunset, 'Fast begins', ev, location);
   } else if (desc.startsWith('Tish\'a B\'Av')) {
-    ev.endEvent = makeTimedEvent(hd, zmanim.tzeit(TZEIT_3MEDIUM_STARS), 'Fast ends', ev, location);
+    ev.endEvent = makeTimedEvent(hd, zmanim.tzeit(fastEndDeg), 'Fast ends', ev, location);
   } else {
     const dawn = zmanim.alotHaShachar();
     ev.startEvent = makeTimedEvent(hd, dawn, 'Fast begins', ev, location);
     if (dt.getDay() !== 5 && !(hd.getDate() === 14 && hd.getMonth() === months.NISAN)) {
-      ev.endEvent = makeTimedEvent(hd, zmanim.tzeit(TZEIT_3MEDIUM_STARS), 'Fast ends', ev, location);
+      ev.endEvent = makeTimedEvent(hd, zmanim.tzeit(fastEndDeg), 'Fast ends', ev, location);
     }
   }
   return ev;
@@ -5235,7 +5260,7 @@ function getBirthdayOrAnniversary_(hyear, gdate) {
   return new HDate(day, month, hyear);
 }
 
-const version="4.4.1";
+const version="4.5.1";
 
 const headers$1={"plural-forms":"nplurals=2; plural=(n > 1);"};const contexts$1={"":{Shabbat:["Shabbos"],"Achrei Mot":["Achrei Mos"],Bechukotai:["Bechukosai"],"Beha'alotcha":["Beha'aloscha"],Bereshit:["Bereshis"],Chukat:["Chukas"],"Erev Shavuot":["Erev Shavuos"],"Erev Sukkot":["Erev Sukkos"],"Ki Tavo":["Ki Savo"],"Ki Teitzei":["Ki Seitzei"],"Ki Tisa":["Ki Sisa"],Matot:["Matos"],"Purim Katan":["Purim Koton"],"Shabbat Chazon":["Shabbos Chazon"],"Shabbat HaChodesh":["Shabbos HaChodesh"],"Shabbat HaGadol":["Shabbos HaGadol"],"Shabbat Nachamu":["Shabbos Nachamu"],"Shabbat Parah":["Shabbos Parah"],"Shabbat Shekalim":["Shabbos Shekalim"],"Shabbat Shuva":["Shabbos Shuvah"],"Shabbat Zachor":["Shabbos Zachor"],Shavuot:["Shavuos"],"Shavuot I":["Shavuos I"],"Shavuot II":["Shavuos II"],Shemot:["Shemos"],"Shmini Atzeret":["Shmini Atzeres"],"Simchat Torah":["Simchas Torah"],Sukkot:["Sukkos"],"Sukkot I":["Sukkos I"],"Sukkot II":["Sukkos II"],"Sukkot II (CH''M)":["Sukkos II (CH''M)"],"Sukkot III (CH''M)":["Sukkos III (CH''M)"],"Sukkot IV (CH''M)":["Sukkos IV (CH''M)"],"Sukkot V (CH''M)":["Sukkos V (CH''M)"],"Sukkot VI (CH''M)":["Sukkos VI (CH''M)"],"Sukkot VII (Hoshana Raba)":["Sukkos VII (Hoshana Raba)"],"Ta'anit Bechorot":["Ta'anis Bechoros"],"Ta'anit Esther":["Ta'anis Esther"],Toldot:["Toldos"],Vaetchanan:["Vaeschanan"],Yitro:["Yisro"],"Vezot Haberakhah":["Vezos Haberakhah"],Parashat:["Parshas"],"Leil Selichot":["Leil Selichos"],"Shabbat Mevarchim Chodesh":["Shabbos Mevorchim Chodesh"],"Shabbat Shirah":["Shabbos Shirah"],Tevet:["Teves"],"Asara B'Tevet":["Asara B'Teves"],"Alot HaShachar":["Alos HaShachar"],"Kriat Shema, sof zeman":["Krias Shema, sof zman"],"Tefilah, sof zeman":["Tefilah, sof zman"],"Kriat Shema, sof zeman (MGA)":["Krias Shema, sof zman (MGA)"],"Tefilah, sof zeman (MGA)":["Tefilah, sof zman (MGA)"],"Chatzot HaLailah":["Chatzos HaLailah"],"Chatzot hayom":["Chatzos"],"Tzeit HaKochavim":["Tzeis HaKochavim"],"Birkat Hachamah":["Birkas Hachamah"],"Shushan Purim Katan":["Shushan Purim Koton"]}};var poAshkenazi = {headers:headers$1,contexts:contexts$1};
 
@@ -5478,11 +5503,15 @@ const MAJOR_FAST = flags.MAJOR_FAST;
 const ROSH_CHODESH = flags.ROSH_CHODESH;
 const PARSHA_HASHAVUA = flags.PARSHA_HASHAVUA;
 const DAF_YOMI = flags.DAF_YOMI;
+const MISHNA_YOMI = flags.MISHNA_YOMI;
+const NACH_YOMI = flags.NACH_YOMI;
+const YERUSHALMI_YOMI = flags.YERUSHALMI_YOMI;
 const OMER_COUNT = flags.OMER_COUNT;
 const SHABBAT_MEVARCHIM = flags.SHABBAT_MEVARCHIM;
 const MINOR_HOLIDAY = flags.MINOR_HOLIDAY;
 const EREV = flags.EREV;
 const CHOL_HAMOED = flags.CHOL_HAMOED;
+const YOM_KIPPUR_KATAN = flags.YOM_KIPPUR_KATAN;
 const unrecognizedAlreadyWarned = Object.create(null);
 const RECOGNIZED_OPTIONS = {
   location: 1,
@@ -5496,6 +5525,7 @@ const RECOGNIZED_OPTIONS = {
   candleLightingMins: 1,
   havdalahMins: 1,
   havdalahDeg: 1,
+  fastEndDeg: 1,
   sedrot: 1,
   il: 1,
   noMinorFast: 1,
@@ -5559,6 +5589,27 @@ const geoIdCandleOffset = {
   '293067': 30 // Zikhron Yaakov
 };
 
+/**
+ * @private
+ * @constant
+ * This calculation is based on the position of the sun 36 minutes after sunset in Jerusalem
+ * around the equinox / equilux, which is 8.5° below geometric zenith.
+ * The Ohr Meir considers this the time that 3 small stars are visible,
+ * which is later than the required 3 medium stars.
+ * @see {https://kosherjava.com/zmanim/docs/api/com/kosherjava/zmanim/ZmanimCalendar.html#ZENITH_8_POINT_5}
+ */
+const TZEIT_3SMALL_STARS = 8.5;
+
+/**
+ * @private
+ * @constant
+ * This calculation is based on observation of 3 medium sized stars by Dr. Baruch Cohen
+ * in his calendar published in in 1899 in Strasbourg, France.
+ * This calculates to 7.0833333° below geometric zenith.
+ * @see {https://kosherjava.com/zmanim/docs/api/com/kosherjava/zmanim/ComplexZmanimCalendar.html#ZENITH_7_POINT_083}
+ */
+const TZEIT_3MEDIUM_STARS = 7.0833333;
+
 /**
  * Modifies options in-place
  * @private
@@ -5593,7 +5644,10 @@ function checkCandleOptions(options) {
   } else if (typeof options.havdalahDeg === 'number') {
     options.havdalahDeg = Math.abs(options.havdalahDeg);
   } else {
-    options.havdalahDeg = 8.5;
+    options.havdalahDeg = TZEIT_3SMALL_STARS;
+  }
+  if (typeof options.fastEndDeg !== 'number') {
+    options.fastEndDeg = TZEIT_3MEDIUM_STARS;
   }
 }
 
@@ -5612,10 +5666,14 @@ function checkCandleOptions(options) {
  * @property {number} havdalahMins - 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 supressed.
+ *      the naked eye). If `0`, Havdalah times are suppressed.
  * @property {number} havdalahDeg - degrees for solar depression for Havdalah.
- *      Default is 8.5 degrees for 3 small stars. use 7.083 degress for 3 medium-sized stars.
- *      If `0`, Havdalah times are supressed.
+ *      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.
+ * @property {number} fastEndDeg - 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.
  * @property {boolean} sedrot - calculate parashah hashavua on Saturdays
  * @property {boolean} il - Israeli holiday and sedra schedule
  * @property {boolean} noMinorFast - suppress minor fasts
@@ -5738,33 +5796,7 @@ function getStartAndEnd(options) {
 function getMaskFromOptions(options) {
   var _options$location;
   if (typeof options.mask === 'number') {
-    const m = options.mask;
-    if (m & ROSH_CHODESH) delete options.noRoshChodesh;
-    if (m & MODERN_HOLIDAY) delete options.noModern;
-    if (m & MINOR_FAST) delete options.noMinorFast;
-    if (m & SPECIAL_SHABBAT) delete options.noSpecialShabbat;
-    if (m & PARSHA_HASHAVUA) options.sedrot = true;
-    if (m & DAF_YOMI) {
-      options.dailyLearning = options.dailyLearning || {};
-      options.dailyLearning.dafYomi = true;
-    }
-    if (m & OMER_COUNT) options.omer = true;
-    if (m & SHABBAT_MEVARCHIM) options.shabbatMevarchim = true;
-    if (m & flags.MISHNA_YOMI) {
-      options.dailyLearning = options.dailyLearning || {};
-      options.dailyLearning.mishnaYomi = true;
-    }
-    if (m & flags.NACH_YOMI) {
-      options.dailyLearning = options.dailyLearning || {};
-      options.dailyLearning.nachYomi = true;
-    }
-    if (m & flags.YOM_KIPPUR_KATAN) options.yomKippurKatan = true;
-    if (m & flags.YERUSHALMI_YOMI) {
-      options.dailyLearning = options.dailyLearning || {};
-      options.dailyLearning.yerushalmi = 1;
-    }
-    options.userMask = true;
-    return m;
+    return setOptionsFromMask(options);
   }
   const il = options.il || ((_options$location = options.location) === null || _options$location === void 0 ? void 0 : _options$location.il) || false;
   let mask = 0;
@@ -5806,7 +5838,7 @@ function getMaskFromOptions(options) {
     mask |= SHABBAT_MEVARCHIM;
   }
   if (options.yomKippurKatan) {
-    mask |= flags.YOM_KIPPUR_KATAN;
+    mask |= YOM_KIPPUR_KATAN;
   }
   if (options.dailyLearning) {
     const dailyLearning = options.dailyLearning;
@@ -5814,13 +5846,13 @@ function getMaskFromOptions(options) {
       mask |= DAF_YOMI;
     }
     if (dailyLearning.mishnaYomi) {
-      mask |= flags.MISHNA_YOMI;
+      mask |= MISHNA_YOMI;
     }
     if (dailyLearning.nachYomi) {
-      mask |= flags.NACH_YOMI;
+      mask |= NACH_YOMI;
     }
     if (dailyLearning.yerushalmi) {
-      mask |= flags.YERUSHALMI_YOMI;
+      mask |= YERUSHALMI_YOMI;
     }
   }
   return mask;
@@ -5842,6 +5874,40 @@ const hour12cc = {
   ZA: 1
 };
 
+/**
+ * @private
+ * @param {CalOptions} options
+ * @return {number}
+ */
+function setOptionsFromMask(options) {
+  const m = options.mask;
+  if (m & ROSH_CHODESH) delete options.noRoshChodesh;
+  if (m & MODERN_HOLIDAY) delete options.noModern;
+  if (m & MINOR_FAST) delete options.noMinorFast;
+  if (m & SPECIAL_SHABBAT) delete options.noSpecialShabbat;
+  if (m & PARSHA_HASHAVUA) options.sedrot = true;
+  if (m & (DAF_YOMI | MISHNA_YOMI | NACH_YOMI | YERUSHALMI_YOMI)) {
+    options.dailyLearning = options.dailyLearning || {};
+    if (m & DAF_YOMI) {
+      options.dailyLearning.dafYomi = true;
+    }
+    if (m & MISHNA_YOMI) {
+      options.dailyLearning.mishnaYomi = true;
+    }
+    if (m & NACH_YOMI) {
+      options.dailyLearning.nachYomi = true;
+    }
+    if (m & YERUSHALMI_YOMI) {
+      options.dailyLearning.yerushalmi = 1;
+    }
+  }
+  if (m & OMER_COUNT) options.omer = true;
+  if (m & SHABBAT_MEVARCHIM) options.shabbatMevarchim = true;
+  if (m & YOM_KIPPUR_KATAN) options.yomKippurKatan = true;
+  options.userMask = true;
+  return m;
+}
+
 /**
  * @private
  * @param {Event} ev
@@ -5928,10 +5994,10 @@ class HebrewCalendar {
    * These defaults can be changed using these options:
    * * `options.candleLightingMins` - minutes before sundown to light candles
    * * `options.havdalahMins` - minutes after sundown for Havdalah (typical values are 42, 50, or 72).
-   *    Havdalah times are supressed when `options.havdalahMins=0`.
+   *    Havdalah times are suppressed when `options.havdalahMins=0`.
    * * `options.havdalahDeg` - degrees for solar depression for Havdalah.
-   *    Default is 8.5 degrees for 3 small stars. Use 7.083 degress for 3 medium-sized stars.
-   *    Havdalah times are supressed when `options.havdalahDeg=0`.
+   *    Default is 8.5 degrees for 3 small stars. Use 7.083 degrees for 3 medium-sized stars.
+   *    Havdalah times are suppressed when `options.havdalahDeg=0`.
    *
    * If both `options.candlelighting=true` and `options.location` is specified,
    * Chanukah candle-lighting times and minor fast start/end times will also be generated.
@@ -6334,7 +6400,7 @@ function appendHolidayAndRelated(events, ev, options, candlesEv, dow) {
   }
 
   const eFlags = ev.getFlags();
-  if (!options.yomKippurKatan && eFlags & flags.YOM_KIPPUR_KATAN || options.noModern && eFlags & MODERN_HOLIDAY) {
+  if (!options.yomKippurKatan && eFlags & YOM_KIPPUR_KATAN || options.noModern && eFlags & MODERN_HOLIDAY) {
     return candlesEv; // bail out early
   }
 
@@ -6342,7 +6408,7 @@ function appendHolidayAndRelated(events, ev, options, candlesEv, dow) {
   const isMajorFast = Boolean(eFlags & MAJOR_FAST);
   const isMinorFast = Boolean(eFlags & MINOR_FAST);
   if (options.candlelighting && (isMajorFast || isMinorFast)) {
-    ev = makeFastStartEnd(ev, location);
+    ev = makeFastStartEnd(ev, options);
     if (ev.startEvent && (isMajorFast || isMinorFast && !options.noMinorFast)) {
       events.push(ev.startEvent);
     }
@@ -6366,7 +6432,7 @@ function appendHolidayAndRelated(events, ev, options, candlesEv, dow) {
         candlesEv = undefined;
       }
     }
-    if (!options.noHolidays || options.yomKippurKatan && eFlags & flags.YOM_KIPPUR_KATAN) {
+    if (!options.noHolidays || options.yomKippurKatan && eFlags & YOM_KIPPUR_KATAN) {
       events.push(ev); // the original event itself
     }
   }

package/hebcal.d.ts

@@ -41,31 +41,58 @@ declare module '@hebcal/core' {
      * Holiday flags for Event
      */
     export const enum flags {
-        CHAG,
-        LIGHT_CANDLES,
-        YOM_TOV_ENDS,
-        CHUL_ONLY,
-        IL_ONLY,
-        LIGHT_CANDLES_TZEIS,
-        CHANUKAH_CANDLES,
-        ROSH_CHODESH,
-        MINOR_FAST,
-        SPECIAL_SHABBAT,
-        PARSHA_HASHAVUA,
-        DAF_YOMI,
-        OMER_COUNT,
-        MODERN_HOLIDAY,
-        MAJOR_FAST,
-        SHABBAT_MEVARCHIM,
-        MOLAD,
-        USER_EVENT,
-        HEBREW_DATE,
-        MINOR_HOLIDAY,
-        EREV,
-        CHOL_HAMOED,
-        MISHNA_YOMI,
-        YERUSHALMI_YOMI,
-        NACH_YOMI,
+        /** Chag, yontiff, yom tov */
+        CHAG = 0x000001,
+        /** Light candles 18 minutes before sundown */
+        LIGHT_CANDLES = 0x000002,
+        /** End of holiday (end of Yom Tov)  */
+        YOM_TOV_ENDS = 0x000004,
+        /** Observed only in the Diaspora (chutz l'aretz)  */
+        CHUL_ONLY = 0x000008,
+        /** Observed only in Israel */
+        IL_ONLY = 0x000010,
+        /** Light candles in the evening at Tzeit time (3 small stars) */
+        LIGHT_CANDLES_TZEIS = 0x000020,
+        /** Candle-lighting for Chanukah */
+        CHANUKAH_CANDLES = 0x000040,
+        /** Rosh Chodesh, beginning of a new Hebrew month */
+        ROSH_CHODESH = 0x000080,
+        /** Minor fasts like Tzom Tammuz, Ta'anit Esther, ... */
+        MINOR_FAST = 0x000100,
+        /** Shabbat Shekalim, Zachor, ... */
+        SPECIAL_SHABBAT = 0x000200,
+        /** Weekly sedrot on Saturdays */
+        PARSHA_HASHAVUA = 0x000400,
+        /** Daily page of Talmud (Bavli) */
+        DAF_YOMI = 0x000800,
+        /** Days of the Omer */
+        OMER_COUNT = 0x001000,
+        /** Yom HaShoah, Yom HaAtzma'ut, ... */
+        MODERN_HOLIDAY = 0x002000,
+        /** Yom Kippur and Tish'a B'Av */
+        MAJOR_FAST = 0x004000,
+        /** On the Saturday before Rosh Chodesh */
+        SHABBAT_MEVARCHIM = 0x008000,
+        /** Molad */
+        MOLAD = 0x010000,
+        /** Yahrzeit or Hebrew Anniversary */
+        USER_EVENT = 0x020000,
+        /** Daily Hebrew date ("11th of Sivan, 5780") */
+        HEBREW_DATE = 0x040000,
+        /** A holiday that's not major, modern, rosh chodesh, or a fast day */
+        MINOR_HOLIDAY = 0x080000,
+        /** Evening before a major or minor holiday */
+        EREV = 0x100000,
+        /** Chol haMoed, intermediate days of Pesach or Sukkot */
+        CHOL_HAMOED = 0x200000,
+        /** Mishna Yomi */
+        MISHNA_YOMI = 0x400000,
+        /** Yom Kippur Katan, minor day of atonement on the day preceeding each Rosh Chodesh */
+        YOM_KIPPUR_KATAN = 0x800000,
+        /** Daily page of Jerusalem Talmud (Yerushalmi) */
+        YERUSHALMI_YOMI = 0x1000000,
+        /** Nach Yomi */
+        NACH_YOMI = 0x2000000,
     }
 
     export type UnitTypeShort = 'd' | 'w' | 'M' | 'y';
@@ -306,7 +333,7 @@ declare module '@hebcal/core' {
         /**
          * @deprecated
          * @param [angle=8.5] optional time for solar depression.
-         *   Default is 8.5 degrees for 3 small stars, use 7.083 degress for 3 medium-sized stars.
+         *   Default is 8.5 degrees for 3 small stars, use 7.083 degrees for 3 medium-sized stars.
          */
         tzeit(hdate: Date | HDate, angle?: number): Date;
         /**
@@ -361,12 +388,19 @@ declare module '@hebcal/core' {
     }
 
     /**
-     * Class representing halachic times
+     * 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.
      */
     export class Zmanim {
         /**
          * Initialize a Zmanim instance
-         * @param date Regular or Hebrew Date
+         * @param date Regular or Hebrew Date. If `date` is a regular `Date`,
+         *    hours, minutes, seconds and milliseconds are ignored
          * @param latitude
          * @param longitude
          */
@@ -389,6 +423,12 @@ declare module '@hebcal/core' {
          */
         static timeZoneOffset(tzid: string, date: Date): string;
 
+        /**
+         * Convenience function to get the time when sun is above or below the
+         * horizon for a certain angle (in degrees).
+         */
+        timeAtAngle(angle: number, rising: boolean): Date;
+
         /** @deprecated */
         suntime(): ZmanimTimesResult;
         /** Upper edge of the Sun appears over the eastern horizon in the morning (0.833° above horizon) */
@@ -431,7 +471,7 @@ declare module '@hebcal/core' {
         plagHaMincha(): Date;
         /**
          * @param [angle=8.5] optional time for solar depression.
-         *   Default is 8.5 degrees for 3 small stars, use 7.083 degress for 3 medium-sized stars.
+         *   Default is 8.5 degrees for 3 small stars, use 7.083 degrees for 3 medium-sized stars.
          */
         tzeit(angle?: number): Date;
         /** Alias for sunrise */
@@ -459,7 +499,7 @@ declare module '@hebcal/core' {
          * Returns an array with tzeit Date object and a 24-hour string formatted time.
          * @deprecated
          * @param angle optional time for solar depression.
-         *   Default is 8.5 degrees for 3 small stars, use 7.083 degress for 3 medium-sized stars.
+         *   Default is 8.5 degrees for 3 small stars, use 7.083 degrees for 3 medium-sized stars.
          */
         tzeitTime(angle: number, timeFormat: Intl.DateTimeFormat): any[];
     }
@@ -577,16 +617,24 @@ declare module '@hebcal/core' {
          * 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 supressed.
+         * the naked eye). If `0`, Havdalah times are suppressed.
          */
         havdalahMins?: number;
         /**
          * degrees for solar depression for Havdalah.
          * Default is 8.5 degrees for 3 small stars.
-         * Use 7.083 degress for 3 medium-sized stars.
-         * Havdalah times are supressed when `havdalahDeg=0`.
+         * Use 7.083 degrees for 3 medium-sized stars (as observed by Dr. Baruch
+         * (Berthold) Cohn in his luach published in France in 1899).
+         * Havdalah times are suppressed when `havdalahDeg=0`.
          */
         havdalahDeg?: number;
+        /**
+         * fastEndDeg - degrees for solar depression for end of fast days.
+         * Default is 7.083 degrees for 3 medium-sized stars. Another
+         * commonly-used value is 6.45 degrees, as calculated by Rabbi
+         * Yechiel Michel Tucazinsky.
+         */
+        fastEndDeg?: number;
         /** calculate parashah hashavua on Saturdays */
         sedrot?: boolean;
         /** Israeli holiday and sedra schedule */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hebcal/core",
-  "version": "4.4.1",
+  "version": "4.5.1",
   "author": "Michael J. Radwin (https://github.com/mjradwin)",
   "contributors": [
     "Eyal Schachter (https://github.com/Scimonster)",
@@ -40,7 +40,6 @@
   ],
   "scripts": {
     "build:rollup": "rollup -c",
-    "build:babel": "babel src --out-dir dist --source-maps",
     "build": "npm run po2json && npm run build:rollup",
     "prepublish": "npm run build",
     "po2json": "node ./po2json.js po/*.po",
@@ -71,13 +70,13 @@
     "@rollup/plugin-node-resolve": "^15.2.3",
     "@rollup/plugin-terser": "^0.4.4",
     "ava": "^5.3.1",
-    "core-js": "^3.33.0",
-    "eslint": "^8.51.0",
+    "core-js": "^3.33.2",
+    "eslint": "^8.53.0",
     "eslint-config-google": "^0.14.0",
     "jsdoc": "^4.0.2",
     "jsdoc-to-markdown": "^8.0.0",
     "nyc": "^15.1.0",
-    "rollup": "^4.1.4",
+    "rollup": "^4.3.0",
     "ttag-cli": "^1.10.6"
   }
 }