MushafEngine

A TypeScript implementation of a Quran Mushaf navigation engine. This library provides functionality for navigating through the Quran by page, verse, and lines with advanced features like cycling navigation, custom bounds, and configurable header handling. It's based on the King Fahad Quran Printing Complex's Mushaf edition.

Features

• Line-based Navigation: Navigate through the Quran by number of lines in either upward or downward direction
• Cycling Navigation: Configure navigation to cycle through bounded ranges with iteration limits
• Custom Bounds: Set upper and lower bounds to restrict navigation to specific verse ranges
• Sura Header Control: Choose whether to include or exclude sura headers from line calculations
• Comprehensive Results: Get detailed information about navigation results including overflow conditions
• Rich Metadata: Access metadata about suras, verses, and pages
• Verse Lookup: Find verses by sura and verse number
• Distance Calculation: Calculate distances between verses in lines

Installation

npm install @sahabaplus/mushaf-engine

Basic Usage

import {
  BaseMushafEngine,
  Direction,
  KingFahadMushaf,
  NavigationSettings,
  VersePosition
} from '@sahabaplus/mushaf-engine';

// Load the included Mushaf data
import kingFahadMushafData from '@sahabaplus/mushaf-engine/data/king_fahad_mushaf.json';

const mushaf = KingFahadMushaf.load(kingFahadMushafData);
const engine = new BaseMushafEngine(mushaf);

// Navigate 15 lines from Sura 5, Verse 3 in upward direction
const result = engine.navigate({
  lines: 15,
  from: new VersePosition(5, 3),
  direction: Direction.Upwards,
  settings: NavigationSettings.builder().build()
});

console.log(result.toString());

Output:

Target verse: Sura 5:5 Position: (1.0, 15) Lines: 5
Distance Moved: 15
Remaining Distance: 0
End of page: Lines distance: 0, Verse: Sura 5:5 Position: (1.0, 15) Lines: 5
End of sura: Lines distance: 300, Verse: Sura 5:120 Position: (1.0, 15) Lines: 1.1

Advanced Features

Navigation Settings

NavigationSettings provides a builder pattern to configure navigation behavior:

import { NavigationSettings, NavigationBounds, VersePosition } from '@sahabaplus/mushaf-engine';

// Create settings with all features
const settings = NavigationSettings.builder()
  .setIgnoreSuraHeader(true)                     // Exclude sura headers from calculations
  .setIterationLimit(3)                           // Allow 3 complete cycles
  .setUpperBound(new VersePosition(2, 1))        // Start of Al-Baqarah
  .setLowerBound(new VersePosition(2, 286))      // End of Al-Baqarah
  .build();

// Use settings in navigation
const result = engine.navigate({
  lines: 100,
  from: new VersePosition(2, 1),
  direction: Direction.Downwards,
  settings
});

Output:

Target verse: Sura 2:58 Position: (0.8, 3) Lines: 2.8
Distance Moved: 98.8
Remaining Distance: 1.2
Overflow: Overflow lines: 0.7, Verse: Sura 2:59 Position: (0.7, 5) Lines: 1.9
End of page: Lines distance: -4, Verse: Sura 2:57 Position: (1.0, 15) Lines: 2.3
End of sura: Lines distance: 612.2, Verse: Sura 2:286 Position: (1.0, 15) Lines: 5.2

Cycling Navigation with Bounds

NavigationBounds controls how navigation behaves when reaching boundaries:

import { NavigationBounds, VersePosition } from '@sahabaplus/mushaf-engine';

// Create bounds for cycling through Juz' Amma (Sura 78-114)
const bounds = new NavigationBounds(
  5,  // Allow 5 complete cycles through the range
  new VersePosition(78, 1),   // Upper bound (start)
  new VersePosition(114, 6)   // Lower bound (end)
);

const settings = NavigationSettings.builder()
  .setBounds(bounds)
  .build();

// Navigation will cycle within this range up to 5 times
const result = engine.navigate({
  lines: 1000,
  from: new VersePosition(78, 1),
  direction: Direction.Downwards,
  settings
});

Output:

Target verse: Sura 107:5 Position: (1.0, 10) Lines: 0.6
Distance Moved: 1000
Remaining Distance: 0
End of page: Lines distance: 5.6, Verse: Sura 108:3 Position: (1.0, 15) Lines: 1
End of sura: Lines distance: 1, Verse: Sura 107:7 Position: (1.0, 11) Lines: 0.5

Key Concepts:

• Iteration Limit: Controls how many complete cycles through the bounded range are allowed
  • 0: No cycling - navigation stops at boundaries
  • n: Allows n complete cycles through the range
• Bounds: upperBound must be less than lowerBound (e.g., (1,1) < (114,6))
• When reaching lowerBound with remaining iterations, navigation cycles back to upperBound

Ignoring Sura Headers

Control whether sura headers (bismillah and sura titles) are included in line calculations:

// Exclude sura headers from calculations
const withoutHeaders = NavigationSettings.builder()
  .setIgnoreSuraHeader(true)
  .build();

// Include sura headers in calculations (default)
const withHeaders = NavigationSettings.builder()
  .setIgnoreSuraHeader(false)
  .build();

// Calculate lines between verses
const linesWithHeaders = engine.calculateLines(
  new VersePosition(2, 1),
  new VersePosition(3, 1),
  Direction.Downwards,
  withHeaders
);

const linesWithoutHeaders = engine.calculateLines(
  new VersePosition(2, 1),
  new VersePosition(3, 1),
  Direction.Downwards,
  withoutHeaders
);

// Difference accounts for sura header lines
console.log(`Lines with headers: ${linesWithHeaders}`);
console.log(`Lines without headers: ${linesWithoutHeaders}`);
console.log(`Difference: ${linesWithHeaders - linesWithoutHeaders} lines`);

Output:

Lines with headers: 715.2
Lines without headers: 711.2
Difference: 4 lines

Note: Sura 9 (At-Tawbah) has no bismillah, only a title (1 line instead of 2).

Calculate Distance Between Verses

Calculate the number of lines between any two verses:

import { VersePosition, Direction } from '@sahabaplus/mushaf-engine';

const lines = engine.calculateLines(
  new VersePosition(2, 255),  // Ayat al-Kursi
  new VersePosition(3, 200),  // End of Al-Imran
  Direction.Downwards,
  NavigationSettings.builder().build()
);

console.log(`Distance: ${lines} lines`);

Output:

Distance: 517.3 lines

Data Format

The Mushaf engine expects data in the following format:

type VerseData = {
  sura: number;    // Sura number (1-114)
  ayah: number;    // Verse number within the sura
  lines: number;   // Number of lines this verse spans (can be fractional)
  y: number;       // Line number on the page (1-15)
  x: number;       // Horizontal position on the line (0.0-1.0)
};

type MushafData = VerseData[][];  // Array of pages, each page is an array of verses

The library includes the King Fahad Mushaf data which you can import directly:

import kingFahadMushafData from '@sahabaplus/mushaf-engine/data/king_fahad_mushaf.json';

API Reference

Core Classes

BaseMushafEngine

Main engine implementing the IMushafEngine interface.

Methods:

• navigate(params): Navigate by lines with comprehensive settings
• calculateLines(from, to, direction, settings): Calculate distance between verses
• getVerse(sura, verse): Find a specific verse
• getPage(pageNumber): Get a page by number

NavigationSettings

Configuration for navigation behavior with builder pattern.

Builder Methods:

• setIgnoreSuraHeader(boolean): Control sura header inclusion
• setBounds(NavigationBounds): Set complete bounds configuration
• setIterationLimit(number): Set cycling iteration limit
• setUpperBound(VersePosition): Set upper navigation bound
• setLowerBound(VersePosition): Set lower navigation bound
• build(): Create the settings instance

NavigationBounds

Defines boundaries and iteration limits for navigation.

Constructor:

new NavigationBounds(
  iterationLimit: number,
  upperBound: VersePosition,
  lowerBound: VersePosition
)

Static Methods:

• default(): Creates default bounds (no cycling, full Quran range)

Supporting Classes

• Verse: Represents a single verse with metadata
• Page: Represents a page in the Mushaf with its verses
• Mushaf: Represents the complete Quran Mushaf
• VersePosition: Identifies a verse by sura and verse number
• QuranMetadata: Provides metadata about suras
• VersesNavigator: Handles low-level navigation between verses

Navigation Types

• Direction: Enum for navigation direction (Upwards or Downwards)
• NavigationResult: Comprehensive result of a navigation operation
• OverflowResult: Information about navigation that exceeds boundaries
• LastVerseResult: Information about boundary verses encountered

Examples

Example 1: Simple Navigation

const result = engine.navigate({
  lines: 10,
  from: new VersePosition(1, 1),
  direction: Direction.Downwards,
  settings: NavigationSettings.builder().build()
});

Output:

Target verse: Sura 1:7 Position: (1.0, 6) Lines: 1.3
Distance Moved: 8
Remaining Distance: 0
Overflow: Overflow lines: 1.5, Verse: Sura 2:1 Position: (0.5, 2) Lines: 1.5
End of page: Lines distance: 1.3, Verse: Sura 1:7 Position: (1.0, 6) Lines: 1.3
End of sura: Lines distance: -2, Verse: Sura 1:7 Position: (1.0, 6) Lines: 1.3

Example 2: Cycling Through a Range

const settings = NavigationSettings.builder()
  .setIterationLimit(2)
  .setUpperBound(new VersePosition(67, 1))  // Sura Al-Mulk
  .setLowerBound(new VersePosition(67, 30))
  .build();

const result = engine.navigate({
  lines: 500,  // Will cycle through the range twice
  from: new VersePosition(67, 1),
  direction: Direction.Downwards,
  settings
});

Output:

Target verse: Sura 67:30 Position: (1.0, 5) Lines: 1
Distance Moved: 105
Remaining Distance: 0
End of page: Lines distance: 11, Verse: Sura 68:16 Position: (1.0, 15) Lines: 0.4
End of sura: Lines distance: -395, Verse: Sura 67:30 Position: (1.0, 5) Lines: 1

Example 3: Navigation Without Sura Headers

const settings = NavigationSettings.builder()
  .setIgnoreSuraHeader(true)
  .build();

const result = engine.navigate({
  lines: 20,
  from: new VersePosition(2, 1),
  direction: Direction.Downwards,
  settings
});

Output:

Target verse: Sura 2:15 Position: (0.5, 14) Lines: 0.9
Distance Moved: 19.5
Remaining Distance: 0.5
Overflow: Overflow lines: 1, Verse: Sura 2:16 Position: (1.0, 15) Lines: 1.5
End of page: Lines distance: 1, Verse: Sura 2:16 Position: (1.0, 15) Lines: 1.5
End of sura: Lines distance: 691.5, Verse: Sura 2:286 Position: (1.0, 15) Lines: 5.2

Testing

All examples in this README are tested in tests/readme-examples.test.ts to ensure accuracy and prevent outdated documentation. Run the tests with:

bun test readme-examples.test.ts

License

MIT License

Copyright (c) 2025

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.