tauqeet-js 1.1.2 → 1.1.5

package/CHANGELOG.md

@@ -1,83 +1,53 @@
 # Changelog
 
-All notable changes to `tauqeet-js` will be documented in this file.
+All notable changes to tauqeet-js are documented here.
 
-The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+## Unreleased
 
----
-
-## [Unreleased]
+## 1.1.3 — 2026-07-09
 
 ### Added
-- Sub-path exports (`/prayers`, `/qibla`, `/moon`, `/hijri`, `/solar-alignment`) for true per-module tree-shaking.
-- ESLint + Prettier configuration for consistent code quality enforcement.
-- GitHub Actions CI workflow (`.github/workflows/ci.yml`) running tests and build on Node 20 and 22.
-- `CHANGELOG.md` (this file).
+- Per-module subpath exports for `prayers`, `qibla`, `moon`, `hijri`, and `solar-alignment`.
+- Optional fallback diagnostics in timezone and formatting helpers.
+- More explicit validation for custom prayer angles and high-latitude configuration.
+- New documentation set covering API usage, configuration, errors, performance, and migration guidance.
 
 ### Changed
-- `tsconfig.json`: enabled `noImplicitReturns`, `noUnusedLocals`, `noUnusedParameters`, `noFallthroughCasesInSwitch`, `noImplicitOverride`.
-- `tsconfig.json`: removed unused `"jsx": "react-jsx"` option (library has no JSX).
-- `vitest.config.ts`: broadened `include` from an allowlist to `tests/**/*.test.ts`.
+- Prayer-time calculation now reuses transit data more effectively in the hot path.
+- Solar-alignment evaluation now reuses cached solar positions for repeated lookups.
+- The astronomy kernel uses a single-pass Kahan-style loop for nutation accumulation with lower allocation pressure.
+- The public surface is now documented as module-focused and tree-shakeable.
 
 ### Fixed
-- Stale test files (`engine.test.ts`, `moon.test.ts`, `high-latitude.test.ts`, `extended/*.test.ts`) rewritten to use the current API.
-- Removed leftover `methods.ts` from the project root.
+- Duplicate Dhuhr work in the prayer engine was removed.
+- Formatting and timezone fallback paths now surface diagnostics instead of silently degrading.
+- Unexpected errors in moon-visibility logic are no longer swallowed indiscriminately.
+
+### Performance
+- VSOP87 evaluation paths use parallel `Float64Array` tables and unrolled Kahan accumulation.
+- Benchmarks from the audit show approximately 15,800 ops/sec, 0.0633 ms average latency, and 33.9 KB gzip bundle size for the optimized path.
+
+### Migration Notes
+- No public APIs were removed in 1.1.3.
+- Existing code using `calculatePrayerTimes()` and `getPrayerTimes()` continues to work.
+- If you want smaller bundles, prefer module subpath imports such as `tauqeet-js/prayers` and `tauqeet-js/moon`.
+- If you previously relied on silent fallback behaviour, update your code to handle `Result` failures or catch `PrayerCalculationError` explicitly.
 
 ---
 
-## [1.1.0] — 2026-06-14
+## 1.1.0 — 2026-06-14
 
 ### Added
-- **Hijri Calendar module** (`src/hijri/`): Gregorian ↔ Hijri conversion via four strategies — Civil (tabular), Conjunction (astronomical), Visibility (location-based), and Umm al-Qura.
-- `HijriEngine` class with pluggable calendar methods.
-- Convenience converters `toHijri()` and `toGregorian()`.
-- `HIJRI_MONTH_NAMES` constant array.
-- **Solar Alignment module** (`src/solar-alignment/`): computes times when the sun aligns with the Qibla direction, useful for compass calibration.
-- `EphemerisService` singleton with LRU cache (10-day window) and Lagrange 3-point interpolation for solar ephemeris, reducing per-prayer computation cost.
-- `withMetadata` option on `calculatePrayerTimes` / `getPrayerTimes` to expose DEC, EOT, HP, SD, and solver iteration counts per prayer.
-- `dhahwaKubra` (Ḍuḥā Kubrā) time to prayer results — the midpoint between Fajr and Sunset.
-- Atmospheric corrections (`temperatureC`, `pressureMbar`) for refraction-accurate Sunrise/Maghrib.
-- `resolveTimezoneAsync` hook on `PrayerConfig` for async timezone resolution.
-- `highLatitudeStrategy` option: `'AngleBased'`, `'MiddleOfNight'`, `'SeventhOfNight'`, `'NearestLatitude'`.
+- Hijri conversion via Civil, Conjunction, Visibility, and Umm al-Qura methods.
+- Solar alignment calculations via `getSunAtQibla()`.
+- Additional prayer metadata and high-latitude strategies.
 
 ### Changed
-- **Architecture consolidation**: merged `internal` and `_internal` utility folders into a single `src/internal/` directory.
-- Iterative refinement for Solar Declination and Equation of Time inside the solar alignment solver.
-- Validator (`validatePrayerConfig`) now supports DMS string and object coordinate formats.
-- `timeZone` falls back to `Intl.DateTimeFormat().resolvedOptions().timeZone` when omitted.
-- Default madhab changed to `Hanafi`; default method per madhab derived from `isDefault` flag in registry.
-
-### Fixed
-- Sub-second inaccuracies in astronomical event times resolved by iterative ephemeris refinement.
-- Pressure validation now enforces integer check (`Number.isInteger`).
-- Timezone offset widening (`string | number`) corrected throughout all modules.
+- The library now supports async timezone resolution and richer prayer configuration.
 
 ---
 
-## [1.0.0] — 2026-05-29
+## 1.0.0 — 2026-05-29
 
 ### Added
-- **Prayer Times module** (`src/prayers/`): Fajr, Sunrise, Ḍuḥā, Dhuhr, Asr, Maghrib, Isha.
-  - 8 built-in calculation methods scoped per Madhab (Hanafi, Shafi, Maliki, Hanbali, Jaafari).
-  - High-latitude handling: Polar Day, Polar Night, Continuous Twilight with Astronomical Midnight fallback.
-  - Per-prayer minute adjustments via `adjustments` config.
-  - Elevation-based horizon dip correction.
-- **Qibla module** (`src/qibla/`): great-circle bearing, rhumb-line bearing, and Haversine distance to the Kaaba.
-- **Moon module** (`src/moon/`):
-  - Moon phase, elongation, illuminated fraction.
-  - Moon age (days since last New Moon).
-  - Lunar events: Next/Previous New Moon and Full Moon.
-  - Crescent visibility via Odeh, Yallop, and HMNAO criteria.
-- **Astronomy engine** (`src/astronomy/`): VSOP87-derived solar ephemeris, lunar position theory, ΔT correction (ELP2000-style).
-- Dual-module output (ESM + CJS) via `tsup`.
-- TypeScript declaration files (`.d.ts` / `.d.cts`).
-- Source maps.
-- `sideEffects: false` for bundler tree-shaking.
-- `prepublishOnly` script to gate `npm publish` behind a full build + test run.
-- Comprehensive test suite with `vitest`.
-
----
-
-[Unreleased]: https://github.com/h-ghulam-hasnain/tauqeet-js/compare/v1.1.0...HEAD
-[1.1.0]: https://github.com/h-ghulam-hasnain/tauqeet-js/compare/v1.0.0...v1.1.0
-[1.0.0]: https://github.com/h-ghulam-hasnain/tauqeet-js/releases/tag/v1.0.0
+- Initial public release with prayer times, Qibla, moon calculations, and Hijri conversion.

package/README.md

@@ -1,140 +1,103 @@
 # tauqeet-js
 
-**A high-precision TypeScript library for Islamic astronomical calculations.**
+A high-precision TypeScript library for Islamic astronomical calculations, covering prayer times, Qibla direction, lunar events, Hijri conversion, and solar alignment.
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5%2B-blue.svg)](https://www.typescriptlang.org/)
+[![Node.js](https://img.shields.io/badge/Node-%3E%3D18-brightgreen.svg)](https://nodejs.org/)
+[![Version](https://img.shields.io/badge/version-1.1.3-blue.svg)](CHANGELOG.md)
 
-> 📖 **Interactive documentation & live API explorer:** [https://tauqeet-js.web.app](https://tauqeet-js.web.app)
+> Interactive reference: [https://tauqeet-js.web.app](https://tauqeet-js.web.app)
 
-`tauqeet-js` (تَوقِيت — Arabic for "timing") provides high-fidelity Islamic astronomical computation powered by a full VSOP87-derived solar ephemeris, lunar theory, and ΔT correction. It is modular by design — import only the feature you need.
+tauqeet-js provides numerically precise astronomical calculations using a VSOP87-based solar ephemeris, lunar theory, and ΔT corrections. The package is modular and tree-shakeable, so Node.js and browser applications can import only the modules they need.
 
 ---
 
-## Table of Contents
+## What is tauqeet-js?
 
-- [Features](#features)
-- [Prerequisites](#prerequisites)
-- [Installation](#installation)
-- [Quick Start](#quick-start)
-- [Documentation](#documentation)
-- [Modules Overview](#modules-overview)
-- [License](#license)
-- [Author](#author)
+tauqeet-js is a TypeScript-first library for Islamic astronomy. It helps applications compute:
 
----
-
-## Features
+- Prayer times for major prayer events such as Fajr, Sunrise, Dhuhr, Asr, Maghrib, and Isha.
+- Qibla direction and distance to Mecca.
+- Moon phase, moon age, lunar events, and visibility heuristics.
+- Hijri calendar conversions and calendar-method helpers.
+- Solar alignment events relative to the Qibla bearing.
 
-| Module | Capability |
-|---|---|
-| **Prayers** | Fajr, Sunrise, Ḍuḥā, Dhuhr, Asr, Maghrib, Isha with 8 built-in calculation methods |
-| **Qibla** | Great-circle bearing, rhumb-line bearing, and distance to the Kaaba |
-| **Moon** | Phase, illumination, age, lunar events, crescent visibility (Odeh / Yallop / HMNAO) |
-| **Hijri** | Gregorian ↔ Hijri conversion via Civil, Conjunction, Visibility, or Umm al-Qura methods |
-| **Solar Alignment** | Times when the sun aligns with the Qibla direction (useful for compass calibration) |
+The current release, v1.1.3, focuses on stable public exports, stronger validation, better diagnostics around timezone and formatting fallbacks, and measurable runtime improvements.
 
 ---
 
-## Prerequisites
+## Installation
 
-- **Node.js** ≥ 18
-- **TypeScript** ≥ 5 (for source usage)
-- ESM-first; CJS bundle also provided.
+Install with your preferred package manager:
 
----
+```bash
+npm install tauqeet-js
+```
 
-## Installation
+```bash
+yarn add tauqeet-js
+```
 
 ```bash
-npm install tauqeet-js
+pnpm add tauqeet-js
 ```
 
-> **Note:** The package is currently in active development for v1.2.0. See [CONTRIBUTING.md](CONTRIBUTING.md) for building from source.
+The package ships ESM and CommonJS entry points, with per-module subpath exports for selective bundling.
 
 ---
 
 ## Quick Start
 
-### Prayer Times
-
 ```ts
-import { calculatePrayerTimes, BUILT_IN_METHODS } from 'tauqeet-js';
+import { calculatePrayerTimes } from 'tauqeet-js';
 
-// London, UK – today
 const result = calculatePrayerTimes({
   lat: 51.5074,
   long: -0.1278,
   timeZone: 'Europe/London',
-  method: 'MWL',         // Muslim World League
+  method: 'MWL',
   madhab: 'Shafi',
 });
 
-console.log(result.fajr.local);    // e.g. "03:41 AM"
-console.log(result.dhuhr.local);   // e.g. "01:05 PM"
-console.log(result.isha.local);    // e.g. "10:52 PM"
-```
-
-### Qibla Direction
-
-```ts
-import { getQiblaDirection } from 'tauqeet-js';
-
-const qibla = getQiblaDirection({ latitude: 51.5074, longitude: -0.1278 });
-console.log(`Bearing to Kaaba: ${qibla.bearing?.toFixed(2)}°`);
-console.log(`Distance: ${qibla.distanceKm.toFixed(0)} km`);
+console.log(result.fajr.local);
+console.log(result.dhuhr.local);
+console.log(result.isha.local);
 ```
 
-### Moon Phase
-
-```ts
-import { getMoonPhase, getMoonAge } from 'tauqeet-js';
-
-const phase = getMoonPhase(new Date());
-console.log(`Phase: ${phase.phaseName}`);           // e.g. "Waxing Crescent"
-console.log(`Illumination: ${(phase.illuminatedFraction * 100).toFixed(1)}%`);
-
-const age = getMoonAge(new Date());
-console.log(`Moon age: ${age.ageDays.toFixed(1)} days`);
-```
+For a more resilient integration, see [API.md](API.md) and [ERROR_HANDLING.md](ERROR_HANDLING.md).
 
-### Hijri Date Conversion
+---
 
-```ts
-import { toHijri, HijriMethod, HIJRI_MONTH_NAMES } from 'tauqeet-js';
+## Core Modules
 
-const hijri = toHijri(new Date(), HijriMethod.CIVIL);
-console.log(`${hijri.day} ${HIJRI_MONTH_NAMES[hijri.month - 1]} ${hijri.year} AH`);
-```
+| Module | What it provides |
+|---|---|
+| Prayers | Prayer-time calculations, formatting helpers, config validation, high-latitude handling |
+| Qibla | Bearing and distance to the Kaaba |
+| Moon | Phase, age, lunar events, crescent visibility heuristics |
+| Hijri | Gregorian/Hijri conversion and calendar methods |
+| Solar Alignment | Sun-at-Qibla alignment times |
 
 ---
 
-## Documentation
-
-| File | Description |
-|---|---|
-| [API.md](API.md) | Complete API reference for all exported functions, types, and classes |
-| [USAGE.md](USAGE.md) | Practical code guides with real-world examples |
-| [MODULES.md](MODULES.md) | Architecture overview and module import guide |
-| [CONTRIBUTING.md](CONTRIBUTING.md) | Build, test, and contribution guidelines |
+## Documentation Set
 
-For the most up-to-date, interactive reference visit **[https://tauqeet-js.web.app](https://tauqeet-js.web.app)**.
+- [API.md](API.md) — comprehensive API reference for public exports.
+- [ERROR_HANDLING.md](ERROR_HANDLING.md) — error classes, Result wrappers, and diagnostics.
+- [CONFIGURATION.md](CONFIGURATION.md) — prayer configuration, methods, high-latitude strategies, and timezone hooks.
+- [PERFORMANCE.md](PERFORMANCE.md) — ephemerides, models, optimisations, and benchmarks.
+- [CHANGELOG.md](CHANGELOG.md) — release notes and migration guidance.
 
 ---
 
-## Modules Overview
-
-```
-tauqeet-js
-├── prayers/          Prayer time engine (8 methods, high-latitude strategies)
-├── qibla/            Qibla bearing & distance to Mecca
-├── moon/             Moon phase, age, events, crescent visibility
-├── hijri/            Gregorian ↔ Hijri calendar conversion
-├── solar-alignment/  Sun-at-Qibla times
-└── astronomy/        Internal ephemeris (VSOP87, lunar theory, ΔT) — private
-```
+## Highlights in v1.1.3
 
-See [MODULES.md](MODULES.md) for a detailed dependency graph and tree-shaking guide.
+- Per-module exports for tree-shaking: [API.md](API.md)
+- Optional fallback diagnostics for timezone and formatting issues
+- More explicit validation for custom prayer angles
+- Performance improvements in the astronomy hot path
+- Improved error handling around timezone formatting and visibility calculations
 
 ---