@quranjs/api 1.5.1 → 1.7.0

package/src/sdk/v4/verses.ts

@@ -1,6 +1,6 @@
 import {
   ChapterId,
-  // HizbNumber,
+  HizbNumber,
   JuzNumber,
   Language,
   PageNumber,
@@ -13,61 +13,59 @@ import {
 } from '../../types';
 import { decamelize } from 'humps';
 import Utils from '../utils';
-import { fetcher } from './_fetcher';
-
-type GetVerseOptions = Partial<{
-  language: Language;
-  reciter: string | number;
-  words: boolean;
-  translations: string[] | number[];
-  tafsirs: string[] | number[];
-  wordFields: Partial<Record<WordField, boolean>>;
-  translationFields: Partial<Record<TranslationField, boolean>>;
-  fields: Partial<Record<VerseField, boolean>>;
-  page: number;
-  perPage: number;
-}>;
+import { fetcher, mergeApiOptions } from './_fetcher';
+import { BaseApiOptions } from '../../types/BaseApiOptions';
+
+type GetVerseOptions = Partial<
+  BaseApiOptions & {
+    reciter: string | number;
+    words: boolean;
+    translations: string[] | number[];
+    tafsirs: string[] | number[];
+    wordFields: Partial<Record<WordField, boolean>>;
+    translationFields: Partial<Record<TranslationField, boolean>>;
+    fields: Partial<Record<VerseField, boolean>>;
+    page: number;
+    perPage: number;
+  }
+>;
 
 const defaultOptions: GetVerseOptions = {
   language: Language.ARABIC,
   perPage: 50,
+  words: false,
 };
 
-const getVerseOptions = (options: GetVerseOptions = {}) => {
-  const initial = { ...defaultOptions, ...options };
-  const result: any = { language: initial.language, perPage: initial.perPage };
-
-  if (initial.page) result.page = initial.page;
-  if (initial.words !== undefined) result.words = initial.words;
-  if (initial.translations)
-    result.translations = initial.translations.join(',');
-  if (initial.tafsirs) result.tafsirs = initial.tafsirs.join(',');
-
-  if (initial.fields) {
-    const fields: string[] = [];
-    for (const [key, value] of Object.entries(initial.fields)) {
-      if (value) fields.push(decamelize(key));
-    }
-    result.fields = fields.join(',');
-  }
+const mergeVerseOptions = (options: GetVerseOptions = {}) => {
+  const result = mergeApiOptions(options, defaultOptions);
+
+  // @ts-expect-error - we accept an array of strings, however, the API expects a comma separated string
+  if (result.translations) result.translations = result.translations.join(',');
 
-  if (initial.wordFields) {
+  // @ts-expect-error - we accept an array of strings, however, the API expects a comma separated string
+  if (result.tafsirs) result.tafsirs = result.tafsirs.join(',');
+
+  if (result.wordFields) {
     const wordFields: string[] = [];
-    for (const [key, value] of Object.entries(initial.wordFields)) {
+    Object.entries(result.wordFields).forEach(([key, value]) => {
       if (value) wordFields.push(decamelize(key));
-    }
+    });
     result.wordFields = wordFields.join(',');
   }
 
-  if (initial.translationFields) {
+  if (result.translationFields) {
     const translationFields: string[] = [];
-    for (const [key, value] of Object.entries(initial.translationFields)) {
+    Object.entries(result.translationFields).forEach(([key, value]) => {
       if (value) translationFields.push(decamelize(key));
-    }
+    });
     result.translationFields = translationFields.join(',');
   }
 
-  if (initial.reciter) result.audio = initial.reciter;
+  // rename `reciter` to `audio` because the API expects `audio`
+  if (result.reciter) {
+    result.audio = result.reciter;
+    result.reciter = undefined;
+  }
 
   return result;
 };
@@ -83,9 +81,13 @@ const getVerseOptions = (options: GetVerseOptions = {}) => {
  */
 const findByKey = async (key: VerseKey, options?: GetVerseOptions) => {
   if (!Utils.isValidVerseKey(key)) throw new Error('Invalid verse key');
-  const params = getVerseOptions(options);
+  const params = mergeVerseOptions(options);
   const url = `/verses/by_key/${key}`;
-  const { verse } = await fetcher<{ verse: Verse }>(url, params);
+  const { verse } = await fetcher<{ verse: Verse }>(
+    url,
+    params,
+    options?.fetchFn
+  );
 
   return verse;
 };
@@ -101,9 +103,13 @@ const findByKey = async (key: VerseKey, options?: GetVerseOptions) => {
  */
 const findByChapter = async (id: ChapterId, options?: GetVerseOptions) => {
   if (!Utils.isValidChapterId(id)) throw new Error('Invalid chapter id');
-  const params = getVerseOptions(options);
+  const params = mergeVerseOptions(options);
   const url = `/verses/by_chapter/${id}`;
-  const { verses } = await fetcher<{ verses: Verse[] }>(url, params);
+  const { verses } = await fetcher<{ verses: Verse[] }>(
+    url,
+    params,
+    options?.fetchFn
+  );
 
   return verses;
 };
@@ -120,9 +126,13 @@ const findByChapter = async (id: ChapterId, options?: GetVerseOptions) => {
 const findByPage = async (page: PageNumber, options?: GetVerseOptions) => {
   if (!Utils.isValidQuranPage(page)) throw new Error('Invalid page');
 
-  const params = getVerseOptions(options);
+  const params = mergeVerseOptions(options);
   const url = `/verses/by_page/${page}`;
-  const { verses } = await fetcher<{ verses: Verse[] }>(url, params);
+  const { verses } = await fetcher<{ verses: Verse[] }>(
+    url,
+    params,
+    options?.fetchFn
+  );
 
   return verses;
 };
@@ -139,14 +149,17 @@ const findByPage = async (page: PageNumber, options?: GetVerseOptions) => {
 const findByJuz = async (juz: JuzNumber, options?: GetVerseOptions) => {
   if (!Utils.isValidJuz(juz)) throw new Error('Invalid juz');
 
-  const params = getVerseOptions(options);
+  const params = mergeVerseOptions(options);
   const url = `/verses/by_juz/${juz}`;
-  const { verses } = await fetcher<{ verses: Verse[] }>(url, params);
+  const { verses } = await fetcher<{ verses: Verse[] }>(
+    url,
+    params,
+    options?.fetchFn
+  );
 
   return verses;
 };
 
-// TODO: uncomment when API is fixed
 /**
  * Get all ayahs for a Hizb.
  * @description https://quran.api-docs.io/v4/verses/by-hizb-number
@@ -156,15 +169,19 @@ const findByJuz = async (juz: JuzNumber, options?: GetVerseOptions) => {
  * quran.v4.verses.findByHizb('1')
  * quran.v4.verses.findByHizb('29')
  */
-// const findByHizb = async (hizb: HizbNumber, options?: GetVerseOptions) => {
-//   if (!Utils.isValidHizb(hizb)) throw new Error('Invalid hizb');
+const findByHizb = async (hizb: HizbNumber, options?: GetVerseOptions) => {
+  if (!Utils.isValidHizb(hizb)) throw new Error('Invalid hizb');
 
-//   const params = getVerseOptions(options);
-//   const url = `/verses/by_hizb/${hizb}`;
-//   const { verses } = await fetcher<{ verses: Verse[] }>(url, params);
+  const params = mergeVerseOptions(options);
+  const url = `/verses/by_hizb/${hizb}`;
+  const { verses } = await fetcher<{ verses: Verse[] }>(
+    url,
+    params,
+    options?.fetchFn
+  );
 
-//   return verses;
-// };
+  return verses;
+};
 
 // TODO: uncomment when API is fixed
 /**
@@ -194,8 +211,12 @@ const findByJuz = async (juz: JuzNumber, options?: GetVerseOptions) => {
  * quran.v4.verses.findRandom()
  */
 const findRandom = async (options?: GetVerseOptions) => {
-  const params = getVerseOptions(options);
-  const { verse } = await fetcher<{ verse: Verse }>('/verses/random', params);
+  const params = mergeVerseOptions(options);
+  const { verse } = await fetcher<{ verse: Verse }>(
+    '/verses/random',
+    params,
+    options?.fetchFn
+  );
 
   return verse;
 };
@@ -205,7 +226,7 @@ const verses = {
   findByChapter,
   findByPage,
   findByJuz,
-  // findByHizb,
+  findByHizb,
   // findByRub,
   findRandom,
 };

package/src/types/BaseApiOptions.ts

@@ -0,0 +1,6 @@
+import { FetchFn, Language } from '.';
+
+export interface BaseApiOptions {
+  language: Language;
+  fetchFn?: FetchFn;
+}

package/src/types/FetchFn.ts

@@ -0,0 +1 @@
+export type FetchFn = (url: string) => Promise<Record<string, unknown>>;

package/src/types/index.ts

@@ -132,3 +132,5 @@ export * from './PageNumber';
 export * from './RubNumber';
 
 export * from './api';
+
+export * from './FetchFn';