@j-o-r/sh 0.0.3 → 1.0.0

package/lib/ProcessOutput.js

@@ -1,113 +0,0 @@
-// Copyright 2021 Google LLC
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     https://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-// 
-//
-// Original Source: zx
-// Link to Original Source: https://github.com/google/zx
-// Reason for Using This Code: 
-// The core functionality of this code is highly beneficial. However, certain parts of the original code 
-// were overwriting the global namespace with core libraries and variables. This was causing conflicts with 
-// other packages (for instance, fetch) and introducing unexpected elements into my code base.
-// Changes Made: 
-// - The code has been or is being reformatted to comply with ES2020 standards.
-// - Some methods were added and existing ones were modified to enhance usability.
-// - The namespace has been changed from '$' to 'SH'.
-// Modified by: jorrit.duin+sh[AT]gmail.com
-
-import { inspect } from 'node:util';
-import { exitCodeInfo} from './utils.js';
-
-/**
-* 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.
-*/
-class ProcessOutput extends Error {
-	#code = 0;
-	#signal;
-	#stdout = '';
-	#stderr = '';
-	#combined = '';
-	/**
-	* @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, signal, stdout = '', stderr = '', combined = '', message = '') {
-		super(message);
-		this.#code = code;
-		this.#signal = signal;
-		this.#stdout = stdout;
-		this.#stderr = stderr;
-		this.#combined = combined;
-		this.name = 'ProcessOutput';
-	}
-	/**
-	* This string represents the standard output (stdout) from the child process.
-	* @returns {string}
-	*/
-	get stdout() {
-		return this.#stdout;
-	}
-	/**
-	* This string represents the error output (stderr) from the child process.
-	* @returns {string}
-	*/
-	get stderr() {
-		return this.#stderr;
-	}
-
-	/**
-	* This is an internal method that is often invoked automatically 
-	* by various JavaScript methods. 
-	* It consolidates the entire output for completeness and facilitates further processing.
-	* 
-	* @returns {string} The consolidated output as a
-	*/
-	toString() {
-		return this.#combined.trim();
-	}
-	/**
-	* This represents the exit code returned by the external process.
-	* @returns {number} The exit
-	*/
-	get exitCode() {
-		return this.#code;
-	}
-	/**
-	* This represents the exit signal, for example, "SIGTERM", received from the child process.
-	* @returns {string} The exit signal from the child
-	*/
-	get signal() {
-		return this.#signal;
-	}
- 	/** 
-	* This method is used for debugging purposes. It displays the current state of the object
-	* when passed to the console.log function.
-	*/
- 	[inspect.custom]() {
- 		let stringify = (s) => s.length === 0 ? "''" : inspect(s);
- 		return `ProcessOutput {
-    stdout: ${stringify(this.stdout)},
-    stderr: ${stringify(this.stderr)},
-    signal: ${inspect(this.signal)},
-    exitCode: ${(this.exitCode)}${exitCodeInfo(this.exitCode)
- 				? ' (' + exitCodeInfo(this.exitCode) + ')'
- 				: ''}
-  }`;
- 	}
-}
-export default ProcessOutput;

package/lib/ProcessPromise.d.ts

@@ -1,147 +0,0 @@
-/// <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/lib/ProcessPromise.js

@@ -1,354 +0,0 @@
-// Copyright 2021 Google LLC
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     https://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-// 
-//
-// Original Source: zx
-// Link to Original Source: https://github.com/google/zx
-// Reason for Using This Code: 
-// The core functionality of this code is highly beneficial. However, certain parts of the original code 
-// were overwriting the global namespace with core libraries and variables. This was causing conflicts with 
-// other packages (for instance, fetch) and introducing unexpected elements into my code base.
-// Changes Made: 
-// - The code has been or is being reformatted to comply with ES2020 standards.
-// - Some methods were added and existing ones were modified to enhance usability.
-// - The namespace has been changed from '$' to 'SH'.
-// Modified by: jorrit.duin+sh[AT]gmail.com
-
-// import { spawn, exec } from 'node:child_process';
-import assert from 'node:assert';
-import { killProcesses, spawn, log, errnoMessage, exitCodeInfo, noop, parseDuration } from './utils.js';
-import ProcessOutput from './ProcessOutput.js';
-
-/** 
-* @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
-*/
-class ProcessPromise extends Promise {
-	#command = '';
-	#from = '';
-	/** @type {resolver} */
-	#resolve = () => { };
-	/** @type {rejecter} */
-	#reject = () => { };
-	#snapshot = {};
-	/** @type {StdioOptions} */
-	#stdio = ['inherit', 'pipe', 'pipe'];
-	#nothrow = false;
-	#quiet = false;
-	#resolved = false;
-	#halted = false;
-	#piped = false;
-	#prerun = noop;
-	#postrun = noop;
-	/**
-	* @param {PromiseConstruct} p - A function that takes two arguments, resolve and reject.
-	*/
-	constructor(p) {
-		// @ts-ignore
-		super(p)
-	}
-	/**
-	* 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, from, resolve, reject, options) {
-		this.#command = cmd;
-		this.#from = from;
-		this.#resolve = resolve;
-		this.#reject = reject;
-		this.#snapshot = { ...options };
-	}
-	/**
-	* Run the promise
-	*/
-	run() {
-		const ENV = this.#snapshot;
-		if (this.child) return this; // The _run() can be called from a few places.
-		this.#prerun(); // In case $1.pipe($2), the $2 returned, and on $2._run() invoke $1._run().
-		log({
-			kind: 'cmd',
-			cmd: this.#command,
-			verbose: ENV.verbose && !this.#quiet,
-		});
-		const cwd = ENV['processCwd'];
-		const shell = ENV['shell'];
-		this.child = spawn(ENV.prefix, [this.#command], {
-			cwd,
-			shell,
-			// @ts-ignore
-			stdio: this.#stdio,
-			windowsHide: true,
-			env: ENV.env,
-		});
-		this.child.on('close', (code, signal) => {
-			let message = `exit code: ${code}`;
-			if (code != 0 || signal != null) {
-				message = `${stderr || '\n'}    at ${this.#from}`;
-				message += `\n    exit code: ${code}${exitCodeInfo(code) ? ' (' + exitCodeInfo(code) + ')' : ''}`;
-				if (signal != null) {
-					message += `\n    signal: ${signal}`;
-				}
-			}
-			let output = new ProcessOutput(code, signal, stdout, stderr, combined, message);
-			if (code === 0 || this.#nothrow) {
-				this.#resolve(output);
-			}
-			else {
-				this.#reject(output);
-			}
-			this.#resolved = true;
-		});
-		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));
-			this.#resolved = true;
-		});
-		let stdout = '', stderr = '', combined = '';
-		/** @param {Blob} data */
-		const onStdout = (data) => {
-			log({ kind: 'stdout', data, verbose: ENV.verbose && !this.#quiet });
-			stdout += data;
-			combined += data;
-		};
-		/** @param {Blob} data */
-		const onStderr = (data) => {
-			log({ kind: 'stderr', data, verbose: ENV.verbose && !this.#quiet });
-			stderr += data;
-			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) {
-			const t = setTimeout(() => this.kill(this._timeoutSignal), this._timeout);
-			this.finally(() => clearTimeout(t)).catch(noop);
-		}
-		return this;
-	}
-	/**
-	* stdin child stream
-	* @retruns {Writeable}
-	*/
-	get stdin() {
-		this.stdio('pipe');
-		this.run();
-		assert(this.child);
-		if (this.child.stdin == null)
-			throw new Error('The stdin of subprocess is null.');
-		return this.child.stdin;
-	}
-	/**
-	* stdout child stream
-	* @retruns {Readable}
-	*/
-	get stdout() {
-		this.run();
-		assert(this.child);
-		if (this.child.stdout == null)
-			throw new Error('The stdout of subprocess is null.');
-		return this.child.stdout;
-	}
-	/**
-	* stderr child stream
-	* @retruns {Readable}
-	*/
-	get stderr() {
-		this.run();
-		assert(this.child);
-		if (this.child.stderr == null)
-			throw new Error('The stderr of subprocess is null.');
-		return this.child.stderr;
-	}
-	/**
-	* process exit code
-	* @returns {Promise<number>}
-	*/
-	get exitCode() {
-		return this.#then((p) => p.exitCode, (p) => p.exitCode);
-	}
-	#then(onfulfilled, onrejected) {
-		if (this.isHalted && !this.child) {
-			throw new Error('The process is halted!');
-		}
-		return super.then(onfulfilled, onrejected);
-	}
-	catch(onrejected) {
-		return super.catch(onrejected);
-	}
-	/**
-	* Pipe the output to the input to the next Promise
-	* @example
-	* const res = await SH`ls -FLa`.pipe(SH`grep package.json`);
-	*/
-	pipe(dest) {
-		if (typeof dest == 'string')
-			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!");
-		}
-		this.#piped = true;
-		if (dest instanceof ProcessPromise) {
-			dest.stdio('pipe');
-			dest._prerun = this.run.bind(this);
-			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;
-		}
-	}
-	/**
-	* Send a KILL signal to the child process
-	* @returns {Promise<number[]>} the pid numbers that has been killed
-	*/
-	async kill(signal = 'SIGTERM') {
-		if (!this.child)
-			throw new Error('Trying to kill a process without creating one.');
-		if (!this.child.pid)
-			throw new Error('The process pid is undefined.');
-
-		return await killProcesses(this.child.pid, signal)
-	}
-	stdio(stdin, stdout = 'pipe', stderr = 'pipe') {
-		this.#stdio = [stdin, stdout, stderr];
-		return this;
-	}
-	/**
-	* Do not throw
-	*/
-	nothrow() {
-		this.#nothrow = true;
-		return this;
-	}
-	/**
-	* supress log output
-	* SH.verbose = false; does the same
-	*/
-	quiet() {
-		this.#quiet = true;
-		return this;
-	}
-	/**
-	* Show log output in the console
-	*/
-	verbose() {
-		this._quiet = false;
-		return this;
-	}
-	/** 
-	* 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, signal = 'SIGTERM') {
-		this._timeout = parseDuration(d);
-		this._timeoutSignal = signal;
-		return this;
-	}
-	/**
-	* stop execution for the next step
-	*/
-	halt() {
-		this.#halted = true;
-		return this;
-	}
-	/** 
-	* @private
-	* Set a prerun action, internal use only
-	* @param {function} f
-	*/
-	set _prerun(f) {
-		// @ts-ignore
-		this.#prerun = f;
-	}
-	/** 
-	* @private
-	* Set a postrun action, internal use only
-	* @param {function} f
-	*/
-	set _postrun(f) {
-		// @ts-ignore
-		this.#postrun = f;
-	}
-	/**
-	* Is this promise halted?
-	* @returns {boolean}
-	*/
-	get isHalted() {
-		return this.#halted;
-	}
-}
-export default ProcessPromise;

package/lib/utils.d.ts

@@ -1,20 +0,0 @@
-/// <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';