From 9cf1090b589963839028542eeecdfd3823df7ef4 Mon Sep 17 00:00:00 2001
From: Franklin <fr@nkl.in>
Date: Sat, 16 Dec 2023 14:05:25 +0100
Subject: [PATCH] Feature: Added config param `throwEmpty`

- Default is `true`
- Set to `false` to return an empty array instead of throwing error 'no results'
---
 README.md       | 26 +++++++++++++++++++-------
 searchitunes.js | 15 +++++++++++----
 test.js         | 28 ++++++++++++++++++++++++++--
 3 files changed, 56 insertions(+), 13 deletions(-)

diff --git a/README.md b/README.md
index e7670ea..a3dd49a 100644
--- a/README.md
+++ b/README.md
@@ -49,11 +49,12 @@ It returns a Promise.
 The parameters below can be included along with the
 normal API params.
 
-param       | type   | default         | description
-:-----------|:-------|:----------------|:-----------
-[timeout]   | number | 5000            | Wait time out in ms
-[userAgent] | string | searchitunes.js | User-Agent header
-...         | mixed  |                 | API parameters
+param        | type   | default         | description
+:------------|:-------|:----------------|:-----------
+[timeout]    | number | 5000            | Wait time out in ms
+[userAgent]  | string | searchitunes.js | User-Agent header
+[throwEmpty] | bool   | true            | Throw `no results` instead of returning `[]`
+...          | mixed  |                 | API parameters
 
 ```js
 itunes( {
@@ -120,10 +121,21 @@ searchitunes( { id: [ 123, 789 ] } )
 
 ## Errors
 
-API errors are handled and thrown, prefixed with `API: `.
+API errors are handled and thrown, prefixed with `API: `
 
-When nothing is found it will throw with message `no results`.
+When nothing is found it will throw with `no results` message. You can prevent
+this behavior by setting `throwEmpty` to `false` to return an empty array.
 
+```js
+searchitunes( {
+  throwEmpty: false,
+  entity: 'software',
+  term: 'github',
+} )
+  .then( console.log )
+  .catch( console.error )
+;
+```
 
 
 ## Unlicense
diff --git a/searchitunes.js b/searchitunes.js
index 6ca9722..9c8d227 100644
--- a/searchitunes.js
+++ b/searchitunes.js
@@ -12,15 +12,17 @@ License:      Unlicense (Public Domain, see UNLICENSE file)
  *
  * @return  {Promise<object|array>}
  *
- * @param   {object}  params                 Parameters to send along
- * @param   {number}  [params.timeout=5000]  Wait timeout in ms
- * @param   {string}  [params.userAgent]     Custom User-Agent header
+ * @param   {object}  params                    Parameters to send along
+ * @param   {number}  [params.timeout=5000]     Wait timeout in ms
+ * @param   {string}  [params.userAgent]        Custom User-Agent header
+ * @param   {bool}    [params.throwEmpty=true]  Throw 'no results' instead of returning an empty array
  */
 
 module.exports = async function SearchItunes ( {
 
   timeout = 5000,
   userAgent = 'searchitunes.js',
+  throwEmpty = true,
   trackId,
 
 } ) {
@@ -38,6 +40,7 @@ module.exports = async function SearchItunes ( {
 
   delete params.timeout;
   delete params.userAgent;
+  delete params.throwEmpty;
 
   // Convert trackId from a search response
   if ( trackId ) {
@@ -90,7 +93,11 @@ module.exports = async function SearchItunes ( {
 
   // Empty result
   if ( ! data.results || ! data.results.length ) {
-    throw new Error( 'no results' );
+    if ( throwEmpty ) {
+      throw new Error( 'no results' );
+    }
+
+    return [];
   }
 
   // Lookup response
diff --git a/test.js b/test.js
index be48133..d09bdbc 100644
--- a/test.js
+++ b/test.js
@@ -21,7 +21,7 @@ dotest.add( 'Interface', test => {
 } );
 
 
-dotest.add( 'Error: no results', async test => {
+dotest.add( 'Error: no results (throwEmpty = true)', async test => {
   let error;
   let data;
 
@@ -203,7 +203,31 @@ dotest.add( 'Default timeout', async test => {
 } );
 
 
-dotest.add( 'API error', async test => {
+dotest.add( 'throwEmpty = false', async test => {
+  let error;
+  let data;
+
+  try {
+    data = await app( {
+      entity: 'software',
+      term: 'SomethingThatShouldNotExistForAPITestingPuposes',
+      throwEmpty: false,
+    } );
+  }
+  catch ( err ) {
+    error = err;
+  }
+
+  test( error )
+    .isArray( 'fail', 'data', data )
+    .isEmpty( 'fail', 'data', data )
+    .isUndefined( 'fail', 'error', error )
+    .done()
+  ;
+} );
+
+
+dotest.add( 'Error: API error', async test => {
   let error;
   let data;