@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. It's based on the King Fahad Quran Printing Complex's Mushaf edition.

## Features

- Navigate through the Quran by number of lines in either upward or downward direction
- Get detailed information about navigation results including overflow conditions
- Access metadata about suras, verses, and pages
- Find verses by sura and verse number
- Calculate distances between verses

## Installation

```bash
npm install mushaf-engine
```

## Usage

```typescript
import { 
  BaseMushafEngine, 
  Direction, 
  KingFahadMushaf 
} from 'mushaf-engine';

// Load the Mushaf data (from a JSON file, API, etc.)
// The data should be an array of pages, where each page is an array of verses
const quranData = await fetch('/path/to/king_fahad_mushaf.json').then(res => res.json());
const mushaf = KingFahadMushaf.load(quranData);

// Create a new Mushaf engine
const engine = new BaseMushafEngine(mushaf);

// Navigate 15 lines from Sura 5, Verse 3 in upward direction
const result = engine.navigate({
  lines: 15,
  fromSura: 5,
  fromVerse: 3,
  direction: Direction.Upwards
});

console.log(result.toString());
// Output includes information about the navigation result:
// - Target verse
// - Distance moved
// - Remaining distance
// - Any overflow, end of page, or end of sura conditions
```

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

## API Reference

### Classes

- **Verse**: Represents a single verse in the Quran with metadata.
- **Page**: Represents a page in the Mushaf with its verses.
- **Mushaf**: Represents the complete Quran Mushaf.
- **QuranMetadata**: Provides metadata about suras in the Quran.
- **VersesNavigator**: Handles low-level navigation between verses.
- **BaseMushafEngine**: Main engine implementing the IMushafEngine interface.

### Navigation

- **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 during navigation.

## License

MIT