prayer_timetable 2.2.2

Comprehensive Dart library for Islamic prayer time calculations with multiple methods, jamaah time management, timezone support, and Hijri calendar integration.

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

2.2.2 - 2025-10-26

Fixed

• Documentation Quality: Fixed unresolved documentation references that could impact pub.dev scoring
  • Fixed [hours, minutes] reference in defaultJamaahOffsets documentation
  • Fixed [year, month, day] references in Utils class documentation
  • Improved documentation clarity for Hijri calendar functions

2.2.1 - 2025-10-26

Added

• Comprehensive Monthly Table Documentation: Detailed examples and usage for both Gregorian and Hijri monthly prayer table generation
  • Clear separation between PrayerTimetable.monthTable() and PrayerTimetable.monthHijriTable() methods
  • Integration examples showing how to use Utils Hijri conversion methods with monthly tables
  • Dual calendar display examples (showing both Hijri and Gregorian dates)
  • Performance optimization documentation for pre-calculated timetables

Fixed

• Minor code quality improvements in test files
• Removed unused variables and unnecessary string interpolation braces

2.2.0 - 2025-10-26

Added

• Hijri Calendar Conversion Functions: Comprehensive static methods in Utils class for Hijri calendar operations
  • Utils.hijriToGregorian(year, month, day) - Convert specific Hijri dates to Gregorian
  • Utils.gregorianToHijri(DateTime) - Convert Gregorian dates to Hijri
  • Utils.getHijriMonthStart(year, month) - Get first day of Hijri month in Gregorian
  • Utils.getHijriMonthEnd(year, month) - Get last day of Hijri month in Gregorian
  • Utils.getHijriMonthLength(year, month) - Get number of days in Hijri month
  • Utils.getHijriYearStart(year) - Get first day of Hijri year (1st Muharram)
  • Utils.getHijriYearEnd(year) - Get last day of Hijri year (last day of Dhul Hijjah)
  • Utils.formatHijriDate(year, month, day) - Format Hijri dates as "YYYY-MM-DD" strings
  • Utils.getHijriMonthNameEnglish(month) - Get English month names (e.g., "Ramadan")
  • Utils.getHijriMonthNameArabic(month) - Get Arabic month names (e.g., "رمضان")
• Enhanced documentation with comprehensive Hijri conversion examples
• Full API documentation for all new Hijri calendar functions

Changed

• Moved Hijri conversion functions from helpers to Utils class as static methods for better organization
• Updated README with detailed Hijri calendar conversion section and examples
• Improved code organization by centralizing Islamic calendar utilities in Utils class

Fixed

• DST Calculation Bug: Corrected Daylight Saving Time logic for Dublin timezone that was incorrectly adding hours instead of subtracting during DST end transition
• Prayer time adjustments now properly handle DST transitions, ensuring accurate times during timezone changes
• Verified DST behavior for October 26, 2025 transition and other DST boundary dates

Technical Details

• All Hijri functions are now accessible via Utils.functionName() syntax
• Functions support both individual date conversions and bulk month/year operations
• Comprehensive error handling and input validation for all date parameters
• Full compatibility with existing hijri package for accurate calendar calculations

2.1.0 - 2024-12-19

Added

• Comprehensive inline documentation for all classes, methods, and properties
• Complete API documentation with parameter explanations and usage examples
• Enhanced README with detailed usage examples and feature explanations
• Support for string-based enum parameters in TimetableCalc (highLatitudeRule, madhab)
• Helper methods for converting string parameters to proper enum types
• Detailed prayer ID documentation and explanation
• Islamic context documentation for developers unfamiliar with prayer times

Changed

• Improved type safety throughout the codebase
• Enhanced error handling and parameter validation
• Updated README to reflect current API and features
• Modernized package structure and documentation standards

Fixed

• Type conversion issues in TimetableCalc constructor
• Null assertion warnings in prayer time calculations
• Enum parameter handling for configuration flexibility
• All linting issues and type safety warnings

Documentation

• Added comprehensive class-level documentation
• Documented all public APIs with examples
• Added parameter descriptions for all methods
• Included Islamic prayer time concepts explanation
• Added timezone and DST handling documentation

2.0.0 - 2024-03-15

Added

• Multiple calculation methods support (astronomical, map-based, list-based)
• Jamaah (congregation) time management with customizable offsets
• Full timezone support with automatic DST handling
• Prayer joining functionality (Dhuhr-Asr, Maghrib-Isha)
• Monthly prayer time generation for Gregorian and Hijri calendars
• Prayer status analysis (current, next, pending jamaah)
• Qibla direction calculation using coordinates
• Hijri calendar integration
• Sunnah time calculations (Islamic midnight, last third of night)

Changed

• Complete rewrite of the prayer calculation engine
• Improved accuracy using adhan_dart library
• Enhanced timezone handling with proper DST support
• Modernized API design with multiple constructor patterns

Breaking Changes

• New API structure with PrayerTimetable.calc(), .map(), .list() constructors
• Prayer objects now use arrays instead of named properties
• Utils class replaces separate Calc, Sunnah, and Qibla classes
• Updated parameter names and types for consistency

1.5.0 - 2023-08-20

Added

• High latitude calculation rules support
• Madhab selection (Shafi, Hanafi) for Asr calculation
• Prayer time adjustments and method adjustments
• Precision control for seconds display
• Enhanced DST calculation accuracy

Changed

• Improved astronomical calculation precision
• Better handling of extreme latitude locations
• Enhanced date and time manipulation utilities

Fixed

• DST calculation issues in certain timezones
• Precision rounding in prayer time calculations
• Edge cases in high latitude regions

1.4.0 - 2023-05-10

Added

• Custom calculation parameters support
• Multiple calculation methods (Muslim World League, ISNA, etc.)
• Altitude-based prayer time adjustments
• Enhanced debugging and logging capabilities

Changed

• Refactored calculation engine for better maintainability
• Improved error handling and validation
• Enhanced documentation and code comments

Fixed

• Memory leaks in continuous calculations
• Performance issues with repeated calculations
• Timezone offset calculation accuracy

1.3.0 - 2023-02-15

Added

• Hijri calendar support and conversions
• Islamic date utilities and formatting
• Monthly prayer time tables generation
• Prayer time difference calculations

Changed

• Enhanced DateTime handling and manipulation
• Improved calculation performance
• Better memory management for large datasets

Fixed

• Leap year calculations in Hijri calendar
• Month boundary issues in prayer calculations
• Timezone conversion edge cases

1.2.0 - 2022-11-30

Added

• Qibla direction calculation from coordinates
• Prayer countdown and count-up timers
• Prayer completion percentage calculation
• Current prayer detection logic

Changed

• Improved prayer time analysis algorithms
• Enhanced user interface for prayer status
• Better integration with timezone libraries

Fixed

• Prayer transition timing accuracy
• Current prayer detection edge cases
• Timer synchronization issues

1.1.0 - 2022-09-15

Added

• Sunnah time calculations (midnight, last third)
• Prayer period end time calculations
• Enhanced prayer status tracking
• Timezone-aware calculations

Changed

• Refactored core calculation logic
• Improved code organization and structure
• Enhanced testing coverage

Fixed

• Prayer end time calculation accuracy
• Sunnah time calculation in different seasons
• Edge cases in prayer period detection

1.0.0 - 2022-06-01

Added

• Initial release of prayer_timetable library
• Basic prayer time calculations using astronomical formulas
• Support for five daily prayers plus sunrise
• Timezone and DST support
• Coordinate-based calculations
• Customizable calculation angles (Fajr, Isha)
• Prayer time formatting and display utilities

Features

• Accurate astronomical calculations based on Jean Meeus algorithms
• Support for different geographic locations
• Customizable prayer calculation parameters
• DateTime integration for easy time manipulation
• Cross-platform compatibility (Dart/Flutter)

---

Version History Summary

• v2.1.0: Documentation overhaul and type safety improvements
• v2.0.0: Major rewrite with multiple calculation methods and jamaah support
• v1.5.0: High latitude rules and madhab selection
• v1.4.0: Custom calculation parameters and multiple methods
• v1.3.0: Hijri calendar integration and monthly tables
• v1.2.0: Qibla calculation and prayer analysis
• v1.1.0: Sunnah times and enhanced status tracking
• v1.0.0: Initial release with core prayer calculations

Migration Guide

From v1.x to v2.0.0

The v2.0.0 release introduced breaking changes to improve the API design:

// Old API (v1.x)
PrayerTimetable location = PrayerTimetable(timezone, lat, lng, angle);
print(location.prayers.current.dawn);

// New API (v2.0.0+)
final timetable = PrayerTimetable.calc(
  timetableCalc: TimetableCalc(
    date: DateTime.now(),
    timezone: 'America/New_York',
    lat: lat,
    lng: lng,
    precision: true,
    fajrAngle: angle,
  ),
  jamaahOn: false,
  timezone: 'America/New_York',
);
print(timetable.current[0].prayerTime); // Fajr

Key Changes:

• Use constructor methods: .calc(), .map(), .list()
• Prayer times are now arrays: current[0] instead of current.dawn
• Utils class combines Calc, Sunnah, and Qibla functionality
• Enhanced timezone handling with string identifiers