v0.8.0 - run/runA (#10)

README.md

@@ -88,7 +88,7 @@ const file_path= fileURLToPath(import.meta.url);
 …and more, see [Node.js v17.9.1 Documentation](https://nodejs.org/docs/latest-v17.x/api/documentation.html#stability-overview).
 
 ## Security guidelines
-**`run()` command injection**: this advice applies to `child_process.exec()` just as
+**`run()`/`runA()` command injection**: this advice applies to `child_process.exec()` just as
 much as it applies to `s.run()`. It is potentially risky to run commands passed
 for example by user input:
 ```js
@@ -97,9 +97,15 @@ curlUnsafe('https://some/url ; rm -rf $HOME'); //=> curl https://some/url ; rm -
 ```
 Therefore, `nodejsscript`s `s.run()` provide way to escapes untrusted parameters:
 ```js
-function curl(url){ return s.run("run ::url::", { url }); }
+function curl(url){ return s.run("curl ::url::", { url }); }
 curl('https://some/url ; rm -rf $HOME'); //=> curl 'https://some/url ; rm -rf $HOME'
 ```
+…you can also use as template function (but without command specific options):
+```js
+function curl(url){ return s.run`curl ${url}`; }
+curl('https://some/url ; rm -rf $HOME'); //=> curl 'https://some/url ; rm -rf $HOME'
+```
+
 …*Note: The ['xargs()'](../interfaces/s.XargsFunction.md) by default also escapes piped strings.*
 
 *…Note 2: `s.run(…cmd, …vars)` is also helpul for escaping parameters passed as variables (e.g. arrays).*
@@ -116,6 +122,19 @@ Keep in mind that you can always turn off this for next command by using:
 s.$("-g").rm("*.txt");
 ```
 
+## Migration from `zx`
+The `runA` is almost identical to `$`:
+```js
+await $`cat package.json | grep name`;
+await s.runA`cat package.json | grep name`;
+```
+…but for `cp`/`mv`/… you need to rewrite code to `s.*`:
+```js
+echo(s.cat("package.json").grep("name"));
+// or
+echo(s.grep("name", "package.json"));
+```
+
 ## Contribute
 - [Contributor Covenant Code of Conduc](./CODE_OF_CONDUCT.md)
 - [How to contribute](./CONTRIBUTING.md)

_index.d.ts

@@ -26,21 +26,23 @@ export function pipe(...funs: Function[]): (input: any)=> any;
  *  · [find](https://github.com/shelljs/shelljs#findpath--path-) · [grep](https://github.com/shelljs/shelljs#grepoptions-regex_filter-file--file-) · [head](https://github.com/shelljs/shelljs#head-n-num-file--file-) · [ln](https://github.com/shelljs/shelljs#lnoptions-source-dest)
  *  · [ls](https://github.com/shelljs/shelljs#lsoptions-path-) · [mkdir](https://github.com/shelljs/shelljs#mkdiroptions-dir--dir-) · [mv](https://github.com/shelljs/shelljs#mvoptions--source--source--dest) · [pwd](https://github.com/shelljs/shelljs#pwd)
  *  · [rm](https://github.com/shelljs/shelljs#rmoptions-file--file-) · [sed](https://github.com/shelljs/shelljs#sedoptions-search_regex-replacement-file--file-) · [sort](https://github.com/shelljs/shelljs#sortoptions-file--file-)
- *  · [tail](https://github.com/shelljs/shelljs#tail-n-num-file--file-) · [tempdir](https://github.com/shelljs/shelljs#tempdir) · [test](https://github.com/shelljs/shelljs#testexpression) · [touch](https://github.com/shelljs/shelljs#touchoptions-file--file-)
+ *  · [tail](https://github.com/shelljs/shelljs#tail-n-num-file--file-) · [test](https://github.com/shelljs/shelljs#testexpression) · [touch](https://github.com/shelljs/shelljs#touchoptions-file--file-)
  *  · [uniq](https://github.com/shelljs/shelljs#uniqoptions-input-output) · [which](https://github.com/shelljs/shelljs#whichcommand) · [exit](https://github.com/shelljs/shelljs#exitcode) · [error](https://github.com/shelljs/shelljs#error) · [errorCode](https://github.com/shelljs/shelljs#errorcode) 
  *
  * ```js
  * s.cat("./package.json").grep("version");
  * ```
  * … this library adds:
  * - {@link s.RunFunction 'run()'}
+ * - {@link s.RunAsyncFunction 'runA()'}
  * - {@link s.XargsFunction 'xargs()'}
  * - {@link s.DollarFunction '$()'}
  *
  * **Changes/recommenctions:**
  * - use {@link echo} instead of `s.echo`, this was changed to `s.ShellString` for easy file writing without logging to console `s.echo("Data").to("file.txt")`.
- * - use {@link s.RunFunction 'run()'} instead of `s.exec`, because of options for passing arguments in secure way.
+ * - use {@link s.RunFunction 'run()'}/{@link s.RunAsyncFunction 'runA()'} instead of `s.exec`, because of options for passing arguments in secure way.
  * - use {@link s.DollarFunction '$()'} instead of `s.set()`, because `$()` allows chaining (you can also access config with {@link cli}s `.is_*` keys).
+ * - use {@link cli.xdg}`.temp` instead of `s.tempdir()` – the `cli.xdg.*` provides more paths than just temp directory.
  * @category Public
  */
 export * as s from './src/shelljs.d';

docs/README.md

@@ -68,7 +68,7 @@ pipe(
 
 #### Defined in
 
-[_index.d.ts:18](https://github.com/jaandrle/nodejsscript/blob/9ae5d73/_index.d.ts#L18)
+[_index.d.ts:18](https://github.com/jaandrle/nodejsscript/blob/6b875ec/_index.d.ts#L18)
 
 ___
 
@@ -116,7 +116,7 @@ try{
 
 #### Defined in
 
-[_index.d.ts:92](https://github.com/jaandrle/nodejsscript/blob/9ae5d73/_index.d.ts#L92)
+[_index.d.ts:94](https://github.com/jaandrle/nodejsscript/blob/6b875ec/_index.d.ts#L94)
 
 ___
 
@@ -162,7 +162,7 @@ function spinner(message= "Waiting…"){
 
 #### Defined in
 
-[_index.d.ts:117](https://github.com/jaandrle/nodejsscript/blob/9ae5d73/_index.d.ts#L117)
+[_index.d.ts:119](https://github.com/jaandrle/nodejsscript/blob/6b875ec/_index.d.ts#L119)
 
 ___
 
@@ -217,7 +217,7 @@ Returns processed string with additional utility methods like .to().
 
 #### Defined in
 
-[src/echo.d.ts:46](https://github.com/jaandrle/nodejsscript/blob/9ae5d73/src/echo.d.ts#L46)
+[src/echo.d.ts:46](https://github.com/jaandrle/nodejsscript/blob/6b875ec/src/echo.d.ts#L46)
 
 ___
 

docs/classes/s.ProcessOutput.md

@@ -0,0 +1,265 @@
+[nodejsscript](../README.md) / [s](../modules/s.md) / ProcessOutput
+
+# Class: ProcessOutput
+
+[s](../modules/s.md).ProcessOutput
+
+## Hierarchy
+
+- `Error`
+
+  ↳ **`ProcessOutput`**
+
+## Table of contents
+
+### Methods
+
+- [captureStackTrace](s.ProcessOutput.md#capturestacktrace)
+- [toString](s.ProcessOutput.md#tostring)
+- [[custom]](s.ProcessOutput.md#[custom])
+
+### Properties
+
+- [prepareStackTrace](s.ProcessOutput.md#preparestacktrace)
+- [stackTraceLimit](s.ProcessOutput.md#stacktracelimit)
+- [name](s.ProcessOutput.md#name)
+- [message](s.ProcessOutput.md#message)
+- [stack](s.ProcessOutput.md#stack)
+
+### Constructors
+
+- [constructor](s.ProcessOutput.md#constructor)
+
+### Accessors
+
+- [stdout](s.ProcessOutput.md#stdout)
+- [stderr](s.ProcessOutput.md#stderr)
+- [exitCode](s.ProcessOutput.md#exitcode)
+- [signal](s.ProcessOutput.md#signal)
+
+## Methods
+
+### captureStackTrace
+
+▸ `Static` **captureStackTrace**(`targetObject`, `constructorOpt?`): `void`
+
+Create .stack property on a target object
+
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `targetObject` | `object` |
+| `constructorOpt?` | `Function` |
+
+#### Returns
+
+`void`
+
+#### Inherited from
+
+Error.captureStackTrace
+
+#### Defined in
+
+node_modules/@types/node/ts4.8/globals.d.ts:4
+
+___
+
+### toString
+
+▸ **toString**(): `string`
+
+#### Returns
+
+`string`
+
+#### Defined in
+
+[src/shelljs.d.ts:112](https://github.com/jaandrle/nodejsscript/blob/6b875ec/src/shelljs.d.ts#L112)
+
+___
+
+### [custom]
+
+▸ **[custom]**(): `string`
+
+#### Returns
+
+`string`
+
+#### Defined in
+
+[src/shelljs.d.ts:117](https://github.com/jaandrle/nodejsscript/blob/6b875ec/src/shelljs.d.ts#L117)
+
+## Properties
+
+### prepareStackTrace
+
+▪ `Static` `Optional` **prepareStackTrace**: (`err`: `Error`, `stackTraces`: `CallSite`[]) => `any`
+
+#### Type declaration
+
+▸ (`err`, `stackTraces`): `any`
+
+Optional override for formatting stack traces
+
+**`See`**
+
+https://v8.dev/docs/stack-trace-api#customizing-stack-traces
+
+##### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `err` | `Error` |
+| `stackTraces` | `CallSite`[] |
+
+##### Returns
+
+`any`
+
+#### Inherited from
+
+Error.prepareStackTrace
+
+#### Defined in
+
+node_modules/@types/node/ts4.8/globals.d.ts:11
+
+___
+
+### stackTraceLimit
+
+▪ `Static` **stackTraceLimit**: `number`
+
+#### Inherited from
+
+Error.stackTraceLimit
+
+#### Defined in
+
+node_modules/@types/node/ts4.8/globals.d.ts:13
+
+___
+
+### name
+
+• **name**: `string`
+
+#### Inherited from
+
+Error.name
+
+#### Defined in
+
+node_modules/typescript/lib/lib.es5.d.ts:1040
+
+___
+
+### message
+
+• **message**: `string`
+
+#### Inherited from
+
+Error.message
+
+#### Defined in
+
+node_modules/typescript/lib/lib.es5.d.ts:1041
+
+___
+
+### stack
+
+• `Optional` **stack**: `string`
+
+#### Inherited from
+
+Error.stack
+
+#### Defined in
+
+node_modules/typescript/lib/lib.es5.d.ts:1042
+
+## Constructors
+
+### constructor
+
+• **new ProcessOutput**(`code`, `signal`, `stdout`, `stderr`, `combined`, `message`)
+
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `code` | `number` |
+| `signal` | `Signals` |
+| `stdout` | `string` |
+| `stderr` | `string` |
+| `combined` | `string` |
+| `message` | `string` |
+
+#### Overrides
+
+Error.constructor
+
+#### Defined in
+
+[src/shelljs.d.ts:111](https://github.com/jaandrle/nodejsscript/blob/6b875ec/src/shelljs.d.ts#L111)
+
+## Accessors
+
+### stdout
+
+• `get` **stdout**(): `string`
+
+#### Returns
+
+`string`
+
+#### Defined in
+
+[src/shelljs.d.ts:113](https://github.com/jaandrle/nodejsscript/blob/6b875ec/src/shelljs.d.ts#L113)
+
+___
+
+### stderr
+
+• `get` **stderr**(): `string`
+
+#### Returns
+
+`string`
+
+#### Defined in
+
+[src/shelljs.d.ts:114](https://github.com/jaandrle/nodejsscript/blob/6b875ec/src/shelljs.d.ts#L114)
+
+___
+
+### exitCode
+
+• `get` **exitCode**(): `number`
+
+#### Returns
+
+`number`
+
+#### Defined in
+
+[src/shelljs.d.ts:115](https://github.com/jaandrle/nodejsscript/blob/6b875ec/src/shelljs.d.ts#L115)
+
+___
+
+### signal
+
+• `get` **signal**(): `Signals`
+
+#### Returns
+
+`Signals`
+
+#### Defined in
+
+[src/shelljs.d.ts:116](https://github.com/jaandrle/nodejsscript/blob/6b875ec/src/shelljs.d.ts#L116)