refactor(qseow): Enhance documentation and improve function signatures

Author: mountaindude

src/lib/browser/browser-install.js

@@ -29,7 +29,6 @@ const { getMostRecentUsableChromeBuildId } = require('./browser-list-available')
  * @throws {Error} - If error getting browser cache path
  * @throws {Error} - If error getting browser executable path
  */
-// eslint-disable-next-line no-unused-vars
 const browserInstall = async (options, _command) => {
     try {
         if (!options.browser || !options.browserVersion) {

src/lib/browser/browser-installed.js

@@ -4,8 +4,19 @@ const { homedir } = require('os');
 
 const { logger, setLoggingLevel, bsiExecutablePath, isPkg } = require('../../globals');
 
-// Function to list all installed browsers
-// Returns an array of installed browsers
+/**
+ * List all installed browsers.
+ *
+ * @param {object} options - An options object.
+ * @param {string} [options.loglevel] - The log level. Can be one of "error", "warn", "info", "verbose", "debug", "silly". Default is "info".
+ *
+ * @returns {Promise<Array<Object>>} - A promise that resolves to an array of installed browsers.
+ * Each browser is represented by an object with the following properties:
+ * - browser {string}: The browser name, e.g. "chrome" or "firefox".
+ * - buildId {string}: The build id, e.g. "121.0.6167.85".
+ * - platform {string}: The platform, e.g. "win64" or "linux".
+ * - path {string}: The path to the browser executable.
+ */
 async function browserInstalled(options) {
     try {
         // Set log level

src/lib/browser/browser-list-available.js

@@ -6,9 +6,12 @@ const axios = require('axios');
 const { logger, setLoggingLevel, bsiExecutablePath, isPkg } = require('../../globals');
 
 /**
- * Maps Puppeteer's platform values to the Chrome version history API platform values
- * @param {string} puppeteerPlatform - Platform value from detectBrowserPlatform()
- * @returns {string} - Platform value for Chrome version history API
+ * Maps Puppeteer's platform values to corresponding Chrome version history API platform values.
+ * Converts 'win' to 'win', 'mac' to 'mac', and 'linux' to 'linux'.
+ * If the platform cannot be mapped, it returns the original Puppeteer platform value.
+ *
+ * @param {string} puppeteerPlatform - Platform value from detectBrowserPlatform().
+ * @returns {string} - Platform value suitable for the Chrome version history API.
  */
 function mapPlatformToChrome(puppeteerPlatform) {
     // Chrome API expects: win, mac, linux
@@ -25,8 +28,20 @@ function mapPlatformToChrome(puppeteerPlatform) {
     return puppeteerPlatform;
 }
 
-// Function to list all available browser versions
-// Returns an array of available browsers
+/**
+ * List all available browser versions.
+ *
+ * @param {object} options - An options object.
+ * @param {string} options.browser - Browser to list available versions for. Can be one of "chrome" or "firefox".
+ * @param {string} options.channel - Which of the browser's release channel versions should be listed?
+ * This option is only used for Chrome. Can be one of "stable", "beta", "dev", or "canary".
+ * @param {string} options.loglevel - The log level. Can be one of "error", "warn", "info", "verbose", "debug", or "silly".
+ *
+ * @returns {Promise<Array<Object>>} - A promise that resolves to an array of available browsers.
+ * Each browser is represented by an object with the following properties:
+ * - version {string}: The browser version, e.g. "115.0.5790.90".
+ * - name {string}: The browser name, e.g. "chrome/platforms/win/channels/stable/versions/115.0.5790.90".
+ */
 async function browserListAvailable(options) {
     try {
         // Set log level
@@ -212,8 +227,14 @@ async function browserListAvailable(options) {
         throw err;
     }
 }
-// Function to find most recent version of Chrome that Puppeteer can download and use
-// Returns the version number
+
+/**
+ * Finds the most recent version of Chrome that Puppeteer can download and use.
+ *
+ * @param {string} channel - The Chrome release channel.
+ * Valid values are "stable", "beta", "dev", "canary".
+ * @returns {Promise<string>} - A promise that resolves to the most recent usable Chrome build ID.
+ */
 async function getMostRecentUsableChromeBuildId(channel) {
     try {
         logger.verbose(`Get most recent usable Chrome build ID: Channel "${channel}"`);

src/lib/browser/browser-uninstall.js

@@ -5,7 +5,18 @@ const fs = require('fs-extra');
 
 const { logger, setLoggingLevel, bsiExecutablePath, isPkg } = require('../../globals');
 
-// Function to delete a specific browser
+/**
+ * Uninstall a browser from the Butler Sheet Icons cache.
+ * @param {object} options - An options object.
+ * @param {string} options.browser - The browser to uninstall.
+ * @param {string} options.browserVersion - The version of the browser to uninstall.
+ * @param {string} [options.loglevel] - The log level. Can be one of "error", "warn", "info", "verbose", "debug", "silly". Default is "info".
+ *
+ * @returns {Promise<boolean>} - A promise that resolves to true if the browser was uninstalled successfully, false otherwise.
+ *
+ * @throws {Error} - If the browser was not found.
+ * @throws {Error} - If there was an error uninstalling the browser.
+ */
 const browserUninstall = async (options) => {
     try {
         // Set log level
@@ -62,7 +73,16 @@ const browserUninstall = async (options) => {
     }
 };
 
-// Function to delete all browsers
+/**
+ * Uninstall all browsers from the Butler Sheet Icons cache.
+ *
+ * @param {object} options - An options object.
+ * @param {string} [options.loglevel] - The log level. Can be one of "error", "warn", "info", "verbose", "debug", "silly". Default is "info".
+ *
+ * @returns {Promise<boolean>} - A promise that resolves to true when all browsers are uninstalled.
+ *
+ * @throws {Error} - If there is an error during the uninstallation process.
+ */
 const browserUninstallAll = async (options) => {
     try {
         // Set log level

src/lib/cloud/cloud-collections.js

@@ -7,10 +7,19 @@ const QlikSaas = require('./cloud-repo');
 const { qscloudTestConnection } = require('./cloud-test-connection');
 
 /**
+ * Lists all available collections in the Qlik Sense Cloud tenant.
  *
- * @param {*} options
- * @returns
+ * @param {Object} options - Configuration options for listing collections.
+ * @param {string} options.tenanturl - URL or host of Qlik Sense cloud tenant.
+ * @param {string} options.apikey - API key used to access the Sense APIs.
+ * @param {string} options.outputformat - Output format, either 'table' or 'json'.
+ * @param {string} [options.loglevel] - Optional log level.
+ *
+ * @returns {Promise<boolean>} - Resolves to true if collections are successfully listed, false otherwise.
+ *
+ * @throws {Error} - Throws an error if there is an issue during the listing process.
  */
+
 const qscloudListCollections = async (options) => {
     try {
         // Set log level
@@ -135,6 +144,18 @@ const qscloudListCollections = async (options) => {
     }
 };
 
+/**
+ * Checks if a specified QS Cloud collection already exists.
+ *
+ * @param {object} options - Configuration options for the verification.
+ * @param {string} options.tenanturl - URL of the QS Cloud tenant.
+ * @param {string} options.apikey - API key for the QS Cloud tenant.
+ * @param {string} options.collectionid - ID of the collection to check for existence.
+ *
+ * @returns {Promise<boolean>} - Resolves to true if the collection exists, false otherwise.
+ *
+ * @throws {Error} - Throws an error if there is an issue during the verification process.
+ */
 const qscloudVerifyCollectionExists = async (options) => {
     try {
         logger.debug('Checking if QS Cloud collection already exists');
@@ -149,13 +170,7 @@ const qscloudVerifyCollectionExists = async (options) => {
 
         // Get all available collections
         const allCollections = await saasInstance.Get('collections');
-        logger.debug(
-            `COLLECTION EXISTS: Collections:\n${JSON.stringify(
-                allCollections,
-                null,
-                2
-            )}`
-        );
+        logger.debug(`COLLECTION EXISTS: Collections:\n${JSON.stringify(allCollections, null, 2)}`);
 
         // Get index of specified collection among the existing ones.
         const index = allCollections.map((e) => e.id).indexOf(options.collectionid);

src/lib/cloud/cloud-create-thumbnails.js

@@ -23,10 +23,13 @@ const selectorLoginPageUserPwd = '[id="\u0031-password"]';
 const selectorLoginPageLoginButton = '[id="\u0031-submit"]';
 
 /**
+ * Process a single Qlik Sense Cloud app.
  *
- * @param {*} appId
- * @param {*} saasInstance
- * @param {*} options
+ * @param {string} appId      App ID of the app to process.
+ * @param {QlikSaas} saasInstance QlikSaas object.
+ * @param {Object}  options    Options object.
+ *
+ * @returns {Promise<void>}
  */
 const processCloudApp = async (appId, saasInstance, options) => {
     // Create image directory on disk for this app
@@ -584,9 +587,27 @@ const processCloudApp = async (appId, saasInstance, options) => {
 };
 
 /**
+ * Create thumbnails for Qlik Sense Cloud (QSC)
+ * @param {object} options - Object containing options for creating thumbnails
+ * @param {string} options.tenanturl - URL of Qlik Sense Cloud tenant
+ * @param {string} options.apikey - API key for Qlik Sense Cloud tenant
+ * @param {string} options.loglevel - log level for the operation
+ * @param {string} options.logonuserid - user ID for Qlik Sense Cloud tenant
+ * @param {string} options.logonpwd - password for Qlik Sense Cloud tenant
+ * @param {string} options.collectionid - ID of collection in Qlik Sense Cloud tenant
+ * @param {string} options.appid - ID of app in Qlik Sense Cloud tenant
+ * @param {string} options.imagedir - directory where images will be stored
+ * @param {string} options.includesheetpart - optional parameter to include sheet parts in the thumbnails. Values: 1, 2, 4
+ * @param {string} options.schemaversion - version of the QS schema
+ * @param {string} options.appid - ID of app in Qlik Sense Cloud tenant
+ * @param {string} options.browser - name of browser to use for rendering thumbnails
+ * @param {string} options.browserVersion - version of browser to use for rendering thumbnails
+ * @param {string} options.blurSheetStatus - which sheet statuses should be blurred
+ * @param {string} options.blurSheetTag - which sheet tags should be blurred
+ * @param {string} options.blurSheetNumber - number of sheets to blur
+ * @param {string} options.blurFactor - blur factor
  *
- * @param {*} options
- * @returns
+ * @returns {Promise<boolean>} - true if thumbnails were created successfully, false otherwise
  */
 const qscloudCreateThumbnails = async (options) => {
     try {

src/lib/cloud/cloud-enigma.js

@@ -5,13 +5,17 @@ const WebSocket = require('ws');
 const { logger } = require('../../globals');
 
 /**
+ * Sets up an Enigma connection to a Qlik Sense SaaS tenant.
  *
- * @param {*} appId
- * @param {*} options
- * @param {*} command
- * @returns
+ * @param {string} appId - The ID of the Qlik Sense app to connect to.
+ * @param {Object} options - Options for the Enigma connection.
+ * @param {string} options.schemaversion - The version of the Enigma schema to use.
+ * @param {string} options.tenanturl - The URL of the Qlik Sense SaaS tenant.
+ * @param {string} options.apikey - The API key to use for authentication.
+ * @param {Object} command - Command options, used for logging.
+ *
+ * @returns {Object} An object with properties `schema` and `url` to be used when creating an Enigma session.
  */
-// eslint-disable-next-line no-unused-vars
 const setupEnigmaConnection = (appId, options, command) => {
     logger.debug(`Prepping for cloud Enigma connection for app ${appId}`);
 

src/lib/cloud/cloud-remove-sheet-icons.js

@@ -8,10 +8,16 @@ const QlikSaas = require('./cloud-repo');
 const { qscloudTestConnection } = require('./cloud-test-connection');
 
 /**
+ * Removes all sheet icons from a Qlik Sense Cloud app.
  *
- * @param {*} appId
- * @param {*} saasInstance
- * @param {*} options
+ * @param {string} appId - The ID of the Qlik Sense Cloud app to process.
+ * @param {Object} saasInstance - Instance of the QlikSaas class.
+ * @param {Object} options - Configuration options for processing the app.
+ * @param {string} options.tenanturl - Host address of the Qlik Sense Cloud tenant.
+ * @param {string} options.apikey - API key for the Qlik Sense Cloud tenant.
+ * @param {string} options.loglevel - The level of logging to output. Valid values are 'error', 'warn', 'info', 'verbose', 'debug', 'silly'.
+ *
+ * @returns {Promise<void>}
  */
 const removeSheetIconsCloudApp = async (appId, saasInstance, options) => {
     try {
@@ -147,9 +153,16 @@ const removeSheetIconsCloudApp = async (appId, saasInstance, options) => {
 };
 
 /**
+ * Removes all sheet icons from one or more Qlik Sense Cloud applications.
+ *
+ * @param {Object} options - Configuration options for the command.
+ * @param {string} options.tenanturl - URL or host of Qlik Sense cloud tenant. Example: "https://tenant.eu.qlikcloud.com" or "tenant.eu.qlikcloud.com"
+ * @param {string} options.apikey - API key used to access the Sense APIs
+ * @param {string} options.appid - The ID of the Qlik Sense Cloud application to process.
+ * @param {string} options.collectionid - The ID of the collection containing apps to process.
+ * @param {string} options.loglevel - The level of logging to output. Valid values are 'error', 'warn', 'info', 'verbose', 'debug', 'silly'.
  *
- * @param {*} options
- * @returns
+ * @returns {Promise<boolean>} - true if thumbnails were removed successfully, false otherwise.
  */
 const qscloudRemoveSheetIcons = async (options) => {
     try {

src/lib/cloud/cloud-repo-request.js

@@ -31,6 +31,13 @@ axios.interceptors.response.use(
         })
 );
 
+/**
+ * Takes a Buffer and returns a Readable Stream
+ *
+ * @param {Buffer} buffer The buffer to stream
+ *
+ * @returns {Readable} A Readable Stream
+ */
 function bufferToStream(buffer) {
     const stream = new Readable();
     stream.push(buffer);
@@ -39,6 +46,14 @@ function bufferToStream(buffer) {
     return stream;
 }
 
+/**
+ * Makes a request to the Qlik Cloud Repository API.
+ *
+ * @param {object} config Axios config object
+ * @param {array} [data=[]] Accumulated data from previous paginated requests
+ *
+ * @returns {Promise<object|array>} The response data
+ */
 async function makeRequest(config, data = []) {
     let returnData = [...data];
 
@@ -82,6 +97,19 @@ async function makeRequest(config, data = []) {
     return returnData;
 }
 
+/**
+ * Makes a request to the Qlik Cloud Repository API.
+ *
+ * @param {object} mainConfig Configuration object for Qlik Cloud
+ * @param {string} path Path to make the request to
+ * @param {string} type HTTP method to use
+ * @param {object|Buffer} data Data to send with the request
+ * @param {string} [contentType=application/json] Content-Type of the request
+ * @param {Buffer} [file] File to send with the request
+ * @param {string} [fileName] Name of the file
+ *
+ * @returns {Promise<object|array>} The response data
+ */
 module.exports = async (
     mainConfig,
     path,

src/lib/cloud/cloud-repo.js

@@ -2,6 +2,22 @@
 /* eslint-disable no-param-reassign */
 const request = require('./cloud-repo-request');
 
+/**
+ * Initializes a QlikSaas instance for interacting with a Qlik SaaS environment.
+ *
+ * @param {Object} config - Configuration object.
+ * @param {string} config.url - The base URL of the Qlik SaaS environment. Must include protocol.
+ * @param {string} config.token - API token for authentication.
+ * @param {number} [config.version=1] - Optional API version, defaults to 1 if not provided.
+ *
+ * @throws Will throw an error if the URL or API token is not provided.
+ *
+ * @property {function} Get - Makes a GET request to the specified path.
+ * @property {function} Delete - Makes a DELETE request to the specified path.
+ * @property {function} Patch - Makes a PATCH request with the provided data or file.
+ * @property {function} Post - Makes a POST request with the provided data or file.
+ * @property {function} Put - Makes a PUT request with the provided data or file.
+ */
 const qlikSaas = function QlikSaas(config) {
     if (!config.url) throw Error({ message: 'URL parameter is required' });
     if (!config.token) throw Error({ message: 'API token parameter is required' });