@sahabaplus/mushaf-engine/dist/mushafEngine/baseMushafEngine.d.ts

TypeScript implementation of a Quran Mushaf navigation engine

import { Mushaf, QuranMetadata, SuraInfo, Verse } from "../mushaf";
import { Direction, NavigationResult, NavigationSettings, VersePosition } from "../navigation";
import { IMushafEngine, NavigateParams } from "./iMushafEngine";
import { VerseLocation } from "./verseLocation";
/**
 * Basic implementation of the Mushaf navigation engine
 */
export declare class BaseMushafEngine implements IMushafEngine {
    mushaf: Mushaf;
    quranMetadata: QuranMetadata;
    /**
     * Create a new BaseMushafEngine with the given Mushaf
     *
     * @param mushaf - The Mushaf to navigate through
     */
    constructor(mushaf: Mushaf);
    /**
     * Create a navigator with the given settings and direction
     */
    private createNavigator;
    /**
     * Get metadata about a specific Sura
     *
     * @param suraNumber - Sura number (1-114)
     * @returns Information about the specified Sura, or undefined if not found
     */
    getSuraInfo(suraNumber: number): SuraInfo | undefined;
    /**
     * Find the next verse from a given verse in the specified direction
     *
     * @param from - Verse position to start from
     * @param direction - Direction to navigate
     * @param settings - Navigation settings
     * @returns The next verse or undefined if at the end
     */
    nextVerse(from: VersePosition, direction: Direction, settings: NavigationSettings): Verse | undefined;
    /**
     * Find the previous verse from a given verse in the specified direction
     *
     * @param from - Verse position to start from
     * @param direction - Direction to navigate
     * @param settings - Navigation settings
     * @returns The previous verse or undefined if at the start
     */
    previousVerse(from: VersePosition, direction: Direction, settings: NavigationSettings): Verse | undefined;
    /**
     * Check if a verse position is out of the current navigation bounds
     */
    isOutOfBounds(verse: VersePosition, direction: Direction, settings: NavigationSettings): boolean;
    /**
     * Get the effective start of the navigation range for the given direction and settings
     */
    getStartBound(direction: Direction, settings: NavigationSettings): VersePosition;
    /**
     * Get the effective end of the navigation range for the given direction and settings
     */
    getEndBound(direction: Direction, settings: NavigationSettings): VersePosition;
    /**
     * Check if navigation direction is wrong for given start and end positions.
     *
     * This is a thin wrapper around `VersesNavigator.isWrongDirection` so that
     * consumers of the engine can reuse the same ordering rules.
     */
    isWrongDirection(start: VersePosition | {
        sura: number;
        verse: number;
    }, end: VersePosition | {
        sura: number;
        verse: number;
    }, direction: Direction): boolean;
    /**
     * Find a verse in the mushaf and return its location (Verse, page, index_of_verse)
     *
     * @param verse - Verse position to find
     * @returns The verse and its location, or undefined if not found
     */
    findVerseLocation(verse: VersePosition): VerseLocation | undefined;
    /**
     * Resolve a (sura, verse) position to the full Verse object in the mushaf
     */
    findVerse(position: VersePosition): Verse | undefined;
    /**
     * Resolve a (sura, verse) pair directly to a Verse object.
     */
    resolvePosition(sura: number, verse: number): Verse | undefined;
    /**
     * Calculate the direct distance in lines between start and end verses
     *
     * This calculates the simple A→B distance without accounting for cycles.
     * When bounded navigation produces cycles, callers can use the `cycleDistance`
     * field from `NavigationResult` to compute total distance:
     *
     * ```text
     * total_distance ≈ (cycles_completed - 1) * cycle_distance + direct_distance
     * ```
     *
     * where `direct_distance` is obtained from this method.
     *
     * @param start - Start verse position
     * @param end - End verse position
     * @param direction - Direction of navigation
     * @param settings - Navigation settings
     * @returns Direct distance in lines between the two verses
     * @throws Error if the verses are unreachable or not found
     */
    calculateLines(start: VersePosition, end: VersePosition, direction: Direction, settings: NavigationSettings): number;
    /**
     * Calculate the lines taken by a verse including any sura headers, using the
     * same rules as the internal navigator.
     */
    calculateVerseLines(verse: Verse, settings: NavigationSettings): number;
    /**
     * Determine which last of sura result to prefer
     *
     * @param lastOfSura - Existing last of sura result, if any
     * @param currentVerse - Current verse being processed
     * @param direction - Direction of navigation
     * @returns The preferred last of sura result
     */
    private preferLastOfSura;
    /**
     * Determine which last of page result to prefer
     *
     * @param lastOfPage - Existing last of page result, if any
     * @param currentVerse - Current verse being processed
     * @param direction - Direction of navigation
     * @returns The preferred last of page result
     */
    private preferLastOfPage;
    /**
     * Navigate from a verse by a specified number of lines in the given direction
     *
     * @param params - Navigation parameters
     * @returns Navigation result containing the verse at the destination after navigation
     */
    navigate(params: NavigateParams): NavigationResult;
}