@sahabaplus/mushaf-engine/dist/navigation/navigationResult.d.ts

TypeScript implementation of a Quran Mushaf navigation engine

import { Verse } from '../mushaf/verse';
import { LastVerseResult } from './lastVerseResult';
import { OverflowResult } from './overflowResult';
/**
 * Information about navigation cycles and boundary crossings
 *
 * This class tracks how many times navigation passed through the starting verse
 * and provides information about cycle distances for bounded navigation.
 */
export declare class CycleInfo {
    /**
     * Number of times navigation passed through the starting verse again
     *
     * This counts how many times the navigator returned to the initial starting verse
     * during navigation. For example, if navigating from (10,1) by 10000 lines ends at
     * (10,100), a `cyclesCompleted` of 2 means we passed through (10,1) twice during
     * navigation, explaining why the large distance resulted in a nearby verse.
     */
    readonly cyclesCompleted: number;
    /**
     * Whether the navigation crossed boundaries (passed starting point or wrapped mushaf)
     *
     * This is true when:
     * - Navigation passed through the starting verse at least once (`cyclesCompleted > 0`)
     * - Mushaf wrapping occurred (sura 1 → 114 upward, or 114 → 1 downward)
     *
     * This helps callers understand non-linear navigation paths where the end position
     * may appear confusing relative to the start position.
     */
    readonly crossedBoundaries: boolean;
    /**
     * The distance (in lines) of one full cycle through the bounded region
     *
     * This is the number of lines required to navigate from the starting verse back to itself
     * when bounded navigation is enabled. For example, if navigating (2,1) → (2,50) → (2,1)
     * in a bounded region takes 150 lines, `cycleDistance` would be 150.0.
     *
     * This field is 0.0 when:
     * - No cycles were completed (`cyclesCompleted == 0`)
     * - No bounds are configured (unbounded navigation)
     *
     * This enables callers to compute total distance using the formula:
     * ```text
     * total_distance = (cycles_completed - 1) * cycle_distance + direct_distance
     * ```
     *
     * where `direct_distance` can be calculated using `calculate_lines(start, end, direction, settings)`.
     */
    readonly cycleDistance: number;
    /**
     * Create a new CycleInfo with the specified cycle tracking data
     *
     * @param cyclesCompleted - Number of cycles through the starting verse
     * @param crossedBoundaries - Whether navigation wrapped around boundaries
     * @param cycleDistance - Distance in lines for one full cycle
     */
    constructor(cyclesCompleted?: number, crossedBoundaries?: boolean, cycleDistance?: number);
    /**
     * Create a new CycleInfo with no cycles
     *
     * @returns A CycleInfo instance with all fields set to default values
     */
    static none(): CycleInfo;
    /**
     * Reconstruct total navigated distance from direct distance
     *
     * This helper method implements the formula:
     * ```text
     * total_distance = (cycles_completed - 1) * cycle_distance + direct_distance
     * ```
     *
     * This formula works because:
     * - `cyclesCompleted` counts passes through the start verse
     * - Each pass adds one `cycleDistance` worth of lines
     * - The current (partial or complete) cycle contributes `directDistance`
     * - So we have (N-1) complete previous cycles + current cycle
     *
     * @param directDistance - The direct distance from start to end (from calculateLines)
     * @returns The total distance including cycles
     *
     * @example
     * ```typescript
     * // If we completed 3 cycles with cycleDistance=100 and directDistance=25
     * const cycleInfo = new CycleInfo(3, true, 100.0);
     * const total = cycleInfo.reconstructDistance(25.0);
     * // total = (3-1)*100 + 25 = 225.0
     * ```
     */
    reconstructDistance(directDistance: number): number;
}
/**
 * Comprehensive result of a navigation operation in the Quran
 *
 * This class contains the primary verse reached through navigation,
 * as well as optional information about any overflow conditions or boundary
 * verses (last verse of page or sura) encountered during navigation.
 */
export declare class NavigationResult {
    /**
     * The verse reached through navigation
     */
    verse: Verse;
    /**
     * Optional information about overflow if navigation exceeded boundaries
     */
    overflow?: OverflowResult;
    /**
     * Optional information about the last verse of the page if encountered during navigation
     */
    endOfPage?: LastVerseResult;
    /**
     * Optional information about the last verse of the sura if encountered during navigation
     */
    endOfSura?: LastVerseResult;
    /**
     * The actual distance moved during navigation in lines
     */
    distanceMoved: number;
    /**
     * The remaining distance that could not be navigated due to boundaries
     */
    remainingDistance: number;
    /**
     * Information about navigation cycles and boundary crossings
     */
    cycleInfo: CycleInfo;
    /**
     * Create a new NavigationResult with all possible parameters
     *
     * @param verse - The verse reached through navigation
     * @param overflow - Optional information about overflow if navigation exceeded boundaries
     * @param endOfPage - Optional information about the last verse of the page if encountered
     * @param endOfSura - Optional information about the last verse of the sura if encountered
     * @param distanceMoved - The actual distance moved during navigation in lines
     * @param cycleInfo - Information about navigation cycles and boundary crossings
     */
    constructor(verse: Verse, overflow?: OverflowResult, endOfPage?: LastVerseResult, endOfSura?: LastVerseResult, distanceMoved?: number, cycleInfo?: CycleInfo);
    /**
     * Create a new NavigationResult for a normal navigation with no boundary conditions
     *
     * @param verse - The verse reached through navigation
     * @param distanceMoved - The actual distance moved during navigation in lines
     * @param cycleInfo - Optional cycle information
     * @returns A new NavigationResult instance with only the target verse and no boundary information
     */
    static newNormal(verse: Verse, distanceMoved: number, cycleInfo?: CycleInfo): NavigationResult;
    /**
     * Create a new NavigationResult for a navigation that includes overflow
     *
     * @param verse - The verse reached through navigation
     * @param overflow - Information about overflow during navigation
     * @param distanceMoved - The actual distance moved during navigation in lines
     * @param cycleInfo - Optional cycle information
     * @returns A new NavigationResult instance with the target verse and overflow information
     */
    static newOverflowed(verse: Verse, overflow: OverflowResult, distanceMoved: number, cycleInfo?: CycleInfo): NavigationResult;
    /**
     * Create a new NavigationResult that reached the last verse of a page
     *
     * @param verse - The verse reached through navigation
     * @param lastOfPage - Information about the last verse of the page
     * @param distanceMoved - The actual distance moved during navigation in lines
     * @param cycleInfo - Optional cycle information
     * @returns A new NavigationResult instance with the target verse and last-of-page information
     */
    static newPageBoundary(verse: Verse, lastOfPage: LastVerseResult, distanceMoved: number, cycleInfo?: CycleInfo): NavigationResult;
    /**
     * Create a new NavigationResult that reached the last verse of a sura
     *
     * @param verse - The verse reached through navigation
     * @param lastOfSura - Information about the last verse of the sura
     * @param distanceMoved - The actual distance moved during navigation in lines
     * @param cycleInfo - Optional cycle information
     * @returns A new NavigationResult instance with the target verse and last-of-sura information
     */
    static newSuraBoundary(verse: Verse, lastOfSura: LastVerseResult, distanceMoved: number, cycleInfo?: CycleInfo): NavigationResult;
    /**
     * Check if this navigation result encountered any boundaries
     *
     * @returns true if the navigation hit the last verse of page, sura, or had an overflow
     */
    hasBoundaries(): boolean;
    /**
     * Check if this navigation result encountered an overflow condition
     *
     * @returns true if the navigation exceeded available boundaries
     */
    hasOverflow(): boolean;
    /**
     * Get the total overflow lines if any exist
     *
     * @returns The number of overflow lines, or 0.0 if no overflow occurred
     */
    overflowLines(): number;
    /**
     * Create a string representation of the navigation result
     */
    toString(): string;
}