CPRAY

Module to retrieve prayer times from the official JAKI Malaysia website

إِنَّ الصَّلَاةَ كَانَتْ عَلَى الْمُؤْمِنِينَ كِتَابًا مَوْقُوتًا - سورة النساء 4:103

Indeed, prayer has been decreed upon the believers a decree of specified times - Surah An-Nisa 4:103

This module retrieves prayer times from the official JAKIM website (e-solat) and returns the data as a JSON object. It also provides a human-readable format for the prayer times. Starting from version 1.2.0, a fallback URL (https://api.waktusolat.me) has been added to ensure reliability even if the main URL is down.

Functions

There are 4 functions that can be used to retrieve prayer times:

getTimesToday(zone); // Returns prayer times for today

getTimesbyWeek(zone); // Returns prayer times for the week

getTimesbyMonth(zone); // Returns prayer times for the month

getTimesbyYear(zone); // Returns prayer times for the year

Zones

The zones are:

1. Kedah

KDH01: KOTA SETAR, POKOK SENA DAN KUBANG PASU
KDH02: KUALA MUDA, PENDANG DAN YAN
KDH03: PADANG TERAP DAN SIK
KDH04: BALING
KDH05: KULIM DAN BANDAR BAHARU
KDH06: LANGKAWI
KDH07: GUNUNG JERAI

2. Melaka

MLK01: SELURUH NEGERI MELAKA

3. Negeri Sembilan

NGS01: JEMPOL DAN TAMPIN
NGS02: PORT DICKSON, SEREMBAN, KUALA PILAH, JELEBU DAN REMBAU

4. Pahang

PHG01: PULAU TIOMAN
PHG02: ROMPIN, PEKAN, MUADZAM SHAH DAN KUANTAN
PHG03: MARAN, CHENOR, TEMERLOH, BERA, JENGKA DAN JERANTUT
PHG04: BENTONG, RAUB DAN LIPIS
PHG05: BUKIT TINGGI, GENTING SEMPAH, DAN JANDA BAIK
PHG06: CAMERON HIGHLANDS, BUKIT FRASER DAN GENTING HIGHLANDS

5. Perak

PRK01: TAPAH, SLIM RIVER DAN TANJUNG MALIM
PRK02: IPOH, BATU GAJAH, KAMPAR, SG. SIPUT DAN KUALA KANGSAR
PRK03: PENGKALAN HULU, GERIK DAN LENGGONG
PRK04: TEMENGOR DAN BELUM
PRK05: TELUK INTAN, BAGAN DATUK, KG. GAJAH, SERI ISKANDAR, BERUAS, PARIT, LUMUT, SITIAWAN DAN PULAU PANGKOR.
PRK06: SELAMA, TAIPING, BAGAN SERAI DAN PARIT BUNTAR
PRK07: BUKIT LARUT

6. Perlis

PLS01: SELURUH NEGERI PERLIS

7. Pulau Pinang

PNG01: SELURUH NEGERI PULAU PINANG

8. Selangor

SGR01: HULU SELANGOR, GOMBAK, PETALING/SHAH ALAM, HULU LANGAT DAN SEPANG
SGR02: SABAK BERNAM DAN KUALA SELANGOR
SGR03: KLANG DAN KUALA LANGAT

9. Terengganu

TRG01: KUALA TERENGGANU, MARANG DAN KUALA NERUS
TRG02: BESUT DAN SETIU
TRG03: HULU TERENGGANU
TRG04: DUNGUN DAN KEMAMAN

10. Johor

JHR01: PULAU AUR DAN PULAU PEMANGGIL
JHR02: KOTA TINGGI, MERSING DAN JOHOR BAHRU
JHR03: KLUANG DAN PONTIAN
JHR04: BATU PAHAT, MUAR, SEGAMAT DAN GEMAS JOHOR

11. Kelantan

KTN01: JAJAHAN KOTA BHARU, BACHOK, PASIR PUTEH, TUMPAT , PASIR MAS, TANAH MERAH, MACHANG KUALA KRAI DAN GUA MUSANG (DAERAH CHIKU)
KTN03: (THIS IS NOT A TYPO) JAJAHAN JELI, GUA MUSANG (DAERAH GALAS DAN BERTAM) DAN JAJAHAN KECIL LOJING

12. Sabah

SBH01: BAHAGIAN SANDAKAN (TIMUR) BANDAR SANDAKAN, BUKIT GARAM, SEMAWANG, TEMANGGONG DAN TAMBISAN
SBH02: BAHAGIAN SANDAKAN (BARAT) PINANGAH, TERUSAN, BELURAN, KUAMUT DAN TELUPID
SBH03: BAHAGIAN TAWAU (TIMUR) LAHAD DATU, KUNAK, SILABUKAN, TUNGKU, SAHABAT, DAN SEMPORNA
SBH04: BAHAGIAN TAWAU (BARAT), BANDAR TAWAU, BALONG, MEROTAI DAN KALABAKAN
SBH05: BAHAGIAN KUDAT KUDAT, KOTA MARUDU, PITAS DAN PULAU BANGGI
SBH06: GUNUNG KINABALU
SBH07: BAHAGIAN PANTAI BARAT KOTA KINABALU, PENAMPANG, TUARAN, PAPAR, KOTA BELUD, PUTATAN DAN RANAU
SBH08: BAHAGIAN PEDALAMAN (ATAS) PENSIANGAN, KENINGAU, TAMBUNAN DAN NABAWAN
SBH09: BAHAGIAN PEDALAMAN (BAWAH) SIPITANG, MEMBAKUT, BEAUFORT, KUALA PENYU, WESTON, TENOM DAN LONG PA SIA

13. Sarawak

SWK01: LIMBANG, SUNDAR, TRUSAN DAN LAWAS
SWK02: NIAH, SIBUTI, MIRI, BEKENU DAN MARUDI
SWK03: TATAU, SUAI, BELAGA, PANDAN, SEBAUH, BINTULU
SWK04: IGAN, KANOWIT, SIBU, DALAT, OYA, BALINGIAN, MUKAH, KAPIT DAN SONG
SWK05: BELAWAI, MATU, DARO, SARIKEI, JULAU, BINTANGOR DAN RAJANG
SWK06: KABONG, LINGGA, SRI AMAN, ENGKELILI, BETONG, SPAOH, PUSA, SARATOK, ROBAN, DEBAK DAN LUBOK ANTU
SWK07: SAMARAHAN, SIMUNJAN, SERIAN, SEBUYAU DAN MELUDAM
SWK08: KUCHING, BAU, LUNDU DAN SEMATAN
SWK09: KAMPUNG PATARIKAN

14. Wilayah Persekutuan

WLY01: KUALA LUMPUR DAN PUTRAJAYA
WLY02: LABUAN

Usage

Install the module with npm:

npm install cpray

Require the Cpray class and create a new instance:

const Cpray = require('cpray');
const cpray = new Cpray();

You can then use the instance to get prayer times. Here's an example of getting the prayer times for a week for the 'KDH01' zone using async/await:

async function getPrayerTimes() {
  try {
    const times = await cpray.getTimesbyWeek('KDH01');
    console.log(times);
  } catch (error) {
    console.error(error);
  }
}

getPrayerTimes();

And here's the same example using .then/.catch:

cpray
  .getTimesbyWeek('KDH01')
  .then((times) => {
    console.log(times);
  })
  .catch((error) => {
    console.error(error);
  });

Please note, the zone is not case sensitive. You can use either 'KDH01' or 'kdh01' or 'Kdh01' or even 'kDh01' or 'kdH01' (if you must).

Errors

The module will throw an error in the following scenarios:

The zone is not specified or invalid: Each method of the Cpray class requires a zone parameter, which should be a string representing a valid zone. The valid zones are hardcoded in the module. If the zone parameter is not provided, or if it's not included in the list of valid zones, the method will throw an error with the message 'Invalid zone: {zone}'.
Both the main and fallback URLs are down: The Cpray class uses two URLs to fetch prayer times: a main URL and a fallback URL. If the main URL fails (for example, if the server is down or the request times out), the class will automatically try the fallback URL. If both URLs fail, the method will throw an error with the message 'Both main and fallback URLs failed'. This ensures that the class can still return prayer times even if one of the URLs is down, but it also means that it's dependent on at least one of the URLs being up.

Promises and Async/Await

The methods of the Cpray class return Promises, which are objects representing the eventual completion or failure of an asynchronous operation.

Promises

You can use the .then method to handle the result of a Promise:

cpray
  .getTimesToday('KDH01')
  .then((timesToday) => {
    console.log(timesToday);
  })
  .catch((error) => {
    console.error('Failed to fetch prayer times:', error.message);
  });

Async/Await

You can also use the async/await syntax to handle Promises in a way that resembles synchronous code:

async function fetchPrayerTimes() {
  try {
    const timesToday = await cpray.getTimesToday('KDH01');
    console.log(timesToday);
  } catch (error) {
    console.error('Failed to fetch prayer times:', error.message);
  }
}

fetchPrayerTimes();

Testing

The Cpray class comes with a suite of tests to ensure its methods work as expected. These tests cover various scenarios, including successful requests, failed requests, the use of both the main and fallback URLs and the use of valid and invalid zones.

To run the tests, you need to have Jest installed. If you don't have Jest installed, you can install it with npm:

npm install --save-dev jest

Once Jest is installed, you can run the tests with the following command:

npm test

The tests ensure that the Cpray class handles Promises and errors correctly using async/await syntax, as well as .then and .catch. They also use try-catch blocks for error handling. Special attention is given to scenarios where an invalid zone is provided. The Cpray class methods require a zone parameter, representing a valid zone. These zones are hardcoded in the module. If an invalid zone is provided, the method will throw an error with the message 'Invalid zone: {zone}'.

cpray