@j-o-r/sh 1.1.23 → 1.1.25

package/README.md

@@ -64,11 +64,14 @@ The module also provides additional utilities for common tasks:
 - `sleep(duration)`: Pause execution for a specified duration.
 - `retry(count, interval, callback)`: Retry a command a specified number of times with an optional interval.
 - `readIn()`: Read from standard input.
+- `userIn(prompt)`: Prompt the user for input and return an object with `input` (Promise resolving to the user input) and `abort()` method to cancel.
 - `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 
+- `hasProp(object, property)`: Safely check if an object has its own property (handles null/undefined objects).
 - `assert.`: Node assert library 
 - `new Test()`: A small sync/async minimal test framework 
+- `AsyncTracker`: A class for tracking asynchronous operations using Node.js async hooks.
 
 ## SHDispatch
 
@@ -118,11 +121,27 @@ This class is returned by the `SH` function. Here's a summary of its methods and
 - Retry with exponential backoff:
   ```javascript
   try {
-    const p = await retry(3, expBackoff(), () => SH`curl -s https://flipwrsi`.run());
+    const p = await retry(3, expBackoff(), () => SH`curl -s https://unreachable`.run());
   } catch (e) {
     console.error('Retry failed:', e);
   }
   ```
+
+- Prompt user for input:
+  ```javascript
+  const user = userIn('Enter your name: ');
+  const name = await user.input;
+  console.log('Hello,', name);
+  ```
+
+- Check if object has property:
+  ```javascript
+  const obj = { a: 1 };
+  console.log(hasProp(obj, 'a')); // true
+  console.log(hasProp(obj, 'b')); // false
+  console.log(hasProp(null, 'a')); // false
+  ```
+
 - Method for copying data to the clipboard:
   ```javascript
   /**

package/lib/SHDispatch.js

@@ -114,7 +114,7 @@ class SHDispatch {
 	* @returns {SHDispatch}
 	*/
 	options(options, prefix) {
-		if (prefix && typeof prefix === 'string') {
+		if (typeof prefix === 'string') {
 			this.#prefix = prefix;
 		}
 		if (options.stdio && typeof options.stdio === 'string') {

package/lib/SHExecute.js

@@ -1,4 +1,4 @@
-import { spawnSync, spawn} from 'node:child_process';
+import { spawnSync, spawn } from 'node:child_process';
 
 // Local helpers
 const isFinitePosInt = (n) => Number.isFinite(n) && n >= 0;
@@ -19,15 +19,13 @@ const parseDuration = (d) => {
 const childrenOf = (pid) => new Promise((resolve, reject) => {
   const p = spawn('pgrep', ['-P', String(pid)], { stdio: ['ignore', 'pipe', 'ignore'] });
   const out = [];
-  p.stdout.on('data', (b) => out.push(b));
+  p.stdout.on('data', (chunk) => out.push(chunk));
   p.on('close', (code) => {
     if (code === 0) {
       const ids = Buffer.concat(out).toString('utf8').trim().split(/\s+/).map(Number).filter(Boolean);
       resolve(ids);
     } else if (code === 1) {
-      resolve([]); // no children
-    } else {
-      reject(new Error(`pgrep -P ${pid} failed with code ${code}`));
+      resolve([]); // no children or error
     }
   });
   p.on('error', reject);
@@ -103,7 +101,7 @@ class SHExecute {
     const shellOpt = this.#options?.shell;
     if (shellOpt) {
       const sh = typeof shellOpt === 'string' ? shellOpt : 'bash';
-      const cmd = `${this.#prefix}; ${this.#command}`;
+      const cmd = this.#prefix ? `${this.#prefix}; ${this.#command}` : this.#command;
       return spawnSync(sh, ['-c', cmd], options);
     }
     // no-shell mode
@@ -139,7 +137,7 @@ class SHExecute {
     const shellOpt = this.#options?.shell;
     if (shellOpt) {
       const sh = typeof shellOpt === 'string' ? shellOpt : 'bash';
-      const cmd = `${this.#prefix}; ${this.#command}`;
+      const cmd = this.#prefix ? `${this.#prefix}; ${this.#command}` : this.#command;
       this.#proc = spawn(sh, ['-c', cmd], options);
     } else {
       this.#proc = spawn('/usr/bin/env', ['-S', this.#command], options);
@@ -199,9 +197,9 @@ class SHExecute {
           resolve(stdout);
         } else {
           const stderrBuf = this.#stderrChunks.length ? Buffer.concat(this.#stderrChunks) : Buffer.alloc(0);
-          let stderr = stderrBuf.toString('utf8').trim();
+          let stderr = stderrBuf.toString('utf8');
           if (this.#truncated.stderr) stderr += '\n[stderr truncated]\n';
-          reject(new Error(`Exit ${code ?? 'null'}${signal ? `, signal ${signal}` : ''}: ${this.#command}${stderr ? ` :: ${stderr}` : ''}`));
+          reject(new Error(`Command failed with code ${code}: ${stderr}`));
         }
       });
 

package/lib/Test.js

@@ -140,7 +140,9 @@ class Test {
 		const len = this.#tests.length;
 		for (; i < len; i++) {
 			this.#currentTest = i;
-			if (execute && !execute.includes(i)) continue;
+			if (execute && !execute.includes(i)) {
+				continue;
+			}
 			let duration = 0;
 			let start = getNow();
 			let executed = false;
@@ -179,9 +181,9 @@ class Test {
 		return this.#report();
 	}
 	/**
-	* @returns {Report}
+	* @returns {Promise<Report>}
 	*/
-	#report() {
+	async #report() {
 		let duration = 0;
 		let executed = 0;
 		const tests = this.#tests.length;
@@ -203,21 +205,29 @@ class Test {
 			console.log(`Total: ${tests} tests, executed: ${executed} in ${duration} ms - errors: ${errors}`);
 			if (tests !== executed) {
 				if (!this.#quiet) console.log('** Not all tests have been executed **');
-		    return { tests, executed, duration, errors };
+		    // return { tests, executed, duration, errors };
 			}
 			// Report on unresolved promises when NOT quiet
 			// This must be on a next tick because the current Promise (where this code is in) is not resolved yet
-			nextTick(() => {
-				const count = this.#promiseTracker.report(true);
-				if (count > 0) {
-					console.log('--------------------------------------------------');
-					console.log(`${count} Unresolved Promises detected.`);
-				}
-			});
+			setTimeout(() => {
+				 const count = this.#promiseTracker.report(true);
+				 if (count > 0) {
+				 	console.log('--------------------------------------------------');
+				 	console.log(`${count} Unresolved Promises detected.`);
+				 }
+			}, 10);
 		}
 		return { tests, executed, duration, errors };
 	}
 
+  unresolved() {
+		 const count = this.#promiseTracker.report(true);
+		 if (count > 0) {
+		 	console.log('--------------------------------------------------');
+		 	console.log(`${count} Unresolved Promises detected.`);
+		 }
+  }  
+
 	/**
 	* Empty tests
 	*/
@@ -225,6 +235,7 @@ class Test {
 		this.#tests = [];
 		this.#reports = [];
 		this.#errors = [];
+		this.#promiseTracker.reset();
 	}
 	/**
 	* Handle an error for the current test 

package/module.md

@@ -0,0 +1,154 @@
+# @j-o-r/sh Module Documentation
+
+## Overview
+
+**Name:** @j-o-r/sh  
+**Version:** 1.1.23  
+**Description:** Execute shell commands on Linux-based systems from javascript.  
+
+This module simplifies the execution of shell commands within JavaScript applications, providing utilities to handle shell scripts and manage their output efficiently. It is inspired by the zx library and supports features like command execution, retries, user input, and more.
+
+**Repository:** https://codeberg.org/duin/sh  
+**License:** Apache License, Version 2.0  
+
+Key features include:
+- Execute shell commands synchronously or asynchronously.
+- Utilities for changing directory, sleeping, retrying commands with backoff.
+- Parsing command-line arguments.
+- User input prompts.
+- A minimal test framework.
+- Async operation tracking.
+
+## Installation Notes
+
+The module is already installed in the current environment. For new installations, use:
+
+```sh
+npm install @j-o-r/sh
+```
+
+Requires Node.js >= 20.0.0.
+
+## API Usage Examples
+
+### Basic Usage
+
+To execute a shell command, use the `SH` function:
+
+```javascript
+import { SH } from '@j-o-r/sh';
+
+SH`your_shell_command`.run()
+  .then(output => {
+    console.log('Output:', output);
+  })
+  .catch(error => {
+    console.error('Error:', error);
+  });
+```
+
+### Advanced Usage
+
+```javascript
+import { SH, cd, within, sleep, retry, expBackoff } from '@j-o-r/sh';
+
+const res = await SH`ls -FLa | grep package.json | wc -l`.run();
+console.log(res);
+
+const ar = within(async () => {
+  const res = await Promise.all([
+    SH`sleep 1; echo 1`.run(),
+    SH`sleep 2; echo 2`.run(),
+    sleep(2),
+    SH`sleep 3; echo 3`.run()
+  ]);
+});
+
+const p = await retry(3, expBackoff(), () => SH`curl -s https://unreachable`.run());
+```
+
+### Additional Examples
+
+- Prompt user for input:
+  ```javascript
+  const user = userIn('Enter your name: ');
+  const name = await user.input;
+  console.log('Hello,', name);
+  ```
+
+- 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');
+  });
+  const report = await test.run();
+  ```
+
+## Full API Reference
+
+### Main Exports
+
+- **SH**: A template tag function that returns an `SHDispatch` object for executing shell commands.
+- **cd(dir: string)**: Changes the working directory.
+- **sleep(duration: string | number)**: Pauses execution for the specified duration (e.g., '5s').
+- **retry(count: number, a: string | number | expBackoff | Function, b?: Function)**: Retries a function with optional intervals.
+- **readIn()**: Reads from stdin as a promise.
+- **userIn(prompt: string)**: Prompts for user input, returns object with `input` promise and `abort` method.
+- **within(callback: Function)**: Creates an async context.
+- **expBackoff(max?: string, rand?: string)**: Generator for exponential backoff intervals.
+- **parseArgs(args?: string[])**: Parses command-line arguments into an object.
+- **jsType(any)**: Returns the 'real' JavaScript type.
+- **hasProp(o: any, p: string)**: Safely checks if an object has a property.
+- **Test**: Class for a minimal test framework.
+- **assert**: Node.js assert library.
+- **AsyncTracker**: Class for tracking async operations.
+
+### SHDispatch Class
+
+Returned by the `SH` template tag. Methods:
+
+- **options(options: SpawnOptions | SpawnSyncOptions, prefix?: string)**: Sets execution options.
+- **run(payload?: string)**: Executes the command asynchronously, returns Promise<string>.
+- **runSync(payload?: string)**: Executes synchronously, returns SpawnSyncReturns.
+- **kill(signal?: string)**: Kills the process.
+
+### Test Class
+
+For running tests:
+
+- **constructor(quiet?: boolean)**: Creates a test suite.
+- **syncTimeout(timeout: number)**: Sets timeout for sync tests.
+- **add(description: string, callback: Function | AsyncFunction)**: Adds a test.
+- **run(execute?: number[])**: Runs tests, returns Promise<Report>.
+- **reset()**: Clears tests.
+
+### AsyncTracker Class
+
+Tracks async operations:
+
+- **enable(type?: SystemTypes)**: Enables tracking.
+- **disable()**: Disables tracking.
+- **reset()**: Clears tracked items.
+- **report(verbose?: boolean)**: Reports unresolved async operations.
+- **getUnresolved(type?: SystemTypes)**: Gets unresolved items.
+- **getTypeDescription(type: SystemTypes)**: Gets type description.
+- **addCustomType(type: string, description: string)**: Adds custom type.
+
+### Types
+
+- **ArgsObject**: Object for parsed args, with `_` for unnamed.
+- **SpawnSyncResponse**: Result of sync spawn.
+- **SHOptions**: Options for SH execution.
+- **AsyncHookItem**: Item in async tracking.
+- **testDefinition, testReport, Report**: Types for test framework.
+
+## Dependencies
+
+**Runtime Dependencies:** None  
+
+**Dev Dependencies:**  
+- @types/node: ^22.10.10
+

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

package/types/Test.d.ts

@@ -59,6 +59,7 @@ declare class Test {
     * @returns {Promise<Report>}
     */
     run(execute?: number[]): Promise<Report>;
+    unresolved(): void;
     /**
     * Empty tests
     */