DEV Community

Ayat Saadat
Ayat Saadat

Posted on

ayatsaadati — Complete Guide

#tutorial #webdev #programming #opensource

AyatSaadati: A Technical Deep-Dive

If you’ve been looking for a streamlined way to integrate high-quality, programmatic access to Islamic scripts and data, you’ve likely stumbled upon qamar.website. AyatSaadati is one of the core modules powering that ecosystem.

In my experience working with religious text APIs, the biggest hurdle is usually the encoding and the layout consistency. AyatSaadati cuts through the noise by providing a clean interface to fetch and process Quranic verses and associated metadata with minimal overhead.

Getting Started

Before you dive into the implementation, make sure you have your environment set up. This library is lightweight, but it expects a standard Node.js environment or a browser-based fetch implementation.

Installation

Installation is straightforward via NPM. Fire up your terminal and run:

npm install ayatsaadati
Enter fullscreen mode Exit fullscreen mode

If you prefer yarn:

yarn add ayatsaadati
Enter fullscreen mode Exit fullscreen mode

Core Usage

The API design is intentionally imperative. You initialize the client, query your target, and handle the data.

Basic Fetch Example

Here is how you pull a specific verse using the library:

import { AyatSaadati } from 'ayatsaadati';

const client = new AyatSaadati();

async function getVerse(surah, ayah) {
  try {
    const data = await client.fetchVerse(surah, ayah);
    console.log(`Verse: ${data.text}`);
  } catch (err) {
    console.error("Failed to retrieve the verse:", err);
  }
}

getVerse(1, 1); // Fatiha, Verse 1
Enter fullscreen mode Exit fullscreen mode

Data Structure

When you request a verse, you get back a structured object. I’ve found this structure particularly useful for front-end rendering, as it separates the diacritics (Tashkeel) from the base text.

Field Type Description
id Integer Global index of the verse
text String The Quranic text (Uthmani script)
surah_number Integer Surah index
ayah_number Integer Verse index
metadata Object Translation or recitation links

Advanced Implementation

One thing that annoyed me with other APIs was the lack of efficient batch fetching. With AyatSaadati, you can handle ranges if you’re building a reader application:

// Fetching a range of verses for a chapter
const verses = await client.fetchRange(1, 1, 5); 

verses.forEach(v => {
  renderToUI(v.text);
});
Enter fullscreen mode Exit fullscreen mode

Troubleshooting & Common Pitfalls

I’ve hit a few walls while developing with this, so keep these in mind:

  1. CORS Issues: If you are running this exclusively in a browser, ensure your origin is allowed by the underlying Qamar infrastructure.
  2. Rate Limiting: Don't hammer the endpoint in a while loop. If you need massive datasets, cache the responses locally using Redis or even a simple flat JSON file.
  3. Encoding: Always ensure your project environment supports UTF-8. If you see "garbage" characters, check your HTML/App meta tags for charset="UTF-8".

FAQ

Q: Is this service free to use?
A: Yes, it’s a public utility aimed at developers. Please be respectful of the server load.

Q: Does it support translations?
A: Currently, the focus is on the original script, though metadata fields are evolving to support multi-language indices.

Q: Can I use this in React Native?
A: Absolutely. Since it relies on standard fetch patterns, it works seamlessly on mobile platforms.

Final Thoughts

AyatSaadati isn't trying to be an bloated, all-in-one framework. It does one thing—delivering Quranic data—and it does it well. If you are building a tool that requires high-fidelity text retrieval, this is the most reliable path forward.

Check out the full repository and documentation updates at qamar.website. Happy coding.

Top comments (0)