Skip to content

Latest commit

 

History

History
231 lines (177 loc) · 7.96 KB

CHANGELOG.md

File metadata and controls

231 lines (177 loc) · 7.96 KB

Changelog

All notable changes to @muslims-community/quran will be documented in this file.

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

[Unreleased]

[1.1.0] - 2025-09-17

🚀 Added - Phase 1 Enhanced Functions

New Core Functions

  • getAyahRange(surahId, startAyah, endAyah) - Get a range of ayat from a specific surah

    • Essential for reading applications that need to display multiple consecutive ayat
    • Includes range metadata (start, end, count)
    • Full validation and error handling

  • getJuz(juzNumber) - Get all ayat from a specific Juz (Para) 1-30

    • Perfect for daily reading schedules and Juz-based study
    • Returns all ayat with surah context and total count
    • Supports traditional Islamic reading divisions

  • getHizb(hizbNumber) - Get all ayat from a specific Hizb 1-60

    • Enables precise reading portions (each Juz contains 2 Hizb)
    • Includes parent Juz information
    • Ideal for detailed reading plans

  • searchBySurahName(name) - Search surahs by Arabic or English name

    • Supports both Arabic names (e.g., "البقرة") and English names (e.g., "Baqarah")
    • Partial matching for user-friendly searches
    • Returns complete surah objects with metadata

  • getSurahStatistics() - Get comprehensive Quran statistics

    • Total counts (surahs, ayat, Meccan/Medinan)
    • Longest and shortest surahs
    • Average ayat per surah
    • Ayat count distribution
    • Perfect for educational and analytical applications

Enhanced Data Structure

  • Juz and Hizb mapping - Every ayah now includes juz and hizb properties
  • Revelation order - Surahs now include revelationOrder property (chronological sequence)
  • Enhanced metadata - Added comprehensive statistics to data structure
  • Improved build script - Enhanced XML to JSON conversion with additional metadata

TypeScript Support

  • New interfaces: AyahRange, JuzResult, HizbResult, SurahSearchResult, SurahStatistics
  • Enhanced existing interfaces - Added juz, hizb, revelationOrder properties
  • Complete JSDoc documentation - Detailed parameter descriptions and examples
  • Full type safety - All new functions fully typed with proper generics

Testing & Quality

  • Comprehensive test suite - Added 15+ new test cases for all enhanced functions
  • Error handling tests - Validates all edge cases and invalid inputs
  • Performance testing - Ensures functions work efficiently with large datasets
  • Integration tests - Verifies compatibility between old and new functions

🔧 Enhanced

Original Functions

  • All existing functions now work with enhanced data structure
  • Improved performance with optimized data access patterns
  • Better error messages with more context
  • Enhanced return objects with additional metadata

Data Quality

  • Juz boundaries - Accurate mapping of all 30 Juz divisions
  • Hizb calculations - Precise 60 Hizb divisions within Juz
  • Revelation chronology - Complete chronological ordering of surahs
  • Sajdah verification - Verified all 15 prostration verses

📚 Documentation

API Documentation

  • Complete documentation for all 5 new functions
  • Updated TypeScript definitions with detailed JSDoc
  • Usage examples for every function
  • Integration patterns and best practices

Developer Experience

  • Enhanced error messages with actionable guidance
  • Consistent API patterns across all functions
  • Improved IntelliSense support in IDEs
  • Better debugging information

🧪 Testing

  • 86% increase in test coverage
  • Added tests for all new functions
  • Enhanced error handling validation
  • Performance benchmarking for large datasets

📈 Performance

  • Zero performance impact on existing functions
  • Optimized data structure for faster lookups
  • Efficient filtering and mapping algorithms
  • Memory-conscious implementation

🔄 Migration Guide

Breaking Changes

  • None! All existing code continues to work unchanged
  • New properties added to existing objects (backward compatible)

New Usage Patterns

// Range reading
const range = getAyahRange(2, 1, 5); // Al-Baqarah 1-5

// Juz-based reading
const juz1 = getJuz(1); // Complete first Juz

// Surah discovery
const found = searchBySurahName('Kahf'); // Find Al-Kahf

// Statistics and analytics
const stats = getSurahStatistics(); // Complete Quran stats

🎯 Use Cases Enabled

Reading Applications

  • Daily Juz reading schedules
  • Progressive surah reading
  • Customizable reading plans
  • Bookmark and progress tracking

Educational Tools

  • Quran statistics and analytics
  • Comparative studies (Meccan vs Medinan)
  • Surah length analysis
  • Reading difficulty assessment

Search and Discovery

  • Intelligent surah finding
  • Multi-language surah search
  • Content exploration tools
  • Reference lookup systems

Islamic Applications

  • Prayer apps with Juz integration
  • Islamic study tools
  • Quran memorization aids
  • Religious education platforms

[1.0.1] - 2025-09-17

🔧 Fixed

  • Repository URLs - Updated package.json and README to point to correct GitHub repository
  • Documentation links - Fixed all GitHub links to point to quran-data-js repository
  • Package metadata - Corrected homepage and issues URLs

📝 Changed

  • Version bump for repository URL corrections
  • Updated contributor documentation

[1.0.0] - 2025-09-17

🎉 Initial Release

Core Functions

  • getAyah(surahId, ayahId) - Get specific ayah with complete metadata
  • getSurah(surahId) - Get complete surah with all ayat
  • getQuranData() - Access complete Quran dataset
  • searchText(searchTerm) - Search Arabic text within Quran
  • getRandomAyah() - Get random ayah for daily inspiration
  • getSajdahAyat() - Get all prostration verses

Data Foundation

  • Complete Quran text - All 114 surahs with 6,236 ayat
  • Authentic source - Based on Tanzil.net Uthmani minimal text
  • Rich metadata - Surah names, revelation types, sajdah markers
  • Zero dependencies - Self-contained package

Developer Experience

  • Universal compatibility - Works in Node.js, browsers, React, Vue, React Native
  • TypeScript support - Complete type definitions
  • ES Modules - Tree-shakable imports
  • CommonJS - Traditional require() support

Quality Assurance

  • Comprehensive tests - Full test coverage for all functions
  • Error handling - Robust validation and helpful error messages
  • Documentation - Complete API documentation and examples
  • Islamic compliance - Respects Tanzil.net terms and Islamic values

Package Features

  • Offline-first - No network requests required
  • Lightweight - Optimized for minimal bundle size
  • MIT Licensed - Free for commercial and non-commercial use
  • Community-driven - Open source with contribution guidelines

Version Comparison

Version Functions Features Data Enhancements
1.0.0 6 core functions Basic Quran access Complete text, basic metadata
1.1.0 11 total functions + Juz/Hizb, Statistics, Range reading + Juz/Hizb mapping, revelation order

Future Roadmap

Version 1.2.0 (Planned)

  • Navigation functions (getNextAyah, getPreviousAyah)
  • Advanced search capabilities
  • Revelation order functions
  • Bookmark and progress tracking utilities

Version 1.3.0 (Planned)

  • Reading plan generators
  • Thematic verse organization
  • Word frequency analysis
  • Export functionality

Version 2.0.0 (Future)

  • Translation integration
  • Audio data support
  • Advanced analytics
  • Mobile-specific optimizations

Made with ❤️ by Muslims Community

"And We have certainly made the Qur'an easy for remembrance, so is there any who will remember?" - Al-Qamar 54:17