@j-o-r/sh 0.0.4 → 1.0.0

package/README.md

@@ -4,9 +4,7 @@ Execute shell commands from JavaScript.
 
 ## Introduction
 
-BETA
-
-This Node.js module, `@j-o-r/sh`, simplifies the execution of shell commands within JavaScript applications. It provides a range of utilities to handle shell scripts and manage their output efficiently.
+`@j-o-r/sh` is a Node.js module that simplifies the execution of shell commands within JavaScript applications. It provides a range of utilities to handle shell scripts and manage their output efficiently.
 
 This project draws inspiration from the exceptional [zx library](https://github.com/google/zx). The core functionality of zx, particularly the shell execution method, has been extracted and forms the foundation of this project.
 
@@ -27,7 +25,7 @@ To execute a shell command, use the `SH` function:
 ```javascript
 import { SH, cd, within, sleep, retry, expBackoff } from '@j-o-r/sh';
 
-SH`your_shell_command`
+SH`your_shell_command`.run()
   .then(output => {
     console.log('Output:', output);
   })
@@ -36,27 +34,28 @@ SH`your_shell_command`
   });
 ```
 
-```javascript
+### Advanced Usage
 
-const res = await SH`ls -FLa`.pipe(SH`grep package.json`);
-console.log(res.toString());
+```javascript
+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`,
-		SH`sleep 2; echo 2`,
-		sleep(2),
-		SH`sleep 3; echo 3`
-	]);
+  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()
+  ]);
 });
-
 ```
 
 ```javascript
-const p = await retry(3, expBackoff(), () => SH`curl -s https://unreachable:`);
+const p = await retry(3, expBackoff(), () => SH`curl -s https://unreachable`.run());
 ```
 
-The `SH` method accepts a template literal string enclosed in backticks as its argument. It returns a `ProcessPromise`. Once this promise is resolved, it yields a `ProcessOutput` object.
+The `SH` method accepts a template literal string enclosed in backticks as its argument. It returns an `SHDispatch` object.
+
 ### Additional Utilities
 
 The module also provides additional utilities for common tasks:
@@ -64,64 +63,57 @@ The module also provides additional utilities for common tasks:
 - `cd(dir)`: Change the working directory.
 - `sleep(duration)`: Pause execution for a specified duration.
 - `retry(count, interval, callback)`: Retry a command a specified number of times with an optional interval.
-- `stdin()`: Read from standard input.
+- `readIn()`: Read from standard input.
 - `within(callback)`: Create an async context in a sync block.
 - `expBackoff(max, rand)`: Generate intervals for exponential backoff.
 
+## SHDispatch
 
-## ProcessPromise
-
-This class is returned by the shell command. Here's a summary of its methods and properties:
+This class is returned by the `SH` function. Here's a summary of its methods and properties:
 
 ### Methods
 
-- **pipe(dest)**: Pipes the output of this process to the input of another `ProcessPromise`
-- **kill(signal = 'SIGTERM')**: Sends a kill signal to the child process.
-- **stdio(stdin, stdout, stderr)**: Sets the standard input/output/error streams for the child process.
-- **nothrow()**: Configures the promise not to throw an error when the command execution fails.
-- **quiet()**: Suppresses log output.
-- **verbose()**: Enables verbose log output.
-- **timeout(d, signal = 'SIGTERM')**: Sets a timeout for killing the process.
-- **halt()**: Stops the execution of the next step in the process.
-
-### Getters
-
-- **stdin**: Returns the standard input stream of the child process.
-- **stdout**: Returns the standard output stream of the child process.
-- **stderr**: Returns the standard error stream of the child process.
-- **exitCode**: Returns a promise that resolves to the exit code of the child process.
-
-### Properties
-
-- **isHalted**: A getter that returns a boolean indicating whether the promise is halted.
-
-## Output
-
-The `ProcessOutput` class collects output from the `ProcessPromise` shell process. It extends the `Error` class to provide compatibility with error handling mechanisms. Here's a summary of its features:
-
-
-### Getters
-
-- **stdout**: Returns the standard output (stdout) of the child process as a string.
-- **stderr**: Returns the error output (stderr) of the child process as a string.
-- **exitCode**: Returns the exit code of the process as a number.
-- **signal**: Returns the signal received by the process, such as 'SIGTERM', as a string.
-
-### Methods
-
-- **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.
-  - Displays the current state of the object when passed to `console.log`.
+- **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`.
+- **kill()**: Sends a kill signal to the child process.
 
 ### Examples
 
-- Script for setting up a wokspace in [TMUX](./workspace.js)
-- Take a look at the [test](./test/sh.js)
+- Elementary usages, piped:
+  ```javascript
+  const res = await SH`ls -FLa | grep package.json | wc -l`.run();
+  console.log(res);
+  ```
+
+- Feed command with content:
+  ```javascript
+  const res = await SH`wc -l`.run(`one\ntwo\n`);
+  console.log(res);
+  ```
+
+- Async context with multiple commands and sleep:
+  ```javascript
+  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()
+    ]);
+    console.log(res);
+  });
+  ```
+
+- Retry with exponential backoff:
+  ```javascript
+  try {
+    const p = await retry(3, expBackoff(), () => SH`curl -s https://flipwrsi`.run());
+  } catch (e) {
+    console.error('Retry failed:', e);
+  }
+  ```
 
 ## License
 
 This project is licensed under the Apache License, Version 2.0.
-

package/lib/sh.d.ts

@@ -1,41 +1,93 @@
-/// <reference types="node" resolution-mode="require"/>
-/// <reference types="node" resolution-mode="require"/>
-export type resolver = Function;
-export type rejecter = Function;
-export type PromiseConstruct = Function;
+export type SpawnSyncResponse = {
+    /**
+     * - The exit code of the child process. A value of `0` indicates success.
+     */
+    status: number;
+    /**
+     * - The signal used to terminate the process, if any.
+     */
+    signal: Buffer | null;
+    /**
+     * - An array containing the standard output and standard error of the child process.
+     */
+    output: Array<string | null>;
+    /**
+     * - The process ID of the child process.
+     */
+    pid: number;
+    /**
+     * - The standard output of the child process.
+     */
+    stdout: Buffer | null;
+    /**
+     * - The standard error of the child process.
+     */
+    stderr: Buffer | null;
+};
+/**
+ * Default options for the execution environment.
+ */
+export type SHOptions = {
+    /**
+     * - The current working directory.
+     */
+    cwd?: string;
+    /**
+     * - The environment variables.
+     */
+    env?: NodeJS.ProcessEnv;
+    /**
+     * - The shell to use for execution.
+     */
+    shell?: string;
+    /**
+     * - The prefix commands to ensure a safe execution environment.
+     */
+    prefix?: string;
+    /**
+     * - The stdio configuration.
+     */
+    stdio?: StdioOption | StdioOptions;
+};
 export type StdioOption = ('pipe' | 'ignore' | 'inherit' | number);
 export type StdioOptions = Array<StdioOption> | StdioOption;
 /**
- * Creates a new ProcessPromise object that represents a command to be executed.
+ * Creates a new SHDispatch 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 }} */
+/** @type {Shell & { (pieces: TemplateStringsArray, ...args: *): SHDispatch }} */
 export const SH: Shell & {
-    (pieces: TemplateStringsArray, ...args: any[]): ProcessPromise;
+    (pieces: TemplateStringsArray, ...args: any): SHDispatch;
 };
 /**
 * Change working directory
 * @param {string} dir
 */
 export function cd(dir: string): void;
+/**
+ * Generates an exponential backoff time with a random jitter.
+ *
+ * @generator
+ * @param {string} [max='60s'] - The maximum backoff time in a human-readable format (e.g., '60s' for 60 seconds).
+ * @param {string} [rand='100ms'] - The maximum random jitter time in a human-readable format (e.g., '100ms' for 100 milliseconds).
+ * @yields {number} The backoff time in milliseconds.
+ */
 export function expBackoff(max?: string, rand?: string): Generator<number, void, unknown>;
 /**
-* This function retries a command a specified number of times.
+* This function reads the standard input (stdin) from the current process.
+* @example
+* const content = await stdin();
+*/
+export function readIn(): Promise<string>;
+/**
+* Retries a given asynchronous function a specified number of times with optional delays between attempts.
+*
+* @param {number} count - The number of retry attempts.
+* @param {string|expBackoff|Function} a - Either a delay duration as a string, a delay generator object, or the callback function.
+* @param {Function} [b] - The callback function to retry, required if `a` is not a function.
+* @returns {Promise<*>} - The result of the callback function if it succeeds within the retry attempts.
+* @throws {Error} - The last error encountered if all retry attempts fail.
+*
 * @example
 * // Retry a command 3 times
 * const p = await retry(3, () => SH`curl -s https://flipwrsi`);
@@ -46,177 +98,50 @@ export function expBackoff(max?: string, rand?: string): Generator<number, void,
 * // 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>;
+export function retry(count: number, a: string | typeof expBackoff | Function, b?: Function): Promise<any>;
 /**
 * 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
-* ]);
+* const res = await sleep('5s');
 */
 export function sleep(duration: string | number): 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`,
+*			SH`sleep 1; echo 1`.run(),
+*			SH`sleep 2; echo 2`.run(),
 *			sleep(2),
-*			SH`sleep 3; echo 3`
+*			SH`sleep 3; echo 3`.run()
 *		]);
 */
-export function within(callback: Function): any;
-/**
-* @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;
+export function within(callback: Function): void;
+declare class SHDispatch {
     /**
-    * Set a timeout to kill a process
-    *
-    * @param {string} d - 10s, 1000ms
-    * @param {string} [signal] - default "SIGTERM" Signal to send to kill the proces
+    * @param {string} cmd - cmd to execute
     */
-    timeout(d: string, signal?: string): this;
-    _timeout: number;
-    _timeoutSignal: string;
+    constructor(cmd: string);
     /**
-    * stop execution for the next step
+    * @param {SHOptions} options
+    * @returns {SHDispatch}
     */
-    halt(): this;
+    options(options: SHOptions): SHDispatch;
     /**
-    * @private
-    * Set a prerun action, internal use only
-    * @param {function} f
+    * @param {string} [payload]
+    * @returns {Promise<string>}
     */
-    private set _prerun(f);
+    run(payload?: string): Promise<string>;
     /**
-    * Is this promise halted?
-    * @returns {boolean}
+    * Works for screen takeovers like editors
+    * @returns {SpawnSyncResponse}
     */
-    get isHalted(): boolean;
+    runSync(): SpawnSyncResponse;
+    kill(): Promise<void>;
     #private;
 }
 export {};