@j-o-r/sh 1.0.0 → 1.0.2

package/README.md

@@ -75,7 +75,7 @@ This class is returned by the `SH` function. Here's a summary of its methods and
 
 - **options(options)**: Sets options for the command execution.
 - **run(payload?)**: Executes the command and returns a promise that resolves with the command's output.
-- **runSync()**: Executes the command synchronously and returns a `SpawnSyncResponse`.
+- **runSync(payload?)**: Executes the command synchronously and returns a `SpawnSyncResponse`.
 - **kill()**: Sends a kill signal to the child process.
 
 ### Examples
@@ -113,7 +113,26 @@ This class is returned by the `SH` function. Here's a summary of its methods and
     console.error('Retry failed:', e);
   }
   ```
+- Method for copying data to the clipboard:
+  ```javascript
+  /**
+  * Copy text to the clipboard
+  * @param {string} text
+  * @retruns {Promise<string>}
+  */
+  const copyToClipboard = async (text) => {
+  	const prams = [
+  		'-selection',
+  		'clipboard'
+  	]
+  	return SH`xclip ${prams}`.options({stdio: 'inherit'}).run(text);
+  }
+  ```
 
+- Open the 'vim' editor  
+  ```javascript
+  SH`vim`.options({stdio: 'inherit'}).runSync();
+  ```
 ## License
 
 This project is licensed under the Apache License, Version 2.0.

package/lib/sh.d.ts

@@ -47,7 +47,11 @@ export type SHOptions = {
     /**
      * - The stdio configuration.
      */
-    stdio?: StdioOption | StdioOptions;
+    stdio?: StdioOptions | StdioOption;
+    /**
+     * - default 20000: a timeout error is triggerd when a process execution time is exceeded, 0 is no timeout
+     */
+    timeout?: number;
 };
 export type StdioOption = ('pipe' | 'ignore' | 'inherit' | number);
 export type StdioOptions = Array<StdioOption> | StdioOption;
@@ -138,9 +142,10 @@ declare class SHDispatch {
     run(payload?: string): Promise<string>;
     /**
     * Works for screen takeovers like editors
+    * @param {string} [payload]
     * @returns {SpawnSyncResponse}
     */
-    runSync(): SpawnSyncResponse;
+    runSync(payload?: string): SpawnSyncResponse;
     kill(): Promise<void>;
     #private;
 }

package/lib/sh.js

@@ -1,5 +1,8 @@
+import assert from 'node:assert';
 import { spawnSync, spawn, exec } from 'node:child_process';
 
+// timeout when a process becomes inresponsive
+
 /**
 * Kills a process and all child processes of a given process ID in Linux/Posix.
 * @param {number} processPid - The process ID.
@@ -45,11 +48,11 @@ const killProcesses = (processPid, signal) => {
 };
 
 class SHExecute {
-   #proc;
-   #command = '';
-   #options = {};
-   #stdout = '';
-   #stderr = '';
+	#proc;
+	#command = '';
+	#options = {};
+	#stdout = '';
+	#stderr = '';
 	constructor(command, options = {}) {
 		this.#command = command;
 		this.#options = options;
@@ -57,26 +60,42 @@ class SHExecute {
 		this.#stdout = '';
 		this.#stderr = '';
 	}
-	runSync () {
-    let { cwd, shell, env, stdio } = this.#options;
+	/**
+	* @param {string} [payload] - data to write
+	* @retuns {Promise<object>}
+	*/
+	runSync(payload) {
+		if (payload && typeof payload !== 'string') {
+			throw new Error('Argument is not a string');
+		}
+		let { cwd, shell, env, stdio } = this.#options;
+		// pipe need to be set on stdin when posting a payload
+		if (payload) stdio[0] = 'pipe';
+		const input = payload || undefined;
 		return spawnSync(this.#options.prefix, [this.#command], {
 			cwd,
 			shell,
 			stdio,
 			windowsHide: true,
 			env,
+			input
 		});
 	}
-  /**
-  * @param {string} [payload] - data to write
-  * @retuns {Promise<string>}
-  */
+	/**
+	* @param {string} [payload] - data to write
+	* @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;
+		}
 		let { cwd, shell, env, stdio } = this.#options;
-		if (payload) stdio = ['pipe', 'pipe', 'pipe'];
+		// 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,
@@ -92,12 +111,19 @@ class SHExecute {
 		this.#proc.stderr?.on('data', (data) => {
 			this.#stderr += data;
 		});
-    if (payload) {
-    	this.#proc.stdin.write(payload);
-      this.#proc.stdin.end();
-    }
+		if (payload) {
+			this.#proc.stdin.end(payload);
+		}
 		return new Promise((resolve, reject) => {
+			let timeout;
+			if (to > 0) {
+				timeout = setTimeout(async () => {
+					await this.#proc.kill();
+					reject(new Error(`Process timed out: ${this.#command}`));
+				}, to); // options.timeout
+			}
 			this.#proc.on('close', (code) => {
+				if (timeout) clearTimeout(timeout);
 				if (code === 0) {
 					resolve(this.#stdout.trim());
 				} else {
@@ -110,9 +136,9 @@ class SHExecute {
 			});
 		});
 	}
-  /**
-  * @returns {Promise<number[]>}
-  */
+	/**
+	* @returns {Promise<number[]>}
+	*/
 	async kill(signal = 'SIGTERM') {
 		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.');
@@ -138,7 +164,8 @@ class SHExecute {
  * @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.
- * @property {StdioOption|StdioOptions} [stdio] - The stdio configuration.
+ * @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
  */
 /**
  * @typedef {('pipe' | 'ignore' | 'inherit' | number)} StdioOption
@@ -180,9 +207,9 @@ const hasProp = (o, p) => {
 
 /**
 * Merge property values while maintaining the fixed set of props in the original object
-* @param {object} predefined - original object
-* @param {object} options - object with new values
-* @retuns {object}
+* @param {SHOptions} predefined - original object
+* @param {SHOptions} options - object with new values
+* @returns {SHOptions}
 */
 const mergeOptions = (predefined, options) => {
 	// Extract the keys from the predefined object
@@ -208,7 +235,8 @@ const defaultOptions = {
 	env: process.env,
 	shell: 'bash',
 	prefix: 'set -euo pipefail;/usr/bin/env',
-	stdio: ['inherit', 'pipe', 'pipe']
+	stdio: ['inherit', 'pipe', 'pipe'],
+	timeout: 10000 // when 0 there is no timeout
 };
 
 
@@ -229,6 +257,13 @@ class SHDispatch {
   * @returns {SHDispatch}
   */
 	options(options) {
+		if (options.stdio && typeof options.stdio === 'string') {
+			// convert stdio to array
+			// This sets the default io values
+			// but can be overwritten when having a payload
+			const io = options.stdio;
+			options.stdio = Array(3).fill(io);
+		}
 		this.#options = mergeOptions(defaultOptions, options);
 		return this;
 	}
@@ -243,11 +278,12 @@ class SHDispatch {
 
   /** 
   * Works for screen takeovers like editors
+  * @param {string} [payload]
   * @returns {SpawnSyncResponse}
   */ 
-	runSync() {
+	runSync(payload) {
 		// @ts-ignore
-		return new SHExecute(this.#cmd, this.#options).runSync();
+		return new SHExecute(this.#cmd, this.#options).runSync(payload);
 	}
 	async kill() {
 		try {
@@ -287,7 +323,6 @@ class SHDispatch {
 // Modified by: jorrit.duin+sh[AT]gmail.com
 
 
-
 /**
  * Creates a new SHDispatch object that represents a command to be executed.
  *
@@ -450,6 +485,7 @@ const retry = async (count, a, b) => {
 			let delay = 0;
 			if (delayStatic > 0)
 				delay = delayStatic;
+				// @ts-ignore
 			if (delayGen) delay = delayGen.next().value;
 			lastErr = err;
 			if (count == 0)

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.0",
+  "version": "1.0.2",
   "description": "Execute shell commands on Linux-based systems from javascript",
   "main": "lib/sh.js",
   "engines": {