docs: add types to runtime

License: MIT
Signed-off-by: Henrique Dias <hacdias@gmail.com>

.eslintrc

@@ -0,0 +1,3 @@
+{
+  "extends": "ipfs"
+}

package.json

@@ -16,7 +16,16 @@
     "src",
     "dist"
   ],
+  "types": "dist/src/index.d.ts",
   "main": "src/index.js",
+  "typesVersions": {
+    "*": {
+      "src/*": [
+        "dist/src/*",
+        "dist/src/*/index"
+      ]
+    }
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/testground/sdk-js.git"
@@ -30,24 +39,15 @@
     "test:browser": "aegir test --target browser"
   },
   "dependencies": {
-    "ioredis": "^4.19.2",
+    "ioredis": "^4.19.4",
     "ipaddr.js": "^2.0.0",
     "lodash.flatten": "^4.4.0",
     "winston": "^3.3.3"
   },
   "devDependencies": {
-    "aegir": "^29.2.2"
+    "aegir": "^30.0.1"
   },
   "engines": {
     "node": ">=12.0.0"
-  },
-  "types": "dist/src/index.d.ts",
-  "typesVersions": {
-    "*": {
-      "src/*": [
-        "dist/src/*",
-        "dist/src/*/index"
-      ]
-    }
   }
 }

src/runtime/events.js

@@ -1,6 +1,20 @@
 'use strict'
 
-function newEvents ({ logger, runParams, getSignalEmitter }) {
+/** @typedef {import('./types').RunParams} RunParams */
+/** @typedef {import('./types').SignalEmitter} SignalEmitter */
+/** @typedef {import('./types').Events} Events */
+/** @typedef {import('winston').Logger} Logger */
+
+/**
+ * @param {RunParams} runParams
+ * @param {Logger} logger
+ * @param {function():SignalEmitter|null} getSignalEmitter
+ * @returns {Events}
+ */
+function newEvents (runParams, logger, getSignalEmitter) {
+  /**
+   * @param {Object} event
+   */
   const emitEvent = async (event) => {
     const signalEmitter = getSignalEmitter()
 
@@ -38,7 +52,7 @@ function newEvents ({ logger, runParams, getSignalEmitter }) {
     recordSuccess: () => {
       const event = {
         success_event: {
-          group: runParams.testGroupID
+          group: runParams.testGroupId
         }
       }
 
@@ -49,7 +63,7 @@ function newEvents ({ logger, runParams, getSignalEmitter }) {
     recordFailure: (err) => {
       const event = {
         failure_event: {
-          group: runParams.testGroupID,
+          group: runParams.testGroupId,
           error: err.toString()
         }
       }
@@ -61,7 +75,7 @@ function newEvents ({ logger, runParams, getSignalEmitter }) {
     recordCrash: (err) => {
       const event = {
         crash_event: {
-          group: runParams.testGroupID,
+          group: runParams.testGroupId,
           error: err.toString(),
           stacktrace: err.stack
         }

src/runtime/index.js

@@ -4,28 +4,47 @@ const { getLogger } = require('./logger')
 const { newEvents } = require('./events')
 const { parseRunParams } = require('./params')
 
+/** @typedef {import('./types').RunParams} RunParams */
+/** @typedef {import('./types').SignalEmitter} SignalEmitter */
+/** @typedef {import('./types').RunEnv} RunEnv */
+
+/**
+ * Creates a runtime environment from the environment variables.
+ *
+ * @returns {RunEnv}
+ */
 function currentRunEnv () {
   return parseRunEnv(process.env)
 }
 
+/**
+ * Creates a runtime environment from the provided list of variables.
+ *
+ * @param {Record<string, string|undefined>} env
+ */
 function parseRunEnv (env) {
   const p = parseRunParams(env)
   return newRunEnv(p)
 }
 
+/**
+ * Creates a runtime environment from the given runtime parameters.
+ *
+ * @param {RunParams} params
+ * @returns {RunEnv}
+ */
 function newRunEnv (params) {
-  let signalEmitter = null
+  let signalEmitter = /** @type {SignalEmitter|null} */(null)
 
-  const options = {
-    runParams: params,
-    logger: getLogger(params),
-    getSignalEmitter: () => signalEmitter
-  }
+  const getSignalEmitter = () => signalEmitter
+  const logger = getLogger(params)
 
   return {
     ...params,
-    ...options,
-    ...newEvents(options),
+    ...newEvents(params, logger, getSignalEmitter),
+    logger: logger,
+    runParams: params,
+    getSignalEmitter: getSignalEmitter,
     setSignalEmitter: (e) => { signalEmitter = e }
   }
 }

src/runtime/logger.js

@@ -3,6 +3,10 @@
 const winston = require('winston')
 const path = require('path')
 
+/**
+ * @param {import('./params').RunParams} params
+ * @returns {winston.Logger}
+ */
 function getLogger (params) {
   const format = winston.format.combine(
     winston.format((info, opts = {}) => {

src/runtime/params.js

@@ -2,6 +2,8 @@
 
 const ipaddr = require('ipaddr.js')
 
+/** @typedef {import('./types').RunParams} RunParams */
+
 const ENV_TEST_BRANCH = 'TEST_BRANCH'
 const ENV_TEST_CASE = 'TEST_CASE'
 const ENV_TEST_GROUP_ID = 'TEST_GROUP_ID'
@@ -18,24 +20,28 @@ const ENV_TEST_START_TIME = 'TEST_START_TIME'
 const ENV_TEST_SUBNET = 'TEST_SUBNET'
 const ENV_TEST_TAG = 'TEST_TAG'
 
+/**
+ * @param {Record<string, string|undefined>} env
+ * @returns {RunParams}
+ */
 function parseRunParams (env) {
-  const params = {
-    testBranch: env[ENV_TEST_BRANCH],
-    testCase: env[ENV_TEST_CASE],
-    testGroupId: env[ENV_TEST_GROUP_ID],
-    testGroupInstanceCount: Number.parseInt(env[ENV_TEST_GROUP_INSTANCE_COUNT]),
-    testInstanceCount: Number.parseInt(env[ENV_TEST_INSTANCE_COUNT]),
-    testInstanceParams: unpackParams(env[ENV_TEST_INSTANCE_PARAMS]),
-    testInstanceRole: env[ENV_TEST_INSTANCE_ROLE],
-    testOutputsPath: env[ENV_TEST_OUTPUTS_PATH],
-    testPlan: env[ENV_TEST_PLAN],
-    testRepo: env[ENV_TEST_REPO],
-    testRun: env[ENV_TEST_RUN],
-    testSidecar: env[ENV_TEST_SIDECAR] === 'true',
-    testStartTime: Date.parse(ENV_TEST_START_TIME),
-    testSubnet: ipaddr.parseCIDR(env[ENV_TEST_SUBNET]),
-    testTag: env[ENV_TEST_TAG]
-  }
+  const params = /** @type {RunParams} */({})
+
+  params.testBranch = env[ENV_TEST_BRANCH] || ''
+  params.testCase = env[ENV_TEST_CASE] || ''
+  params.testGroupId = env[ENV_TEST_GROUP_ID] || ''
+  params.testGroupInstanceCount = Number.parseInt(env[ENV_TEST_GROUP_INSTANCE_COUNT] || '')
+  params.testInstanceCount = Number.parseInt(env[ENV_TEST_INSTANCE_COUNT] || '')
+  params.testInstanceParams = unpackParams(env[ENV_TEST_INSTANCE_PARAMS] || '')
+  params.testInstanceRole = env[ENV_TEST_INSTANCE_ROLE] || ''
+  params.testOutputsPath = env[ENV_TEST_OUTPUTS_PATH] || ''
+  params.testPlan = env[ENV_TEST_PLAN] || ''
+  params.testRepo = env[ENV_TEST_REPO] || ''
+  params.testRun = env[ENV_TEST_RUN] || ''
+  params.testSidecar = env[ENV_TEST_SIDECAR] === 'true'
+  params.testStartTime = Date.parse(ENV_TEST_START_TIME)
+  params.testSubnet = ipaddr.parseCIDR(env[ENV_TEST_SUBNET] || '')
+  params.testTag = env[ENV_TEST_TAG] || ''
 
   params.toJSON = () => {
     const json = {
@@ -46,17 +52,16 @@ function parseRunParams (env) {
       outputs_path: params.testOutputsPath,
       network: params.testSubnet.toString(),
       group: params.testGroupId,
-      group_instances: params.testGroupInstanceCount
+      group_instances: params.testGroupInstanceCount,
+      repo: '',
+      branch: '',
+      tag: ''
     }
 
     if (params.testRepo) {
       json.repo = params.testRepo
     }
 
-    if (params.testCommit) {
-      json.commit = params.testCommit
-    }
-
     if (params.testBranch) {
       json.branch = params.testBranch
     }
@@ -71,16 +76,19 @@ function parseRunParams (env) {
   return params
 }
 
+/**
+ * @param {string} packed
+ * @returns {Record<string, string>}
+ */
 function unpackParams (packed) {
   const spltparams = packed.split('|')
-  const params = {}
+  const params = /** @type {Record<string, string>} */({})
 
   for (const s of spltparams) {
     const v = s.split('=')
-    if (v.length !== 2) {
-      continue
+    if (v.length === 2) {
+      params[v[0]] = v[1]
     }
-    params[v[0]] = v[1]
   }
 
   return params

src/runtime/types.ts

@@ -0,0 +1,45 @@
+import type { IPv4, IPv6 } from 'ipaddr.js'
+import type { Logger } from 'winston'
+
+export interface RunParams {
+  testBranch: string
+  testCase: string
+  testGroupId: string
+  testGroupInstanceCount: number
+  testInstanceCount: number
+  testInstanceParams: Record<string, string>
+  testInstanceRole: string
+  testOutputsPath: string
+  testPlan: string
+  testRepo: string
+  testRun: string
+  testSidecar: boolean
+  testStartTime: number
+  testSubnet: [IPv4 | IPv6, number]
+  testTag: string
+  toJSON: () => Object
+}
+
+export interface SignalEmitter {
+  signalEvent: (event: Object) => void
+}
+
+export interface Events {
+  /** Records an informational message. */
+  recordMessage: (message: string) => void
+  /** Records that the calling instance started. */
+  recordStart: () => void
+  /** Records that the calling instance succeeded. */
+  recordSuccess: () => void
+  /** Records that the calling instance failed with the supplied error. */
+  recordFailure: (err: Error) => void
+  /** Records that the calling instance crashed with the supplied error. */
+  recordCrash: (err: Error) => void
+}
+
+export interface RunEnv extends Events, RunParams {
+  logger: Logger
+  runParams: RunParams
+  getSignalEmitter: () => SignalEmitter|null
+  setSignalEmitter: (e: SignalEmitter) => void
+}

tsconfig.json

@@ -0,0 +1,10 @@
+{
+    "extends": "./node_modules/aegir/src/config/tsconfig.aegir.json",
+    "compilerOptions": {
+        "outDir": "dist"
+    },
+    "include": [
+      "test", // remove this line if you don't want to type-check tests
+      "src"
+    ]
+}