Skip to content

Commit 350a26f

Browse files
jaandrlejaandrle
authored
v0.8.0 - run/runA (#10)
1 parent cc2e235 commit 350a26f

24 files changed

Lines changed: 1450 additions & 278 deletions

‎README.md‎

Lines changed: 21 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -88,7 +88,7 @@ const file_path= fileURLToPath(import.meta.url);
8888
…and more, see [Node.js v17.9.1 Documentation](https://nodejs.org/docs/latest-v17.x/api/documentation.html#stability-overview).
8989
9090
## Security guidelines
91-
**`run()` command injection**: this advice applies to `child_process.exec()` just as
91+
**`run()`/`runA()` command injection**: this advice applies to `child_process.exec()` just as
9292
much as it applies to `s.run()`. It is potentially risky to run commands passed
9393
for example by user input:
9494
```js
@@ -97,9 +97,15 @@ curlUnsafe('https://some/url ; rm -rf $HOME'); //=> curl https://some/url ; rm -
9797
```
9898
Therefore, `nodejsscript`s `s.run()` provide way to escapes untrusted parameters:
9999
```js
100-
function curl(url){ return s.run("run ::url::", { url }); }
100+
function curl(url){ return s.run("curl ::url::", { url }); }
101101
curl('https://some/url ; rm -rf $HOME'); //=> curl 'https://some/url ; rm -rf $HOME'
102102
```
103+
…you can also use as template function (but without command specific options):
104+
```js
105+
function curl(url){ return s.run`curl ${url}`; }
106+
curl('https://some/url ; rm -rf $HOME'); //=> curl 'https://some/url ; rm -rf $HOME'
107+
```
108+
103109
…*Note: The ['xargs()'](../interfaces/s.XargsFunction.md) by default also escapes piped strings.*
104110
105111
*…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:
116122
s.$("-g").rm("*.txt");
117123
```
118124
125+
## Migration from `zx`
126+
The `runA` is almost identical to `$`:
127+
```js
128+
await $`cat package.json | grep name`;
129+
await s.runA`cat package.json | grep name`;
130+
```
131+
…but for `cp`/`mv`/… you need to rewrite code to `s.*`:
132+
```js
133+
echo(s.cat("package.json").grep("name"));
134+
// or
135+
echo(s.grep("name", "package.json"));
136+
```
137+
119138
## Contribute
120139
- [Contributor Covenant Code of Conduc](./CODE_OF_CONDUCT.md)
121140
- [How to contribute](./CONTRIBUTING.md)

‎_index.d.ts‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -26,21 +26,23 @@ export function pipe(...funs: Function[]): (input: any)=> any;
2626
* · [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)
2727
* · [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)
2828
* · [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-)
29-
* · [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-)
29+
* · [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-)
3030
* · [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)
3131
*
3232
* ```js
3333
* s.cat("./package.json").grep("version");
3434
* ```
3535
* … this library adds:
3636
* - {@link s.RunFunction 'run()'}
37+
* - {@link s.RunAsyncFunction 'runA()'}
3738
* - {@link s.XargsFunction 'xargs()'}
3839
* - {@link s.DollarFunction '$()'}
3940
*
4041
* **Changes/recommenctions:**
4142
* - 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")`.
42-
* - use {@link s.RunFunction 'run()'} instead of `s.exec`, because of options for passing arguments in secure way.
43+
* - use {@link s.RunFunction 'run()'}/{@link s.RunAsyncFunction 'runA()'} instead of `s.exec`, because of options for passing arguments in secure way.
4344
* - use {@link s.DollarFunction '$()'} instead of `s.set()`, because `$()` allows chaining (you can also access config with {@link cli}s `.is_*` keys).
45+
* - use {@link cli.xdg}`.temp` instead of `s.tempdir()` – the `cli.xdg.*` provides more paths than just temp directory.
4446
* @category Public
4547
*/
4648
export * as s from './src/shelljs.d';

‎docs/README.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -68,7 +68,7 @@ pipe(
6868

6969
#### Defined in
7070

71-
[_index.d.ts:18](https://github.com/jaandrle/nodejsscript/blob/9ae5d73/_index.d.ts#L18)
71+
[_index.d.ts:18](https://github.com/jaandrle/nodejsscript/blob/6b875ec/_index.d.ts#L18)
7272

7373
___
7474

@@ -116,7 +116,7 @@ try{
116116

117117
#### Defined in
118118

119-
[_index.d.ts:92](https://github.com/jaandrle/nodejsscript/blob/9ae5d73/_index.d.ts#L92)
119+
[_index.d.ts:94](https://github.com/jaandrle/nodejsscript/blob/6b875ec/_index.d.ts#L94)
120120

121121
___
122122

@@ -162,7 +162,7 @@ function spinner(message= "Waiting…"){
162162

163163
#### Defined in
164164

165-
[_index.d.ts:117](https://github.com/jaandrle/nodejsscript/blob/9ae5d73/_index.d.ts#L117)
165+
[_index.d.ts:119](https://github.com/jaandrle/nodejsscript/blob/6b875ec/_index.d.ts#L119)
166166

167167
___
168168

@@ -217,7 +217,7 @@ Returns processed string with additional utility methods like .to().
217217

218218
#### Defined in
219219

220-
[src/echo.d.ts:46](https://github.com/jaandrle/nodejsscript/blob/9ae5d73/src/echo.d.ts#L46)
220+
[src/echo.d.ts:46](https://github.com/jaandrle/nodejsscript/blob/6b875ec/src/echo.d.ts#L46)
221221

222222
___
223223

‎docs/classes/s.ProcessOutput.md‎

Lines changed: 265 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,265 @@
1+
[nodejsscript](../README.md) / [s](../modules/s.md) / ProcessOutput
2+
3+
# Class: ProcessOutput
4+
5+
[s](../modules/s.md).ProcessOutput
6+
7+
## Hierarchy
8+
9+
- `Error`
10+
11+
↳ **`ProcessOutput`**
12+
13+
## Table of contents
14+
15+
### Methods
16+
17+
- [captureStackTrace](s.ProcessOutput.md#capturestacktrace)
18+
- [toString](s.ProcessOutput.md#tostring)
19+
- [[custom]](s.ProcessOutput.md#[custom])
20+
21+
### Properties
22+
23+
- [prepareStackTrace](s.ProcessOutput.md#preparestacktrace)
24+
- [stackTraceLimit](s.ProcessOutput.md#stacktracelimit)
25+
- [name](s.ProcessOutput.md#name)
26+
- [message](s.ProcessOutput.md#message)
27+
- [stack](s.ProcessOutput.md#stack)
28+
29+
### Constructors
30+
31+
- [constructor](s.ProcessOutput.md#constructor)
32+
33+
### Accessors
34+
35+
- [stdout](s.ProcessOutput.md#stdout)
36+
- [stderr](s.ProcessOutput.md#stderr)
37+
- [exitCode](s.ProcessOutput.md#exitcode)
38+
- [signal](s.ProcessOutput.md#signal)
39+
40+
## Methods
41+
42+
### captureStackTrace
43+
44+
▸ `Static` **captureStackTrace**(`targetObject`, `constructorOpt?`): `void`
45+
46+
Create .stack property on a target object
47+
48+
#### Parameters
49+
50+
| Name | Type |
51+
| :------ | :------ |
52+
| `targetObject` | `object` |
53+
| `constructorOpt?` | `Function` |
54+
55+
#### Returns
56+
57+
`void`
58+
59+
#### Inherited from
60+
61+
Error.captureStackTrace
62+
63+
#### Defined in
64+
65+
node_modules/@types/node/ts4.8/globals.d.ts:4
66+
67+
___
68+
69+
### toString
70+
71+
▸ **toString**(): `string`
72+
73+
#### Returns
74+
75+
`string`
76+
77+
#### Defined in
78+
79+
[src/shelljs.d.ts:112](https://github.com/jaandrle/nodejsscript/blob/6b875ec/src/shelljs.d.ts#L112)
80+
81+
___
82+
83+
### [custom]
84+
85+
▸ **[custom]**(): `string`
86+
87+
#### Returns
88+
89+
`string`
90+
91+
#### Defined in
92+
93+
[src/shelljs.d.ts:117](https://github.com/jaandrle/nodejsscript/blob/6b875ec/src/shelljs.d.ts#L117)
94+
95+
## Properties
96+
97+
### prepareStackTrace
98+
99+
▪ `Static` `Optional` **prepareStackTrace**: (`err`: `Error`, `stackTraces`: `CallSite`[]) => `any`
100+
101+
#### Type declaration
102+
103+
▸ (`err`, `stackTraces`): `any`
104+
105+
Optional override for formatting stack traces
106+
107+
**`See`**
108+
109+
https://v8.dev/docs/stack-trace-api#customizing-stack-traces
110+
111+
##### Parameters
112+
113+
| Name | Type |
114+
| :------ | :------ |
115+
| `err` | `Error` |
116+
| `stackTraces` | `CallSite`[] |
117+
118+
##### Returns
119+
120+
`any`
121+
122+
#### Inherited from
123+
124+
Error.prepareStackTrace
125+
126+
#### Defined in
127+
128+
node_modules/@types/node/ts4.8/globals.d.ts:11
129+
130+
___
131+
132+
### stackTraceLimit
133+
134+
▪ `Static` **stackTraceLimit**: `number`
135+
136+
#### Inherited from
137+
138+
Error.stackTraceLimit
139+
140+
#### Defined in
141+
142+
node_modules/@types/node/ts4.8/globals.d.ts:13
143+
144+
___
145+
146+
### name
147+
148+
• **name**: `string`
149+
150+
#### Inherited from
151+
152+
Error.name
153+
154+
#### Defined in
155+
156+
node_modules/typescript/lib/lib.es5.d.ts:1040
157+
158+
___
159+
160+
### message
161+
162+
• **message**: `string`
163+
164+
#### Inherited from
165+
166+
Error.message
167+
168+
#### Defined in
169+
170+
node_modules/typescript/lib/lib.es5.d.ts:1041
171+
172+
___
173+
174+
### stack
175+
176+
• `Optional` **stack**: `string`
177+
178+
#### Inherited from
179+
180+
Error.stack
181+
182+
#### Defined in
183+
184+
node_modules/typescript/lib/lib.es5.d.ts:1042
185+
186+
## Constructors
187+
188+
### constructor
189+
190+
• **new ProcessOutput**(`code`, `signal`, `stdout`, `stderr`, `combined`, `message`)
191+
192+
#### Parameters
193+
194+
| Name | Type |
195+
| :------ | :------ |
196+
| `code` | `number` |
197+
| `signal` | `Signals` |
198+
| `stdout` | `string` |
199+
| `stderr` | `string` |
200+
| `combined` | `string` |
201+
| `message` | `string` |
202+
203+
#### Overrides
204+
205+
Error.constructor
206+
207+
#### Defined in
208+
209+
[src/shelljs.d.ts:111](https://github.com/jaandrle/nodejsscript/blob/6b875ec/src/shelljs.d.ts#L111)
210+
211+
## Accessors
212+
213+
### stdout
214+
215+
• `get` **stdout**(): `string`
216+
217+
#### Returns
218+
219+
`string`
220+
221+
#### Defined in
222+
223+
[src/shelljs.d.ts:113](https://github.com/jaandrle/nodejsscript/blob/6b875ec/src/shelljs.d.ts#L113)
224+
225+
___
226+
227+
### stderr
228+
229+
• `get` **stderr**(): `string`
230+
231+
#### Returns
232+
233+
`string`
234+
235+
#### Defined in
236+
237+
[src/shelljs.d.ts:114](https://github.com/jaandrle/nodejsscript/blob/6b875ec/src/shelljs.d.ts#L114)
238+
239+
___
240+
241+
### exitCode
242+
243+
• `get` **exitCode**(): `number`
244+
245+
#### Returns
246+
247+
`number`
248+
249+
#### Defined in
250+
251+
[src/shelljs.d.ts:115](https://github.com/jaandrle/nodejsscript/blob/6b875ec/src/shelljs.d.ts#L115)
252+
253+
___
254+
255+
### signal
256+
257+
• `get` **signal**(): `Signals`
258+
259+
#### Returns
260+
261+
`Signals`
262+
263+
#### Defined in
264+
265+
[src/shelljs.d.ts:116](https://github.com/jaandrle/nodejsscript/blob/6b875ec/src/shelljs.d.ts#L116)

0 commit comments

Comments
 (0)