进程 Promise

¥Process Promise

$ 返回 ProcessPromise 实例。解决后，它就变成了 ProcessOutput。

¥The $ returns a ProcessPromise instance. When resolved, it becomes a ProcessOutput.

const p = $`command` // ProcessPromise

const o = await p    // ProcessOutput

stdin

返回 stdin 进程的可写流。访问此 getter 将触发执行具有 stdio('pipe') 的子进程。

¥Returns a writable stream of the stdin process. Accessing this getter will trigger execution of a subprocess with stdio('pipe').

不要忘记结束流。

¥Do not forget to end the stream.

const p = $`while read; do echo $REPLY; done`
p.stdin.write('Hello, World!\n')
p.stdin.end()

默认情况下，每个进程都是使用 stdin 以继承模式创建的。

¥By default, each process is created with stdin in inherit mode.

stdout/stderr

返回 stdout/stderr 进程的可读流。

¥Returns a readable streams of stdout/stderr process.

const p = $`npm init`
for await (const chunk of p.stdout) {
  echo(chunk)
}

exitCode

返回一个解析为进程退出代码的 promise。

¥Returns a promise which resolves to the exit code of the process.

if (await $`[[ -d path ]]`.exitCode == 0) {
...
}

json(), text(), lines(), buffer(), blob()

输出格式化程序集合。

¥Output formatters collection.

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.

await $`echo "Hello, stdout!"`
  .pipe(fs.createWriteStream('/tmp/output.txt'))

await $`cat /tmp/output.txt`

管道可用于显示进程的实时输出：

¥Pipes can be used to show a real-time output of the process:

await $`echo 1; sleep 1; echo 2; sleep 1; echo 3;`
  .pipe(process.stdout)

pipe() 方法可以组合 $ 过程。与 bash 中的 | 相同：

¥The pipe() method can combine $ processes. Same as | in bash:

const greeting = await $`printf "hello"`
  .pipe($`awk '{printf $1", world!"}'`)
  .pipe($`tr '[a-z]' '[A-Z]'`)

echo(greeting)

使用 pipe() 和 nothrow() 的组合：

¥Use combinations of pipe() and nothrow():

await $`find ./examples -type f -print0`
  .pipe($`xargs -0 grep ${'missing' + 'part'}`.nothrow())
  .pipe($`wc -l`)

kill()

杀死进程和所有子进程。

¥Kills the process and all children.

默认情况下，发送信号 SIGTERM。你可以通过参数指定信号。

¥By default, signal SIGTERM is sent. You can specify a signal via an argument.

const p = $`sleep 999`
setTimeout(() => p.kill('SIGINT'), 100)
await p

abort()

通过 AbortController 信号终止进程。

¥Terminates the process via an AbortController signal.

const ac = new AbortController()
const {signal} = ac
const p = $({signal})`sleep 999`

setTimeout(() => ac.abort('reason'), 100)
await p

如果未提供 ac 或 signal，它将自动创建并可用于控制外部进程。

¥If ac or signal is not provided, it will be autocreated and could be used to control external processes.

const p = $`sleep 999`
const {signal} = p

const res = fetch('https://example.com', {signal})
p.abort('reason')

stdio()

指定进程的 stdio。

¥Specifies a stdio for the process.

默认为 .stdio('inherit', 'pipe', 'pipe')。

¥Default is .stdio('inherit', 'pipe', 'pipe').

const p = $`read`.stdio('pipe')

nothrow()

更改 $ 的行为，使其在非零退出代码时不引发异常。

¥Changes behavior of $ to not throw an exception on non-zero exit codes.

await $`grep something from-file`.nothrow()

// Inside a pipe():

await $`find ./examples -type f -print0`
  .pipe($`xargs -0 grep something`.nothrow())
  .pipe($`wc -l`)

如果只需要 exitCode，可以直接使用 exitCode：

¥If only the exitCode is needed, you can use exitCode directly:

if (await $`[[ -d path ]]`.exitCode == 0) {
...
}

// Equivalent of:

if ((await $`[[ -d path ]]`.nothrow()).exitCode == 0) {
...
}

quiet()

更改 $ 的行为以启用抑制模式。

¥Changes behavior of $ to enable suppress mode.

// Command output will not be displayed.
await $`grep something from-file`.quiet()

$.quiet = true
await $`echo foo`.quiet(false) // Disable for the specific command

verbose()

启用详细输出。传递 false 以禁用。

¥Enables verbose output. Pass false to disable.

await $`grep something from-file`.verbose()

$.verbose = true
await $`echo foo`.verbose(false) // Turn off verbose mode once

timeout()

在指定的超时后终止进程。

¥Kills the process after a specified timeout.

await $`sleep 999`.timeout('5s')

// Or with a specific signal.
await $`sleep 999`.timeout('5s', 'SIGKILL')