@hebcal/core 6.0.5 → 6.0.7

package/dist/src/tachanun.js

@@ -0,0 +1,120 @@
+import { HDate, months } from '@hebcal/hdate';
+import { dateYomHaZikaron } from './modern';
+function range(start, end) {
+    const arr = [];
+    for (let i = start; i <= end; i++) {
+        arr.push(i);
+    }
+    return arr;
+}
+const NONE = {
+    shacharit: false,
+    mincha: false,
+    allCongs: false,
+};
+/**
+ * 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,
+ * Rosh Chodesh Sivan until Isru Chag, Tisha B'av, 15 Av, Erev Rosh Hashanah,
+ * Rosh Hashanah, Erev Yom Kippur until after Simchat Torah, Chanukah,
+ * Tu B'shvat, Purim and Shushan Purim, and Purim and Shushan Purim Katan.
+ *
+ * In some congregations Tachanun is not said until from Rosh Chodesh Sivan
+ * until 14th Sivan, Sukkot until after Rosh Chodesh Cheshvan, Pesach Sheini,
+ * Yom Ha'atzmaut, and Yom Yerushalayim.
+ *
+ * Tachanun is not said at Mincha on days before it is not said at Shacharit.
+ *
+ * Tachanun is not said at Shacharit on Shabbat, but is at Mincha, usually.
+ */
+export function tachanun(hdate, il) {
+    return tachanun0(hdate, il, true);
+}
+function tachanun0(hdate, il, checkNext) {
+    const year = hdate.yy;
+    const dates = tachanunYear(year, il);
+    const abs = hdate.abs();
+    if (dates.none.indexOf(abs) > -1) {
+        return NONE;
+    }
+    const dow = hdate.getDay();
+    const ret = {
+        shacharit: false,
+        mincha: false,
+        allCongs: false,
+    };
+    if (dates.some.indexOf(abs) === -1) {
+        ret.allCongs = true;
+    }
+    if (dow !== 6) {
+        ret.shacharit = true;
+    }
+    const tomorrow = abs + 1;
+    if (checkNext && dates.yesPrev.indexOf(tomorrow) === -1) {
+        const tmp = tachanun0(new HDate(tomorrow), il, false);
+        ret.mincha = tmp.shacharit;
+    }
+    else {
+        ret.mincha = dow !== 5;
+    }
+    if (ret.allCongs && !ret.mincha && !ret.shacharit) {
+        return NONE;
+    }
+    return ret;
+}
+function tachanunYear(year, il) {
+    const leap = HDate.isLeapYear(year);
+    const monthsInYear = HDate.monthsInYear(year);
+    let av9dt = new HDate(9, months.AV, year);
+    if (av9dt.getDay() === 6) {
+        av9dt = av9dt.next();
+    }
+    let shushPurim = new HDate(15, months.ADAR_II, year);
+    if (shushPurim.getDay() === 6) {
+        shushPurim = shushPurim.next();
+    }
+    const none = [
+        new HDate(2, months.TISHREI, year), // Rosh Hashana II
+    ].concat(
+    // Rosh Chodesh - 1st of every month. Also includes RH day 1 (1 Tishrei)
+    range(1, monthsInYear).map(month => new HDate(1, month, year)), 
+    // Rosh Chodesh - 30th of months that have one
+    range(1, monthsInYear)
+        .filter(month => HDate.daysInMonth(month, year) === 30)
+        .map(month => new HDate(30, month, year)), 
+    // entire month of Nisan
+    range(1, HDate.daysInMonth(months.NISAN, year)).map(mday => new HDate(mday, months.NISAN, year)), new HDate(18, months.IYYAR, year), // Lag BaOmer
+    // Rosh Chodesh Sivan thru Isru Chag
+    range(1, 8 - (il ? 1 : 0)).map(mday => new HDate(mday, months.SIVAN, year)), av9dt, // Tisha B'Av
+    new HDate(15, months.AV, year), // Tu B'Av
+    new HDate(29, months.ELUL, year), // Erev Rosh Hashanah
+    // Erev Yom Kippur thru Isru Chag
+    range(9, 24 - (il ? 1 : 0)).map(mday => new HDate(mday, months.TISHREI, year)), 
+    // Chanukah
+    range(25, 33).map(mday => new HDate(mday, months.KISLEV, year)), new HDate(15, months.SHVAT, year), // Tu BiShvat
+    new HDate(14, months.ADAR_II, year), // Purim
+    shushPurim, leap ? new HDate(14, months.ADAR_I, year) : [] // Purim Katan
+    );
+    const some = [
+        new HDate(14, months.IYYAR, year), // Pesach Sheini
+    ].concat(
+    // Until 14 Sivan
+    range(1, 13).map(mday => new HDate(mday, months.SIVAN, year)), 
+    // Until after Rosh Chodesh Cheshvan
+    range(20, 31).map(mday => new HDate(mday, months.TISHREI, year)), 
+    // Yom HaAtzma'ut, which changes based on day of week
+    year >= 5708 ? dateYomHaZikaron(year).next() : [], 
+    // Yom Yerushalayim
+    year >= 5727 ? new HDate(28, months.IYYAR, year) : []);
+    const yesPrev = [
+        new HDate(29, months.ELUL, year - 1), // Erev Rosh Hashanah
+        new HDate(9, months.TISHREI, year), // Erev Yom Kippur
+        new HDate(14, months.IYYAR, year), // Pesach Sheini
+    ];
+    return {
+        none: none.map(hd => hd.abs()).sort((a, b) => a - b),
+        some: some.map(hd => hd.abs()).sort((a, b) => a - b),
+        yesPrev: yesPrev.map(hd => hd.abs()).sort((a, b) => a - b),
+    };
+}

package/dist/src/zmanim.d.ts

@@ -0,0 +1,347 @@
+import 'temporal-polyfill/global';
+import { GeoLocation } from '@hebcal/noaa';
+import { HDate } from '@hebcal/hdate';
+/**
+ * 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 {GeoLocation, Zmanim} = require('@hebcal/core');
+ * const latitude = 41.822232;
+ * const longitude = -71.448292;
+ * const tzid = 'America/New_York';
+ * const friday = new Date(2023, 8, 8);
+ * const gloc = new GeoLocation(null, latitude, longitude, 0, tzid);
+ * const zmanim = new Zmanim(gloc, friday, false);
+ * const candleLighting = zmanim.sunsetOffset(-18, true);
+ * const timeStr = Zmanim.formatISOWithTimeZone(tzid, candleLighting);
+ */
+export declare class Zmanim {
+    private readonly date;
+    private readonly gloc;
+    private readonly noaa;
+    private useElevation;
+    /**
+     * Initialize a Zmanim instance.
+     * @param gloc GeoLocation including latitude, longitude, and timezone
+     * @param date Regular or Hebrew Date. If `date` is a regular `Date`,
+     *    hours, minutes, seconds and milliseconds are ignored.
+     * @param useElevation 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.
+     */
+    constructor(gloc: GeoLocation, date: Date | HDate, useElevation: boolean);
+    /**
+     * Returns `true` if elevation adjustment is enabled
+     * for zmanim support elevation adjustment
+     */
+    getUseElevation(): boolean;
+    /**
+     * Enables or disables elevation adjustment for zmanim support elevation adjustment
+     * @param useElevation
+     */
+    setUseElevation(useElevation: boolean): void;
+    /**
+     * 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
+     */
+    timeAtAngle(angle: number, rising: boolean): Date;
+    /**
+     * 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(): Date;
+    /**
+     * 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(): Date;
+    /**
+     * 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(): Date;
+    /**
+     * When the upper edge of the Sun disappears below the horizon (0.833° below horizon).
+     * This function does not support elevation adjustment.
+     */
+    seaLevelSunset(): Date;
+    /**
+     * Civil dawn; Sun is 6° below the horizon in the morning.
+     * Because degree-based functions estimate the amount of light in the sky,
+     * the result is not impacted by elevation.
+     */
+    dawn(): Date;
+    /**
+     * Civil dusk; Sun is 6° 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.
+     */
+    dusk(): Date;
+    /**
+     * Returns sunset for the previous day.
+     * If elevation is enabled, this function will include elevation in the calculation.
+     */
+    gregEve(): Date;
+    /**
+     * @private
+     */
+    nightHour(): number;
+    /**
+     * Midday – Chatzot; Sunrise plus 6 halachic hours
+     */
+    chatzot(): Date;
+    /**
+     * Midnight – Chatzot; Sunset plus 6 halachic hours.
+     * If elevation is enabled, this function will include elevation in the calculation.
+     */
+    chatzotNight(): Date;
+    /**
+     * Dawn – Alot haShachar; Sun is 16.1° below the horizon in the morning.
+     * Because degree-based functions estimate the amount of light in the sky,
+     * the result is not impacted by elevation.
+     */
+    alotHaShachar(): Date;
+    /**
+     * Dawn – Alot haShachar; calculated as 72 minutes before sunrise or
+     * sea level sunrise.
+     */
+    alotHaShachar72(): Date;
+    /**
+     * Earliest talis & tefillin – Misheyakir; Sun is 11.5° below the horizon in the morning.
+     * Because degree-based functions estimate the amount of light in the sky,
+     * the result is not impacted by elevation.
+     */
+    misheyakir(): Date;
+    /**
+     * Earliest talis & tefillin – Misheyakir Machmir; Sun is 10.2° below the horizon in the morning.
+     * Because degree-based functions estimate the amount of light in the sky,
+     * the result is not impacted by elevation.
+     */
+    misheyakirMachmir(): Date;
+    /**
+     * Utility method for using elevation-aware sunrise/sunset
+     * @private
+     * @param hours
+     */
+    getShaahZmanisBasedZman(hours: number): Date;
+    /**
+     * Latest Shema (Gra); Sunrise plus 3 halachic hours, according to the Gra.
+     * If elevation is enabled, this function will include elevation in the calculation.
+     */
+    sofZmanShma(): 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.
+     */
+    sofZmanTfilla(): Date;
+    /**
+     * Returns an array with alot (Date) and ms in hour (number)
+     * @private
+     */
+    getTemporalHour72(forceSeaLevel: boolean): [Date, number];
+    /**
+     * Returns an array with alot (Date) and ms in hour (number)
+     * @private
+     */
+    getTemporalHourByDeg(angle: number): [Date, number];
+    /**
+     * Latest Shema (MGA); Sunrise plus 3 halachic hours, according to Magen Avraham.
+     * Based on the opinion of the MGA that the day is calculated from
+     * dawn being fixed 72 minutes before sea-level sunrise, and nightfall is fixed
+     * 72 minutes after sea-level sunset.
+     */
+    sofZmanShmaMGA(): Date;
+    /**
+     * Latest Shema (MGA); Sunrise plus 3 halachic hours, according to Magen Avraham.
+     * Based on the opinion of the MGA that the day is calculated from
+     * dawn to nightfall with both being 16.1° below the horizon.
+     */
+    sofZmanShmaMGA16Point1(): Date;
+    /**
+     * Latest Shema (MGA); Sunrise plus 3 halachic hours, according to Magen Avraham.
+     * Based on the opinion of the MGA that the day is calculated from
+     * dawn to nightfall with both being 19.8° below the horizon.
+     *
+     * This calculation is based on the position of the sun 90 minutes after sunset in Jerusalem
+     * around the equinox / equilux which calculates to 19.8° below geometric zenith.
+     * https://kosherjava.com/2022/01/12/equinox-vs-equilux-zmanim-calculations/
+     */
+    sofZmanShmaMGA19Point8(): Date;
+    /**
+     * Latest Shacharit (MGA); Sunrise plus 4 halachic hours, according to Magen Avraham
+     */
+    sofZmanTfillaMGA(): Date;
+    /**
+     * Latest Shacharit (MGA); Sunrise plus 4 halachic hours, according to Magen Avraham.
+     * Based on the opinion of the MGA that the day is calculated from
+     * dawn to nightfall with both being 16.1° below the horizon.
+     */
+    sofZmanTfillaMGA16Point1(): Date;
+    /**
+     * Latest Shacharit (MGA); Sunrise plus 4 halachic hours, according to Magen Avraham.
+     * Based on the opinion of the MGA that the day is calculated from
+     * dawn to nightfall with both being 19.8° below the horizon.
+     *
+     * This calculation is based on the position of the sun 90 minutes after sunset in Jerusalem
+     * around the equinox / equilux which calculates to 19.8° below geometric zenith.
+     * https://kosherjava.com/2022/01/12/equinox-vs-equilux-zmanim-calculations/
+     */
+    sofZmanTfillaMGA19Point8(): Date;
+    /**
+     * 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*.
+     */
+    minchaGedola(): 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*.
+     */
+    minchaGedolaMGA(): Date;
+    /**
+     * 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).
+     */
+    minchaKetana(): 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.
+     */
+    minchaKetanaMGA(): Date;
+    /**
+     * Plag haMincha; Sunrise plus 10.75 halachic hours.
+     * If elevation is enabled, this function will include elevation in the calculation.
+     */
+    plagHaMincha(): Date;
+    /**
+     * @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.
+     * Because degree-based functions estimate the amount of light in the sky,
+     * the result is not impacted by elevation.
+     */
+    tzeit(angle?: number): Date;
+    /**
+     * Alias for sunrise
+     */
+    neitzHaChama(): Date;
+    /**
+     * Alias for sunset
+     */
+    shkiah(): Date;
+    /**
+     * Rabbeinu Tam holds that bein hashmashos is a specific time
+     * between sunset and tzeis hakochavim.
+     * One opinion on how to calculate this time is that
+     * it is 13.5 minutes before tzies 7.083.
+     * Because degree-based functions estimate the amount of light in the sky,
+     * the result is not impacted by elevation.
+     */
+    beinHaShmashos(): Date;
+    /**
+     * Uses timeFormat to return a date like '20:34'.
+     * Returns `XX:XX` if the date is invalid.
+     */
+    static formatTime(dt: Date, timeFormat: Intl.DateTimeFormat): string;
+    /**
+     * Discards seconds, rounding to nearest minute.
+     * @param dt
+     */
+    static roundTime(dt: Date): Date;
+    /**
+     * Get offset string (like "+05:00" or "-08:00") from tzid (like "Europe/Moscow")
+     * @param tzid
+     * @param date
+     */
+    static timeZoneOffset(tzid: string, date: Date): string;
+    /**
+     * Returns a string like "2022-04-01T13:06:00-11:00"
+     * @param tzid
+     * @param date
+     */
+    static formatISOWithTimeZone(tzid: string, date: Date): string;
+    /**
+     * Returns sunrise + `offset` minutes (either positive or negative).
+     * If elevation is enabled, this function will include elevation in the calculation
+     *  unless `forceSeaLevel` is `true`.
+     * @param offset minutes
+     * @param roundMinute round time to nearest minute (default true)
+     * @param forceSeaLevel use sea-level sunrise (default false)
+     */
+    sunriseOffset(offset: number, roundMinute?: boolean, forceSeaLevel?: boolean): Date;
+    /**
+     * Returns sunset + `offset` minutes (either positive or negative).
+     * If elevation is enabled, this function will include elevation in the calculation
+     *  unless `forceSeaLevel` is `true`.
+     * @param offset minutes
+     * @param roundMinute round time to nearest minute (default true)
+     * @param forceSeaLevel use sea-level sunset (default false)
+     */
+    sunsetOffset(offset: number, roundMinute?: boolean, forceSeaLevel?: boolean): Date;
+    /**
+     * Returns the Hebrew date relative to the specified location and Gregorian date,
+     * taking into consideration whether the time is before or after sunset.
+     *
+     * For example, if the given date and is `2024-09-22T10:35` (before sunset), and
+     * sunset for the specified location is **19:04**, then this function would
+     * return a Hebrew date of `19th of Elul, 5784`.
+     * If the given date is the same Gregorian day after sunset
+     * (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');
+     * const latitude = 48.85341;
+     * const longitude = 2.3488;
+     * const timezone = 'Europe/Paris';
+     * const gloc = new GeoLocation(null, latitude, longitude, 0, timezone);
+     * const before = Zmanim.makeSunsetAwareHDate(gloc, new Date('2024-09-22T17:38:46.123Z'), false);
+     * console.log(before.toString()); // '19 Elul 5784'
+     * const after = Zmanim.makeSunsetAwareHDate(gloc, new Date('2024-09-22T23:45:18.345Z'), false);
+     * console.log(after.toString()); // '20 Elul 5784'
+     */
+    static makeSunsetAwareHDate(gloc: GeoLocation, date: Date, useElevation: boolean): HDate;
+}