Skip to content

Commit 5e4d818

Browse files
authored
docs(runtime): improve Process docs (#90)
1 parent 34984c2 commit 5e4d818

File tree

1 file changed

+55
-1
lines changed

1 file changed

+55
-1
lines changed

README.md

Lines changed: 55 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -75,6 +75,7 @@ await fs.ensureDir("./tmp");
7575
- [Permissions](#permissions)
7676
- [Markdown](#markdown)
7777
- [Methods](#methods)
78+
- [Process](#process)
7879
- [Modules](#modules)
7980
- [Variables](#variables)
8081
- [Experimental](#experimental)
@@ -269,26 +270,79 @@ Methods and properties of the `Process` class which implements
269270

270271
- `.pid`: Returns the process id of the executed command.
271272

273+
```ts
274+
// Get the process id.
275+
const child = $`echo foo`;
276+
console.log("pid:", child.pid);
277+
await child;
278+
```
279+
272280
- `.noThrow`: If invoked the command doesn't throw an error if the command
273281
returns a none-zero exit code.
274282

283+
```ts
284+
// Don't throw an error for none-zero exit codes.
285+
const { status } = await $`exit 1`.noThrow;
286+
```
287+
275288
- `.statusCode`: Returns the status code of the executed command and calls
276289
`.noThrow` internally to catch the error and return the status code.
277290

291+
```ts
292+
// Get only the status code.
293+
const statusCode: number = await $`exit 1`.statusCode;
294+
```
295+
278296
- `.stdout` Returns `Promise<string>` and resolves with the stdout output.
279297

298+
```ts
299+
// Get only stdout.
300+
const foo: string = await $`echo foo; echo bar >&2`.stdout;
301+
```
302+
280303
- `.stderr` Returns `Promise<string>` and resolves with the stderr output.
281304

282-
- `.retry(retries: number)` Retry the command `n` times if it fails.
305+
```ts
306+
// Get only stderr.
307+
const bar: string = await $`echo foo; echo bar >&2`.stderr;
308+
```
309+
310+
- `.retry(retries: number | RetryCallback)` Retry the command `n` times if it
311+
fails.
312+
313+
```ts
314+
// Retry the command 3 times.
315+
await $`exit 1`.retry(3);
316+
317+
// Retry the command 3 times using a callback handler.
318+
await $`exit 1`.retry(({ retries }: ProcessError) => retries < 3);
319+
```
283320

284321
- `.delay(delay: number)` Number of milliseconds to delay the retry of a failed
285322
command. Default: `500`
286323

324+
```ts
325+
// Retry the command 3 times but wait 1sec before executing it again.
326+
await $`exit 1`.retry(3).delay(1000);
327+
```
328+
287329
- `.timeout(timeout: number)` Throws an error if the command takes longer than
288330
the provided `timeout` in milliseconds.
289331

332+
```ts
333+
// Kill the command if it takes longer than one second.
334+
await $`sleep 10`.timeout(1000);
335+
```
336+
290337
- `.kill(signal: Deno.Signal)` Kills the running process.
291338

339+
```ts
340+
// Manually kill the command.
341+
const child = $`sleep 10`;
342+
setTimout(() => child.kill("SIGINT"), 100);
343+
await child;
344+
```
345+
292346
### Modules
293347

294348
- **$.\[style]:** Cliffy's color module. A chainable wrapper for Deno's

0 commit comments

Comments
 (0)