widequran 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +336 -0
  3. package/package.json +51 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 WideHoly
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,336 @@
1
+ # widequran
2
+
3
+ [![npm](https://img.shields.io/npm/v/widequran)](https://www.npmjs.com/package/widequran)
4
+ [![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue)](https://www.typescriptlang.org/)
5
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
6
+ [![Zero Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)](https://www.npmjs.com/package/widequran)
7
+
8
+ TypeScript SDK for [WideQuran](https://widequran.com) — access 114 surahs, 31,240 ayahs across 5 translations, 7,604 hadith from Sahih al-Bukhari, 1,896 tafsir entries from Ibn Kathir, and a comprehensive Islamic encyclopedia through a typed API. Zero runtime dependencies, uses native `fetch`.
9
+
10
+ WideQuran is part of the [WideHoly](https://wideholy.com) multi-religion scripture platform, providing structured Quranic data, hadith collections, tafsir commentary, and encyclopedic content about prophets, topics, and Islamic terminology.
11
+
12
+ > **Explore the Quran at [widequran.com](https://widequran.com)** — [Surahs](https://widequran.com/surahs/), [Translations](https://widequran.com/translations/), [Hadith](https://widequran.com/hadith/), [Tafsir](https://widequran.com/tafsir/), [People](https://widequran.com/people/)
13
+
14
+ ## Table of Contents
15
+
16
+ - [Install](#install)
17
+ - [Quick Start](#quick-start)
18
+ - [What You'll Find on WideQuran](#what-youll-find-on-widequran)
19
+ - [Surahs & Ayahs](#surahs--ayahs)
20
+ - [Juz & Hizb Divisions](#juz--hizb-divisions)
21
+ - [Hadith Collections](#hadith-collections)
22
+ - [Tafsir Commentary](#tafsir-commentary)
23
+ - [Prophets & Quranic Figures](#prophets--quranic-figures)
24
+ - [Topics & Glossary](#topics--glossary)
25
+ - [API Reference](#api-reference)
26
+ - [TypeScript Types](#typescript-types)
27
+ - [Learn More About the Quran](#learn-more-about-the-quran)
28
+ - [Also Available for Python](#also-available-for-python)
29
+ - [WideHoly Scripture Platform](#wideholy-scripture-platform)
30
+ - [License](#license)
31
+
32
+ ## Install
33
+
34
+ ```bash
35
+ npm install widequran
36
+ ```
37
+
38
+ ## Quick Start
39
+
40
+ ```ts
41
+ import { WideQuran } from "widequran";
42
+
43
+ const api = new WideQuran();
44
+
45
+ // List all 114 surahs of the Quran
46
+ const surahs = await api.listSurahs();
47
+ console.log(surahs.results[0].name); // Al-Fatihah
48
+
49
+ // Get surah details — Al-Baqarah, the longest surah with 286 ayahs
50
+ const baqarah = await api.getSurah("al-baqarah");
51
+ console.log(baqarah.verse_count); // 286
52
+ console.log(baqarah.revelation_type); // medinan
53
+
54
+ // Search ayahs across all translations
55
+ const results = await api.search("mercy");
56
+ console.log(results.count); // Number of matching ayahs
57
+
58
+ // Browse hadith from Sahih al-Bukhari
59
+ const collections = await api.listHadithCollections();
60
+ console.log(collections.results[0].name); // Sahih al-Bukhari
61
+ ```
62
+
63
+ ## What You'll Find on WideQuran
64
+
65
+ ### Surahs & Ayahs
66
+
67
+ The Quran contains 114 surahs (chapters) with 6,236 ayahs (verses). Surahs range from the 7-ayah Al-Fatihah (the Opening) to the 286-ayah Al-Baqarah (the Cow). Each surah is classified by its place of revelation — Meccan surahs (revealed before the Hijra, 86 surahs) tend to focus on faith and the afterlife, while Medinan surahs (revealed after the Hijra, 28 surahs) address community law and social guidance.
68
+
69
+ WideQuran provides 31,240 ayahs across 5 translations, allowing comparative study of Quranic text.
70
+
71
+ | Translation | Language | Focus |
72
+ |-------------|----------|-------|
73
+ | Sahih International | English | Clear, accurate modern English |
74
+ | Yusuf Ali | English | Classical commentary with footnotes |
75
+ | Pickthall | English | Literal rendering of meaning |
76
+ | Al-Hilali & Khan | English | Saudi-standard translation |
77
+ | Arabic (Uthmani) | Arabic | Original Uthmani script |
78
+
79
+ ```ts
80
+ import { WideQuran } from "widequran";
81
+
82
+ const api = new WideQuran();
83
+
84
+ // Filter surahs by revelation type — 86 Meccan surahs
85
+ const meccan = await api.listSurahs("meccan");
86
+ console.log(meccan.count); // 86
87
+
88
+ // Get Al-Fatihah — the most recited surah in daily prayers
89
+ const fatihah = await api.getSurah("al-fatihah");
90
+ console.log(fatihah.name_arabic); // الفاتحة
91
+ console.log(fatihah.name_translation); // The Opening
92
+ console.log(fatihah.revelation_order); // 5
93
+
94
+ // Retrieve a specific ayah by ID
95
+ const ayah = await api.getAyah(1);
96
+ console.log(ayah.text_arabic); // بِسْمِ اللَّهِ الرَّحْمَنِ الرَّحِيمِ
97
+ console.log(ayah.text_translation); // In the name of Allah...
98
+
99
+ // Search for ayahs containing "patience"
100
+ const patience = await api.search("patience");
101
+ console.log(patience.count); // Ayahs mentioning patience (sabr)
102
+ ```
103
+
104
+ Learn more: [Browse All Surahs](https://widequran.com/surahs/) · [Quran Translations](https://widequran.com/translations/)
105
+
106
+ ### Juz & Hizb Divisions
107
+
108
+ The Quran is divided into 30 equal parts called juz (plural: ajza), each containing roughly 20 pages. This division facilitates reading the entire Quran in one month — one juz per day during Ramadan is a widespread practice. Each juz is further divided into 2 hizbs (60 total), and each hizb into 4 quarters (240 total), used as markers for structured recitation.
109
+
110
+ ```ts
111
+ import { WideQuran } from "widequran";
112
+
113
+ const api = new WideQuran();
114
+
115
+ // List all 30 juz divisions
116
+ const juzList = await api.listJuz();
117
+ console.log(juzList.count); // 30
118
+
119
+ // Get Juz 1 — starts with Al-Fatihah, ends in Al-Baqarah
120
+ const juz1 = await api.getJuz(1);
121
+ console.log(juz1.start_surah); // al-fatihah
122
+ console.log(juz1.end_surah); // al-baqarah
123
+
124
+ // List hizb markers within a specific juz
125
+ const hizbs = await api.listHizbs(1);
126
+ console.log(hizbs.count); // Hizbs in Juz 1
127
+ ```
128
+
129
+ Learn more: [Juz Overview](https://widequran.com/juz/) · [Reading Guide](https://widequran.com/guides/)
130
+
131
+ ### Hadith Collections
132
+
133
+ Hadith are recorded sayings, actions, and approvals of Prophet Muhammad (peace be upon him). WideQuran indexes 7,604 hadith from major collections. Sahih al-Bukhari, compiled by Imam al-Bukhari (810-870 CE), is considered the most authentic hadith collection in Sunni Islam, containing 7,563 hadith across 97 books after rigorous verification from an initial pool of 600,000 narrations.
134
+
135
+ Each hadith includes the isnad (chain of narrators), matn (text), and grading (sahih, hasan, da'if).
136
+
137
+ | Collection | Compiler | Hadith Count | Period |
138
+ |------------|----------|-------------|--------|
139
+ | Sahih al-Bukhari | Imam al-Bukhari | 7,563 | 846 CE |
140
+ | Sahih Muslim | Imam Muslim | — | 875 CE |
141
+ | Sunan Abu Dawud | Abu Dawud | — | 889 CE |
142
+ | Jami at-Tirmidhi | Imam at-Tirmidhi | — | 892 CE |
143
+
144
+ ```ts
145
+ import { WideQuran } from "widequran";
146
+
147
+ const api = new WideQuran();
148
+
149
+ // List available hadith collections
150
+ const collections = await api.listHadithCollections();
151
+ for (const c of collections.results) {
152
+ console.log(`${c.name}: ${c.hadith_count} hadith`);
153
+ }
154
+
155
+ // Get a specific hadith by ID
156
+ const hadith = await api.getHadith(1);
157
+ console.log(hadith.narrator); // Narrator chain
158
+ console.log(hadith.text_english); // English translation
159
+ console.log(hadith.grade); // Sahih, Hasan, etc.
160
+
161
+ // Search hadith for specific topics
162
+ const prayer = await api.searchHadith("prayer");
163
+ console.log(prayer.count); // Hadith about prayer (salat)
164
+
165
+ // Filter search within a specific collection
166
+ const bukhari = await api.searchHadith("fasting", "bukhari");
167
+ console.log(bukhari.count); // Bukhari hadith about fasting
168
+ ```
169
+
170
+ Learn more: [Hadith Collections](https://widequran.com/hadith/) · [Hadith Search](https://widequran.com/hadith/search/)
171
+
172
+ ### Tafsir Commentary
173
+
174
+ Tafsir is the scholarly exegesis and interpretation of the Quran. WideQuran provides 1,896 tafsir entries from Ibn Kathir (1300-1373 CE), one of the most widely referenced tafsir works in Islamic scholarship. Tafsir Ibn Kathir explains verses using other Quranic passages, hadith, and reports from the Companions, following a methodology known as tafsir bil-ma'thur (interpretation through transmitted tradition).
175
+
176
+ ```ts
177
+ import { WideQuran } from "widequran";
178
+
179
+ const api = new WideQuran();
180
+
181
+ // List available tafsir collections
182
+ const tafsirs = await api.listTafsirs();
183
+ for (const t of tafsirs.results) {
184
+ console.log(`${t.name} by ${t.author}: ${t.entry_count} entries`);
185
+ }
186
+
187
+ // Get tafsir entries for a specific surah
188
+ const fatihahTafsir = await api.getTafsirEntries("ibn-kathir", "al-fatihah");
189
+ for (const entry of fatihahTafsir.results) {
190
+ console.log(`Ayah ${entry.ayah_start}-${entry.ayah_end}: ${entry.text.slice(0, 100)}...`);
191
+ }
192
+ ```
193
+
194
+ Learn more: [Tafsir Ibn Kathir](https://widequran.com/tafsir/) · [Tafsir Methodology](https://widequran.com/guides/)
195
+
196
+ ### Prophets & Quranic Figures
197
+
198
+ The Quran mentions 25 prophets by name, from Adam to Muhammad (peace be upon them all). WideQuran catalogs these prophets and other significant figures with their Arabic names, mention counts, and biographical descriptions. The most frequently mentioned prophet in the Quran is Musa (Moses), appearing in 136 ayahs across 34 surahs.
199
+
200
+ ```ts
201
+ import { WideQuran } from "widequran";
202
+
203
+ const api = new WideQuran();
204
+
205
+ // List all Quranic people
206
+ const people = await api.listPeople();
207
+ console.log(people.count); // Total prophets and figures
208
+
209
+ // Filter to prophets only — 25 prophets mentioned by name
210
+ const prophets = await api.listPeople(true);
211
+ for (const p of prophets.results) {
212
+ console.log(`${p.name} (${p.name_arabic}): ${p.mention_count} mentions`);
213
+ }
214
+
215
+ // Get details about Prophet Ibrahim (Abraham)
216
+ const ibrahim = await api.getPerson("ibrahim");
217
+ console.log(ibrahim.name_arabic); // إبراهيم
218
+ console.log(ibrahim.is_prophet); // true
219
+ console.log(ibrahim.mention_count); // Mentions across the Quran
220
+ ```
221
+
222
+ Learn more: [Prophets in the Quran](https://widequran.com/people/) · [Prophet Stories](https://widequran.com/guides/)
223
+
224
+ ### Topics & Glossary
225
+
226
+ WideQuran organizes Quranic content into thematic topics — mercy (rahmah), justice (adl), patience (sabr), charity (sadaqah), and more. Each topic links to relevant ayahs across multiple surahs, enabling thematic study of the Quran.
227
+
228
+ The glossary provides definitions for essential Islamic and Arabic terms, including transliterations and original Arabic script. Terms like "taqwa" (God-consciousness), "dhikr" (remembrance), and "ummah" (community) are explained with their Quranic usage context.
229
+
230
+ ```ts
231
+ import { WideQuran } from "widequran";
232
+
233
+ const api = new WideQuran();
234
+
235
+ // Browse Quranic topics and themes
236
+ const topics = await api.listTopics();
237
+ for (const t of topics.results) {
238
+ console.log(`${t.name}: ${t.ayah_count} related ayahs`);
239
+ }
240
+
241
+ // Browse Islamic glossary terms
242
+ const glossary = await api.listGlossary();
243
+ for (const term of glossary.results) {
244
+ console.log(`${term.term} (${term.term_arabic}): ${term.definition.slice(0, 80)}...`);
245
+ }
246
+ ```
247
+
248
+ Learn more: [Quranic Topics](https://widequran.com/topics/) · [Islamic Glossary](https://widequran.com/glossary/)
249
+
250
+ ## API Reference
251
+
252
+ | Method | Parameters | Returns | Description |
253
+ |--------|-----------|---------|-------------|
254
+ | `listSurahs` | `revelationType?` | `PaginatedResponse<Surah>` | List all 114 surahs |
255
+ | `getSurah` | `slug` | `Surah` | Surah details by slug |
256
+ | `getAyah` | `ayahId` | `Ayah` | Get ayah by ID |
257
+ | `search` | `query, surah?` | `PaginatedResponse<Ayah>` | Search ayahs by text |
258
+ | `listJuz` | — | `PaginatedResponse<Juz>` | List all 30 juz |
259
+ | `getJuz` | `number` | `Juz` | Juz details by number |
260
+ | `listHizbs` | `juz?` | `PaginatedResponse<Hizb>` | List hizb markers |
261
+ | `listTafsirs` | — | `PaginatedResponse<Tafsir>` | List tafsir collections |
262
+ | `getTafsirEntries` | `tafsir?, surah?` | `PaginatedResponse<TafsirEntry>` | Get tafsir entries |
263
+ | `listHadithCollections` | — | `PaginatedResponse<HadithCollection>` | List hadith collections |
264
+ | `getHadith` | `hadithId` | `Hadith` | Get hadith by ID |
265
+ | `searchHadith` | `query, collection?` | `PaginatedResponse<Hadith>` | Search hadith text |
266
+ | `listPeople` | `isProphet?` | `PaginatedResponse<QuranicPerson>` | List Quranic people |
267
+ | `getPerson` | `slug` | `QuranicPerson` | Person details by slug |
268
+ | `listTopics` | — | `PaginatedResponse<Topic>` | List Quranic topics |
269
+ | `listGlossary` | — | `PaginatedResponse<GlossaryTerm>` | List glossary terms |
270
+
271
+ ## TypeScript Types
272
+
273
+ All response types are fully exported:
274
+
275
+ ```ts
276
+ import type {
277
+ Surah,
278
+ Ayah,
279
+ Juz,
280
+ Hizb,
281
+ Tafsir,
282
+ TafsirEntry,
283
+ HadithCollection,
284
+ Hadith,
285
+ QuranicPerson,
286
+ Topic,
287
+ GlossaryTerm,
288
+ PaginatedResponse,
289
+ } from "widequran";
290
+ ```
291
+
292
+ | Type | Key Fields |
293
+ |------|-----------|
294
+ | `Surah` | `slug`, `number`, `name`, `name_arabic`, `verse_count`, `revelation_type` |
295
+ | `Ayah` | `id`, `surah`, `ayah_number`, `text_arabic`, `text_translation`, `juz` |
296
+ | `Juz` | `number`, `start_surah`, `start_ayah`, `end_surah`, `end_ayah` |
297
+ | `Hizb` | `number`, `juz`, `quarter`, `start_surah`, `start_ayah` |
298
+ | `Tafsir` | `slug`, `name`, `author`, `language`, `entry_count` |
299
+ | `TafsirEntry` | `id`, `tafsir`, `surah`, `ayah_start`, `ayah_end`, `text` |
300
+ | `HadithCollection` | `slug`, `name`, `compiler`, `hadith_count` |
301
+ | `Hadith` | `id`, `collection`, `hadith_number`, `narrator`, `text_english`, `grade` |
302
+ | `QuranicPerson` | `slug`, `name`, `name_arabic`, `is_prophet`, `mention_count` |
303
+ | `Topic` | `slug`, `name`, `ayah_count` |
304
+ | `GlossaryTerm` | `slug`, `term`, `term_arabic`, `transliteration`, `definition` |
305
+ | `PaginatedResponse<T>` | `count`, `next`, `previous`, `results` |
306
+
307
+ ## Learn More About the Quran
308
+
309
+ - **Browse**: [Surahs](https://widequran.com/surahs/) · [Translations](https://widequran.com/translations/) · [Juz](https://widequran.com/juz/)
310
+ - **Study**: [Tafsir](https://widequran.com/tafsir/) · [Topics](https://widequran.com/topics/) · [People](https://widequran.com/people/)
311
+ - **Reference**: [Hadith Collections](https://widequran.com/hadith/) · [Glossary](https://widequran.com/glossary/)
312
+ - **API**: [REST API Docs](https://widequran.com/developers/) · [OpenAPI Spec](https://widequran.com/api/openapi.json)
313
+ - **Python**: [PyPI Package](https://pypi.org/project/widequran/)
314
+
315
+ ## Also Available for Python
316
+
317
+ | Platform | Install | Link |
318
+ |----------|---------|------|
319
+ | **PyPI** | `pip install widequran` | [PyPI](https://pypi.org/project/widequran/) |
320
+
321
+ ## WideHoly Scripture Platform
322
+
323
+ Part of the [WideHoly](https://wideholy.com) multi-religion scripture platform.
324
+
325
+ | Site | Domain | Focus |
326
+ |------|--------|-------|
327
+ | **WideQuran** | [widequran.com](https://widequran.com) | **114 surahs, 31,240 ayahs, 7,604 hadith, tafsir, Islamic encyclopedia** |
328
+ | WideBible | [widebible.com](https://widebible.com) | 66 books, 31,102 verses, cross-references, biblical encyclopedia |
329
+ | WideGita | [widegita.com](https://widegita.com) | 18 chapters, 700 shlokas, Bhagavad Gita commentary |
330
+ | WideTorah | [widetorah.com](https://widetorah.com) | Torah, Talmud, Jewish scripture and commentary |
331
+ | WideSutra | [widesutra.com](https://widesutra.com) | Buddhist sutras, Pali Canon, Mahayana texts |
332
+ | WideHoly | [wideholy.com](https://wideholy.com) | Multi-religion scripture hub and cross-reference |
333
+
334
+ ## License
335
+
336
+ MIT
package/package.json ADDED
@@ -0,0 +1,51 @@
1
+ {
2
+ "name": "widequran",
3
+ "version": "0.1.0",
4
+ "description": "TypeScript SDK for WideQuran -- 114 surahs, 31,240 ayahs, 7,604 hadith, tafsir commentary, and Islamic encyclopedia. Zero dependencies.",
5
+ "type": "module",
6
+ "main": "dist/index.js",
7
+ "types": "dist/index.d.ts",
8
+ "exports": {
9
+ ".": {
10
+ "import": "./dist/index.js",
11
+ "types": "./dist/index.d.ts"
12
+ }
13
+ },
14
+ "files": [
15
+ "dist"
16
+ ],
17
+ "scripts": {
18
+ "build": "tsup src/index.ts --format esm --dts",
19
+ "test": "vitest run",
20
+ "typecheck": "tsc --noEmit"
21
+ },
22
+ "keywords": [
23
+ "quran",
24
+ "quran-api",
25
+ "surah",
26
+ "ayah",
27
+ "hadith",
28
+ "tafsir",
29
+ "islamic",
30
+ "scripture",
31
+ "juz",
32
+ "hizb",
33
+ "bukhari",
34
+ "ibn-kathir",
35
+ "quran-sdk",
36
+ "quran-search",
37
+ "typescript"
38
+ ],
39
+ "author": "WideHoly",
40
+ "license": "MIT",
41
+ "homepage": "https://widequran.com",
42
+ "repository": {
43
+ "type": "git",
44
+ "url": "https://github.com/dobestan/widequran-js"
45
+ },
46
+ "devDependencies": {
47
+ "tsup": "^8.0",
48
+ "typescript": "^5.7",
49
+ "vitest": "^3.0"
50
+ }
51
+ }