diff --git a/src/helpers/index.js b/src/helpers/index.js index 0861314..321faf9 100644 --- a/src/helpers/index.js +++ b/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 */ diff --git a/src/hosting-api.js b/src/hosting-api.js index 008a4a6..b143a93 100644 --- a/src/hosting-api.js +++ b/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} - A boolean indicating whether the domain is hosted by a green web host if `options.verbose` is false, + * @param {DomainCheckOptions=} options + * @returns {Promise} - 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,8 +42,11 @@ 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; } @@ -51,8 +54,8 @@ 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} - An array of domains that are hosted by a green web host if `options.verbose` is false, + * @param {DomainCheckOptions=} options + * @returns {Promise} - 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. */ diff --git a/src/hosting-api.test.js b/src/hosting-api.test.js index 5337460..edced56 100644 --- a/src/hosting-api.test.js +++ b/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: () => diff --git a/src/hosting-json.js b/src/hosting-json.js index 46aaf51..38e91ff 100644 --- a/src/hosting-json.js +++ b/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); diff --git a/src/hosting-json.node.js b/src/hosting-json.node.js index c891307..1d8cbfd 100644 --- a/src/hosting-json.node.js +++ b/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, }; diff --git a/src/hosting-node.js b/src/hosting-node.js index 9042e00..acaa4cd 100644 --- a/src/hosting-node.js +++ b/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} - A boolean if a string was provided, or an array of booleans if an array of domains was provided. + * @returns {Promise} - 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} - An array of domains that are hosted by a green web host if `options.verbose` is false, + * @returns {Promise} - 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 = {}) { diff --git a/src/hosting.js b/src/hosting.js index 2008ef6..8783c60 100644 --- a/src/hosting.js +++ b/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} - A boolean if a string was provided, or an array of booleans if an array of domains was provided. + * @returns {Promise} - 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, diff --git a/src/hosting.test.js b/src/hosting.test.js index 80bdda6..ab9d48e 100644 --- a/src/hosting.test.js +++ b/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), diff --git a/src/types.js b/src/types.js index 45f9909..9147998 100644 --- a/src/types.js +++ b/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}