@j-o-r/sh 1.1.4 → 1.1.6

package/lib/SH.js

@@ -31,27 +31,34 @@ import SHDispatch from './SHDispatch.js';
 import Test from './Test.js'
 
 /**
- * @typedef {Function} RejectCallback
- * @param {Error} error - The error object passed to the callback.
- */
+* @typedef {Object.<string, string>} ArgsObject
+* @property {string} [key: string] - Any string key maps to an object
+* @property {string[]} _ - Array of strings, unnamed parameters
+* @description Parsed parameters result.
+*/
+
 /**
- * @typedef {Function} ResolveCallback
- * @param {any} [param] - Optional callback any value
- */
+* @typedef {Function} RejectCallback
+* @param {Error} error - The error object passed to the callback.
+*/
 /**
- * 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();
- */
+* @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
@@ -259,7 +266,7 @@ function* expBackoff(max = '60s', rand = '100ms') {
 * All unrecognized arguments are collected in an array under the `_` property.
 *
 * @param {string[]} args - An array of command-line arguments.
-* @returns {object} An object where:
+* @returns {ArgsObject} An object where:
 *   - Each key corresponds to an argument that starts with `--`,
 *   - The value is either the next argument or `true` if no value is provided,
 *   - The `_` property contains an array of unbound arguments.

package/lib/SHDispatch.js

@@ -15,10 +15,8 @@ import SHExec from './SHExecute.js';
  * @property {string} [cwd] - The current working directory.
  * @property {NodeJS.ProcessEnv} [env] - The environment variables.
  * @property {string} [shell] - The shell to use for execution.
- * @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
@@ -45,39 +43,17 @@ import SHExec from './SHExecute.js';
  * - 'inherit': Inherit all stdio streams from the parent.
  */
 /**
- * 'Code Safe' has own prop
- *
- * @param {any} o - object to examine
- * @param {string} p - property to look for
- * @returns {boolean}
- */
-const hasProp = (o, p) => {
-	if (typeof o === 'undefined') {
-		return false;
-	}
-	return Object.prototype.hasOwnProperty.call(o, p);
-};
-
-/**
-* Merge property values while maintaining the fixed set of props in the original object
-* @param {SHOptions} predefined - original object
-* @param {SHOptions} options - object with new values
+* Merge property values while maintaining the fixed set of props from the predefined object
+* @param {SHOptions} predefined - options
+* @param {import('child_process').SpawnOptions | import('child_process').SpawnSyncOptions} options
 * @returns {SHOptions}
 */
 const mergeOptions = (predefined, options) => {
-	// Extract the keys from the predefined object
 	const keys = Object.keys(predefined);
-
-	// Use reduce to accumulate only the predefined properties from sourceObj
 	const mergedObj = keys.reduce((acc, key) => {
-		if (hasProp(options, key)) {
-			acc[key] = options[key];
-		} else {
-			acc[key] = predefined[key];
-		}
+		acc[key] = options[key] !== undefined ? options[key] : predefined[key];
 		return acc;
 	}, {});
-
 	return mergedObj;
 }
 
@@ -87,8 +63,6 @@ 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
 };
@@ -96,6 +70,8 @@ const defaultOptions = {
 
 
 class SHDispatch {
+	// #prefix =  'set -euo pipefail;/usr/bin/env'
+	#prefix = 'set -euo pipefail;/usr/bin/env -S'
 	#cmd = '';
 	#options = {};
 	/** 
@@ -106,14 +82,21 @@ class SHDispatch {
 	* @param {string} cmd - cmd to execute
 	*/
 	constructor(cmd) {
+		if (!cmd || cmd === '') {
+			throw new Error('Undefined command');
+		}
 		this.#cmd = cmd;
 		this.#options = defaultOptions
 	}
 	/**
-	* @param {SHOptions} options
+	* @param {import('child_process').SpawnOptions | import('child_process').SpawnSyncOptions} options
+	* @param {string} [prefix] - command prefix e.g (default) '/usr/bin/env'
 	* @returns {SHDispatch}
 	*/
-	options(options) {
+	options(options, prefix) {
+		if (prefix && typeof prefix === 'string') {
+			this.#prefix = prefix;
+		}
 		if (options.stdio && typeof options.stdio === 'string') {
 			// convert stdio to array
 			// This sets the default io values
@@ -129,18 +112,17 @@ class SHDispatch {
 	* @returns {Promise<string>}
 	*/
 	run(payload) {
-		this.#proc = new SHExec(this.#cmd, this.#options);
+		this.#proc = new SHExec(this.#cmd, this.#prefix, this.#options);
 		return this.#proc.run(payload);
 	}
 
 	/** 
 	* Works for screen takeovers like editors
 	* @param {string} [payload]
-	* @returns {SpawnSyncResponse}
+	* @returns {import('child_process').SpawnSyncReturns}
 	*/
 	runSync(payload) {
-		// @ts-ignore
-		return new SHExec(this.#cmd, this.#options).runSync(payload);
+		return new SHExec(this.#cmd, this.#prefix, this.#options).runSync(payload);
 	}
 	async kill(signal = 'SIGTERM') {
 		let res = [];

package/lib/SHExecute.js

@@ -3,7 +3,7 @@ import { spawnSync, spawn, exec } from 'node:child_process';
 /**
 * Kills a process and all child processes of a given process ID in Linux/Posix.
 * @param {number} processPid - The process ID.
-* @param {string} signal - Signal to send.
+* @param {string|number} signal - Signal to send.
 * @retruns {Promise<number[]>} array with killed pid numbers
 */
 const killProcesses = (processPid, signal) => {
@@ -45,20 +45,24 @@ const killProcesses = (processPid, signal) => {
 }
 
 class SHExecute {
+	#forcedKill = false;
 	/**
 	* @type {import('child_process').ChildProcess}
 	*/
-	#forcedKill = false;
 	#proc;
+	#prefix = '';
 	#command = '';
+	/** @type {import('child_process').SpawnOptions | import('child_process').SpawnSyncOptions} */
 	#options = {};
 	#stdout = '';
 	#stderr = '';
 	/**
 	* @param {string} command - linux command to be executed
-	* @param {import('./SHDispatch').SHOptions} [options] - ChildProcess options
+	* @param {string} prefix  - command prefix (bash, sh etc.)
+	* @param {import('child_process').SpawnOptions | import('child_process').SpawnSyncOptions} options
 	*/
-	constructor(command, options = {}) {
+	constructor(command, prefix, options = {}) {
+		this.#prefix = prefix;
 		this.#command = command;
 		this.#options = options;
 		this.#proc = null;
@@ -73,19 +77,16 @@ class SHExecute {
 		if (payload && typeof payload !== 'string') {
 			throw new Error('Argument is not a string');
 		}
-		let { cwd, shell, env, stdio, detached } = this.#options;
+		/** @type {import('node:child_process').SpawnSyncOptions} */
+		const options = this.#options;
 		// pipe need to be set on stdin when posting a payload
-		if (payload) stdio[0] = 'pipe';
+		// @ts-ignore
+		if (payload) options['stdio'][0] = 'pipe';
 		const input = payload || undefined;
-		return spawnSync(this.#options.prefix, [this.#command], {
-			cwd,
-			shell,
-			stdio,
-			detached,
-			windowsHide: true,
-			env,
-			input
-		});
+		if (input) {
+			options.input = input
+		}
+		return spawnSync(this.#prefix, [this.#command], options);
 	}
 	/**
 	* @param {string} [payload] - data to write
@@ -99,16 +100,12 @@ class SHExecute {
 		if (this.#options.timeout) {
 			to = this.#options.timeout;
 		}
-		let { cwd, shell, env, stdio } = this.#options;
+		/** @type {import('node:child_process').SpawnOptions} */
+		const options = this.#options;
 		// pipe need to be set on stdin when posting a payload
-		if (payload) stdio[0] = 'pipe';
-		this.#proc = spawn(this.#options.prefix, [this.#command], {
-			cwd,
-			shell,
-			stdio,
-			windowsHide: true,
-			env,
-		});
+		// @ts-ignore
+		if (payload) options.stdio[0] = 'pipe';
+		this.#proc = spawn(this.#prefix, [this.#command], options);
 		this.#proc.stdout?.on('data', (data) => {
 			this.#stdout += data;
 		});
@@ -148,7 +145,7 @@ class SHExecute {
 	}
 	/**
 	* Kill this process and possible child processes
-	* @param {string} signal - kill signal
+	* @param {number | string} signal - kill signal
 	* @returns {Promise<number[]>}
 	*/
 	async kill(signal = 'SIGTERM') {
@@ -163,6 +160,7 @@ class SHExecute {
 		if (!res.includes(this.#proc.pid)) {
 			// Kill self if I am not allready killed
 			res.push(this.#proc.pid);
+			// @ts-ignore
 			this.#proc.kill(signal);
 		}
 		this.#proc = undefined;

package/lib/Test.js

@@ -1,5 +1,7 @@
-import assert from 'node:assert/strict';
 import { jsType } from './SH.js'
+/**
+* Valid jsTypes for test methods
+*/
 const FNC = ['Function', 'AsyncFunction'];
 // Settle async calls in a SYNC function
 const SETTLE_ASYNC = 50;
@@ -53,6 +55,9 @@ class Test {
 	#tests = [];
 	/** @type {testReport[]} */
 	#reports = [];
+	/**
+	* @type {Error[]}
+	*/
 	#errors = [];
 	/** verbosed **/
 	#quite = false;
@@ -106,7 +111,7 @@ class Test {
 	* @returns {Test}
 	*/
 	add(description, callback) {
-		if (jsType(description) !== 'String') {
+		if (typeof(description) !== 'string') {
 			throw new Error(`'description' should be a string`)
 		}
 		if (!FNC.includes(jsType(callback))) {
@@ -205,9 +210,8 @@ class Test {
 		this.#errors = [];
 	}
 	/**
-	* @private
 	* Handle an error for the current test 
-	* @param {Error}
+	* @param {Error} err
 	* @param {boolean} [outside] default false, Error is catched ouside the callscope of the test 
 	*/
 	#handleError(err, outside = false) {

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.4",
+  "version": "1.1.6",
   "description": "Execute shell commands on Linux-based systems from javascript",
   "main": "lib/SH.js",
   "types": "types/SH.d.ts",
@@ -14,7 +14,7 @@
     "test:sh": "scenarios/sh.js",
     "publish": "npm run release && npm publish --access public",
     "release": "npm pack --pack-destination=release",
-    "types": "tsc",
+    "types": "tsc -p tsc.json",
     "clear:types": "rm types/*.d.ts"
   },
   "repository": {

package/types/SH.d.ts

@@ -1,3 +1,6 @@
+export type ArgsObject = {
+    [x: string]: string;
+};
 export type RejectCallback = Function;
 export type ResolveCallback = Function;
 /**
@@ -83,34 +86,40 @@ export function expBackoff(max?: string | undefined, rand?: string | undefined):
 * All unrecognized arguments are collected in an array under the `_` property.
 *
 * @param {string[]} args - An array of command-line arguments.
-* @returns {object} An object where:
+* @returns {ArgsObject} An object where:
 *   - Each key corresponds to an argument that starts with `--`,
 *   - The value is either the next argument or `true` if no value is provided,
 *   - The `_` property contains an array of unbound arguments.
 */
-export function parseArgs(args: string[]): object;
+export function parseArgs(args: string[]): ArgsObject;
 /**
- * @typedef {Function} RejectCallback
- * @param {Error} error - The error object passed to the callback.
- */
+* @typedef {Object.<string, string>} ArgsObject
+* @property {string} [key: string] - Any string key maps to an object
+* @property {string[]} _ - Array of strings, unnamed parameters
+* @description Parsed parameters result.
+*/
 /**
- * @typedef {Function} ResolveCallback
- * @param {any} [param] - Optional callback any value
- */
+* @typedef {Function} RejectCallback
+* @param {Error} error - The error object passed to the callback.
+*/
 /**
- * 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();
- */
+* @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/SHDispatch.d.ts

@@ -41,10 +41,6 @@ export type SHOptions = {
      * - The shell to use for execution.
      */
     shell?: string | undefined;
-    /**
-     * - The prefix commands to ensure a safe execution environment. e.g: prefix: 'set -euo pipefail;/usr/bin/env',
-     */
-    prefix?: string | undefined;
     /**
      * - The stdio configuration.
      */
@@ -53,10 +49,6 @@ 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;
@@ -66,10 +58,11 @@ declare class SHDispatch {
     */
     constructor(cmd: string);
     /**
-    * @param {SHOptions} options
+    * @param {import('child_process').SpawnOptions | import('child_process').SpawnSyncOptions} options
+    * @param {string} [prefix] - command prefix e.g (default) '/usr/bin/env'
     * @returns {SHDispatch}
     */
-    options(options: SHOptions): SHDispatch;
+    options(options: import("child_process").SpawnOptions | import("child_process").SpawnSyncOptions, prefix?: string | undefined): SHDispatch;
     /**
     * @param {string} [payload]
     * @returns {Promise<string>}
@@ -78,9 +71,9 @@ declare class SHDispatch {
     /**
     * Works for screen takeovers like editors
     * @param {string} [payload]
-    * @returns {SpawnSyncResponse}
+    * @returns {import('child_process').SpawnSyncReturns}
     */
-    runSync(payload?: string | undefined): SpawnSyncResponse;
+    runSync(payload?: string | undefined): import("child_process").SpawnSyncReturns<any>;
     kill(signal?: string): Promise<number[]>;
     #private;
 }

package/types/SHExecute.d.ts

@@ -2,14 +2,15 @@ export default SHExecute;
 declare class SHExecute {
     /**
     * @param {string} command - linux command to be executed
-    * @param {import('./SHDispatch').SHOptions} [options] - ChildProcess options
+    * @param {string} prefix  - command prefix (bash, sh etc.)
+    * @param {import('child_process').SpawnOptions | import('child_process').SpawnSyncOptions} options
     */
-    constructor(command: string, options?: any);
+    constructor(command: string, prefix: string, options?: import("child_process").SpawnOptions | import("child_process").SpawnSyncOptions);
     /**
     * @param {string} [payload] - data to write
     * @retuns {Promise<object>}
     */
-    runSync(payload?: string | undefined): import("child_process").SpawnSyncReturns<Buffer> & import("child_process").SpawnSyncReturns<string> & import("child_process").SpawnSyncReturns<string | Buffer>;
+    runSync(payload?: string | undefined): import("child_process").SpawnSyncReturns<string | Buffer>;
     /**
     * @param {string} [payload] - data to write
     * @retuns {Promise<string>}
@@ -17,9 +18,9 @@ declare class SHExecute {
     run(payload?: string | undefined): Promise<any>;
     /**
     * Kill this process and possible child processes
-    * @param {string} signal - kill signal
+    * @param {number | string} signal - kill signal
     * @returns {Promise<number[]>}
     */
-    kill(signal?: string): Promise<number[]>;
+    kill(signal?: number | string): Promise<number[]>;
     #private;
 }