feat: added a qibla utility and exposed certain internals

docs/.vitepress/config.ts

@@ -82,15 +82,7 @@ function sidebarGuide() {
         { text: 'One Time Calculator', link: '/guide/one-time-calculator' },
         { text: 'Reactive Calculator', link: '/guide/reactive-calculator' },
 
-        {
-          text: 'Calculating The Qibla',
-          link: '/guide/calculating-the-qibla',
-        },
-
-        {
-          text: 'Testing',
-          link: '/guide/testing',
-        },
+        { text: 'Calculating The Qibla', link: '/guide/calculating-the-qibla' },
       ],
     },
     {
@@ -100,6 +92,7 @@ function sidebarGuide() {
         { text: 'Formatters', link: '/recipes/formatters' },
         { text: 'Hijri Dates', link: '/recipes/hijri' },
         { text: 'Internalization', link: '/recipes/i18n' },
+        { text: 'Testing', link: '/recipes/testing' },
       ],
     },
     {

docs/guide/calculating-the-qibla.md

@@ -1,3 +1,50 @@
 # Qibla Calculations
 
-WIP
+`prayers-call` offers two convenient ways to calculate this direction: using a calculator (either static or reactive) and using a standalone function helper. This guide will walk you through both methods.
+
+## Using a Calculator
+
+Both the `StaticCalculator` and `ReactiveCalculator` classes expose a method called `getQiblaDirection`. By default, this method uses the geographical coordinates you provided during the calculator's initialization to compute the Qibla direction.
+
+```ts
+import { Methods, ReactiveCalculator } from 'prayer-call'
+
+// calculations for Cyberjaya
+const reactiveCalculator = new ReactiveCalculator({
+  latitude: 2.9213,
+  longitude: 101.6559,
+  method: Methods.MALAYSIA,
+  adjustments: { dhuhr: 3, asr: 3, isha: 2 },
+})
+
+const qiblaDirection = reactiveCalculator.getQiblaDirection()
+console.log(qiblaDirection) // 292.6457605278075
+```
+
+### Optional Coordinates
+
+You can also pass in an optional [`CoordinatesObject`]() to the `getQiblaDirection` method. This is useful if you want to calculate the Qibla direction for a different location than the one you used to initialize the calculator.
+
+```ts
+const alAqsaCoordinates = {
+  latitude: 31.7782624,
+  longitude: 35.2335256,
+}
+
+const qiblaDirection = reactiveCalculator.getQiblaDirection(alAqsaCoordinates)
+console.log(qiblaDirection) // 157.29924281528764
+```
+
+## Using the `calculateQiblaDirection` Function Helper
+
+The `calculateQiblaDirection` function helper is a standalone function that can be used to calculate the Qibla direction. It accepts a [`CoordinatesObject`]() as its only argument.
+
+```ts
+import { calculateQiblaDirection } from 'prayer-call'
+
+const qiblaDirection = calculateQiblaDirection({
+  latitude: 2.9213,
+  longitude: 101.6559,
+})
+console.log(qiblaDirection) // 292.6457605278075
+```

docs/recipes/testing.md

@@ -0,0 +1,7 @@
+# Testing
+
+::: tip
+This is a work in progress. If you have any questions or suggestions, please [open an issue]() or [start a discussion]().
+:::
+
+Testing reactive code can be tricky. That's why `prayer-call` provides some helpers that allows you to test your reactive code in a synchronous manner.

docs/roadmap.md

@@ -1,4 +1,5 @@
-- offer open source tools to make comparing and making methods easier.
-- re-write the library from scratch making it reactive from the ground up (using vue 3 reactive core api)
-- add altitude to the calculation formula
-- support `Temporal`
+- Offer open source tools to make comparing and making methods easier.
+- Re-write the library from scratch making it reactive from the ground up (using vue 3 reactive core api)
+- Add altitude to the calculation formula
+- Support `Temporal` instead of `Date`
+- Offer testing utilities for reactive code

src/MethodRecommender.ts

@@ -1,42 +1,9 @@
 import { findCountryByCoordinate } from 'country-locator'
 import { CountryMethods } from './data/methods'
-import type { LngLatLike } from './types/LangLatLike'
 import type { Methods } from './types/Methods'
+import type { CoordinatesObject } from './types/Coordinates'
 
-/**
- * recommend methods to use from given coordinate
- * the methods are ranked by the most used to the least used
- * @param point - an array of two numbers - [x, y].
- * PAY ATTENTION: x == longitude, y == latitude!
- * @returns Methods[] | undefined - An array of recommended prayer methods for the given location, or undefined if the location is not found.
- */
-export function MethodRecommender(coordinates: LngLatLike): Methods[] | undefined
-/**
- * recommend methods to use given coordinate
- * the methods are ranked by the most used to the least used
- * @param latitude - latitude of coordinate
- * @param longitude - longitude of coordinate
- * @returns Methods[] | undefined - An array of recommended prayer methods for the given location, or undefined if the location is not found.
- */
-export function MethodRecommender(latitude: number, longitude: number): Methods[] | undefined
-
-export function MethodRecommender(coordinatesOrLat: LngLatLike | number, longitude?: number): Methods[] | undefined {
-  const countryInfo = findCountryByCoordinate(
-    longitude ? [coordinatesOrLat as number, longitude] : getLngLat(coordinatesOrLat as LngLatLike)
-  )
+export function recommendMethod({ latitude, longitude }: CoordinatesObject): Methods[] | undefined {
+  const countryInfo = findCountryByCoordinate(latitude, longitude)
   return countryInfo?.code ? (CountryMethods as Record<string, Methods[]>)[countryInfo?.code] : undefined
 }
-
-function getLngLat(coordinates: LngLatLike): [number, number] {
-  if (Array.isArray(coordinates)) {
-    return coordinates
-  } else if ('lng' in coordinates && 'lat' in coordinates) {
-    return [coordinates.lng, coordinates.lat]
-  } else if ('lon' in coordinates && 'lat' in coordinates) {
-    return [coordinates.lon, coordinates.lat]
-  } else if ('longitude' in coordinates && 'latitude' in coordinates) {
-    return [coordinates.longitude, coordinates.latitude]
-  } else {
-    throw new Error('Invalid coordinates object')
-  }
-}

src/QiblaCalculator.ts

@@ -0,0 +1,6 @@
+import { Coordinates, Qibla } from 'adhan'
+import type { CoordinatesObject } from './types/Coordinates'
+
+export function calculateQiblaDirection({ latitude, longitude }: CoordinatesObject): number {
+  return Qibla(new Coordinates(latitude, longitude))
+}

src/index.ts

@@ -1,11 +1,15 @@
 export { HighLatitudeRule, PolarCircleResolution } from 'adhan'
 export { StaticCalculator } from './Calculator'
 export { ReactiveCalculator } from './ReactiveCalculator'
+export { Formatter } from './Formatter'
+export { recommendMethod } from './MethodRecommender'
+export { calculateQiblaDirection } from './QiblaCalculator'
 
 // Types export
 export { Methods } from './types/Methods'
 export { AsrTime } from './types/AsrTime'
 export { EventType, PrayerNames } from './types/TimeObject'
+export { HijriCalendar } from './types/HijriCalendar'
 export type {
   PrayersTimeObject,
   PrayerNamesType,
@@ -14,4 +18,6 @@ export type {
   TimeEventObject,
   TimeObject,
 } from './types/TimeObject'
+export type { CoordinatesObject } from './types/Coordinates'
+export type { FormatterConfig } from './types/FormatterConfig'
 export type { CalculationsConfig, ReactiveCalculationsConfig } from './types/CalculationsConfig'