TypeScript types

Overview

All types are exported from quran-search-engine and provide full TypeScript support for search operations, highlighting, and data structures.

import type {
  QuranText,
  ScoredQuranText,
  SearchResponse,
  SearchOptions,
  SearchCounts,
  MorphologyAya,
  WordMap,
  MatchType,
  HighlightRange,
  PaginationOptions,
} from 'quran-search-engine';

Core types

QuranText

Represents a single verse in the Quran dataset. This is the input type for search operations.

export type QuranText = {
  sura_id: number;
  aya_id_display: string;
  uthmani: string;
  gid: number;
  aya_id: number;
  page_id: number;
  juz_id: number;
  standard: string;
  standard_full: string;
  sura_name: string;
  sura_name_en: string;
  sura_name_romanization: string;
};

gid

number

Unique global verse identifier (1-6236)

sura_id

number

Chapter number (1-114)

aya_id

number

Verse number within the chapter

aya_id_display

string

Formatted verse identifier for display (e.g., “1:1”)

uthmani

string

Verse text in Uthmani script with diacritics (commonly used for display and highlighting)

standard

string

Verse text in standard Arabic script (used for exact text matching)

standard_full

string

Full verse text including Bismillah where applicable

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

ScoredQuranText

Extends QuranText with search scoring and highlighting metadata. This is the type returned in search results.

export type ScoredQuranText = QuranText & {
  matchScore: number;
  matchType: MatchType;
  matchedTokens: string[];
  tokenTypes?: Record<string, MatchType>;
};

matchScore

number

Total score for this verse based on match quality:

Exact matches: +3 per token
Lemma matches: +2 per token
Root matches: +1 per token
Fuzzy matches: +0.5 per token

matchType

MatchType

The best overall match type for this verse: 'exact', 'lemma', 'root', 'fuzzy', or 'none'

matchedTokens

string[]

Deduplicated array of query tokens that matched in this verse (used for highlighting)

tokenTypes

Record<string, MatchType>

Optional mapping of each matched token to its match type (used for match-type-specific highlighting)

SearchResponse

The complete response object returned by the search() function.

export type SearchResponse = {
  results: ScoredQuranText[];
  counts: SearchCounts;
  pagination: {
    totalResults: number;
    totalPages: number;
    currentPage: number;
    limit: number;
  };
};

results

ScoredQuranText[]

Array of matching verses, sorted by match score (highest first)

counts

SearchCounts

Match statistics by type

simple

number

Number of exact text matches

lemma

number

Number of lemma matches

root

number

Number of root matches

fuzzy

number

Number of fuzzy matches

total

number

Total number of matches across all types

pagination

object

Pagination metadata

totalResults

number

Total number of matching verses

totalPages

number

Total number of pages based on limit

currentPage

number

Current page number (1-based)

limit

number

Number of results per page

SearchOptions

Configuration options for search behavior.

export type SearchOptions = {
  lemma: boolean;
  root: boolean;
  fuzzy?: boolean;
};

lemma

boolean

required

Enable lemma-based matching (requires morphology data and word map)

root

boolean

required

Enable root-based matching (requires morphology data and word map)

fuzzy

boolean

Enable fuzzy fallback matching. Defaults to true. Set to false to disable fuzzy search entirely.

SearchCounts

Match statistics returned by the search function, providing breakdown of results by match type.

export type SearchCounts = {
  simple: number;
  lemma: number;
  root: number;
  fuzzy: number;
  total: number;
};

simple

number

Number of verses with exact text matches

lemma

number

Number of verses with lemma-based matches

root

number

Number of verses with root-based matches

fuzzy

number

Number of verses with only fuzzy matches

total

number

Total number of matching verses across all types

Morphology types

MorphologyAya

Morphological data for a single verse, containing lemmas and roots for linguistic matching.

export type MorphologyAya = {
  gid: number;
  lemmas: string[];
  roots: string[];
};

gid

number

Global verse identifier matching QuranText.gid

lemmas

string[]

Array of normalized lemma forms for all words in the verse

roots

string[]

Array of Arabic roots for all words in the verse

WordMap

Dictionary mapping normalized query tokens to their canonical lemma and root forms.

export type WordMap = {
  [key: string]: {
    lemma?: string;
    root?: string;
  };
};

[key: string]

object

Normalized token as key

lemma

string

Canonical lemma form of the token

root

string

Arabic root of the token

Example:

const wordMap: WordMap = await loadWordMap();
// wordMap['الله'] => { lemma: 'الله', root: 'ا ل ه' }

Match types

MatchType

Enumeration of possible match types for search results.

export type MatchType = 'exact' | 'lemma' | 'root' | 'fuzzy' | 'none';

'exact'

literal

Direct text match in the verse (highest priority, score: +3)

'lemma'

literal

Lemma-based match using morphological analysis (score: +2)

'root'

literal

Root-based match using Arabic roots (score: +1)

'fuzzy'

literal

Fuzzy match fallback when no exact/lemma/root match found (score: +0.5)

'none'

literal

No match (used internally)

HighlightRange

Represents a character range to highlight in the text, returned by getHighlightRanges().

export type HighlightRange = {
  start: number;
  end: number;
  token: string;
  matchType: MatchType;
};

start

number

Starting character index (0-based, inclusive)

end

number

Ending character index (0-based, exclusive)

token

string

The original query token that matched this range

matchType

MatchType

The type of match for this range

Pagination types

PaginationOptions

Options for paginating search results.

export type PaginationOptions = {
  page?: number;
  limit?: number;
};

page

number

Page number to retrieve (1-based). Defaults to 1.

limit

number

Number of results per page. Defaults to 10.

Example:

const response = search(
  'الله الرحمن',
  quranData,
  morphologyMap,
  wordMap,
  { lemma: true, root: true },
  { page: 2, limit: 20 } // Get page 2 with 20 results per page
);

Custom dataset types

VerseInput

Minimal interface required for custom verse datasets.

export type VerseInput = {
  gid: number;
  uthmani: string;
  standard: string;
};

gid

number

required

Unique verse identifier (used to join with morphology data)

uthmani

string

required

Verse text with diacritics (used for fuzzy fallback and highlighting)

standard

string

required

Verse text in standard form (used for exact text matching)

Custom dataset example:

import { search, type VerseInput, type WordMap, type MorphologyAya } 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, the Entirely Merciful, the Especially Merciful.',
  },
];

const morphologyMap = new Map<number, MorphologyAya>();
const wordMap: WordMap = {};

const response = search('الله الرحمن', myQuranData, morphologyMap, wordMap, {
  lemma: false,
  root: false,
});
// response.results[0] => { gid: 1, sura: 1, aya: 1, matchType: 'exact', matchScore: 6, ... }

Search

Data Loaders

Normalization

Highlighting

Types

Overview

Core types

QuranText

ScoredQuranText

SearchResponse

SearchOptions

SearchCounts

Morphology types

MorphologyAya

WordMap

Match types

MatchType

HighlightRange

PaginationOptions

Custom dataset types

VerseInput

Build docs developers (and LLMs) love

Search

Data Loaders

Normalization

Highlighting

Types

Documentation Index

​Overview

​Core types

​QuranText

​ScoredQuranText

​SearchResponse

​SearchOptions

​SearchCounts

​Morphology types

​MorphologyAya

​WordMap

​Match types

​MatchType

​HighlightRange

​Pagination types

​PaginationOptions

​Custom dataset types

​VerseInput

Build docs developers (and LLMs) love

Overview

Core types

QuranText

ScoredQuranText

SearchResponse

SearchOptions

SearchCounts

Morphology types

MorphologyAya

WordMap

Match types

MatchType

HighlightRange

Pagination types

PaginationOptions

Custom dataset types

VerseInput