Skip to content

Commit ed09d11

Browse files
antonmedvantonmedv
committed
Add v7 folder
1 parent 52a123b commit ed09d11

11 files changed

+1028
-24
lines changed

‎.vitepress/config.mts

+49-24
Original file line numberDiff line numberDiff line change
@@ -24,35 +24,60 @@ export default defineConfig({
2424
{text: 'Home', link: '/'},
2525
{text: 'Docs', link: '/getting-started'},
2626
{
27-
text: '7.x',
27+
text: 'v8',
2828
items: [
29-
{text: 'Releases', link: 'https://github.com/google/zx/releases'},
29+
{text: 'v7', link: '/v7/api'},
3030
],
3131
},
3232
],
3333

34-
sidebar: [
35-
{
36-
text: 'Docs',
37-
items: [
38-
{text: 'Getting Started', link: '/getting-started'},
39-
{text: 'Process Promise', link: '/process-promise'},
40-
{text: 'API Reference', link: '/api'},
41-
{text: 'Configuration', link: '/configuration'},
42-
{text: 'CLI Usage', link: '/cli'},
43-
],
44-
},
45-
{
46-
text: 'FAQ',
47-
link: '/faq',
48-
items: [
49-
{text: 'Quotes', link: '/quotes'},
50-
{text: 'TypeScript', link: '/typescript'},
51-
{text: 'Markdown Scripts', link: '/markdown-scripts'},
52-
{text: 'Known Issues', link: '/known-issues'},
53-
],
54-
},
55-
],
34+
sidebar: {
35+
'/': [
36+
{
37+
text: 'Docs',
38+
items: [
39+
{text: 'Getting Started', link: '/getting-started'},
40+
{text: 'Process Promise', link: '/process-promise'},
41+
{text: 'API Reference', link: '/api'},
42+
{text: 'Configuration', link: '/configuration'},
43+
{text: 'CLI Usage', link: '/cli'},
44+
],
45+
},
46+
{
47+
text: 'FAQ',
48+
link: '/faq',
49+
items: [
50+
{text: 'Quotes', link: '/quotes'},
51+
{text: 'TypeScript', link: '/typescript'},
52+
{text: 'Markdown Scripts', link: '/markdown-scripts'},
53+
{text: 'Known Issues', link: '/known-issues'},
54+
],
55+
},
56+
],
57+
58+
'/v7/': [
59+
{
60+
text: 'Docs (v7)',
61+
items: [
62+
{text: 'Getting Started', link: '/v7/getting-started'},
63+
{text: 'Process Promise', link: '/v7/process-promise'},
64+
{text: 'API Reference', link: '/v7/api'},
65+
{text: 'Configuration', link: '/v7/configuration'},
66+
{text: 'CLI Usage', link: '/v7/cli'},
67+
],
68+
},
69+
{
70+
text: 'FAQ',
71+
link: '/v7/faq',
72+
items: [
73+
{text: 'Quotes', link: '/v7/quotes'},
74+
{text: 'TypeScript', link: '/v7/typescript'},
75+
{text: 'Markdown Scripts', link: '/v7/markdown-scripts'},
76+
{text: 'Known Issues', link: '/v7/known-issues'},
77+
],
78+
},
79+
],
80+
},
5681

5782
socialLinks: [
5883
{icon: 'github', link: 'https://github.com/google/zx'},

‎v7/api.md

+206
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,206 @@
1+
::: warning
2+
This is documentation for zx v7, which is no longer actively maintained.
3+
4+
For up-to-date documentation, see the [latest version](/api) (v8).
5+
:::
6+
7+
# API Reference
8+
9+
## cd()
10+
11+
Changes the current working directory.
12+
13+
```js
14+
cd('/tmp')
15+
await $`pwd` // => /tmp
16+
```
17+
18+
Like `echo`, in addition to `string` arguments, `cd` accepts and trims
19+
trailing newlines from `ProcessOutput` enabling common idioms like:
20+
21+
```js
22+
cd(await $`mktemp -d`)
23+
```
24+
25+
## fetch()
26+
27+
A wrapper around the [node-fetch](https://www.npmjs.com/package/node-fetch)
28+
package.
29+
30+
```js
31+
const resp = await fetch('https://medv.io')
32+
```
33+
34+
## question()
35+
36+
A wrapper around the [readline](https://nodejs.org/api/readline.html) package.
37+
38+
```js
39+
const bear = await question('What kind of bear is best? ')
40+
```
41+
42+
## sleep()
43+
44+
A wrapper around the `setTimeout` function.
45+
46+
```js
47+
await sleep(1000)
48+
```
49+
50+
## echo()
51+
52+
A `console.log()` alternative which can take [ProcessOutput](#processoutput).
53+
54+
```js
55+
const branch = await $`git branch --show-current`
56+
57+
echo`Current branch is ${branch}.`
58+
// or
59+
echo('Current branch is', branch)
60+
```
61+
62+
## stdin()
63+
64+
Returns the stdin as a string.
65+
66+
```js
67+
const content = JSON.parse(await stdin())
68+
```
69+
70+
## within()
71+
72+
Creates a new async context.
73+
74+
```js
75+
await $`pwd` // => /home/path
76+
77+
within(async () => {
78+
cd('/tmp')
79+
80+
setTimeout(async () => {
81+
await $`pwd` // => /tmp
82+
}, 1000)
83+
})
84+
85+
await $`pwd` // => /home/path
86+
```
87+
88+
```js
89+
await $`node --version` // => v20.2.0
90+
91+
const version = await within(async () => {
92+
$.prefix += 'export NVM_DIR=$HOME/.nvm; source $NVM_DIR/nvm.sh; nvm use 16;'
93+
94+
return $`node --version`
95+
})
96+
97+
echo(version) // => v16.20.0
98+
```
99+
100+
## retry()
101+
102+
Retries a callback for a few times. Will return after the first
103+
successful attempt, or will throw after specifies attempts count.
104+
105+
```js
106+
const p = await retry(10, () => $`curl https://medv.io`)
107+
108+
// With a specified delay between attempts.
109+
const p = await retry(20, '1s', () => $`curl https://medv.io`)
110+
111+
// With an exponential backoff.
112+
const p = await retry(30, expBackoff(), () => $`curl https://medv.io`)
113+
```
114+
115+
## spinner()
116+
117+
Starts a simple CLI spinner.
118+
119+
```js
120+
await spinner(() => $`long-running command`)
121+
122+
// With a message.
123+
await spinner('working...', () => $`sleep 99`)
124+
```
125+
126+
## glob()
127+
128+
The [globby](https://github.com/sindresorhus/globby) package.
129+
130+
```js
131+
const packages = await glob(['package.json', 'packages/*/package.json'])
132+
```
133+
134+
## which()
135+
136+
The [which](https://github.com/npm/node-which) package.
137+
138+
```js
139+
const node = await which('node')
140+
```
141+
142+
## argv
143+
144+
The [minimist](https://www.npmjs.com/package/minimist) package.
145+
146+
A minimist-parsed version of the `process.argv` as `argv`.
147+
148+
```js
149+
if (argv.someFlag) {
150+
echo('yes')
151+
}
152+
```
153+
154+
Use minimist options to customize the parsing:
155+
156+
```js
157+
const myCustomArgv = minimist(process.argv.slice(2), {
158+
boolean: [
159+
'force',
160+
'help',
161+
],
162+
alias: {
163+
h: 'help',
164+
},
165+
})
166+
```
167+
168+
## chalk
169+
170+
The [chalk](https://www.npmjs.com/package/chalk) package.
171+
172+
```js
173+
console.log(chalk.blue('Hello world!'))
174+
```
175+
176+
## fs
177+
178+
The [fs-extra](https://www.npmjs.com/package/fs-extra) package.
179+
180+
```js
181+
const {version} = await fs.readJson('./package.json')
182+
```
183+
184+
## os
185+
186+
The [os](https://nodejs.org/api/os.html) package.
187+
188+
```js
189+
await $`cd ${os.homedir()} && mkdir example`
190+
```
191+
192+
## path
193+
194+
The [path](https://nodejs.org/api/path.html) package.
195+
196+
```js
197+
await $`mkdir ${path.join(basedir, 'output')}`
198+
```
199+
200+
## yaml
201+
202+
The [yaml](https://www.npmjs.com/package/yaml) package.
203+
204+
```js
205+
console.log(YAML.parse('foo: bar').foo)
206+
```

‎v7/cli.md

+91
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
::: warning
2+
This is documentation for zx v7, which is no longer actively maintained.
3+
4+
For up-to-date documentation, see the [latest version](/api) (v8).
5+
:::
6+
7+
# CLI Usage
8+
9+
Zx provides a CLI for running scripts. It is installed with the package and can be used as `zx` executable.
10+
11+
```sh
12+
zx script.mjs
13+
```
14+
15+
## No extensions
16+
17+
If script does not have a file extension (like `.git/hooks/pre-commit`), zx
18+
assumes that it is
19+
an [ESM](https://nodejs.org/api/modules.html#modules_module_createrequire_filename)
20+
module.
21+
22+
```bash
23+
zx docs/markdown.md
24+
```
25+
26+
## Remote scripts
27+
28+
If the argument to the `zx` executable starts with `https://`, the file will be
29+
downloaded and executed.
30+
31+
```bash
32+
zx https://medv.io/game-of-life.js
33+
```
34+
35+
## Scripts from stdin
36+
37+
The `zx` supports executing scripts from stdin.
38+
39+
```js
40+
zx << 'EOF'
41+
await $`pwd`
42+
EOF
43+
```
44+
45+
## --eval
46+
47+
Evaluate the following argument as a script.
48+
49+
```bash
50+
cat package.json | zx --eval 'const v = JSON.parse(await stdin()).version; echo(v)'
51+
```
52+
53+
## --install
54+
55+
```js
56+
// script.mjs:
57+
import sh from 'tinysh'
58+
59+
sh.say('Hello, world!')
60+
```
61+
62+
Add `--install` flag to the `zx` command to install missing dependencies
63+
automatically.
64+
65+
```bash
66+
zx --install script.mjs
67+
```
68+
69+
You can also specify needed version by adding comment with `@` after
70+
the import.
71+
72+
```js
73+
import sh from 'tinysh' // @^1
74+
```
75+
76+
## __filename & __dirname
77+
78+
In [ESM](https://nodejs.org/api/esm.html) modules, Node.js does not provide
79+
`__filename` and `__dirname` globals. As such globals are really handy in scripts,
80+
zx provides these for use in `.mjs` files (when using the `zx` executable).
81+
82+
## require()
83+
84+
In [ESM](https://nodejs.org/api/modules.html#modules_module_createrequire_filename)
85+
modules, the `require()` function is not defined.
86+
The `zx` provides `require()` function, so it can be used with imports in `.mjs`
87+
files (when using `zx` executable).
88+
89+
```js
90+
const {version} = require('./package.json')
91+
```

0 commit comments

Comments
 (0)