mihrab-methods 0.0.0-stage → 1.0.0

package/dist/cjs/methods/indonesia.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.kemenagRawMinutes = kemenagRawMinutes;
+exports.kemenagTimes = kemenagTimes;
+/**
+ * Indonesia — the Ministry of Religious Affairs' (Kemenag) method, as its
+ * timetable is computed.
+ *
+ * Read off its table for all 517 regencies and cities (October–December
+ * 2026):
+ *
+ *   • the precise apparent Sun (`preciseApparentSun`, as JPL's to a tenth
+ *     of a second), taken at each prayer's own moment, iterated — Meeus's
+ *     shorter series drifts by a second and left a minute in two hundred
+ *     off;
+ *   • Fajr 20°, Isha 18°; sunrise and Maghrib at −1°, and at −2° in the
+ *     regencies the ministry classes as highland — in six highland
+ *     regencies of Papua the degree is taken off Fajr and Isha too;
+ *   • Asr when the shadow is its length plus the noon shadow, the noon
+ *     shadow from the Sun's declination at 00:00 UT of the day (as an
+ *     almanac's daily entry gives it), the hour angle from the Sun at Asr;
+ *   • every time rounded up, after a margin of two minutes (three for
+ *     Dhuhr, minus three for sunrise).
+ *
+ * At each regency's own point (fitted to the table; Karawang's afternoon
+ * at a second one) this gives the ministry's minute for 99.969 % of its
+ * times, and never a minute further; the rest are within about a second
+ * of a minute's edge, with no pattern a model could take
+ * (`data/corrections/indonesia.json` has them).
+ */
+const preciseSun_js_1 = require("../sun/preciseSun.js");
+const RAD = Math.PI / 180;
+const DAY_MS = 86_400_000;
+const ITERATIONS = 3;
+const MARGIN = { fajr: 2, sunrise: -3, dhuhr: 3, asr: 2, maghrib: 2, isha: 2 };
+const ASR_ITERATIONS = 4;
+/** Exact times with the margins, minutes past 00:00 UT of the civil date, before rounding. */
+function kemenagRawMinutes(latitude, longitude, year, month, day, opts = {}) {
+    const d0 = (Date.UTC(year, month, day) - Date.UTC(2000, 0, 1)) / DAY_MS - 0.5;
+    const at = (t) => (0, preciseSun_js_1.preciseApparentSun)(d0 + t / 1440);
+    let noon = 720 - 4 * longitude;
+    for (let i = 0; i < ITERATIONS; i++)
+        noon = 720 - 4 * longitude - at(noon).eot;
+    const sp = Math.sin(latitude * RAD);
+    const cp = Math.cos(latitude * RAD);
+    const hourAngle = (alt, dec) => {
+        const c = (Math.sin(alt * RAD) - sp * Math.sin(dec)) / (cp * Math.cos(dec));
+        return Math.abs(c) <= 1 ? (4 * Math.acos(c)) / RAD : NaN;
+    };
+    const event = (alt, sign, start) => {
+        let t = start;
+        for (let i = 0; i < ITERATIONS; i++) {
+            const { dec, eot } = at(t);
+            t = 720 - 4 * longitude - eot + sign * hourAngle(alt, dec);
+            if (!Number.isFinite(t))
+                return NaN;
+        }
+        return t;
+    };
+    const twilight = opts.twilightDip ? 1 : 0;
+    const horizon = opts.highland ? -2 : -1;
+    // The noon shadow from the declination at 00:00 UT; the hour angle from the Sun at Asr, iterated.
+    const shadowDec = at(0).dec;
+    const asrAlt = Math.atan(1 / ((opts.asrShadow ?? 1) + Math.tan(Math.abs(latitude * RAD - shadowDec)))) / RAD;
+    let asr = noon + 200;
+    for (let i = 0; i < ASR_ITERATIONS; i++) {
+        const { dec, eot } = at(asr);
+        asr = 720 - 4 * longitude - eot + hourAngle(asrAlt, dec);
+    }
+    return {
+        fajr: event(-20 - twilight, -1, noon - 420) + MARGIN.fajr,
+        sunrise: event(horizon, -1, noon - 360) + MARGIN.sunrise,
+        dhuhr: noon + MARGIN.dhuhr,
+        asr: asr + MARGIN.asr,
+        maghrib: event(horizon, 1, noon + 360) + MARGIN.maghrib,
+        isha: event(-18 - twilight, 1, noon + 420) + MARGIN.isha,
+    };
+}
+/** The ministry's times for a point and civil date (month 0-based), on the minute; null where one does not form. */
+function kemenagTimes(latitude, longitude, year, month, day, opts = {}) {
+    const r = kemenagRawMinutes(latitude, longitude, year, month, day, opts);
+    if (opts.afternoon) {
+        const pm = kemenagRawMinutes(opts.afternoon[0], opts.afternoon[1], year, month, day, opts);
+        r.asr = pm.asr;
+        r.maghrib = pm.maghrib;
+        r.isha = pm.isha;
+    }
+    const all = [r.fajr, r.sunrise, r.dhuhr, r.asr, r.maghrib, r.isha];
+    if (!all.every(Number.isFinite))
+        return null;
+    const start = Date.UTC(year, month, day);
+    const at = (m) => new Date(start + Math.ceil(m - 1e-9) * 60_000);
+    return { fajr: at(r.fajr), sunrise: at(r.sunrise), dhuhr: at(r.dhuhr), asr: at(r.asr), maghrib: at(r.maghrib), isha: at(r.isha) };
+}

package/dist/cjs/methods/morocco.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Morocco — the Ministry of Habous and Islamic Affairs's method, as its
+ * timetable is computed (issue #10).
+ *
+ * Read off 77 days of the ministry's tables for its 164 located cities:
+ *
+ *   • a precise Sun — Meeus's apparent Sun with the full nutation and his
+ *     chapter-28 equation of time; a JPL ephemeris fits no better, NOAA's
+ *     and the Almanac's series far worse — taken at each prayer's own
+ *     moment (iterated), declination and equation of time alike;
+ *   • Fajr 19°, Isha 17°, Asr one shadow length (Shafi'i);
+ *   • Dhuhr five minutes after the transit;
+ *   • sunrise 2.85 minutes before, and Maghrib 3.7 after, the Sun's upper
+ *     limb on the horizon — refraction 34′ and the Sun's semi-diameter for
+ *     its distance that day — less the city's own horizon dip;
+ *   • Fajr rounded down to the minute, the rest to the nearest.
+ *
+ * The dip is the ministry's own per city and per side — the horizon east
+ * at sunrise, west at Maghrib, which mountains or the sea make different —
+ * fitted from its tables with the city's point (`data/moroccoMethodPoints.json`,
+ * about 0.02° per √metre of height); elsewhere 0.02°·√height, 0.86 of it at
+ * Maghrib. On 77 days of the ministry's tables for its 164 located cities
+ * this is its printed minute for 99.12 % of times, and never further than
+ * one; `data/corrections/morocco.json` holds the rest.
+ */
+export type MoroccoInstants = {
+    fajr: Date;
+    sunrise: Date;
+    dhuhr: Date;
+    asr: Date;
+    maghrib: Date;
+    isha: Date;
+};
+/** Meeus's apparent Sun at `d` days from J2000.0: declination (rad), equation of time (minutes). */
+export declare function meeusApparentSun(d: number): {
+    dec: number;
+    eot: number;
+};
+/** Minutes before the horizon crossing that the ministry prints sunrise, and after it Maghrib. */
+export declare const MOROCCO_SUNRISE_MARGIN = -2.85;
+export declare const MOROCCO_MAGHRIB_MARGIN = 3.7;
+/** The share of the horizon dip Maghrib takes, against sunrise's whole, where a city's own is not known. */
+export declare const MOROCCO_MAGHRIB_DIP_SHARE = 0.86;
+/** Degrees of dip per √metre where the ministry's own value is not known. */
+export declare const MOROCCO_DIP_PER_SQRT_M = 0.02;
+/** Exact times, minutes past 00:00 UT of the civil date, margins applied, before rounding. NaN where one does not form. */
+export declare function moroccoRawMinutes(latitude: number, longitude: number, year: number, month: number, day: number, dipDeg?: number, asrShadow?: number, 
+/** The horizon's dip westward, at Maghrib; MOROCCO_MAGHRIB_DIP_SHARE of `dipDeg` when not known. */
+dipMaghribDeg?: number): {
+    fajr: number;
+    sunrise: number;
+    dhuhr: number;
+    asr: number;
+    maghrib: number;
+    isha: number;
+};
+/**
+ * The ministry's times for a point and civil date (month 0-based), on the
+ * minute. Null when a time does not form there.
+ */
+export declare function moroccoTimes(latitude: number, longitude: number, year: number, month: number, day: number, dipDeg?: number, asrShadow?: number, dipMaghribDeg?: number): MoroccoInstants | null;

package/dist/cjs/methods/morocco.js

@@ -0,0 +1,113 @@
+"use strict";
+/**
+ * Morocco — the Ministry of Habous and Islamic Affairs's method, as its
+ * timetable is computed (issue #10).
+ *
+ * Read off 77 days of the ministry's tables for its 164 located cities:
+ *
+ *   • a precise Sun — Meeus's apparent Sun with the full nutation and his
+ *     chapter-28 equation of time; a JPL ephemeris fits no better, NOAA's
+ *     and the Almanac's series far worse — taken at each prayer's own
+ *     moment (iterated), declination and equation of time alike;
+ *   • Fajr 19°, Isha 17°, Asr one shadow length (Shafi'i);
+ *   • Dhuhr five minutes after the transit;
+ *   • sunrise 2.85 minutes before, and Maghrib 3.7 after, the Sun's upper
+ *     limb on the horizon — refraction 34′ and the Sun's semi-diameter for
+ *     its distance that day — less the city's own horizon dip;
+ *   • Fajr rounded down to the minute, the rest to the nearest.
+ *
+ * The dip is the ministry's own per city and per side — the horizon east
+ * at sunrise, west at Maghrib, which mountains or the sea make different —
+ * fitted from its tables with the city's point (`data/moroccoMethodPoints.json`,
+ * about 0.02° per √metre of height); elsewhere 0.02°·√height, 0.86 of it at
+ * Maghrib. On 77 days of the ministry's tables for its 164 located cities
+ * this is its printed minute for 99.12 % of times, and never further than
+ * one; `data/corrections/morocco.json` holds the rest.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MOROCCO_DIP_PER_SQRT_M = exports.MOROCCO_MAGHRIB_DIP_SHARE = exports.MOROCCO_MAGHRIB_MARGIN = exports.MOROCCO_SUNRISE_MARGIN = void 0;
+exports.meeusApparentSun = meeusApparentSun;
+exports.moroccoRawMinutes = moroccoRawMinutes;
+exports.moroccoTimes = moroccoTimes;
+const RAD = Math.PI / 180;
+const DAY_MS = 86_400_000;
+/** Meeus's apparent Sun at `d` days from J2000.0: declination (rad), equation of time (minutes). */
+function meeusApparentSun(d) {
+    const T = d / 36525;
+    const L0 = (((280.46646 + T * (36000.76983 + 0.0003032 * T)) % 360) + 360) % 360;
+    const M = (357.52911 + T * (35999.05029 - 0.0001537 * T)) * RAD;
+    const C = (1.914602 - T * (0.004817 + 0.000014 * T)) * Math.sin(M) +
+        (0.019993 - 0.000101 * T) * Math.sin(2 * M) +
+        0.000289 * Math.sin(3 * M);
+    const om = (125.04 - 1934.136 * T) * RAD;
+    const eps0 = 23 + (26 + (21.448 - T * (46.815 + T * (0.00059 - T * 0.001813))) / 60) / 60;
+    const Lm = (280.4665 + 36000.7698 * T) * RAD;
+    const Lmoon = (218.3165 + 481267.8813 * T) * RAD;
+    const dpsi = (-17.2 * Math.sin(om) - 1.32 * Math.sin(2 * Lm) - 0.23 * Math.sin(2 * Lmoon) + 0.21 * Math.sin(2 * om)) / 3600;
+    const deps = (9.2 * Math.cos(om) + 0.57 * Math.cos(2 * Lm) + 0.1 * Math.cos(2 * Lmoon) - 0.09 * Math.cos(2 * om)) / 3600;
+    const lambda = (L0 + C - 0.00569 + dpsi) * RAD;
+    const eps = (eps0 + deps) * RAD;
+    const ra = (((Math.atan2(Math.cos(eps) * Math.sin(lambda), Math.cos(lambda)) / RAD) % 360) + 360) % 360;
+    const dec = Math.asin(Math.sin(eps) * Math.sin(lambda));
+    const E = L0 - 0.0057183 - ra + dpsi * Math.cos(eps);
+    const eot = ((((E + 180) % 360) + 360) % 360 - 180) * 4;
+    return { dec, eot };
+}
+const ITERATIONS = 3;
+/** Minutes before the horizon crossing that the ministry prints sunrise, and after it Maghrib. */
+exports.MOROCCO_SUNRISE_MARGIN = -2.85;
+exports.MOROCCO_MAGHRIB_MARGIN = 3.7;
+/** The share of the horizon dip Maghrib takes, against sunrise's whole, where a city's own is not known. */
+exports.MOROCCO_MAGHRIB_DIP_SHARE = 0.86;
+/** Degrees of dip per √metre where the ministry's own value is not known. */
+exports.MOROCCO_DIP_PER_SQRT_M = 0.02;
+/** Exact times, minutes past 00:00 UT of the civil date, margins applied, before rounding. NaN where one does not form. */
+function moroccoRawMinutes(latitude, longitude, year, month, day, dipDeg = 0, asrShadow = 1, 
+/** The horizon's dip westward, at Maghrib; MOROCCO_MAGHRIB_DIP_SHARE of `dipDeg` when not known. */
+dipMaghribDeg = exports.MOROCCO_MAGHRIB_DIP_SHARE * dipDeg) {
+    const d0 = (Date.UTC(year, month, day) - Date.UTC(2000, 0, 1)) / DAY_MS - 0.5;
+    const at = (t) => meeusApparentSun(d0 + t / 1440);
+    let noon = 720 - 4 * longitude;
+    for (let i = 0; i < ITERATIONS; i++)
+        noon = 720 - 4 * longitude - at(noon).eot;
+    const sp = Math.sin(latitude * RAD);
+    const cp = Math.cos(latitude * RAD);
+    // the upper limb on the horizon: refraction 34′ and the semi-diameter for the Sun's distance that day
+    const T = (d0 + noon / 1440) / 36525;
+    const Ma = (357.52911 + 35999.05029 * T) * RAD;
+    const horizon = -(34 / 60 + 0.26667 / (1.00014 - 0.016708 * Math.cos(Ma) - 0.00014 * Math.cos(2 * Ma)));
+    const event = (altitudeOf, sign, start) => {
+        let t = start;
+        for (let i = 0; i < ITERATIONS; i++) {
+            const { dec, eot } = at(t);
+            const c = (Math.sin(altitudeOf(dec) * RAD) - sp * Math.sin(dec)) / (cp * Math.cos(dec));
+            if (!(Math.abs(c) <= 1))
+                return NaN;
+            t = 720 - 4 * longitude - eot + (sign * 4 * Math.acos(c)) / RAD;
+        }
+        return t;
+    };
+    const fixed = (a) => () => a;
+    const asrAltitude = (dec) => Math.atan(1 / (asrShadow + Math.tan(Math.abs(latitude - dec / RAD) * RAD))) / RAD;
+    return {
+        fajr: event(fixed(-19), -1, noon - 420) - 0.5,
+        sunrise: event(fixed(horizon - dipDeg), -1, noon - 360) + exports.MOROCCO_SUNRISE_MARGIN,
+        dhuhr: noon + 5,
+        asr: event(asrAltitude, 1, noon + 200),
+        maghrib: event(fixed(horizon - dipMaghribDeg), 1, noon + 360) + exports.MOROCCO_MAGHRIB_MARGIN,
+        isha: event(fixed(-17), 1, noon + 420),
+    };
+}
+/**
+ * The ministry's times for a point and civil date (month 0-based), on the
+ * minute. Null when a time does not form there.
+ */
+function moroccoTimes(latitude, longitude, year, month, day, dipDeg = 0, asrShadow = 1, dipMaghribDeg) {
+    const r = moroccoRawMinutes(latitude, longitude, year, month, day, dipDeg, asrShadow, dipMaghribDeg);
+    const all = [r.fajr, r.sunrise, r.dhuhr, r.asr, r.maghrib, r.isha];
+    if (!all.every(Number.isFinite))
+        return null;
+    const start = Date.UTC(year, month, day);
+    const at = (m) => new Date(start + Math.floor(m + 0.5) * 60_000);
+    return { fajr: at(r.fajr), sunrise: at(r.sunrise), dhuhr: at(r.dhuhr), asr: at(r.asr), maghrib: at(r.maghrib), isha: at(r.isha) };
+}

package/dist/cjs/methods/revisions.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Each method's revision: raised whenever a change to a method, or to the
+ * points it computes its places at, changes what it prints. A correction
+ * list is written for one revision (certification.json names it), and an
+ * app applies a list only to the revision it computes — a list for another
+ * would move the wrong minutes. An app on an older revision tells its user
+ * to update instead.
+ */
+export declare const METHOD_REVISION: {
+    readonly sweden: 1;
+    readonly diyanet: 1;
+    readonly morocco: 1;
+    readonly algeria: 1;
+    readonly indonesia: 1;
+};

package/dist/cjs/methods/revisions.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.METHOD_REVISION = void 0;
+/**
+ * Each method's revision: raised whenever a change to a method, or to the
+ * points it computes its places at, changes what it prints. A correction
+ * list is written for one revision (certification.json names it), and an
+ * app applies a list only to the revision it computes — a list for another
+ * would move the wrong minutes. An app on an older revision tells its user
+ * to update instead.
+ */
+exports.METHOD_REVISION = {
+    sweden: 1,
+    diyanet: 1,
+    morocco: 1,
+    algeria: 1,
+    indonesia: 1,
+};

package/dist/cjs/methods/scratch-congress.d.ts

@@ -0,0 +1,87 @@
+/**
+ * The International Prayer Times Congress method (Istanbul, 2021 — the
+ * Diyanet and the European Council for Fatwa and Research) as Diyanet's
+ * tables realise it. Islamiska Förbundet's Swedish tables are those
+ * tables, row for row, so this is Sweden's method (id 24).
+ *
+ * The published rules (awqatsalah.com, "Tespit Kriterleri"):
+ *  - Dhuhr five minutes after transit; Asr one shadow (Dhuhr when the
+ *    shadow never forms), four minutes late; sunrise seven early,
+ *    Maghrib seven late ("temkin").
+ *  - Neither the day nor the night is shorter than five hours.
+ *  - True Fajr at 18°, true Isha at 16°. Where the 18° dawn no longer
+ *    forms, the share of the night the sharia night's third took on the
+ *    last day it did is carried: Isha that share of the night after
+ *    Maghrib, Fajr the same share scaled by 18/16 before sunrise.
+ *  - The move from true times to the carried ones is gradual, starting
+ *    twenty minutes before (Isha) or after (Fajr) the takdir.
+ *
+ * What the tables turn out to do with them, read off Diyanet's own tables
+ * for all 160 Swedish places, 2024–2027 (99.98 % of times on the printed
+ * minute, the rest a fraction of a second from the rounding point):
+ *  - The sun is taken once a day, at 0h UT less 45 s: Meeus's mean
+ *    elements and equation of the centre, the TRUE (geometric) longitude,
+ *    the apparent obliquity (mean plus nutation), the equation of time as
+ *    the mean longitude less the right ascension, 0.106 s later; and
+ *    two small waves by the mean longitude the formula leaves out: a few
+ *    hundredths of a second on the transit, a tenth of an arc-second on
+ *    the declination.
+ *  - Coordinates are kept to three decimals of a degree.
+ *  - Asr that never forms is printed at Dhuhr's time.
+ *  - The night a share is taken of is the day's own: 24 h less the
+ *    printed day, sunrise to Maghrib.
+ *  - The five-hour floors hold each end separately, 150 minutes from the
+ *    printed Dhuhr or from the midnight after it. Where midsummer's
+ *    night is floored at both ends (to within a minute), that night
+ *    anchors the season, and the floored times never step back: before
+ *    midsummer no sunrise earlier than midsummer's and a floored Maghrib
+ *    no earlier than the day before; after it no sunrise earlier nor
+ *    Maghrib later than on any day since midsummer — and Fajr and Isha
+ *    carried the same way.
+ *  - The gradual transition is a straight line across the days next to
+ *    the gap on which the true time lies within twenty minutes of the
+ *    takdir at the gap's edge: twenty minutes away at the far end, the
+ *    takdir at the edge.
+ *
+ * Beyond Sweden the same code gives Diyanet's tables worldwide, read off
+ * them for places on six continents:
+ *  - Where the dawn forms all summer but midsummer's true Isha (at 16°)
+ *    falls later than the share carried from that night, midsummer is the
+ *    takdir's day — a gap of one day, with its ramps (from about 44.4°
+ *    north: Austria, central France, northern Bosnia).
+ *  - Isha is printed at 16° in some countries and 17° in others; the
+ *    high-latitude rules are worked at 16° either way (`ishaDeg`).
+ *
+ * Times are minutes past 0h UT of the date, a frame the clock changes
+ * cannot bend; `congressTimes` turns them into instants.
+ */
+/**
+ * Isha's depression: the Congress's 16° (Diyanet's in much of Europe,
+ * Russia, Central Asia, China and North America), or Diyanet's own 17°
+ * (elsewhere). The high-latitude rules are the Congress's at 16° either way;
+ * the angle sets only the true Isha printed.
+ */
+export declare const CONGRESS_ISHA_DEG = 16;
+export declare const DIYANET_ISHA_DEG = 17;
+export type CongressInstants = {
+    fajr: Date;
+    sunrise: Date;
+    dhuhr: Date;
+    asr: Date;
+    maghrib: Date;
+    isha: Date;
+};
+/**
+ * The Congress method's times for a calendar date (year, month 0–11, day),
+ * as instants, unrounded. `asrShadow` is 1 for the standard Asr, 2 for the
+ * Hanafi one; the tables print the standard. `ishaDeg` is Isha's depression:
+ * 16° (the Congress's, Diyanet's in Europe and North America) or 17°
+ * (Diyanet's everywhere else).
+ */
+export declare function congressTimes(latitude: number, longitude: number, year: number, month: number, day: number, asrShadow?: number, ishaDeg?: number): CongressInstants;
+/** For tests and the verification tool: the year's structure as the method sees it. */
+export declare function congressYearInfo(latitude: number, longitude: number, year: number): {
+    gap: [string, string] | null;
+    ratio: number | null;
+    midsummerFloors: boolean;
+};