EQuran NPM Package

NEW

Official Node.js SDK untuk EQuran.id API v2. Akses data Al-Quran, Tafsir, dan Audio dengan mudah!

Tentang EQuran Package

SDK resmi yang menyediakan akses lengkap ke data Al-Quran dengan fitur caching dan TypeScript support

114

Surat

6,236

Ayat

Qari Audio

TypeScript

Fitur Utama

Data Lengkap

Semua 114 Surat dengan 6,236 Ayat lengkap dengan teks Arab, Latin, dan terjemahan Indonesia

Tafsir

Interpretasi lengkap untuk setiap ayat Al-Quran

Audio Recitations

6 Qari terkenal: Abdullah Al-Juhany, Abdul Muhsin Al-Qasim, dll

Built-in Caching

In-memory cache dengan TTL support untuk performa optimal

TypeScript

Full type definitions untuk pengalaman development yang lebih baik

Dual Format

Support ESM dan CommonJS untuk kompatibilitas maksimal

Instalasi

Pasang package menggunakan package manager pilihan Anda

npm

npm install equran

yarn

yarn add equran

pnpm

pnpm add equran

Quick Start

Mulai menggunakan EQuran package dalam hitungan menit

import { EQuran } from 'equran';

const quran = new EQuran();

// Get all surahs
const surahs = await quran.getAllSurat();

// Get a specific surah with all verses
const alFatihah = await quran.getSurat(1);

// Get tafsir
const tafsir = await quran.getTafsir(1);

API Reference

Daftar lengkap fungsi yang tersedia

Core
Fungsi Utama

Fungsi	Deskripsi
getAllSurat()	Mendapatkan daftar semua 114 surat
getSurat(nomor)	Mendapatkan detail surat dengan semua ayat
getTafsir(nomor)	Mendapatkan tafsir untuk suatu surat

Helper
Fungsi Pembantu

Fungsi	Deskripsi
getAyat(suratNomor, ayatNomor)	Mendapatkan satu ayat spesifik
getAyatRange(suratNomor, from, to)	Mendapatkan rentang ayat
getSuratByName(name)	Mencari surat berdasarkan nama Latin
searchSurat(keyword)	Pencarian surat berdasarkan keyword
getMakkiyahSurat()	Mendapatkan semua surat Makkiyah (86 surat)
getMadaniyahSurat()	Mendapatkan semua surat Madaniyah (28 surat)

Audio
Fungsi Audio

Fungsi	Deskripsi
getAudioFull(suratNomor, qariId?)	Mendapatkan URL audio full surat
getAudioAyat(suratNomor, ayatNomor, qariId?)	Mendapatkan URL audio per ayat
getQariList()	Mendapatkan daftar Qari yang tersedia

Utility
Fungsi Utilitas

Fungsi	Deskripsi
getTafsirAyat(suratNomor, ayatNomor)	Mendapatkan tafsir untuk ayat spesifik
getRandomAyat()	Mendapatkan ayat acak dengan konteks surat
getSuratInfo(nomor)	Info surat tanpa ayat (lebih ringan)
getNextSurat(currentNomor)	Mendapatkan surat selanjutnya
getPrevSurat(currentNomor)	Mendapatkan surat sebelumnya

Advanced
Fungsi Lanjutan

Fungsi	Deskripsi
getSuratWithTafsir(nomor)	Surat + Tafsir dalam satu panggilan (parallel)
bulkGetSurat(nomorList)	Fetch multiple surat secara parallel

Cache
Manajemen Cache

Fungsi	Deskripsi
clearCache()	Menghapus semua data cache
getCacheStats()	Statistik cache (hits, misses, size, hitRate)
pruneCache()	Menghapus cache entries yang expired

Konfigurasi

Opsi konfigurasi yang tersedia

const quran = new EQuran({
  // Base API URL (default: https://equran.id/api/v2)
  baseUrl: 'https://equran.id/api/v2',
  
  // Request timeout in milliseconds (default: 30000)
  timeout: 30000,
  
  // Cache configuration
  cache: {
    enabled: true,      // Enable caching (default: true)
    ttl: 60 * 60 * 1000, // TTL in ms (default: 1 hour)
    maxSize: 200,        // Max cache entries (default: 200)
  }
});

TypeScript Support

Semua types tersedia untuk digunakan

import type {
  Surat,
  SuratDetail,
  Ayat,
  TafsirDetail,
  TafsirAyat,
  QariInfo,
  RandomAyat,
  AyatRange,
  SuratWithTafsir,
  EQuranConfig,
  CacheStats,
  AudioMap,
} from 'equran';

Error Handling

Menangani error dengan baik

import { EQuran, EQuranApiError } from 'equran';

try {
  const surah = await quran.getSurat(999);
} catch (error) {
  if (error instanceof EQuranApiError) {
    console.error(`API Error: ${error.message}`);
    console.error(`Status Code: ${error.statusCode}`);
    console.error(`Endpoint: ${error.endpoint}`);
  }
}

Contoh Penggunaan

Implementasi praktis untuk berbagai use case

📅 Daily Verse Widget

async function getDailyVerse() {
  const quran = new EQuran();
  const random = await quran.getRandomAyat();
  
  return {
    surah: random.suratNamaLatin,
    verse: random.ayat.nomorAyat,
    arabic: random.ayat.teksArab,
    translation: random.ayat.teksIndonesia,
    audio: random.ayat.audio['05'],
  };
}

📖 Quran Reader

async function readSurah(nomor: number) {
  const quran = new EQuran();
  const surah = await quran.getSurat(nomor);
  
  console.log(`${surah.namaLatin} (${surah.nama})`);
  console.log(`${surah.tempatTurun} | ${surah.jumlahAyat} verses`);
  console.log(`Meaning: ${surah.arti}\n`);
  
  for (const ayat of surah.ayat) {
    console.log(`[${ayat.nomorAyat}] ${ayat.teksArab}`);
    console.log(`  ${ayat.teksIndonesia}\n`);
  }
}

📚 Surah with Tafsir

async function studySurah(nomor: number) {
  const quran = new EQuran();
  const { surat, tafsir } = await quran.getSuratWithTafsir(nomor);
  
  for (let i = 0; i < surat.ayat.length; i++) {
    const ayat = surat.ayat[i];
    const tafsirAyat = tafsir.tafsir[i];
    
    console.log(`--- Verse ${ayat.nomorAyat} ---`);
    console.log(`Arabic: ${ayat.teksArab}`);
    console.log(`Translation: ${ayat.teksIndonesia}`);
    console.log(`Tafsir: ${tafsirAyat.teks}\n`);
  }
}

Kembali ke API Hub NPM Package GitHub Repository