@j-o-r/sh 1.1.25 → 1.1.27

package/lib/SH.js

@@ -103,22 +103,62 @@ const parseDuration = (d) => {
 	}
 	throw new Error(`Unknown duration: "${d}".`);
 }
+/**
+* bash escape a string suitable as an argument on the commandline
+* for javascript code
+* @param {string} x
+* @returns {string}
+*/
+const bashEscape = (x) => {
+	let str = String(x).trim();
+	// the trick is to double escape escape vars first
+	str = str.replace(/\\/g, '\\\\');
+	// then add escaping for oddities
+	// Replace literal escape sequences like \n, \t, \r in quoted strings
+	str = str.replace(/(['"])\\(.)\1/g, '$1\\\\$2$1');
+	// escape $ (is a BASH var)
+	str = str.replace(/\$/g, '\\$');
+	// Escape backticks
+	str = str.replace(/`/g, '\\`');
+	// Escape quotes
+	str = str.replace(/"/g, '\\"');
+	return str;
+}
+
+
+/** @type {import('./SHDispatch.js').SHOptions} */
+const defaultOptions = {
+	cwd: process.cwd(),
+	env: process.env,
+	shell: 'bash',
+	stdio: ['inherit', 'pipe', 'pipe'],
+	timeout: 0, // when 0 there is no timeout
+};
+
+const setHandler = {
+  set(target, prop, value) {
+    defaultOptions[prop] = value;  // Allow setting on target
+    // console.log(`Set ${String(prop)} = ${value}`);
+    // console.log(defaultOptions);
+    return true;
+  }
+}
+
 /**
 * A template-tag that returns an SHDispatch.
 * @typedef {(pieces: TemplateStringsArray, ...args: unknown[]) => SHDispatch} SHTag
 */
 /**
-* @type {Shell & SHTag}
+* SH template tag
+*
+* Interpolation rules:
+* - Arrays: each element is String(x).trim(), with newlines/carriage returns/tabs escaped; if an element contains shell metacharacters or spaces, it is wrapped in single-quotes and internal single-quotes are escaped as '\''.
+* - Non-array values: currently coerced with String(value) and inserted as-is (NOT shell-escaped). Be careful when interpolating untrusted input.
+*
+* @type {Shell & SHTag & defaultOptions}
+* Returns an SHDispatch that can be configured via .options() and executed with .run() / .runSync().
+* @returns {SHDispatch}
 */
-/**
- * SH template tag
- *
- * Interpolation rules:
- * - Arrays: each element is String(x).trim(), with newlines/carriage returns/tabs escaped; if an element contains shell metacharacters or spaces, it is wrapped in single-quotes and internal single-quotes are escaped as '\''.
- * - Non-array values: currently coerced with String(value) and inserted as-is (NOT shell-escaped). Be careful when interpolating untrusted input.
- *
- * Returns an SHDispatch that can be configured via .options() and executed with .run() / .runSync().
- */
 const SH = new Proxy(function(pieces, ...args) {
 	if (pieces.some((p) => p == undefined)) {
 		throw new Error(`Malformed command ${pieces}`);
@@ -145,8 +185,9 @@ const SH = new Proxy(function(pieces, ...args) {
 		}
 		cmd += s + pieces[++i];
 	}
-	return new SHDispatch(cmd);
-}, {});
+	return new SHDispatch(cmd, defaultOptions);
+}, setHandler);
+
 
 /**
 * Create a async/sync context in new execution callstack
@@ -220,11 +261,12 @@ const userIn = (prompt) => {
 
   const cleanup = () => {
     process.stdin.removeListener('data', onData);
+    // @ts-ignore
     rl.removeAllListeners('line');
     clearTimeout(timer);
     rl.close();
   };
-
+  // @ts-ignore
   rl.on('line', (line) => {
     buffer += line + '\n';
     clearTimeout(timer);
@@ -415,5 +457,6 @@ export {
 	hasProp,
 	Test,
 	assert,
-	AsyncTracker
+	AsyncTracker,
+	bashEscape
 }

package/lib/SHDispatch.js

@@ -48,7 +48,7 @@ import SHExec from './SHExecute.js';
 /**
 * 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
+* @param {SHOptions} options
 * @returns {SHOptions}
 */
 const mergeOptions = (predefined, options) => {
@@ -63,7 +63,6 @@ const mergeOptions = (predefined, options) => {
 	return mergedObj;
 }
 
-/** @type {SHOptions} */
 /**
  * SHOptions — effective defaults and semantics used by SHDispatch/SHExecute
  *
@@ -79,19 +78,12 @@ const mergeOptions = (predefined, options) => {
  * - The prefix (see options(prefix)) is only applied when a shell is used; it is ignored in no-shell mode.
  * - Each call to options() resets to the defaults and merges the provided options; it does not accumulate from prior calls.
  */
-const defaultOptions = {
-	cwd: process.cwd(),
-	env: process.env,
-	shell: 'bash',
-	stdio: ['inherit', 'pipe', 'pipe'],
-	timeout: 0 // when 0 there is no timeout
-};
-
 
 
 class SHDispatch {
 	// #prefix =  'set -euo pipefail;/usr/bin/env'
-	#prefix = 'set -euo pipefail'
+	// #prefix = 'set -euo pipefail'
+	#prefix = '';
 	#cmd = '';
 	#options = {};
 	/** 
@@ -100,23 +92,29 @@ class SHDispatch {
 	#proc;
 	/**
 	* @param {string} cmd - cmd to execute
+	* @param {SHOptions} options
+	* @param {string} [prefix] - command prefix e.g (default) '/usr/bin/env'
 	*/
-	constructor(cmd) {
-		if (!cmd || cmd === '') {
+	constructor(cmd, options, prefix) {
+		if (typeof cmd !== 'string' || cmd === '') {
 			throw new Error('Undefined command');
 		}
 		this.#cmd = cmd;
-		this.#options = defaultOptions
+		this.options(options, prefix);
 	}
 	/**
-	* @param {import('child_process').SpawnOptions | import('child_process').SpawnSyncOptions} options
+	* @param {SHOptions} [options]
 	* @param {string} [prefix] - command prefix e.g (default) '/usr/bin/env'
 	* @returns {SHDispatch}
 	*/
 	options(options, prefix) {
+		// this.#options = defaultOptions
 		if (typeof prefix === 'string') {
 			this.#prefix = prefix;
 		}
+		if (!options) {
+			return this;
+		}
 		if (options.stdio && typeof options.stdio === 'string') {
 			// convert stdio to array
 			// This sets the default io values
@@ -124,7 +122,7 @@ class SHDispatch {
 			const io = options.stdio;
 			options.stdio = Array(3).fill(io);
 		}
-		this.#options = mergeOptions(defaultOptions, options)
+		this.#options = mergeOptions(this.#options, options);
 		return this;
 	}
 

package/module.md

@@ -3,7 +3,7 @@
 ## Overview
 
 **Name:** @j-o-r/sh  
-**Version:** 1.1.23  
+**Version:** 1.1.26  
 **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.
@@ -33,117 +33,196 @@ Requires Node.js >= 20.0.0.
 
 ### 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);
-  });
+const output = await SH`ls -la`.run();
+console.log(output);
 ```
 
 ### Advanced Usage
 
 ```javascript
-import { SH, cd, within, sleep, retry, expBackoff } from '@j-o-r/sh';
+import { SH, cd, within, sleep, retry, expBackoff, userIn } from '@j-o-r/sh';
+
+cd('/tmp'); // Change directory
 
-const res = await SH`ls -FLa | grep package.json | wc -l`.run();
+const res = await SH`echo "Hello World"`.run();
 console.log(res);
 
-const ar = within(async () => {
-  const res = await Promise.all([
+// Retry example
+try {
+  const p = await retry(3, expBackoff(), () => SH`curl -s https://unreachable`.run());
+  console.log(p);
+} catch (e) {
+  console.error('Retry failed:', e);
+}
+
+// User input
+const user = userIn('Enter your name: ');
+const name = await user.input;
+console.log('Hello,', name);
+
+// Within async context
+within(async () => {
+  const results = await Promise.all([
     SH`sleep 1; echo 1`.run(),
     SH`sleep 2; echo 2`.run(),
     sleep(2),
     SH`sleep 3; echo 3`.run()
   ]);
+  console.log(results);
 });
-
-const p = await retry(3, expBackoff(), () => SH`curl -s https://unreachable`.run());
 ```
 
-### Additional Examples
+### Test Framework Example
+
+```javascript
+import { Test, assert, jsType } from '@j-o-r/sh';
+
+const test = new Test();
+test.add('Test type', () => {
+  assert.strictEqual(jsType('string'), 'String');
+});
+const report = await test.run();
+if (report.errors > 0) {
+  process.exit(1);
+}
+```
 
-- Prompt user for input:
-  ```javascript
-  const user = userIn('Enter your name: ');
-  const name = await user.input;
-  console.log('Hello,', name);
-  ```
+### AsyncTracker Example
 
-- Create and run a test:
-  ```javascript
-  import { assert, jsType, Test } from '@j-o-r/sh';
+```javascript
+import { AsyncTracker } 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();
-  ```
+const tracker = new AsyncTracker();
+tracker.enable();
+setTimeout(() => {
+  tracker.report(true); // Verbose report
+}, 1000);
+```
 
 ## 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.
+- **SH**: `(pieces: TemplateStringsArray, ...args: unknown[]) => SHDispatch`
+  - Template tag for creating shell commands. Returns SHDispatch.
+  - Interpolation: Arrays elements trimmed/escaped; non-arrays String(value) as-is (no escape, careful with untrusted input).
+
+- **cd(dir: string)**: `void`
+  - Changes the working directory.
+
+- **sleep(duration: string | number)**: `Promise<any>`
+  - Pauses execution for duration (e.g., '5s', 5000 ms).
+
+- **retry(count: number, a: string | number | typeof expBackoff | Function, b?: Function)**: `Promise<any>`
+  - Retries callback up to `count` times. `a` can be delay, backoff generator, or callback (then `b` is callback).
+
+- **readIn()**: `Promise<string>`
+  - Reads stdin as UTF-8, empty if TTY.
+
+- **userIn(prompt: string)**: `{input: Promise<string | void>, abort: () => void}`
+  - Prompts user for input.
+
+- **within(callback: Function)**: `Promise<any>`
+  - Executes callback in a new execution context.
+
+- **expBackoff(max?: string, rand?: string)**: `Generator<number>`
+  - Yields exponential backoff intervals with jitter (max default '60s', rand '100ms').
+
+- **parseArgs(args?: string[])**: `ArgsObject`
+  - Parses args: --key value, -k value; duplicates error; no =value or grouped shorts; _ for unnamed.
+
+- **jsType(any: any)**: `string`
+  - Returns real JS type name (e.g., 'Array' for []).
+
+- **hasProp(o: any, p: string)**: `boolean`
+  - Safely checks if `o` has own property `p` (handles null/undefined).
+
+- **assert**: `typeof import('node:assert')`
+  - Node.js assert module.
+
+- **Test**: Class - Minimal sync/async test framework (see below).
+
+- **AsyncTracker**: Class - Tracks async operations using Node async_hooks (see below).
 
 ### SHDispatch Class
 
-Returned by the `SH` template tag. Methods:
+`new SHDispatch(cmd: string, options: SHOptions, prefix?: string)`
+
+- **options(options?: SHOptions, prefix?: string)**: `SHDispatch`
+  - Configures execution options, merges with defaults (resets each call).
+
+- **run(payload?: string)**: `Promise<string>`
+  - Executes command asynchronously, returns stdout. Rejects on error/timeout/kill.
 
-- **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.
+- **runSync(payload?: string)**: `import('child_process').SpawnSyncReturns<any>`
+  - Executes synchronously.
+
+- **kill(signal?: string)**: `Promise<number[]>`
+  - Kills the process (and children if possible).
+
+**Defaults/Semantics:**
+- cwd: `process.cwd()`
+- env: `process.env`
+- shell: `'bash'` (use shell if string/true; no shell if false/undefined, uses /usr/bin/env -S)
+- stdio: `['inherit', 'pipe', 'pipe']`
+- timeout: `0` (no timeout)
+- Prefix (e.g., 'set -euo pipefail') applied only with shell.
+- Buffering: Up to 40MiB per stream, truncates with marker.
+- Payload: Writes to stdin (forces pipe).
 
 ### Test Class
 
-For running tests:
+`new Test(quiet?: boolean)` - quiet: no auto-report.
+
+- **syncTimeout(timeout: number)**: `void` - Timeout for sync tests (default 50ms, for async in sync).
+
+- **add(description: string, callback: Function | AsyncFunction)**: `Test`
+  - Adds sync or async test. Throws if conditions fail.
+
+- **run(execute?: number[])**: `Promise<Report>`
+  - Runs all or specified tests (by index).
 
-- **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.
+- **unresolved()**: `void` - Checks/handles unresolved (internal?).
+
+- **reset()**: `void` - Clears tests.
+
+**Types:**
+- `AsyncFunction = () => Promise<any>`
+- `testDefinition = {description: string, callback: Function | AsyncFunction}`
+- `testReport = {description: string, duration: number, executed: boolean}`
+- `Report = {tests: number, duration: number, errors: number, executed: number}`
 
 ### AsyncTracker Class
 
-Tracks async operations:
+`new AsyncTracker()`
+
+- **enable(type?: SystemTypes)**: `void` - Starts tracking all or specific type.
+
+- **disable()**: `void` - Stops tracking.
+
+- **reset()**: `void` - Clears tracked items.
 
-- **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.
+- **report(verbose?: boolean)**: `number` - Logs unresolved, returns count.
 
-### Types
+- **getUnresolved(type?: SystemTypes)**: `AsyncHookItem[]` - Gets unresolved items.
 
-- **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.
+- **getTypeDescription(type: SystemTypes)**: `string` - Description of type.
+
+- **addCustomType(type: string, description: string)**: `void` - Adds custom type desc.
+
+**Types:**
+- `AsyncHookItem = {key: number, type: string, triggerAsyncId: number, stack: string, resource: SystemTypes}`
+- `SystemTypes` = "PROMISE" | "TIMEOUT" | ... (full Node async resource types)
+
+### Other Types
+
+- `ArgsObject = {[x: string]: string}` (with `_`: string[] for unnamed)
+- `SpawnSyncResponse = {status: number|null, signal: string|null, output: (string|Buffer|null)[], pid: number, stdout: string|Buffer|null, stderr: string|Buffer|null}`
+- `SHOptions` extends `SpawnOptions` & `{maxBuffer?: number, input?: string|Uint8Array|Buffer}`
+- `StdioOption = "pipe" | "ignore" | "inherit" | number`
 
 ## Dependencies
 
@@ -151,4 +230,3 @@ Tracks async operations:
 
 **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.25",
+  "version": "1.1.27",
   "description": "Execute shell commands on Linux-based systems from javascript",
   "main": "lib/SH.js",
   "types": "types/SH.d.ts",

package/types/SH.d.ts

@@ -11,7 +11,22 @@ export type Shell = Function;
  * A template-tag that returns an SHDispatch.
  */
 export type SHTag = (pieces: TemplateStringsArray, ...args: unknown[]) => SHDispatch;
-export function SH(pieces: any, ...args: any[]): SHDispatch;
+/**
+* A template-tag that returns an SHDispatch.
+* @typedef {(pieces: TemplateStringsArray, ...args: unknown[]) => SHDispatch} SHTag
+*/
+/**
+* SH template tag
+*
+* Interpolation rules:
+* - Arrays: each element is String(x).trim(), with newlines/carriage returns/tabs escaped; if an element contains shell metacharacters or spaces, it is wrapped in single-quotes and internal single-quotes are escaped as '\''.
+* - Non-array values: currently coerced with String(value) and inserted as-is (NOT shell-escaped). Be careful when interpolating untrusted input.
+*
+* @type {Shell & SHTag & defaultOptions}
+* Returns an SHDispatch that can be configured via .options() and executed with .run() / .runSync().
+* @returns {SHDispatch}
+*/
+export const SH: Shell & SHTag & import("./SHDispatch.js").SHOptions;
 /**
 * Change working directory
 * @param {string} dir
@@ -172,5 +187,12 @@ export function hasProp(o: any, p: string): boolean;
 import Test from './Test.js';
 import assert from 'node:assert';
 import AsyncTracker from './AsyncTracker.js';
+/**
+* bash escape a string suitable as an argument on the commandline
+* for javascript code
+* @param {string} x
+* @returns {string}
+*/
+export function bashEscape(x: string): string;
 import SHDispatch from './SHDispatch.js';
 export { Test, assert, AsyncTracker };

package/types/SHDispatch.d.ts

@@ -69,17 +69,34 @@ export type SHOptions = {
 };
 export type StdioOption = ("pipe" | "ignore" | "inherit" | number);
 export type StdioOptions = Array<StdioOption> | StdioOption;
+/**
+ * SHOptions — effective defaults and semantics used by SHDispatch/SHExecute
+ *
+ * Defaults:
+ * - cwd: process.cwd()
+ * - env: process.env
+ * - shell: 'bash' (string). If a string, that shell is used. If true, 'bash' is used. If false/undefined, no shell is used.
+ * - stdio: ['inherit', 'pipe', 'pipe'] — inherit stdin, capture stdout/stderr
+ * - timeout: 0 — no timeout
+ * - maxBuffer?: number — optional (bytes per stream). Passed through to SHExecute.
+ *
+ * Notes:
+ * - The prefix (see options(prefix)) is only applied when a shell is used; it is ignored in no-shell mode.
+ * - Each call to options() resets to the defaults and merges the provided options; it does not accumulate from prior calls.
+ */
 declare class SHDispatch {
     /**
     * @param {string} cmd - cmd to execute
+    * @param {SHOptions} options
+    * @param {string} [prefix] - command prefix e.g (default) '/usr/bin/env'
     */
-    constructor(cmd: string);
+    constructor(cmd: string, options: SHOptions, prefix?: string);
     /**
-    * @param {import('child_process').SpawnOptions | import('child_process').SpawnSyncOptions} options
+    * @param {SHOptions} [options]
     * @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): SHDispatch;
+    options(options?: SHOptions, prefix?: string): SHDispatch;
     /**
     * @param {string} [payload]
     * @returns {Promise<string>}