@j-o-r/sh 1.1.28 → 1.1.29

package/lib/Test.js

@@ -1,51 +1,60 @@
 import { nextTick } from 'process';
-import { jsType } from './SH.js'
+import { jsType } from './SH.js';
 import AsyncTracker from './AsyncTracker.js';
+
 /**
-* Valid jsTypes for test methods
-*/
+ * Valid jsTypes for test callbacks (from {@link jsType}).
+ * @type {('Function'|'AsyncFunction')[]}
+ */
 const FNC = ['Function', 'AsyncFunction'];
-// Settle async calls in a SYNC function
+
+/**
+ * Default timeout (ms) to settle async calls in sync test functions.
+ * @type {number}
+ */
 const SETTLE_ASYNC = 50;
 
 /**
-* @typedef {(function(): Promise<any>)} AsyncFunction
-*/
+ * @typedef {() => Promise<any>} AsyncFunction
+ * @description Async test callback.
+ */
 
 /**
-* @typedef {Object} testDefinition
-* @prop {string} description
-* @prop {Function|AsyncFunction} callback - syc/ async function
-*/
+ * @typedef {Object} TestDefinition
+ * @property {string} description - Test name/description.
+ * @property {Function | AsyncFunction} callback - Sync/async test function.
+ */
 
 /**
-* @typedef {Object} testReport
-* @prop {string} description
-* @prop {number} duration - start time in MS
-* @prop {boolean} executed - Has it been called?
-*/
+ * @typedef {Object} TestReport
+ * @property {string} description - Test description.
+ * @property {number} duration - Execution duration (ms).
+ * @property {boolean} executed - Whether the test ran.
+ */
 
 /**
-* @typedef {Object} Report
-* @prop {number} tests
-* @prop {number} duration - start time in MS
-* @prop {number} errors - number of errors
-* @prop {number} executed - number of tests executed
-*/
+ * @typedef {Object} TestReportSummary
+ * @property {number} tests - Total tests defined.
+ * @property {number} duration - Total execution time (ms).
+ * @property {number} errors - Number of failures.
+ * @property {number} executed - Number of tests run.
+ */
+
 /**
-* Get the current time
-* used for calculating a duration
-* @returns {number}
-*/
+ * Returns current timestamp (ms) for duration calculations.
+ *
+ * @returns {number} Current time (Date.getTime()).
+ */
 function getNow() {
 	return new Date().getTime();
 }
 
 /**
-* Get the duration based on a previous gathered start time
-* @param {number} start - start time
-* @returns {number}
-*/
+ * Calculates duration from start time.
+ *
+ * @param {number} start - Start timestamp (ms).
+ * @returns {number} Duration (ms).
+ */
 function getDuration(start) {
 	return new Date().getTime() - start;
 }
@@ -55,85 +64,78 @@ class Test {
 	#promiseTracker;
 	#catchErrors = false;
 	#currentTest = -1;
-	/** @type {testDefinition[]} */
+	/** @type {TestDefinition[]} */
 	#tests = [];
-	/** @type {testReport[]} */
+	/** @type {TestReport[]} */
 	#reports = [];
-	/**
-	* @type {Error[]}
-	*/
+	/** @type {Error[]} */
 	#errors = [];
-	/** verbosed **/
 	#quiet = false;
-	/** Timeout in ms to settle async code blocks called from sync methods */
 	#TO = SETTLE_ASYNC;
+
 	/**
-	* @param {boolean} [quiet] - does not output a report when true, default `false`
-	*/
+	 * Creates a test runner instance.
+	 *
+	 * Tracks tests, errors, unresolved promises via {@link AsyncTracker}.
+	 * Supports sync/async callbacks; detects global errors.
+	 *
+	 * @param {boolean} [quiet=false] - Suppress console reports.
+	 * @example
+	 * const t = new Test();
+	 * t.add('basic', () => { throw new Error('fail'); });
+	 * const report = await t.run();
+	 */
 	constructor(quiet = false) {
 		if (quiet) {
 			this.#quiet = true;
 		}
-		// Track for unresolved promises
 		this.#promiseTracker = new AsyncTracker();
 		this.#promiseTracker.enable('PROMISE');
 	}
+
 	/**
-	* Set the timeout when a synced function is called.
-	* This settles async code used in a sync function
-	* and give some time to catch errors (#HACK)
-	* @param {number} timeout - in MS, default 50
-	*/
+	 * Sets timeout for settling async in sync tests (hack for late errors).
+	 *
+	 * @param {number} timeout - Timeout (ms); default 50.
+	 * @example
+	 * t.syncTimeout(100);
+	 */
 	syncTimeout(timeout) {
 		this.#TO = timeout;
 	}
 
 	/**
-	* Activate a listener on errors outside the call stack scope
-	* @param {boolean} active - register / unregister 
-	*/
-	#detectErrors(active = true) {
-		const errListener = (err) => {
-			this.#handleError(err, true);
-		}
-		if (active) {
-			if (!this.#catchErrors) {
-				process.on('uncaughtException', errListener);
-				this.#catchErrors = true;
-			}
-		} else {
-			if (this.#catchErrors) {
-				process.removeListener('uncaughtException', errListener);
-				this.#catchErrors = false;
-			}
-		}
-
-	}
-
-	/**
-	*
-	* @param {string} description
-	* @param {Function|AsyncFunction} callback - sync / async function
-	* @throws Error when conditions are not met
-	* @returns {Test}
-	*/
+	 * Adds a test case.
+	 *
+	 * @param {string} description - Test name.
+	 * @param {Function | AsyncFunction} callback - Test function.
+	 * @returns {Test} Self for chaining.
+	 * @throws {Error} Invalid description (non-string) or callback (not function).
+	 * @example
+	 * t.add('check 1+1', () => expect(1+1).toBe(2));
+	 */
 	add(description, callback) {
-		if (typeof (description) !== 'string') {
-			throw new Error(`'description' should be a string`)
+		if (typeof description !== 'string') {
+			throw new Error(`'description' should be a string`);
 		}
 		if (!FNC.includes(jsType(callback))) {
-			throw new Error(`'callback' should be a (async) Function`)
+			throw new Error(`'callback' should be a (async) Function`);
 		}
 		this.#tests.push({ description, callback });
 		return this;
 	}
+
 	/**
-	* Execute tests
-	* @param {number[]} [execute] - limit the execution tests
-	* @returns {Promise<Report>}
-	*/
+	 * Runs tests (all or selected); returns summary.
+	 *
+	 * Prints progress/errors; checks unresolved promises post-run.
+	 *
+	 * @param {number[]} [execute] - Indices of tests to run (default: all).
+	 * @returns {Promise<TestReportSummary>} Summary stats.
+	 * @example
+	 * await t.run([0, 2]); // Run tests 0 and 2
+	 */
 	async run(execute) {
-		// Detect errors outside the call stack
 		this.#detectErrors(true);
 		let errors = false;
 		let i = 0;
@@ -155,16 +157,13 @@ class Test {
 				await Promise.resolve(cb.callback());
 				executed = true;
 				if (type === 'Function') {
-					// To settle async calls in sync functions
-					// (catching errors outside this call stack, that may throw later (=== bad practise))
-					await new Promise(resolve => setTimeout(resolve, this.#TO)); // This will pause the the current loop.
-					// add timeout for an honest execution time
+					await new Promise(resolve => setTimeout(resolve, this.#TO));
 					start = start + this.#TO;
 				}
 			} catch (e) {
 				executed = true;
 				if (!errors) {
-					errors = true
+					errors = true;
 				}
 				error = e;
 			}
@@ -180,9 +179,63 @@ class Test {
 		this.#detectErrors(false);
 		return this.#report();
 	}
+
+	/**
+	 * Prints unresolved promises report (if any).
+	 *
+	 * @example
+	 * t.unresolved();
+	 */
+	unresolved() {
+		const count = this.#promiseTracker.report(true);
+		if (count > 0) {
+			console.log('--------------------------------------------------');
+			console.log(`${count} Unresolved Promises detected.`);
+		}
+	}
+
+	/**
+	 * Resets all tests, reports, errors, tracker.
+	 *
+	 * @example
+	 * t.reset();
+	 */
+	reset() {
+		this.#tests = [];
+		this.#reports = [];
+		this.#errors = [];
+		this.#promiseTracker.reset();
+	}
+
+	/**
+	 * Toggles global error listener (uncaughtException).
+	 *
+	 * @private
+	 * @param {boolean} active - Enable/disable.
+	 */
+	#detectErrors(active = true) {
+		const errListener = (err) => {
+			this.#handleError(err, true);
+		};
+		if (active) {
+			if (!this.#catchErrors) {
+				process.on('uncaughtException', errListener);
+				this.#catchErrors = true;
+			}
+		} else {
+			if (this.#catchErrors) {
+				process.removeListener('uncaughtException', errListener);
+				this.#catchErrors = false;
+			}
+		}
+	}
+
 	/**
-	* @returns {Promise<Report>}
-	*/
+	 * Generates final report summary.
+	 *
+	 * @private
+	 * @returns {Promise<TestReportSummary>}
+	 */
 	async #report() {
 		let duration = 0;
 		let executed = 0;
@@ -197,64 +250,41 @@ class Test {
 					executed = 1 + executed;
 				}
 			}
-
 		}
 		const errors = this.#errors.length;
 		if (!this.#quiet) {
 			console.log('--------------------------------------------------');
 			console.log(`Total: ${tests} tests, executed: ${executed} in ${duration} ms - errors: ${errors}`);
 			if (tests !== executed) {
-				if (!this.#quiet) console.log('** Not all tests have been executed **');
-		    // return { tests, executed, duration, errors };
+				console.log('** Not all tests have been executed **');
 			}
-			// Report on unresolved promises when NOT quiet
-			// This must be on a next tick because the current Promise (where this code is in) is not resolved yet
 			setTimeout(() => {
-				 const count = this.#promiseTracker.report(true);
-				 if (count > 0) {
-				 	console.log('--------------------------------------------------');
-				 	console.log(`${count} Unresolved Promises detected.`);
-				 }
+				const count = this.#promiseTracker.report(true);
+				if (count > 0) {
+					console.log('--------------------------------------------------');
+					console.log(`${count} Unresolved Promises detected.`);
+				}
 			}, 10);
 		}
 		return { tests, executed, duration, errors };
 	}
 
-  unresolved() {
-		 const count = this.#promiseTracker.report(true);
-		 if (count > 0) {
-		 	console.log('--------------------------------------------------');
-		 	console.log(`${count} Unresolved Promises detected.`);
-		 }
-  }  
-
-	/**
-	* Empty tests
-	*/
-	reset() {
-		this.#tests = [];
-		this.#reports = [];
-		this.#errors = [];
-		this.#promiseTracker.reset();
-	}
 	/**
-	* Handle an error for the current test 
-	* @param {Error} err
-	* @param {boolean} [outside] default false, Error is catched ouside the callscope of the test 
-	*/
+	 * Handles/logs test errors (current or global).
+	 *
+	 * @private
+	 * @param {Error} err - Error instance.
+	 * @param {boolean} [outside=false] - Global error flag.
+	 */
 	#handleError(err, outside = false) {
-		// A global error is an error catched outside the callstack of the test
-		const ERR = outside ? 'GLOBAL_ERROR' : 'ERROR'
+		const ERR = outside ? 'GLOBAL_ERROR' : 'ERROR';
 		if (this.#currentTest > -1) {
 			if (!this.#quiet) process.stdout.write(`\n`);
-			// Register this error
-			// Always print out errors despite #quiet
 			const description = this.#reports[this.#currentTest].description;
 			const executed = this.#reports[this.#currentTest].executed;
 			if (executed) {
 				process.stdout.write(`\x1b[31m-- ${ERR} Test: ${this.#currentTest}. ${description} --\x1b[0m\n`);
 			} else {
-				// Can been thrown from an other test
 				process.stdout.write(`\x1b[31m-- ${ERR} --\x1b[0m\n`);
 			}
 			console.error(err);

package/package.json

@@ -2,7 +2,7 @@
   "name": "@j-o-r/sh",
   "author": "Jorrit Duin <j-o-r@duin.work>",
   "type": "module",
-  "version": "1.1.28",
+  "version": "1.1.29",
   "description": "Execute shell commands on Linux-based systems from javascript",
   "main": "lib/SH.js",
   "types": "types/SH.d.ts",

package/types/AsyncTracker.d.ts

@@ -1,66 +1,100 @@
 export default AsyncTracker;
-/**
- * Represents an item in the async hooks tracking.
- */
 export type AsyncHookItem = {
     /**
-     * - The unique identifier for the async operation.
+     * - Unique async ID.
      */
     key: number;
     /**
-     * - The type of the async operation, e.g., 'PROMISE'.
+     * - Async type (e.g., 'PROMISE').
      */
     type: string;
     /**
-     * - The async ID of the resource that triggered this operation.
+     * - Triggering async ID.
      */
     triggerAsyncId: number;
     /**
-     * - The call stack trace when the async operation was initialized.
+     * - Call stack at init.
      */
     stack: string;
     /**
-     * - The Promise object associated with this operation, including its state and async IDs.-
+     * - Associated resource (e.g., Promise).
      */
-    resource: SystemTypes;
+    resource: any;
 };
+export type SystemTypes = "PROMISE" | "TIMEOUT" | "PROCESSNEXTTICK" | "TICKOBJECT" | "SCRIPT" | "QUERYWRAP" | "FILEHANDLE" | "HTTP2SESSION" | "HTTP2STREAM" | "ZLIB" | "UDPSENDWRAP" | "WRITEWRAP" | "SHUTDOWNWRAP" | "PROMISEEXECUTOR" | "TCPCONNECTWRAP" | "GETADDRINFOREQWRAP" | "GETNAMEINFOREQWRAP" | "IMMEDIATE" | "TCPWRAP" | "TCPSERVERWRAP" | "UDPWRAP" | "FSREQCALLBACK" | "HTTPPARSER" | "PIPEWRAP" | "PIPECONNECTWRAP" | "STREAMWRAP" | "TTYWRAP" | "PROCESS" | "SIGNALWRAP" | "TIMERWRAP";
 /**
- * /**
+ * Tracks unresolved async operations using Node's async_hooks.
+ *
+ * Detects leaks like hanging Promises, Timers. Used by {@link Test}.
+ *
+ * @example
+ * const tracker = new AsyncTracker();
+ * tracker.enable('PROMISE');
+ * // Run code...
+ * console.log(tracker.report(true)); // Unresolved count + details
  */
-export type SystemTypes = "PROMISE" | "TIMEOUT" | "PROCESSNEXTTICK" | "TICKOBJECT" | "SCRIPT" | "QUERYWRAP" | "FILEHANDLE" | "HTTP2SESSION" | "HTTP2STREAM" | "ZLIB" | "UDPSENDWRAP" | "WRITEWRAP" | "SHUTDOWNWRAP" | "PROMISEEXECUTOR" | "TCPCONNECTWRAP" | "GETADDRINFOREQWRAP" | "GETNAMEINFOREQWRAP" | "IMMEDIATE" | "TCPWRAP" | "TCPSERVERWRAP" | "UDPWRAP" | "FSREQCALLBACK" | "HTTPPARSER" | "PIPEWRAP" | "PIPECONNECTWRAP" | "STREAMWRAP" | "TTYWRAP" | "PROCESS" | "SIGNALWRAP" | "TIMERWRAP";
 declare class AsyncTracker {
     /**
-    * Enables tracking of asynchronous methods. Optionally, only methods of a specified type can be tracked.
-    * @param {SystemTypes} [type] - optional only register async methods for a specific type
-    */
+     * Enables tracking (optionally filter by type).
+     *
+     * @param {SystemTypes} [type] - Filter to specific type (e.g., 'PROMISE').
+     * @throws {Error} Unknown type.
+     * @example
+     * tracker.enable('PROMISE');
+     */
     enable(type?: SystemTypes): void;
     /**
-    * Disables the tracking of asynchronous methods.
-    */
+     * Disables tracking.
+     *
+     * @example
+     * tracker.disable();
+     */
     disable(): void;
     /**
-    * Clears all tracked asynchronous methods.
-    */
+     * Clears tracked items.
+     *
+     * @example
+     * tracker.reset();
+     */
     reset(): void;
+    /**
+     * Reports unresolved count (+ verbose details).
+     *
+     * @param {boolean} [verbose=false] - Print stack/resource per item.
+     * @returns {number} Unresolved count.
+     * @example
+     * if (tracker.report(true) > 0) console.error('Leaks!');
+     */
     report(verbose?: boolean): number;
     /**
-    * Returns an array of unresolved asynchronous methods, optionally filtered by type
-    * @param {SystemTypes} [type] - The type of async methods to filter by
-    * @returns {AsyncHookItem[]}
-    */
+     * Gets unresolved items (filtered).
+     *
+     * Temporarily disables hook during query.
+     *
+     * @param {SystemTypes} [type] - Filter type.
+     * @returns {AsyncHookItem[]} Array of items.
+     * @example
+     * const leaks = tracker.getUnresolved('PROMISE');
+     */
     getUnresolved(type?: SystemTypes): AsyncHookItem[];
     /**
-    * Returns a description of the specified asynchronous method type
-    * @param {SystemTypes} type - The type of asynchronous method.
-    * @returns {string}
-    */
+     * Gets description for type.
+     *
+     * @param {SystemTypes} type - Type.
+     * @returns {string} Description.
+     * @throws {Error} Unknown.
+     * @example
+     * tracker.getTypeDescription('PROMISE'); // 'Promise'
+     */
     getTypeDescription(type: SystemTypes): string;
     /**
-    * Adds or overwrites a custom type for asynchronous methods.
-    * @param {string} type - The type of asynchronous method.
-    * @param {string} description - the description
-    * @returns {void}
-    */
+     * Registers custom type description.
+     *
+     * @param {string} type - Type key (uppercased).
+     * @param {string} description - Description.
+     * @example
+     * tracker.addCustomType('MYTYPE', 'My async op');
+     */
     addCustomType(type: string, description: string): void;
     #private;
 }