From c94dcf15335e7c0313ef3236400650ea6b5dcd58 Mon Sep 17 00:00:00 2001 From: Matthew Nickson Date: Thu, 2 Jun 2022 14:32:38 +0100 Subject: [PATCH] Added JSDoc for src/* Signed-off-by: Matthew Nickson --- src/util-frontend.js | 7 ++-- src/util.js | 70 ++++++++++++++++++++++++++++++++++++---- src/util.ts | 76 ++++++++++++++++++++++++++++++++++++++------ 3 files changed, 135 insertions(+), 18 deletions(-) diff --git a/src/util-frontend.js b/src/util-frontend.js index 565b053c4..36dac49f9 100644 --- a/src/util-frontend.js +++ b/src/util-frontend.js @@ -26,8 +26,8 @@ function getTimezoneOffset(timeZone) { /** * Returns a list of timezones sorted by their offset from UTC. -* @param {Array} timezones - An array of timezone objects. -* @returns {Array} A list of the given timezones sorted by their offset from UTC. +* @param {Object[]} timezones An array of timezone objects. +* @returns {Object[]} A list of the given timezones sorted by their offset from UTC. * * Generated by Trelent */ @@ -63,6 +63,7 @@ export function timezoneList() { return result; } +/** Set the locale of the HTML page */ export function setPageLocale() { const html = document.documentElement; html.setAttribute("lang", currentLocale() ); @@ -70,7 +71,9 @@ export function setPageLocale() { } /** + * Get the base URL * Mainly used for dev, because the backend and the frontend are in different ports. + * @returns {string} */ export function getResBaseURL() { const env = process.env.NODE_ENV; diff --git a/src/util.js b/src/util.js index ee6095e08..d5e3617fd 100644 --- a/src/util.js +++ b/src/util.js @@ -18,6 +18,7 @@ exports.PENDING = 2; exports.STATUS_PAGE_ALL_DOWN = 0; exports.STATUS_PAGE_ALL_UP = 1; exports.STATUS_PAGE_PARTIAL_DOWN = 2; +/** Flip the status of s */ function flipStatus(s) { if (s === exports.UP) { return exports.DOWN; @@ -28,6 +29,10 @@ function flipStatus(s) { return s; } exports.flipStatus = flipStatus; +/** + * Delays for specified number of seconds + * @param ms Number of milliseconds to sleep for + */ function sleep(ms) { return new Promise(resolve => setTimeout(resolve, ms)); } @@ -83,6 +88,12 @@ class Logger { this.debug("server", this.hideLog); } } + /** + * Write a message to the log + * @param module The module the log comes from + * @param msg Message to write + * @param level Log level. One of INFO, WARN, ERROR, DEBUG or can be customized. + */ log(module, msg, level) { if (this.hideLog[level] && this.hideLog[level].includes(module)) { return; @@ -109,18 +120,44 @@ class Logger { console.log(formattedMessage); } } + /** + * Log an INFO message + * @param module Module log comes from + * @param msg Message to write + */ info(module, msg) { this.log(module, msg, "info"); } + /** + * Log a WARN message + * @param module Module log comes from + * @param msg Message to write + */ warn(module, msg) { this.log(module, msg, "warn"); } + /** + * Log an ERROR message + * @param module Module log comes from + * @param msg Message to write + */ error(module, msg) { this.log(module, msg, "error"); } + /** + * Log a DEBUG message + * @param module Module log comes from + * @param msg Message to write + */ debug(module, msg) { this.log(module, msg, "debug"); } + /** + * Log an exeption as an ERROR + * @param module Module log comes from + * @param exception The exeption to include + * @param msg The message to write + */ exception(module, exception, msg) { let finalMessage = exception; if (msg) { @@ -130,13 +167,13 @@ class Logger { } } exports.log = new Logger(); +/** + * String.prototype.replaceAll() polyfill + * https://gomakethings.com/how-to-replace-a-section-of-a-string-with-another-one-with-vanilla-js/ + * @author Chris Ferdinandi + * @license MIT + */ function polyfill() { - /** - * String.prototype.replaceAll() polyfill - * https://gomakethings.com/how-to-replace-a-section-of-a-string-with-another-one-with-vanilla-js/ - * @author Chris Ferdinandi - * @license MIT - */ if (!String.prototype.replaceAll) { String.prototype.replaceAll = function (str, newStr) { // If a regex pattern @@ -153,6 +190,10 @@ class TimeLogger { constructor() { this.startTime = dayjs().valueOf(); } + /** + * Output time since start of monitor + * @param name Name of monitor + */ print(name) { if (exports.isDev && process.env.TIMELOGGER === "1") { console.log(name + ": " + (dayjs().valueOf() - this.startTime) + "ms"); @@ -201,6 +242,13 @@ let getRandomBytes = ((typeof window !== 'undefined' && window.crypto) : function () { return require("crypto").randomBytes; })(); +/** + * Get a random integer suitable for use in cryptography between upper + * and lower bounds. + * @param min Minimum value of integer + * @param max Maximum value of integer + * @returns Cryptographically suitable random integer + */ function getCryptoRandomInt(min, max) { // synchronous version of: https://github.com/joepie91/node-random-number-csprng const range = max - min; @@ -231,6 +279,11 @@ function getCryptoRandomInt(min, max) { } } exports.getCryptoRandomInt = getCryptoRandomInt; +/** + * Generate a secret + * @param length Lenght of secret to generate + * @returns + */ function genSecret(length = 64) { let secret = ""; const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789"; @@ -241,6 +294,11 @@ function genSecret(length = 64) { return secret; } exports.genSecret = genSecret; +/** + * Get the path of a monitor + * @param id ID of monitor + * @returns Formatted relative path + */ function getMonitorRelativeURL(id) { return "/dashboard/" + id; } diff --git a/src/util.ts b/src/util.ts index 057090b72..b28ba3c15 100644 --- a/src/util.ts +++ b/src/util.ts @@ -19,7 +19,7 @@ export const STATUS_PAGE_ALL_DOWN = 0; export const STATUS_PAGE_ALL_UP = 1; export const STATUS_PAGE_PARTIAL_DOWN = 2; - +/** Flip the status of s */ export function flipStatus(s: number) { if (s === UP) { return DOWN; @@ -32,6 +32,10 @@ export function flipStatus(s: number) { return s; } +/** + * Delays for specified number of seconds + * @param ms Number of milliseconds to sleep for + */ export function sleep(ms: number) { return new Promise(resolve => setTimeout(resolve, ms)); } @@ -94,6 +98,12 @@ class Logger { } } + /** + * Write a message to the log + * @param module The module the log comes from + * @param msg Message to write + * @param level Log level. One of INFO, WARN, ERROR, DEBUG or can be customized. + */ log(module: string, msg: any, level: string) { if (this.hideLog[level] && this.hideLog[level].includes(module)) { return; @@ -120,22 +130,48 @@ class Logger { } } + /** + * Log an INFO message + * @param module Module log comes from + * @param msg Message to write + */ info(module: string, msg: any) { this.log(module, msg, "info"); } + /** + * Log a WARN message + * @param module Module log comes from + * @param msg Message to write + */ warn(module: string, msg: any) { this.log(module, msg, "warn"); } - error(module: string, msg: any) { + /** + * Log an ERROR message + * @param module Module log comes from + * @param msg Message to write + */ + error(module: string, msg: any) { this.log(module, msg, "error"); } - debug(module: string, msg: any) { + /** + * Log a DEBUG message + * @param module Module log comes from + * @param msg Message to write + */ + debug(module: string, msg: any) { this.log(module, msg, "debug"); } + /** + * Log an exeption as an ERROR + * @param module Module log comes from + * @param exception The exeption to include + * @param msg The message to write + */ exception(module: string, exception: any, msg: any) { let finalMessage = exception @@ -151,13 +187,13 @@ export const log = new Logger(); declare global { interface String { replaceAll(str: string, newStr: string): string; } } +/** + * String.prototype.replaceAll() polyfill + * https://gomakethings.com/how-to-replace-a-section-of-a-string-with-another-one-with-vanilla-js/ + * @author Chris Ferdinandi + * @license MIT + */ export function polyfill() { - /** - * String.prototype.replaceAll() polyfill - * https://gomakethings.com/how-to-replace-a-section-of-a-string-with-another-one-with-vanilla-js/ - * @author Chris Ferdinandi - * @license MIT - */ if (!String.prototype.replaceAll) { String.prototype.replaceAll = function (str: string, newStr: string) { // If a regex pattern @@ -177,7 +213,10 @@ export class TimeLogger { constructor() { this.startTime = dayjs().valueOf(); } - + /** + * Output time since start of monitor + * @param name Name of monitor + */ print(name: string) { if (isDev && process.env.TIMELOGGER === "1") { console.log(name + ": " + (dayjs().valueOf() - this.startTime) + "ms") @@ -231,6 +270,13 @@ let getRandomBytes = ( } )(); +/** + * Get a random integer suitable for use in cryptography between upper + * and lower bounds. + * @param min Minimum value of integer + * @param max Maximum value of integer + * @returns Cryptographically suitable random integer + */ export function getCryptoRandomInt(min: number, max: number):number { // synchronous version of: https://github.com/joepie91/node-random-number-csprng @@ -267,6 +313,11 @@ export function getCryptoRandomInt(min: number, max: number):number { } } +/** + * Generate a secret + * @param length Lenght of secret to generate + * @returns + */ export function genSecret(length = 64) { let secret = ""; const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789"; @@ -277,6 +328,11 @@ export function genSecret(length = 64) { return secret; } +/** + * Get the path of a monitor + * @param id ID of monitor + * @returns Formatted relative path + */ export function getMonitorRelativeURL(id: string) { return "/dashboard/" + id; }