diff options
Diffstat (limited to 'node_modules/npm-run-all/docs')
| -rw-r--r-- | node_modules/npm-run-all/docs/node-api.md | 117 | ||||
| -rw-r--r-- | node_modules/npm-run-all/docs/npm-run-all.md | 192 | ||||
| -rw-r--r-- | node_modules/npm-run-all/docs/run-p.md | 156 | ||||
| -rw-r--r-- | node_modules/npm-run-all/docs/run-s.md | 147 |
4 files changed, 612 insertions, 0 deletions
diff --git a/node_modules/npm-run-all/docs/node-api.md b/node_modules/npm-run-all/docs/node-api.md new file mode 100644 index 0000000..37530e1 --- /dev/null +++ b/node_modules/npm-run-all/docs/node-api.md @@ -0,0 +1,117 @@ +| [index](../README.md) | [npm-run-all](npm-run-all.md) | [run-s](run-s.md) | [run-p](run-p.md) | Node API | +|-----------------------|-------------------------------|-------------------|-------------------|----------| + +# Node API + +A Node module to run given npm-scripts in parallel or sequential. + +```js +const runAll = require("npm-run-all"); + +runAll(["clean", "lint", "build:*"], {parallel: false}) + .then(() => { + console.log("done!"); + }) + .catch(err => { + console.log("failed!"); + }); + +runAll(["build:* -- --watch"], {parallel: true}) + .then(() => { + console.log("done!"); + }) + .catch(err => { + console.log("failed!"); + }); +``` + +## runAll + +``` +let promise = runAll(patterns, options); +``` + +Run npm-scripts. + +- **patterns** `string|string[]` -- Glob-like patterns for script names. +- **options** `object` + - **options.aggregateOutput** `boolean` -- + The flag to avoid interleaving output by delaying printing of each command's output until it has finished. + This option is valid only with `options.parallel` option. + Default is `false`. + - **options.arguments** `string[]` -- + An argument list to replace argument placeholders (such as `{1}`, `{2}`). If pattern text has `{1}`, it's replaced by `options.arguments[0]`. + Default is an empty array. + - **options.continueOnError** `boolean` -- + The flag to continue executing other/subsequent scripts even if a script threw an error. + Returned `Promise` object will be rejected if one or more scripts threw error(s). + Default is `false`. + - **options.parallel** `boolean` -- + The flag to run scripts in parallel. + Default is `false`. + - **options.maxParallel** `number` -- + The maximum number of parallelism. + This option is valid only with `options.parallel` option. + Default is `Number.POSITIVE_INFINITY`. + - **options.npmPath** `string` -- + The path to npm. + Default is `process.env.npm_execpath` or `"npm"`. + - **options.packageConfig** `object|null` -- + The map-like object to overwrite package configs. + Keys are package names. + Every value is a map-like object (Pairs of variable name and value). + e.g. `{"npm-run-all": {"test": 777, "test2": 333}}` + Default is `null`. + - **options.printLabel** `boolean` -- + Set the flag to print the task name as a prefix on each line of output. + Tools in scripts may stop coloring their output if this option is given. + Default is `false`. + - **options.printName** `boolean` -- + Set the flag to print the task name before running each task. + Default is `false`. + - **options.race** `boolean` -- + Set the flag to kill all npm-scripts when a npm-script finished with zero. + This option is valid only with `options.parallel` option. + Default is `false`. + - **options.silent** `boolean` -- + The flag to set `silent` to the log level of npm. + Default is `false`. + - **options.stdin** `stream.Readable|null` -- + The readable stream to send to the stdin of npm-scripts. + Default is nothing. + Set `process.stdin` in order to send from stdin. + - **options.stdout** `stream.Writable|null` -- + The writable stream to receive from the stdout of npm-scripts. + Default is nothing. + Set `process.stdout` in order to print to stdout. + - **options.stderr** `stream.Writable|null` -- + The writable stream to receive from the stderr of npm-scripts + Default is nothing. + Set `process.stderr` in order to print to stderr. + - **options.taskList** `string[]|null` -- + The string array of all script names. + If this is `null`, it reads from `package.json` in the current directory. + Default is `null`. + +`runAll` returns a promise that will becomes *fulfilled* when all scripts are completed. +The promise will become *rejected* when any of the scripts exit with a non-zero code. + +The promise gives `results` to the fulfilled handler. +`results` is an array of objects which have 2 properties: `name` and `code`. +The `name` property is the name of a npm-script. +The `code` property is the exit code of the npm-script. If the npm-script was not executed, the `code` property is `undefined`. + +```js +runAll(["clean", "lint", "build"]) + .then(results => { + console.log(`${results[0].name}: ${results[0].code}`); // clean: 0 + console.log(`${results[1].name}: ${results[1].code}`); // lint: 0 + console.log(`${results[2].name}: ${results[2].code}`); // build: 0 + }); +``` + +## About MaxListenersExceededWarning + +- If you use `options.stdin`, `options.stdout`, or `options.stderr` in parallel mode, please configure max listeners by [emitter.setMaxListeners(n)](https://nodejs.org/api/events.html#events_emitter_setmaxlisteners_n) properly. +- If you don't use those options and `process.stdXXX.isTTY` is `false`, please configure max listeners of the `process.stdXXX` properly. In that case, `npm-run-all` uses piping to connect to child processes.<br> + On the other hand, if `process.stdXXX.isTTY` is `true`, `npm-run-all` uses `inherit` option, so the configuration is unnecessary. diff --git a/node_modules/npm-run-all/docs/npm-run-all.md b/node_modules/npm-run-all/docs/npm-run-all.md new file mode 100644 index 0000000..c6f1aaa --- /dev/null +++ b/node_modules/npm-run-all/docs/npm-run-all.md @@ -0,0 +1,192 @@ +| [index](../README.md) | npm-run-all | [run-s](run-s.md) | [run-p](run-p.md) | [Node API](node-api.md) | +|-----------------------|-------------|-------------------|-------------------|-------------------------| + +# `npm-run-all` command + +``` +Usage: + $ npm-run-all [--help | -h | --version | -v] + $ npm-run-all [tasks] [OPTIONS] + + Run given npm-scripts in parallel or sequential. + + <tasks> : A list of npm-scripts' names and Glob-like patterns. + +Options: + --aggregate-output - - - Avoid interleaving output by delaying printing of + each command's output until it has finished. + -c, --continue-on-error - Set the flag to continue executing + other/subsequent tasks even if a task threw an + error. 'npm-run-all' itself will exit with + non-zero code if one or more tasks threw error(s) + --max-parallel <number> - Set the maximum number of parallelism. Default is + unlimited. + --npm-path <string> - - - Set the path to npm. Default is the value of + environment variable npm_execpath. + If the variable is not defined, then it's "npm." + In this case, the "npm" command must be found in + environment variable PATH. + -l, --print-label - - - - Set the flag to print the task name as a prefix + on each line of output. Tools in tasks may stop + coloring their output if this option was given. + -n, --print-name - - - - Set the flag to print the task name before + running each task. + -p, --parallel <tasks> - Run a group of tasks in parallel. + e.g. 'npm-run-all -p foo bar' is similar to + 'npm run foo & npm run bar'. + -r, --race - - - - - - - Set the flag to kill all tasks when a task + finished with zero. This option is valid only + with 'parallel' option. + -s, --sequential <tasks> - Run a group of tasks sequentially. + --serial <tasks> e.g. 'npm-run-all -s foo bar' is similar to + 'npm run foo && npm run bar'. + '--serial' is a synonym of '--sequential'. + --silent - - - - - - - - Set 'silent' to the log level of npm. + +Examples: + $ npm-run-all --serial clean lint build:** + $ npm-run-all --parallel watch:** + $ npm-run-all clean lint --parallel "build:** -- --watch" + $ npm-run-all -l -p start-server start-browser start-electron +``` + +### npm-scripts + +It's `"scripts"` field of `package.json`. +For example: + +```json +{ + "scripts": { + "clean": "rimraf dist", + "lint": "eslint src", + "build": "babel src -o lib" + } +} +``` + +We can run a script with `npm run` command. +On the other hand, this `npm-run-all` command runs multiple scripts in parallel or sequential. + +### Run scripts sequentially + +``` +$ npm-run-all clean lint build +``` + +This is same as `npm run clean && npm run lint && npm run build`. + +**Note:** If a script exited with non zero code, the following scripts are not run. +If `--continue-on-error` option is given, this behavior will be disabled. + +### Run scripts in parallel + +``` +$ npm-run-all --parallel lint build +``` + +This is similar to `npm run lint & npm run build`. + +**Note1:** If a script exited with a non-zero code, the other scripts and those descendant processes are killed with `SIGTERM` (On Windows, with `taskkill.exe /F /T`). +If `--continue-on-error` option is given, this behavior will be disabled. + +**Note2:** `&` operator does not work on Windows' `cmd.exe`. But `npm-run-all --parallel` works fine there. + +### Run a mix of sequential and parallel scripts + +``` +$ npm-run-all clean lint --parallel watch:html watch:js +``` + +1. First, this runs `clean` and `lint` sequentially / serially. +2. Next, runs `watch:html` and `watch:js` in parallel. + +``` +$ npm-run-all a b --parallel c d --sequential e f --parallel g h i +``` +or + +``` +$ npm-run-all a b --parallel c d --serial e f --parallel g h i +``` + +1. First, runs `a` and `b` sequentially / serially. +2. Second, runs `c` and `d` in parallel. +3. Third, runs `e` and `f` sequentially / serially. +4. Lastly, runs `g`, `h`, and `i` in parallel. + +### Glob-like pattern matching for script names + +We can use [glob]-like patterns to specify npm-scripts. +The difference is one -- the separator is `:` instead of `/`. + +``` +$ npm-run-all --parallel watch:* +``` + +In this case, runs sub scripts of `watch`. For example: `watch:html`, `watch:js`. +But, doesn't run sub-sub scripts. For example: `watch:js:index`. + +``` +$ npm-run-all --parallel watch:** +``` + +If we use a globstar `**`, runs both sub scripts and sub-sub scripts. + +`npm-run-all` reads the actual npm-script list from `package.json` in the current directory, then filters the scripts by glob-like patterns, then runs those. + +### Run with arguments + +We can enclose a script name or a pattern in quotes to use arguments. +The following 2 commands are similar. + +``` +$ npm-run-all --parallel "build:* -- --watch" +$ npm run build:aaa -- --watch & npm run build:bbb -- --watch +``` + +When we use a pattern, arguments are forwarded to every matched script. + +### Argument placeholders + +We can use placeholders to give the arguments preceded by `--` to scripts. + +``` +$ npm-run-all build "start-server -- --port {1}" -- 8080 +``` + +This is useful to pass through arguments from `npm run` command. + +```json +{ + "scripts": { + "start": "npm-run-all build \"start-server -- --port {1}\" --" + } +} +``` + +``` +$ npm run start 8080 + +> example@0.0.0 start /path/to/package.json +> npm-run-all build "start-server -- --port {1}" -- "8080" +``` + +There are the following placeholders: + +- `{1}`, `{2}`, ... -- An argument. `{1}` is the 1st argument. `{2}` is the 2nd. +- `{@}` -- All arguments. +- `{*}` -- All arguments as combined. + +Those are similar to [Shell Parameters](http://www.gnu.org/software/bash/manual/bashref.html#Shell-Parameters). But please note arguments are enclosed by double quotes automatically (similar to npm). + +### Known Limitations + +- If `--print-label` option is given, some tools in scripts might stop coloring their output. + Because some coloring library (e.g. [chalk]) will stop coloring if `process.stdout` is not a TTY. + `npm-run-all` changes the `process.stdout` of child processes to a pipe in order to add labels to the head of each line if `--print-label` option is given.<br> + For example, [eslint] stops coloring under `npm-run-all --print-label`. But [eslint] has `--color` option to force coloring, we can use it. For anything [chalk] based you can set the environment variable `FORCE_COLOR=1` to produce colored output anyway. + +[glob]: https://www.npmjs.com/package/glob#glob-primer +[chalk]: https://www.npmjs.com/package/chalk +[eslint]: https://www.npmjs.com/package/eslint diff --git a/node_modules/npm-run-all/docs/run-p.md b/node_modules/npm-run-all/docs/run-p.md new file mode 100644 index 0000000..ce9d309 --- /dev/null +++ b/node_modules/npm-run-all/docs/run-p.md @@ -0,0 +1,156 @@ +| [index](../README.md) | [npm-run-all](npm-run-all.md) | [run-s](run-s.md) | run-p | [Node API](node-api.md) | +|-----------------------|-------------------------------|-------------------|-------|-------------------------| + +# `run-p` command + +A CLI command to run given npm-scripts in parallel. +This command is the shorthand of `npm-run-all -p`. + +``` +Usage: + $ run-p [--help | -h | --version | -v] + $ run-p [OPTIONS] <tasks> + + Run given npm-scripts in parallel. + + <tasks> : A list of npm-scripts' names and Glob-like patterns. + +Options: + --aggregate-output - - - Avoid interleaving output by delaying printing of + each command's output until it has finished. + -c, --continue-on-error - Set the flag to continue executing other tasks + even if a task threw an error. 'run-p' itself + will exit with non-zero code if one or more tasks + threw error(s). + --max-parallel <number> - Set the maximum number of parallelism. Default is + unlimited. + --npm-path <string> - - - Set the path to npm. Default is the value of + environment variable npm_execpath. + If the variable is not defined, then it's "npm." + In this case, the "npm" command must be found in + environment variable PATH. + -l, --print-label - - - - Set the flag to print the task name as a prefix + on each line of output. Tools in tasks may stop + coloring their output if this option was given. + -n, --print-name - - - - Set the flag to print the task name before + running each task. + -r, --race - - - - - - - Set the flag to kill all tasks when a task + finished with zero. + -s, --silent - - - - - - Set 'silent' to the log level of npm. + + Shorthand aliases can be combined. + For example, '-clns' equals to '-c -l -n -s'. + +Examples: + $ run-p watch:** + $ run-p --print-label "build:** -- --watch" + $ run-p -l "build:** -- --watch" + $ run-p start-server start-browser start-electron +``` + +### npm-scripts + +It's `"scripts"` field of `package.json`. +For example: + +```json +{ + "scripts": { + "clean": "rimraf dist", + "lint": "eslint src", + "build": "babel src -o lib" + } +} +``` + +We can run a script with `npm run` command. +On the other hand, this `run-p` command runs multiple scripts in parallel. + +The following 2 commands are similar. +The `run-p` command is shorter and **available on Windows**. + +``` +$ run-p lint build +$ npm run lint & npm run build +``` + +**Note1:** If a script exited with a non-zero code, the other scripts and those descendant processes are killed with `SIGTERM` (On Windows, with `taskkill.exe /F /T`). +If `--continue-on-error` option is given, this behavior will be disabled. + +**Note2:** `&` operator does not work on Windows' `cmd.exe`. But `run-p` works fine there. + +### Glob-like pattern matching for script names + +We can use [glob]-like patterns to specify npm-scripts. +The difference is one -- the separator is `:` instead of `/`. + +``` +$ run-p watch:* +``` + +In this case, runs sub scripts of `watch`. For example: `watch:html`, `watch:js`. +But, doesn't run sub-sub scripts. For example: `watch:js:index`. + +``` +$ run-p watch:** +``` + +If we use a globstar `**`, runs both sub scripts and sub-sub scripts. + +`run-p` reads the actual npm-script list from `package.json` in the current directory, then filters the scripts by glob-like patterns, then runs those. + +### Run with arguments + +We can enclose a script name or a pattern in quotes to use arguments. +The following 2 commands are similar. + +``` +$ run-p "build:* -- --watch" +$ npm run build:aaa -- --watch & npm run build:bbb -- --watch +``` + +When we use a pattern, arguments are forwarded to every matched script. + +### Argument placeholders + +We can use placeholders to give the arguments preceded by `--` to scripts. + +``` +$ run-p "start-server -- --port {1}" -- 8080 +``` + +This is useful to pass through arguments from `npm run` command. + +```json +{ + "scripts": { + "start": "run-p \"start-server -- --port {1}\" --" + } +} +``` + +``` +$ npm run start 8080 + +> example@0.0.0 start /path/to/package.json +> run-p "start-server -- --port {1}" -- "8080" +``` + +There are the following placeholders: + +- `{1}`, `{2}`, ... -- An argument. `{1}` is the 1st argument. `{2}` is the 2nd. +- `{@}` -- All arguments. +- `{*}` -- All arguments as combined. + +Those are similar to [Shell Parameters](http://www.gnu.org/software/bash/manual/bashref.html#Shell-Parameters). But please note arguments are enclosed by double quotes automatically (similar to npm). + +### Known Limitations + +- If `--print-label` option is given, some tools in scripts might stop coloring their output. + Because some coloring library (e.g. [chalk]) will stop coloring if `process.stdout` is not a TTY. + `run-p` changes the `process.stdout` of child processes to a pipe in order to add labels to the head of each line if `--print-label` option is given.<br> + For example, [eslint] stops coloring under `run-p --print-label`. But [eslint] has `--color` option to force coloring, we can use it. + +[glob]: https://www.npmjs.com/package/glob#glob-primer +[chalk]: https://www.npmjs.com/package/chalk +[eslint]: https://www.npmjs.com/package/eslint diff --git a/node_modules/npm-run-all/docs/run-s.md b/node_modules/npm-run-all/docs/run-s.md new file mode 100644 index 0000000..cf62681 --- /dev/null +++ b/node_modules/npm-run-all/docs/run-s.md @@ -0,0 +1,147 @@ +| [index](../README.md) | [npm-run-all](npm-run-all.md) | run-s | [run-p](run-p.md) | [Node API](node-api.md) | +|-----------------------|-------------------------------|-------|-------------------|-------------------------| + +# `run-s` command + +A CLI command to run given npm-scripts sequentially. +This command is the shorthand of `npm-run-all -s`. + +``` +Usage: + $ run-s [--help | -h | --version | -v] + $ run-s [OPTIONS] <tasks> + + Run given npm-scripts sequentially. + + <tasks> : A list of npm-scripts' names and Glob-like patterns. + +Options: + -c, --continue-on-error - Set the flag to continue executing subsequent + tasks even if a task threw an error. 'run-s' + itself will exit with non-zero code if one or + more tasks threw error(s). + --npm-path <string> - - - Set the path to npm. Default is the value of + environment variable npm_execpath. + If the variable is not defined, then it's "npm." + In this case, the "npm" command must be found in + environment variable PATH. + -l, --print-label - - - - Set the flag to print the task name as a prefix + on each line of output. Tools in tasks may stop + coloring their output if this option was given. + -n, --print-name - - - - Set the flag to print the task name before + running each task. + -s, --silent - - - - - - Set 'silent' to the log level of npm. + + Shorthand aliases can be combined. + For example, '-clns' equals to '-c -l -n -s'. + +Examples: + $ run-s build:** + $ run-s lint clean build:** + $ run-s --silent --print-name lint clean build:** + $ run-s -sn lint clean build:** +``` + +### npm-scripts + +It's `"scripts"` field of `package.json`. +For example: + +```json +{ + "scripts": { + "clean": "rimraf dist", + "lint": "eslint src", + "build": "babel src -o lib" + } +} +``` + +We can run a script with `npm run` command. +On the other hand, this `run-s` command runs multiple scripts sequentially. + +The following 2 commands are the same. +The `run-s` command is shorter. + +``` +$ run-s clean lint build +$ npm run clean && npm run lint && npm run build +``` + +**Note:** If a script exited with a non-zero code, the following scripts are not run. + +### Glob-like pattern matching for script names + +We can use [glob]-like patterns to specify npm-scripts. +The difference is one -- the separator is `:` instead of `/`. + +``` +$ run-s build:* +``` + +In this case, runs sub scripts of `build`. For example: `build:html`, `build:js`. +But, doesn't run sub-sub scripts. For example: `build:js:index`. + +``` +$ run-s build:** +``` + +If we use a globstar `**`, runs both sub scripts and sub-sub scripts. + +`run-s` reads the actual npm-script list from `package.json` in the current directory, then filters the scripts by glob-like patterns, then runs those. + +### Run with arguments + +We can enclose a script name or a pattern in quotes to use arguments. +The following 2 commands are the same. + +``` +$ run-s start:server "delay 3000" start:client +$ npm run start:server && npm run delay 3000 && npm run start:client +``` + +When we use a pattern, arguments are forwarded to every matched script. + +### Argument placeholders + +We can use placeholders to give the arguments preceded by `--` to scripts. + +``` +$ run-s build "start-server -- --port {1}" -- 8080 +``` + +This is useful to pass through arguments from `npm run` command. + +```json +{ + "scripts": { + "start": "run-s build \"start-server -- --port {1}\" --" + } +} +``` + +``` +$ npm run start 8080 + +> example@0.0.0 start /path/to/package.json +> run-s build "start-server -- --port {1}" -- "8080" +``` + +There are the following placeholders: + +- `{1}`, `{2}`, ... -- An argument. `{1}` is the 1st argument. `{2}` is the 2nd. +- `{@}` -- All arguments. +- `{*}` -- All arguments as combined. + +Those are similar to [Shell Parameters](http://www.gnu.org/software/bash/manual/bashref.html#Shell-Parameters). But please note arguments are enclosed by double quotes automatically (similar to npm). + +### Known Limitations + +- If `--print-label` option is given, some tools in scripts might stop coloring their output. + Because some coloring library (e.g. [chalk]) will stop coloring if `process.stdout` is not a TTY. + `run-s` changes the `process.stdout` of child processes to a pipe in order to add labels to the head of each line if `--print-label` option is given.<br> + For example, [eslint] stops coloring under `run-s --print-label`. But [eslint] has `--color` option to force coloring, we can use it. + +[glob]: https://www.npmjs.com/package/glob#glob-primer +[chalk]: https://www.npmjs.com/package/chalk +[eslint]: https://www.npmjs.com/package/eslint |