@j-o-r/sh 0.0.2 → 0.0.3

package/README.md

@@ -2,8 +2,6 @@
 
 Execute shell commands from JavaScript.
 
-![Alt text](https://raw.githubusercontent.com/j-o-r/sh/main/jor-sh.png "logo")
-
 ## Introduction
 
 BETA
@@ -52,7 +50,7 @@ const ar = within(async () => {
 	]);
 });
 
-``` 
+```
 
 ```javascript
 const p = await retry(3, expBackoff(), () => SH`curl -s https://unreachable:`);
@@ -111,8 +109,8 @@ The `ProcessOutput` class collects output from the `ProcessPromise` shell proces
 
 ### Methods
 
-- **toString()**: 
-  - Returns a trimmed string combining `stderr` and `stdout`. 
+- **toString()**:
+  - Returns a trimmed string combining `stderr` and `stdout`.
   - This method is automatically invoked by various JavaScript methods for output consolidation.
 - **[inspect.custom]()**:
   - Custom inspection method used for debugging.
@@ -120,13 +118,9 @@ The `ProcessOutput` class collects output from the `ProcessPromise` shell proces
 
 ### Examples
 
-- Script for setting up my wokspace in [TMUX](./workspace.js)
+- Script for setting up a wokspace in [TMUX](./workspace.js)
 - Take a look at the [test](./test/sh.js)
 
-## Contributing
-
-Contributions are welcome. Please submit issues and pull requests on our [GitHub repository](https://github.com/j-o-r/sh).
-
 ## License
 
 This project is licensed under the Apache License, Version 2.0.

package/lib/ProcessOutput.d.ts

@@ -0,0 +1,44 @@
+/// <reference types="node" />
+export default ProcessOutput;
+/**
+* The ProcessPromise returns a ProcessOutput even when it fails, by rejecting it.
+* The extension of the Error class is implemented to ensure compatibility when an Error is expected upon rejection.
+*/
+declare class ProcessOutput extends Error {
+    /**
+    * @param {number} code - exit code
+    * @param {string} signal - SIGTERM ...
+    * @param {string} stdout - std reponse string
+    * @param {string} stderr - error reponse string
+    * @param {string} combined - stderr + stdout
+    * @param {string} message - Error message
+    */
+    constructor(code: number, signal: string, stdout?: string, stderr?: string, combined?: string, message?: string);
+    /**
+    * This string represents the standard output (stdout) from the child process.
+    * @returns {string}
+    */
+    get stdout(): string;
+    /**
+    * This string represents the error output (stderr) from the child process.
+    * @returns {string}
+    */
+    get stderr(): string;
+    /**
+    * This represents the exit code returned by the external process.
+    * @returns {number} The exit
+    */
+    get exitCode(): number;
+    /**
+    * This represents the exit signal, for example, "SIGTERM", received from the child process.
+    * @returns {string} The exit signal from the child
+    */
+    get signal(): string;
+    /**
+    * This method is used for debugging purposes. It displays the current state of the object
+    * when passed to the console.log function.
+    */
+    [inspect.custom](): string;
+    #private;
+}
+import { inspect } from 'node:util';

package/lib/ProcessPromise.d.ts

@@ -0,0 +1,147 @@
+/// <reference types="node" />
+/// <reference types="node" />
+export default ProcessPromise;
+export type resolver = Function;
+export type rejecter = Function;
+export type PromiseConstruct = Function;
+export type StdioOption = ('pipe' | 'ignore' | 'inherit' | number);
+export type StdioOptions = Array<StdioOption> | StdioOption;
+/**
+* @typedef {Function} resolver
+* @param {ProcessOutput} value
+*/
+/**
+* @typedef {Function} rejecter
+* @param {ProcessOutput} value
+*/
+/**
+* @typedef {Function} PromiseConstruct
+* @param {resolver} resolve
+* @param {rejecter} reject
+*/
+/**
+ * @typedef {('pipe' | 'ignore' | 'inherit' | number)} StdioOption
+ * @description Defines the stdio configuration for each of the standard streams.
+ *
+ * - 'pipe' creates a pipe between the child process and the parent process.
+ *   The parent end of the pipe is exposed as a property on the `ChildProcess` object.
+ * - 'ignore' indicates that the child process's corresponding stdio file descriptor will be ignored.
+ * - 'inherit' passes the corresponding stdio stream to/from the child process.
+ * - Stream object to be used for the stdio stream.
+ * - Positive integer representing a file descriptor to be used for the stdio stream.
+ */
+/**
+ * @typedef {Array<StdioOption>|StdioOption} StdioOptions
+ * @description
+ * Configures the stdio streams for the child process. This can be an array or a single StdioOption.
+ *
+ * Array Form: Specify the configuration for [stdin, stdout, stderr].
+ *   - If array length is more than 3, additional positions correspond to extra streams.
+ * Single Value: This value will be applied to stdin, stdout, and stderr.
+ *
+ * Examples:
+ * - ['pipe', 'pipe', 'ignore']: Pipe stdin and stdout, ignore stderr.
+ * - 'inherit': Inherit all stdio streams from the parent.
+ */
+/**
+* class extends promise
+*/
+declare class ProcessPromise extends Promise<any> {
+    /**
+    * @param {PromiseConstruct} p - A function that takes two arguments, resolve and reject.
+    */
+    constructor(p: PromiseConstruct);
+    /**
+    * Set the environment
+    * and the
+    * @param {string} cmd - Command to execute
+    * @param {string} from - Position in the codfe where this is triggred from
+    * @param {function} resolve - Promise resolve method
+    * @param {function} reject - Reject method
+    * @param {object} options - Settings (options default)
+    */
+    _bind(cmd: string, from: string, resolve: Function, reject: Function, options: object): void;
+    /**
+    * Run the promise
+    */
+    run(): this;
+    child: import("child_process").ChildProcessWithoutNullStreams & import("child_process").ChildProcessByStdio<import("stream").Writable, import("stream").Readable, import("stream").Readable> & import("child_process").ChildProcessByStdio<import("stream").Writable, import("stream").Readable, null> & import("child_process").ChildProcessByStdio<import("stream").Writable, null, import("stream").Readable> & import("child_process").ChildProcessByStdio<null, import("stream").Readable, import("stream").Readable> & import("child_process").ChildProcessByStdio<import("stream").Writable, null, null> & import("child_process").ChildProcessByStdio<null, import("stream").Readable, null> & import("child_process").ChildProcessByStdio<null, null, import("stream").Readable> & import("child_process").ChildProcessByStdio<null, null, null> & import("child_process").ChildProcess;
+    /**
+    * stdin child stream
+    * @retruns {Writeable}
+    */
+    get stdin(): null;
+    /**
+    * stdout child stream
+    * @retruns {Readable}
+    */
+    get stdout(): null;
+    /**
+    * stderr child stream
+    * @retruns {Readable}
+    */
+    get stderr(): null;
+    /**
+    * process exit code
+    * @returns {Promise<number>}
+    */
+    get exitCode(): Promise<number>;
+    catch(onrejected: any): Promise<any>;
+    /**
+    * Pipe the output to the input to the next Promise
+    * @example
+    * const res = await SH`ls -FLa`.pipe(SH`grep package.json`);
+    */
+    pipe(dest: any): ProcessPromise;
+    /**
+    * @private
+    * Set a postrun action, internal use only
+    * @param {function} f
+    */
+    private set _postrun(f);
+    /**
+    * Send a KILL signal to the child process
+    * @returns {Promise<number[]>} the pid numbers that has been killed
+    */
+    kill(signal?: string): Promise<number[]>;
+    stdio(stdin: any, stdout?: string, stderr?: string): this;
+    /**
+    * Do not throw
+    */
+    nothrow(): this;
+    /**
+    * supress log output
+    * SH.verbose = false; does the same
+    */
+    quiet(): this;
+    /**
+    * Show log output in the console
+    */
+    verbose(): this;
+    _quiet: boolean;
+    /**
+    * Set a timeout to kill a process
+    *
+    * @param {string} d - 10s, 1000ms
+    * @param {string} [signal] - default "SIGTERM" Signal to send to kill the proces
+    */
+    timeout(d: string, signal?: string): this;
+    _timeout: number;
+    _timeoutSignal: string;
+    /**
+    * stop execution for the next step
+    */
+    halt(): this;
+    /**
+    * @private
+    * Set a prerun action, internal use only
+    * @param {function} f
+    */
+    private set _prerun(f);
+    /**
+    * Is this promise halted?
+    * @returns {boolean}
+    */
+    get isHalted(): boolean;
+    #private;
+}

package/{src → lib}/ProcessPromise.js

@@ -44,7 +44,7 @@ import ProcessOutput from './ProcessOutput.js';
 * @param {rejecter} reject
 */
 /**
- * @typedef {('pipe' | 'ignore' | 'inherit' | Stream | number)} StdioOption
+ * @typedef {('pipe' | 'ignore' | 'inherit' | number)} StdioOption
  * @description Defines the stdio configuration for each of the standard streams.
  * 
  * - 'pipe' creates a pipe between the child process and the parent process. 
@@ -68,6 +68,10 @@ import ProcessOutput from './ProcessOutput.js';
  * - ['pipe', 'pipe', 'ignore']: Pipe stdin and stdout, ignore stderr.
  * - 'inherit': Inherit all stdio streams from the parent.
  */
+
+/**
+* class extends promise
+*/
 class ProcessPromise extends Promise {
 	#command = '';
 	#from = '';
@@ -89,6 +93,7 @@ class ProcessPromise extends Promise {
 	* @param {PromiseConstruct} p - A function that takes two arguments, resolve and reject.
 	*/
 	constructor(p) {
+		// @ts-ignore
 		super(p)
 	}
 	/**
@@ -124,6 +129,7 @@ class ProcessPromise extends Promise {
 		this.child = spawn(ENV.prefix, [this.#command], {
 			cwd,
 			shell,
+			// @ts-ignore
 			stdio: this.#stdio,
 			windowsHide: true,
 			env: ENV.env,
@@ -148,7 +154,9 @@ class ProcessPromise extends Promise {
 		});
 		this.child.on('error', (err) => {
 			const message = `${err.message}\n` +
+				// @ts-ignore
 				`    errno: ${err.errno} (${errnoMessage(err.errno)})\n` +
+				// @ts-ignore
 				`    code: ${err.code}\n` +
 				`    at ${this.#from}`;
 			this.#reject(new ProcessOutput(null, null, stdout, stderr, combined, message));
@@ -168,7 +176,9 @@ class ProcessPromise extends Promise {
 			combined += data;
 		};
 		if (!this.#piped)
+			// @ts-ignore
 			this.child.stdout?.on('data', onStdout); // If process is piped, don't collect or print output.
+		// @ts-ignore
 		this.child.stderr?.on('data', onStderr); // Stderr should be printed regardless of piping.
 		this.#postrun(); // In case $1.pipe($2), after both subprocesses are running, we can pipe $1.stdout to $2.stdin.
 		if (this._timeout && this._timeoutSignal) {
@@ -216,9 +226,9 @@ class ProcessPromise extends Promise {
 	* @returns {Promise<number>}
 	*/
 	get exitCode() {
-		return this.then((p) => p.exitCode, (p) => p.exitCode);
+		return this.#then((p) => p.exitCode, (p) => p.exitCode);
 	}
-	then(onfulfilled, onrejected) {
+	#then(onfulfilled, onrejected) {
 		if (this.isHalted && !this.child) {
 			throw new Error('The process is halted!');
 		}
@@ -237,6 +247,7 @@ class ProcessPromise extends Promise {
 			throw new Error('The pipe() method does not take strings. Forgot SH?');
 		if (this.#resolved) {
 			if (dest instanceof ProcessPromise)
+				// @ts-ignore
 				dest.stdin.end(); // In case of piped stdin, we may want to close stdin of dest as well.
 			throw new Error("The pipe() method shouldn't be called after promise is already resolved!");
 		}
@@ -247,11 +258,13 @@ class ProcessPromise extends Promise {
 			dest._postrun = () => {
 				if (!dest.child)
 					throw new Error('Access to stdin of pipe destination without creation a subprocess.');
+				// @ts-ignore
 				this.stdout.pipe(dest.stdin);
 			};
 			return dest;
 		}
 		else {
+			// @ts-ignore
 			this._postrun = () => this.stdout.pipe(dest);
 			return this;
 		}

package/lib/sh.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Creates a new ProcessPromise object that represents a command to be executed.
+ */
+export type Shell = Function;
+/**
+ * Creates a new ProcessPromise object that represents a command to be executed.
+ *
+ * @typedef {Function} Shell
+ * @property {function(Array, ...*): ProcessPromise} execute - The function to execute the command.
+ * @property {boolean} verbose - A property to control verbosity.
+ *
+ * @param {Array} pieces - An array of string literals from a template literal.
+ * @param {...*} args - The values to be interpolated into the string literals.
+ * @returns {ProcessPromise} A ProcessPromise object that represents 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!'`;
+ */
+/** @type {Shell & { (pieces: TemplateStringsArray, ...args: any[]): ProcessPromise }} */
+export const SH: Function & ((pieces: TemplateStringsArray, ...args: any[]) => ProcessPromise);
+/**
+* Change working directory
+* @param {string} dir
+*/
+export function cd(dir: string): void;
+/**
+* This function pauses or "sleeps" code execution for a specified duration.
+* @param {string|number} duration - The duration to pause execution for, e.g., '100ms' or '3s'.
+*
+* @example
+*
+* const res = await Promise.all([
+* 	SH`sleep 2; echo 2`,  // Sleep for 2 seconds
+* 	sleep(2),             // Sleep for 2 seconds
+* 	SH`sleep 3; echo 3`   // Sleep for 3 seconds
+* ]);
+*/
+export function sleep(duration: string | number): Promise<any>;
+/**
+* This function retries a command a specified number of times.
+* @example
+* // Retry a command 3 times
+* const p = await retry(3, () => SH`curl -s https://flipwrsi`);
+*
+* // Retry a command 3 times with an interval of 1 second between each try
+* const p = await retry(3, '1s', () => SH`curl -s https://flipwrsi`);
+*
+* // 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: any, a: any, b: any): Promise<any>;
+/**
+* This function reads the standard input (stdin) for the current process.
+* It is used to get piped content into a script.
+* @example
+* const content = await stdin();
+*/
+export function stdin(): Promise<string>;
+/**
+* Create a async context in an sync block
+* @param {function} callback - async function
+* @example
+* const p = within(async () => {
+*		const res = await Promise.all([
+*			SH`sleep 1; echo 1`,
+*			SH`sleep 2; echo 2`,
+*			sleep(2),
+*			SH`sleep 3; echo 3`
+*		]);
+*/
+export function within(callback: Function): any;
+export function expBackoff(max?: string, rand?: string): Generator<number, void, unknown>;
+import ProcessPromise from './ProcessPromise.js';

package/{src → lib}/sh.js

@@ -29,7 +29,6 @@ import assert from 'node:assert';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { log, parseDuration, quote, quotePowerShell, } from './utils.js';
 import ProcessPromise from './ProcessPromise.js';
-// const processCwd = Symbol('processCwd');
 const storage = new AsyncLocalStorage();
 
 const defaults = {
@@ -43,6 +42,7 @@ defaults.prefix = 'set -euo pipefail;/usr/bin/env';
 
 /**
 * Escape CLI arguments
+* @param {string[]} arg
 * @retruns {string}
 */
 const sanitizeArg = (arg) => {
@@ -56,23 +56,23 @@ const sanitizeArg = (arg) => {
 const getStore = () => {
 	return storage.getStore() || defaults;
 }
-
 /**
-* Creates a new ProcessPromise object that represents a command to be executed.
-*
-* @typedef {Function} Shell
-* @type {function}
-* @param {Array} pieces - An array of string literals from a template literal.
-* @param {...*} args - The values to be interpolated into the string literals.
-* @returns {ProcessPromise} A ProcessPromise object that represents the command.
-* @throws {Error} Throws an error if any of the string literals in `pieces` is undefined.
-*
-* @property {boolean} verbose
-*
-* @example
-* const command = await SH`echo 'Hello, world!'`;
-*/
-/** @type {Shell} */
+ * Creates a new ProcessPromise object that represents a command to be executed.
+ *
+ * @typedef {Function} Shell
+ * @property {function(Array, ...*): ProcessPromise} execute - The function to execute the command.
+ * @property {boolean} verbose - A property to control verbosity.
+ *
+ * @param {Array} pieces - An array of string literals from a template literal.
+ * @param {...*} args - The values to be interpolated into the string literals.
+ * @returns {ProcessPromise} A ProcessPromise object that represents 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!'`;
+ */
+/** @type {Shell & { (pieces: TemplateStringsArray, ...args: any[]): ProcessPromise }} */
+// @ts-ignore
 const SH = new Proxy(function(pieces, ...args) {
 	const from = new Error().stack.split(/^\s*at\s/m)[2].trim();
 	if (pieces.some((p) => p == undefined)) {
@@ -172,7 +172,6 @@ const retry = async (count, a, b) => {
 		else {
 			delayStatic = parseDuration(a);
 		}
-		// console.log(assert(b));
 		assert(b);
 		callback = b;
 	}
@@ -206,7 +205,7 @@ const retry = async (count, a, b) => {
 }
 /**
 * This function pauses or "sleeps" code execution for a specified duration.
-* @param {string} duration - The duration to pause execution for, e.g., '100ms' or '3s'.
+* @param {string|number} duration - The duration to pause execution for, e.g., '100ms' or '3s'.
 * 
 * @example
 * 
@@ -245,7 +244,6 @@ function* expBackoff(max = '60s', rand = '100ms') {
 // 		process.chdir(SH['processCwd']);
 // }
 export {
-	/** @type {Shell} */
 	SH,
 	cd,
 	sleep,

package/lib/utils.d.ts

@@ -0,0 +1,20 @@
+/// <reference types="node" />
+/**
+* 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.
+* @retruns {Promise<number[]>} array with killed pid numbers
+*/
+export function killProcesses(processPid: number, signal: string): Promise<any>;
+export function noop(): void;
+export function randomId(): string;
+export function isString(obj: any): boolean;
+export function quote(arg: any): any;
+export function quotePowerShell(arg: any): any;
+export function log(entry: any): void;
+export function exitCodeInfo(exitCode: any): any;
+export function errnoMessage(errno: any): any;
+export function parseDuration(d: any): number;
+export function formatCmd(cmd: any): string;
+export { spawn };
+import { spawn } from 'node:child_process';

package/package.json

@@ -1,19 +1,23 @@
 {
   "name": "@j-o-r/sh",
-  "author": "Jorrit Duin <jorrit.duin@gmail.com>",
+  "author": "Jorrit Duin <j-o-r@duin.work>",
   "type": "module",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "Execute shell commands on Linux-based systems from javascript",
-  "main": "src/sh.js",
+  "main": "lib/sh.js",
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=20.0.0"
   },
   "scripts": {
-    "test": "test/sh.js"
+    "test": "test/sh.js",
+    "publish": "npm run release && npm publish --access public",
+    "release": "npm pack --pack-destination=release",
+    "clear:types": "rm lib/*.d.ts",
+    "types": "tsc lib/*.js --declaration --allowJs --emitDeclarationOnly"
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/j-o-r/sh.git"
+    "url": "https://codeberg.org/duin/sh"
   },
   "license": "Apache License, Version 2.0",
   "dependencies": {},
@@ -22,9 +26,9 @@
     "uvu": "^0.5.6"
   },
   "bugs": {
-    "url": "https://github.com/j-o-r/sh/issues"
+    "url": "https://codeberg.org/duin/sh/issues"
   },
-  "homepage": "https://github.com/j-o-r/sh",
+  "homepage": "https://codeberg.org/duin",
   "keywords": [
     "shell",
     "posix",