@hebcal/core 6.9.1 → 6.9.2

package/dist/bundle.js

@@ -1,9 +1,9 @@
-/*! @hebcal/core v6.9.1, distributed under GPLv2 https://www.gnu.org/licenses/gpl-2.0.txt */
+/*! @hebcal/core v6.9.2, distributed under GPLv2 https://www.gnu.org/licenses/gpl-2.0.txt */
 var hebcal = (function (exports) {
 'use strict';
 
 /** DO NOT EDIT THIS AUTO-GENERATED FILE! */
-const version = '6.9.1';
+const version = '6.9.2';
 
 /*! @hebcal/hdate v0.22.7, distributed under GPLv2 https://www.gnu.org/licenses/gpl-2.0.txt */
 /** @private */
@@ -8057,12 +8057,36 @@ class NOAACalculator {
      * @return {Temporal.ZonedDateTime | null} The Date.
      */
     getDateFromTime(time, isSunrise) {
-        if (isNaN(time)) {
+        const epochMillis = this.getEpochMillisFromTime(time, isSunrise);
+        if (isNaN(epochMillis)) {
             return null;
         }
+        return Temporal.Instant.fromEpochMilliseconds(epochMillis).toZonedDateTimeISO(this.geoLocation.getTimeZone());
+    }
+    /**
+     * The instant that {@link getDateFromTime} describes, as milliseconds since
+     * the epoch, without building a `Temporal.ZonedDateTime`.
+     *
+     * Constructing a `ZonedDateTime` costs roughly 750ns because the IANA zone
+     * has to be resolved, and that dominates this calculation. Callers that only
+     * want an instant — a `Date`, or the difference between two times — can skip
+     * it. Deriving the instant arithmetically also avoids a `PlainTime`
+     * allocation and turns the day rollover into a subtraction rather than a
+     * ~610ns `PlainDate.add({days})`.
+     *
+     * @param {number} time
+     *            The time in the format 18.75 for 6:45:00 PM, as returned by
+     *            {@link getUTCSunrise} / {@link getUTCSunset}, i.e. already
+     *            normalized to `[0, 24)`.
+     * @param {boolean} isSunrise true if the time is sunrise, and false if it is sunset
+     * @return {number} milliseconds since the epoch, or `NaN` if `time` is `NaN`
+     */
+    getEpochMillisFromTime(time, isSunrise) {
+        if (isNaN(time)) {
+            return NaN;
+        }
         let calculatedTime = time;
-        let cal = this.getAdjustedDate();
-        //    let cal = new Temporal.PlainDate(adj.year, adj.month, adj.day);
+        const cal = this.getAdjustedDate();
         const hours = Math.trunc(calculatedTime); // retain only the hours
         calculatedTime -= hours;
         const minutes = Math.trunc((calculatedTime *= 60)); // retain only the minutes
@@ -8072,19 +8096,24 @@ class NOAACalculator {
         // Check if a date transition has occurred, or is about to occur - this indicates the date of the event is
         // actually not the target date, but the day prior or after
         const localTimeHours = Math.trunc(this.geoLocation.getLongitude() / 15);
+        let dayOffset = 0;
         if (isSunrise && localTimeHours + hours > 18) {
-            cal = cal.add({ days: -1 });
-            //      cal = cal.minus({days: 1});
+            dayOffset = -1;
         }
         else if (!isSunrise && localTimeHours + hours < 6) {
-            cal = cal.add({ days: 1 });
+            dayOffset = 1;
+        }
+        const year = cal.year;
+        let millis = Date.UTC(year, cal.month - 1, cal.day, hours, minutes, seconds, Math.trunc(calculatedTime * 1000));
+        if (year >= 0 && year < 100) {
+            // Date.UTC() maps years 0-99 onto 1900-1999; setUTCFullYear() does not.
+            // Worth the branch (about 3ns): @hebcal/core computes candle-lighting
+            // times for early historical years rather than suppressing them.
+            const d = new Date(millis);
+            d.setUTCFullYear(year);
+            millis = d.getTime();
         }
-        return cal
-            .toZonedDateTime({
-            timeZone: 'UTC',
-            plainTime: new Temporal.PlainTime(hours, minutes, seconds, Math.trunc(calculatedTime * 1000)),
-        })
-            .withTimeZone(this.geoLocation.getTimeZone());
+        return millis + dayOffset * 86400000;
     }
     /**
      * Return the <a href="http://en.wikipedia.org/wiki/Julian_day">Julian day</a> from a Java Calendar
@@ -9724,13 +9753,17 @@ class MoladEvent extends Event {
 }
 
 /**
+ * Converts an instant to a `Date`, discarding milliseconds.
+ *
+ * Zmanim are read out to the minute, and every accessor here reduces to an
+ * instant, so we ask `@hebcal/noaa` for epoch milliseconds rather than a
+ * `Temporal.ZonedDateTime`. Resolving the IANA zone to build a
+ * `ZonedDateTime` costs roughly 750ns and nothing downstream uses it, which
+ * made it the single most expensive step in a sunrise/sunset calculation.
  * @private
  */
-function zdtToDate(zdt) {
-    if (zdt === null) {
-        return new Date(NaN);
-    }
-    const res = new Date(zdt.epochMilliseconds);
+function millisToDate(millis) {
+    const res = new Date(millis);
     res.setMilliseconds(0);
     return res;
 }
@@ -9747,6 +9780,20 @@ const GEOMETRIC_ZENITH = 90;
  * @see Zmanim.sunsetBaalHatanya
  */
 const ZENITH_1_POINT_583 = GEOMETRIC_ZENITH + 1.583;
+/**
+ * The zenith of civil twilight; the sun is 6° below the horizon.
+ * Matches `NOAACalculator.CIVIL_ZENITH`.
+ */
+const CIVIL_ZENITH = GEOMETRIC_ZENITH + 6;
+/**
+ * Length of one temporal (halachic) hour in milliseconds, i.e. one twelfth of
+ * the day. Mirrors `NOAACalculator.getTemporalHour()`, including its floor, so
+ * that results stay identical to the `ZonedDateTime` code path.
+ * @private
+ */
+function temporalHourMillis(startOfDay, endOfDay) {
+    return Math.floor((endOfDay - startOfDay) / 12);
+}
 /**
  * Calculate halachic times (zmanim / זְמַנִּים) for a given day and location.
  * Calculations are available for tzeit / tzais (nightfall),
@@ -9789,11 +9836,10 @@ class Zmanim {
     constructor(gloc, date, useElevation) {
         this.hdate = new HDate(date);
         const dt = isDate(date) ? date : this.hdate.greg();
-        this.plainDate = Temporal.PlainDate.from({
-            year: dt.getFullYear(),
-            month: dt.getMonth() + 1,
-            day: dt.getDate(),
-        });
+        // The constructor is ~1.8x cheaper than PlainDate.from(), which has to
+        // walk a property bag and apply overflow handling. The fields come from a
+        // real Date, so they are always in range and never need constraining.
+        this.plainDate = new Temporal.PlainDate(dt.getFullYear(), dt.getMonth() + 1, dt.getDate());
         this.gloc = gloc;
         this.noaa = new NOAACalculator(gloc, this.plainDate);
         this.useElevation = Boolean(useElevation);
@@ -9827,46 +9873,64 @@ class Zmanim {
      */
     timeAtAngle(angle, rising) {
         const offsetZenith = GEOMETRIC_ZENITH + angle;
-        const zdt = rising
-            ? this.noaa.getSunriseOffsetByDegrees(offsetZenith)
-            : this.noaa.getSunsetOffsetByDegrees(offsetZenith);
-        return zdtToDate(zdt);
+        return millisToDate(rising
+            ? this.sunriseMillis(offsetZenith, true)
+            : this.sunsetMillis(offsetZenith, true));
+    }
+    /**
+     * Sunrise for a given zenith as epoch milliseconds, mirroring what
+     * `NOAACalculator.getSunrise()` / `getSeaLevelSunrise()` /
+     * `getSunriseOffsetByDegrees()` compute, minus the `ZonedDateTime`.
+     *
+     * Note that noaa's degree-based accessors pass `adjustForElevation = true`
+     * as well; the adjustment is a no-op unless the zenith is exactly
+     * {@link GEOMETRIC_ZENITH}, which is why degree-based zmanim are unaffected
+     * by elevation.
+     * @private
+     */
+    sunriseMillis(zenith, useElevation) {
+        const utc = useElevation
+            ? this.noaa.getUTCSunrise0(zenith)
+            : this.noaa.getUTCSeaLevelSunrise(zenith);
+        return this.noaa.getEpochMillisFromTime(utc, true);
+    }
+    /**
+     * Sunset counterpart of {@link sunriseMillis}.
+     * @private
+     */
+    sunsetMillis(zenith, useElevation) {
+        const utc = useElevation
+            ? this.noaa.getUTCSunset0(zenith)
+            : this.noaa.getUTCSeaLevelSunset(zenith);
+        return this.noaa.getEpochMillisFromTime(utc, false);
     }
     /**
      * Upper edge of the Sun appears over the eastern horizon in the morning (0.833° above horizon)
      * If elevation is enabled, this function will include elevation in the calculation.
      */
     sunrise() {
-        const zdt = this.useElevation
-            ? this.noaa.getSunrise()
-            : this.noaa.getSeaLevelSunrise();
-        return zdtToDate(zdt);
+        return millisToDate(this.sunriseMillis(GEOMETRIC_ZENITH, this.useElevation));
     }
     /**
      * Upper edge of the Sun appears over the eastern horizon in the morning (0.833° above horizon).
      * This function does not support elevation adjustment.
      */
     seaLevelSunrise() {
-        const zdt = this.noaa.getSeaLevelSunrise();
-        return zdtToDate(zdt);
+        return millisToDate(this.sunriseMillis(GEOMETRIC_ZENITH, false));
     }
     /**
      * When the upper edge of the Sun disappears below the horizon (0.833° below horizon).
      * If elevation is enabled, this function will include elevation in the calculation.
      */
     sunset() {
-        const zdt = this.useElevation
-            ? this.noaa.getSunset()
-            : this.noaa.getSeaLevelSunset();
-        return zdtToDate(zdt);
+        return millisToDate(this.sunsetMillis(GEOMETRIC_ZENITH, this.useElevation));
     }
     /**
      * When the upper edge of the Sun disappears below the horizon (0.833° below horizon).
      * This function does not support elevation adjustment.
      */
     seaLevelSunset() {
-        const zdt = this.noaa.getSeaLevelSunset();
-        return zdtToDate(zdt);
+        return millisToDate(this.sunsetMillis(GEOMETRIC_ZENITH, false));
     }
     /**
      * Civil dawn; Sun is 6° below the horizon in the morning.
@@ -9874,8 +9938,7 @@ class Zmanim {
      * the result is not impacted by elevation.
      */
     dawn() {
-        const zdt = this.noaa.getBeginCivilTwilight();
-        return zdtToDate(zdt);
+        return millisToDate(this.sunriseMillis(CIVIL_ZENITH, true));
     }
     /**
      * Civil dusk; Sun is 6° below the horizon in the evening.
@@ -9883,8 +9946,7 @@ class Zmanim {
      * the result is not impacted by elevation.
      */
     dusk() {
-        const zdt = this.noaa.getEndCivilTwilight();
-        return zdtToDate(zdt);
+        return millisToDate(this.sunsetMillis(CIVIL_ZENITH, true));
     }
     /**
      * Returns sunset for the previous day.
@@ -9912,10 +9974,10 @@ class Zmanim {
      * `useElevation` setting.
      */
     chatzot() {
-        const startOfDay = this.noaa.getSeaLevelSunrise();
-        const endOfDay = this.noaa.getSeaLevelSunset();
-        const zdt = this.noaa.getSunTransit(startOfDay, endOfDay);
-        return zdtToDate(zdt);
+        const startOfDay = this.sunriseMillis(GEOMETRIC_ZENITH, false);
+        const endOfDay = this.sunsetMillis(GEOMETRIC_ZENITH, false);
+        // NOAACalculator.getSunTransit(): sunrise plus 6 temporal hours
+        return millisToDate(startOfDay + temporalHourMillis(startOfDay, endOfDay) * 6);
     }
     /**
      * Midnight – Chatzot; Sunset plus 6 halachic hours.
@@ -9969,25 +10031,18 @@ class Zmanim {
     misheyakirMachmir() {
         return this.timeAtAngle(10.2, true);
     }
-    getShaahZmanisBasedZmanZdt(startOfDay, endOfDay, hours) {
-        const temporalHour = this.noaa.getTemporalHour(startOfDay, endOfDay);
-        const offset = Math.trunc(temporalHour * hours);
-        const zdt = NOAACalculator.getTimeOffset(startOfDay, offset);
-        return zdt;
+    getShaahZmanisBasedZmanMillis(startOfDay, endOfDay, hours) {
+        const offset = Math.trunc(temporalHourMillis(startOfDay, endOfDay) * hours);
+        return startOfDay + offset;
     }
     /**
      * Utility method for using elevation-aware sunrise/sunset
      * @param hours number of _shaos zmaniyos_ (solar hours) after sunrise
      */
     getShaahZmanisBasedZman(hours) {
-        const startOfDay = this.useElevation
-            ? this.noaa.getSunrise()
-            : this.noaa.getSeaLevelSunrise();
-        const endOfDay = this.useElevation
-            ? this.noaa.getSunset()
-            : this.noaa.getSeaLevelSunset();
-        const zdt = this.getShaahZmanisBasedZmanZdt(startOfDay, endOfDay, hours);
-        return zdtToDate(zdt);
+        const startOfDay = this.sunriseMillis(GEOMETRIC_ZENITH, this.useElevation);
+        const endOfDay = this.sunsetMillis(GEOMETRIC_ZENITH, this.useElevation);
+        return millisToDate(this.getShaahZmanisBasedZmanMillis(startOfDay, endOfDay, hours));
     }
     /**
      * Latest Shema (Gra); Sunrise plus 3 halachic hours, according to the Gra.
@@ -10485,7 +10540,7 @@ class Zmanim {
      *         where it does not set, `null` will be returned.
      */
     getSunriseBaalHatanya() {
-        return this.noaa.getSunriseOffsetByDegrees(ZENITH_1_POINT_583);
+        return this.sunriseMillis(ZENITH_1_POINT_583, true);
     }
     /**
      * A method that returns the [Baal Hatanya](https://en.wikipedia.org/wiki/Shneur_Zalman_of_Liadi)'s
@@ -10508,7 +10563,7 @@ class Zmanim {
      *         rise, and one where it does not set, `null` will be returned.
      */
     getSunsetBaalHatanya() {
-        return this.noaa.getSunsetOffsetByDegrees(ZENITH_1_POINT_583);
+        return this.sunsetMillis(ZENITH_1_POINT_583, true);
     }
     /**
      * Returns the [Baal Hatanya](https://en.wikipedia.org/wiki/Shneur_Zalman_of_Liadi)'s _alos_
@@ -10530,8 +10585,7 @@ class Zmanim {
         return this.timeAtAngle(16.9, true);
     }
     getShaahZmanisBaalHatanya(hours) {
-        const zdt = this.getShaahZmanisBasedZmanZdt(this.getSunriseBaalHatanya(), this.getSunsetBaalHatanya(), hours);
-        return zdtToDate(zdt);
+        return millisToDate(this.getShaahZmanisBasedZmanMillis(this.getSunriseBaalHatanya(), this.getSunsetBaalHatanya(), hours));
     }
     /**
      * This method returns the latest _zman krias shema_ (time to recite Shema in the morning). This time is 3
@@ -10624,9 +10678,15 @@ class Zmanim {
             return 'XX:XX'; // Invalid Date
         }
         const time = timeFormat.format(dt);
-        const hm = time.split(':');
-        if (hm[0] === '24') {
-            return '00:' + hm[1];
+        // Rewrite the h24 midnight ("24:15") that some locales produce. Checking
+        // the two leading characters avoids the throwaway array that split(':')
+        // allocated on every event; this runs once per timed event, and the
+        // Intl.format() call above is already the expensive part.
+        if (time.charCodeAt(0) === 0x32 && // '2'
+            time.charCodeAt(1) === 0x34 && // '4'
+            time.charCodeAt(2) === 0x3a // ':'
+        ) {
+            return '00' + time.substring(2);
         }
         return time;
     }