rebase with verbose domain check changes

src/helpers/index.js

@@ -8,13 +8,6 @@ import {
 
 // Shared type definitions to be used across different files
 
-/**
- * @typedef {Object} DomainCheckOptions options to control the behavior when checking a domain
- * @property {string} userAgentIdentifier - Optional. The app, site, or organisation that is making the request.
- * @property {boolean} verbose - Optional. Whether to return a verbose response.
- * @property {string[]} db - Optional. A database list to use for lookups.
- */
-
 /**
  * @param {number} num
  */

src/hosting-api.js

@@ -6,17 +6,17 @@ import hostingJSON from "./hosting-json.js";
 /**
  * Check if a string or array of domains is hosted by a green web host by querying the Green Web Foundation API.
  * @param {string | string[]} domain - The domain to check, or an array of domains to be checked.
- * @param {string | DomainCheckOptions} optionsOrAgentId - Optional. An object of domain check options, or a string
+ * @param {(string | DomainCheckOptions)=} optionsOrAgentId - Optional. An object of domain check options, or a string
  *   representing the app, site, or organisation that is making the request.
  */
-
 function check(domain, optionsOrAgentId) {
+  /** @type DomainCheckOptions | undefined */
   const options =
     typeof optionsOrAgentId === "string"
       ? { userAgentIdentifier: optionsOrAgentId }
       : optionsOrAgentId;
 
-  if (options?.db && options.verbose) {
+  if (options?.db && options?.verbose) {
     throw new Error("verbose mode cannot be used with a local lookup database");
   }
   // is it a single domain or an array of them?
@@ -30,8 +30,8 @@ function check(domain, optionsOrAgentId) {
 /**
  * Check if a domain is hosted by a green web host by querying the Green Web Foundation API.
  * @param {string} domain - The domain to check.
- * @param {DomainCheckOptions} options
- * @returns {Promise<boolean>} - A boolean indicating whether the domain is hosted by a green web host if `options.verbose` is false,
+ * @param {DomainCheckOptions=} options
+ * @returns {Promise<boolean | PerDomainCheckResponse>} - A boolean indicating whether the domain is hosted by a green web host if `options.verbose` is false,
  *   otherwise an object representing the domain host information.
  */
 async function checkAgainstAPI(domain, options = {}) {
@@ -42,17 +42,20 @@ async function checkAgainstAPI(domain, options = {}) {
     }
   );
   if (options?.db) {
-    return hostingJSON.check(domain, options.db);
+    return hostingJSON
+      .check(domain, options.db)
+      .then((res) => (Array.isArray(res) ? res.length > 0 : res));
   }
+  /** @type {PerDomainCheckResponse} */
   const res = await req.json();
   return options.verbose ? res : res.green;
 }
 
 /**
  * Check if an array of domains is hosted by a green web host by querying the Green Web Foundation API.
  * @param {string[]} domains - An array of domains to check.
- * @param {DomainCheckOptions} options
- * @returns {Promise<string[]>} - An array of domains that are hosted by a green web host if `options.verbose` is false,
+ * @param {DomainCheckOptions=} options
+ * @returns {Promise<string[] | MultiDomainCheckResponse>} - An array of domains that are hosted by a green web host if `options.verbose` is false,
  *   otherwise a dictionary of domain to host information.
  */
 

src/hosting-api.test.js

@@ -43,6 +43,7 @@ describe("hostingAPI", () => {
       expect(res).toEqual(true);
     });
     it("handles the verbose=true option", async () => {
+      // @ts-ignore
       fetch.mockImplementation(() =>
         Promise.resolve({
           json: () =>
@@ -100,6 +101,7 @@ describe("hostingAPI", () => {
       expect(res).toContain("google.com");
     });
     it("handles the verbose=true option", async () => {
+      // @ts-ignore
       fetch.mockImplementation(() =>
         Promise.resolve({
           json: () =>

src/hosting-json.js

@@ -2,7 +2,8 @@
 
 /**
  * Check if a string or array of domains has been provided
- * @param {string|array} domain - The domain to check, or an array of domains to be checked.
+ * @param {string | string[]} domain - The domain to check, or an array of domains to be checked.
+ * @param {string[]} db - The database to check against.
  */
 async function check(domain, db) {
   // is it a single domain or an array of them?
@@ -16,7 +17,7 @@ async function check(domain, db) {
 /**
  * Check if a domain is hosted by a green web host by querying the database.
  * @param {string} domain - The domain to check.
- * @param {object} db - The database to check against.
+ * @param {string[]} db - The database to check against.
  * @returns {boolean} - A boolean indicating whether the domain is hosted by a green web host.
  */
 function checkInJSON(domain, db) {
@@ -29,20 +30,20 @@ function checkInJSON(domain, db) {
 /**
  * Extract the green domains from the results of a green check.
  * @param {object} greenResults - The results of a green check.
- * @returns {array} - An array of domains that are hosted by a green web host.
+ * @returns {string[]} - An array of domains that are hosted by a green web host.
  */
 function greenDomainsFromResults(greenResults) {
   const entries = Object.entries(greenResults);
-  const greenEntries = entries.filter(([key, val]) => val.green);
+  const greenEntries = entries.filter(([_, val]) => val.green);
 
-  return greenEntries.map(([key, val]) => val.url);
+  return greenEntries.map(([_, val]) => val.url);
 }
 
 /**
  * Check if an array of domains is hosted by a green web host by querying the database.
- * @param {array} domains - An array of domains to check.
- * @param {object} db - The database to check against.
- * @returns {array} - An array of domains that are hosted by a green web host.
+ * @param {string[]} domains - An array of domains to check.
+ * @param {string[]} db - The database to check against.
+ * @returns {string[]} - An array of domains that are hosted by a green web host.
  */
 function checkDomainsInJSON(domains, db) {
   let greenDomains = [];
@@ -57,7 +58,8 @@ function checkDomainsInJSON(domains, db) {
 
 /**
  * Find the provided information a string or array of domains
- * @param {string|array} domain - The domain to check, or an array of domains to be checked.
+ * @param {string | string[]} domain - The domain to check, or an array of domains to be checked.
+ * @param {string[]} db - The database to check against.
  */
 function find(domain, db) {
   // is it a single domain or an array of them?
@@ -71,12 +73,15 @@ function find(domain, db) {
 /**
  * Check if a domain is hosted by a green web host by querying the database.
  * @param {string} domain - The domain to check.
- * @param {object} db - The database to check against.
- * @returns {object} - An object representing the domain provided host information.
+ * @param {string[]} db - The database to check against.
+ * @returns {PerDomainCheckResponse} - An object representing the domain provided host information.
  */
 function findInJSON(domain, db) {
   if (db.indexOf(domain) > -1) {
-    return domain;
+    return {
+      url: domain,
+      green: true,
+    };
   }
   return {
     url: domain,
@@ -86,11 +91,12 @@ function findInJSON(domain, db) {
 
 /**
  * Check if an array of domains is hosted by a green web host by querying the database.
- * @param {array} domains - An array of domains to check.
- * @param {object} db - The database to check against.
- * @returns {array} - A dictionary of domain to provided host information.
+ * @param {string[]} domains - An array of domains to check.
+ * @param {string[]} db - The database to check against.
+ * @returns {MultiDomainCheckResponse} - A dictionary of domain to provided host information.
  */
 function findDomainsInJSON(domains, db) {
+  /** @type {MultiDomainCheckResponse} */
   const result = {};
   for (let domain of domains) {
     result[domain] = findInJSON(domain, db);

src/hosting-json.node.js

@@ -49,63 +49,6 @@ async function loadJSON(jsonPath) {
   return JSON.parse(jsonBuffer.toString());
 }
 
-/**
- * Check if a string or array of domains has been provided
- * @param {string|string[]} domain - The domain to check, or an array of domains to be checked.
- * @param {string[]} db - The domain to check, or an array of domains to be checked.
- */
-async function check(domain, db) {
-  // is it a single domain or an array of them?
-  if (typeof domain === "string") {
-    return checkInJSON(domain, db);
-  } else {
-    return checkDomainsInJSON(domain, db);
-  }
-}
-
-/**
- * Check if a domain is hosted by a green web host by querying the database.
- * @param {string} domain - The domain to check.
- * @param {string[]} db - The database to check against.
- * @returns {boolean} - A boolean indicating whether the domain is hosted by a green web host.
- */
-function checkInJSON(domain, db) {
-  if (db.indexOf(domain) > -1) {
-    return true;
-  }
-  return false;
-}
-
-/**
- * Extract the green domains from the results of a green check.
- * @param {MultiDomainCheckResponse} greenResults - The results of a green check.
- * @returns {string[]} - An array of domains that are hosted by a green web host.
- */
-function greenDomainsFromResults(greenResults) {
-  const entries = Object.entries(greenResults);
-  const greenEntries = entries.filter(([, val]) => val.green);
-
-  return greenEntries.map(([, val]) => val.url);
-}
-
-/**
- * Check if an array of domains is hosted by a green web host by querying the database.
- * @param {string[]} domains - An array of domains to check.
- * @param {string[]} db - The database to check against.
- * @returns {string[]} - An array of domains that are hosted by a green web host.
- */
-function checkDomainsInJSON(domains, db) {
-  let greenDomains = [];
-
-  for (let domain of domains) {
-    if (db.indexOf(domain) > -1) {
-      greenDomains.push(domain);
-    }
-  }
-  return greenDomains;
-}
-
 export default {
-  check,
   loadJSON,
 };

src/hosting-node.js

@@ -53,9 +53,9 @@ async function getBody(url, userAgentIdentifier) {
 /**
  * Check if a domain is hosted by a green web host.
  * @param {string | string[]} domain - The domain to check, or an array of domains to be checked.
- * @param {string[] | DomainCheckOptions} optionsOrDb - Optional. An object of domain check options, or a database list to use for lookups.
+ * @param {(string[] | DomainCheckOptions)=} optionsOrDb - Optional. An object of domain check options, or a database list to use for lookups.
  * @param {string=} userAgentIdentifier - Optional. The app, site, or organisation that is making the request.
- * @returns {Promise<boolean | string[]>} - A boolean if a string was provided, or an array of booleans if an array of domains was provided.
+ * @returns {Promise<boolean | string[] | MultiDomainCheckResponse>} - A boolean if a string was provided, or an array of booleans if an array of domains was provided.
  *   if a string was provided for `domain`: a boolean indicating whether the domain is hosted by a green web host if `options.verbose` is false,
  *     otherwise an object representing the domain host information.
  *   if an array was provided for `domain`: an array of domains that are hosted by a green web host if `options.verbose` is false,
@@ -64,8 +64,9 @@ async function getBody(url, userAgentIdentifier) {
 
 function check(domain, optionsOrDb, userAgentIdentifier) {
   let db,
+    /** @type {DomainCheckOptions | undefined} */
     options = {};
-  if (!db && Array.isArray(optionsOrDb)) {
+  if (Array.isArray(optionsOrDb)) {
     db = optionsOrDb;
   } else {
     options = optionsOrDb;
@@ -112,7 +113,7 @@ async function checkAgainstAPI(domain, options = {}) {
  * Check if an array of domains is hosted by a green web host by querying the Green Web Foundation API.
  * @param {string[]} domains - An array of domains to check.
  * @param {DomainCheckOptions} options
- * @returns {Promise<string[]>} - An array of domains that are hosted by a green web host if `options.verbose` is false,
+ * @returns {Promise<string[] | MultiDomainCheckResponse>} - An array of domains that are hosted by a green web host if `options.verbose` is false,
  * otherwise a dictionary of domain to host information.
  */
 async function checkDomainsAgainstAPI(domains, options = {}) {

src/hosting.js

@@ -7,7 +7,7 @@ import hostingAPI from "./hosting-api.js";
  * @param {string | string[]} domain - The domain to check, or an array of domains to be checked.
  * @param {string} optionsOrAgentId - Optional. An object of domain check options, or a string
  *   representing the app, site, or organisation that is making the request.
- * @returns {Promise<boolean | string[]>} - A boolean if a string was provided, or an array of booleans if an array of domains was provided.
+ * @returns {Promise<boolean | string[] | PerDomainCheckResponse | MultiDomainCheckResponse>} - A boolean if a string was provided, or an array of booleans if an array of domains was provided.
  *   if a string was provided for `domain`: a boolean indicating whether the domain is hosted by a green web host if `options.verbose` is false,
  *     otherwise an object representing the domain host information.
  *   if an array was provided for `domain`: an array of domains that are hosted by a green web host if `options.verbose` is false,

src/hosting.test.js

@@ -44,17 +44,6 @@ describe("hosting", () => {
       );
 
       expect(greenDomains).toHaveLength(2);
-    });
-    it("fails if verbose=true is set", async () => {
-      const db = await hosting.loadJSON(jsonPath);
-      await expect(() => {
-        hosting.check(
-          ["www.thegreenwebfoundation.org", "fonts.googleapis.com"],
-          { verbose: true, db }
-        );
-      }).toThrowError(
-        "verbose mode cannot be used with a local lookup database"
-      );
       const expectedGreendomains = [
         "www.thegreenwebfoundation.org",
         "fonts.googleapis.com",
@@ -64,6 +53,15 @@ describe("hosting", () => {
         expect(expectedGreendomains).toContain(dom);
       });
     });
+    it("fails if verbose=true is set", async () => {
+      const db = await hosting.loadJSON(jsonPath);
+      await expect(() => {
+        hosting.check(
+          ["www.thegreenwebfoundation.org", "fonts.googleapis.com"],
+          { verbose: true, db }
+        );
+      }).toThrow("verbose mode cannot be used with a local lookup database");
+    });
   });
   describe("checking a single domain with #check", () => {
     it("use the API instead", async () => {
@@ -95,7 +93,7 @@ describe("hosting", () => {
       );
     });
     it("sets the correct user agent header when passed as a parameter", async () => {
-      await hosting.check("google.com", null, requestHeaderComment);
+      await hosting.check("google.com", undefined, requestHeaderComment);
       expect(httpsGetSpy).toHaveBeenCalledTimes(1);
       expect(httpsGetSpy).toHaveBeenLastCalledWith(
         expect.any(String),

src/types.js

@@ -131,9 +131,16 @@
  * @property {number} co2
  * @property {number} transferSize
  *
+ * @typedef DomainCheckOptions options to control the behavior when checking a domain
+ * @property {string=} userAgentIdentifier - Optional. The app, site, or organisation that is making the request.
+ * @property {boolean=} verbose - Optional. Whether to return a verbose response.
+ * @property {string[]=} db - Optional. A database list to use for lookups.
+ *
  * @typedef PerDomainCheckResponse
  * @property {string} url
  * @property {boolean} green
+ * @property {string=} hosted_by
+ * @property {string=} hosted_by_website
  *
  * @typedef MultiDomainCheckResponse
  * @type {Record<string, PerDomainCheckResponse>}