{"_id":"@danishfareed/ramadan-timings","_rev":"4-116225312a8c808d4014dae8380983ad","name":"@danishfareed/ramadan-timings","dist-tags":{"latest":"1.1.0"},"versions":{"1.0.0":{"name":"@danishfareed/ramadan-timings","version":"1.0.0","keywords":["ramadan","fasting","prayer-times","fajr","maghrib","sunrise","sunset","islamic","astronomy","zero-dependency"],"author":{"name":"danish"},"license":"MIT","_id":"@danishfareed/ramadan-timings@1.0.0","maintainers":[{"name":"danishfareed","email":"fareedanish1@gmail.com"}],"homepage":"https://github.com/danish/ramadan-times-core#readme","bugs":{"url":"https://github.com/danish/ramadan-times-core/issues"},"dist":{"shasum":"0dc9d93fe4e1415fdcf7b35dad9d105f8809b464","tarball":"https://registry.npmjs.org/@danishfareed/ramadan-timings/-/ramadan-timings-1.0.0.tgz","fileCount":35,"integrity":"sha512-xA85anoJ+QCGTwDCfU90i2WJqxdBlenZGad2Y8Zhh35DFz4N74xHHeLw6fTmYzQWj9y2hlGk8xPzJJRdOFfL8A==","signatures":[{"sig":"MEYCIQDfKvd/KehuCYNVqGQTQjnhHjtBttBwTBPeIjTRbMHcDwIhALUN1s0xxK8ySwQdJ/fo4efaTA1OF3IJ3GDzRbwkFfXt","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":86813},"main":"dist/cjs/index.js","types":"dist/cjs/index.d.ts","module":"dist/esm/index.js","exports":{".":{"import":{"types":"./dist/esm/index.d.ts","default":"./dist/esm/index.js"},"require":{"types":"./dist/cjs/index.d.ts","default":"./dist/cjs/index.js"}}},"gitHead":"9c8995e1fcbe0b2671daa104daf50012fe5258e3","scripts":{"test":"vitest run","build":"npm run clean && npm run build:cjs && npm run build:esm","clean":"rm -rf dist","build:cjs":"tsc --outDir dist/cjs","build:esm":"tsc --project tsconfig.esm.json","prepublishOnly":"npm run build"},"_npmUser":{"name":"danishfareed","email":"fareedanish1@gmail.com"},"repository":{"url":"git+https://github.com/danish/ramadan-times-core.git","type":"git"},"_npmVersion":"10.9.4","description":"Minimal, zero-dependency Ramadan fasting times library — calculates true Fajr (dawn) and Maghrib (sunset) worldwide using built-in solar math.","directories":{},"sideEffects":false,"_nodeVersion":"22.22.0","_hasShrinkwrap":false,"devDependencies":{"vitest":"^4.0.18","typescript":"^5.9.3","@types/node":"^25.3.0"},"_npmOperationalInternal":{"tmp":"tmp/ramadan-timings_1.0.0_1771958390701_0.517627713577147","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@danishfareed/ramadan-timings","version":"1.0.1","keywords":["ramadan","fasting","prayer-times","fajr","maghrib","sunrise","sunset","islamic","astronomy","zero-dependency"],"author":{"name":"danish"},"license":"MIT","_id":"@danishfareed/ramadan-timings@1.0.1","maintainers":[{"name":"danishfareed","email":"fareedanish1@gmail.com"}],"homepage":"https://github.com/danishfareed/ramadan-timings#readme","bugs":{"url":"https://github.com/danishfareed/ramadan-timings/issues"},"dist":{"shasum":"6599cad0e8f5a9ba1043dba331d82a72b247534d","tarball":"https://registry.npmjs.org/@danishfareed/ramadan-timings/-/ramadan-timings-1.0.1.tgz","fileCount":35,"integrity":"sha512-NTCJhhkE9LU4smwPbcufTYJ2PW8EGPNxh16eajtOOhUpPNLIY9A8c6sDvhbuGSAMJNquSWP4KyS5wI+2s39Wrw==","signatures":[{"sig":"MEUCIEOcIZ0aIibQ5llnNn3Z19CGqMJxwo36ZqSdHqOlIgfZAiEAnbqvZKDykmPRrb/nq6QP1W9jCS/zZwrmdXPzT9mvSGw=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":86821},"main":"dist/cjs/index.js","types":"dist/cjs/index.d.ts","module":"dist/esm/index.js","exports":{".":{"import":{"types":"./dist/esm/index.d.ts","default":"./dist/esm/index.js"},"require":{"types":"./dist/cjs/index.d.ts","default":"./dist/cjs/index.js"}}},"gitHead":"9f85067e99bb13c859e8c8bfeae8719f60046cca","scripts":{"test":"vitest run","build":"npm run clean && npm run build:cjs && npm run build:esm","clean":"rm -rf dist","build:cjs":"tsc --outDir dist/cjs","build:esm":"tsc --project tsconfig.esm.json","prepublishOnly":"npm run build"},"_npmUser":{"name":"danishfareed","email":"fareedanish1@gmail.com"},"repository":{"url":"git+https://github.com/danishfareed/ramadan-timings.git","type":"git"},"_npmVersion":"10.9.4","description":"Minimal, zero-dependency Ramadan fasting times library — calculates true Fajr (dawn) and Maghrib (sunset) worldwide using built-in solar math.","directories":{},"sideEffects":false,"_nodeVersion":"22.22.0","_hasShrinkwrap":false,"devDependencies":{"vitest":"^4.0.18","typescript":"^5.9.3","@types/node":"^25.3.0"},"_npmOperationalInternal":{"tmp":"tmp/ramadan-timings_1.0.1_1771958518737_0.7316980204296835","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@danishfareed/ramadan-timings","version":"1.0.2","keywords":["ramadan","fasting","prayer-times","fajr","maghrib","sunrise","sunset","islamic","astronomy","zero-dependency"],"author":{"name":"danish"},"license":"MIT","_id":"@danishfareed/ramadan-timings@1.0.2","maintainers":[{"name":"danishfareed","email":"fareedanish1@gmail.com"}],"homepage":"https://github.com/danishfareed/ramadan-timings#readme","bugs":{"url":"https://github.com/danishfareed/ramadan-timings/issues"},"dist":{"shasum":"c4a7404505cb45c58ba88c3410a2eebfe99306da","tarball":"https://registry.npmjs.org/@danishfareed/ramadan-timings/-/ramadan-timings-1.0.2.tgz","fileCount":43,"integrity":"sha512-UEMYA6KOdJWHmktFo8OGgKKuQKGDrVpE4nd3fQWkFxJR4E/hR5vLPK6/4UevKUSOsCAUGR7b4bD0wg04nsw1ig==","signatures":[{"sig":"MEYCIQCQ+sQiLkdi1R4msdhJxMOdBvJNHxXruf6dRNeNBmWu0QIhALdV3htrFyNVEzCWGng4WwctLvXZzslHLX533C+ckbHk","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":104643},"main":"dist/cjs/index.js","types":"dist/cjs/index.d.ts","module":"dist/esm/index.js","exports":{".":{"import":{"types":"./dist/esm/index.d.ts","default":"./dist/esm/index.js"},"require":{"types":"./dist/cjs/index.d.ts","default":"./dist/cjs/index.js"}}},"gitHead":"e694cf2492dea7cddc3d0c61766a945f5dfca7e9","scripts":{"test":"vitest run","build":"npm run clean && npm run build:cjs && npm run build:esm","clean":"rm -rf dist","build:cjs":"tsc --outDir dist/cjs","build:esm":"tsc --project tsconfig.esm.json","prepublishOnly":"npm run build"},"_npmUser":{"name":"danishfareed","email":"fareedanish1@gmail.com"},"repository":{"url":"git+https://github.com/danishfareed/ramadan-timings.git","type":"git"},"_npmVersion":"10.9.4","description":"Minimal, zero-dependency Ramadan fasting times library — calculates true Fajr (dawn) and Maghrib (sunset) worldwide using built-in solar math.","directories":{},"sideEffects":false,"_nodeVersion":"22.22.0","_hasShrinkwrap":false,"devDependencies":{"vitest":"^4.0.18","typescript":"^5.9.3","@types/node":"^25.3.0"},"_npmOperationalInternal":{"tmp":"tmp/ramadan-timings_1.0.2_1771959983811_0.9578245875085396","host":"s3://npm-registry-packages-npm-production"}},"1.1.0":{"name":"@danishfareed/ramadan-timings","version":"1.1.0","description":"Zero-dependency library that calculates all 5 daily prayer times (Fajr, Dhuhr, Asr, Maghrib, Isha) and Ramadan fasting times worldwide using built-in solar math.","main":"dist/cjs/index.js","module":"dist/esm/index.js","types":"dist/cjs/index.d.ts","exports":{".":{"import":{"types":"./dist/esm/index.d.ts","default":"./dist/esm/index.js"},"require":{"types":"./dist/cjs/index.d.ts","default":"./dist/cjs/index.js"}}},"sideEffects":false,"scripts":{"clean":"rm -rf dist","build:cjs":"tsc --outDir dist/cjs","build:esm":"tsc --project tsconfig.esm.json","build":"npm run clean && npm run build:cjs && npm run build:esm","test":"vitest run","prepublishOnly":"npm run build"},"keywords":["ramadan","fasting","prayer-times","fajr","maghrib","sunrise","sunset","islamic","astronomy","zero-dependency"],"author":{"name":"danish"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/danishfareed/ramadan-timings.git"},"devDependencies":{"@types/node":"^25.3.0","typescript":"^5.9.3","vitest":"^4.0.18"},"_id":"@danishfareed/ramadan-timings@1.1.0","gitHead":"f19478cc6e954b69e86596a0c35a0f5a646f641d","bugs":{"url":"https://github.com/danishfareed/ramadan-timings/issues"},"homepage":"https://github.com/danishfareed/ramadan-timings#readme","_nodeVersion":"22.22.0","_npmVersion":"10.9.4","dist":{"integrity":"sha512-eAOhxGamScuUdcsyJptKHNYsKx5U/xreqQK/NE0K8jYDksXMPMKQCTqP02PI7j5Ma0g+iaIAR0LkpYuH3EtX6A==","shasum":"6f9c473d9b8edc2dc02357a80a772d72688ce319","tarball":"https://registry.npmjs.org/@danishfareed/ramadan-timings/-/ramadan-timings-1.1.0.tgz","fileCount":43,"unpackedSize":123789,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIA13jiU2M8jwZ2RB8n9jwpiLzRSou6A6Elty/5hsh6X8AiB4Am2vuegVcGnEH8dxlI72gBauW/+P5gnmmIw02a3dBA=="}]},"_npmUser":{"name":"danishfareed","email":"fareedanish1@gmail.com"},"directories":{},"maintainers":[{"name":"danishfareed","email":"fareedanish1@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/ramadan-timings_1.1.0_1771961517993_0.5229071121866069"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-24T18:39:50.559Z","modified":"2026-02-24T19:31:58.306Z","1.0.0":"2026-02-24T18:39:50.843Z","1.0.1":"2026-02-24T18:41:58.892Z","1.0.2":"2026-02-24T19:06:23.966Z","1.1.0":"2026-02-24T19:31:58.183Z"},"bugs":{"url":"https://github.com/danishfareed/ramadan-timings/issues"},"author":{"name":"danish"},"license":"MIT","homepage":"https://github.com/danishfareed/ramadan-timings#readme","keywords":["ramadan","fasting","prayer-times","fajr","maghrib","sunrise","sunset","islamic","astronomy","zero-dependency"],"repository":{"type":"git","url":"git+https://github.com/danishfareed/ramadan-timings.git"},"description":"Zero-dependency library that calculates all 5 daily prayer times (Fajr, Dhuhr, Asr, Maghrib, Isha) and Ramadan fasting times worldwide using built-in solar math.","maintainers":[{"name":"danishfareed","email":"fareedanish1@gmail.com"}],"readme":"# @danishfareed/ramadan-timings\n\n[![npm version](https://img.shields.io/npm/v/@danishfareed/ramadan-timings.svg)](https://www.npmjs.com/package/@danishfareed/ramadan-timings)\n[![bundle size](https://img.shields.io/bundlephobia/minzip/@danishfareed/ramadan-timings)](https://bundlephobia.com/package/@danishfareed/ramadan-timings)\n[![license](https://img.shields.io/npm/l/@danishfareed/ramadan-timings.svg)](./LICENSE)\n[![zero deps](https://img.shields.io/badge/dependencies-0-brightgreen.svg)]()\n\nA **minimal, zero-dependency** library that calculates Ramadan fasting times and **all 5 daily prayer times** (Fajr, Dhuhr, Asr, Maghrib, Isha) worldwide using built-in solar math.\n\n## ✨ Features\n\n| Feature | Details |\n|---------|---------|\n| **Zero dependencies** | Pure TypeScript — no moment, no date-fns, no astronomy libs |\n| **All 5 prayers** | Fajr, Dhuhr, Asr (Standard / Hanafi), Maghrib, Isha |\n| **Single authentic method** | True Fajr → Sunset, per Qur'an 2:187 and authentic Sunnah |\n| **Accurate everywhere** | Built-in Meeus/NOAA solar algorithms (±1-2 min) |\n| **City search** | Resolve city names or reverse-geocode coordinates (OpenStreetMap) |\n| **Dual CJS + ESM** | Works in Node, browsers, serverless, Deno |\n| **Tiny bundle** | ~12 kB packed |\n| **High-latitude fallbacks** | `middle-of-night`, `one-seventh`, and `angle-based` modes |\n| **Input validation** | Descriptive `RangeError` messages for invalid configs |\n\n---\n\n## Installation\n\n```bash\nnpm install @danishfareed/ramadan-timings\n```\n\n---\n\n## Quick Start\n\n```typescript\nimport { getDayFastingTimes, formatLocalTime } from '@danishfareed/ramadan-timings';\n\nconst times = getDayFastingTimes(new Date(2025, 2, 1), {\n  latitude: 25.2048,       // Dubai\n  longitude: 55.2708,\n  timezoneOffsetMinutes: 240, // UTC+4\n  fajrTwilightAngle: 18.5,\n  imsakMarginMinutes: 10,\n});\n\nif (times) {\n  console.log(`Imsak:   ${formatLocalTime(times.imsak,   240)}`);\n  console.log(`Fajr:    ${formatLocalTime(times.fajr,    240)}`);\n  console.log(`Sunrise: ${formatLocalTime(times.sunrise, 240)}`);\n  console.log(`Noon:    ${formatLocalTime(times.solarNoon, 240)}`);\n  console.log(`Maghrib: ${formatLocalTime(times.maghrib, 240)}`);\n  console.log(`Duration: ${times.fastingDurationMinutes} mins`);\n}\n```\n\n---\n\n## API Reference\n\n### `getDayFastingTimes(date, config): FastingTimes | null`\n\nReturns fasting times for a single calendar day, or `null` if times cannot be computed (extreme latitudes with no fallback).\n\n### `getDayPrayerTimes(date, config): PrayerTimes | null`\n\nReturns all 5 prayer times (Fajr, Sunrise, Dhuhr, Asr, Maghrib, Isha) for a single day. Asr defaults to the Sunni Standard (Shafi'i/Maliki/Hanbali) method; set `asrMethod: 'hanafi'` for the Hanafi school.\n\n### `getRamadanFastingTimes(startDate, endDate, config): (FastingTimes | null)[]`\n\nReturns daily fasting times for a date range (e.g. entire Ramadan).\n\n### `formatLocalTime(date, timezoneOffsetMinutes): string`\n\nConverts a UTC `Date` to a local `\"HH:MM\"` string.\n\n### `validateConfig(config): void`\n\nThrows a descriptive `RangeError` if any config value is invalid.\n\n### `formatDuration(totalMinutes): string`\n\nFormats a duration in minutes into a human-readable string like `\"14h 20m\"`.\n\n### `reverseGeocode(latitude, longitude): Promise<string>`\n\nReverse-geocodes coordinates to a human-readable area name using the free OpenStreetMap Nominatim API. Returns formatted strings like `\"Al Haram, Mecca, Saudi Arabia\"`.\n\n### `getCityCoordinates(cityName, date?): Promise<...>`\n\nResolves a city name to coordinates and timezone using the free Open-Meteo Geocoding API.\n\n### `getFastingTimesByCity(cityName, date?, config?): Promise<...>`\n\nFetches coordinates for a city and returns fasting times.\n\n### `getPrayerTimesByCity(cityName, date?, config?): Promise<...>`\n\nFetches coordinates for a city and returns prayer times.\n\n---\n\n### `RamadanCoreConfig`\n\n```typescript\ninterface RamadanCoreConfig {\n  latitude: number;               // -90 to 90\n  longitude: number;              // -180 to 180\n  timezoneOffsetMinutes: number;  // UTC offset in minutes (e.g. +240 for UTC+4)\n\n  imsakMarginMinutes?: number;    // Minutes before Fajr to stop eating (default: 0)\n  maghribDelayMinutes?: number;   // Minutes after sunset to break fast (default: 0)\n  fajrTwilightAngle?: number;     // Fajr angle below horizon (default: 18)\n  ishaTwilightAngle?: number;     // Isha angle below horizon (default: 18)\n  asrMethod?: 'standard' | 'hanafi'; // Asr shadow method (default: 'standard')\n\n  highLatitudeMode?: HighLatitudeMode; // Fallback strategy (default: 'none')\n}\n\ntype HighLatitudeMode = 'none' | 'middle-of-night' | 'one-seventh' | 'angle-based';\n```\n\n### `FastingTimes`\n\n```typescript\ninterface FastingTimes {\n  date: Date;\n  fajr: Date;                       // True dawn\n  imsak: Date;                      // Fajr minus imsakMarginMinutes\n  sunrise: Date;                    // Sun's upper limb above horizon\n  solarNoon: Date;                  // Solar transit (Dhuhr)\n  maghrib: Date;                    // Sunset — fast ends\n  fastingDurationMinutes: number;   // maghrib – fajr in minutes\n  highLatitudeFallbackApplied: boolean;\n}\n```\n\n### `PrayerTimes`\n\n```typescript\ninterface PrayerTimes {\n  date: Date;\n  fajr: Date;\n  sunrise: Date;\n  dhuhr: Date;\n  asr: Date;\n  maghrib: Date;\n  isha: Date;\n  highLatitudeFallbackApplied: boolean;\n}\n```\n\n---\n\n## High-Latitude Handling\n\nAt extreme latitudes (above ~48°) during certain seasons, the sun may never reach 18° below the horizon. When this happens, `getDayFastingTimes` returns `null` by default. You can configure a fallback:\n\n| Mode | Description |\n|------|-------------|\n| `'none'` | Return `null` (default) |\n| `'middle-of-night'` | Fajr = midpoint of the night (sunset → sunrise) |\n| `'one-seventh'` | Fajr = sunrise minus 1/7 of night duration |\n| `'angle-based'` | Fajr = proportional to `fajrAngle / 60` of night |\n\n```typescript\nconst times = getDayFastingTimes(date, {\n  ...config,\n  highLatitudeMode: 'one-seventh',\n});\n```\n\n---\n\n## Method & Fiqh\n\nThis package uses **one consistent method** based on Qur'an and authentic Sunnah:\n\n- **Fasting begins at true Fajr (dawn)** — when the horizontal white light of dawn becomes distinct from the dark night (Qur'an 2:187, hadith of Ibn 'Umar and 'Adi ibn Hatim).\n- **Fasting ends at sunset (Maghrib)** — the moment the sun's disk fully disappears below the horizon, even if the sky is still bright.\n- No madhhab switching. No imsak is *required* by Shariah, but a configurable safety margin (`imsakMarginMinutes`) is supported.\n\nThe Fajr angle defaults to **18°** below the horizon (astronomical twilight), which closely matches the observed \"true dawn\". Use `18.5°` to match conventions like Umm al-Qura.\n\n---\n\n## License\n\nMIT\n","readmeFilename":"README.md"}