refactor: improve telemetry types (#5942)

Author: Lukas Holzer

src/utils/proxy.mjs

@@ -75,19 +75,35 @@ const formatEdgeFunctionError = (errorBuffer, acceptsHtml) => {
   })
 }
 
-const isInternal = function (url) {
+/**
+ * @param {string} url
+ */
+function isInternal(url) {
   return url.startsWith('/.netlify/')
 }
-const isFunction = function (functionsPort, url) {
+
+/**
+ * @param {boolean|number|undefined} functionsPort
+ * @param {string} url
+ */
+function isFunction(functionsPort, url) {
   return functionsPort && url.match(/^\/.netlify\/(functions|builders)\/.+/)
 }
 
-const getAddonUrl = function (addonsUrls, req) {
-  const matches = req.url.match(/^\/.netlify\/([^/]+)(\/.*)/)
+/**
+ * @param {Record<string, string>} addonsUrls
+ * @param {http.IncomingMessage} req
+ */
+function getAddonUrl(addonsUrls, req) {
+  const matches = req.url?.match(/^\/.netlify\/([^/]+)(\/.*)/)
   const addonUrl = matches && addonsUrls[matches[1]]
   return addonUrl ? `${addonUrl}${matches[2]}` : null
 }
 
+/**
+ * @param {string} pathname
+ * @param {string} publicFolder
+ */
 const getStatic = async function (pathname, publicFolder) {
   const alternatives = [pathname, ...alternativePathsFor(pathname)].map((filePath) =>
     path.resolve(publicFolder, filePath.slice(1)),

src/utils/telemetry/telemetry.mjs

@@ -13,14 +13,18 @@ import isValidEventName from './validation.mjs'
 
 const dirPath = dirname(fileURLToPath(import.meta.url))
 
-const send = function (type, payload) {
+/**
+ * @param {'track' | 'identify'} type
+ * @param {object} payload
+ */
+function send(type, payload) {
   const requestFile = join(dirPath, 'request.mjs')
   const options = JSON.stringify({
     data: payload,
     type,
   })
 
-  const args = [process.execPath, [requestFile, options]]
+  const args = /** @type {const} */ ([process.execPath, [requestFile, options]])
   if (process.env.NETLIFY_TEST_TELEMETRY_WAIT === 'true') {
     return execa(...args, {
       stdio: 'inherit',
@@ -46,7 +50,12 @@ const eventConfig = {
   ],
 }
 
-export const track = async function (eventName, payload = {}) {
+/**
+ * Tracks a custom event with the provided payload
+ * @param {string} eventName
+ * @param {{status?: string, duration?: number, [key: string]: unknown}} [payload]
+ */
+export async function track(eventName, payload = {}) {
   if (isCI) {
     return
   }
@@ -83,7 +92,14 @@ export const track = async function (eventName, payload = {}) {
   return send('track', defaultData)
 }
 
-export const identify = async function (payload) {
+/**
+ * @param {object} payload
+ * @param {string} payload.name
+ * @param {string} payload.email
+ * @param {string} payload.userId
+ * @returns
+ */
+export async function identify(payload) {
   if (isCI) {
     return
   }

src/utils/validation.mjs

@@ -1,6 +1,10 @@
 // @ts-check
 import { BANG, chalk } from './command-helpers.mjs'
 
+/**
+ * @param {string} exampleCommand
+ * @returns {(value:string, previous: unknown) => unknown}
+ */
 export const getGeoCountryArgParser = (exampleCommand) => (arg) => {
   // Validate that the arg passed is two letters only for country
   // See https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes