@j-o-r/sh 0.0.2 → 0.0.4

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/sh.d.ts

@@ -0,0 +1,222 @@
+/// <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 StdioOption = ('pipe' | 'ignore' | 'inherit' | number);
+export type StdioOptions = Array<StdioOption> | StdioOption;
+/**
+ * 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: Shell & {
+    (pieces: TemplateStringsArray, ...args: any[]): ProcessPromise;
+};
+/**
+* Change working directory
+* @param {string} dir
+*/
+export function cd(dir: string): void;
+export function expBackoff(max?: string, rand?: string): Generator<number, void, unknown>;
+/**
+* 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 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 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;
+/**
+* @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;
+}
+export {};