hadith-collections/README.md

A comprehensive npm package for searching and browsing hadith collections with Arabic and English support

# Hadith Collections

A comprehensive npm package for searching and browsing hadith collections with Arabic and English support. This package provides easy access to authentic hadith collections including Sahih al-Bukhari, Sahih Muslim, Sunan an-Nasa'i, and more.

## Features

- 🔍 **Search**: Full-text search in both Arabic and English
- 📚 **Browse**: Navigate through collections, books, and chapters
- 🎯 **Retrieve**: Get specific hadiths by URN or browse by collection
- 🌐 **Multilingual**: Support for Arabic (with and without diacritics) and English
- 📊 **Statistics**: Get collection statistics and metadata
- 🎲 **Random**: Get random hadiths for daily reading
- 💾 **Local**: Works offline with SQLite database
- 🔧 **TypeScript**: Full TypeScript support with type definitions

## Installation

```bash
npm install hadith-collections
```

## Requirements

- Node.js >= 14.0.0
- The package includes the hadith database (`data/hadith.db`)

## Quick Start

```javascript
const HadithDB = require('hadith-collections');

// Initialize the database
const hadithDb = new HadithDB();

// Get all collections
const collections = hadithDb.getCollections();
console.log('Available collections:', collections.length);

// Search for hadiths
const searchResults = hadithDb.search('prayer');
console.log(`Found ${searchResults.total} hadiths about prayer`);

// Get a random hadith
const randomHadith = hadithDb.getRandomHadith();
console.log('Random hadith:', randomHadith.content);

// Don't forget to close the connection
hadithDb.close();
```

## API Documentation

### Constructor

#### `new HadithDB(dbPath?)`

Creates a new HadithDB instance.

- `dbPath` (optional): Path to the SQLite database file. Defaults to `./data/hadith.db`

```javascript
const hadithDb = new HadithDB();
// or with custom path
const hadithDb = new HadithDB('/path/to/hadith.db');
```

### Collection Methods

#### `getCollections(): Collection[]`

Returns all hadith collections.

```javascript
const collections = hadithDb.getCollections();
collections.forEach(collection => {
  console.log(`${collection.title_en} (${collection.title})`);
});
```

#### `getCollection(collectionId): Collection | null`

Get a specific collection by ID.

```javascript
const bukhari = hadithDb.getCollection(1); // Sahih al-Bukhari
console.log(bukhari.title_en); // "Sahih al-Bukhari"
```

#### `getCollectionStats(collectionId?): CollectionStats`

Get statistics for a collection or overall database.

```javascript
// Overall stats
const stats = hadithDb.getCollectionStats();
console.log(`Total collections: ${stats.collection_count}`);

// Collection-specific stats
const bukhariStats = hadithDb.getCollectionStats(1);
console.log(`Books in Bukhari: ${bukhariStats.book_count}`);
```

### Book Methods

#### `getBooks(collectionId): Book[]`

Get all books in a collection.

```javascript
const books = hadithDb.getBooks(1); // Books in Sahih al-Bukhari
books.forEach(book => {
  console.log(`${book.title_en} (${book.hadith_count} hadiths)`);
});
```

#### `getBook(collectionId, bookId): Book | null`

Get a specific book.

```javascript
const book = hadithDb.getBook(1, 1); // First book of Bukhari
console.log(book.title_en); // "Revelation"
```

### Chapter Methods

#### `getChapters(collectionId, bookId): Chapter[]`

Get all chapters in a book.

```javascript
const chapters = hadithDb.getChapters(1, 1); // Chapters in first book
chapters.forEach(chapter => {
  console.log(chapter.title_en);
});
```

#### `getChapter(collectionId, bookId, chapterId): Chapter | null`

Get a specific chapter.

```javascript
const chapter = hadithDb.getChapter(1, 1, 1);
console.log(chapter.title_en);
```

### Hadith Retrieval Methods

#### `getHadithsByCollection(collectionId, options?): Hadith[]`

Get hadiths from a collection with optional filtering.

```javascript
// Get first 10 hadiths from Bukhari
const hadiths = hadithDb.getHadithsByCollection(1, { limit: 10 });

// Get hadiths from specific book
const bookHadiths = hadithDb.getHadithsByCollection(1, { 
  bookId: 1, 
  limit: 5 
});

// Get hadiths from specific chapter
const chapterHadiths = hadithDb.getHadithsByCollection(1, {
  bookId: 1,
  chapterId: 1,
  limit: 3
});
```

#### `getEnglishHadithsByCollection(collectionId, options?): EnglishHadith[]`

Get English translations of hadiths.

```javascript
const englishHadiths = hadithDb.getEnglishHadithsByCollection(1, { limit: 10 });
englishHadiths.forEach(hadith => {
  console.log(hadith.content);
});
```

#### `getHadithByUrn(urn): Hadith | null`

Get a specific hadith by its URN (Uniform Resource Name).

```javascript
const hadith = hadithDb.getHadithByUrn('bukhari:1:1:1');
if (hadith) {
  console.log(hadith.content);
}
```

#### `getEnglishHadithByUrn(urn): EnglishHadith | null`

Get English translation of a hadith by URN.

```javascript
const englishHadith = hadithDb.getEnglishHadithByUrn('bukhari:1:1:1');
if (englishHadith) {
  console.log(englishHadith.content);
}
```

### Search Methods

#### `searchArabic(query, options?): Hadith[]`

Search hadiths in Arabic.

```javascript
// Basic search
const results = hadithDb.searchArabic('الصلاة');

// Search with options
const results = hadithDb.searchArabic('الصلاة', {
  collectionId: 1, // Only in Bukhari
  limit: 20,
  searchInDiacless: true // Search without diacritics
});
```

#### `searchEnglish(query, options?): EnglishHadith[]`

Search hadiths in English.

```javascript
const results = hadithDb.searchEnglish('prayer', {
  collectionId: 1,
  limit: 10
});
```

#### `search(query, options?): SearchResults`

Search in both Arabic and English.

```javascript
const results = hadithDb.search('prayer');
console.log(`Arabic results: ${results.arabic.length}`);
console.log(`English results: ${results.english.length}`);
console.log(`Total: ${results.total}`);
```

### Utility Methods

#### `getRandomHadith(collectionId?): Hadith | null`

Get a random hadith.

```javascript
// Random hadith from any collection
const randomHadith = hadithDb.getRandomHadith();

// Random hadith from specific collection
const randomBukhari = hadithDb.getRandomHadith(1);
```

#### `getScholars(): Scholar[]`

Get information about hadith scholars.

```javascript
const scholars = hadithDb.getScholars();
scholars.forEach(scholar => {
  console.log(`${scholar.famous_name} (${scholar.born_on} - ${scholar.died_on})`);
});
```

#### `getInfo(): DatabaseInfo`

Get database information and statistics.

```javascript
const info = hadithDb.getInfo();
console.log(`Database version: ${info.version}`);
console.log(`Available collections: ${info.collections.length}`);
```

#### `close(): void`

Close the database connection.

```javascript
hadithDb.close(); // Always close when done
```

## Examples

### Search Example

```javascript
const HadithDB = require('hadith-collections');
const hadithDb = new HadithDB();

// Search for hadiths about charity
const results = hadithDb.search('charity');

console.log(`Found ${results.total} hadiths about charity:`);
console.log(`- ${results.arabic.length} in Arabic`);
console.log(`- ${results.english.length} in English`);

// Display first English result
if (results.english.length > 0) {
  const hadith = results.english[0];
  console.log(`\nHadith: ${hadith.content}`);
  console.log(`Reference: ${hadith.reference}`);
}

hadithDb.close();
```

### Browse Collections Example

```javascript
const HadithDB = require('hadith-collections');
const hadithDb = new HadithDB();

// Get all collections
const collections = hadithDb.getCollections();

collections.forEach(collection => {
  console.log(`\n${collection.title_en} (${collection.title})`);
  console.log(`Status: ${collection.status}`);
  
  // Get books in this collection
  const books = hadithDb.getBooks(collection.id);
  console.log(`Books: ${books.length}`);
  
  // Get first few hadiths
  const hadiths = hadithDb.getHadithsByCollection(collection.id, { limit: 3 });
  console.log(`Sample hadiths: ${hadiths.length}`);
});

hadithDb.close();
```

### Daily Hadith Example

```javascript
const HadithDB = require('hadith-collections');
const hadithDb = new HadithDB();

function getDailyHadith() {
  const hadith = hadithDb.getRandomHadith();
  const englishHadith = hadithDb.getEnglishHadithByUrn(hadith.urn);
  
  return {
    arabic: hadith.content,
    english: englishHadith ? englishHadith.content : null,
    reference: hadith.urn,
    narrator: hadith.narrator_prefix
  };
}

const daily = getDailyHadith();
console.log('Today\'s Hadith:');
console.log(`Arabic: ${daily.arabic}`);
if (daily.english) {
  console.log(`English: ${daily.english}`);
}
console.log(`Reference: ${daily.reference}`);

hadithDb.close();
```

## TypeScript Support

The package includes full TypeScript definitions:

```typescript
import HadithDB, { Collection, Hadith, SearchResults } from 'hadith-collections';

const hadithDb = new HadithDB();

const collections: Collection[] = hadithDb.getCollections();
const results: SearchResults = hadithDb.search('prayer');
const hadith: Hadith | null = hadithDb.getRandomHadith();

hadithDb.close();
```

## Available Collections

The database includes several major hadith collections:

- **Sahih al-Bukhari** - The most authentic collection
- **Sahih Muslim** - Second most authentic collection  
- **Sunan an-Nasa'i** - One of the six canonical collections
- And more...

Use `getCollections()` to see all available collections in your database.

## Performance Notes

- The package uses SQLite with WAL mode for better performance
- Search operations use SQL LIKE queries for compatibility
- For better search performance with the full FTS capabilities, ensure your SQLite installation supports the Arabic tokenizer
- Always call `close()` when done to free resources

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

MIT License - see LICENSE file for details.

## Support

For questions and support, please open an issue on GitHub.