Neat parallel task execution
npm install @schummar/runp
- Run commands in parallel, in series or any combination
- Reference npm scripts by name with glob support
- Command outputs will be separated in their own blocks instead of all mixed together
- Nested runp calls will be merged with indented sub commands
- CLI and type-safe Node API
``bash`
npm i @schummar/runp
`bash`
runp clean :p "build:*" :s "rm -rf .cache"
Assuming the following package.json:
`json`
{
"scripts": {
"clean": "rimraf dist",
"build:esm": "some build command",
"build:cjs": "another build command",
"build:type": "tsc --emitDeclarationOnly"
}
}
Each parameter can be a program, npm script, a flag or a switch. Arguments for programs and scripts can be added by encapsulating them in quotes.
- clean executes npm run clean
- :p for "parallel": remaining commands will be executed after the previous and in parallel
- "build:*" executes all script matching this glob (see minimatch)
Mind the quotes, otherwise your shell will try to resolve the wildcard!
- :s for "sequential": remaining commands will be execute after the previous and in series
- "rm -rf .cache" deletes the .cache folder
`
❯ runp --help
runp v1.5.0
Usage:
runp [flags...]
Flags:
-f, --forever Task will run forever. It won't display a spinner but a different symbol instead
-h, --help Show help
-k, --keep-output Keep output of successful commands visible
-n, --output-length
--version Show version
`
Options can either be used as flags (prefix "-") or switches (prefix ":"). Flags generally apply to all commands while switches can be used to change behavior midway for the remaining commands.
Flags -f, --forever apply to all commands
Switches :f, :f=false apply for all remaining commands
You might run commands in parallel that are supposed to run indefinitely, like a backend server and a frontend dev server. In this case instead of a spinner, runp can display an arrow icons instead. The effect is purely cosmetic:
Flag -k, --keep-output apply to all commands
Switches :k, :k=false apply to remaining commands
Usually a command's output will disappear after is has successfully executed. When --keep-output is set, it will remain visible.
Flags -n , --output-length apply to all commands
Switches :n= apply to remaining commands
Defines how many lines of output will be visible at maximum for each command.
Switches :p, :s apply to remaining commands
Commands after the :p switch will first wait for all commands before the switch to finish, then execute in parallel.
Commands after the :s switch will first wait for all commands before the switch to finish, then execute in series.
Both apply to all commands until another :p or :s appears.
It's possible to have multiple :p switches in succession, forming multiple parallel blocks.runp :p task1 task2 :p task3 task4
For example will execute first task1 and task2 in parallel, then task3 and task4 in parallel.
Before the first :p or :s switch appears, all commands will be executed in parallel by default.
Flags and switches can be combined. E.g. -fk or :pfn=10k=false
When an error occurs the command will be marked with a red x-symbol and the command output will remain visible.
Any parallel tasks are allowed to continue but dependent commands will not be executed.
When runp is executed as child process of another runp instance, it delegates its tasks to the parent instance.
Commands will be shown as child commands to the parent instance's command.
That is useful for example for composing npm scripts.
Say we have the following package.json:
`json`
{
"scripts": {
"lint": "eslint",
"clean": "rimraf dist",
"build": "build:*",
"build:esm": "some build command",
"build:cjs": "another build command",
"build:type": "tsc --emitDeclarationOnly",
"prepublishOnly": "runp :s lint build"
}
}
Running npm publish will now execute the prepublishOnly script, which in turn has runp execute the lint and build scripts.build
The script executes another instance of runp with its build:* commands.
The output however looks seamless:
`ts
import { runp } from '@schummar/runp';
runp({
keepOutput: true,
outputLength: 10,
commands: [
{
cmd: 'clean',
name: 'Clean',
keepOutput: false,
},
':p',
{
cmd: 'build:*',
cwd: 'src',
},
':s',
{
cmd: 'rm',
args: ['-rf', '.cache'],
},
],
});
`
The Node API allows running runp` programmatically with all the same options, plus a bit more fine grained control.
The executable or npm script to run.
Arguments to pass to executable or npm script.
Execute command in different working directory
Give a task an id that can be referenced as dependency.
Command will only start once all dependencies have finished.