eigen
eigen copied to clipboard
feat(scripts): try out zx for our scripts
The type of this PR is: TYPE
This PR resolves []
Description
https://github.com/google/zx
I found zx and i really liked it, so i thought ill try it out in a few scripts. i have tried different things over the years, bash, node, ts-node, deno, and other stuff. this one seems to bring the easiest api with the least overhead. with it, we get the benefit of js in our scripts, and easy terminal command calls.
there is only one thing that still bash scripts are more clear on, and its things like curl https://whatever.com > saved.txt
, where in zx this is written as await $`curl https://whatever.com`.pipe(fs.createWriteStream("saved.txt"))
. not the best but not bad, and we could probably make a function and use it like .pipe(out("saved.txt"))
or something.
in any case, i would suggest to look at the scripts before and after, and see for yourself if you like this or not. i definitely prefer it, because with it we can turn all our scripts in the same "language". all scripts get the set -euo pipefail
which is great, its super easy to just call terminal commands in it, its just javascript, we get async stuff on top level because zx uses mjs
as the default which is great, and we then are more consistent, no more bash and js and ts and ruby and deno etc.
one other cool thing i discovered while using zx, is the shebang language associator https://marketplace.visualstudio.com/items?itemName=davidhewitt.shebang-language-associator, which ill be using personally from now on, but i also added a little config for eigen too. basically our scripts could be named like fetch-echo
or fetch-echo.mjs
or fetch-echo.sh
or fetch-echo.js
etc. i always prefered no extension, as they are just scripts and commands, no need to care for implementation, but sometimes i have added extensions in the past, to make vscode understand the language, and the tools, like prettier. with this extension, i can finally get what i want! no extension, perfect, and also language detection based on the shebang of the file, magical! so there we go. use it if you like it. its awesome.
follow up work:
- [ ] turn the rest of the scripts into zx
- [ ] make sure prettier runs on these scripts
- [ ] make tsc run on these scripts optionally?
PR Checklist (tick all before merging)
- [ ] I have included screenshots or videos to illustrate my changes, or I have not changed anything that impacts the UI.
- [ ] I have tested my changes on iOS and Android.
- [ ] I have added tests/stories for my changes, or my changes don't require testing/stories, or I have included a link to a separate Jira ticket covering the tests.
- [ ] I have added a feature flag, or my changes don't require a feature flag. (How do I add one?)
- [ ] I have documented any follow-up work that this PR will require, or it does not require any.
- [ ] I have added an app state migration, or my changes do not require one. (What are migrations?)
- [ ] I have added a changelog entry below or my changes do not require one.
To the reviewers 👀
- [ ] I would like at least one of the reviewers to run this PR on the simulator or device.
Changelog updates
Changelog updates
Cross-platform user-facing changes
iOS user-facing changes
Android user-facing changes
Dev changes
Warnings | |
---|---|
:warning: | Please assign someone to merge this PR, and optionally include people who should review. |
zx
Author: Anton Medvedev
Description: A tool for writing better scripts.
Homepage: https://github.com/google/zx#readme
Created | about 8 years ago |
Last Updated | 13 days ago |
License | Apache-2.0 |
Maintainers | 2 |
Releases | 46 |
Direct Dependencies | @types/fs-extra , @types/minimist , @types/node , chalk , fs-extra , globby , minimist , node-fetch , ps-tree , which and yaml |
README
🐚 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 is great, but when it comes to writing scripts,
people usually choose a more convenient programming language.
JavaScript is a perfect choice, but standard Node.js library
requires additional hassle before using. The zx
package provides
useful wrappers around child_process
, escapes arguments and
gives sensible defaults.
Install
npm i -g zx
Requirement: Node version >= 16.0.0
Documentation
Write your scripts in a file with .mjs
extension in order to
be able to use await
on top level. If you prefer the .js
extension,
wrap your scripts in something like void async function () {...}()
.
Add the following shebang to the beginning of your zx
scripts:
#!/usr/bin/env zx
Now you will be able to run your script like so:
chmod +x ./script.mjs
./script.mjs
Or via the zx
executable:
zx ./script.mjs
All functions ($
, cd
, fetch
, etc) are available straight away
without any imports.
Or import globals explicitly (for better autocomplete in VS Code).
import 'zx/globals'
$`command`
Executes a given string using the spawn
function from the
child_process
package and returns ProcessPromise<ProcessOutput>
.
Everything passed through ${...}
will be automatically escaped and quoted.
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<T> extends Promise<T> {
readonly stdin: Writable
readonly stdout: Readable
readonly stderr: Readable
readonly exitCode: Promise<number>
pipe(dest): ProcessPromise<T>
kill(signal = 'SIGTERM'): Promise<void>
}
The pipe()
method can be used to redirect stdout:
await $`cat file.txt`.pipe(process.stdout)
Read more about pipelines.
ProcessOutput
class ProcessOutput {
readonly stdout: string
readonly stderr: string
readonly exitCode: number
readonly signal: 'SIGTERM' | 'SIGKILL' | ...
toString(): string
}
Functions
cd()
Changes the current working directory.
cd('/tmp')
await $`pwd` // outputs /tmp
fetch()
A wrapper around the node-fetch package.
let resp = await fetch('https://wttr.in')
if (resp.ok) {
console.log(await resp.text())
}
question()
A wrapper around the readline package.
Usage:
let bear = await question('What kind of bear is best? ')
let token = await question('Choose env variable: ', {
choices: Object.keys(process.env)
})
In second argument, array of choices for Tab autocompletion can be specified.
function question(query?: string, options?: QuestionOptions): Promise<string>
type QuestionOptions = { choices: string[] }
sleep()
A wrapper around the setTimeout
function.
await sleep(1000)
nothrow()
Changes behavior of $
to not throw an exception on non-zero exit codes.
function nothrow<P>(p: P): P
Usage:
await nothrow($`grep something from-file`)
// Inside a pipe():
await $`find ./examples -type f -print0`
.pipe(nothrow($`xargs -0 grep something`))
.pipe($`wc -l`)
If only the exitCode
is needed, you can use the next code instead:
if (await $`[[ -d path ]]`.exitCode == 0) {
...
}
// Equivalent of:
if ((await nothrow($`[[ -d path ]]`)).exitCode == 0) {
...
}
quiet()
Changes behavior of $
to disable verbose output.
function quiet<P>(p: P): P
Usage:
await quiet($`grep something from-file`)
// Command and output will not be displayed.
Packages
Following packages are available without importing inside scripts.
chalk
package
The chalk package.
console.log(chalk.blue('Hello world!'))
yaml
package
The yaml package.
console.log(YAML.parse('foo: bar').foo)
fs
package
The fs-extra package.
let content = await fs.readFile('./package.json')
globby
package
The globby package.
let packages = await globby(['package.json', 'packages/*/package.json'])
let pictures = globby.globbySync('content/*.(jpg|png)')
Also, globby available via the glob
shortcut:
await $`svgo ${await glob('*.svg')}`
os
package
The os package.
await $`cd ${os.homedir()} && mkdir example`
path
package
The path package.
await $`mkdir ${path.join(basedir, 'output')}`
minimist
package
The minimist package.
Available as global const argv
.
Configuration
$.shell
Specifies what shell is used. Default is which bash
.
$.shell = '/usr/bin/bash'
Or use a CLI argument: --shell=/bin/bash
$.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, the zx
prints all executed commands alongside with their
outputs.
Or use a CLI argument --quiet
to set $.verbose = false
.
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')
Experimental
The zx also provides a few experimental functions. Please leave a feedback about those features in the discussion.
retry()
Retries a command a few times. Will return after the first successful attempt, or will throw after specifies attempts count.
import {retry} from 'zx/experimental'
let {stdout} = await retry(5)`curl localhost`
echo()
A console.log()
alternative which can take ProcessOutput.
import {echo} from 'zx/experimental'
let branch = await $`git branch --show-current`
echo`Current branch is ${branch}.`
// or
echo('Current branch is', branch)
startSpinner()
Starts a simple CLI spinner, and returns stop()
function.
import {startSpinner} from 'zx/experimental'
let stop = startSpinner()
await $`long-running command`
stop()
FAQ
Passing env variables
process.env.FOO = 'bar'
await $`echo $FOO`
Passing array of values
If array of values passed as argument to $
, items of the array will be escaped
individually and concatenated via space.
Example:
let files = [...]
await $`tar cz ${files}`
Importing from 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 in markdown
(docs/markdown.md):
zx docs/markdown.md
TypeScript scripts
import {$} from 'zx'
// Or
import 'zx/globals'
void async function () {
await $`ls -la`
}()
Use ts-node as a esm node loader.
node --loader ts-node/esm script.ts
You must set "type": "module"
in package.json
and "module": "ESNext"
in tsconfig.json
.
{
"type": "module"
}
{
"compilerOptions": {
"module": "ESNext"
}
}
Executing remote scripts
If the argument to the zx
executable starts with https://
, the file will be
downloaded and executed.
zx https://medv.io/example-script.mjs
zx https://medv.io/game-of-life.mjs
Executing scripts from stdin
The zx
supports executing scripts from stdin.
zx <<'EOF'
await $`pwd`
EOF
License
Apache-2.0
Disclaimer: This is not an officially supported Google product.
New dependencies added: zx
.
Generated by :no_entry_sign: dangerJS against 39c9e95915c5f87f56cb0fbea0249a94265fef69
google zx, shmoogle zx. closing this, we will get this over to https://github.com/pvinis/multishcript when its done hehe