@quranjs/api 1.0.1

package/dist/types/index.d.ts

@@ -0,0 +1,88 @@
+export declare enum Language {
+    ARABIC = "ar",
+    ENGLISH = "en",
+    URDU = "ur",
+    BENGALI = "bn",
+    TURKISH = "tr",
+    SPANISH = "es",
+    GERMAN = "de",
+    BOSNIAN = "bs",
+    RUSSIAN = "ru",
+    ALBANIAN_AL = "al",
+    FRENCH = "fr",
+    DUTCH = "nl",
+    TAMIL = "ta",
+    TAJIK = "tg",
+    INDONESIAN = "id",
+    UZBEK = "uz",
+    VIETNAMESE = "vi",
+    CHINESE = "zh",
+    ITALIAN = "it",
+    JAPANESE = "ja",
+    MALAYALAM = "ml",
+    AMHARIC = "am",
+    KAZAKH = "kk",
+    PORTUGUESE = "pt",
+    TAGALOG = "tl",
+    THAI = "th",
+    KOREAN = "ko",
+    HINDI = "hi",
+    KURDISH = "ku",
+    HAUSA = "ha",
+    AZERI = "az",
+    SWAHILI = "sw",
+    PERSIAN = "fa",
+    SERBIAN = "sr",
+    MARANAO = "mrn",
+    AMAZIGH = "zgh",
+    ASSAMESE = "as",
+    BULGARIAN = "bg",
+    CHECHEN = "ce",
+    CZECH = "cs",
+    DIVEHI = "dv",
+    DHIVEHI = "dv",
+    MALDIVIAN = "dv",
+    FINNISH = "fi",
+    GUJAARATI = "gu",
+    HEBREW = "he",
+    GEORGIAN = "ka",
+    CENTRAL_KHMER = "km",
+    GANDA = "lg",
+    MARATHI = "mr",
+    YORUBA = "yo",
+    MALAY = "ms",
+    NEPALI = "ne",
+    SWEDISH = "sv",
+    TELUGU = "te",
+    TATAR = "tt",
+    UIGHUR = "ug",
+    UYGHUR = "ug",
+    UKRAINIAN = "uk",
+    NORWEGIAN = "no",
+    OROMO = "om",
+    POLISH = "pl",
+    PASHTO = "ps",
+    ROMANIAN = "ro",
+    SINDHI = "sd",
+    NORTHERN_SAMI = "se",
+    SINHALA = "si",
+    SINHALESE = "si",
+    SOMALI = "so",
+    ALBANIAN_SQ = "sq"
+}
+export declare enum QuranFont {
+    MadaniV1 = "code_v1",
+    MadaniV2 = "code_v2",
+    Uthmani = "text_uthmani"
+}
+export declare type VerseField = 'chapterId' | 'textUthmani' | 'textUthmaniSimple' | 'textImlaei' | 'textImlaeiSimple' | 'textIndopak' | 'textUthmaniTajweed' | 'imageUrl' | 'imageWidth' | 'codeV1' | 'codeV2' | 'v1Page' | 'v2Page';
+export declare type WordField = 'v1Page' | 'v2Page' | 'textUthmani' | 'textImlaei' | 'textIndopak' | 'verseKey' | 'location' | 'codeV1' | 'codeV2';
+export declare type TranslationField = 'resourceName' | 'verseId' | 'languageId' | 'languageName' | 'verseKey' | 'chapterId' | 'verseNumber' | 'juzNumber' | 'hizbNumber' | 'rubNumber' | 'pageNumber';
+export declare type VerseRecitationField = 'id' | 'chapterId' | 'segments' | 'format';
+export * from './VerseKey';
+export * from './ChapterId';
+export * from './HizbNumber';
+export * from './JuzNumber';
+export * from './PageNumber';
+export * from './RubNumber';
+export * from './api';

package/dist/utils/misc.d.ts

@@ -0,0 +1 @@
+export declare const removeBeginningSlash: (url: string) => string;

package/dist/utils/qs-stringify.d.ts

@@ -0,0 +1,21 @@
+declare type QueryObject = Record<string, any>;
+export declare type StringifyFunction = (key: string, value: any) => any;
+declare type Config = {
+    eq?: string;
+    sep?: string;
+    fn?: StringifyFunction;
+    prefix?: string;
+};
+/**
+ * Given a query object, return the query string
+ * See qs-stringify.test.ts for examples
+ *
+ * @param {QueryObject} obj a query object to be converted to a query string
+ * @param {Config} config optional configuration
+ * @returns {string} query string
+ *
+ * @example
+ * stringify({a: 1, b: 2}) // returns 'a=1&b=s'
+ */
+declare function stringify(obj: QueryObject, config?: Config): string;
+export default stringify;

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@quranjs/api",
+  "description": "A library for fetching quran data from the quran.com API.",
+  "author": "Ahmed Riad <me@ar1.dev> (https://ar1.dev)",
+  "publishConfig": {
+    "access": "public"
+  },
+  "version": "1.0.1",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "typings": "dist/index.d.ts",
+  "module": "dist/api.esm.js",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "start": "dts watch",
+    "build": "dts build",
+    "test": "dts test",
+    "test:dev": "dts test --watch",
+    "lint": "dts lint src test mocks",
+    "prepare": "husky install && dts build",
+    "size": "size-limit",
+    "analyze": "size-limit --why"
+  },
+  "devDependencies": {
+    "@rollup/plugin-alias": "^3.1.9",
+    "@rollup/plugin-node-resolve": "^13.1.3",
+    "@size-limit/preset-small-lib": "^7.0.8",
+    "@types/humps": "^2.0.1",
+    "dts-cli": "^1.4.0",
+    "husky": "^7.0.4",
+    "msw": "^0.39.2",
+    "rollup-plugin-buble": "^0.19.8",
+    "rollup-plugin-sizes": "^1.0.4",
+    "size-limit": "^7.0.8",
+    "tslib": "^2.3.1",
+    "typescript": "^4.6.2"
+  },
+  "prettier": {
+    "printWidth": 80,
+    "semi": true,
+    "singleQuote": true,
+    "trailingComma": "es5"
+  },
+  "size-limit": [
+    {
+      "path": "dist/api.cjs.production.min.js",
+      "limit": "10 KB"
+    },
+    {
+      "path": "dist/api.esm.js",
+      "limit": "10 KB"
+    }
+  ],
+  "engines": {
+    "node": ">=12"
+  },
+  "dependencies": {
+    "cross-fetch": "^3.1.5",
+    "humps": "^2.0.1"
+  }
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export { default as quran } from './sdk';
+export * from './types';

package/src/sdk/index.ts

@@ -0,0 +1,9 @@
+import v4 from './v4';
+import utils from './utils';
+
+const quran = {
+  v4,
+  utils,
+};
+
+export default quran;

package/src/sdk/utils.ts

@@ -0,0 +1,230 @@
+// this maps chapterNumber to verseCount
+export const versesMaping = {
+  '1': 7,
+  '2': 286,
+  '3': 200,
+  '4': 176,
+  '5': 120,
+  '6': 165,
+  '7': 206,
+  '8': 75,
+  '9': 129,
+  '10': 109,
+  '11': 123,
+  '12': 111,
+  '13': 43,
+  '14': 52,
+  '15': 99,
+  '16': 128,
+  '17': 111,
+  '18': 110,
+  '19': 98,
+  '20': 135,
+  '21': 112,
+  '22': 78,
+  '23': 118,
+  '24': 64,
+  '25': 77,
+  '26': 227,
+  '27': 93,
+  '28': 88,
+  '29': 69,
+  '30': 60,
+  '31': 34,
+  '32': 30,
+  '33': 73,
+  '34': 54,
+  '35': 45,
+  '36': 83,
+  '37': 182,
+  '38': 88,
+  '39': 75,
+  '40': 85,
+  '41': 54,
+  '42': 53,
+  '43': 89,
+  '44': 59,
+  '45': 37,
+  '46': 35,
+  '47': 38,
+  '48': 29,
+  '49': 18,
+  '50': 45,
+  '51': 60,
+  '52': 49,
+  '53': 62,
+  '54': 55,
+  '55': 78,
+  '56': 96,
+  '57': 29,
+  '58': 22,
+  '59': 24,
+  '60': 13,
+  '61': 14,
+  '62': 11,
+  '63': 11,
+  '64': 18,
+  '65': 12,
+  '66': 12,
+  '67': 30,
+  '68': 52,
+  '69': 52,
+  '70': 44,
+  '71': 28,
+  '72': 28,
+  '73': 20,
+  '74': 56,
+  '75': 40,
+  '76': 31,
+  '77': 50,
+  '78': 40,
+  '79': 46,
+  '80': 42,
+  '81': 29,
+  '82': 19,
+  '83': 36,
+  '84': 25,
+  '85': 22,
+  '86': 17,
+  '87': 19,
+  '88': 26,
+  '89': 30,
+  '90': 20,
+  '91': 15,
+  '92': 21,
+  '93': 11,
+  '94': 8,
+  '95': 8,
+  '96': 19,
+  '97': 5,
+  '98': 8,
+  '99': 8,
+  '100': 11,
+  '101': 11,
+  '102': 8,
+  '103': 3,
+  '104': 9,
+  '105': 5,
+  '106': 4,
+  '107': 7,
+  '108': 3,
+  '109': 6,
+  '110': 3,
+  '111': 5,
+  '112': 4,
+  '113': 5,
+  '114': 6,
+};
+
+/**
+ * Validates chapter id
+ * @param id chapter id
+ * @example 
+ isValidChapterId('1') // true
+ isValidChapterId('114') // true
+ isValidChapterId('0') // false
+ isValidChapterId('-1') // false
+ isValidChapterId('200') // false
+ */
+const isValidChapterId = (id: string | number) => {
+  const parsedId = typeof id === 'number' ? id : Number(id);
+  if (!parsedId || parsedId <= 0 || parsedId > 114) return false;
+  return true;
+};
+
+/**
+ * Validates juz number
+ * @param juz juz number
+ * @example 
+ isValidJuz('1') // true
+ isValidJuz('30') // true
+ isValidJuz('0') // false
+ isValidJuz('-1') // false
+ isValidJuz('200') // false
+ */
+const isValidJuz = (juz: string | number) => {
+  const parsedJuz = typeof juz === 'number' ? juz : Number(juz);
+  if (!parsedJuz || parsedJuz <= 0 || parsedJuz > 30) return false;
+  return true;
+};
+
+/**
+ * Validates rub number
+ * @param rub rub number
+ * @example 
+ isValidRub('1') // true
+ isValidRub('240') // true
+ isValidRub('0') // false
+ isValidRub('-1') // false
+ isValidRub('300') // false
+ */
+const isValidRub = (rub: string | number) => {
+  const parsedRub = typeof rub === 'number' ? rub : Number(rub);
+  if (!parsedRub || parsedRub <= 0 || parsedRub > 240) return false;
+  return true;
+};
+
+/**
+ * Validates hizb number
+ * @param hizb hizb number
+ * @example 
+ isValidHizb('1') // true
+ isValidHizb('60') // true
+ isValidHizb('0') // false
+ isValidHizb('-1') // false
+ isValidHizb('200') // false
+ */
+const isValidHizb = (hizb: string | number) => {
+  const parsedHizb = typeof hizb === 'number' ? hizb : Number(hizb);
+  if (!parsedHizb || parsedHizb <= 0 || parsedHizb > 60) return false;
+  return true;
+};
+
+/**
+ * Validates mushaf page number
+ * @param page mushaf page number
+ * @example 
+ isValidQuranPage('1') // true
+ isValidQuranPage('604') // true
+ isValidQuranPage('0') // false
+ isValidQuranPage('-1') // false
+ isValidQuranPage('1000') // false
+ */
+const isValidQuranPage = (page: string | number) => {
+  const parsedPage = typeof page === 'number' ? page : Number(page);
+  if (!parsedPage || parsedPage <= 0 || parsedPage > 604) return false;
+  return true;
+};
+
+/**
+ * Validates verse key
+ * @param key colon separated verse key (chapter:verse)
+ * @example 
+ isValidVerseKey('1:1') // true
+ isValidVerseKey('30:1') // true
+ isValidVerseKey('0') // false
+ isValidVerseKey('1:-') // false
+ isValidVerseKey('1_1') // false
+ */
+const isValidVerseKey = (key: string) => {
+  const [chapterId, verseId] = key.trim().split(':');
+  if (!chapterId || !verseId || !isValidChapterId(chapterId)) return false;
+
+  const parsedVerse = Number(verseId);
+  const verseCount = (versesMaping as any)[chapterId];
+  if (!parsedVerse || parsedVerse <= 0 || parsedVerse > verseCount)
+    return false;
+
+  return true;
+};
+
+const Utils = {
+  isValidChapterId,
+  isValidJuz,
+  isValidRub,
+  isValidHizb,
+  isValidQuranPage,
+  isValidVerseKey,
+};
+
+export default Utils;

package/src/sdk/v4/_fetcher.ts

@@ -0,0 +1,28 @@
+import fetch from 'cross-fetch';
+import { camelizeKeys, decamelizeKeys } from 'humps';
+import stringify from '@/utils/qs-stringify';
+import { removeBeginningSlash } from '@/utils/misc';
+
+export const API_BASE_URL = 'https://api.quran.com/api/v4/';
+
+export const makeUrl = (url: string, params?: Record<string, unknown>) => {
+  const baseUrl = `${API_BASE_URL}${removeBeginningSlash(url)}`;
+  if (!params) return baseUrl;
+
+  const decamelizedKeys = decamelizeKeys(params);
+  const paramsString = stringify(decamelizedKeys);
+  if (!paramsString) return baseUrl;
+
+  return `${baseUrl}?${paramsString}`;
+};
+
+export const fetcher = async <T extends object>(
+  url: string,
+  params: Record<string, unknown> = {}
+) => {
+  const res = await fetch(makeUrl(url, params));
+  if (res.status >= 400) throw new Error(`${res.status} ${res.statusText}`);
+  const json = await res.json();
+
+  return camelizeKeys(json) as T;
+};