@hebcal/core 6.1.0 → 6.2.0

package/dist/zmanim.d.ts

@@ -1,460 +0,0 @@
-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 plainDate;
-    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;
-    alotHaShachar72zdt(): Temporal.ZonedDateTime | null;
-    /**
-     * 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;
-    tzeit72(): Temporal.ZonedDateTime | null;
-    /**
-     * 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;
-    /**
-     * Used by Molad based _zmanim_ to determine if _zmanim_ occur during the current day.
-     * @return previous midnight
-     */
-    private getMidnightLastNight;
-    /**
-     * Used by Molad based _zmanim_ to determine if _zmanim_ occur during the current day.
-     * @return following midnight
-     */
-    private getMidnightTonight;
-    /**
-     * Returns the Date of the _molad_ based time if it occurs on the current date. Since _Kiddush Levana_
-     * can only be said during the day, there are parameters to limit it to between _alos_ and _tzais_. If
-     * the time occurs between _alos_ and _tzais_, _tzais_ will be returned.
-     *
-     * @param moladBasedTime
-     *            the _molad_ based time such as _molad_, _tchilas_ and _sof zman Kiddush Levana_
-     * @param alos
-     *            optional start of day to limit _molad_ times to the end of the night before or beginning of the next night.
-     *            Ignored if either _alos_ or _tzais_ are null.
-     * @param tzais
-     *            optional end of day to limit _molad_ times to the end of the night before or beginning of the next night.
-     *            Ignored if either _tzais_ or _alos_ are null
-     * @param techila
-     *            is it the start of _Kiddush Levana_ time or the end? If it is start roll it to the next _tzais_,
-     *            and if it is the end, return the end of the previous night (_alos_ passed in). Ignored if either
-     *            _alos_ or _tzais_ are null.
-     * @return the _molad_ based time. If the _zman_ does not occur during the current date, <code>null</code> will be
-     *         returned.
-     */
-    private getMoladBasedTime;
-    private getHDate;
-    /**
-     * 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
-     * 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(Date, Date)}.
-     *
-     * @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 alos. If either the _alos_ or _tzais_ parameters
-     *            are null, no daytime adjustment will be made.
-     * @param tzais
-     *            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 <code>null</code> will be returned.
-     */
-    getSofZmanKidushLevanaBetweenMoldos(alos?: Temporal.ZonedDateTime | null, tzais?: Temporal.ZonedDateTime | null): Temporal.ZonedDateTime | null;
-    /**
-     * 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(Date, Date) 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(Date, Date)}.
-     *
-     * @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
-     *         <code>null</code> will be returned.
-     *
-     *
-     */
-    getSofZmanKidushLevana15Days(alos?: Temporal.ZonedDateTime | null, tzais?: Temporal.ZonedDateTime | null): Temporal.ZonedDateTime | null;
-    /**
-     * 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_.
-     * 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.
-     *
-     * @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 _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.
-     *
-     * @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
-     *         <code>null</code> will be returned.
-     */
-    getTchilasZmanKidushLevana3Days(alos?: Temporal.ZonedDateTime | null, tzais?: Temporal.ZonedDateTime | null): Temporal.ZonedDateTime | null;
-    /**
-     * 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
-     *         <code>null</code> will be returned.
-     *
-     */
-    getZmanMolad(): Temporal.ZonedDateTime | null;
-    /**
-     * 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(Date, Date)} if you want to limit the time to night hours.
-     *
-     * @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 <code>null</code> will be returned.
-     */
-    getTchilasZmanKidushLevana7Days(alos?: Temporal.ZonedDateTime | null, tzais?: Temporal.ZonedDateTime | null): Temporal.ZonedDateTime | null;
-    /**
-     * 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;
-}