spawn-rx: A better version of spawn

| Linux/OSX | Windows |
| --- | --- |
|  |  |

spawn-rx is a package that adds an Observable as well as a Promise version of
the child_process.spawn API, and fixes some deficiencies in spawn that come
up especially on Windows. For example:

* spawn searches PATH on POSIX platforms but will not on Windows, you need to
provide an exact path. spawn-rx makes Windows act like other platforms.

* On Windows, {detached: true} doesn't actually create a process group properly.
spawn-rx provides a spawnDetached method that allows you to spawn a detached
process and kill the entire process group if needed.

* POSIX platforms allow you to directly execute scripts that have a shebang at
the top of the file, whereas Windows can only natively spawn EXE files, which
makes executing npm binaries annoying. spawn-rx automatically rewrites your
cmd and args parameters for CMD scripts, PowerShell scripts, and node.js
files.

Examples

spawn-as-promise:

``js
// Will run down path to find C:\Windows\System32\wmic.exe, whereas normal
// 'spawn' would require an absolute path.
spawnPromise('wmic', [])
.then((result) => console.log(result));
`

Handle failed processes as errors:

`js
try {
await spawnPromise('exit', ['-1']);
} catch (e) {
console.log("Processes that return non-zero exit codes throw")
}
`

Kill running process trees:

`js
let disp = spawnDetached('takesALongTime', []).subscribe();
await Promise.delay(1000);

// Kill the process and its children by unsubscribing.
disp.dispose();
`

Stream process output:

`js
spawn('ls', ['-r'])
.subscribe(
(x) => console.log(x),
(e) => console.log("Process exited with an error"));
`

Execute scripts:

`js
// Executes ./node_modules/.bin/uuid.cmd on Windows if invoked via npm run
let result = await spawnPromise('uuid');
`

What's Jobber?

Jobber is a Windows executable that will execute a command in a process group,
and if signaled via a named pipe, will terminate that process group. It's used
in the implementation of spawnDetached. Jobber was written by me, and its license
is the same as spawn-rx, it is not a third-party dependency.

Spawn output

By default spawn will merge stdout and stderr into the returned observable.
You can exclude one or the other by passing ignore in the stdio option of spawn.

Alternatively if you call it with { split: true } option, the observable output
will be an object { source: 'stdout', text: '...' } so you can distinguish
the outputs.

Stdin support

If you provide an Observable in opts.stdin, it'll be subscribed upon
and fed into the child process stdin. Its completion will terminate stdin stream.

Methods

``typescript
/**
* Spawns a process attached as a child of the current process.
*
* @param {string} exe The executable to run
* @param {string[]} params The parameters to pass to the child
* @param {SpawnOptions & SpawnRxExtras} opts Options to pass to spawn.
*
* @return {Observable} Returns an Observable that when subscribed
* to, will create a child process. The
* process output will be streamed to this
* Observable, and if unsubscribed from, the
* process will be terminated early. If the
* process terminates with a non-zero value,
* the Observable will terminate with onError.
*/
function spawn(
exe: string,
params: string[],
opts: SpawnOptions & SpawnRxExtras & { split: true }
): Observable;

function spawn(
exe: string,
params: string[],
opts?: SpawnOptions & SpawnRxExtras & { split: false | undefined }
): Observable;

/**
* Spawns a process but detached from the current process. The process is put
* into its own Process Group.
*
* @param {string} exe The executable to run
* @param {string[]} params The parameters to pass to the child
* @param {SpawnOptions & SpawnRxExtras} opts Options to pass to spawn.
*
* @return {Observable} Returns an Observable that when subscribed
* to, will create a detached process. The
* process output will be streamed to this
* Observable, and if unsubscribed from, the
* process will be terminated early. If the
* process terminates with a non-zero value,
* the Observable will terminate with onError.
*/
function spawnDetached(
exe: string,
params: string[],
opts: SpawnOptions & SpawnRxExtras & { split: true }
): Observable;

function spawnDetached(
exe: string,
params: string[],
opts?: SpawnOptions & SpawnRxExtras & { split: false | undefined }
): Observable;

/**
* Spawns a process as a child process.
*
* @param {string} exe The executable to run
* @param {string[]} params The parameters to pass to the child
* @param {SpawnOptions & SpawnRxExtras} opts Options to pass to spawn.
*
* @return {Promise<[string, string]>} Returns a Promise that represents a child
* process. The value returned is the process
* output. If the process terminates with a
* non-zero value, the Promise will resolve with
* an Error.
*/
function spawnPromise(
exe: string,
params: string[],
opts: SpawnOptions & SpawnRxExtras & { split: true }
): Promise<[string, string]>;

function spawnPromise(
exe: string,
params: string[],
opts?: SpawnOptions & SpawnRxExtras
): Promise;

/**
* Spawns a process but detached from the current process. The process is put
* into its own Process Group.
*
* @param {string} exe The executable to run
* @param {string[]} params The parameters to pass to the child
* @param {SpawnOptions & SpawnRxExtras} opts Options to pass to spawn.
*
* @return {Promise<[string, string]>} Returns a Promise that represents a detached
* process. The value returned is the process
* output. If the process terminates with a
* non-zero value, the Promise will resolve with
* an Error.
*/
function spawnDetachedPromise(
exe: string,
params: string[],
opts: SpawnOptions & SpawnRxExtras & { split: true }
): Promise<[string, string]>;

function spawnDetachedPromise(
exe: string,
params: string[],
opts?: SpawnOptions & SpawnRxExtras
): Promise;

/**
* Finds the actual executable and parameters to run on Windows. This method
* mimics the POSIX behavior of being able to run scripts as executables by
* replacing the passed-in executable with the script runner, for PowerShell,
* CMD, and node scripts.
*
* This method also does the work of running down PATH, which spawn on Windows
* also doesn't do, unlike on POSIX.
*
* @param {string} exe The executable to run
* @param {string[]} args The arguments to run
*
* @return {Object} The cmd and args to run
* @property {string} cmd The command to pass to spawn
* @property {string[]} args The arguments to pass to spawn
*/
function findActualExecutable(
exe: string,
args: string[]
): {
cmd: string;
args: string[];
};