Running a background bash to reduce the amount of child processes.
Last updated a year ago by leichtgewicht .
MIT · Repository · Bugs · Original npm · Tarball · package.json
$ cnpm install bgbash 
SYNC missed versions from official npm registry.


Build Status JavaScript Style Guide Maintainability Test Coverage

bgbash is a partial drop-in replacement for require('child_process').exec specifically made for long-running applications.

npm i bgbash --save


Starting a child process using spawn or exec will create a new instance of ChildProcess, open several streams and create a new system background process. This is very expensive if you do it often. bgbash starts a single background process on the the first request, every future request will use that process's stdin to execute commands. Reducing the startup and feedback time for subsequent calls.

Performance comparison

"echo hi" - 2000 runs on node-v10.12.0(darwin) node.js bgback notes
startup 10.98ms 16.05ms 46% slower - The startup is naturally slower as it does a little more.
repeat response 4.91ms 1.96ms 251% faster - But repeat calls are significantly faster,
repeat user 1.31ms 0.95ms 137% faster - with part of it coming from the reduced user execution time ...
repeat system 0.64ms 0.04ms 1457% faster - ... and a significantly reduced system execution time.
rss 37.9Mb (avg. 19.8Mb) 9.9Mb (avg. 6.6Mb) With a significantly lower rss memory allocation (which is stable even with more calls)
heap total 37.5Mb (avg. 21.4Mb) 6Mb (avg. 3.2Mb) The node.js version also fills up the heap a lot quicker to a avg. 32Mb use at 10000 execs while the bgback version needs around 20000 to get there.
heap used 19.5Mb (avg. 6.3Mb) 4.1Mb (avg. 1.4Mb) The difference in size can be attributed to the additional code loaded. This will slightly grow with number of calls (~20kb per 5000 calls). Reason is unclear but consistent for both the node.js and bgback version.
c-memory inc. 8.6Kb (avg. -201b) 170b (avg. -7.8Kb) The C++ memory can be negative as some initial c memory is cleared.

Note: This data is compiled using the ./perf.js script.

API compatibility

The API of exec is implemented to be a reasonable (but not feature complete) drop-in replacement for node's native exec.

const { exec } = require('bgbash')

const cmd = 'echo hi'
const opts = { // (optional)
  cwd: '.',             // (optional) Path in which the code is to be executed, defaults to `process.cwd()`.
  env: { KEY: 'value' } // (optional) Environment variables to be used for the execution.
  timeout: 100,         // (optional) Time in milliseconds until a timeout appear, defaults to `0` = no timeout.
  encoding: 'utf8',     // (optional) Encoding to be used, an unknown or `null` encoding returns a Buffer.

exec(cmd, opts, (error, stdout, stderr) => {
  error // Error that might occur, i.e. TIMEOUT or of the process died.
  stdout // Output of the execution
  stderr // Error of the execution

A notable incompatibility is that stderr will be empty, even though output might exist, if no error occurs. This is done for performance reasons.

Closing at shutdown

The background process will continue to run forever. If you want the process to close, you have to run close().

const { exec, close } = require('bgbash')

exec('echo hi')
close( // Will be executed after the previous command completed!
  () => {
    // All closed!

Promises API

Much like node js, bgbash also comes with a Promise API that is available using either require('bgbash').promises or require('bgbash/promises').

const { exec } = require('bgbash').promises
const opts = { /* Same options as above. */ }
const { stdout, stderr } = await exec('echo hi', opts)

try {
  await exec('exit 1', opts)
} catch (error) {
  // Error that happened.



Current Tags

  • 1.0.0                                ...           latest (a year ago)

1 Versions

  • 1.0.0                                ...           a year ago
Maintainers (1)
Today 0
This Week 0
This Month 0
Last Day 0
Last Week 0
Last Month 1
Dependencies (2)
Dev Dependencies (4)
Dependents (0)

Copyright 2014 - 2017 © |