@sahabaplus/mushaf-engine/README.md

TypeScript implementation of a Quran Mushaf navigation engine

# 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

```bash
npm install @sahabaplus/mushaf-engine
```

## Basic Usage

```typescript
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:

```typescript
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:

```typescript
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:

```typescript
// 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:

```typescript
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:

```typescript
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:

```typescript
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:**

```typescript
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

```typescript
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

```typescript
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

```typescript
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:

```bash
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.