{"_id":"@azkal182/islamic-utils","_rev":"4-82b9471051b7c05da9a3929ca08d0947","name":"@azkal182/islamic-utils","dist-tags":{"latest":"0.3.0"},"versions":{"0.1.0":{"name":"@azkal182/islamic-utils","version":"0.1.0","keywords":["islamic","prayer-times","salat","sholat","qibla","kiblat","inheritance","faraidh","waris","muslim","imsak","dhuha"],"author":{"name":"azkal182"},"license":"MIT","_id":"@azkal182/islamic-utils@0.1.0","maintainers":[{"name":"azkal182","email":"mohazkalarif@gmail.com"}],"homepage":"https://github.com/azkal182/islamic-utils#readme","bugs":{"url":"https://github.com/azkal182/islamic-utils/issues"},"dist":{"shasum":"aa6444411332ce17de6f1b08d20751f36ecf6a9d","tarball":"https://registry.npmjs.org/@azkal182/islamic-utils/-/islamic-utils-0.1.0.tgz","fileCount":8,"integrity":"sha512-hO0D9JBr7sL/Nn/LISmbP6EZhyP/bvBHHiiJwiNrrA3nRIdiOG+Kf918NwXcvdGoQOUQz2WqznSxvfTOHLP6ig==","signatures":[{"sig":"MEYCIQCO6mQyY/vDzDczH2FcCwuHGHfkk9as8BOqPX81GBlSLwIhAP35eirC2vq/94BrmXf0xW9MRfq+t+h9rVw5CyXatESi","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":365014},"main":"dist/index.js","types":"dist/index.d.ts","module":"dist/index.mjs","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"}},"gitHead":"74047b01521644266ee9f1cf26ae4810b7ac9343","scripts":{"dev":"tsup src/index.ts --format cjs,esm --dts --watch","lint":"eslint src --ext .ts","test":"vitest","bench":"vitest bench","build":"tsup src/index.ts --format cjs,esm --dts --clean","format":"prettier --write \"src/**/*.ts\"","lint:fix":"eslint src --ext .ts --fix","test:run":"vitest run","typecheck":"tsc --noEmit","example:qibla":"tsx examples/qibla.ts","test:coverage":"vitest run --coverage","prepublishOnly":"pnpm run build","example:prayer-times":"tsx examples/prayer-times.ts"},"_npmUser":{"name":"azkal182","email":"mohazkalarif@gmail.com"},"repository":{"url":"git+https://github.com/azkal182/islamic-utils.git","type":"git"},"_npmVersion":"11.6.2","description":"Accurate and consistent Islamic utilities library for prayer times, qibla direction, and inheritance calculation","directories":{},"_nodeVersion":"24.12.0","_hasShrinkwrap":false,"packageManager":"pnpm@10.26.1","devDependencies":{"tsx":"^4.21.0","tsup":"^8.5.1","eslint":"^9.39.2","vitest":"^4.0.16","prettier":"^3.7.4","typescript":"^5.9.3","@types/node":"^25.0.3","@vitest/coverage-v8":"^4.0.16","@typescript-eslint/parser":"^8.52.0","@typescript-eslint/eslint-plugin":"^8.52.0"},"_npmOperationalInternal":{"tmp":"tmp/islamic-utils_0.1.0_1767649986717_0.5819819904887664","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@azkal182/islamic-utils","version":"0.2.0","keywords":["islamic","prayer-times","salat","sholat","qibla","kiblat","inheritance","faraidh","waris","muslim","imsak","dhuha"],"author":{"name":"azkal182"},"license":"MIT","_id":"@azkal182/islamic-utils@0.2.0","maintainers":[{"name":"azkal182","email":"mohazkalarif@gmail.com"}],"homepage":"https://github.com/azkal182/islamic-utils#readme","bugs":{"url":"https://github.com/azkal182/islamic-utils/issues"},"dist":{"shasum":"d33fb0e14183ee0643a7002efb7f576dd649eb17","tarball":"https://registry.npmjs.org/@azkal182/islamic-utils/-/islamic-utils-0.2.0.tgz","fileCount":8,"integrity":"sha512-UjRvoWKtaZJsPGTVD3uUvwbCnk+EktkCK7LV4gsrvXAkzc882cdfW5p8Ao9XBUOUzz94KxMzLkFeCD6mA9PtdQ==","signatures":[{"sig":"MEQCIEyHDbIlImV8Jqwx3AlF7F7jy53gHhYe1DoDs0DkkftgAiBib0dRJv2bNkj/Z39gaE1M8Msv1pApEBmB2v4/ZTvTLw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":576313},"main":"dist/index.js","types":"dist/index.d.ts","module":"dist/index.mjs","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"}},"gitHead":"24056caafd2ad4911d32565162dc762b4ddd1657","scripts":{"dev":"tsup src/index.ts --format cjs,esm --dts --watch","docs":"typedoc","lint":"eslint src --ext .ts","test":"vitest","bench":"vitest bench","build":"tsup src/index.ts --format cjs,esm --dts --clean","format":"prettier --write \"src/**/*.ts\"","lint:fix":"eslint src --ext .ts --fix","test:run":"vitest run","typecheck":"tsc --noEmit","example:qibla":"tsx examples/qibla.ts","test:coverage":"vitest run --coverage","prepublishOnly":"pnpm run build","example:inheritance":"tsx examples/inheritance.ts","example:prayer-times":"tsx examples/prayer-times.ts"},"_npmUser":{"name":"azkal182","email":"mohazkalarif@gmail.com"},"repository":{"url":"git+https://github.com/azkal182/islamic-utils.git","type":"git"},"_npmVersion":"11.6.2","description":"Accurate and consistent Islamic utilities library for prayer times, qibla direction, and inheritance calculation","directories":{},"_nodeVersion":"24.12.0","_hasShrinkwrap":false,"packageManager":"pnpm@10.26.1","devDependencies":{"tsx":"^4.21.0","tsup":"^8.5.1","eslint":"^9.39.2","vitest":"^4.0.16","typedoc":"^0.28.15","prettier":"^3.7.4","typescript":"^5.9.3","@types/node":"^25.0.3","@vitest/coverage-v8":"^4.0.16","typedoc-plugin-markdown":"^4.9.0","@typescript-eslint/parser":"^8.52.0","@typescript-eslint/eslint-plugin":"^8.52.0"},"_npmOperationalInternal":{"tmp":"tmp/islamic-utils_0.2.0_1767675770730_0.29029635377898755","host":"s3://npm-registry-packages-npm-production"}},"0.2.1":{"name":"@azkal182/islamic-utils","version":"0.2.1","keywords":["islamic","prayer-times","salat","sholat","qibla","kiblat","inheritance","faraidh","waris","muslim","imsak","dhuha"],"author":{"name":"azkal182"},"license":"MIT","_id":"@azkal182/islamic-utils@0.2.1","maintainers":[{"name":"azkal182","email":"mohazkalarif@gmail.com"}],"homepage":"https://github.com/azkal182/islamic-utils#readme","bugs":{"url":"https://github.com/azkal182/islamic-utils/issues"},"dist":{"shasum":"8df94793f5d2fc66059c33c6a5d64095b52a1153","tarball":"https://registry.npmjs.org/@azkal182/islamic-utils/-/islamic-utils-0.2.1.tgz","fileCount":8,"integrity":"sha512-Yg6kaJsjzY0Ay8lJeZunwLgtyYFCCMhuwyH0wtID/xiWZQyoQJlQzM3zDE11rBONc4ad9pcmovuAyoTtR7xQmg==","signatures":[{"sig":"MEUCIDB5RrUKPmFE9rdisFEKS/xANb35Mv9C8BBRITy5IHztAiEApjb756dQEuRGGOZwXA/xKYXLzfgSlYRJSkTEKLFsHLU=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":619763},"main":"dist/index.js","types":"dist/index.d.ts","module":"dist/index.mjs","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"}},"gitHead":"a30827e72f5e43f868fff9ce519ca224296e663c","scripts":{"dev":"tsup src/index.ts --format cjs,esm --dts --watch","docs":"typedoc","lint":"eslint src --ext .ts","test":"vitest","bench":"vitest bench","build":"tsup src/index.ts --format cjs,esm --dts --clean","format":"prettier --write \"src/**/*.ts\"","lint:fix":"eslint src --ext .ts --fix","test:run":"vitest run","typecheck":"tsc --noEmit","example:qibla":"tsx examples/qibla.ts","test:coverage":"vitest run --coverage","prepublishOnly":"pnpm run build","example:inheritance":"tsx examples/inheritance.ts","example:prayer-times":"tsx examples/prayer-times.ts"},"_npmUser":{"name":"azkal182","email":"mohazkalarif@gmail.com"},"repository":{"url":"git+https://github.com/azkal182/islamic-utils.git","type":"git"},"_npmVersion":"11.6.2","description":"Accurate and consistent Islamic utilities library for prayer times, qibla direction, and inheritance calculation","directories":{},"_nodeVersion":"24.12.0","_hasShrinkwrap":false,"packageManager":"pnpm@10.26.1","devDependencies":{"tsx":"^4.21.0","tsup":"^8.5.1","eslint":"^9.39.2","vitest":"^4.0.16","typedoc":"^0.28.15","prettier":"^3.7.4","typescript":"^5.9.3","@types/node":"^25.0.3","@vitest/coverage-v8":"^4.0.16","typedoc-plugin-markdown":"^4.9.0","@typescript-eslint/parser":"^8.52.0","@typescript-eslint/eslint-plugin":"^8.52.0"},"_npmOperationalInternal":{"tmp":"tmp/islamic-utils_0.2.1_1767695465693_0.6715759423602798","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"name":"@azkal182/islamic-utils","version":"0.3.0","description":"Accurate and consistent Islamic utilities library for prayer times, qibla direction, and inheritance calculation","main":"dist/index.js","module":"dist/index.mjs","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"},"./hijri-calendar":{"types":"./dist/hijri-calendar/index.d.ts","import":"./dist/hijri-calendar/index.mjs","require":"./dist/hijri-calendar/index.js"}},"scripts":{"dev":"tsup src/index.ts --format cjs,esm --dts --watch","build":"tsup src/index.ts --format cjs,esm --dts --clean","test":"vitest","test:run":"vitest run","test:coverage":"vitest run --coverage","lint":"eslint src","lint:fix":"eslint src --fix","format":"prettier --write \"src/**/*.ts\"","typecheck":"tsc --noEmit","example:prayer-times":"tsx examples/prayer-times.ts","example:qibla":"tsx examples/qibla.ts","example:inheritance":"tsx examples/inheritance.ts","bench":"vitest bench","docs":"typedoc","prepublishOnly":"pnpm run build"},"keywords":["islamic","prayer-times","salat","sholat","qibla","kiblat","inheritance","faraidh","waris","muslim","imsak","dhuha"],"author":{"name":"azkal182"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/azkal182/islamic-utils.git"},"homepage":"https://github.com/azkal182/islamic-utils#readme","bugs":{"url":"https://github.com/azkal182/islamic-utils/issues"},"engines":{"node":">=18"},"packageManager":"pnpm@10.26.1","devDependencies":{"@types/node":"^25.0.3","@typescript-eslint/eslint-plugin":"^8.52.0","@typescript-eslint/parser":"^8.52.0","@vitest/coverage-v8":"^4.0.16","eslint":"^9.39.2","prettier":"^3.7.4","tsup":"^8.5.1","tsx":"^4.21.0","typedoc":"^0.28.15","typedoc-plugin-markdown":"^4.9.0","typescript":"^5.9.3","vitest":"^4.0.16"},"gitHead":"f23c83eafdffe7c7164dc3273d0dd7f8988cd321","_id":"@azkal182/islamic-utils@0.3.0","_nodeVersion":"24.12.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-ZvXU4wXpm8s0DnZIOlE9N3GHrtOKB+T2z6yfs8oaiNOJoDalVCa3c0lvKZH9OCn7VotYR155kS4TrTtOLLPHUg==","shasum":"b324c398d46f24dfb26202614d4816d865132ee9","tarball":"https://registry.npmjs.org/@azkal182/islamic-utils/-/islamic-utils-0.3.0.tgz","fileCount":8,"unpackedSize":1090991,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDEBke7pPZOhLA1pEjShJbCu/7hqpPTobNHY/oSh7XJZQIgUIj1uOWMegtt+5lWKRs/ZvFHegCVBjg5RDjzL8d0mRk="}]},"_npmUser":{"name":"azkal182","email":"mohazkalarif@gmail.com"},"directories":{},"maintainers":[{"name":"azkal182","email":"mohazkalarif@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/islamic-utils_0.3.0_1768206005698_0.9565320590881328"},"_hasShrinkwrap":false}},"time":{"created":"2026-01-05T21:53:06.567Z","modified":"2026-01-12T08:20:06.079Z","0.1.0":"2026-01-05T21:53:06.852Z","0.2.0":"2026-01-06T05:02:50.901Z","0.2.1":"2026-01-06T10:31:05.859Z","0.3.0":"2026-01-12T08:20:05.910Z"},"bugs":{"url":"https://github.com/azkal182/islamic-utils/issues"},"author":{"name":"azkal182"},"license":"MIT","homepage":"https://github.com/azkal182/islamic-utils#readme","keywords":["islamic","prayer-times","salat","sholat","qibla","kiblat","inheritance","faraidh","waris","muslim","imsak","dhuha"],"repository":{"type":"git","url":"git+https://github.com/azkal182/islamic-utils.git"},"description":"Accurate and consistent Islamic utilities library for prayer times, qibla direction, and inheritance calculation","maintainers":[{"name":"azkal182","email":"mohazkalarif@gmail.com"}],"readme":"# Islamic Utilities Library\r\n\r\n> Accurate and consistent Islamic utilities for prayer times, qibla direction, and inheritance calculation.\r\n\r\n[![npm version](https://img.shields.io/npm/v/@azkal182/islamic-utils.svg)](https://www.npmjs.com/package/@azkal182/islamic-utils)\r\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\r\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)\r\n\r\n## ✨ Features\r\n\r\n| Module | Status | Description |\r\n|--------|--------|-------------|\r\n| 🕌 **Prayer Times** | ✅ Complete | 9 prayer times with 13+ calculation methods |\r\n| 🧭 **Qibla Direction** | ✅ Complete | Bearing and distance to Ka'bah |\r\n| 📜 **Inheritance (Faraidh)** | ✅ Complete | 30+ heir types, hijab, aul, radd, special cases |\r\n| 🗓️ **Hijri Calendar** | ✅ Complete | Gregorian ↔ Hijri conversion, monthly calendar, adjustments |\r\n\r\n## 📦 Installation\r\n\r\n```bash\r\nnpm install @azkal182/islamic-utils\r\n# or\r\npnpm add @azkal182/islamic-utils\r\n# or\r\nyarn add @azkal182/islamic-utils\r\n```\r\n\r\n## 🚀 Quick Start\r\n\r\n### Prayer Times\r\n\r\n```typescript\r\nimport { computePrayerTimes, CALCULATION_METHODS } from '@azkal182/islamic-utils';\r\n\r\nconst result = computePrayerTimes(\r\n  { latitude: -6.2088, longitude: 106.8456 }, // Jakarta\r\n  { date: { year: 2024, month: 1, day: 15 }, timezone: 7 },\r\n  { method: CALCULATION_METHODS.KEMENAG }\r\n);\r\n\r\nif (result.success) {\r\n  console.log('Fajr:', result.data.formatted.fajr);       // \"04:24\"\r\n  console.log('Maghrib:', result.data.formatted.maghrib); // \"18:15\"\r\n}\r\n```\r\n\r\n### Qibla Direction\r\n\r\n```typescript\r\nimport { computeQiblaDirection } from '@azkal182/islamic-utils';\r\n\r\nconst result = computeQiblaDirection({\r\n  coordinates: { latitude: -6.2088, longitude: 106.8456 }\r\n});\r\n\r\nif (result.success) {\r\n  console.log(`Qibla: ${result.data.bearing}°`);          // \"295.15°\"\r\n  console.log(`Direction: ${result.data.compassDirection}`); // \"WNW\"\r\n}\r\n```\r\n\r\n### Inheritance (Faraidh)\r\n\r\n```typescript\r\nimport { computeInheritance, HeirType } from '@azkal182/islamic-utils';\r\n\r\nconst result = computeInheritance({\r\n  estate: {\r\n    grossValue: 1_000_000_000,\r\n    debts: 50_000_000,\r\n    wasiyyah: 100_000_000,\r\n  },\r\n  heirs: [\r\n    { type: HeirType.WIFE, count: 1 },\r\n    { type: HeirType.SON, count: 2 },\r\n    { type: HeirType.DAUGHTER, count: 1 },\r\n  ],\r\n  deceased: { gender: 'male' },\r\n});\r\n\r\nif (result.success) {\r\n  console.log(`Net Estate: ${result.data.netEstate}`);\r\n  for (const share of result.data.shares) {\r\n    console.log(`${share.heirType}: ${share.totalValue}`);\r\n  }\r\n}\r\n```\r\n\r\n### Hijri Calendar\r\n\r\n```typescript\r\nimport { computeHijriDate } from '@azkal182/islamic-utils/hijri-calendar';\r\n\r\nconst result = computeHijriDate(\r\n  { date: { year: 2025, month: 3, day: 15 } },\r\n  { method: 'ummul_qura' }\r\n);\r\n\r\nif (result.success) {\r\n  console.log(result.data.hijri);\r\n}\r\n```\r\n\r\n---\r\n\r\n## 🕌 Prayer Times Module\r\n\r\n### Overview\r\n\r\nCalculate 9 daily prayer times with support for:\r\n- **13+ calculation methods** from major Islamic organizations\r\n- **High latitude handling** for regions above 48.5°\r\n- **Asr madhhab options** (Standard/Hanafi)\r\n- **Time adjustments** and rounding options\r\n- **Trace mode** for debugging\r\n\r\n### 9 Prayer Times\r\n\r\n| Time | Arabic | Description |\r\n|------|--------|-------------|\r\n| `imsak` | الإمساك | Time to stop eating before Fajr |\r\n| `fajr` | الفجر | Dawn prayer |\r\n| `sunrise` | الشروق | Sunrise (Isyraq) |\r\n| `dhuha_start` | بداية الضحى | Start of Dhuha window |\r\n| `dhuha_end` | نهاية الضحى | End of Dhuha window |\r\n| `dhuhr` | الظهر | Noon prayer |\r\n| `asr` | العصر | Afternoon prayer |\r\n| `maghrib` | المغرب | Sunset prayer |\r\n| `isha` | العشاء | Night prayer |\r\n\r\n### 13 Calculation Methods\r\n\r\n| Method | Fajr | Isha | Region |\r\n|--------|------|------|--------|\r\n| `MWL` | 18° | 17° | Muslim World League |\r\n| `ISNA` | 15° | 15° | North America |\r\n| `EGYPT` | 19.5° | 17.5° | Egypt, Africa |\r\n| `MAKKAH` | 18.5° | 90 min | Saudi Arabia |\r\n| `KARACHI` | 18° | 18° | Pakistan, India |\r\n| `TEHRAN` | 17.7° | 14° | Iran |\r\n| `JAKIM` | 20° | 18° | Malaysia |\r\n| `SINGAPORE` | 20° | 18° | Singapore |\r\n| `KEMENAG` | 20° | 18° | Indonesia |\r\n| `DIYANET` | 18° | 17° | Turkey |\r\n| `UOIF` | 12° | 12° | France |\r\n| `KUWAIT` | 18° | 17.5° | Kuwait |\r\n| `QATAR` | 18° | 90 min | Qatar |\r\n\r\n### Advanced Options\r\n\r\n```typescript\r\nimport {\r\n  computePrayerTimes,\r\n  CALCULATION_METHODS,\r\n  AsrMadhhab,\r\n  HighLatitudeRule,\r\n  PrayerRoundingRule\r\n} from '@azkal182/islamic-utils';\r\n\r\nconst result = computePrayerTimes(\r\n  { latitude: 59.3293, longitude: 18.0686 }, // Stockholm\r\n  { date: { year: 2024, month: 6, day: 21 }, timezone: 2 },\r\n  {\r\n    method: CALCULATION_METHODS.MWL,\r\n    asrMadhhab: AsrMadhhab.HANAFI,           // Hanafi Asr calculation\r\n    highLatitudeRule: HighLatitudeRule.MIDDLE_OF_NIGHT,\r\n  },\r\n  {\r\n    includeTrace: true,                       // Debug trace\r\n  }\r\n);\r\n```\r\n\r\n### Asr Calculation Methods\r\n\r\n| Method | Shadow Factor | Used By |\r\n|--------|---------------|---------|\r\n| `AsrMadhhab.STANDARD` | 1× object length | Shafi'i, Maliki, Hanbali |\r\n| `AsrMadhhab.HANAFI` | 2× object length | Hanafi |\r\n\r\n### High Latitude Rules\r\n\r\nFor locations above ~48.5° where sun may not reach required angles:\r\n\r\n| Rule | Description |\r\n|------|-------------|\r\n| `NONE` | Return null if time cannot be calculated |\r\n| `MIDDLE_OF_NIGHT` | Split night from Maghrib to Fajr |\r\n| `ONE_SEVENTH` | Night portion = 1/7 of total night |\r\n| `ANGLE_BASED` | Proportional to angle vs night duration |\r\n\r\n### Monthly Prayer Times\r\n\r\nCalculate prayer times for an entire month with a single function call:\r\n\r\n```typescript\r\nimport { computeMonthlyPrayerTimes, CALCULATION_METHODS } from '@azkal182/islamic-utils';\r\n\r\nconst result = computeMonthlyPrayerTimes({\r\n  year: 2024,\r\n  month: 3,  // March\r\n  location: { latitude: -6.2088, longitude: 106.8456 },\r\n  timezone: 7,\r\n  params: { method: CALCULATION_METHODS.KEMENAG },\r\n});\r\n\r\nif (result.success) {\r\n  // Access all days\r\n  console.log(`Days in month: ${result.data.meta.daysInMonth}`);\r\n\r\n  // Iterate through each day\r\n  for (const day of result.data.days) {\r\n    console.log(`Day ${day.day}: Fajr ${day.formatted.fajr}, Maghrib ${day.formatted.maghrib}`);\r\n  }\r\n\r\n  // Access specific day (0-indexed)\r\n  const day15 = result.data.days[14]; // Day 15\r\n  console.log(`Day 15 Fajr: ${day15.formatted.fajr}`);\r\n}\r\n```\r\n\r\n**Return Type:**\r\n\r\n```typescript\r\ninterface MonthlyPrayerTimesResult {\r\n  days: Array<{\r\n    day: number;           // 1-31\r\n    date: DateOnly;        // { year, month, day }\r\n    times: PrayerTimes;    // Fractional hours\r\n    formatted: PrayerTimeStrings; // \"HH:MM\" format\r\n  }>;\r\n  meta: {\r\n    year: number;\r\n    month: number;\r\n    daysInMonth: number;\r\n    isLeapYear: boolean;\r\n    location: LocationInput;\r\n    timezone: Timezone;\r\n    method: CalculationMethod;\r\n  };\r\n}\r\n```\r\n\r\n### Next Prayer Time\r\n\r\nDetermine the next upcoming prayer based on current time:\r\n\r\n```typescript\r\nimport {\r\n  getNextPrayer,\r\n  getCurrentPrayer,\r\n  formatMinutesUntil,\r\n  CALCULATION_METHODS\r\n} from '@azkal182/islamic-utils';\r\n\r\n// Simple API - calculates everything automatically!\r\nconst result = getNextPrayer(\r\n  { latitude: -6.2088, longitude: 106.8456 },\r\n  'Asia/Jakarta',\r\n  { method: CALCULATION_METHODS.KEMENAG }\r\n  // currentTime defaults to new Date()\r\n);\r\n\r\nif (result.success) {\r\n  console.log(`Next: ${result.data.name}`);                    // \"maghrib\"\r\n  console.log(`Time: ${result.data.time}`);                    // \"18:07\"\r\n  console.log(`In: ${formatMinutesUntil(result.data.minutesUntil)}`);  // \"1h 30m\"\r\n\r\n  if (result.data.isNextDay) {\r\n    console.log('(Tomorrow)');\r\n  }\r\n\r\n  // Prayer times are included in the result\r\n  console.log(result.data.prayerTimes.formatted);\r\n}\r\n\r\n// Get current prayer period\r\nconst current = getCurrentPrayer(\r\n  { latitude: -6.2088, longitude: 106.8456 },\r\n  'Asia/Jakarta',\r\n  { method: CALCULATION_METHODS.KEMENAG }\r\n);\r\n\r\nif (current.success && current.data.current) {\r\n  console.log(`Current period: ${current.data.current}`);    // \"asr\"\r\n}\r\n```\r\n\r\n**Return Types:**\r\n\r\n```typescript\r\ninterface NextPrayerInfo {\r\n  name: PrayerName;           // \"maghrib\"\r\n  time: string;               // \"18:07\"\r\n  timeNumeric: number;        // 18.12 (fractional hours)\r\n  minutesUntil: number;       // 90\r\n  isNextDay: boolean;         // true if past Isha\r\n  prayerTimes: PrayerTimesResult;  // Full prayer times for today\r\n}\r\n\r\ninterface CurrentPrayerInfo {\r\n  current: PrayerName | null;  // Current prayer period\r\n  previous: PrayerName | null; // Previous prayer\r\n  prayerTimes: PrayerTimesResult;\r\n}\r\n```\r\n\r\n### Timezone Support\r\n\r\nAll functions support both **IANA timezone names** and **UTC offsets**:\r\n\r\n```typescript\r\n// IANA timezone (recommended) - handles DST automatically\r\ntimezone: 'Asia/Jakarta'\r\ntimezone: 'America/New_York'\r\ntimezone: 'Europe/London'\r\n\r\n// UTC offset (simple)\r\ntimezone: 7     // UTC+7\r\ntimezone: -5    // UTC-5\r\ntimezone: 5.5   // UTC+5:30 (India)\r\n```\r\n\r\n---\r\n\r\n\r\n## 🧭 Qibla Direction Module\r\n\r\n### Overview\r\n\r\nCalculate the direction (bearing) from any location on Earth to the Ka'bah in Makkah using great circle navigation.\r\n\r\n### Basic Usage\r\n\r\n```typescript\r\nimport { computeQiblaDirection } from '@azkal182/islamic-utils';\r\n\r\nconst result = computeQiblaDirection({\r\n  coordinates: { latitude: -6.2088, longitude: 106.8456 } // Jakarta\r\n});\r\n\r\nif (result.success) {\r\n  console.log(`Bearing: ${result.data.bearing}°`);           // 295.15\r\n  console.log(`Compass: ${result.data.compassDirection}`);   // \"WNW\"\r\n}\r\n```\r\n\r\n### With Distance Calculation\r\n\r\n```typescript\r\nconst result = computeQiblaDirection(\r\n  { coordinates: { latitude: -6.2088, longitude: 106.8456 } },\r\n  { includeDistance: true, includeTrace: true }\r\n);\r\n\r\nif (result.success) {\r\n  console.log(`Distance: ${result.data.meta.distance} km`); // 7920.14\r\n  console.log(`At Ka'bah: ${result.data.meta.atKaaba}`);    // false\r\n}\r\n```\r\n\r\n### 16-Point Compass Directions\r\n\r\nThe module returns compass directions: `N`, `NNE`, `NE`, `ENE`, `E`, `ESE`, `SE`, `SSE`, `S`, `SSW`, `SW`, `WSW`, `W`, `WNW`, `NW`, `NNW`\r\n\r\n### Great Circle Utilities\r\n\r\n```typescript\r\nimport {\r\n  calculateInitialBearing,\r\n  calculateFinalBearing,\r\n  calculateGreatCircleDistance,\r\n  calculateMidpoint\r\n} from '@azkal182/islamic-utils';\r\n\r\n// Calculate bearing between two points\r\nconst bearing = calculateInitialBearing(\r\n  { latitude: -6.2, longitude: 106.8 },\r\n  { latitude: 21.4, longitude: 39.8 }\r\n);\r\n```\r\n\r\n---\r\n\r\n## 📜 Inheritance (Faraidh) Module\r\n\r\n### Overview\r\n\r\nComplete Islamic inheritance calculator implementing classical fiqh rules:\r\n\r\n- **30+ Heir Types** - All Quranic and Sunnah-defined heirs\r\n- **7 Hijab Rules** - Heir blocking/exclusion rules\r\n- **10 Special Cases** - Including Umariyatayn, Mushtarakah, Akdariyyah\r\n- **Aul & Radd** - Over-subscription and remainder handling\r\n- **Wasiyyah Limits** - Automatic 1/3 cap enforcement\r\n- **Fraction Utilities** - Precise calculations without floating-point errors\r\n\r\n### Heir Types (30+)\r\n\r\n#### Primary Heirs (Ashab al-Furudh & Asabah)\r\n\r\n| Category | Types | Arabic |\r\n|----------|-------|--------|\r\n| **Spouse** | `HUSBAND`, `WIFE` | الزوج، الزوجة |\r\n| **Parents** | `FATHER`, `MOTHER` | الأب، الأم |\r\n| **Grandparents** | `GRANDFATHER_PATERNAL`, `GRANDMOTHER_MATERNAL`, `GRANDMOTHER_PATERNAL` | الجد، الجدة |\r\n| **Children** | `SON`, `DAUGHTER` | الابن، البنت |\r\n| **Grandchildren** | `GRANDSON_SON`, `GRANDDAUGHTER_SON` | ابن الابن، بنت الابن |\r\n\r\n#### Siblings\r\n\r\n| Type | Arabic | Description |\r\n|------|--------|-------------|\r\n| `BROTHER_FULL` | الأخ الشقيق | Same father and mother |\r\n| `SISTER_FULL` | الأخت الشقيقة | Same father and mother |\r\n| `BROTHER_PATERNAL` | الأخ لأب | Same father only |\r\n| `SISTER_PATERNAL` | الأخت لأب | Same father only |\r\n| `BROTHER_UTERINE` | الأخ لأم | Same mother only |\r\n| `SISTER_UTERINE` | الأخت لأم | Same mother only |\r\n\r\n#### Extended Asabah\r\n\r\n| Category | Types |\r\n|----------|-------|\r\n| **Nephews** | `NEPHEW_FULL`, `NEPHEW_PATERNAL` |\r\n| **Uncles** | `UNCLE_FULL`, `UNCLE_PATERNAL` |\r\n| **Cousins** | `COUSIN_FULL`, `COUSIN_PATERNAL` |\r\n\r\n### Fixed Shares (Furudh)\r\n\r\n| Share | Arabic | Recipients |\r\n|-------|--------|------------|\r\n| **1/2** (النصف) | Husband (no child), Single daughter, Single full/paternal sister |\r\n| **1/4** (الربع) | Husband (with child), Wife (no child) |\r\n| **1/8** (الثمن) | Wife (with child) |\r\n| **1/3** (الثلث) | Mother (no child, <2 siblings), 2+ uterine siblings |\r\n| **1/6** (السدس) | Father (with child), Mother (with child), Grandmother, Granddaughters with daughter |\r\n| **2/3** (الثلثان) | 2+ daughters, 2+ full/paternal sisters |\r\n\r\n### Asabah (Residuary Heirs)\r\n\r\n| Type | Arabic | Description |\r\n|------|--------|-------------|\r\n| **Asabah bi Nafs** | عصبة بالنفس | Male heirs who take remainder alone |\r\n| **Asabah bil Ghayr** | عصبة بالغير | Females with male siblings (2:1 ratio) |\r\n| **Asabah maal Ghayr** | عصبة مع الغير | Sisters with daughters |\r\n\r\n### Hijab (Blocking) Rules\r\n\r\n7 total exclusion rules implemented:\r\n\r\n| Rule | Blocker | Blocked Heirs |\r\n|------|---------|---------------|\r\n| E1 | Son/Daughter | All siblings |\r\n| E2 | Father | Grandfather, all siblings, uncles, nephews, cousins |\r\n| E3 | Son | Grandsons, Granddaughters |\r\n| E4 | Mother | Maternal grandmother |\r\n| E5 | Father | Paternal grandmother |\r\n| E6 | Full brother | Paternal siblings |\r\n| E7 | Paternal brother | Nephews |\r\n\r\n### Special Cases (10)\r\n\r\n| Case | Arabic | Condition |\r\n|------|--------|-----------|\r\n| **Umariyatayn** | العُمَرِيَّتَان | Spouse + Mother + Father, no descendant |\r\n| **Mushtarakah** | المُشْتَرَكَة | Husband + Mother + 2+ uterine siblings + full siblings |\r\n| **Akdariyyah** | الأكدرية | Husband + Mother + Grandfather + 1 full sister |\r\n| **Maal Ghayr** | عصبة مع الغير | Daughter(s) + sisters (no son) |\r\n| **Completion 2/3** | تكملة الثلثين | 1 daughter + granddaughters |\r\n\r\n### Estate Deductions\r\n\r\nDeductions are applied in Islamic order:\r\n\r\n```typescript\r\nconst result = computeInheritance({\r\n  estate: {\r\n    grossValue: 1_000_000_000,     // Total harta\r\n    funeralCosts: 50_000_000,      // 1. Biaya jenazah (first)\r\n    debts: 100_000_000,            // 2. Hutang (second)\r\n    wasiyyah: 200_000_000,         // 3. Wasiat (max 1/3 of remainder)\r\n    wasiyyahApprovedByHeirs: false, // If true, wasiyyah can exceed 1/3\r\n    currency: 'IDR',\r\n  },\r\n  heirs: [...],\r\n  deceased: { gender: 'male' },\r\n});\r\n```\r\n\r\n### Trace Mode\r\n\r\nFor debugging and verification:\r\n\r\n```typescript\r\nconst result = computeInheritance(\r\n  { estate: {...}, heirs: [...], deceased: {...} },\r\n  { includeTrace: true }\r\n);\r\n\r\nif (result.success) {\r\n  for (const step of result.data.trace) {\r\n    console.log(`[${step.phase}] ${step.description}`);\r\n    if (step.arabicTerm) console.log(`  Arabic: ${step.arabicTerm}`);\r\n  }\r\n}\r\n```\r\n\r\n### Full Example\r\n\r\n```typescript\r\nimport {\r\n  computeInheritance,\r\n  HeirType,\r\n  getHeirArabicName,\r\n} from '@azkal182/islamic-utils';\r\n\r\nconst result = computeInheritance({\r\n  estate: {\r\n    grossValue: 600_000_000,\r\n    debts: 50_000_000,\r\n    wasiyyah: 50_000_000,\r\n  },\r\n  heirs: [\r\n    { type: HeirType.WIFE, count: 1 },\r\n    { type: HeirType.FATHER, count: 1 },\r\n    { type: HeirType.MOTHER, count: 1 },\r\n    { type: HeirType.SON, count: 1 },\r\n    { type: HeirType.DAUGHTER, count: 2 },\r\n  ],\r\n  deceased: { gender: 'male' },\r\n});\r\n\r\nif (result.success) {\r\n  const data = result.data;\r\n\r\n  console.log('=== Estate Summary ===');\r\n  console.log(`Gross Value: ${data.meta.estate.grossValue}`);\r\n  console.log(`Net Estate:  ${data.netEstate}`);\r\n\r\n  console.log('\\n=== Heir Shares ===');\r\n  for (const share of data.shares) {\r\n    if (share.isBlocked) {\r\n      console.log(`${share.heirType}: BLOCKED by ${share.blockedBy}`);\r\n    } else {\r\n      const arabic = getHeirArabicName(share.heirType);\r\n      console.log(`${share.heirType} (${arabic})`);\r\n      console.log(`  Category: ${share.category}`);\r\n      console.log(`  Total: ${share.totalValue}`);\r\n      console.log(`  Per Person: ${share.perPersonValue}`);\r\n    }\r\n  }\r\n\r\n  console.log('\\n=== Summary ===');\r\n  console.log(`Aul Applied: ${data.summary.aulApplied}`);\r\n  console.log(`Radd Applied: ${data.summary.raddApplied}`);\r\n  console.log(`Special Case: ${data.summary.specialCase || 'None'}`);\r\n  console.log(`Valid: ${data.verification.isValid}`);\r\n}\r\n```\r\n\r\n---\r\n\r\n## 🎯 Result Pattern\r\n\r\nAll library functions return a `Result<T>` type (similar to Rust):\r\n\r\n```typescript\r\ntype Result<T> = SuccessResult<T> | ErrorResult;\r\n\r\ninterface SuccessResult<T> {\r\n  success: true;\r\n  data: T;\r\n  trace?: TraceStep[];\r\n}\r\n\r\ninterface ErrorResult {\r\n  success: false;\r\n  error: LibraryError;\r\n  trace?: TraceStep[];\r\n}\r\n```\r\n\r\n### Usage\r\n\r\n```typescript\r\nconst result = computePrayerTimes(...);\r\n\r\nif (result.success) {\r\n  // TypeScript knows result.data exists\r\n  console.log(result.data.times.fajr);\r\n} else {\r\n  // TypeScript knows result.error exists\r\n  console.error(result.error.message);\r\n}\r\n\r\n// Or use utility functions\r\nimport { unwrap, unwrapOr, isSuccess, isError } from '@azkal182/islamic-utils';\r\n\r\nconst data = unwrap(result);              // Throws on error\r\nconst data = unwrapOr(result, fallback);  // Returns fallback on error\r\n```\r\n\r\n---\r\n\r\n## 📊 Performance\r\n\r\n| Module | Operation | Speed |\r\n|--------|-----------|-------|\r\n| Prayer Times | Single calculation | ~97,500 ops/sec |\r\n| Prayer Times | Year (365 days) | ~264 ops/sec |\r\n| Qibla | Single calculation | ~500,000+ ops/sec |\r\n| Inheritance | Simple case | ~50,000+ ops/sec |\r\n| Inheritance | Complex case | ~25,000+ ops/sec |\r\n\r\n---\r\n\r\n## 🎨 Design Principles\r\n\r\n- **Language-Agnostic** - Pure algorithms without platform dependencies\r\n- **Deterministic** - Same input always produces same output\r\n- **Explainable** - Results include optional trace for verification\r\n- **Modular** - Each module can be used independently\r\n- **No I/O** - All external data provided by the caller\r\n- **Type-Safe** - Full TypeScript support with strict types\r\n\r\n---\r\n\r\n## 🗺️ Roadmap\r\n\r\n### ✅ Completed (v0.2.0)\r\n\r\n- Prayer Times with 13 methods\r\n- Qibla Direction with great circle navigation\r\n- Inheritance (Faraidh) with 30+ heir types\r\n- Hijab, Furudh, Asabah, Aul, Radd rules\r\n- Special cases (Umariyatayn, Mushtarakah)\r\n- TypeDoc API documentation\r\n- Performance benchmarks\r\n\r\n### 🔜 Planned Features\r\n\r\n| Feature | Description | Priority |\r\n|---------|-------------|----------|\r\n| **Gono Gini** | Marital property (harta bersama) calculation before inheritance | High |\r\n| **Dhawil Arham** | Complete distant relative distribution | Medium |\r\n| **Grandfather Competition** | Full grandfather with siblings calculation | Medium |\r\n| **Hijri Calendar** | Hijri date conversion and calculation | Medium |\r\n| **Zakat Calculator** | Zakat calculation for various assets | Low |\r\n| **Fasting Calendar** | Ramadan and voluntary fasting calculator | Low |\r\n\r\n### 🔜 Gono Gini (Planned)\r\n\r\nSupport for Indonesian marital property law:\r\n\r\n```typescript\r\n// Future API (planned)\r\nconst result = computeInheritance({\r\n  estate: {\r\n    jointProperty: 600_000_000,    // Harta bersama (gono gini)\r\n    separateProperty: 400_000_000, // Harta bawaan mayit\r\n    // ...\r\n  },\r\n  // ...\r\n});\r\n\r\n// Joint property split 50:50 before inheritance\r\n// Survivor gets: 300M (their half)\r\n// Inheritance: 300M + 400M = 700M\r\n```\r\n\r\n---\r\n\r\n## 📁 Examples\r\n\r\nSee [examples/](./examples/) for complete usage examples:\r\n\r\n- [prayer-times.ts](./examples/prayer-times.ts) - Prayer Times features\r\n- [qibla.ts](./examples/qibla.ts) - Qibla Direction features\r\n- [inheritance.ts](./examples/inheritance.ts) - Inheritance (Faraidh) features\r\n\r\nRun examples:\r\n```bash\r\npnpm run example:prayer-times\r\npnpm run example:qibla\r\npnpm run example:inheritance\r\n```\r\n\r\n---\r\n\r\n## 📖 API Documentation\r\n\r\nFull API documentation generated with TypeDoc:\r\n\r\n```bash\r\npnpm run docs\r\n```\r\n\r\nDocumentation is generated at `docs/api/`.\r\n\r\n---\r\n\r\n## 🧪 Testing\r\n\r\n```bash\r\npnpm test           # Run tests in watch mode\r\npnpm test:run       # Run tests once\r\npnpm test:coverage  # Run with coverage\r\npnpm bench          # Run benchmarks\r\n```\r\n\r\n---\r\n\r\n## 📄 License\r\n\r\nMIT © 2024\r\n\r\n---\r\n\r\n## 🤝 Contributing\r\n\r\nContributions are welcome! Please read the [Contributing Guide](./CONTRIBUTING.md) for details.\r\n\r\n## 🙏 Acknowledgments\r\n\r\n- Islamic calculation methods from major organizations worldwide\r\n- Classical fiqh sources for inheritance rules\r\n","readmeFilename":"README.md"}