From b76a9d46abfeeba3815c70d2333898c7bca6defb Mon Sep 17 00:00:00 2001 From: gimy Date: Tue, 3 Oct 2023 07:15:14 +0800 Subject: [PATCH] feat: added a qibla utility and exposed certain internals --- docs/.vitepress/config.ts | 11 ++----- docs/guide/calculating-the-qibla.md | 49 ++++++++++++++++++++++++++++- docs/guide/testing.md | 3 -- docs/recipes/testing.md | 7 +++++ docs/roadmap.md | 9 +++--- src/MethodRecommender.ts | 39 ++--------------------- src/QiblaCalculator.ts | 6 ++++ src/index.ts | 6 ++++ src/types/LangLatLike.ts | 5 --- 9 files changed, 77 insertions(+), 58 deletions(-) delete mode 100644 docs/guide/testing.md create mode 100644 docs/recipes/testing.md create mode 100644 src/QiblaCalculator.ts delete mode 100644 src/types/LangLatLike.ts diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index fcfef95..78ecc7a 100644 --- a/docs/.vitepress/config.ts +++ b/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' }, ], }, { diff --git a/docs/guide/calculating-the-qibla.md b/docs/guide/calculating-the-qibla.md index dbfd81f..2533e35 100644 --- a/docs/guide/calculating-the-qibla.md +++ b/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 +``` diff --git a/docs/guide/testing.md b/docs/guide/testing.md deleted file mode 100644 index c46e346..0000000 --- a/docs/guide/testing.md +++ /dev/null @@ -1,3 +0,0 @@ -# Testing - -WIP diff --git a/docs/recipes/testing.md b/docs/recipes/testing.md new file mode 100644 index 0000000..7040ac8 --- /dev/null +++ b/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. diff --git a/docs/roadmap.md b/docs/roadmap.md index e095115..e51aa79 100644 --- a/docs/roadmap.md +++ b/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 diff --git a/src/MethodRecommender.ts b/src/MethodRecommender.ts index 9673286..d51dd42 100644 --- a/src/MethodRecommender.ts +++ b/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)[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') - } -} diff --git a/src/QiblaCalculator.ts b/src/QiblaCalculator.ts new file mode 100644 index 0000000..400a0b3 --- /dev/null +++ b/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)) +} diff --git a/src/index.ts b/src/index.ts index 36e055d..a9062a3 100644 --- a/src/index.ts +++ b/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' diff --git a/src/types/LangLatLike.ts b/src/types/LangLatLike.ts deleted file mode 100644 index 0df5adc..0000000 --- a/src/types/LangLatLike.ts +++ /dev/null @@ -1,5 +0,0 @@ -export type CoordinatesObject = - | { lng: number; lat: number } - | { lon: number; lat: number } - | { longitude: number; latitude: number } -export type LngLatLike = [number, number] | CoordinatesObject