@j-o-r/sh 1.1.2 → 1.1.4

package/lib/SH.js

@@ -29,6 +29,15 @@
 import assert from 'node:assert';
 import SHDispatch from './SHDispatch.js';
 import Test from './Test.js'
+
+/**
+ * @typedef {Function} RejectCallback
+ * @param {Error} error - The error object passed to the callback.
+ */
+/**
+ * @typedef {Function} ResolveCallback
+ * @param {any} [param] - Optional callback any value
+ */
 /**
  * Creates a new SHDispatch object that represents a command to be executed.
  *
@@ -44,6 +53,17 @@ import Test from './Test.js'
  * const command = await SH`echo 'Hello, world!'`.run();
  */
 
+/**
+* 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;
+};
 /**
 * 4ms, 5s || 5
 * @param {number|string} d 
@@ -81,9 +101,12 @@ const SH = new Proxy(function(pieces, ...args) {
 	}
 	return new SHDispatch(cmd);
 }, {});
+
 /**
-* Create a async context in an sync block
-* @param {function} callback - async function
+* Create a async/sync context in new execution callstack
+* @param {function} callback - async/sync function
+* @param {ResolveCallback} [resolve] - optional resolve/result callback
+* @param {RejectCallback} [reject] - optional reject/error callback
 * @example
 * const p = within(async () => {
 *		const res = await Promise.all([
@@ -92,12 +115,29 @@ const SH = new Proxy(function(pieces, ...args) {
 *			sleep(2),
 *			SH`sleep 3; echo 3`.run()
 *		]);
+*   return 'res';
+* });
 */
-const within = (callback) => {
+const within = (callback, resolve, reject) => {
+	// optional, custom resolve/reject functions from an outside promise/function
+	const RCB = jsType(resolve) === 'Function';
+	const ECB = jsType(reject) === 'Function';
 	(async () => {
-		return await callback()
+		try {
+			const res = await Promise.resolve(callback());
+			if (RCB) {
+				resolve(res);
+			}
+		} catch (e) {
+			if (ECB) {
+				reject(e)
+			} else {
+				throw (e);
+			}
+		}
 	})()
 }
+
 /**
 * This function reads the standard input (stdin) from the current process.
 * @example 
@@ -178,7 +218,7 @@ const retry = async (count, a, b) => {
 * 
 * @example
 * 
-* const res = await sleep('5s');
+* await sleep('5s');
 */
 const sleep = (duration) => {
 	return new Promise((resolve) => {
@@ -239,17 +279,6 @@ 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,

package/lib/Test.js

@@ -18,6 +18,7 @@ const SETTLE_ASYNC = 50;
 * @typedef {Object} testReport
 * @prop {string} description
 * @prop {number} duration - start time in MS
+* @prop {boolean} executed - Has it been called?
 */
 
 /**
@@ -55,7 +56,7 @@ class Test {
 	#errors = [];
 	/** verbosed **/
 	#quite = false;
-  /** Timeout in ms to settle async code blocks called from sync methods */
+	/** 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`
@@ -65,23 +66,23 @@ class Test {
 			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;
-  }
-	
+	/**
+	* 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
+	*/
+	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)
+			this.#handleError(err, true);
 		}
 		if (active) {
 			if (!this.#catchErrors) {
@@ -102,6 +103,7 @@ class Test {
 	* @param {string} description
 	* @param {Function|AsyncFunction} callback - sync / async function
 	* @throws Error when conditions are not met
+	* @returns {Test}
 	*/
 	add(description, callback) {
 		if (jsType(description) !== 'String') {
@@ -111,6 +113,7 @@ class Test {
 			throw new Error(`'callback' should be a (async) Function`)
 		}
 		this.#tests.push({ description, callback });
+		return this;
 	}
 	/**
 	* Execute tests
@@ -126,36 +129,38 @@ class Test {
 		for (; i < len; i++) {
 			this.#currentTest = i;
 			if (execute && !execute.includes(i)) continue;
+			let duration = 0;
 			let start = getNow();
+			let executed = false;
 			const cb = this.#tests[i];
 			const type = jsType(cb.callback);
+			this.#reports[i] = { description: cb.description, duration, executed };
 			let error;
 			try {
-			  if (!this.#quite) process.stdout.write(`${i}. ${cb.description}\n`);
+				if (!this.#quite) process.stdout.write(`${i}. ${cb.description} `);
+				await Promise.resolve(cb.callback());
+				executed = true;
 				if (type === 'Function') {
-					cb.callback();
 					// To settle async calls in sync functions
-					// (catching errors outside this call stack, that may throw later)
+					// (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
 					start = start + this.#TO;
-				} else {
-					await cb.callback();
 				}
 			} catch (e) {
-          process.stdout.write(`\x1b[31mERROR:  ${i}. ${cb.description}\x1b[0m\n`);
+				executed = true;
 				if (!errors) {
 					errors = true
 				}
 				error = e;
 			}
-			const duration = getDuration(start);
-			if (!this.#quite && !error) process.stdout.write(`Finished in: ${duration} ms\n`);
-			
+			duration = getDuration(start);
+			if (!this.#quite && !error) process.stdout.write(`(duration: ${duration} ms)\n`);
+			this.#reports[i].duration = duration;
+			this.#reports[i].executed = executed;
 			if (error) {
 				this.#handleError(error);
 			}
-			this.#reports[i] = { description: cb.description, duration };
 		}
 		this.#currentTest = -1;
 		this.#detectErrors(false);
@@ -167,7 +172,6 @@ class Test {
 	#report() {
 		let duration = 0;
 		let executed = 0;
-		let errors = 0;
 		const tests = this.#tests.length;
 		let i = 0;
 		const len = this.#reports.length;
@@ -175,22 +179,21 @@ class Test {
 			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 (r.executed) {
+					executed = 1 + executed;
 				}
 			}
 
 		}
+		const errors = this.#errors.length;
 		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}`);
+			console.log('--------------------------------------------------');
+			console.log(`Total: ${tests} tests, executed: ${executed} in ${duration} ms - errors: ${errors}`);
 		}
-		return {tests, executed, duration, errors};
+		return { tests, executed, duration, errors };
 	}
 
 	/**
@@ -203,17 +206,27 @@ class Test {
 	}
 	/**
 	* @private
-	* Handle an error outside the callstack
-	* for the current test
+	* Handle an error for the current test 
 	* @param {Error}
+	* @param {boolean} [outside] default false, Error is catched ouside the callscope of the test 
 	*/
-	#handleError(err) {
+	#handleError(err, outside = false) {
+		// A global error is an error catched outside the callstack of the test
+		const ERR = outside? 'GLOBAL_ERROR' : 'ERROR'
 		if (this.#currentTest > -1) {
+			if (!this.#quite) process.stdout.write(`\n`);
 			// Register this error
-			// Always print out errors
-			// Despite #quite
+			// Always print out errors despite #quite
+			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);
-			this.#errors[this.#currentTest] = err;
+			this.#errors.push(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.2",
+  "version": "1.1.4",
   "description": "Execute shell commands on Linux-based systems from javascript",
   "main": "lib/SH.js",
   "types": "types/SH.d.ts",
@@ -10,7 +10,8 @@
     "node": ">=20.0.0"
   },
   "scripts": {
-    "test": "test/sh.js",
+    "test": "npm run test:sh",
+    "test:sh": "scenarios/sh.js",
     "publish": "npm run release && npm publish --access public",
     "release": "npm pack --pack-destination=release",
     "types": "tsc",

package/types/SH.d.ts

@@ -1,3 +1,5 @@
+export type RejectCallback = Function;
+export type ResolveCallback = Function;
 /**
  * Creates a new SHDispatch object that represents a command to be executed.
  */
@@ -17,7 +19,7 @@ export function cd(dir: string): void;
 *
 * @example
 *
-* const res = await sleep('5s');
+* await sleep('5s');
 */
 export function sleep(duration: string | number): Promise<any>;
 /**
@@ -47,8 +49,10 @@ export function retry(count: number, a: string | typeof expBackoff | Function, b
 */
 export function readIn(): Promise<string>;
 /**
-* Create a async context in an sync block
-* @param {function} callback - async function
+* Create a async/sync context in new execution callstack
+* @param {function} callback - async/sync function
+* @param {ResolveCallback} [resolve] - optional resolve/result callback
+* @param {RejectCallback} [reject] - optional reject/error callback
 * @example
 * const p = within(async () => {
 *		const res = await Promise.all([
@@ -57,8 +61,10 @@ export function readIn(): Promise<string>;
 *			sleep(2),
 *			SH`sleep 3; echo 3`.run()
 *		]);
+*   return 'res';
+* });
 */
-export function within(callback: Function): void;
+export function within(callback: Function, resolve?: Function | undefined, reject?: Function | undefined): void;
 /**
  * Generates an exponential backoff time with a random jitter.
  *
@@ -83,6 +89,28 @@ export function expBackoff(max?: string | undefined, rand?: string | undefined):
 *   - The `_` property contains an array of unbound arguments.
 */
 export function parseArgs(args: string[]): object;
+/**
+ * @typedef {Function} RejectCallback
+ * @param {Error} error - The error object passed to the callback.
+ */
+/**
+ * @typedef {Function} ResolveCallback
+ * @param {any} [param] - Optional callback any value
+ */
+/**
+ * Creates a new SHDispatch object that represents a command to be executed.
+ *
+ * @typedef {Function} Shell
+ * @property {function(Array, ...*): ProcessPromise} execute - The function to execute the command.
+ *
+ * @param {Array} pieces - An array of string literals from a template literal.
+ * @param {...*} args - The values to be interpolated into the string literals.
+ * @returns {SHDispatch} Trigger for the command.
+ * @throws {Error} Throws an error if any of the string literals in `pieces` is undefined.
+ *
+ * @example
+ * const command = await SH`echo 'Hello, world!'`.run();
+ */
 /**
 * Determine a javascript type
 *

package/types/Test.d.ts

@@ -13,6 +13,10 @@ export type testReport = {
      * - start time in MS
      */
     duration: number;
+    /**
+     * - Has it been called?
+     */
+    executed: boolean;
 };
 export type Report = {
     tests: number;
@@ -38,7 +42,7 @@ declare class Test {
     * 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
+    * @param {number} timeout - in MS, default 50
     */
     syncTimeout(timeout: number): void;
     /**
@@ -46,8 +50,9 @@ declare class Test {
     * @param {string} description
     * @param {Function|AsyncFunction} callback - sync / async function
     * @throws Error when conditions are not met
+    * @returns {Test}
     */
-    add(description: string, callback: Function | AsyncFunction): void;
+    add(description: string, callback: Function | AsyncFunction): Test;
     /**
     * Execute tests
     * @param {number[]} [execute] - limit the execution tests