@universal-packages/sub-process
v1.15.10
Published
Process encapsulation for different exec technics
Downloads
52,122
Readme
Sub SubProcess
Sub process encapsulation for different exec technics.
Install
npm install @universal-packages/sub-process
SubProcess
SubProcess is the main interface to setup a process to run at whenever time and only once.
import { SubProcess } from '@universal-packages/sub-process'
const subProcess = new SubProcess({ command: 'echo', args: ['$VARIABLE'], env: { VARIABLE: 'value' } })
await subProcess.run()
console.log(subProcess.stdout.toString())
Options
args
string[]
Arguments to pass to the command.command
string
Command to run.engine
Engine | 'spawn' | 'exec' | 'fork' | 'test'
default: spawn
Instance of the engine to be used to execute the process or a string identifying the engine adapter.engineOptions
Object
Options to pass to the engine if resolved as adapter.env
Object
Environment variables to pass to the process.input
string | Buffer | string[] | Buffer[] | Readable
Input to pass to the process. For example when a process requires any kind of input like a yes/no question.timeout
number
Time to wait in milliseconds before killing the process.workingDirectory
string
Working directory to run the process in.
Instance methods
prepare()
async
Initialize the internal engine in case it needs preparation.
release()
async
Releases the engine resources in case they need to be disposed after finishing the process.
run()
async
Runs the process and waits for it to finish.
kill([signal: string])
async
Kills the process if it is running.
skip([reason: string])
Skips the process if it has not been started yet to mark it as skipped and do not let it run.
waitForStatus(status: string)
async
Waits for the process to reach a specific status or an status in the same level, for example success
or failure
will wait for the process to finish with any of those statuses.
Instance properties
stdout
string
Buffer containing the stdout of the process.
stderr
string
Buffer containing the stderr of the process.
exitCode
number
Exit code of the process.
signal
string
Signal that killed the process.
processId
number
Process id of the process.
status
idle | running | success | error | failure | killed | stopped | killing | stopping
Status of the process.
Events
SubProcess
will emit events regarding execution status and output.
subProcess.on('*', (event) => console.log(event))
subProcess.on('running', (event) => console.log(event))
subProcess.on('stdout', (event) => console.log(event))
subProcess.on('stderr', (event) => console.log(event))
subProcess.on('success', (event) => console.log(event))
subProcess.on('failure', (event) => console.log(event))
subProcess.on('stopping', (event) => console.log(event))
subProcess.on('stopped', (event) => console.log(event))
subProcess.on('skipped', (event) => console.log(event))
subProcess.on('end', (event) => console.log(event))
subProcess.on('timeout', (event) => console.log(event))
subProcess.on('error', (event) => console.log(event))
subProcess.on('warning', (event) => console.log(event))
Engine
To create an engine that suits your requirements you just need to implement new classes and use them as the following:
import MyEngine from './MyEngine'
const subProcess = new SubProcess({ engine: new MyEngine() })
You need to implement a engine process representation by subclassify the EngineProcess
class to provide a way to kill yur custom process.
import { EngineProcess } from '@universal-packages/sub-process'
export default class MyEngineProcess extends EngineProcess {
killObject(signal) {
this.object.sendKillSignal(signal)
}
}
The run method of the engine will be called with the command, args, input and env to execute the process and return an EngineProcess
instance.
export default class MyEngine {
constructor(options) {
// Options passed through the adapters sub system
}
prepare() {
// Initialize any connection using options
}
release() {
// Release any resources or close any connection
}
run(command, args, input, env) {
const myExecutableObject = myExecutionMethod.exec(command, args, input, env)
const engineProcess = new MyEngineProcess(myExecutableObject.processId, myExecutableObject)
// Now the SubProcess instance knows how to kill the process when needed as well as the process id.
return engineProcess
}
}
EngineInterface
If you are using TypeScript just implement the EngineInterface
in your class to ensure the right implementation.
import { EngineInterface } from '@universal-packages/sub-process'
export default class MyEngine implements EngineInterface {}
Typescript
This library is developed in TypeScript and shipped fully typed.
Contributing
The development of this library happens in the open on GitHub, and we are grateful to the community for contributing bugfixes and improvements. Read below to learn how you can take part in improving this library.