This library is developed for use with Node 20+ (ES2022+ modules) and may not work properly with prior versions of Node.

A custom async-focused variant of Node's built-in child-process module, based exclusively around child_process.spawn()

All the spawning methods accept the same arguments as child_process.spawn(), but in any order.

If an array argument isn't provided, it will try options.args or options.argv; failing that, the string argument (or options.command or options.file) will be split (by default " " is used, but that can be changed using options.ws), and all but the first element will be used as the argv argument, setting the first element as the new command argument.

example

// import default (everything)
import cp from "@futagoza/child-process"
// import everything, same as classic require("@futagoza/child-process")
import * as cp from "@futagoza/child-process"
// named import
import { $, isSpawnError } from "@futagoza/child-process"

// Spawns a new process.
cp.spawn( command )
cp.spawn( command, options )
cp.spawn( command, argv )
cp.spawn( command, argv, options )
cp.spawn( options )

// Spawns a shell, executing the command inside the shell and buffering any generated output.
cp.exec( command )
cp.exec( command, options )
cp.exec( command, argv )
cp.exec( command, argv, options )
cp.exec( options )

// Same as `cp.exec`, but sends any output to the current process instead.
cp.run( command )
cp.run( command, options )
cp.run( command, argv )
cp.run( command, argv, options )
cp.run( options )

// Simple wrapper (`exec` with callback, otherwise `run`) if you don't need options
cp.x( command )
cp.x( command, cwd )
cp.x( command, buffer )
cp.x( command, buffer, cwd )
cp.x( command, callback )
cp.x( command, callback, cwd )

// Simple wrapper for `exec` (for a bash-like experience with template strings)
cp.$`command`

// Create a wrapper for `spawn` to use on template strings.
const $ = cp.create( options )
$`command`

// Confirm if the given error was thrown from a spawn'ed process.
cp.isSpawnError( object? )

// All arguments are optional, apart from the `command`, which can be passed as the
// first argument or as an option (either `command` or `file`)
cp.spawn( "npm", [ "publish", "--access", "public" ] )
cp.spawn( "npm", { args: [ "publish", "--access", "public" ] } )
cp.spawn( "npm publish --access public" )
cp.spawn( { command: "npm publish --access public" } )

options

In addition to the options used by child_process.spawn(), the following options are also supported:

| option | description | | ---------- | ----------- | | args | Alternative to passing an array as argv argument (using options.argv is preferred) | | argv | Alternative to passing an array as argv argument | | buffer1 | On options.pipe this will buffer the results from both stdout and stderr | | command | Alternative to passing the command as a string argument | | encoding1 | Used alongside options.buffer, this specifies the character encoding used to decode the results | | file | Alternative to passing the command as a string argument | | ignore2 | Will set options.stdio to ignore | | inherit2 | Will set options.stdio to inherit3 | | input | passed to the child process's stdin | | pipe2 | Will set options.stdio to pipe4 | | ready | A function that will be called with the child process as it's argument once the promise has started waiting | | silent2 | Will set options.stdio to pipe | | ws | If there were no args found, then this is used to split the command string and extract the args |

1. The buffer option is only used in cp.spawn (optional) and cp.exec (fixed)
2. Is ignored if the stdio option is already set
3. The fixed option for stdio with cp.run
4. The fixed option for stdio with cp.exec, and the default for it on cp.spawn

license

Copyright (c) 2018+ Futago-za Ryuu The MIT License, http://opensource.org/licenses/MIT