Quick start

Get started with quran-search-engine in minutes

1. Install the package

   Complete the installation to add quran-search-engine to your project.

2. Load the data

   Load the Quran dataset, morphology map, and word map at app startup:

   TypeScript

   import {
     search,
     loadMorphology,
     loadQuranData,
     loadWordMap,
     type SearchResponse,
   } from 'quran-search-engine';
   
   const [quranData, morphologyMap, wordMap] = await Promise.all([
     loadQuranData(),
     loadMorphology(),
     loadWordMap(),
   ]);
   // Example output:
   // quranData.length => 6236
   // morphologyMap.size => 6236
   // Object.keys(wordMap).length => (depends on dataset)
   

   Examples assume an async context (Node 18+, ESM, or browser).
3. Perform a search

   Use the search function with your query and loaded data:

   TypeScript

   const response: SearchResponse = search('الله الرحمن', quranData, morphologyMap, wordMap, {
     lemma: true,
     root: true,
   });
   
   response.results.forEach((v) => {
     console.log(v.sura_id, v.aya_id, v.matchType, v.matchScore);
   });
   // Example output:
   // 1 1 exact 6
   // 1 3 lemma 4
   

Search options

The search function accepts the following options to control matching behavior:

Option	Type	Description
lemma	boolean	Enable lemma-based matching (morphological analysis)
root	boolean	Enable root-based matching (word etymology)
fuzzy	boolean	Enable fuzzy fallback matching (optional, defaults to true)

Match scoring

Each match type has a different score weight:

Match type	Score per hit
Exact	+3
Lemma	+2
Root	+1
Fuzzy	+0.5 (fallback only)

Pagination

Control the number of results returned using pagination options:

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

The response includes pagination metadata:

response.pagination
// => { totalResults: 42, totalPages: 5, currentPage: 1, limit: 10 }

Search response structure

The SearchResponse object contains:

• results: Array of ScoredQuranText objects with match metadata
• counts: Breakdown of matches by type (exact, lemma, root, fuzzy)
• pagination: Current page info and total results

Each result includes:

{
  gid: number;              // Unique verse ID
  sura_id: number;          // Chapter number
  aya_id: number;           // Verse number
  uthmani: string;          // Uthmani script text
  standard: string;         // Standard Arabic text
  matchScore: number;       // Total match score
  matchType: MatchType;     // Best match type ('exact' | 'lemma' | 'root' | 'fuzzy')
  matchedTokens: string[];  // Tokens that matched (for highlighting)
  // ... additional fields
}

Next steps

Search API

Explore all search options and advanced features

Highlighting

Learn how to highlight matched text in your UI