prayer-timetable-lib

About

This package serves as a convenient way to display your daily prayers, both for individual use or for masjids. This library is not for automatic calculation of prayer times based on location. Based on my experience, 'automatic' prayer apps do not display exactly the same time as local masjids, which comes to be an issue if determining exact time the prayer commences or your fast begins and ends.

You need to provide 2 inputs, one with prayer times and second with settings. More details below. The lib itself exports 2 functions, namely prayersCalc() and dayCalc().

Installation - Yarn:

yarn add prayer-timetable-lib

Installation - NPM:

npm i prayer-timetable-lib

Usage:

import { prayersCalc, dayCalc } from 'prayer-timetable-lib'

Prayers Calculation

The prayersCalc() function takes following arguments: prayersCalc(timetable, settings, showJamaah, city)

• timetable: timetable object / json file in the format as shown below. Defaults to included timetable json file.
• settings: settings object as discussed below. Defaults to included generic settings json file.
• show: boolean value (true/false) to display jamaah times. Default is true.
• city: used for daylight saving calculation, as in time zones list. Defaults to Europe/Dublin.

The function returns the following:

{
    prayers: {
        today: [], // returns list of today's prayers, see below
        yesterday: [], // list of yesterday's prayers, see below
        tomorrow [], // list of tomorrow's prayers, see below
    },
    previous, // returns single item from prayer list, relative to now. Moment object.
    current, // as above, current
    next, // as above, next
    focus, // it is next prayer/jamaah in focus; if the jamaah is pending it will be jamaah time object, otherwise it is same as 'next' above
    countUp: {
        name, // string, name of current prayer
        time, // moment object, time of current prayer
        duration // moment duration object, time since last prayer (or jamaah time if on)
    }
    countDown: {name, time, duration}, // as above, refers to next prayer / jamaah
    now, // moment() object - time now
    hijri, // as above but incorporates hijri day adjustment
    percentage, // moment duration object, percentage of time passed from previous prayer/jamaah to next prayer/jamaah.
    isAfterIsha, // boolean, shows if current time is after isha prayer/jamaah
}

Prayer list above (there are six total - fajr, shurooq, dhuhr, asr, maghrib, isha; 0-5), each one returning the following:

{
    time, // moment object, time of the prayer
    isJamaahPending, // boolean, shows if jamaah is next
    jtime, // moment object, time of the jamaah
    index, // number of prayer (ie. 0 for fajr)
    hasPassed, // boolean, if the prayer is in the past
    name, // string, name of the prayer
    when, // string, today/tomorrow
    dstAdjust // number, daylight saving time adjustment -1, 0, 1
}

Day Calc

This is just a helper for some commonly used moment objects. It takes 4 arguments with displayed defaults:

dayCalc(offsetDay = 0, offSetHour = 0, hijrioffset = 0, city = 'Europe/Dublin')

Timetable File

Typically, you will have your timetable file in json format and import/conver to object such as this:

import timetable from './timetable.json'

It is structured as follows:

{
    "1": {
        "1": [[6,43],[8,37],[12,30],[14,3],[16,19],[18,7]],
        "2": [[6,43],[8,37],[12,31],[14,3],[16,20],[18,8]],
        "3": [[6,43],[8,37],[12,31],[14,4],[16,22],[18,9]],
        ...
    }
...
}

Starts with month (first "1"), followed by day in a month ("1", "2", "3", ...). Every day contains array of six sub-arrays with [hour:minute] (no zero prepend) displayed inside.

Settings file

Settings file would have the following minimum structure:

{
    "hijrioffset": "1",
    "join": "0",
    "jummuahtime": [13,15],
    "taraweehtime": [23,15],
    "jamaahmethods": ["beforenext","","beforenext","afterthis","afterthis","fixed"],
    "jamaahoffsets": [[0,30],[],[0,15],[0,15],[0,15],[22,25]],
}

• hijrioffset: adjust the hijri date, ie. 0, 1, -1
• join: 0/1, should maghrib and isha be prayed together in congregation
• jummuahtime: array, friday prayer time; not currently used by lib, but by other apps using it
• taraweehtime: array, taraweeh prayer time; not currently used by lib, but by other apps using it
• jamaahmethods: array of strings to calculate start of congregation prayer - "beforenext" - hours and minutes before next prayer (ie. when fajr is prayed 30 minutes before sun rise); "afterthis" - hours and minutes after adhan; "fixed" - fixed time for the prayer (H:m)
• jamaahoffsets - array of sub-arrays of numbers, used for methods above

Demo

Clone the repo and run demo app:

git clone https://gitlab.com/prayer-timetable/prayer-timetable-lib.git
cd prayer-timetable-lib
yarn
yarn demo

Demo looks like this:

26/Nov/2018 19/Rab-I/1440 dst: 0 isafterIsha: false

today    0 - fajr        06:14  07:35
today    1 - shurooq     08:05  08:05
today    2 - dhuhr       12:14  13:44
today    3 - asr         13:59  14:14
today    4 - maghrib     16:20  16:35 next
today    5 - isha        18:04  22:25

asr jamaah 14:14 1:22:23 << 15:36:23 >> 0:43:37 maghrib 16:20

█████████████████████████████████████############# 65.38

Use the provided code as you wish. You can, for example, when isha time passes, switch to tomorrow's prayer list.

import timetable from './timetable'
import settings from './settings'
const { prayers, isAfterIsha } = prayersCalc(timetable, settings)

const prayerList = isAfterIsha ? prayers.tomorrow : prayers.today

prayerList.forEach((element) => {
    console.log(
        element.when, '\t',
        element.index, \t,
        element.time.format('HH:mm'), \t, 
        element.jtime.format('HH:mm'), \t,
        element.name === next.name ? 'next' '', \t,
        element.isJamaahPending ? 'jamaah pending' : ''
    )
}

Other

This lib is used by prayer-timetable-react and other packages for convenient way to keep the prayer calculations separate from the design logic.