terminal-spawn

A library which wraps Node's child_process.spawn to provide easy use of terminal commands.

It does this in an easy to use way by providing a nice interface on top of child_process.spawn which allows you to call it exactly the same way as if you were running commands directly in the terminal.

I personally use this for running gulp tasks, since I got used to using npm scripts and their ability to directly run terminal commands very easily. Since it returns both a Promise and a ChildProcess it can easily be used with gulp.

The promise resolves with the same information as spawnSync and does so once the close event has been received and thus you can await the promise to resolve if you wish to ensure it completed.

This project uses TypeScript and thus has types for it exported, so it works well in that environment. However, it also works just fine with vanilla JavaScript.

Installation

  npm install terminal-spawn

Usage

To just spawn a task if you don't need to know when it finishes

import terminalSpawn from 'terminal-spawn';
 
terminalSpawn('echo "hello world!"');

To spawn a task and wait for it to complete, checking status code

import terminalSpawn from 'terminal-spawn';
 
// execute inside of IIAFE since we can't use top-level await
(async () => {
  const subprocess = await terminalSpawn('echo "hello world!"').promise;
 
  if (subprocess.status === 0) {
    console.log('everything went well!');
  } else {
    console.warn('something went wrong!!!!');
  }
})();

To spawn a task which never terminates, killing it and ensuring it was killed

import terminalSpawn from 'terminal-spawn';
 
// execute inside of IIAFE since we can't use top-level await
(async () => {
  const subprocessSpawn = terminalSpawn(`
    while true
    do
      echo "hello world!"
      sleep 0.25
    done
  `);
  // wait for 500 ms to pass...
  const timeToWait = 500;
  await new Promise((resolve, _reject) =>
    setTimeout(() => {
      resolve();
    }, timeToWait),
  );
  subprocessSpawn.process.kill();
  // subprocess.signal should be 'SIGTERM'
  const subprocess = await subprocessSpawn.promise;
})();

API

terminalSpawn(command, options)

return type:

  {
    promise: Promise<SpawnSyncReturns<Buffer>>
    process: ChildProcess
  }

Executes the command inside of Node.js as if it were run in the shell. If command is an array then the commands will be run in series/sequentially.

The result is an object which contains both a Promise which has the same structure/type as the return value of the synchronous version of child_process.spawn. and also a 'ChildProcess`. Each of these are useful in certain circumstances, for example you need the process reference if you want to kill an infinite process. You may want to use the promise to check status codes or termination signals to verify that the process actually ended and how.

terminalSpawnParallel(command, options)

return type:

  {
    promise: Promise<SpawnSyncReturns<Buffer>>
    process: ChildProcess
  }

Executes the command inside of Node.js as if it were run in the shell, if command is an array then the commands will be run in parallel rather than in series/sequentially.

The result is an object which contains both a Promise which has the same structure/type as the return value of the synchronous version of child_process.spawn. and also a 'ChildProcess`. Each of these are useful in certain circumstances, for example you need the process reference if you want to kill an infinite process. You may want to use the promise to check status codes or termination signals to verify that the process actually ended and how.

command

type: string or string[]

The command will be run using the shell and the output will be redirected to the shell. This means that it will essentially function as if you ran it directly in a shell such as /bin/sh, but inside of Node.js.

If command is an array then all of the commands in the array will be executed: either in series or in parallel, depending on the function. The default is to executed them in series, as if they were called with && between them.

options

type: SpawnOptions

These are the options to pass to child_process.spawn they are the same as the spawn options and are passed directly to child_process.spawn.

By default they are:

  {
    stdio: 'inherit',
    shell: true,
  }

Which allows terminalSpawn to act like a terminal. However, if you wanted the nice argument passing of terminalSpawn, e.g. 'echo "hello world!" without actually using the terminal, then you could disable this using options.

The API for options is designed to be as user-friendly as possible thus, it assumes that you want to keep the terminal-like behavior, but may want to change other options such as using cwd. To support this the user-provided options are added to the default options, rather than always overwriting them (aka. set union). However, if you explicitly specify a a default command such as stdio then it will be overwritten.

However, it should be noted that if you pass the option shell: false then many features such as multiple commands run in series or parallel will not work due to reliance on running in a shell.

License

MIT Copyright (c) David Piper