loadMorphology()

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

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:

number

Global unique identifier for the verse (matches QuranText.gid)

string[]

Array of lemmas (dictionary forms) for all words in the verse

string[]

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

Search

Data Loaders

Normalization

Highlighting

Types

Overview

Signature

Return value

MorphologyAya structure

Example

Usage with search

Data structure benefits

Data source

Error handling

Without morphology

​Overview

​Signature

​Return value

​MorphologyAya structure

​Example

​Usage with search

​Data structure benefits

​Data source

​Error handling

​Without morphology

Overview

Signature

Return value

MorphologyAya structure

Example

Usage with search

Data structure benefits

Data source

Error handling

Without morphology