tauqeet-js 1.0.2 → 1.1.1

package/CHANGELOG.md

@@ -0,0 +1,83 @@
+# Changelog
+
+All notable changes to `tauqeet-js` will be documented in this file.
+
+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]
+
+### 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).
+
+### 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`.
+
+### 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.
+
+---
+
+## [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'`.
+
+### 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.
+
+---
+
+## [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

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026
+Copyright (c) 2026 Ghulam Hasnain
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,101 +1,143 @@
-# TauqeetJS
-
-**TauqeetJS** is a high-performance, modular, and headless-first TypeScript library for calculating Islamic prayer times and astronomical data. Designed for professional engineers, it prioritizes precision, type safety, and minimal bundle size.
-
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-![Bundle Size](https://img.shields.io/bundlephobia/minzip/tauqeetjs)
-
----
-
-## Key Features
-
-- **Headless-First**: Import only the logic you need. No forced UI dependencies.
-- **Type-Safe**: Written in TypeScript with exhaustive definitions.
-- **Robust Error Handling**: Uses the `Result<T, E>` pattern—no silent failures or unexpected exceptions.
-- **Environmentally Aware**: High-precision atmospheric refraction adjustments (elevation, temperature, pressure).
-- **Small Footprint**: Zero external dependencies in the core engine.
-
----
-
-## Quick Start
-
-Install via your preferred package manager:
-
-```bash
-npm install tauqeet-js
-# or
-yarn add tauqeet-js
-```
-
-### Basic Usage (Low-Code)
-
-Get prayer times for a specific location using smart defaults (Karachi method, Hanafi madhab).
-
-```typescript
-import { getPrayerTimes } from 'tauqeet-js';
-
-const result = getPrayerTimes({
-  location: { latitude: 24.8607, longitude: 67.0011 }
-});
-
-if (result.success) {
-  const { fajr, dhuhr, asr, maghrib, isha } = result.data;
-  console.log(`Fajr: ${fajr.toLocaleTimeString()}`);
-} else {
-  console.error(`Calculation failed: ${result.error}`);
-}
-```
-
----
-
-## Core Concepts
-
-### Headless-First Architecture
-
-To keep your production bundle small, TauqeetJS is designed to be imported modularly. If you only need the prayer calculation engine without Qibla or Moon logic:
-
-```typescript
-import { getPrayerTimes } from 'tauqeetjs/prayer';
-```
-
-### The Result Pattern
-
-Unlike libraries that throw errors or return `null`, TauqeetJS returns a `Result<T, E>` object. This ensures your application remains stable even with invalid inputs.
-
-```typescript
-const result = getPrayerTimes(config);
-
-if (!result.success) {
-  // result.error contains a descriptive string
-  handleError(result.error);
-} else {
-  // result.data is fully typed
-  renderUI(result.data);
-}
-```
-
----
-
-## Advanced Configuration
-
-Fine-tune calculations for specific environmental conditions or local preferences.
-
-```typescript
-const config = {
-  location: { latitude: 24.86, longitude: 67.01, elevation: 20 },
-  method: 'MWL',
-  madhab: 'Hanafi',
-  temperature: 25, // Celsius
-  pressure: 1010,   // hPa/mbar
-  adjustments: {
-    fajr: 2, // Add 2 minutes
-    maghrib: 1 // Add 1 minute (safety margin)
-  }
-};
-```
-
----
-
-## Documentation
-
-For a full breakdown of the API, configuration options, and astronomical parameters, see [API.md](./API.md).
+# tauqeet-js
+
+**A high-precision TypeScript library for Islamic astronomical calculations.**
+
+[![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/)
+
+> 📖 **Interactive documentation & live API explorer:** [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.
+
+---
+
+## Table of Contents
+
+- [Features](#features)
+- [Prerequisites](#prerequisites)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Documentation](#documentation)
+- [Modules Overview](#modules-overview)
+- [License](#license)
+- [Author](#author)
+
+---
+
+## Features
+
+| 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) |
+
+---
+
+## Prerequisites
+
+- **Node.js** ≥ 18
+- **TypeScript** ≥ 5 (for source usage)
+- ESM-first; CJS bundle also provided.
+
+---
+
+## Installation
+
+```bash
+npm install tauqeet-js
+```
+
+> **Note:** The package is currently in active development for v1.2.0. See [CONTRIBUTING.md](CONTRIBUTING.md) for building from source.
+
+---
+
+## Quick Start
+
+### Prayer Times
+
+```ts
+import { calculatePrayerTimes, BUILT_IN_METHODS } from 'tauqeet-js';
+
+// London, UK – today
+const result = calculatePrayerTimes({
+  lat: 51.5074,
+  long: -0.1278,
+  timeZone: 'Europe/London',
+  method: 'MWL',         // Muslim World League
+  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`);
+```
+
+### 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`);
+```
+
+### Hijri Date Conversion
+
+```ts
+import { toHijri, HijriMethod, HIJRI_MONTH_NAMES } from 'tauqeet-js';
+
+const hijri = toHijri(new Date(), HijriMethod.CIVIL);
+console.log(`${hijri.day} ${HIJRI_MONTH_NAMES[hijri.month - 1]} ${hijri.year} AH`);
+```
+
+---
+
+## 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 |
+
+For the most up-to-date, interactive reference visit **[https://tauqeet-js.web.app](https://tauqeet-js.web.app)**.
+
+---
+
+## 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
+```
+
+See [MODULES.md](MODULES.md) for a detailed dependency graph and tree-shaking guide.
+
+---
+
+## License
+
+[MIT](LICENSE) © Ghulam Hasnain