@hebcal/core

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; }