JSPM

myquran-api

1.0.3
    • ESM via JSPM
    • ES Module Entrypoint
    • Export Map
    • Keywords
    • License
    • Repository URL
    • TypeScript Types
    • README
    • Created
    • Published
    • Downloads 4
    • Score
      100M100P100Q96470F
    • License MIT

    JavaScript/TypeScript library for MyQuran API

    Package Exports

    • myquran-api

    Readme

    MyQuran 🕌

    A modern, type-safe TypeScript/JavaScript library for accessing Indonesian prayer times through the MyQuran API.

    ✨ Features

    • 🎯 Zero Dependencies - Uses native fetch API only
    • 📦 Dual Package Support - CommonJS & ES Modules
    • 🔒 Type-Safe - Full TypeScript support with comprehensive type definitions
    • 🌐 Universal - Works in Node.js (>=14) and modern browsers
    • 🚀 Lightweight - Minimal bundle size
    • 📝 Well Documented - Complete JSDoc comments with examples
    • ⚡ Modern API - Clean async/await interface
    • 🛡️ Error Handling - Custom error class with detailed messages
    • 🕌 Complete API Coverage - Prayer times, location search, and Hijriyah calendar conversion

    📦 Installation

    # npm
npm install myquran-api

# yarn
yarn add myquran-api

# pnpm
pnpm add myquran-api

    🚀 Quick Start

    import myquran from "myquran-api";

// Search for a location
const locations = await myquran.cariLokasi("jakarta");
console.log(locations[0]); // { id: '1101', lokasi: 'KAB. JAKARTA' }

// Get today's prayer schedule
const schedule = await myquran.getJadwalHariIni(locations[0].id);
console.log(`Fajr: ${schedule.jadwal.subuh}`);
console.log(`Dhuhr: ${schedule.jadwal.dzuhur}`);
console.log(`Asr: ${schedule.jadwal.ashar}`);
console.log(`Maghrib: ${schedule.jadwal.maghrib}`);
console.log(`Isha: ${schedule.jadwal.isya}`);

    📚 API Reference

    Location Methods

    cariLokasi(keyword: string): Promise<Lokasi[]>

    Search for locations by keyword.

    const locations = await myquran.cariLokasi("jakarta");
console.log(locations);
// [
//   { id: '1101', lokasi: 'KAB. JAKARTA' },
//   { id: '1102', lokasi: 'KOTA JAKARTA SELATAN' },
//   ...
// ]

    getLokasi(id: string | number): Promise<Lokasi>

    Get location details by ID.

    const location = await myquran.getLokasi("1632");
console.log(location); // { id: '1632', lokasi: 'KOTA KEDIRI' }

    getSemuaLokasi(): Promise<Lokasi[]>

    Get all available locations.

    const allLocations = await myquran.getSemuaLokasi();
console.log(allLocations.length); // 1000+

    Prayer Schedule Methods

    getJadwalHarian(idLokasi: string | number, tanggal?: string | Date | 'today'): Promise<JadwalHarian>

    Get daily prayer schedule for a specific location and date.

    // Get today's schedule
const today = await myquran.getJadwalHarian("1632");

// Get specific date (string format)
const schedule = await myquran.getJadwalHarian("1632", "2024-06-23");

// Using Date object
const date = new Date("2024-06-23");
const schedule2 = await myquran.getJadwalHarian("1632", date);

console.log(schedule.jadwal);
// {
//   tanggal: 'Minggu, 23/06/2024',
//   imsak: '04:13',
//   subuh: '04:23',
//   terbit: '05:41',
//   dhuha: '06:10',
//   dzuhur: '11:38',
//   ashar: '14:57',
//   maghrib: '17:28',
//   isya: '18:42',
//   date: '2024-06-23'
// }

    getJadwalBulanan(idLokasi: string | number, tahun: number, bulan: number): Promise<JadwalBulanan>

    Get monthly prayer schedule for a specific location.

    const monthly = await myquran.getJadwalBulanan("1632", 2024, 6);
console.log(`Total days: ${monthly.jadwal.length}`); // 30

// Loop through all days
monthly.jadwal.forEach((day) => {
  console.log(`${day.tanggal}: Fajr at ${day.subuh}`);
});

    Helper Methods

    getJadwalHariIni(idLokasi: string | number): Promise<JadwalHarian>

    Shortcut to get today's prayer schedule.

    const schedule = await myquran.getJadwalHariIni("1632");
console.log(`Fajr: ${schedule.jadwal.subuh}`);

    getJadwalBulanIni(idLokasi: string | number): Promise<JadwalBulanan>

    Shortcut to get current month's prayer schedule.

    const schedule = await myquran.getJadwalBulanIni("1632");
console.log(`Total days: ${schedule.jadwal.length}`);

    Hijriyah Calendar Methods

    getTanggalHijriyahHariIni(adj?: number): Promise<TanggalHijriyah>

    Get today's Hijriyah (Islamic) date with optional adjustment.

    // Get today's Hijriyah date (default adjustment: -1)
const hijri = await myquran.getTanggalHijriyahHariIni();
console.log(hijri.date[0]); // Day name: "Jum'at"
console.log(hijri.date[1]); // Hijri date: "27 Syaban 1445 H"
console.log(hijri.date[2]); // Gregorian date: "08-03-2024"

// With custom adjustment
const hijriCustom = await myquran.getTanggalHijriyahHariIni(0);

    getTanggalHijriyah(tanggal?: string | Date | 'today', adj?: number): Promise<TanggalHijriyah>

    Get Hijriyah date for a specific Gregorian date.

    // Get specific date
const hijri = await myquran.getTanggalHijriyah("2024-06-23");
console.log(hijri.date[1]); // "16 Dzulhijjah 1445 H"

// Using Date object
const date = new Date("2024-06-23");
const hijri2 = await myquran.getTanggalHijriyah(date);

// With custom adjustment
const hijri3 = await myquran.getTanggalHijriyah("2024-06-23", 0);

// Response structure:
// date[0] = Day name (e.g., "Ahad")
// date[1] = Hijri date (e.g., "16 Dzulhijjah 1445 H")
// date[2] = Gregorian date (e.g., "23-06-2024")
// num[0] = Day index (1=Sunday, 7=Saturday)
// num[1] = Day number (1-31)
// num[2] = Gregorian month (1-12)
// num[3] = Gregorian year
// num[4] = Hijri day (1-30)
// num[5] = Hijri month (1-12)
// num[6] = Hijri year

    getDaftarHari(): Promise<any>

    Get list of day names and indices.

    const days = await myquran.getDaftarHari();
console.log(days);

    getDaftarBulan(): Promise<any>

    Get list of month names and indices.

    const months = await myquran.getDaftarBulan();
console.log(months);

    💡 Usage Examples

    Example 1: Search and Display Prayer Times

    import myquran from "myquran-api";

const locations = await myquran.cariLokasi("jakarta");
const schedule = await myquran.getJadwalHariIni(locations[0].id);

console.log(`Fajr: ${schedule.jadwal.subuh}`);
console.log(`Dhuhr: ${schedule.jadwal.dzuhur}`);
console.log(`Asr: ${schedule.jadwal.ashar}`);
console.log(`Maghrib: ${schedule.jadwal.maghrib}`);
console.log(`Isha: ${schedule.jadwal.isya}`);

    Example 2: Get Monthly Schedule

    import myquran from "myquran-api";

const monthly = await myquran.getJadwalBulanan("1632", 2024, 6);
console.log(`Total days: ${monthly.jadwal.length}`);

// Loop through all days
monthly.jadwal.forEach((day) => {
  console.log(`${day.tanggal}: Fajr at ${day.subuh}`);
});

    Example 3: Error Handling

    import myquran, { MyQuranError } from "myquran-api";

try {
  const schedule = await myquran.getJadwalHarian("1632", "2024-06-23");
  console.log(schedule);
} catch (error) {
  if (error instanceof MyQuranError) {
    console.error("MyQuran Error:", error.message);
    if (error.statusCode) {
      console.error("Status Code:", error.statusCode);
    }
  }
}

    Example 4: TypeScript Usage

    import myquran, { JadwalHarian, Lokasi } from "myquran-api";

const locations: Lokasi[] = await myquran.cariLokasi("bandung");
const schedule: JadwalHarian = await myquran.getJadwalHariIni("1301");

console.log(schedule.lokasi);
console.log(schedule.jadwal.subuh);

    Example 5: Custom Instance

    import { MyQuran } from "myquran-api";

const client = new MyQuran("https://custom-api.com/v2");
const schedule = await client.getJadwalHariIni("1632");

    Example 6: Complete Application

    import myquran from "myquran-api";

async function displayPrayerTimes(cityName: string) {
  try {
    // Search for location
    const locations = await myquran.cariLokasi(cityName);

    if (locations.length === 0) {
      console.log(`No locations found for "${cityName}"`);
      return;
    }

    // Get today's schedule
    const schedule = await myquran.getJadwalHariIni(locations[0].id);

    console.log(`\nPrayer Times for ${schedule.lokasi}`);
    console.log(`Date: ${schedule.jadwal.tanggal}\n`);
    console.log(`Imsak   : ${schedule.jadwal.imsak}`);
    console.log(`Fajr    : ${schedule.jadwal.subuh}`);
    console.log(`Sunrise : ${schedule.jadwal.terbit}`);
    console.log(`Dhuha   : ${schedule.jadwal.dhuha}`);
    console.log(`Dhuhr   : ${schedule.jadwal.dzuhur}`);
    console.log(`Asr     : ${schedule.jadwal.ashar}`);
    console.log(`Maghrib : ${schedule.jadwal.maghrib}`);
    console.log(`Isha    : ${schedule.jadwal.isya}`);
  } catch (error) {
    console.error("Error:", error.message);
  }
}

displayPrayerTimes("jakarta");

    Example 7: Hijriyah Calendar Conversion

    import myquran from "myquran-api";

// Get today's Hijriyah date
const today = await myquran.getTanggalHijriyahHariIni();
console.log(`Today is ${today.date[1]} (${today.date[2]})`);

// Get Hijriyah date for specific date
const ramadan = await myquran.getTanggalHijriyah("2024-03-11");
console.log(`\nHijriyah Date: ${ramadan.date[1]}`);
console.log(`Day: ${ramadan.date[0]}`);
console.log(`Gregorian: ${ramadan.date[2]}`);

// Access numeric values
console.log(`\nHijri Year: ${ramadan.num[6]}`);
console.log(`Hijri Month: ${ramadan.num[5]}`);
console.log(`Hijri Day: ${ramadan.num[4]}`);

// Get month lists
const months = await myquran.getDaftarBulan();
console.log("Available months:", months);

    🔧 TypeScript Types

    interface Lokasi {
  id: string;
  lokasi: string;
}

interface DetailLokasi extends Lokasi {
  daerah?: string;
}

interface JadwalSholat {
  tanggal: string;
  imsak: string;
  subuh: string;
  terbit: string;
  dhuha: string;
  dzuhur: string;
  ashar: string;
  maghrib: string;
  isya: string;
  date: string;
}

interface JadwalHarian {
  id: number;
  lokasi: string;
  daerah?: string;
  jadwal: JadwalSholat;
}

interface JadwalBulanan {
  id: number;
  lokasi: string;
  daerah?: string;
  jadwal: JadwalSholat[];
}

interface TanggalHijriyah {
  date: [string, string, string];
  num: [number, number, number, number, number, number, number];
}

class MyQuranError extends Error {
  statusCode?: number;
}

    ⚠️ Error Handling

    The library uses a custom MyQuranError class for all errors:

    import { MyQuranError } from "myquran-api";

try {
  await myquran.cariLokasi("");
} catch (error) {
  if (error instanceof MyQuranError) {
    console.error(error.message); // "Keyword cannot be empty"
  }
}

    Common error messages:

    • "Keyword cannot be empty" - Empty search keyword
    • "Location ID must be a 4-digit number" - Invalid location ID format
    • "Date format must be YYYY-MM-DD or YYYY/MM/DD" - Invalid date format
    • "Year must be 4 digits" - Invalid year
    • "Month must be between 1-12" - Invalid month
    • "HTTP error: [status]" - Network/API errors
    • "API returned status: false" - API returned error

    🌐 Browser Support

    This library works in any environment that supports ES2020 and the native fetch API:

    • Node.js >= 14
    • Modern browsers (Chrome, Firefox, Safari, Edge)
    • Deno
    • Cloudflare Workers
    • Vercel Edge Functions

    📝 License

    MIT License - see LICENSE file for details.

    🙏 Credits

    This library is a wrapper for the MyQuran.com API. All prayer time data is provided by MyQuran.com.

    📧 Support

    If you have any questions or issues, please open an issue on GitHub.

    Made with ❤️ for the Muslim community