Skip to main content

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.

​
Signature

function search<TVerse extends VerseInput>(
  query: string,
  quranData: TVerse[],
  morphologyMap: Map<number, MorphologyAya>,
  wordMap: WordMap,
  options?: AdvancedSearchOptions,
  pagination?: PaginationOptions,
): SearchResponse<TVerse>

​
Description

Performs a comprehensive search across the Quran that combines simple text search with linguistic (lemma/root) analysis and fuzzy fallback. Results are scored, deduplicated, and sorted by relevance. This is your primary API for Quran search results with scoring and pagination.

​
Parameters

​
query
string
required
The search query in Arabic text. Non-Arabic characters are automatically stripped during processing.
​
quranData
TVerse[]
required
Array of Quran verses to search. Each verse must satisfy the VerseInput type with gid, uthmani, and standard fields.
​
morphologyMap
Map<number, MorphologyAya>
required
Map of verse morphology data indexed by gid. Each entry contains lemmas and roots arrays for linguistic matching.
​
wordMap
WordMap
required
Dictionary mapping normalized query tokens to their canonical lemma and root forms.
​
options
AdvancedSearchOptions
default:"{ lemma: true, root: true }"
Search options controlling linguistic matching:
  • lemma (boolean): Enable lemma-based matching
  • root (boolean): Enable root-based matching
  • fuzzy (boolean, optional): Enable fuzzy fallback matching (default: true)
Set fuzzy: false to disable fuzzy fallback when no exact/lemma/root matches are found.
​
pagination
PaginationOptions
default:"{ page: 1, limit: 20 }"
Pagination controls:
  • page (number, optional): Page number to retrieve (default: 1)
  • limit (number, optional): Results per page (default: 20)

​
Returns

​
SearchResponse
object
​
results
ScoredVerse[]
Array of matching verses with scoring metadata. Each result includes:
  • All original verse fields
  • matchScore (number): Weighted relevance score
  • matchType (MatchType): Best match type (‘exact’ | ‘lemma’ | ‘root’ | ‘fuzzy’ | ‘none’)
  • matchedTokens (string[]): Deduplicated matched tokens for highlighting
  • tokenTypes (Record<string, MatchType>): Match type for each token
​
counts
SearchCounts
Match type breakdown:
  • simple (number): Verses with exact text matches
  • lemma (number): Verses with lemma matches
  • root (number): Verses with root matches
  • fuzzy (number): Verses with only fuzzy matches
  • total (number): Total matching verses
​
pagination
object
Pagination metadata:
  • totalResults (number): Total matching verses across all pages
  • totalPages (number): Total number of pages
  • currentPage (number): Current page number
  • limit (number): Results per page

​
Scoring system

Match types are weighted differently:
Match typeScore per hit
Exact+3
Lemma+2
Root+1
Fuzzy+0.5

​
Multi-word queries

The search uses AND logic:
  • Query is split by whitespace into tokens
  • Results must match every token (via exact, lemma/root, or fuzzy fallback)
  • Scores accumulate across all matched tokens

​
Examples

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 },
);

response.results.forEach((v) => {
  console.log(v.sura_id, v.aya_id, v.matchType, v.matchScore);
});
// Output:
// 1 1 exact 6
// 1 3 lemma 4

​
With pagination

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

console.log(response.pagination);
// Output:
// {
//   totalResults: 42,
//   totalPages: 5,
//   currentPage: 1,
//   limit: 10
// }

console.log(response.counts);
// Output:
// {
//   simple: 10,
//   lemma: 18,
//   root: 9,
//   fuzzy: 5,
//   total: 42
// }

​
Disable fuzzy matching

const response = search(
  'الله',
  quranData,
  morphologyMap,
  wordMap,
  { lemma: true, root: true, fuzzy: false },
);

// Only returns exact, lemma, and root matches
// No fuzzy fallback for tokens without matches

​
Custom dataset

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

type MyVerse = VerseInput & {
  sura: number;
  aya: number;
  translation_en?: string;
};

const myQuranData: MyVerse[] = [
  {
    gid: 1,
    standard: 'بسم الله الرحمن الرحيم',
    uthmani: 'بِسْمِ ٱللَّهِ ٱلرَّحْمَٰنِ ٱلرَّحِيمِ',
    sura: 1,
    aya: 1,
    translation_en: 'In the name of Allah...',
  },
];

const response = search(
  'الله الرحمن',
  myQuranData,
  new Map(),
  {},
  { lemma: false, root: false },
);

console.log(response.results[0]);
// Output includes custom fields: sura, aya, translation_en

​
Notes

  • The query is automatically normalized (Arabic normalization, tashkeel removal)
  • Non-Arabic characters are stripped from the query
  • Empty queries return an empty result set
  • Results are sorted by matchScore in descending order
  • Use matchedTokens with getHighlightRanges() for UI highlighting

Build docs developers (and LLMs) love

Get started for freeTalk to us