feat: accept a custom fetcher function in all methods

Author: ahmedriad1

package.json

@@ -26,10 +26,10 @@
     "analyze": "size-limit --why"
   },
   "dependencies": {
-    "cross-fetch": "^3.1.5",
     "humps": "^2.0.1"
   },
   "devDependencies": {
+    "cross-fetch": "^3.1.5",
     "@size-limit/preset-small-lib": "^7.0.8",
     "@types/humps": "^2.0.1",
     "@typescript-eslint/eslint-plugin": "^5.42.0",
@@ -62,4 +62,4 @@
   "engines": {
     "node": ">=12"
   }
-}
+}

src/sdk/v4/_fetcher.ts

@@ -1,6 +1,6 @@
-import fetch from 'cross-fetch';
-import { camelizeKeys, decamelizeKeys } from 'humps';
-import stringify from '../../utils/qs-stringify';
+import { camelizeKeys, decamelize, decamelizeKeys } from 'humps';
+import { FetchFn } from '../../types';
+import { BaseApiOptions } from '../../types/BaseApiOptions';
 import { removeBeginningSlash } from '../../utils/misc';
 
 export const API_BASE_URL = 'https://api.quran.com/api/v4/';
@@ -9,20 +9,71 @@ 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);
+  const paramsWithDecamelizedKeys = decamelizeKeys(params) as Record<
+    string,
+    string
+  >;
+  const paramsString = new URLSearchParams(
+    Object.entries(paramsWithDecamelizedKeys).filter(
+      ([, value]) => value !== undefined
+    )
+  ).toString();
   if (!paramsString) return baseUrl;
 
   return `${baseUrl}?${paramsString}`;
 };
 
 export const fetcher = async <T extends object>(
   url: string,
-  params: Record<string, unknown> = {}
+  params: Record<string, unknown> = {},
+  fetchFn?: FetchFn
 ) => {
+  if (fetchFn) {
+    const json = await fetchFn(makeUrl(url, params));
+    return camelizeKeys(json) as T;
+  }
+
+  if (typeof fetch === 'undefined') {
+    throw new Error('fetch is not defined');
+  }
+
+  // if there is no fetchFn, we use the global fetch
   const res = await fetch(makeUrl(url, params));
-  if (res.status >= 400) throw new Error(`${res.status} ${res.statusText}`);
+
+  if (!res.ok || res.status >= 400) {
+    throw new Error(`${res.status} ${res.statusText}`);
+  }
+
   const json = await res.json();
 
   return camelizeKeys(json) as T;
 };
+
+type MergeApiOptionsObject = Pick<BaseApiOptions, 'fetchFn'> & {
+  fields?: Record<string, boolean>;
+} & Record<string, unknown>;
+
+export const mergeApiOptions = (
+  options: MergeApiOptionsObject = {},
+  defaultOptions: Record<string, unknown> = {}
+) => {
+  // we can set it to undefined because `makeUrl` will filter it out
+  if (options.fetchFn) options.fetchFn = undefined;
+
+  const final: Record<string, unknown> = {
+    ...defaultOptions,
+    ...options,
+  };
+
+  if (final.fields) {
+    const fields: string[] = [];
+    Object.entries(final.fields).forEach(([key, value]) => {
+      if (value) fields.push(decamelize(key));
+    });
+
+    // convert `fields` to a string sperated by commas
+    final.fields = fields.join(',');
+  }
+
+  return final;
+};

src/sdk/v4/audio.ts

@@ -11,52 +11,26 @@ import {
   VerseKey,
   VerseRecitationField,
 } from '../../types';
-import { decamelize } from 'humps';
 import Utils from '../utils';
-import { fetcher } from './_fetcher';
+import { fetcher, mergeApiOptions } from './_fetcher';
+import { BaseApiOptions } from '../../types/BaseApiOptions';
 
-type GetChapterRecitationOptions = Partial<{
-  language: Language;
-}>;
+type GetChapterRecitationOptions = Partial<BaseApiOptions>;
 
 const defaultChapterRecitationsOptions: GetChapterRecitationOptions = {
   language: Language.ARABIC,
 };
 
-const getChapterRecitationsOptions = (
-  options: GetChapterRecitationOptions = {}
-) => {
-  const final: any = { ...defaultChapterRecitationsOptions, ...options };
-
-  return final;
-};
-
-type GetVerseRecitationOptions = Partial<{
-  language: Language;
-  fields: Partial<Record<VerseRecitationField, boolean>>;
-}>;
+type GetVerseRecitationOptions = Partial<
+  BaseApiOptions & {
+    fields: Partial<Record<VerseRecitationField, boolean>>;
+  }
+>;
 
 const defaultVerseRecitationsOptions: GetVerseRecitationOptions = {
   language: Language.ARABIC,
 };
 
-const getVerseRecitationsOptions = (
-  options: GetVerseRecitationOptions = {}
-) => {
-  const initial = { ...defaultVerseRecitationsOptions, ...options };
-  const final: any = { language: initial.language };
-
-  if (initial.fields) {
-    const fields: string[] = [];
-    for (const [key, value] of Object.entries(initial.fields)) {
-      if (value) fields.push(decamelize(key));
-    }
-    final.fields = fields.join(',');
-  }
-
-  return final;
-};
-
 /**
  * Get all chapter recitations for specific reciter
  * @description https://quran.api-docs.io/v4/audio-recitations/list-of-all-surah-audio-files-for-specific-reciter
@@ -69,10 +43,11 @@ const findAllChapterRecitations = async (
   reciterId: string,
   options?: GetChapterRecitationOptions
 ) => {
-  const params = getChapterRecitationsOptions(options);
+  const params = mergeApiOptions(options, defaultChapterRecitationsOptions);
   const { audioFiles } = await fetcher<{ audioFiles: ChapterRecitation[] }>(
     `/chapter_recitations/${reciterId}`,
-    params
+    params,
+    options?.fetchFn
   );
   return audioFiles;
 };
@@ -93,10 +68,11 @@ const findChapterRecitationById = async (
 ) => {
   if (!Utils.isValidChapterId(chapterId)) throw new Error('Invalid chapter id');
 
-  const params = getChapterRecitationsOptions(options);
+  const params = mergeApiOptions(options, defaultChapterRecitationsOptions);
   const { audioFile } = await fetcher<{ audioFile: ChapterRecitation }>(
     `/chapter_recitations/${reciterId}/${chapterId}`,
-    params
+    params,
+    options?.fetchFn
   );
 
   return audioFile;
@@ -118,11 +94,15 @@ const findVerseRecitationsByChapter = async (
 ) => {
   if (!Utils.isValidChapterId(chapterId)) throw new Error('Invalid chapter id');
 
-  const params = getVerseRecitationsOptions(options);
+  const params = mergeApiOptions(options, defaultVerseRecitationsOptions);
   const data = await fetcher<{
     audioFiles: VerseRecitation[];
     pagination: Pagination;
-  }>(`/recitations/${recitationId}/by_chapter/${chapterId}`, params);
+  }>(
+    `/recitations/${recitationId}/by_chapter/${chapterId}`,
+    params,
+    options?.fetchFn
+  );
 
   return data;
 };
@@ -143,11 +123,11 @@ const findVerseRecitationsByJuz = async (
 ) => {
   if (!Utils.isValidJuz(juz)) throw new Error('Invalid juz');
 
-  const params = getVerseRecitationsOptions(options);
+  const params = mergeApiOptions(options, defaultVerseRecitationsOptions);
   const data = await fetcher<{
     audioFiles: VerseRecitation[];
     pagination: Pagination;
-  }>(`/recitations/${recitationId}/by_juz/${juz}`, params);
+  }>(`/recitations/${recitationId}/by_juz/${juz}`, params, options?.fetchFn);
 
   return data;
 };
@@ -168,11 +148,11 @@ const findVerseRecitationsByPage = async (
 ) => {
   if (!Utils.isValidQuranPage(page)) throw new Error('Invalid page');
 
-  const params = getVerseRecitationsOptions(options);
+  const params = mergeApiOptions(options, defaultVerseRecitationsOptions);
   const data = await fetcher<{
     audioFiles: VerseRecitation[];
     pagination: Pagination;
-  }>(`/recitations/${recitationId}/by_page/${page}`, params);
+  }>(`/recitations/${recitationId}/by_page/${page}`, params, options?.fetchFn);
 
   return data;
 };
@@ -193,11 +173,11 @@ const findVerseRecitationsByRub = async (
 ) => {
   if (!Utils.isValidRub(rub)) throw new Error('Invalid rub');
 
-  const params = getVerseRecitationsOptions(options);
+  const params = mergeApiOptions(options, defaultVerseRecitationsOptions);
   const data = await fetcher<{
     audioFiles: VerseRecitation[];
     pagination: Pagination;
-  }>(`/recitations/${recitationId}/by_rub/${rub}`, params);
+  }>(`/recitations/${recitationId}/by_rub/${rub}`, params, options?.fetchFn);
 
   return data;
 };
@@ -218,11 +198,11 @@ const findVerseRecitationsByHizb = async (
 ) => {
   if (!Utils.isValidHizb(hizb)) throw new Error('Invalid hizb');
 
-  const params = getVerseRecitationsOptions(options);
+  const params = mergeApiOptions(options, defaultVerseRecitationsOptions);
   const data = await fetcher<{
     audioFiles: VerseRecitation[];
     pagination: Pagination;
-  }>(`/recitations/${recitationId}/by_hizb/${hizb}`, params);
+  }>(`/recitations/${recitationId}/by_hizb/${hizb}`, params, options?.fetchFn);
 
   return data;
 };
@@ -243,11 +223,11 @@ const findVerseRecitationsByKey = async (
 ) => {
   if (!Utils.isValidVerseKey(key)) throw new Error('Invalid verse key');
 
-  const params = getVerseRecitationsOptions(options);
+  const params = mergeApiOptions(options, defaultVerseRecitationsOptions);
   const data = await fetcher<{
     audioFiles: VerseRecitation[];
     pagination: Pagination;
-  }>(`/recitations/${recitationId}/by_ayah/${key}`, params);
+  }>(`/recitations/${recitationId}/by_ayah/${key}`, params, options?.fetchFn);
 
   return data;
 };

src/sdk/v4/chapters.ts

@@ -1,20 +1,14 @@
 import { Chapter, ChapterId, ChapterInfo, Language } from '../../types';
-import { fetcher } from './_fetcher';
+import { fetcher, mergeApiOptions } from './_fetcher';
 import Utils from '../utils';
+import { BaseApiOptions } from '../../types/BaseApiOptions';
 
-type GetChapterOptions = Partial<{
-  language: Language;
-}>;
+type GetChapterOptions = Partial<BaseApiOptions>;
 
 const defaultOptions: GetChapterOptions = {
   language: Language.ARABIC,
 };
 
-const getChapterOptions = (options: GetChapterOptions = {}) => {
-  const final: any = { ...defaultOptions, ...options };
-  return final;
-};
-
 /**
  * Get all chapters.
  * @description https://quran.api-docs.io/v4/chapters/list-chapters
@@ -23,10 +17,11 @@ const getChapterOptions = (options: GetChapterOptions = {}) => {
  * quran.v4.chapters.findAll()
  */
 const findAll = async (options?: GetChapterOptions) => {
-  const params = getChapterOptions(options);
+  const params = mergeApiOptions(options, defaultOptions);
   const { chapters } = await fetcher<{ chapters: Chapter[] }>(
     '/chapters',
-    params
+    params,
+    options?.fetchFn
   );
 
   return chapters;
@@ -44,10 +39,11 @@ const findAll = async (options?: GetChapterOptions) => {
 const findById = async (id: ChapterId, options?: GetChapterOptions) => {
   if (!Utils.isValidChapterId(id)) throw new Error('Invalid chapter id');
 
-  const params = getChapterOptions(options);
+  const params = mergeApiOptions(options, defaultOptions);
   const { chapter } = await fetcher<{ chapter: Chapter }>(
     `/chapters/${id}`,
-    params
+    params,
+    options?.fetchFn
   );
 
   return chapter;
@@ -65,10 +61,11 @@ const findById = async (id: ChapterId, options?: GetChapterOptions) => {
 const findInfoById = async (id: ChapterId, options?: GetChapterOptions) => {
   if (!Utils.isValidChapterId(id)) throw new Error('Invalid chapter id');
 
-  const params = getChapterOptions(options);
+  const params = mergeApiOptions(options, defaultOptions);
   const { chapterInfo } = await fetcher<{ chapterInfo: ChapterInfo }>(
     `/chapters/${id}/info`,
-    params
+    params,
+    options?.fetchFn
   );
 
   return chapterInfo;

src/sdk/v4/juzs.ts

@@ -1,4 +1,5 @@
 import { Juz } from '../../types';
+import { BaseApiOptions } from '../../types/BaseApiOptions';
 import { fetcher } from './_fetcher';
 
 /**
@@ -7,8 +8,12 @@ import { fetcher } from './_fetcher';
  * @example
  * quran.v4.juzs.findAll()
  */
-const findAll = async () => {
-  const { juzs } = await fetcher<{ juzs: Juz[] }>('/juzs');
+const findAll = async (options?: Omit<BaseApiOptions, 'language'>) => {
+  const { juzs } = await fetcher<{ juzs: Juz[] }>(
+    '/juzs',
+    undefined,
+    options?.fetchFn
+  );
   return juzs;
 };