@j-o-r/sh 0.0.3 → 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,44 +1,93 @@
+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;
+};
 /**
- * Creates a new ProcessPromise object that represents a command to be executed.
+ * Default options for the execution environment.
  */
-export type Shell = Function;
+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.
- *
- * @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!'`;
+ * Creates a new SHDispatch object that represents a command to be executed.
  */
-/** @type {Shell & { (pieces: TemplateStringsArray, ...args: any[]): ProcessPromise }} */
-export const SH: Function & ((pieces: TemplateStringsArray, ...args: any[]) => ProcessPromise);
+export type Shell = Function;
+/** @type {Shell & { (pieces: TemplateStringsArray, ...args: *): SHDispatch }} */
+export const SH: Shell & {
+    (pieces: TemplateStringsArray, ...args: any): SHDispatch;
+};
 /**
 * 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'.
-*
+ * 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 reads the standard input (stdin) from the current process.
 * @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 content = await stdin();
 */
-export function sleep(duration: string | number): Promise<any>;
+export function readIn(): Promise<string>;
 /**
-* This function retries a command a specified number of times.
+* 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`);
@@ -49,26 +98,50 @@ export function sleep(duration: string | number): Promise<any>;
 * // 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 reads the standard input (stdin) for the current process.
-* It is used to get piped content into a script.
+* 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 content = await stdin();
+*
+* const res = await sleep('5s');
 */
-export function stdin(): Promise<string>;
+export function sleep(duration: string | number): Promise<any>;
 /**
 * 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;
-export function expBackoff(max?: string, rand?: string): Generator<number, void, unknown>;
-import ProcessPromise from './ProcessPromise.js';
+export function within(callback: Function): void;
+declare class SHDispatch {
+    /**
+    * @param {string} cmd - cmd to execute
+    */
+    constructor(cmd: string);
+    /**
+    * @param {SHOptions} options
+    * @returns {SHDispatch}
+    */
+    options(options: SHOptions): SHDispatch;
+    /**
+    * @param {string} [payload]
+    * @returns {Promise<string>}
+    */
+    run(payload?: string): Promise<string>;
+    /**
+    * Works for screen takeovers like editors
+    * @returns {SpawnSyncResponse}
+    */
+    runSync(): SpawnSyncResponse;
+    kill(): Promise<void>;
+    #private;
+}
+export {};