prayer_timetable 2.1.0

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.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