initial commit of tsconfig.json file and some initial jsdoc updates

fixes #199

package.json

@@ -45,6 +45,7 @@
   "license": "Apache-2.0",
   "devDependencies": {
     "@tgwf/url2green": "^0.4.0",
+    "@tsconfig/strictest": "^2.0.3",
     "all-contributors-cli": "^6.26.1",
     "esbuild": "^0.14.47",
     "esbuild-jest": "^0.5.0",
@@ -76,4 +77,4 @@
     "type": "git",
     "url": "https://github.com/thegreenwebfoundation/co2.js.git"
   }
-}
+}

src/helpers/index.js

@@ -176,10 +176,13 @@ function parseOptions(options) {
  * Returns an object containing all the HTTP headers to use when making a request to the Green Web Foundation API.
  * @param {string} comment - Optional. The app, site, or organisation that is making the request.
  *
- * @returns {import('http').OutgoingHttpHeaders}
+ * @returns {Record<string, string>}
  */
 function getApiRequestHeaders(comment = "") {
-  return { "User-Agent": `co2js/${process.env.CO2JS_VERSION} ${comment}` };
+  if (!process.env["CO2JS_VERSION"]) {
+    return {};
+  }
+  return { "User-Agent": `co2js/${process.env["CO2JS_VERSION"]} ${comment}` };
 }
 
 export { formatNumber, parseOptions, getApiRequestHeaders };

src/hosting-api.js

@@ -4,7 +4,7 @@ import { getApiRequestHeaders } from "./helpers/index.js";
 
 /**
  * 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} userAgentIdentifier - Optional. The app, site, or organisation that is making the request.
  */
 
@@ -21,7 +21,7 @@ function check(domain, userAgentIdentifier) {
  * 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 {string} userAgentIdentifier - Optional. The app, site, or organisation that is making the request.
- * @returns {boolean} - A boolean indicating whether the domain is hosted by a green web host.
+ * @returns {Promise<boolean>} - A boolean indicating whether the domain is hosted by a green web host.
  */
 async function checkAgainstAPI(domain, userAgentIdentifier) {
   const req = await fetch(
@@ -36,9 +36,9 @@ async function checkAgainstAPI(domain, userAgentIdentifier) {
 
 /**
  * Check if an array of domains is hosted by a green web host by querying the Green Web Foundation API.
- * @param {array} domains - An array of domains to check.
+ * @param {string[]} domains - An array of domains to check.
  * @param {string} userAgentIdentifier - Optional. The app, site, or organisation that is making the request.
- * @returns {array} - An array of domains that are hosted by a green web host.
+ * @returns {Promise<string[]>} - An array of domains that are hosted by a green web host.
  */
 
 async function checkDomainsAgainstAPI(domains, userAgentIdentifier) {
@@ -61,7 +61,7 @@ async function checkDomainsAgainstAPI(domains, userAgentIdentifier) {
 /**
  * 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);

src/hosting.js

@@ -4,9 +4,9 @@ import hostingAPI from "./hosting-api.js";
 
 /**
  * Check if a domain is hosted by a green web host.
- * @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} userAgentIdentifier - Optional. The app, site, or organisation that is making the request.
- * @returns {boolean|array} - A boolean if a string was provided, or an array of booleans if an array of domains was provided.
+ * @returns {Promise<boolean | string[]>} - A boolean if a string was provided, or an array of strings if an array of domains was provided.
  */
 function check(domain, userAgentIdentifier) {
   return hostingAPI.check(domain, userAgentIdentifier);

tsconfig.json

@@ -0,0 +1,10 @@
+{
+    "extends": "@tsconfig/strictest/tsconfig.json",
+    "include": ["src/**/*"],
+    "compilerOptions": {
+        "noEmit": true,
+        "strict": true,
+        "allowJs": true,
+        "checkJs": true,
+    }
+}