jsh - npm Package Compare versions

Comparing version 0.31.0 to 0.32.0

dist/index.d.ts

@@ -72,3 +72,2 @@ /// <reference types="node" />
     red(content: string, ...optionalArgs: any[]): void;
-    noNewLine: (content: string) => boolean;
 };
@@ -89,3 +88,3 @@ /**
        const name = prompt("What's your name?");
-       const name = prompt(() => { echo.noNewLine("What's your name? "); });
+       const name = prompt(() => { printf("What's your name? "); });
        const name = prompt(() => { echo.yellow("What's your name? "); });
@@ -100,2 +99,22 @@ });
 declare const _sleep: (ms: number) => void;
+export interface ICommandOptions {
+    /**
+     * If true will capture stdout from command and return it.  If false, stdout will not be captured but only printed to the console.  Default: true
+     */
+    captureStdout?: boolean;
+    /**
+     * If true will echo the command itself before running it
+     */
+    echoCommand?: boolean;
+    /**
+     * If set to true, will not throw if the command returns a non-zero exit code
+     */
+    noThrow?: boolean;
+    /**
+     *  In milliseconds the maximum amount of time the process is allowed to run
+     */
+    timeout?: number;
+    shell?: string | boolean | undefined;
+    maxBuffer?: number;
+}
 export declare class CommandError extends Error {
@@ -111,48 +130,17 @@ command: string;
  * @param command The command to run.
- * @param echoStdout If true will echo stdout of the command as it runs and not capture its output
- * @param echoCommand If true will echo the command before running it
+ * @param options
  * @returns
  */
-declare const _$: {
-    (command: string, echoStdout?: boolean, echoCommand?: boolean): string;
-    /**
-     * Runs a command and echo its stdout as it executes.  Stdout from the command is not captured.
-     * @param command The command to run.
-     * @param echoStdout If true will echo stdout of the command as it runs and not capture its output
-     * @param echoCommand If true will echo the command before running it
-     * @returns void
-     */
-    echo(command: string, echoCommand?: boolean): void;
-    /**
-     * Runs a command and will not throw if the command returns a non-zero exit code.  Instead the stderr (or stdout if stderr is empty) will be returned.
-     * @param command
-     * @param pipe
-     * @param echoCommand
-     * @returns
-     */
-    noThrow(command: string, pipe?: boolean, echoCommand?: boolean): string;
-    /**
-     * Runs a command without echoing it
-     * @param command
-     * @param pipe
-     * @returns
-     */
-    quiet(command: string, pipe?: boolean): string;
-    /**
-     * Runs a command and will retry up to maxTries if the command returns a non-zero exit code
-     * @param cmd
-     * @param maxTries
-     * @param waitMillisecondsBeforeRetry
-     * @param echoFailures
-     * @param pipe
-     * @param echoCommand
-     * @returns
-     */
-    retry(cmd: string, maxTries?: number, waitMillisecondsBeforeRetry?: number, echoFailures?: boolean, pipe?: boolean, echoCommand?: boolean): string;
-    shell: string | null;
-    maxBuffer: number;
-};
+declare const _$: (command: string, options?: ICommandOptions) => string;
+declare type IExecCommandOptions = Omit<ICommandOptions, "echoStdout">;
+/**
+ * Runs a command and echos its stdout as it executes.  Stdout from the command is not captured.
+ * @param command The command to run
+ * @param options
+ * @returns void
+ */
+declare const _exec: (command: string, options?: IExecCommandOptions) => void;
 export declare type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
 export declare type HttpData = object | stream.Readable | null;
-export interface IHttpRequestOptions {
+export interface IHttpRawRequestOptions {
     protocol: string;
@@ -164,5 +152,14 @@ hostname: string;
     method: string;
-    headers: NodeJS.Dict<string | string[]>;
-    timeout: number;
+    headers?: NodeJS.Dict<string | string[]>;
+    /**
+     * The number of milliseconds of inactivity before a socket is presumed to have timed out.
+     */
+    timeout?: number;
 }
+export declare type IHttpRequestOptions = Pick<Partial<IHttpRawRequestOptions>, "headers" | "timeout"> & {
+    /**
+     * If set to true, will not throw if the response status code is not 2xx
+     */
+    noThrow?: boolean;
+};
 export interface IHttpResponse<T> {
@@ -174,8 +171,8 @@ data: T;
     statusMessage: string | undefined;
-    requestOptions: IHttpRequestOptions;
+    requestOptions: IHttpRawRequestOptions;
 }
 export declare class HttpRequestError<T> extends Error {
-    request: IHttpRequestOptions;
+    request: IHttpRawRequestOptions;
     response: IHttpResponse<T> | null;
-    constructor(message: string, request: IHttpRequestOptions, response?: IHttpResponse<T> | null);
+    constructor(message: string, request: IHttpRawRequestOptions, response?: IHttpResponse<T> | null);
     get data(): T | undefined;
@@ -195,32 +192,4 @@ get body(): string | undefined;
 declare const _http: {
-    <T>(method: HttpMethod, url: string, data?: HttpData, headers?: {
-        [name: string]: string;
-    }): Promise<IHttpResponse<T>>;
-    timeout: number;
+    <T>(method: HttpMethod, url: string, data?: HttpData, options?: IHttpRequestOptions): Promise<IHttpResponse<T>>;
     /**
-     * Makes a synchronous HTTP request and returns the response.   Will not throw an error if the response status code is not 2xx.
-     * @param method
-     * @param url
-     * @param data
-     * @param headers
-     * @returns
-     */
-    noThrow<T_1>(method: HttpMethod, url: string, data?: HttpData, headers?: {
-        [name: string]: string;
-    }): Promise<IHttpResponse<T_1>>;
-    /**
-     * Makes a HTTP request and returns the response.   Will retry up to maxTries if an error is thrown because the status code is not 2xx.
-     * @param method
-     * @param url
-     * @param data
-     * @param headers
-     * @param maxTries
-     * @param waitMillisecondsBeforeRetry
-     * @param echoFailures
-     * @returns
-     */
-    retry<T_2>(method: HttpMethod, url: string, data?: HttpData, headers?: {
-        [name: string]: string;
-    }, maxTries?: number, waitMillisecondsBeforeRetry?: number, echoFailures?: boolean): Promise<IHttpResponse<T_2>>;
-    /**
      * Makes a GET HTTP request and returns the response data.  Will throw an error if the response status code is not 2xx.
@@ -231,5 +200,5 @@ * @param url
      */
-    get<T_3>(url: string, headers?: {
+    get<T_1>(url: string, headers?: {
         [name: string]: string;
-    }): Promise<T_3>;
+    }): Promise<T_1>;
     /**
@@ -241,5 +210,5 @@ * Makes a POST HTTP request and returns the response data.  Will throw an error if the response status code is not 2xx.
      */
-    post<T_4>(url: string, data: HttpData, headers?: {
+    post<T_2>(url: string, data: HttpData, headers?: {
         [name: string]: string;
-    }): Promise<T_4>;
+    }): Promise<T_2>;
     /**
@@ -251,5 +220,5 @@ * Makes a PUT HTTP request and returns the response data.  Will throw an error if the response status code is not 2xx.
      */
-    put<T_5>(url: string, data: HttpData, headers?: {
+    put<T_3>(url: string, data: HttpData, headers?: {
         [name: string]: string;
-    }): Promise<T_5>;
+    }): Promise<T_3>;
     /**
@@ -261,5 +230,5 @@ * Makes a PATCH HTTP request and returns the response data.  Will throw an error if the response status code is not 2xx.
      */
-    patch<T_6>(url: string, data: HttpData, headers?: {
+    patch<T_4>(url: string, data: HttpData, headers?: {
         [name: string]: string;
-    }): Promise<T_6>;
+    }): Promise<T_4>;
     /**
@@ -271,5 +240,5 @@ * Makes a DELETE HTTP request and returns the response data.  Will throw an error if the response status code is not 2xx.
      */
-    delete<T_7>(url: string, data: HttpData, headers?: {
+    delete<T_5>(url: string, data: HttpData, headers?: {
         [name: string]: string;
-    }): Promise<T_7>;
+    }): Promise<T_5>;
 };
@@ -325,3 +294,3 @@ /**
     var $: typeof _$;
-    var exec: typeof _$.echo;
+    var exec: typeof _exec;
     var http: typeof _http;
@@ -328,0 +297,0 @@ var cd: typeof process.chdir;

package.json

 {
   "name": "jsh",
-  "version": "0.31.0",
+  "version": "0.32.0",
   "description": "Helpers for Bash like shell scripting in JavaScript",
@@ -5,0 +5,0 @@ "author": "Brady Holt",

README.md

@@ -44,3 +44,3 @@ # jsh
 | `echo.red("Hello")` | Print red colored text to console with trailing newline |
-| `echo.noNewLine("Processing...")` | Print text to console without a trailing newline; also aliased as `printf()`. |
+| `printf("Processing...")` | Print text to console without a trailing newline |
 | `exit(1)` | Halt the script and return an exit code |
@@ -69,6 +69,3 @@ | `error("An error", 1)` | Echo an error and halt the script with an exit code |
 | `result=$("cmd.sh")` | Execute a command and return the stdout |
-| `$.echo("cmd.sh")` | Execute a command and stream stdout to console without returning a value; also aliased as `exec()`. |
-| `$.noThrow("cmd.sh")` | Execute a command and do not throw an error if its exit code is not 0 |
-| `$.quiet("cmd.sh")` | Execute a command and do not echo the command before running it |
-| `$.retry("cmd.sh", 5)` | Execute a command and if it throws and error, retry up to a number of times until it succeeds |
+| `exec("cmd.sh")` | Execute a command and streams stdout to console without returning a value |
 
@@ -93,11 +90,9 @@ **File System**
 |     | Description |
-| --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
 | `await http.get("https://www.myapi.com")`                   | Make a HTTP GET request and return the response body data                                                |
-| `await http.post("https://www.myapi.com", { data: "1" }) `  | Make a HTTP POST request and return the response body data                                               |
+| `await http.post("https://www.myapi.com", { data: "1" })`   | Make a HTTP POST request and return the response body data                                               |
 | `await http.put("https://www.myapi.com", { data: "1" })`    | Make a HTTP PUT request and return the response body data                                                |
 | `await http.patch("https://www.myapi.com", { data: "1" })`  | Make a HTTP PATCH request and return the response body data                                              |
 | `await http.delete("https://www.myapi.com", { data: "1" })` | Make a HTTP DELETE request and return the response body data                                             |
-| `await http("GET", "https://www.myapi.com")`                | Make a HTTP request and return the response: (`{ data, headers, statusCode, statusMessage }`)            |
-| `await http.noThrow("GET", "https://www.myapi.com")`        | Make a HTTP request and do not throw an error if status code is not 20X                                  |
-| `await http.retry("GET", "https://www.myapi.com")`          | Make a HTTP request and if response status code is not 20X, retry up to a number of times until it is    |
+| `await http("POST", "https://www.myapi.com", { data: "1" }, { headers: { Accept: "application/json" } })`                | Make a HTTP request and return the response: (`{ data, headers, statusCode, statusMessage }`)            |
 
@@ -196,5 +191,5 @@ ## Examples
 
-### $.echo()
+### exec
 
-**$.echo()** (also aliased as `exec()`) should be used when running commands where the output (stdout) does not need to be captured, but only printed to the console. This helper is intended for long running commands or those where output does not need to be captured.
+**exec** should be used when running commands where the output (stdout) does not need to be captured, but only printed to the console. This helper is intended for long running commands or those where output does not need to be captured.
 
@@ -205,5 +200,5 @@ Example:
 // Will print `npm install` output immediately as it happens
-// $.echo() will not return anything (void)
+// exec will not return anything (void)
 
-$.echo(`npm install`) // or exec(`npm install`)
+exec(`npm install`)
 
@@ -232,5 +227,5 @@ > added 379 packages, and audited 380 packages in 1s
 
-#### $.noThrow()
+#### `noThrow` option
 
-You can call `$.noThrow()` to prevent an error from being thrown. Instead, the stderr will be returned.
+You can pass in the option `noThrow: true` to prevent an error from being thrown. Instead, the stderr will be returned.
 
@@ -241,3 +236,3 @@ Example:
 // This command will error out but will not throw because `$.noThrow()` was called.
-let content=$(`cat invalid.txt`)
+let content=$(`cat invalid.txt`, { noThrow: true})
 echo(content);
@@ -248,5 +243,11 @@
 
-### Options
+### Command Options
 
-- `$.shell` - By default, commands will be run inside of a shell (`/bin/sh` on *nix systems and `process.env.ComSpec` on Windows).  You can specify the path to a different shell to execute commands with by setting the `$.shell` config variable.  All subsequent command executions will honor this setting.  For example: `$.shell = "/bin/bash";`
+`$()` and `exec()` accept an `options` parameter object that may contain any of the following fields:
+ 
+- `echoCommand: boolean` - If true will echo the command itself before running it (Default: `true`)
+- `noThrow: boolean` -  If set to true, will not throw if the command returns a non-zero exit code (Default: `false`)
+- `timeout: number` - In milliseconds the maximum amount of time the process is allowed to run (Default: `undefined` (unlimited))
+- `shell: string` - By default, commands will be run inside of a shell (`/bin/sh` on *nix systems and `process.env.ComSpec` on Windows).  This option can be used to specify the path to a different shell to execute commands with.  For example, you could specify `shell: "/bin/bash"` to use bash.
+  `maxBuffer: number` - Specifies the largest number of bytes allowed on stdout or stderr. If this value is exceeded, the child process will be terminated. (Default: `268435456` (256MB))
 
@@ -326,5 +327,5 @@ ## HTTP Request Helpers
 
-#### http.noThrow()
+#### `noThrow` option
 
-You can call `http.noThrow()` to prevent an error from being thrown. Instead, the response will be returned.
+You can pass in the option `noThrow: true` when calling `http()` to prevent an error from being thrown when the response status is not 2xx. Instead, the response will be returned.
 
@@ -334,3 +335,3 @@ Example:
 ```
-const response = await http.noThrow("GET", "https://www.myapi.com);
+const response = await http("POST", "https://www.myapi.com", { data: 2 }, { noThrow: true });
 
@@ -343,2 +344,10 @@ echo(response.data) // "A server error occurred.  Please try again later."
 
+### HTTP Request Options
+
+`http()` accepts an `options` parameter object that may contain any of the following fields:
+ 
+- `headers: object` - The request headers to send with the request.  A set of default headers will be included with the request even if not specified here.  See "Default Headers" section above for more info.
+- `timeout: number` - The number of milliseconds of inactivity before a socket is presumed to have timed out (Default: `120000` (2 minutes))
+- `noThrow: boolean` - If set to true, will not throw if the response status code is not 2xx (Default: false)
+
 ## Installation
@@ -345,0 +354,0 @@

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Number of lines in readme file

464

increased by1.98%

Worsened metrics

Total package byte prevSize

70093

decreased by-7.29%

Lines of code

1465

decreased by-11.53%

No dependency changes