executable-harness

Node.js - Electron - NW.js asynchronous controller for binary executables or scripts

Quick Start

npm install executable-harness

const executableHarness = require("executable-harness");

let test = {};
test.executable = "/test/executable";

test.stdoutFunction = function (stdout) {
  console.log(stdout);
};

executableHarness.startExecutable(test);

Single Dependency

child_process

API

All settings of an executable or script executed by executable-harness are stored in a JavaScript object with an arbitrary name and the following object properties:

• executable
  String for the filename of a binary executable or script:
  either filename on PATH or full pathname
  This object property is mandatory.

  test.executable = "/full/path/to/executable";

  or

  test.executable = "executable-on-path";

  There are two possible configurations when a script has to be started:

  • The executable object property points to the appropriate script interpreter and the executableArguments object property holds the script full pathname. In this case, the script is executed by the selected script interpreter regardless of the operating system.

  • The executable object property holds the script full pathname and the script is executed by the default interpreter of the operating system, if any.

• stdoutFunction
  will be executed every time data is available on STDOUT
  The only parameter passed to the stdoutFunction is the STDOUT String.

  test.stdoutFunction = function (stdout) {
    document.getElementById("DOM-element-id").textContent = stdout;
  };

• stderrFunction
  will be executed every time data is available on STDERR
  The only parameter passed to the stderrFunction is the STDERR String.

  test.stderrFunction = function (stderr) {
    console.log("STDERR:\n");
    console.log(stderr);
  };

• errorFunction
  will be executed on executable error
  The only parameter passed to the errorFunction is the error Object.

  The errorFunction can generate a message when executable is not found:

  test.errorFunction = function (error) {
    if (error.code === "ENOENT") {
      console.log("Executable was not found.");
    }
  };

• exitFunction
  will be executed when executable has ended
  The only parameter passed to the exitFunction is the exit code String.

  The exitFunction can generate a message when executable is not found:

  test.exitFunction = function (exitCode) {
    if (exitCode === 2) {
      console.log("Executable was not found.");
    }
  };

• executableArguments
  Array for command-line arguments

  test.executableArguments = [];
  test.executableArguments.push("argument-one");
  test.executableArguments.push("argument-two");

• options
  Object for executable options passed to the child_process core module.
  Click here for a full list of all available child_process options.

• options.cwd
  String for a new current working directory of the selected executable

  test.options = {};
  test.options.cwd = "/full/path/to/current-working-directory";;

• options.env
  Object for a new environment of the selected executable

  Executable environment with an inherited PATH and a new variable:

  test.options = {};
  test.options.env = {};
  test.options.env.PATH = process.env.PATH;
  test.options.env.TEST = "test";

• options.detached
  Boolean option for starting detached processes like servers

  options.detached must be set to true and
  options.stdio must be set to "ignore" to
  start a detached process without receiving anything from it.
  A process detached with the above options can run even after its parent has ended.

  Example settings for a server application:

  let server = {};
  server.executable = "/path/to/server-application";
  
  server.options = {};
  server.options.detached = true;
  server.options.stdio = "ignore";
  
  const executableHarness = require("executable-harness");
  executableHarness.startExecutable(server);
  
  server.executableHandler.unref();

• inputData
  String or Function supplying user data as its return value.
  inputData is written on executable STDIN.

  inputData function with no dependencies:

  test.inputData = function () {
    let data = document.getElementById("data-input").value;
    return data;
  }

Interactive Executables or Scripts

executable-harness can also start and communicate with interactive executables or scripts having their own event loops and capable of repeatedly receiving STDIN input. Use the following code to send data to an interactive executable or script waiting for input on STDIN:

let data = document.getElementById("data-input").value;
test.executableHandler.stdin.write(data);

Credits

License

MIT 2018
Dimitar D. Mitov