Islamic Utils

A comprehensive Dart/Flutter package for Islamic utilities including prayer times calculation, Qibla direction, and inheritance (Faraidh) distribution.

Features

• 🕌 Prayer Times - Calculate 9 prayer times with 18+ calculation methods
• 🧭 Qibla Direction - Get bearing and distance to Ka'bah
• 💰 Inheritance (Faraidh) - Complete Islamic inheritance calculation

Installation

Add to your pubspec.yaml:

dependencies:
  islamic_utils: ^1.0.0

Quick Start

import 'package:islamic_utils/islamic_utils.dart';

void main() {
  // Prayer Times
  final prayers = computePrayerTimes(
    location: Coordinates(latitude: -6.2088, longitude: 106.8456),
    date: DateOnly.now(),
    timezone: 7, // WIB
    params: PrayerCalculationParams(method: CalculationMethods.kemenag),
  );

  if (prayers.isSuccess) {
    print('Fajr: ${prayers.unwrap().formatted[PrayerName.fajr]}');
    print('Dhuhr: ${prayers.unwrap().formatted[PrayerName.dhuhr]}');
  }

  // Qibla Direction
  final qibla = computeQiblaDirection(
    coordinates: Coordinates(latitude: -6.2088, longitude: 106.8456),
    includeDistance: true,
  );

  if (qibla.isSuccess) {
    print('Qibla: ${qibla.unwrap().bearing.toStringAsFixed(1)}°');
    print('Direction: ${qibla.unwrap().compassDirection.displayName}');
  }

  // Inheritance
  final inheritance = computeInheritance(
    estate: EstateInput(grossValue: 1000000000),
    heirs: [
      HeirInput(type: HeirType.wife, count: 1),
      HeirInput(type: HeirType.son, count: 2),
    ],
    deceased: DeceasedInfo(gender: Gender.male),
  );

  if (inheritance.isSuccess) {
    for (final share in inheritance.unwrap().shares) {
      print('${share.heirType.name}: ${share.totalValue}');
    }
  }
}

---

Prayer Times

Calculation Methods

Method	Fajr Angle	Isha	Regions
kemenag	20°	18°	Indonesia
mwl	18°	17°	Europe, Far East
isna	15°	15°	North America
makkah	18.5°	90 min	Arabian Peninsula
egypt	19.5°	17.5°	Africa, Middle East
karachi	18°	18°	Pakistan, India
tehran	17.7°	14°	Iran
singapore	20°	18°	Singapore, Malaysia

Parameters

PrayerCalculationParams(
  method: CalculationMethods.kemenag,
  asrMadhhab: AsrMadhhab.standard,      // or .hanafi
  highLatitudeRule: HighLatitudeRule.middleOfNight,
  roundingRule: PrayerRoundingRule.nearest,
  safetyBufferMinutes: 2,               // Add safety margin
  adjustments: {PrayerName.fajr: 2},    // Manual adjustments
)

High Latitude Rules

For locations above 48°N/S where Fajr/Isha may not occur:

Rule	Description
none	No adjustment (times may be null)
middleOfNight	Based on middle of night
oneSeventh	1/7 of night duration
angleBased	Proportional to angle

Monthly & Next Prayer

// Get monthly schedule
final monthly = computeMonthlyPrayerTimes(
  year: 2024, month: 3,
  location: Coordinates(latitude: -6.2088, longitude: 106.8456),
  timezone: 7,
  params: PrayerCalculationParams(method: CalculationMethods.kemenag),
);

// Get next prayer
final next = getNextPrayer(
  location: Coordinates(latitude: -6.2088, longitude: 106.8456),
  timezone: 7,
  params: PrayerCalculationParams(method: CalculationMethods.kemenag),
);

---

Qibla Direction

final qibla = computeQiblaDirection(
  coordinates: Coordinates(latitude: -6.2088, longitude: 106.8456),
  includeDistance: true,
);

print('Bearing: ${qibla.unwrap().bearing}°');           // 294.7°
print('Compass: ${qibla.unwrap().compassDirection}');   // WNW
print('Distance: ${qibla.unwrap().meta.distance} km'); // ~7920 km

Reference Bearings

Location	Bearing
Jakarta, Indonesia	295° (WNW)
New York, USA	58° (ENE)
London, UK	119° (ESE)
Sydney, Australia	277° (W)
Tokyo, Japan	293° (WNW)

---

Inheritance (Faraidh)

Basic Example

final result = computeInheritance(
  estate: EstateInput(
    grossValue: 1000000000,
    debts: 50000000,
    funeralCosts: 10000000,
    wasiyyah: 100000000,  // Max 1/3 unless approved
  ),
  heirs: [
    HeirInput(type: HeirType.wife, count: 1),
    HeirInput(type: HeirType.son, count: 2),
    HeirInput(type: HeirType.daughter, count: 1),
  ],
  deceased: DeceasedInfo(gender: Gender.male),
);

Heir Types

Category	Types
Spouse	husband, wife
Ascendants	father, mother, grandfatherPaternal, grandmotherMaternal, grandmotherPaternal
Descendants	son, daughter, grandsonSon, granddaughterSon
Siblings	brotherFull, sisterFull, brotherPaternal, sisterPaternal, brotherUterine, sisterUterine
Extended	nephewFull, uncleFull, cousinFull, etc.

Special Cases

The library automatically detects and applies special cases:

Case	Description
Umariyatayn	Spouse + Father + Mother (Mother gets 1/3 of remainder)
Mushtarakah	Full siblings share with uterine siblings
Akdariyyah	Husband + Mother + Grandfather + Sister
Aul	Shares exceed 100% (proportional reduction)
Radd	Shares under 100% (redistribution)

Trace Output (Debugging)

final result = computeInheritance(
  estate: EstateInput(grossValue: 1000000000),
  heirs: [...],
  deceased: DeceasedInfo(gender: Gender.male),
  includeTrace: true,  // Enable trace
);

// Print trace steps
for (final step in result.unwrap().trace!) {
  print('[${step.step}] ${step.category}: ${step.description}');
}

---

Core Types

Result Pattern

All calculations return Result<T>:

final result = computePrayerTimes(...);

// Check success
if (result.isSuccess) {
  final times = result.unwrap();
} else {
  final error = result.errorOrNull;
}

// Or use map
result.map((times) => print(times.formatted));

// With default
final times = result.unwrapOr(defaultTimes);

Coordinates

final location = Coordinates(
  latitude: -6.2088,
  longitude: 106.8456,
  altitude: 10, // optional, meters
);

// Validation
if (!location.isValid) { ... }

// Ka'bah constant
const kaaba = Coordinates.kaaba;

DateOnly

final date = DateOnly(year: 2024, month: 1, day: 15);
final today = DateOnly.now();
final tomorrow = today.nextDay;
final nextWeek = today.addDays(7);

print(date.isLeapYear);   // false
print(date.daysInMonth);  // 31

Fraction

final half = Fraction(1, 2);
final third = Fraction.oneThird;

final sum = half + third;           // 5/6
final product = half * third;       // 1/6
print(half.toDouble());             // 0.5
print(half.simplified.toString());  // 1/2

---

API Reference

Generate API documentation:

dart doc .

View at doc/api/index.html

---

License

MIT License - see LICENSE for details.

---

Contributing

Contributions welcome! Please read the contribution guidelines first.

Acknowledgments

• Astronomical algorithms based on Jean Meeus' "Astronomical Algorithms"
• Prayer time calculations reference PrayTimes.org
• Islamic inheritance rules based on classical fiqh sources