@hebcal/core 5.3.11 → 5.3.13

package/dist/zmanim.d.ts

@@ -0,0 +1,321 @@
+/**
+ * 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 class Zmanim {
+    /**
+     * Uses timeFormat to return a date like '20:34'
+     * @param {Date} dt
+     * @param {Intl.DateTimeFormat} timeFormat
+     * @return {string}
+     */
+    static formatTime(dt: Date, timeFormat: Intl.DateTimeFormat): string;
+    /**
+     * Discards seconds, rounding to nearest minute.
+     * @param {Date} dt
+     * @return {Date}
+     */
+    static roundTime(dt: Date): Date;
+    /**
+     * Get offset string (like "+05:00" or "-08:00") from tzid (like "Europe/Moscow")
+     * @param {string} tzid
+     * @param {Date} date
+     * @return {string}
+     */
+    static timeZoneOffset(tzid: string, date: Date): string;
+    /**
+     * Returns a string like "2022-04-01T13:06:00-11:00"
+     * @param {string} tzid
+     * @param {Date} date
+     * @return {string}
+     */
+    static formatISOWithTimeZone(tzid: string, date: Date): string;
+    /**
+     * Initialize a Zmanim instance.
+     * @param {GeoLocation} gloc GeoLocation including latitude, longitude, and timezone
+     * @param {Date|HDate} date Regular or Hebrew Date. If `date` is a regular `Date`,
+     *    hours, minutes, seconds and milliseconds are ignored.
+     * @param {boolean} 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);
+    date: any;
+    gloc: GeoLocation;
+    noaa: NOAACalculator;
+    useElevation: boolean;
+    /**
+     * Returns `true` if elevation adjustment is enabled
+     * for zmanim support elevation adjustment
+     * @return {boolean}
+     */
+    getUseElevation(): boolean;
+    /**
+     * Enables or disables elevation adjustment for zmanim support elevation adjustment
+     * @param {boolean} 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 {number} angle
+     * @param {boolean} rising
+     * @return {Date}
+     */
+    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.
+     * @return {Date}
+     */
+    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.
+     * @return {Date}
+     */
+    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.
+     * @return {Date}
+     */
+    sunset(): Date;
+    /**
+     * When the upper edge of the Sun disappears below the horizon (0.833° below horizon).
+     * This function does not support elevation adjustment.
+     * @return {Date}
+     */
+    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.
+     * @return {Date}
+     */
+    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.
+     * @return {Date}
+     */
+    dusk(): Date;
+    /**
+     * Returns sunset for the previous day.
+     * If elevation is enabled, this function will include elevation in the calculation.
+     * @return {Date}
+     */
+    gregEve(): Date;
+    /**
+     * @private
+     * @return {number}
+     */
+    private nightHour;
+    /**
+     * Midday – Chatzot; Sunrise plus 6 halachic hours
+     * @return {Date}
+     */
+    chatzot(): Date;
+    /**
+     * Midnight – Chatzot; Sunset plus 6 halachic hours.
+     * If elevation is enabled, this function will include elevation in the calculation.
+     * @return {Date}
+     */
+    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.
+     * @return {Date}
+     */
+    alotHaShachar(): 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.
+     * @return {Date}
+     */
+    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.
+     * @return {Date}
+     */
+    misheyakirMachmir(): Date;
+    /**
+     * Utility method for using elevation-aware sunrise/sunset
+     * @private
+     * @param {number} hours
+     * @return {Date}
+     */
+    private getShaahZmanisBasedZman;
+    /**
+     * Latest Shema (Gra); Sunrise plus 3 halachic hours, according to the Gra.
+     * If elevation is enabled, this function will include elevation in the calculation.
+     * @return {Date}
+     */
+    sofZmanShma(): Date;
+    /**
+     * Latest Shacharit (Gra); Sunrise plus 4 halachic hours, according to the Gra.
+     * If elevation is enabled, this function will include elevation in the calculation.
+     * @return {Date}
+     */
+    sofZmanTfilla(): Date;
+    /**
+     * Returns an array with alot (Date) and ms in hour (number)
+     * @private
+     * @return {any[]}
+     */
+    private getTemporalHour72;
+    /**
+     * Returns an array with alot (Date) and ms in hour (number)
+     * @private
+     * @param {number} angle
+     * @return {any[]}
+     */
+    private getTemporalHourByDeg;
+    /**
+     * 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.
+     * @return {Date}
+     */
+    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.
+     * @return {Date}
+     */
+    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/
+     * @return {Date}
+     */
+    sofZmanShmaMGA19Point8(): Date;
+    /**
+     * Latest Shacharit (MGA); Sunrise plus 4 halachic hours, according to Magen Avraham
+     * @return {Date}
+     */
+    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.
+     * @return {Date}
+     */
+    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/
+     * @return {Date}
+     */
+    sofZmanTfillaMGA19Point8(): Date;
+    /**
+     * Earliest Mincha – Mincha Gedola; Sunrise plus 6.5 halachic hours.
+     * If elevation is enabled, this function will include elevation in the calculation.
+     * @return {Date}
+     */
+    minchaGedola(): 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.
+     * @return {Date}
+     */
+    minchaKetana(): Date;
+    /**
+     * Plag haMincha; Sunrise plus 10.75 halachic hours.
+     * If elevation is enabled, this function will include elevation in the calculation.
+     * @return {Date}
+     */
+    plagHaMincha(): Date;
+    /**
+     * @param {number} [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.
+     * @return {Date}
+     */
+    tzeit(angle?: number | undefined): Date;
+    /**
+     * Alias for sunrise
+     * @return {Date}
+     */
+    neitzHaChama(): Date;
+    /**
+     * Alias for sunset
+     * @return {Date}
+     */
+    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.
+     * @return {Date}
+     */
+    beinHaShmashos(): Date;
+    /**
+     * 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 {number} offset minutes
+     * @param {boolean} roundMinute round time to nearest minute (default true)
+     * @param {boolean} forceSeaLevel use sea-level sunrise (default false)
+     * @return {Date}
+     */
+    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 {number} offset minutes
+     * @param {boolean} roundMinute round time to nearest minute (default true)
+     * @param {boolean} forceSeaLevel use sea-level sunset (default false)
+     * @return {Date}
+     */
+    sunsetOffset(offset: number, roundMinute?: boolean, forceSeaLevel?: boolean): Date;
+}
+import { NOAACalculator } from '@hebcal/noaa';
+import { HDate } from './hdate.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hebcal/core",
-  "version": "5.3.11",
+  "version": "5.3.13",
   "author": "Michael J. Radwin (https://github.com/mjradwin)",
   "contributors": [
     "Eyal Schachter (https://github.com/Scimonster)",
@@ -27,9 +27,9 @@
   "exports": {
     "import": "./dist/index.mjs",
     "require": "./dist/index.cjs",
-    "types": "./hebcal.d.ts"
+    "types": "./dist/index.d.ts"
   },
-  "typings": "hebcal.d.ts",
+  "typings": "./dist/index.d.ts",
   "engines": {
     "node": ">= 16.0.0"
   },
@@ -42,12 +42,11 @@
   },
   "files": [
     "dist",
-    "hebcal.d.ts",
     "po"
   ],
   "scripts": {
     "build:rollup": "rollup -c",
-    "build": "npm run po2json && npm run version && npm run build:rollup",
+    "build": "npm run po2json && npm run version && npm run build:rollup --production",
     "prepublish": "npm run build",
     "po2json": "node ./po2json.cjs po/*.po",
     "version": "node ./version.cjs package.json src/pkgVersion.js",
@@ -74,13 +73,14 @@
     "@babel/core": "^7.24.5",
     "@babel/preset-env": "^7.24.5",
     "@babel/register": "^7.23.7",
-    "@hebcal/hdate": "^0.9.3",
+    "@hebcal/hdate": "^0.9.6",
     "@hebcal/noaa": "^0.8.14",
     "@rollup/plugin-babel": "^6.0.4",
-    "@rollup/plugin-commonjs": "^25.0.7",
+    "@rollup/plugin-commonjs": "^25.0.8",
     "@rollup/plugin-json": "^6.1.0",
     "@rollup/plugin-node-resolve": "^15.2.3",
     "@rollup/plugin-terser": "^0.4.4",
+    "@rollup/plugin-typescript": "^11.1.6",
     "ava": "^6.1.3",
     "core-js": "^3.37.1",
     "eslint": "^8.57.0",
@@ -89,7 +89,11 @@
     "jsdoc-to-markdown": "^8.0.1",
     "nyc": "^15.1.0",
     "quick-lru": "^7.0.0",
-    "rollup": "^4.17.2",
-    "ttag-cli": "^1.10.12"
+    "rollup": "^4.18.0",
+    "ttag-cli": "^1.10.12",
+    "typescript": "^5.4.5"
+  },
+  "dependencies": {
+    "tslib": "^2.6.2"
   }
 }