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 #

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:

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 #

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 #

Special Cases #

The library automatically detects and applies special cases:

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