loadQuranData()

Lazily loads the Quran text data with code splitting support

Overview

Lazily loads the Quran text data. This dataset is loaded asynchronously to avoid increasing the initial bundle size.

Signature

export const loadQuranData = async (): Promise<QuranText[]>

Return value

Promise<QuranText[]> · Promise

A Promise that resolves to an array of QuranText objects. Each object represents a single verse from the Quran with metadata.

QuranText structure

Each verse in the returned array contains:

gid · number

Global unique identifier for the verse

sura_id · number

Chapter (Surah) number (1-114)

aya_id · number

Verse (Ayah) number within the chapter

aya_id_display · string

Display-formatted verse identifier

uthmani · string

Quranic text in Uthmani script with diacritics (tashkeel)

standard · string

Quranic text in standard Arabic script

standard_full · string

Full standard text including Bismillah

page_id · number

Page number in the Mushaf

juz_id · number

Juz (part) number (1-30)

sura_name · string

Chapter name in Arabic

sura_name_en · string

Chapter name in English

sura_name_romanization · string

Romanized chapter name

Example

import { loadQuranData, type QuranText } from 'quran-search-engine';

const quranData: QuranText[] = await loadQuranData();

// Total verses in the Quran
console.log(quranData.length); // => 6236

// First verse (Al-Fatiha 1:1)
console.log(quranData[0]);
// => {
//   gid: 1,
//   sura_id: 1,
//   aya_id: 1,
//   uthmani: 'بِسْمِ ٱللَّهِ ٱلرَّحْمَٰنِ ٱلرَّحِيمِ',
//   standard: 'بسم الله الرحمن الرحيم',
//   ...
// }

Usage with search

Load once at application startup, then reuse across multiple searches:

import {
  search,
  loadQuranData,
  loadMorphology,
  loadWordMap,
} from 'quran-search-engine';

const [quranData, morphologyMap, wordMap] = await Promise.all([
  loadQuranData(),
  loadMorphology(),
  loadWordMap(),
]);

const response = search('الله الرحمن', quranData, morphologyMap, wordMap, {
  lemma: true,
  root: true,
});

Data source

The Quran text data comes from Quranic Arabic Corpus v4.0: https://corpus.quran.com

Error handling

Throws an error if the data file cannot be loaded:

try {
  const quranData = await loadQuranData();
} catch (error) {
  console.error('Failed to load Quran data:', error);
  // Error: Could not load Quran data. Ensure src/data/quran.json exists.
}