Add comments to basics functionality

Author: georg-schwarz

basics/src/env.ts

@@ -1,5 +1,10 @@
 import { isEmpty } from './validators'
 
+/**
+ * Reads an environment variable, and logs it.
+ * If the environment variable cannot be found, the process is exited (die).
+ * @param envName the name of the environment variable to be read
+ */
 export function readEnvOrDie (envName: string): string {
   const env = process.env[envName]
   if (isEmpty(env)) {

basics/src/index.ts

@@ -1,11 +1,4 @@
-import { sleep } from './sleep'
-import * as validators from './validators'
-import * as stringifiers from './stringifiers'
-import { readEnvOrDie } from './env'
-
-export {
-  sleep,
-  validators,
-  readEnvOrDie,
-  stringifiers
-}
+export { sleep } from './sleep'
+export * as validators from './validators'
+export * as stringifiers from './stringifiers'
+export { readEnvOrDie } from './env'

basics/src/sleep.ts

@@ -1,3 +1,7 @@
+/**
+ * Return promise after given amount of milliseconds. Await the promise to simulate a sleep.
+ * @param ms time in milliseconds
+ */
 export async function sleep (ms: number): Promise<void> {
   return await new Promise<void>(resolve => setTimeout(resolve, ms))
 }

basics/src/stringifiers.ts

@@ -1,10 +1,22 @@
 
+/**
+ * Stringifies an array and cuts out text from elements if it is longer than maxLen.
+ * Can be used for logging to reduce clutter.
+ * @param arg the array of objects to be logged.
+ * @param maxLen if length of stringified arg is longer than maxLen, then we cut it short.
+ */
 export function stringifyArray (args: unknown[], maxLen?: number): string {
   return JSON.stringify(
     args.map(arg => stringify(arg, maxLen))
   )
 }
 
+/**
+ * Stringifies an object and cuts out text if it is longer than maxLen.
+ * Can be used for logging to reduce clutter.
+ * @param arg the object to be logged.
+ * @param maxLen if length of stringified arg is longer than maxLen, then we cut it short.
+ */
 export const stringify = (arg: unknown, maxLen?: number): string => {
   const json = JSON.stringify(arg)
   if (maxLen === undefined || json.length <= maxLen) {

basics/src/validators.ts

@@ -1,19 +1,40 @@
+/**
+ * Type guard checking if x is a number.
+ * @param x
+ */
 export function isNumber (x: unknown): x is number {
   return typeof x === 'number'
 }
 
+/**
+ * Type guard checking if x is a string.
+ * @param x
+ */
 export function isString (x: unknown): x is string {
   return typeof x === 'string'
 }
 
+/**
+ * Type guard checking if value is undefined or empty.
+ * @param value
+ */
 export function isEmpty (value: string | undefined): value is undefined {
   return value === undefined || value === ''
 }
 
+/**
+ * Type guard checking if x is an object.
+ * @param x
+ */
 export function isObject (x: unknown): x is object {
   return typeof x === 'object'
 }
 
+/**
+ * Type guard checking if object has property p.
+ * @param object the object to be checked
+ * @param name name of the property
+ */
 // Helper function to fix issue that `in` operator as type guard is not widening type with the asserted property key
 // See https://github.com/microsoft/TypeScript/issues/21732
 export function hasProperty<P extends PropertyKey, O extends object> (object: O, name: P):