@j-o-r/sh 1.0.8 → 1.1.1

package/README.md

@@ -66,6 +66,9 @@ The module also provides additional utilities for common tasks:
 - `readIn()`: Read from standard input.
 - `within(callback)`: Create an async context in a sync block.
 - `expBackoff(max, rand)`: Generate intervals for exponential backoff.
+- `jsType(any)`: Get the 'real' javascript variable type 
+- `assert.`: Node assert library 
+- `new Test()`: A small sync/async minimal test framework 
 
 ## SHDispatch
 
@@ -125,7 +128,7 @@ This class is returned by the `SH` function. Here's a summary of its methods and
   /**
   * Copy text to the clipboard
   * @param {string} text
-  * @retruns {Promise<string>}
+  * @returns {Promise<string>}
   */
   const copyToClipboard = async (text) => {
   	const prams = [
@@ -140,6 +143,34 @@ This class is returned by the `SH` function. Here's a summary of its methods and
   ```javascript
   SH`vim`.options({stdio: 'inherit'}).runSync();
   ```
+
+- Create and run a test
+```javascript
+import { assert, jsType, Test} from '@j-o-r/sh';
+
+const test = new Test();
+test.add('Test is test in sync', () => {
+	assert.strictEqual(jsType(test), 'Test');
+});
+test.add('Test an Array in sync', () => {
+	assert.strictEqual(jsType([]), 'Array');
+});
+test.add('Test is test in async', async () => {
+	assert.strictEqual(jsType(test), 'Test');
+});
+test.add('Test is test in async, returning a promise', async () => {
+	return new Promise((resolve, _reject) => {
+		assert.strictEqual(jsType(test), 'Test');
+		resolve();
+	});
+});
+const report = await test.run();
+if (report.errors > 0) {
+  process.exit(1);
+}
+// await test.run([0,3]); // only run test 0 and 3
+```
+
 ## License
 
 This project is licensed under the Apache License, Version 2.0.

package/lib/SH.js

@@ -23,12 +23,12 @@
 // Changes Made: 
 // - The code has been or is being reformatted to comply with ES2020 standards.
 // - Some methods were added and existing ones were modified or deleted to enhance usability.
-// - Most methods were deleted, 
 // - The namespace has been changed from '$' to 'SH'.
 // Modified by: jorrit.duin+sh[AT]gmail.com
+/** @type {assert} */
 import assert from 'node:assert';
 import SHDispatch from './SHDispatch.js';
-
+import Test from './Test.js'
 /**
  * Creates a new SHDispatch object that represents a command to be executed.
  *
@@ -238,6 +238,19 @@ const parseArgs = (args) => {
 	}
 	return result;
 }
+
+/**
+* Determine a javascript type
+*
+* @param {any} fn - Any let type
+* @returns {string} The "real" object / typeof name
+*/
+const jsType = (fn) => {
+	if (fn === undefined) return 'undefined';
+	const type = Object.prototype.toString.call(fn).slice(8, -1);
+	return type === 'Object' ? fn.constructor.name : type;
+};
+
 export {
 	SH,
 	cd,
@@ -246,5 +259,8 @@ export {
 	readIn,
 	within,
 	expBackoff,
-	parseArgs
+	parseArgs,
+	jsType,
+	Test,
+	assert
 }

package/lib/Test.js

@@ -0,0 +1,218 @@
+import assert from 'node:assert/strict';
+import { jsType } from './SH.js'
+const FNC = ['Function', 'AsyncFunction'];
+// Settle async calls in a SYNC function
+const SETTLE_ASYNC = 50;
+
+/**
+* @typedef {(function(): Promise<any>)} AsyncFunction
+*/
+
+/**
+* @typedef {Object} testDefinition
+* @prop {string} description
+* @prop {Function|AsyncFunction} callback - syc/ async function
+*/
+
+/**
+* @typedef {Object} testReport
+* @prop {string} description
+* @prop {number} duration - start time in MS
+*/
+
+/**
+* @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
+*/
+/**
+* Get the current time
+* used for calculating a duration
+* @returns {number}
+*/
+function getNow() {
+	return new Date().getTime();
+}
+
+/**
+* Get the duration based on a previous gathered start time
+* @param {number} start - start time
+* @returns {number}
+*/
+function getDuration(start) {
+	return new Date().getTime() - start;
+}
+
+class Test {
+	#catchErrors = false;
+	#currentTest = -1;
+	/** @type {testDefinition[]} */
+	#tests = [];
+	/** @type {testReport[]} */
+	#reports = [];
+	#errors = [];
+	/** verbosed **/
+	#quite = 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`
+	*/
+	constructor(quiet = false) {
+		if (quiet) {
+			this.#quite = true;
+		}
+	}
+  /**
+  * 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 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)
+		}
+		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
+	*/
+	add(description, callback) {
+		if (jsType(description) !== 'String') {
+			throw new Error(`'description' should be a string`)
+		}
+		if (!FNC.includes(jsType(callback))) {
+			throw new Error(`'callback' should be a (async) Function`)
+		}
+		this.#tests.push({ description, callback });
+	}
+	/**
+	* Execute tests
+	* @param {number[]} [execute] - limit the execution tests
+	* @returns {Promise<Report>}
+	*/
+	async run(execute) {
+		// Detect errors outside the call stack
+		this.#detectErrors(true);
+		let errors = false;
+		let i = 0;
+		const len = this.#tests.length;
+		for (; i < len; i++) {
+			this.#currentTest = i;
+			if (execute && !execute.includes(i)) continue;
+			let start = getNow();
+			const cb = this.#tests[i];
+			const type = jsType(cb.callback);
+			let error;
+			try {
+				if (type === 'Function') {
+					cb.callback();
+					// To settle async calls in sync functions
+					// (catching errors outside this call stack, that may throw later)
+					await new Promise(resolve => setTimeout(resolve, this.#TO)); // This will pause the the current loop.
+					// add timeout for an honest execution time
+					start = start + this.#TO;
+				} else {
+					await cb.callback();
+				}
+			} catch (e) {
+				if (!errors) {
+					errors = true
+				}
+				error = e;
+			}
+			const duration = getDuration(start);
+			if (!this.#quite) process.stdout.write(`${i}. ${cb.description} : ${duration} ms\n`);
+			if (error) {
+				this.#handleError(error);
+			}
+			this.#reports[i] = { description: cb.description, duration };
+		}
+		this.#currentTest = -1;
+		this.#detectErrors(false);
+		return this.#report();
+	}
+	/**
+	* @returns {Report}
+	*/
+	#report() {
+		let duration = 0;
+		let executed = 0;
+		let errors = 0;
+		const tests = this.#tests.length;
+		let i = 0;
+		const len = this.#reports.length;
+		for (; i < len; i++) {
+			const r = this.#reports[i];
+			if (r) {
+				duration = r.duration + duration;
+				executed = 1 + executed;
+				const E = this.#errors[i];
+				if (E) {
+					errors = 1 + errors;
+				}
+			}
+
+		}
+		if (tests !== executed) {
+			if (!this.#quite) console.log('** Not all tests have been executed **');
+		}
+		if (!this.#quite) {
+		  console.log('--------------------------------------------------');
+		  console.log(`Total: ${tests} tests, executed: ${executed} in ${duration} ms - errors: ${errors}`);
+		}
+		return {tests, executed, duration, errors};
+	}
+
+	/**
+	* Empty tests
+	*/
+	reset() {
+		this.#tests = [];
+		this.#reports = [];
+		this.#errors = [];
+	}
+	/**
+	* @private
+	* Handle an error outside the callstack
+	* for the current test
+	* @param {Error}
+	*/
+	#handleError(err) {
+		if (this.#currentTest > -1) {
+			// Register this error
+			// Always print out errors
+			// Despite #quite
+			console.error(err);
+			this.#errors[this.#currentTest] = err;
+		}
+	}
+}
+
+export default Test;

package/package.json

@@ -2,7 +2,7 @@
   "name": "@j-o-r/sh",
   "author": "Jorrit Duin <j-o-r@duin.work>",
   "type": "module",
-  "version": "1.0.8",
+  "version": "1.1.1",
   "description": "Execute shell commands on Linux-based systems from javascript",
   "main": "lib/SH.js",
   "types": "types/SH.d.ts",
@@ -21,14 +21,17 @@
     "url": "https://codeberg.org/duin/sh"
   },
   "license": "Apache License, Version 2.0",
-  "dependencies": {},
-  "devDependencies": {},
+  "dependencies": {
+    "@types/node": "^22.10.10"
+  },
   "bugs": {
     "url": "https://codeberg.org/duin/sh/issues"
   },
   "homepage": "https://codeberg.org/duin",
   "keywords": [
     "shell",
+    "typeof",
+    "test",
     "posix",
     "linux",
     "command-line",

package/types/SH.d.ts

@@ -83,4 +83,14 @@ export function expBackoff(max?: string | undefined, rand?: string | undefined):
 *   - The `_` property contains an array of unbound arguments.
 */
 export function parseArgs(args: string[]): object;
+/**
+* Determine a javascript type
+*
+* @param {any} fn - Any let type
+* @returns {string} The "real" object / typeof name
+*/
+export function jsType(fn: any): string;
+import Test from './Test.js';
+import assert from 'node:assert';
 import SHDispatch from './SHDispatch.js';
+export { Test, assert };

package/types/SHDispatch.d.ts

@@ -36,7 +36,7 @@ export type SHOptions = {
     /**
      * - The environment variables.
      */
-    env?: any;
+    env?: NodeJS.ProcessEnv | undefined;
     /**
      * - The shell to use for execution.
      */

package/types/SHExecute.d.ts

@@ -9,7 +9,7 @@ declare class SHExecute {
     * @param {string} [payload] - data to write
     * @retuns {Promise<object>}
     */
-    runSync(payload?: string | undefined): any;
+    runSync(payload?: string | undefined): import("child_process").SpawnSyncReturns<Buffer> & import("child_process").SpawnSyncReturns<string> & import("child_process").SpawnSyncReturns<string | Buffer>;
     /**
     * @param {string} [payload] - data to write
     * @retuns {Promise<string>}

package/types/Test.d.ts

@@ -0,0 +1,62 @@
+export default Test;
+export type AsyncFunction = (() => Promise<any>);
+export type testDefinition = {
+    description: string;
+    /**
+     * - syc/ async function
+     */
+    callback: Function | AsyncFunction;
+};
+export type testReport = {
+    description: string;
+    /**
+     * - start time in MS
+     */
+    duration: number;
+};
+export type Report = {
+    tests: number;
+    /**
+     * - start time in MS
+     */
+    duration: number;
+    /**
+     * - number of errors
+     */
+    errors: number;
+    /**
+     * - number of tests executed
+     */
+    executed: number;
+};
+declare class Test {
+    /**
+    * @param {boolean} [quiet] - does not output a report when true, default `false`
+    */
+    constructor(quiet?: boolean | undefined);
+    /**
+    * 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 100
+    */
+    syncTimeout(timeout: number): void;
+    /**
+    *
+    * @param {string} description
+    * @param {Function|AsyncFunction} callback - sync / async function
+    * @throws Error when conditions are not met
+    */
+    add(description: string, callback: Function | AsyncFunction): void;
+    /**
+    * Execute tests
+    * @param {number[]} [execute] - limit the execution tests
+    * @returns {Promise<Report>}
+    */
+    run(execute?: number[] | undefined): Promise<Report>;
+    /**
+    * Empty tests
+    */
+    reset(): void;
+    #private;
+}