hadith-collections

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

npm install hadith-collections

Requirements

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

Quick Start

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

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

Collection Methods

getCollections(): Collection[]

Returns all hadith collections.

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

getCollection(collectionId): Collection | null

Get a specific collection by ID.

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.

// 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.

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.

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.

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.

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.

// 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.

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).

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.

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

Search Methods

searchArabic(query, options?): Hadith[]

Search hadiths in Arabic.

// 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.

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

search(query, options?): SearchResults

Search in both Arabic and English.

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.

// 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.

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.

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

close(): void

Close the database connection.

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

Examples

Search Example

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

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

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:

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.