@j-o-r/sh 1.1.6 → 1.1.8

package/lib/SH.js

@@ -31,12 +31,11 @@ import SHDispatch from './SHDispatch.js';
 import Test from './Test.js'
 
 /**
-* @typedef {Object.<string, string>} ArgsObject
-* @property {string} [key: string] - Any string key maps to an object
+* @typedef {Object.<string, string | string[]>} ArgsObject
+* @property {string} [key: string] - Any string key maps to a string value
 * @property {string[]} _ - Array of strings, unnamed parameters
 * @description Parsed parameters result.
 */
-
 /**
 * @typedef {Function} RejectCallback
 * @param {Error} error - The error object passed to the callback.
@@ -260,32 +259,46 @@ function* expBackoff(max = '60s', rand = '100ms') {
 /**
 * Parses command-line arguments into an object.
 *
-* The function recognizes arguments that start with two dashes (`--`) as keys,
+* The function recognizes arguments that start with two dashes (`--`) or one dash (`-`) as keys,
 * and the subsequent value (if not another key) as the corresponding value.
 * If a key does not have a value, it defaults to `true`.
 * All unrecognized arguments are collected in an array under the `_` property.
 *
-* @param {string[]} args - An array of command-line arguments.
+* @param {string[]} [args] -  An array of command-line arguments (process.argv.slice(2)).
 * @returns {ArgsObject} An object where:
-*   - Each key corresponds to an argument that starts with `--`,
+*   - If args is not passed, process.argv.slice(2) will be the default
+*   - Each key corresponds to an argument that starts with `--` or `-`,
 *   - The value is either the next argument or `true` if no value is provided,
 *   - The `_` property contains an array of unbound arguments.
 */
 const parseArgs = (args) => {
-	const result = { _: [] }; // Initialize result with an empty array for unbound values
+	if (!args) args = process.argv.slice(2);
+	const result = { _: [] };
+	const seenKeys = new Set();
 	for (let i = 0; i < args.length; i++) {
-		if (args[i].startsWith('--')) {
-			const key = args[i].substring(2);
-			const value = args[i + 1] && !args[i + 1].startsWith('--') ? args[i + 1] : true;
+		if (args[i].startsWith('--') || args[i].startsWith('-')) {
+			if (args[i].startsWith('-') && !args[i].startsWith('--') && args[i].length > 2) {
+				throw new Error(`Invalid argument: ${args[i]}. Use '--' for long options.`);
+			}
+			const key = args[i].startsWith('--') ? args[i].substring(2) : args[i].substring(1);
+			if (seenKeys.has(key)) {
+				throw new Error(`Duplicate argument: ${args[i]}`);
+			}
+			seenKeys.add(key);
+			let value;
+			if (args[i + 1] && !args[i + 1].startsWith('-')) {
+				value = args[i + 1];
+				i++; // Skip next element as it is a value
+			} else {
+				value = true;
+			}
 			result[key] = value;
-			if (value !== true) i++; // Skip the next element as it is a value
 		} else {
-			result._.push(args[i]); // Add unbound value to the array
+			result._.push(args[i]);
 		}
 	}
 	return result;
-}
-
+};
 
 export {
 	SH,

package/lib/SHDispatch.js

@@ -8,15 +8,18 @@ import SHExec from './SHExecute.js';
  * @property {Buffer|null} stdout - The standard output of the child process.
  * @property {Buffer|null} stderr - The standard error of the child process.
  */
-/**
- * Default options for the execution environment.
- *
+ /**
  * @typedef {Object} SHOptions
- * @property {string} [cwd] - The current working directory.
- * @property {NodeJS.ProcessEnv} [env] - The environment variables.
- * @property {string} [shell] - The shell to use for execution.
- * @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 {string} [cwd] - Current working directory of the child process.
+ * @property {Object} [env] - Environment key-value pairs.
+ * @property {Array|string} [argv0] - Explicitly set the value of `argv[0]` sent to the child process.
+ * @property {boolean} [detached=false] - If true, the child will be a process group leader.
+ * @property {number} [uid] - Sets the user identity of the process.
+ * @property {number} [gid] - Sets the group identity of the process.
+ * @property {StdioOptions|StdioOption} [stdio='pipe'] - Child's stdio configuration.
+ * @property {boolean|string} [shell="bash"] - If true, runs command inside a shell.
+ * @property {number} [timeout=0] - In milliseconds, specifies when to terminate the child process.
+ * @property {string|Buffer|URL} [input] - The input to write to stdin.
  */
 /**
  * @typedef {('pipe' | 'ignore' | 'inherit' | number)} StdioOption
@@ -49,22 +52,24 @@ import SHExec from './SHExecute.js';
 * @returns {SHOptions}
 */
 const mergeOptions = (predefined, options) => {
-	const keys = Object.keys(predefined);
-	const mergedObj = keys.reduce((acc, key) => {
-		acc[key] = options[key] !== undefined ? options[key] : predefined[key];
-		return acc;
-	}, {});
+	const mergedObj = { ...predefined };
+
+	for (const key in options) {
+		if (options[key] !== undefined) {
+			mergedObj[key] = options[key];
+		}
+	}
+
 	return mergedObj;
 }
 
-
 /** @type {SHOptions} */
 const defaultOptions = {
 	cwd: process.cwd(),
 	env: process.env,
 	shell: 'bash',
 	stdio: ['inherit', 'pipe', 'pipe'],
-	timeout: 10000 // when 0 there is no timeout
+	timeout: 0 // when 0 there is no timeout
 };
 
 
@@ -107,6 +112,7 @@ class SHDispatch {
 		this.#options = mergeOptions(defaultOptions, options)
 		return this;
 	}
+
 	/** 
 	* @param {string} [payload]
 	* @returns {Promise<string>}
@@ -117,7 +123,7 @@ class SHDispatch {
 	}
 
 	/** 
-	* Works for screen takeovers like editors
+	* Works for terminal screen takeovers like editors
 	* @param {string} [payload]
 	* @returns {import('child_process').SpawnSyncReturns}
 	*/

package/lib/SHExecute.js

@@ -93,13 +93,9 @@ class SHExecute {
 	* @retuns {Promise<string>}
 	*/
 	run(payload) {
-		let to = 0;
 		if (payload && typeof payload !== 'string') {
 			throw new Error('Argument is not a string');
 		}
-		if (this.#options.timeout) {
-			to = this.#options.timeout;
-		}
 		/** @type {import('node:child_process').SpawnOptions} */
 		const options = this.#options;
 		// pipe need to be set on stdin when posting a payload
@@ -117,21 +113,14 @@ class SHExecute {
 			this.#proc.stdin.end(payload);
 		}
 		return new Promise((resolve, reject) => {
-			let timeout;
-			if (to > 0) {
-				timeout = setTimeout(async () => {
-					this.#proc.kill();
-					reject(new Error(`Process timed out: ${this.#command}`));
-				}, to); // options.timeout
-			}
 			this.#proc.on('close', (code) => {
-				if (timeout) clearTimeout(timeout);
 				if (this.#forcedKill) {
 					// Resolve without content
 					resolve();
 					return;
 				}
-				if (code === 0) {
+				// Detached does not closes with an exitcode
+				if (code === 0 || code === null || typeof (code) === 'undefined') {
 					resolve(this.#stdout.trim());
 				} else {
 					reject(new Error(`${code}: ${this.#command} "${this.#stderr.trim()}"`));

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.6",
+  "version": "1.1.8",
   "description": "Execute shell commands on Linux-based systems from javascript",
   "main": "lib/SH.js",
   "types": "types/SH.d.ts",

package/types/SH.d.ts

@@ -1,5 +1,5 @@
 export type ArgsObject = {
-    [x: string]: string;
+    [x: string]: string | string[];
 };
 export type RejectCallback = Function;
 export type ResolveCallback = Function;
@@ -44,7 +44,7 @@ export function sleep(duration: string | number): Promise<any>;
 * // Retry a command 3 times with irregular intervals using exponential backoff
 * const p = await retry(3, expBackoff(), () => SH`curl -s https://flipwrsi`);
 */
-export function retry(count: number, a: string | typeof expBackoff | Function, b?: Function | undefined): Promise<any>;
+export function retry(count: number, a: string | typeof expBackoff | Function, b?: Function): Promise<any>;
 /**
 * This function reads the standard input (stdin) from the current process.
 * @example
@@ -67,7 +67,7 @@ export function readIn(): Promise<string>;
 *   return 'res';
 * });
 */
-export function within(callback: Function, resolve?: Function | undefined, reject?: Function | undefined): void;
+export function within(callback: Function, resolve?: ResolveCallback, reject?: RejectCallback): void;
 /**
  * Generates an exponential backoff time with a random jitter.
  *
@@ -76,25 +76,26 @@ export function within(callback: Function, resolve?: Function | undefined, rejec
  * @param {string} [rand='100ms'] - The maximum random jitter time in a human-readable format (e.g., '100ms' for 100 milliseconds).
  * @yields {number} The backoff time in milliseconds.
  */
-export function expBackoff(max?: string | undefined, rand?: string | undefined): Generator<number, void, unknown>;
+export function expBackoff(max?: string, rand?: string): Generator<number, void, unknown>;
 /**
 * Parses command-line arguments into an object.
 *
-* The function recognizes arguments that start with two dashes (`--`) as keys,
+* The function recognizes arguments that start with two dashes (`--`) or one dash (`-`) as keys,
 * and the subsequent value (if not another key) as the corresponding value.
 * If a key does not have a value, it defaults to `true`.
 * All unrecognized arguments are collected in an array under the `_` property.
 *
-* @param {string[]} args - An array of command-line arguments.
+* @param {string[]} [args] -  An array of command-line arguments (process.argv.slice(2)).
 * @returns {ArgsObject} An object where:
-*   - Each key corresponds to an argument that starts with `--`,
+*   - If args is not passed, process.argv.slice(2) will be the default
+*   - Each key corresponds to an argument that starts with `--` or `-`,
 *   - 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[]): ArgsObject;
+export function parseArgs(args?: string[]): ArgsObject;
 /**
-* @typedef {Object.<string, string>} ArgsObject
-* @property {string} [key: string] - Any string key maps to an object
+* @typedef {Object.<string, string | string[]>} ArgsObject
+* @property {string} [key: string] - Any string key maps to a string value
 * @property {string[]} _ - Array of strings, unnamed parameters
 * @description Parsed parameters result.
 */

package/types/SHDispatch.d.ts

@@ -25,30 +25,47 @@ export type SpawnSyncResponse = {
      */
     stderr: Buffer | null;
 };
-/**
- * Default options for the execution environment.
- */
 export type SHOptions = {
     /**
-     * - The current working directory.
+     * - Current working directory of the child process.
      */
     cwd?: string | undefined;
     /**
-     * - The environment variables.
+     * - Environment key-value pairs.
      */
-    env?: NodeJS.ProcessEnv | undefined;
+    env?: Object | undefined;
     /**
-     * - The shell to use for execution.
+     * - Explicitly set the value of `argv[0]` sent to the child process.
      */
-    shell?: string | undefined;
+    argv0?: string | any[] | undefined;
     /**
-     * - The stdio configuration.
+     * - If true, the child will be a process group leader.
+     */
+    detached?: boolean | undefined;
+    /**
+     * - Sets the user identity of the process.
+     */
+    uid?: number | undefined;
+    /**
+     * - Sets the group identity of the process.
+     */
+    gid?: number | undefined;
+    /**
+     * - Child's stdio configuration.
      */
     stdio?: number | "pipe" | "ignore" | "inherit" | StdioOption[] | undefined;
     /**
-     * - default 20000: a timeout error is triggerd when a process execution time is exceeded, 0 is no timeout
+     * - If true, runs command inside a shell.
+     */
+    shell?: string | boolean | undefined;
+    /**
+     * - In milliseconds, specifies when to terminate the child process.
      */
     timeout?: number | undefined;
+    /**
+     * - The input to write to stdin.
+     */
+    input?: string | Buffer<ArrayBufferLike> | URL | undefined;
 };
 export type StdioOption = ("pipe" | "ignore" | "inherit" | number);
 export type StdioOptions = Array<StdioOption> | StdioOption;
@@ -62,18 +79,18 @@ declare class SHDispatch {
     * @param {string} [prefix] - command prefix e.g (default) '/usr/bin/env'
     * @returns {SHDispatch}
     */
-    options(options: import("child_process").SpawnOptions | import("child_process").SpawnSyncOptions, prefix?: string | undefined): SHDispatch;
+    options(options: import("child_process").SpawnOptions | import("child_process").SpawnSyncOptions, prefix?: string): SHDispatch;
     /**
     * @param {string} [payload]
     * @returns {Promise<string>}
     */
-    run(payload?: string | undefined): Promise<string>;
+    run(payload?: string): Promise<string>;
     /**
-    * Works for screen takeovers like editors
+    * Works for terminal screen takeovers like editors
     * @param {string} [payload]
     * @returns {import('child_process').SpawnSyncReturns}
     */
-    runSync(payload?: string | undefined): import("child_process").SpawnSyncReturns<any>;
+    runSync(payload?: string): import("child_process").SpawnSyncReturns<any>;
     kill(signal?: string): Promise<number[]>;
     #private;
 }

package/types/SHExecute.d.ts

@@ -10,12 +10,12 @@ declare class SHExecute {
     * @param {string} [payload] - data to write
     * @retuns {Promise<object>}
     */
-    runSync(payload?: string | undefined): import("child_process").SpawnSyncReturns<string | Buffer>;
+    runSync(payload?: string): import("child_process").SpawnSyncReturns<string | Buffer<ArrayBufferLike>>;
     /**
     * @param {string} [payload] - data to write
     * @retuns {Promise<string>}
     */
-    run(payload?: string | undefined): Promise<any>;
+    run(payload?: string): Promise<any>;
     /**
     * Kill this process and possible child processes
     * @param {number | string} signal - kill signal

package/types/Test.d.ts

@@ -37,7 +37,7 @@ declare class Test {
     /**
     * @param {boolean} [quiet] - does not output a report when true, default `false`
     */
-    constructor(quiet?: boolean | undefined);
+    constructor(quiet?: boolean);
     /**
     * Set the timeout when a synced function is called.
     * This settles async code used in a sync function
@@ -58,7 +58,7 @@ declare class Test {
     * @param {number[]} [execute] - limit the execution tests
     * @returns {Promise<Report>}
     */
-    run(execute?: number[] | undefined): Promise<Report>;
+    run(execute?: number[]): Promise<Report>;
     /**
     * Empty tests
     */