Documentation Index
Fetch the complete documentation index at: https://mintlify.com/adelpro/quran-search-engine/llms.txt
Use this file to discover all available pages before exploring further.
Overview
Lazily loads the Quran morphology data. This large dataset is loaded asynchronously to avoid increasing the initial bundle size. The morphology data enables lemma and root matching for advanced search capabilities.
Signature
export const loadMorphology = async (): Promise<Map<number, MorphologyAya>>
Return value
Promise<Map<number, MorphologyAya>>
A Promise that resolves to a Map where the key is the verse global identifier (gid) and the value is morphology data for that verse.
MorphologyAya structure
Each morphology entry contains:
Global unique identifier for the verse (matches QuranText.gid)
Array of lemmas (dictionary forms) for all words in the verse
Array of roots for all words in the verse
Example
import { loadMorphology, type MorphologyAya } from 'quran-search-engine';
const morphologyMap: Map<number, MorphologyAya> = await loadMorphology();
// Total verses with morphology data
console.log(morphologyMap.size); // => 6236
// Get morphology for first verse (gid: 1)
const firstVerse = morphologyMap.get(1);
console.log(firstVerse);
// => {
// gid: 1,
// lemmas: ['ب', 'اسم', 'الله', 'الرحمن', 'الرحيم'],
// roots: ['ب س م', 'س م و', 'ا ل ه', 'ر ح م', 'ر ح م']
// }
Usage with search
Enable lemma and root matching by providing the morphology map:
import {
search,
loadQuranData,
loadMorphology,
loadWordMap,
} from 'quran-search-engine';
const [quranData, morphologyMap, wordMap] = await Promise.all([
loadQuranData(),
loadMorphology(),
loadWordMap(),
]);
// Search with lemma and root matching enabled
const response = search('الله الرحمن', quranData, morphologyMap, wordMap, {
lemma: true, // Uses morphologyMap for lemma matching
root: true, // Uses morphologyMap for root matching
});
console.log(response.results[0]);
// => {
// gid: 1,
// matchType: 'exact',
// matchScore: 6,
// ...
// }
Data structure benefits
The function transforms the source array into a Map for O(1) lookup performance:
// Fast lookups by verse gid
const verse123 = morphologyMap.get(123);
Data source
The morphological data (lemmas and roots) comes from Quranic Arabic Corpus v4.0: https://corpus.quran.com
Error handling
Throws an error if the morphology data file cannot be loaded:
try {
const morphologyMap = await loadMorphology();
} catch (error) {
console.error('Failed to load morphology data:', error);
// Error: Could not load morphology data. Ensure src/data/morphology.json exists.
}
Without morphology
You can still use the search function without morphology data (lemma/root matching disabled):
import { search, loadQuranData } from 'quran-search-engine';
const quranData = await loadQuranData();
// Use empty Map if morphology not needed
const response = search('الله', quranData, new Map(), {}, {
lemma: false,
root: false,
});
// Only exact text matching will be performed