@j-o-r/sh 1.0.7 → 1.1.0

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,31 @@ 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 a promise',
+	new Promise((resolve, _reject) => {
+		assert.strictEqual(jsType(test), 'Test');
+		resolve();
+	})
+)
+
+await test.run();
+```
+
 ## License
 
 This project is licensed under the Apache License, Version 2.0.

package/lib/SH.js

@@ -28,7 +28,7 @@
 // Modified by: jorrit.duin+sh[AT]gmail.com
 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/SHDispatch.js

@@ -18,6 +18,7 @@ import SHExec from './SHExecute.js';
  * @property {string} [prefix] - The prefix commands to ensure a safe execution environment. e.g: prefix: 'set -euo pipefail;/usr/bin/env',
  * @property {StdioOptions|StdioOption} [stdio] - The stdio configuration.
  * @property {number} [timeout] - default 20000: a timeout error is triggerd when a process execution time is exceeded, 0 is no timeout
+ * @property {boolean} [detached] - default false, when true it runnes as a background process  
  */
 /**
  * @typedef {('pipe' | 'ignore' | 'inherit' | number)} StdioOption
@@ -86,6 +87,7 @@ const defaultOptions = {
 	cwd: process.cwd(),
 	env: process.env,
 	shell: 'bash',
+	detached: false,
 	prefix: '/usr/bin/env',
 	stdio: ['inherit', 'pipe', 'pipe'],
 	timeout: 10000 // when 0 there is no timeout

package/lib/SHExecute.js

@@ -73,7 +73,7 @@ class SHExecute {
 		if (payload && typeof payload !== 'string') {
 			throw new Error('Argument is not a string');
 		}
-		let { cwd, shell, env, stdio } = this.#options;
+		let { cwd, shell, env, stdio, detached } = this.#options;
 		// pipe need to be set on stdin when posting a payload
 		if (payload) stdio[0] = 'pipe';
 		const input = payload || undefined;
@@ -81,6 +81,7 @@ class SHExecute {
 			cwd,
 			shell,
 			stdio,
+			detached,
 			windowsHide: true,
 			env,
 			input
@@ -146,6 +147,7 @@ class SHExecute {
 		});
 	}
 	/**
+	* Kill this process and possible child processes
 	* @param {string} signal - kill signal
 	* @returns {Promise<number[]>}
 	*/
@@ -153,7 +155,16 @@ class SHExecute {
 		if (!this.#proc) throw new Error('Trying to kill a process without creating one.');
 		if (!this.#proc.pid) throw new Error('The process pid is undefined.');
 		this.#forcedKill = true;
-		const res = killProcesses(this.#proc.pid, signal);
+		let res = [];
+		try {
+			// Try to kill pid 'childs'
+			res = await killProcesses(this.#proc.pid, signal);
+		} catch (_e) { }
+		if (!res.includes(this.#proc.pid)) {
+			// Kill self if I am not allready killed
+			res.push(this.#proc.pid);
+			this.#proc.kill(signal);
+		}
 		this.#proc = undefined;
 		return res;
 	}

package/lib/Test.js

@@ -0,0 +1,213 @@
+import assert from 'node:assert/strict';
+import { jsType } from './SH.js'
+const FNC = ['Function', 'AsyncFunction', 'Promise'];
+// Settle async calls in a SYNC function
+const SETTLE_ASYNC = 100;
+
+/**
+* @typedef {Object} testDefinition
+* @prop {string} description
+* @prop {function|asyncfunction} callback
+*/
+
+/**
+* @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
+* @returns {number}
+*/
+function getNow() {
+	return new Date().getTime();
+}
+
+/**
+* Get the duration
+* @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|Promise} callback
+	* @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 or Promise`)
+		}
+		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 if (type === 'Promise') {
+					await Promise.all([cb.callback]);
+				} 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 = [];
+	}
+	/**
+	* Handle an error outside the callstack
+	* for the current test
+	*/
+	_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.7",
+  "version": "1.1.0",
   "description": "Execute shell commands on Linux-based systems from javascript",
   "main": "lib/SH.js",
   "types": "types/SH.d.ts",
@@ -22,13 +22,14 @@
   },
   "license": "Apache License, Version 2.0",
   "dependencies": {},
-  "devDependencies": {},
   "bugs": {
     "url": "https://codeberg.org/duin/sh/issues"
   },
   "homepage": "https://codeberg.org/duin",
   "keywords": [
     "shell",
+    "typeof",
+    "test",
     "posix",
     "linux",
     "command-line",
@@ -46,4 +47,4 @@
     "process-promise",
     "process-output"
   ]
-}
+}

package/types/SH.d.ts

@@ -83,4 +83,13 @@ 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 object / let type name
+*/
+export function jsType(fn: any): string;
+import Test from './Test.js';
 import SHDispatch from './SHDispatch.js';
+export { Test, assert };

package/types/SHDispatch.d.ts

@@ -53,6 +53,10 @@ export type SHOptions = {
      * - default 20000: a timeout error is triggerd when a process execution time is exceeded, 0 is no timeout
      */
     timeout?: number | undefined;
+    /**
+     * - default false, when true it runnes as a background process
+     */
+    detached?: boolean | undefined;
 };
 export type StdioOption = ("pipe" | "ignore" | "inherit" | number);
 export type StdioOptions = Array<StdioOption> | StdioOption;

package/types/SHExecute.d.ts

@@ -16,6 +16,7 @@ declare class SHExecute {
     */
     run(payload?: string | undefined): Promise<any>;
     /**
+    * Kill this process and possible child processes
     * @param {string} signal - kill signal
     * @returns {Promise<number[]>}
     */

package/types/Test.d.ts

@@ -0,0 +1,64 @@
+export default Test;
+export type testDefinition = {
+    description: string;
+    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;
+    catchErrors: boolean | undefined;
+    /**
+    *
+    * @param {string} description
+    * @param {Function|AsyncFunction|Promise} callback
+    * @throws Error when conditions are not met
+    */
+    add(description: string, callback: Function | AsyncFunction | Promise<any>): void;
+    /**
+    * Execute tests
+    * @param {number[]} [execute] - limit the execution tests
+    * @returns {Promise<Report>}
+    */
+    run(execute?: number[] | undefined): Promise<Report>;
+    /**
+    * Empty tests
+    */
+    reset(): void;
+    /**
+    * Handle an error outside the callstack
+    * for the current test
+    */
+    _handleError(err: any): void;
+    #private;
+}