✨ Features

| | Feature | Details | |---|---|---| | 📚 | Complete Collection | All 3,956 authentic hadiths from Jami al-Tirmidhi | | 🌐 | Bilingual | Full Arabic text + English translation | | ⚡ | Offline-first | Data bundled — no CDN needed | | 🔧 | Zero Dependencies | Nothing extra to install | | 🔍 | Full-text Search | Search English text and narrator names instantly | | 🖥️ | CLI | Terminal access with Arabic/English/both flags | | ⚛️ | React Hook | One command generates useTirmidhi() | | 🐍 | Python | Identical API — same camelCase method names | | 📘 | TypeScript | Full type definitions included |

🚀 Installation

npm install jami-al-tirmidhi       # JS local
npm install -g jami-al-tirmidhi    # JS global CLI
pip install jami-al-tirmidhi       # Python

🟨 JavaScript / Node.js

const tirmidhi = require('jami-al-tirmidhi');  // CJS
import tirmidhi from 'jami-al-tirmidhi';       // ESM

tirmidhi.get(1)
tirmidhi.getByChapter(1)
tirmidhi.search('prayer')
tirmidhi.search('prayer', 5)
tirmidhi.getRandom()
tirmidhi[0]
tirmidhi.length
tirmidhi.metadata
tirmidhi.chapters
tirmidhi.find(h => h.id === 23)
tirmidhi.filter(h => h.chapterId === 1)
tirmidhi.slice(0, 10)

⚛️ React

cd my-react-app
tirmidhi --react    # generates src/hooks/useTirmidhi.js

import { useTirmidhi } from '../hooks/useTirmidhi';

function HadithOfTheDay() {
  const tirmidhi = useTirmidhi();
  if (!tirmidhi) return <p>Loading...</p>;
  const h = tirmidhi.getRandom();
  return <div><strong>{h.english.narrator}</strong><p>{h.english.text}</p></div>;
}

🐍 Python

from jami_al_tirmidhi import Tirmidhi

tirmidhi = Tirmidhi()

tirmidhi.get(1)
tirmidhi.getByChapter(1)
tirmidhi.search("prayer")
tirmidhi.search("prayer", limit=5)
tirmidhi.getRandom()
tirmidhi[0]
tirmidhi.length
tirmidhi.find(lambda h: h.id == 23)
tirmidhi.filter(lambda h: h.chapterId == 1)
tirmidhi.slice(0, 10)

# Custom path
tirmidhi = Tirmidhi(data_path="/path/to/tirmidhi.json")

🖥️ CLI

tirmidhi 1
tirmidhi 2345 -a           # Arabic only
tirmidhi 2345 -b           # Arabic + English
tirmidhi 23 34             # Hadith 34 within chapter 23
tirmidhi --search "prayer"
tirmidhi --search "fasting" --all
tirmidhi --chapter 1
tirmidhi --random
tirmidhi --react
tirmidhi --version

📂 Structure

jami-al-tirmidhi/
├── data/
│   ├── tirmidhi.json          ← source of truth (replace with your real data)
│   ├── tirmidhi.json.gz       ← generated (shipped in packages)
│   └── chapters/              ← generated (gitignored)
├── bin/index.js               ← CLI
├── src/                       ← JS source
├── types/index.d.ts
├── python/jami_al_tirmidhi/   ← Python package
├── scripts/build.mjs
├── examples/
├── docs/
└── tests/

🔧 Development

# Place your real tirmidhi.json in data/
node scripts/build.mjs    # compress, generate chapters/, copy to python/

# Test locally before publishing
python -m build --wheel
python -m zipfile -l dist\jami_al_tirmidhi-1.0.0-py3-none-any.whl | findstr "tirmidhi.json.gz"
pip install dist\jami_al_tirmidhi-1.0.0-py3-none-any.whl --force-reinstall
tirmidhi 23

Publishing is automatic via GitHub Actions on every GitHub Release.

📄 License

GNU Affero General Public License v3.0 (AGPL-3.0)

Made with ❤️ for the Muslim community · Seeking knowledge together