adhan - npm Package Compare versions

Comparing version 4.2.1 to 4.3.0

Adhan.d.ts

@@ -21,12 +21,62 @@ export as namespace adhan;
 
+  /**
+   * Name of the method, can be used to apply special behavior in calculations.
+   */
   readonly method: string;
+
+  /**
+   * Angle of the sun below the horizon used for calculating Fajr.
+   */
   fajrAngle: number;
+
+  /**
+   * Angle of the sun below the horizon used for calculating Isha.
+   */
   ishaAngle: number;
+
+  /**
+   * Minutes after Maghrib to determine time for Isha,
+   * if this value is greater than 0 then ishaAngle is not used.
+   */
   ishaInterval: number;
+
+  /**
+   * Angle of the sun below the horizon used for calculating Maghrib.
+   * Only used by the Tehran method to account for lightness in the sky.
+   */
   maghribAngle: number;
+
+  /**
+   * Madhab to determine how Asr is calculated.
+   */
   madhab: Madhab;
+
+  /**
+   * Rule to determine the earliest time for Fajr and latest time for Isha
+   * needed for high latitude locations where Fajr and Isha may not truly exist
+   * or may present a hardship unless bound to a reasonable time.
+   */
   highLatitudeRule: HighLatitudeRule;
+
+  /**
+   * Manual adjustments (in minutes) to be added to each prayer time.
+   */
   adjustments: PrayerAdjustments;
+
+  /**
+   * Rule to determine how to resolve prayer times inside the Polar Circle
+   * where daylight or night may persist for more than 24 hours depending
+   * on the season.
+   */
   polarCircleResolution: PolarCircleResolution;
+
+  /**
+   * How seconds are rounded for prayer times.
+   */
   rounding: Rounding;
+
+  /**
+   * Used by the MoonsightingCommittee method to determine how to calculate Isha
+   */
+  shafaq: Shafaq;
 }
@@ -103,2 +153,24 @@
 
+/**
+ * Shafaq is the twilight in the sky. Different madhabs define the appearance of
+ * twilight differently. These values are used by the MoonsightingComittee method
+ * for the different ways to calculate Isha.
+ */
+export enum Shafaq {
+  /**
+   * General is a combination of Ahmer and Abyad.
+   */
+  General,
+
+  /**
+   * Ahmer means the twilight is the red glow in the sky. Used by the Shafi, Maliki, and Hanbali madhabs.
+   */
+  Ahmer,
+
+  /**
+   * Abyad means the twilight is the white glow in the sky. Used by the Hanafi madhab.
+   */
+  Abyad
+}
+
 export enum PolarCircleResolution {
@@ -105,0 +177,0 @@ AqrabBalad,

Adhan.js

@@ -184,2 +184,14 @@ (function webpackUniversalModuleDefinition(root, factory) {
 }
+// CONCATENATED MODULE: ./src/Shafaq.js
+// Shafaq is the twilight in the sky. Different madhabs define the appearance of
+// twilight differently. These values are used by the MoonsightingComittee method
+// for the different ways to calculate Isha.
+const Shafaq = {
+  // General is a combination of Ahmer and Abyad.
+  General: 'general',
+  // Ahmer means the twilight is the red glow in the sky. Used by the Shafi, Maliki, and Hanbali madhabs.
+  Ahmer: 'ahmer',
+  // Abyad means the twilight is the white glow in the sky. Used by the Hanafi madhab.
+  Abyad: 'abyad'
+};
 // CONCATENATED MODULE: ./src/Astronomical.js
@@ -189,2 +201,3 @@ /* eslint-disable max-params, max-lines */
 
+
 const Astronomical = {
@@ -484,8 +497,22 @@ /* The geometric mean longitude of the sun in degrees. */
 
-  seasonAdjustedEveningTwilight(latitude, dayOfYear, year, sunset) {
-    const a = 75 + 25.60 / 55.0 * Math.abs(latitude);
-    const b = 75 + 2.050 / 55.0 * Math.abs(latitude);
-    const c = 75 - 9.210 / 55.0 * Math.abs(latitude);
-    const d = 75 + 6.140 / 55.0 * Math.abs(latitude);
+  seasonAdjustedEveningTwilight(latitude, dayOfYear, year, sunset, shafaq) {
+    let a, b, c, d;
 
+    if (shafaq === Shafaq.Ahmer) {
+      a = 62 + 17.40 / 55.0 * Math.abs(latitude);
+      b = 62 - 7.160 / 55.0 * Math.abs(latitude);
+      c = 62 + 5.120 / 55.0 * Math.abs(latitude);
+      d = 62 + 19.44 / 55.0 * Math.abs(latitude);
+    } else if (shafaq === Shafaq.Abyad) {
+      a = 75 + 25.60 / 55.0 * Math.abs(latitude);
+      b = 75 + 7.160 / 55.0 * Math.abs(latitude);
+      c = 75 + 36.84 / 55.0 * Math.abs(latitude);
+      d = 75 + 81.84 / 55.0 * Math.abs(latitude);
+    } else {
+      a = 75 + 25.60 / 55.0 * Math.abs(latitude);
+      b = 75 + 2.050 / 55.0 * Math.abs(latitude);
+      c = 75 - 9.210 / 55.0 * Math.abs(latitude);
+      d = 75 + 6.140 / 55.0 * Math.abs(latitude);
+    }
+
     const adjustment = function () {
@@ -817,3 +844,3 @@ const dyy = Astronomical.daysSinceSolstice(dayOfYear, year, latitude);
         if (calculationParameters.method === "MoonsightingCommittee") {
-          return src_Astronomical.seasonAdjustedEveningTwilight(coordinates.latitude, DateUtils_dayOfYear(date), date.getFullYear(), sunsetTime);
+          return src_Astronomical.seasonAdjustedEveningTwilight(coordinates.latitude, DateUtils_dayOfYear(date), date.getFullYear(), sunsetTime, calculationParameters.shafaq);
         } else {
@@ -939,11 +966,25 @@ const portion = calculationParameters.nightPortions().isha;
 
+
 class CalculationParameters_CalculationParameters {
   constructor(methodName, fajrAngle, ishaAngle, ishaInterval, maghribAngle) {
-    this.method = methodName || "Other";
-    this.fajrAngle = fajrAngle || 0;
-    this.ishaAngle = ishaAngle || 0;
-    this.ishaInterval = ishaInterval || 0;
-    this.maghribAngle = maghribAngle;
-    this.madhab = Madhab.Shafi;
-    this.highLatitudeRule = src_HighLatitudeRule.MiddleOfTheNight;
+    // Name of the method, can be used to apply special behavior in calculations.
+    // This property should not be manually modified.
+    this.method = methodName || "Other"; // Angle of the sun below the horizon used for calculating Fajr.
+
+    this.fajrAngle = fajrAngle || 0; // Angle of the sun below the horizon used for calculating Isha.
+
+    this.ishaAngle = ishaAngle || 0; // Minutes after Maghrib to determine time for Isha
+    // if this value is greater than 0 then ishaAngle is not used.
+
+    this.ishaInterval = ishaInterval || 0; // Angle of the sun below the horizon used for calculating Maghrib.
+    // Only used by the Tehran method to account for lightness in the sky.
+
+    this.maghribAngle = maghribAngle; // Madhab to determine how Asr is calculated.
+
+    this.madhab = Madhab.Shafi; // Rule to determine the earliest time for Fajr and latest time for Isha
+    // needed for high latitude locations where Fajr and Isha may not truly exist
+    // or may present a hardship unless bound to a reasonable time.
+
+    this.highLatitudeRule = src_HighLatitudeRule.MiddleOfTheNight; // Manual adjustments (in minutes) to be added to each prayer time.
+
     this.adjustments = {
@@ -956,3 +997,4 @@ fajr: 0,
       isha: 0
-    };
+    }; // Adjustments set by a calculation method. This value should not be manually modified.
+
     this.methodAdjustments = {
@@ -965,5 +1007,11 @@ fajr: 0,
       isha: 0
-    };
-    this.polarCircleResolution = PolarCircleResolution.Unresolved;
-    this.rounding = Rounding.Nearest;
+    }; // Rule to determine how to resolve prayer times inside the Polar Circle
+    // where daylight or night may persist for more than 24 hours depending
+    // on the season
+
+    this.polarCircleResolution = PolarCircleResolution.Unresolved; // How seconds are rounded when calculating prayer times
+
+    this.rounding = Rounding.Nearest; // Used by the MoonsightingCommittee method to determine how to calculate Isha
+
+    this.shafaq = Shafaq.General;
   }
@@ -970,0 +1018,0 @@

CHANGELOG.md

@@ -0,1 +1,8 @@
+# [4.3.0](https://github.com/batoulapps/adhan-js/compare/v4.2.1...v4.3.0) (2021-12-24)
+
+
+### Features
+
+* **calculation params:** adds shafaq parameter ([4c62bdf](https://github.com/batoulapps/adhan-js/commit/4c62bdf8094cd4df5d459884eccd83258d4f06d8)), closes [#78](https://github.com/batoulapps/adhan-js/issues/78)
+
 ## [4.2.1](https://github.com/batoulapps/adhan-js/compare/v4.2.0...v4.2.1) (2021-06-18)
@@ -2,0 +9,0 @@

METHODS.md

@@ -18,2 +18,3 @@ # Calculation Parameters Guide
 | fajrAngle | Angle of the sun used to calculate Fajr |
+| maghribAngle | Angle of the sun used to calculate Maghrib (this is used by the Tehran method) |
 | ishaAngle | Angle of the sun used to calculate Isha |
@@ -25,2 +26,3 @@ | ishaInterval | Minutes after Maghrib (if set, the time for Isha will be Maghrib plus ishaInterval) |
 | polarCircleResolution | Value from the PolarCircleResolution object, strategy used to resolve undefined prayer times for areas located in polar circles  |
+| shafaq | Used by the MoonsightingCommittee method to determine how to calculate Isha. See explanation of values below. |
 
@@ -68,2 +70,12 @@ #### CalculationMethod
 | adhan.PolarCircleResolution.AqrabYaum | Finds the closest date (forward or backward) for which sunrise and sunset prayer times can be computed |
-| adhan.PolarCircleResolution.Unresolved | (default) Leaves sunrise and sunset prayer times `undefined` when they can't be computed  |
+| adhan.PolarCircleResolution.Unresolved | (default) Leaves sunrise and sunset prayer times `undefined` when they can't be computed  |
+
+#### Shafaq
+
+Shafaq is used by the MoonsightingCommittee method to determine what type of twilight to use in order to determine the time for Isha.
+
+| Value | Description |
+| ----- | ----------- |
+| adhan.Shafaq.General | General is a combination of Ahmer and Abyad. This is the defualt value and will provide more reasonable times for locations at higher latitudes. |
+| adhan.Shafaq.Ahmer | Ahmer means the twilight is the red glow in the sky. Used by the Shafi, Maliki, and Hanbali madhabs. This generally produces an earlier Isha time. |
+| adhan.Shafaq.Abyad | Abyad means the twilight is the white glow in the sky. Used by the Hanafi madhab. This generally produces a later Isha time. |

package.json

 {
   "name": "adhan",
-  "version": "4.2.1",
+  "version": "4.3.0",
   "description": "High precision Islamic prayer time library",
@@ -12,3 +12,3 @@ "main": "Adhan.js",
     "test:unit": "jest",
-    "test:audit": "npm audit --audit-level=high",
+    "test:audit": "npm audit --production --audit-level=high",
     "test-watch": "jest --watch",
@@ -15,0 +15,0 @@ "coverage": "codecov",

src/Astronomical.js

 /* eslint-disable max-params, max-lines */
 import { degreesToRadians, radiansToDegrees, unwindAngle, normalizeToScale, quadrantShiftAngle } from './MathUtils';
 import { dateByAddingSeconds } from './DateUtils';
+import { Shafaq } from './Shafaq';
 
@@ -287,7 +288,20 @@ const Astronomical = {
 
-    seasonAdjustedEveningTwilight(latitude, dayOfYear, year, sunset) {
-        const a = 75 + ((25.60 / 55.0) * Math.abs(latitude));
-        const b = 75 + ((2.050 / 55.0) * Math.abs(latitude));
-        const c = 75 - ((9.210 / 55.0) * Math.abs(latitude));
-        const d = 75 + ((6.140 / 55.0) * Math.abs(latitude));
+    seasonAdjustedEveningTwilight(latitude, dayOfYear, year, sunset, shafaq) {
+        let a, b, c, d;
+        if (shafaq === Shafaq.Ahmer) {
+            a = 62 + ((17.40 / 55.0) * Math.abs(latitude));
+            b = 62 - ((7.160 / 55.0) * Math.abs(latitude));
+            c = 62 + ((5.120 / 55.0) * Math.abs(latitude));
+            d = 62 + ((19.44 / 55.0) * Math.abs(latitude));
+        } else if (shafaq === Shafaq.Abyad) {
+            a = 75 + ((25.60 / 55.0) * Math.abs(latitude));
+            b = 75 + ((7.160 / 55.0) * Math.abs(latitude));
+            c = 75 + ((36.84 / 55.0) * Math.abs(latitude));
+            d = 75 + ((81.84 / 55.0) * Math.abs(latitude));
+        } else {
+            a = 75 + ((25.60 / 55.0) * Math.abs(latitude));
+            b = 75 + ((2.050 / 55.0) * Math.abs(latitude));
+            c = 75 - ((9.210 / 55.0) * Math.abs(latitude));
+            d = 75 + ((6.140 / 55.0) * Math.abs(latitude));
+        }
 
@@ -294,0 +308,0 @@ const adjustment = (function() {

src/CalculationParameters.js

@@ -5,16 +5,48 @@ import { Madhab } from './Madhab';
 import { Rounding } from './Rounding';
+import { Shafaq } from './Shafaq';
 
 export default class CalculationParameters {
     constructor(methodName, fajrAngle, ishaAngle, ishaInterval, maghribAngle) {
+        // Name of the method, can be used to apply special behavior in calculations.
+        // This property should not be manually modified.
         this.method = methodName || "Other";
+
+        // Angle of the sun below the horizon used for calculating Fajr.
         this.fajrAngle = fajrAngle || 0;
+
+        // Angle of the sun below the horizon used for calculating Isha.
         this.ishaAngle = ishaAngle || 0;
+
+        // Minutes after Maghrib to determine time for Isha
+        // if this value is greater than 0 then ishaAngle is not used.
         this.ishaInterval = ishaInterval || 0;
+
+        // Angle of the sun below the horizon used for calculating Maghrib.
+        // Only used by the Tehran method to account for lightness in the sky.
         this.maghribAngle = maghribAngle;
+
+        // Madhab to determine how Asr is calculated.
         this.madhab = Madhab.Shafi;
+
+        // Rule to determine the earliest time for Fajr and latest time for Isha
+        // needed for high latitude locations where Fajr and Isha may not truly exist
+        // or may present a hardship unless bound to a reasonable time.
         this.highLatitudeRule = HighLatitudeRule.MiddleOfTheNight;
+
+        // Manual adjustments (in minutes) to be added to each prayer time.
         this.adjustments = { fajr: 0, sunrise: 0, dhuhr: 0, asr: 0, maghrib: 0, isha: 0 };
+
+        // Adjustments set by a calculation method. This value should not be manually modified.
         this.methodAdjustments = { fajr: 0, sunrise: 0, dhuhr: 0, asr: 0, maghrib: 0, isha: 0 };
+
+        // Rule to determine how to resolve prayer times inside the Polar Circle
+        // where daylight or night may persist for more than 24 hours depending
+        // on the season
         this.polarCircleResolution = PolarCircleResolution.Unresolved;
+
+        // How seconds are rounded when calculating prayer times
         this.rounding = Rounding.Nearest;
+
+        // Used by the MoonsightingCommittee method to determine how to calculate Isha
+        this.shafaq = Shafaq.General;
     }
@@ -21,0 +53,0 @@

src/PrayerTimes.js

@@ -100,3 +100,3 @@ import SolarTime from './SolarTime';
                 if (calculationParameters.method === "MoonsightingCommittee") {
-                    return Astronomical.seasonAdjustedEveningTwilight(coordinates.latitude, dayOfYear(date), date.getFullYear(), sunsetTime);
+                    return Astronomical.seasonAdjustedEveningTwilight(coordinates.latitude, dayOfYear(date), date.getFullYear(), sunsetTime, calculationParameters.shafaq);
                 }
@@ -103,0 +103,0 @@ else {

No alert changes

Improved metrics

Total package byte prevSize

206669

6.26%

Number of package files

37

2.78%

Lines of code

2165

6.86%

No dependency changes