Commit cc36915

Anton Golub <antongolub@antongolub.com>
2024-05-21 14:52:36
docs: describe `$.preferLocal`, `abort()`API and `ProcessPromise` formatters (#817)
1 parent d8cd974
configuration.md
@@ -32,6 +32,16 @@ Like a `$.prefix`, but for the end of the command.
 $.postfix = '; exit $LastExitCode' // for PowerShell compatibility
 ```
 
+## $.preferLocal
+
+Specifies whether to prefer `node_modules/.bin` located binaries over globally system installed ones.
+
+```js
+$.preferLocal = true
+
+await $`c8 npm test`
+```
+
 ## $.quote
 
 Specifies a function for escaping special characters during
process-promise.md
@@ -44,6 +44,21 @@ if (await $`[[ -d path ]]`.exitCode == 0) {
 }
 ```
 
+## `json(), text(), lines(), buffer(), blob()`
+
+Output formatters collection.
+
+```js
+const p = $`echo 'foo\nbar'`
+
+await p.text()        // foo\n\bar\n
+await p.text('hex')   //  666f6f0a0861720a
+await p.buffer()      //  Buffer.from('foo\n\bar\n')
+await p.lines()       // ['foo', 'bar']
+await $`echo '{"foo": "bar"}'`.json() // {foo: 'bar'}
+```
+
+
 ## `pipe()`
 
 Redirects the stdout of the process.
@@ -92,6 +107,29 @@ setTimeout(() => p.kill('SIGINT'), 100)
 await p
 ```
 
+## `abort()`
+
+Terminates the process via an `AbortController` signal.
+
+```js
+const ac = new AbortController()
+const {signal} = ac
+const p = $({signal})`sleep 999`
+
+setTimeout(() => ac.abort('reason'), 100)
+await p
+```
+
+If `ac` or `signal` is not provided, it will be autocreated and could be used to control external processes.
+
+```js
+const p = $`sleep 999`
+const {signal} = p
+
+const res = fetch('https://example.com', {signal})
+p.abort('reason')
+```
+
 ## `stdio()`
 
 Specifies a stdio for the process.