谷歌开源项目zx,在node中bash-爱代码爱编程
🐚 zx
#!/usr/bin/env zx
await $`cat package.json | grep name`
let branch = await $`git branch --show-current`
await $`dep deploy --branch=${branch}`
await Promise.all([
$`sleep 1; echo 1`,
$`sleep 2; echo 2`,
$`sleep 3; echo 3`,
])
let name = 'foo bar'
await $`mkdir /tmp/${name}`
Bash很棒,但当涉及到编写更复杂的脚本时,许多人更喜欢更方便的编程语言。JavaScript是一个完美的选择,但是Node.js标准库在使用之前需要额外的麻烦。zx包为child_process提供了有用的包装器,转义参数并给出了合理的默认值。
安装
npm i -g zx
Requirement: Node version >= 16.0.0
用于在远程主机上运行命令, 请看webpod.
文档
在扩展名为.mjs的文件中编写脚本,以便在顶层使用await。如果你更喜欢.js扩展名,可以将脚本包装在void async function(){…}()中。
在zx脚本的开头添加以下shebang:
#!/usr/bin/env zx
现在你可以像这样运行你的脚本:
chmod +x ./script.mjs
./script.mjs
或者通过zx可执行文件:
zx ./script.mjs
所有函数($,cd, fetch等)都可以直接使用,无需任何导入。
或者显式地导入全局变量(以便在VS Code中更好地自动补全)。
import 'zx/globals'
$command
使用spawn func执行给定命令并返回ProcessPromise。
所有东西都经过${…}将自动转义并引用。
let name = 'foo & bar'
await $`mkdir ${name}`
There is no need to add extra quotes. Read more about it in quotes.
You can pass an array of arguments if needed:
let flags = [
'--oneline',
'--decorate',
'--color',
]
await $`git log ${flags}`
If the executed program returns a non-zero exit code, ProcessOutput will be thrown.
try {
await $`exit 1`
} catch (p) {
console.log(`Exit code: ${p.exitCode}`)
console.log(`Error: ${p.stderr}`)
}
ProcessPromise
class ProcessPromise extends Promise<ProcessOutput> {
stdin: Writable
stdout: Readable
stderr: Readable
exitCode: Promise<number>
pipe(dest): ProcessPromise
kill(): Promise<void>
nothrow(): this
quiet(): this
}
Read more about the ProcessPromise.
ProcessOutput
class ProcessOutput {
readonly stdout: string
readonly stderr: string
readonly signal: string
readonly exitCode: number
toString(): string // Combined stdout & stderr.
}
The output of the process is captured as-is. Usually, programs print a new line \n at the end. If ProcessOutput is used as an argument to some other $ process, zx will use stdout and trim the new line.
let date = await $date
await $echo Current date is ${date}.
Functions
cd()
Changes the current working directory.
cd(‘/tmp’)
await $pwd
// => /tmp
fetch()
A wrapper around the node-fetch package.
let resp = await fetch(‘https://medv.io’)
question()
A wrapper around the readline package.
let bear = await question('What kind of bear is best? ')
sleep()
A wrapper around the setTimeout function.
await sleep(1000)
echo()
A console.log() alternative which can take ProcessOutput.
let branch = await $git branch --show-current
echoCurrent branch is ${branch}.
// or
echo(‘Current branch is’, branch)
stdin()
Returns the stdin as a string.
let content = JSON.parse(await stdin())
within()
Creates a new async context.
await $pwd
// => /home/path
within(async () => {
cd(‘/tmp’)
setTimeout(async () => {
await $pwd
// => /tmp
}, 1000)
})
await $pwd
// => /home/path
let version = await within(async () => {
.
p
r
e
f
i
x
+
=
′
e
x
p
o
r
t
N
V
M
D
I
R
=
.prefix += 'export NVM_DIR=
.prefix+=′exportNVMDIR=HOME/.nvm; source $NVM_DIR/nvm.sh; ’
await $nvm use 16
return $node -v
})
retry()
Retries a callback for a few times. Will return after the first successful attempt, or will throw after specifies attempts count.
let p = await retry(10, () => $curl https://medv.io
)
// With a specified delay between attempts.
let p = await retry(20, ‘1s’, () => $curl https://medv.io
)
// With an exponential backoff.
let p = await retry(30, expBackoff(), () => $curl https://medv.io
)
spinner()
Starts a simple CLI spinner.
await spinner(() => $long-running command
)
// With a message.
await spinner(‘working…’, () => $sleep 99
)
Packages
The following packages are available without importing inside scripts.
chalk package
The chalk package.
console.log(chalk.blue(‘Hello world!’))
fs package
The fs-extra package.
let {version} = await fs.readJson(‘./package.json’)
os package
The os package.
await $cd ${os.homedir()} && mkdir example
path package
The path package.
await $mkdir ${path.join(basedir, 'output')}
globby package
The globby package.
let packages = await glob([‘package.json’, ‘packages/*/package.json’])
yaml package
The yaml package.
console.log(YAML.parse(‘foo: bar’).foo)
minimist package
The minimist package available as global const argv.
if (argv.someFlag) {
echo(‘yes’)
}
which package
The which package.
let node = await which(‘node’)
Configuration
$.shell
Specifies what shell is used. Default is which bash.
$.shell = ‘/usr/bin/bash’
Or use a CLI argument: --shell=/bin/bash
$.spawn
Specifies a spawn api. Defaults to require(‘child_process’).spawn.
$.prefix
Specifies the command that will be prefixed to all commands run.
Default is set -euo pipefail;.
Or use a CLI argument: --prefix=‘set -e;’
$.quote
Specifies a function for escaping special characters during command substitution.
$.verbose
Specifies verbosity. Default is true.
In verbose mode, zx prints all executed commands alongside with their outputs.
Or use the CLI argument --quiet to set $.verbose = false.
$.env
Specifies an environment variables map.
Defaults to process.env.
$.cwd
Specifies a current working directory of all processes created with the $.
The cd() func changes only process.cwd() and if no $.cwd specified, all $ processes use process.cwd() by default (same as spawn behavior).
$.log
Specifies a logging function.
import { LogEntry, log } from ‘zx/core’
$.log = (entry: LogEntry) => {
switch (entry.kind) {
case ‘cmd’:
// for example, apply custom data masker for cmd printing
process.stderr.write(masker(entry.cmd))
break
default:
log(entry)
}
}
Polyfills
__filename & __dirname
In ESM modules, Node.js does not provide __filename and __dirname globals. As such globals are really handy in scripts, zx provides these for use in .mjs files (when using the zx executable).
require()
In ESM modules, the require() function is not defined. The zx provides require() function, so it can be used with imports in .mjs files (when using zx executable).
let {version} = require(‘./package.json’)
FAQ
Passing env variables
process.env.FOO = ‘bar’
await $echo $FOO
Passing array of values
When passing an array of values as an argument to $, items of the array will be escaped individually and concatenated via space.
Example:
let files = […]
await $tar cz ${files}
Importing into other scripts
It is possible to make use of $ and other functions via explicit imports:
#!/usr/bin/env node
import { $ } from ‘zx’
await $date
Scripts without extensions
If script does not have a file extension (like .git/hooks/pre-commit), zx assumes that it is an ESM module.
Markdown scripts
The zx can execute scripts written as markdown:
zx docs/markdown.md
TypeScript scripts
import { $ } from ‘zx’
// Or
import ‘zx/globals’
void async function () {
await $ls -la
}()
Set “type”: “module” in package.json and “module”: “ESNext” in tsconfig.json.
Executing remote scripts
If the argument to the zx executable starts with https://, the file will be downloaded and executed.
zx https://medv.io/game-of-life.js
Executing scripts from stdin
The zx supports executing scripts from stdin.
zx << ‘EOF’
await $pwd
EOF
Executing scripts via --eval
Evaluate the following argument as a script.
cat package.json | zx --eval ‘let v = JSON.parse(await stdin()).version; echo(v)’
Installing dependencies via --install
// script.mjs:
import sh from ‘tinysh’
sh.say(‘Hello, world!’)
Add --install flag to the zx command to install missing dependencies automatically.
zx --install script.mjs
You can also specify needed version by adding comment with @ after the import.
import sh from ‘tinysh’ // @^1
Executing commands on remote hosts
The zx uses webpod to execute commands on remote hosts.
import { ssh } from ‘zx’
await ssh(‘user@host’)echo Hello, world!
Attaching a profile
By default child_process does not include aliases and bash functions. But you are still able to do it by hand. Just attach necessary directives to the $.prefix.
.
p
r
e
f
i
x
+
=
′
e
x
p
o
r
t
N
V
M
D
I
R
=
.prefix += 'export NVM_DIR=
.prefix+=′exportNVMDIR=HOME/.nvm; source $NVM_DIR/nvm.sh; ’
await $nvm -v
Using GitHub Actions
The default GitHub Action runner comes with npx installed.
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Build
env:
FORCE_COLOR: 3
run: |
npx zx <<'EOF'
await $`...`
EOF
Canary / Beta / RC builds
Impatient early adopters can try the experimental zx versions. But keep in mind: these builds are ⚠️️__beta__ in every sense.
npm i zx@dev
npx zx@dev --install --quiet <<< ‘import _ from “lodash” /* 4.17.15 */; console.log(_.VERSION)’
License