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

fixes thegreenwebfoundation#199

package.json

@@ -18,11 +18,13 @@
     "test:watch": "jest --watch src",
     "lint": "eslint src",
     "lint:fix": "eslint src --fix",
+    "check:types": "tsc --noEmit",
     "serve": "python -m http.server --directory ./public",
     "build": "npm run build:esm && npm run build:browser && npm run build:node",
     "build:esm": "node .esbuild.esm.js && ./fixup",
     "build:browser": "node .esbuild.browser.js",
     "build:node": "node .esbuild.node.js && ./fixup",
+    "emit:types": "tsc --emitDeclarationOnly --outDir dist/",
     "release:minor": "npm run build && npm run intensity-data && npm run format-data && np minor",
     "release:patch": "npm run build && npm run intensity-data && npm run format-data && np patch",
     "gitpod": "npm run build && cp ./dist/iife/index.js ./public && npm run serve",
@@ -45,6 +47,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",
@@ -57,7 +60,8 @@
     "nock": "^13.2.4",
     "np": "^8.0.4",
     "pagexray": "^4.4.2",
-    "prettier": "^2.6.2"
+    "prettier": "^2.6.2",
+    "typescript": "^5.4.2"
   },
   "jest": {
     "transform": {
@@ -76,4 +80,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,11 @@
+{
+    "extends": "@tsconfig/strictest/tsconfig.json",
+    "include": ["src/**/*"],
+    "compilerOptions": {
+        "strict": true,
+        "allowJs": true,
+        "checkJs": true,
+        "emitDeclarationOnly": true,
+        "declaration": true
+    }
+}