From 25cd44857e70e86e32de3ddc6c4fee346a296d20 Mon Sep 17 00:00:00 2001 From: gimy Date: Tue, 3 Oct 2023 14:53:59 +0800 Subject: [PATCH] docs: added calculator config section --- docs/.vitepress/config.ts | 7 +- docs/config/config.md | 153 +++++++++++++++++++++++++ docs/config/{index.md => formatter.md} | 2 +- docs/config/methods.md | 2 +- docs/config/static.md | 0 docs/guide/concepts.md | 4 +- docs/guide/one-time-calculator.md | 4 +- docs/guide/reactive-calculator.md | 2 +- docs/recipes/hijri.md | 2 +- docs/roadmap.md | 1 + examples/index.ts | 5 +- 11 files changed, 170 insertions(+), 12 deletions(-) create mode 100644 docs/config/config.md rename docs/config/{index.md => formatter.md} (89%) delete mode 100644 docs/config/static.md diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index c1b78b8..8c1ad0b 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -3,7 +3,7 @@ import { version } from '../../package.json' // if version doesn't work we need to use this plugin https://github.com/semantic-release/git export default defineConfig({ - title: 'prayers-call', + title: 'Prayers-Call', description: 'A reactive prayer times calculation library for node and the browser built with Typescript', ignoreDeadLinks: true, // FIXME: remove this when the docs are mature lastUpdated: true, @@ -44,7 +44,7 @@ function nav() { }, { text: 'Config', - link: '/config/index', + link: '/config/config', activeMatch: '/config/', }, { @@ -99,7 +99,8 @@ function sidebarGuide() { text: 'Config', collapsible: true, items: [ - { text: 'Config Reference', link: '/config/index' }, + { text: 'Calculators Config', link: '/config/config' }, + { text: 'Formatter Config', link: '/config/formatter' }, { text: 'Calculation Methods', link: '/config/methods' }, ], }, diff --git a/docs/config/config.md b/docs/config/config.md new file mode 100644 index 0000000..fbbcb3a --- /dev/null +++ b/docs/config/config.md @@ -0,0 +1,153 @@ +# Calculators Config + +The `StaticCalculator` and the `ReactiveCalculator` class in `prayers-call` both require a config object to be passed to their constructor. This page will guide you through the configuration options available for both. for configuration options specific to a calculator, it will be mentioned as such. Otherwise, the configuration options are available for both calculators. + +### date (`StaticCalculator` only) + +- Required: `true` +- Type: `Date` + +The date for which the prayer times will be calculated it can be past current or future. This property is specific to `StaticCalculator`. + +### latitude and longitude + +- Required: `true` +- Type: `number` + +The geographical coordinates of the location for which the prayer times will be calculated. + +### method + +- Required: `false` +- Type: `Methods | CustomMethod` +- Default: `Methods.UMM_AL_QURA` + +The calculation method to use. You can use one of the built-in methods or provide a custom method. for a comprehensive guide of available methods, see [Calculation Methods](./methods.md). + +### adjustments + +- Required: `false` +- Type: `Partial` +- Default: `{ fajr: 0, sunrise: 0, dhuhr: 0, asr: 0, maghrib: 0, isha: 0 }` + +Custom adjustments in minutes for each prayer time. + +### asrTime + +- Required: `false` +- Type: `AsrTime` +- Default: `AsrTime.JUMHOOR` + +Whether to use the earlier (Jumhoor) or later (Hanafi) Asr time calculation. + +### iqama + +- Required: `false` +- Type: `Partial` +- Default: `{ fajr: 20, dhuhr: 10, asr: 10, maghrib: 5, isha: 15 }` + +Waiting time in minutes for iqama after the actual prayer time. + +### adjustForRamadan + +- Required: `false` +- Type: `boolean` +- Default: `false` + +Whether to adjust the prayer times for Ramadan by adding 30 minutes to Isha. + +::: tip +When using `UMM_AL_QURA` method `prayer-calls` will automatically adjust the prayer times for Ramadan. This option is only useful when using other methods. +::: + +### hijriCalendar + +- Required: `false` +- Type: `HijriCalendar` +- Default: `HijriCalendar.UMM_AL_QURA` + +The Hijri calendar to use in conjunction with `adjustForRamadan` to determine the start and end of Ramadan. for a comprehensive list of available calendars, see [HijriCalendar](../api.md#HijriCalendar). + +### highLatitudeRule + +- Required: `false` +- Type: `ValueOf` +- Default: `HighLatitudeRule.MiddleOfTheNight` + +Rule to use for calculating prayer times at high latitudes. See the [Advanced section](#advanced-configuration) for more details. + +### polarCircleResolution + +- Required: `false` +- Type: `ValueOf` +- Default: `PolarCircleResolution.Unresolved` + +How to handle Midnight Sun & Polar Night days. See the [Advanced section](#advanced-configuration) for more details. + +### debug (`ReactiveCalculator` only) + +- Required: `false` +- Type: `boolean` +- Default: `false` + +Enable debugging logs for the `ReactiveCalculator`. + +## Example Usage + +Here's an example that includes multiple configuration options: + +```ts +import { StaticCalculator, Methods, HighLatitudeRule, AsrTime } from 'prayers-call' + +const calculator = new StaticCalculator({ + date: new Date(), + latitude: 40.7128, + longitude: -74.006, + method: Methods.NORTH_AMERICA, + adjustments: { fajr: 2, isha: -2 }, + highLatitudeRule: HighLatitudeRule.SeventhOfTheNight, + asrTime: AsrTime.HANAFI, + iqama: { fajr: 15, dhuhr: 10 }, + adjustForRamadan: true, +}) +``` + +## Advanced Configuration + +In certain geographical locations, calculating Islamic prayer times can be challenging due to the unique solar behavior. The `highLatitudeRule` and `polarCircleResolution` options in the configuration aim to address these challenges. + +### High Latitude Rule + +The `HighLatitudeRule` object provides three methods to calculate prayer times for locations with high latitudes (above 48.5° N or S), where the [twilight](https://en.wikipedia.org/wiki/Twilight) period can be extended. + +#### Options + +- **MiddleOfTheNight**: Divides the night (sunset to sunrise) in half to determine the latest time for Isha and the earliest time for Fajr. Essentially, neither Fajr nor Isha will occur before or after the midpoint of the night. + +- **SeventhOfTheNight**: Divides the night (sunset to sunrise) into seven parts. Fajr is set at the beginning of the last seventh of the night, and Isha at the end of the first seventh. This is particularly useful for locations above 48° latitude where twilight lasts longer. + +- **TwilightAngle**: Divide the night (sunset to sunrise) into roughly 1/3. The exact value is derived by dividing the fajr/isha angles by 60. It aims to prevent extremely early or late Fajr and Isha times. + +#### Recommended + +The `recommended` function can automatically select the most appropriate high latitude rule based on the geographical coordinates. For example, for Oslo, Norway, you can use: + +```ts +import { HighLatitudeRule } from 'prayers-call' + +const rule = HighLatitudeRule.recommended({ latitude: 59.91, longitude: 10.75 }) // SeventhOfTheNight +``` + +In places like Oslo, Norway, where the sun barely sets during summer, using the `SeventhOfTheNight` rule can make prayer times more manageable. This rule ensures that Isha is not too late and Fajr is not too early, making it easier for people to observe their prayers. + +### Polar Circle Resolution + +This setting is crucial for locations within the polar circles (above approximately 66.5° N or S) where there may be days when the sun never sets (Midnight Sun) or never rises (Polar Night). The options help to resolve prayer times on such days. + +#### Options + +- **AqrabBalad:** This option calculates the prayer times based on the closest geographical location where conventional sunrise and sunset times are available. Essentially, it "borrows" the prayer times from the nearest place where the sun does rise and set. + +- **AqrabYaum:** This calculates the prayer times based on the closest date (either in the past or future) when conventional sunrise and sunset times can be determined. In other words, it uses the prayer times from the nearest "normal" day. + +- **Unresolved:** This is the default setting. It leaves the sunrise and sunset prayer times undefined when they can't be computed due to the extreme latitude. diff --git a/docs/config/index.md b/docs/config/formatter.md similarity index 89% rename from docs/config/index.md rename to docs/config/formatter.md index 69d897e..465c9ce 100644 --- a/docs/config/index.md +++ b/docs/config/formatter.md @@ -1,4 +1,4 @@ -# Configuration Reference +# Formatter Config WIP diff --git a/docs/config/methods.md b/docs/config/methods.md index 0c99e39..bec4c4b 100644 --- a/docs/config/methods.md +++ b/docs/config/methods.md @@ -1,3 +1,3 @@ -# Available Methods +# Calculation Methods WIP diff --git a/docs/config/static.md b/docs/config/static.md deleted file mode 100644 index e69de29..0000000 diff --git a/docs/guide/concepts.md b/docs/guide/concepts.md index 9de188d..4cc67aa 100644 --- a/docs/guide/concepts.md +++ b/docs/guide/concepts.md @@ -29,7 +29,7 @@ calculator.getPrayerTimes() For a detailed list of available functions within th `StaticCalculator` class, consult the [One time Calculator](./one-time-calculator.md) documentation. -For configuration options, refer to the [Config](../config.md) section. +For configuration options, refer to the [Config](../config/config.md) section. ## Reactive Calculator @@ -64,7 +64,7 @@ adhanSubscription.unsubscribe() For a detailed list of available functions within the `ReactiveCalculator` class, consult the [Reactive Calculator](./reactive-calculator.md) documentation. -For configuration options, refer to the [Config](../config.md) section. +For configuration options, refer to the [Config](../config/config.md) section. ## Date formatting diff --git a/docs/guide/one-time-calculator.md b/docs/guide/one-time-calculator.md index 6a59733..bc9a846 100644 --- a/docs/guide/one-time-calculator.md +++ b/docs/guide/one-time-calculator.md @@ -15,7 +15,7 @@ const calculator = new StaticCalculator({ }) ``` -For configuration details, refer to the [Config](../config.md) section. +For configuration details, refer to the [Config](../config/config.md) section. ## Available Functions @@ -174,7 +174,7 @@ calculator.getCalculationOptions() Allows you to update the calculator's configuration without creating a new instance. Accepts a `newConfig` param of type `Partial`. -For configuration details, refer to the [Config](../config.md) section. +For configuration details, refer to the [Config](../config/config.md) section. ```ts import { Methods, StaticCalculator } from 'prayer-call' diff --git a/docs/guide/reactive-calculator.md b/docs/guide/reactive-calculator.md index 7ebbfb2..6bd56ba 100644 --- a/docs/guide/reactive-calculator.md +++ b/docs/guide/reactive-calculator.md @@ -151,7 +151,7 @@ reactiveCalculator.cleanup() ``` ::: tip -The default time intervals in minutes between Adhan and Iqama are: `{ fajr: 20, dhuhr: 10, asr: 10, maghrib: 5, isha: 15 }` You can customize these intervals in the `ReactiveCalculator` configuration. For more details, see the [Config](../config.md) section. +The default time intervals in minutes between Adhan and Iqama are: `{ fajr: 20, dhuhr: 10, asr: 10, maghrib: 5, isha: 15 }` You can customize these intervals in the `ReactiveCalculator` configuration. For more details, see the [Config](../config/config.md) section. ::: ### `qiyamTimesObserver` diff --git a/docs/recipes/hijri.md b/docs/recipes/hijri.md index cc4e7a3..5dc250d 100644 --- a/docs/recipes/hijri.md +++ b/docs/recipes/hijri.md @@ -2,7 +2,7 @@ The `Formatter` class uses the [`Intl.DateTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat) API which supports the Hijri calendar. This means that you can use the `calendar` option to format dates and times in the Hijri calendar. -:: tip +::: tip For detailed information on formatting dates and times and how to use the `Formatter` class, visit the [Date/Time Formatting](./formatters.md) section. ::: diff --git a/docs/roadmap.md b/docs/roadmap.md index e2768ba..9eaf47d 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -1,3 +1,4 @@ +- Write more tests to cover the library - Offer open source tools to make comparing and building calculation methods easier. - Re-write the library from scratch making it reactive from the ground up (using vue 3 reactive core api) - improve the docs to have examples imported from actual ts files diff --git a/examples/index.ts b/examples/index.ts index 158196f..af82779 100644 --- a/examples/index.ts +++ b/examples/index.ts @@ -1,5 +1,5 @@ import { Methods } from '../src/types/Methods' -import { Formatter, HijriCalendar, PrayerNames, ReactiveCalculator, StaticCalculator } from '../src' +import { Formatter, HighLatitudeRule, HijriCalendar, PrayerNames, ReactiveCalculator, StaticCalculator } from '../src' import type { TimeEventObject } from '../src' import { TimesNames } from '../src/types/TimeObject' @@ -24,6 +24,9 @@ const formatterExample = new Formatter({ const date = new Date(2022, 1, 1) console.log('default formatter', formatterExample.formatDate(date)) + +const rule = HighLatitudeRule.recommended({ latitude: 59.91, longitude: 10.75 }) // SeventhOfTheNight +console.log(rule) // console.log(calculator.getPrayerTime(PrayerNames.FAJR)) // console.log('Middle', calculator.getMiddleOfTheNightTime().time?.toLocaleString()) // console.log('LastThird', calculator.getLastThirdOfTheNightTime().time?.toLocaleString())