Node.Library.Execa
- Package
- purescript-node-execa
- Repository
- jordanmartinez/purescript-node-execa
Provides a higher-level replacement to Node.js child_process
module.
Uses sane defaults with clearer error messages.
spawn
/spawnSync
->execa
/execaSync
exec
/execSync
->execaCommand
/execaCommandSync
fork
- has no equivalent
#ExecaError Source
type ExecaError = { escapedCommand :: String, exitCode :: Maybe Int, failed :: Boolean, isCanceled :: Boolean, killed :: Boolean, message :: String, originalMessage :: Maybe String, shortMessage :: String, signal :: Maybe (Either Int String), signalDescription :: Maybe String, stderr :: String, stdout :: String, timedOut :: Boolean }
#ExecaOptions Source
type ExecaOptions = { argv0 :: Maybe String, cleanup :: Maybe Boolean, cwd :: Maybe String, detached :: Maybe Boolean, encoding :: Maybe Encoding, env :: Maybe (Object String), extendEnv :: Maybe Boolean, gid :: Maybe Int, maxBuffer :: Maybe Number, preferLocal :: Maybe { execPath :: Maybe String, localDir :: Maybe String }, shell :: Maybe String, stdioExtra :: Maybe (Array Foreign), stripFinalNewline :: Maybe Boolean, timeout :: Maybe { killSignal :: Either Int String, milliseconds :: Number }, uid :: Maybe Int, windowsEnableCmdEcho :: Maybe Boolean, windowsHide :: Maybe Boolean, windowsVerbatimArguments :: Maybe Boolean }
cleanup
(default:true
): Kill the spawned process when the parent process exits unless either:- the spawned process is
detached
- the parent process is terminated abruptly, for example, with SIGKILL as opposed to SIGTERM or a normal exit
- preferLocal
(default:Nothing
): WhenJust
, includes and prefers locally-installednode_modules/.bin
binaries when looking for a binary to execute. In short, if younpm install foo``, you can run
execa "foo".
localDir(if
Nothing,
Process.cwdis used) - Preferred path to find locally installed binaries in
execPath(if
Nothing,
Process.execPathis used) - Path to the Node.js executable to use in child processes. This can be either an absolute path or a path relative to the
localDir` option.
- the spawned process is
stripFinalNewline
- (default:true
). If enabled, trims the newline character ofstdout
/stderr
(e.g./(?:/r/n)|\r|\n$/
extendEnv
(default:true
) - Extends the child process'env
withProcess.env
argv0
- see Node docsstdioExtra
- Append any otherstdio
values to the array. Thestdio
array used is always["pipe", "pipe", "pipe", "ipc"] <> fromMaybe [] options.stdioExtra
detached
- see Node docsuid
- see Node docsgid
- see Node docsshell
- see Node docs. The Boolean variant is not supportedtimeout
- the amount of time to wait before killing the child process with the given kill signalmaxBuffer
- the amount of buffer space available tostdout
/stderr
. If more data is written to their buffers, child process will error with a max buffer size exceeded error.windowsVerbatimArguments
- see Node docswindowsHide
- see Node docswindowsEnableCmdEcho
(default:true
) - Enables the\q
flag when using thecmd
shell. See https://github.com/nodejs/node/issues/27120 This goes against the Windows' defaults but makes thestdout
/stderr
behavior more consistent across different operating systems.
#ExecaProcess Source
type ExecaProcess = { cancel :: Aff Unit, channel :: Aff (Maybe { ref :: Effect Unit, unref :: Effect Unit }), connected :: Aff Boolean, disconnect :: Aff Unit, exitCode :: Aff (Maybe Int), kill :: Aff Boolean, killForced :: Milliseconds -> Aff Boolean, killForcedWithSignal :: Either Int String -> Milliseconds -> Aff Boolean, killWithSignal :: Either Int String -> Aff Boolean, killed :: Aff Boolean, onClose :: (Maybe Int -> Maybe String -> Effect Unit) -> Aff Unit, onDisconnect :: Effect Unit -> Aff Unit, onError :: (ChildProcessError -> Effect Unit) -> Aff Unit, onMessage :: (Foreign -> Maybe Handle -> Effect Unit) -> Aff Unit, onSpawn :: Effect Unit -> Aff Unit, pid :: Aff (Maybe Pid), pidExists :: Aff Boolean, ref :: Aff Unit, result :: Aff (Either ExecaError ExecaSuccess), send :: Foreign -> Handle -> ({ keepOpen :: Maybe Boolean } -> { keepOpen :: Maybe Boolean }) -> Effect Unit -> Aff Boolean, signalCode :: Aff (Maybe String), spawnArgs :: Array String, spawnFile :: String, stderr :: { output :: Aff { error :: Maybe Error, text :: String }, pipeToParentStderr :: Aff Unit, stream :: Readable () }, stdin :: { end :: Aff Unit, shareParentProcessStdin :: Aff Unit, stream :: Writable (), writeUtf8 :: String -> Aff Unit, writeUtf8End :: String -> Aff Unit }, stdio :: Aff (Array Foreign), stdout :: { output :: Aff { error :: Maybe Error, text :: String }, pipeToParentStdout :: Aff Unit, stream :: Readable () }, unref :: Aff Unit }
Re-exposes all the bindings for ChildProcess
.
In addition exposes, the following:
result
- gets the result of the process
cancel
- kill the child process, but indicate it was cancelled rather than killed in the error message
stdin.stream
- access the child process' stdin
stdin.writeUt8
- Write a string to the child process' stdin
stdin.writeUt8End
- Write a string to the child process' stdin
and then end
the stream
stdin.end
- End the child process' stdin
#execa Source
execa :: String -> Array String -> (ExecaOptions -> ExecaOptions) -> Aff ExecaProcess
Replacement for childProcess.spawn
. Since this is asynchronous,
the returned value will not provide any results until one calls spawned.result
:
execa ... >>= \spawned -> spawned.result
.
Override the default options using record update syntax.
If defaults are good enough, just use identity
.
spawned <- execa "git checkout -b my-branch" (_
{ cwd = Just $ Path.concat [ "some", "other", "directory"]
})
spawned.result
spawned2 <- execa "git checkout -b my-branch" identity
spawned2.result
#ExecaSyncOptions Source
type ExecaSyncOptions = { argv0 :: Maybe String, cleanup :: Maybe Boolean, cwd :: Maybe String, detached :: Maybe Boolean, encoding :: Maybe Encoding, env :: Maybe (Object String), extendEnv :: Maybe Boolean, gid :: Maybe Int, input :: Maybe ImmutableBuffer, maxBuffer :: Maybe Number, preferLocal :: Maybe { execPath :: Maybe String, localDir :: Maybe String }, shell :: Maybe String, stdioExtra :: Maybe (Array Foreign), stripFinalNewline :: Maybe Boolean, timeout :: Maybe { killSignal :: Either Int String, milliseconds :: Number }, uid :: Maybe Int, windowsEnableCmdEcho :: Maybe Boolean, windowsHide :: Maybe Boolean, windowsVerbatimArguments :: Maybe Boolean }
cleanup
(default:true
): Kill the spawned process when the parent process exits unless either:- the spawned process is
detached
- the parent process is terminated abruptly, for example, with SIGKILL as opposed to SIGTERM or a normal exit
- preferLocal
(default:Nothing
): WhenJust
, includes and prefers locally-installednode_modules/.bin
binaries when looking for a binary to execute. In short, if younpm install foo``, you can run
execa "foo".
localDir(if
Nothing,
Process.cwdis used) - Preferred path to find locally installed binaries in
execPath(if
Nothing,
Process.execPathis used) - Path to the Node.js executable to use in child processes. This can be either an absolute path or a path relative to the
localDir` option.
- the spawned process is
stripFinalNewline
- (default:true
). If enabled, trims the newline character ofstdout
/stderr
(e.g./(?:/r/n)|\r|\n$/
extendEnv
(default:true
) - Extends the child process'env
withProcess.env
argv0
- see Node docsinput
- When defined, the input is piped into the child'sstdin
and thenstdin
isend
ed.stdioExtra
- Append any otherstdio
values to the array. Thestdio
array used is always["pipe", "pipe", "pipe", "ipc"] <> fromMaybe [] options.stdioExtra
detached
- see Node docsuid
- see Node docsgid
- see Node docsshell
- see Node docs. The Boolean variant is not supportedtimeout
- the amount of time to wait before killing the child process with the given kill signalmaxBuffer
- the amount of buffer space available tostdout
/stderr
. If more data is written to their buffers, child process will error with a max buffer size exceeded error.encoding
(default:Just UTF8
) - the encoding to use to decodestdout
/stderr
to a StringwindowsVerbatimArguments
- see Node docswindowsHide
- see Node docswindowsEnableCmdEcho
(default:true
) - Enables the\q
flag when using thecmd
shell. See https://github.com/nodejs/node/issues/27120 This goes against the Windows' defaults but makes thestdout
/stderr
behavior more consistent across different operating systems.
#execaSync Source
execaSync :: String -> Array String -> (ExecaSyncOptions -> ExecaSyncOptions) -> Effect (Either ExecaError ExecaSyncResult)
Replacement for childProcess.spawnSync
. Override the default options
using record update syntax. If defaults are good enough, just use identity
.
execaSync "jq" [ "-M", "--" ] (_
{ input = Just $ ImmutableBuffer.fromString UTF8 """{ "json": 0, "array": ["my json"] }"""
})
execaSync "jq" [ "-M", "path/to/some/file.json" ] identity
#execaCommand Source
execaCommand :: String -> (ExecaOptions -> ExecaOptions) -> Aff ExecaProcess
Replacement for childProcess.exec
. Override the default options
using record update syntax. If defaults are good enough, just use identity
.
execaCommand "git checkout -b my-branch"
{ cwd = Just $ Path.concat [ "some", "other", "directory"]
})
execaCommand "git checkout -b my-branch" identity
#execaCommandSync Source
execaCommandSync :: String -> (ExecaSyncOptions -> ExecaSyncOptions) -> Effect (Either ExecaError ExecaSyncResult)
Replacement for childProcess.execSync
. Override the default options
using record update syntax. If defaults are good enough, just use identity
.
Note: this will throw an error if the string does not contain
a valid command.
execaCommandSync "git checkout -b my-branch" (_
{ cwd = Just $ Path.concat [ "some", "other", "directory"]
})
execaCommandSync "git checkout -b my-branch" identity
- Modules
- Node.
Library. Execa - Node.
Library. Execa. CrossSpawn - Node.
Library. Execa. GetStream - Node.
Library. Execa. IsExe - Node.
Library. Execa. MergeStream - Node.
Library. Execa. NpmRunPath - Node.
Library. Execa. ParseCommand - Node.
Library. Execa. ShebangCommand - Node.
Library. Execa. SignalExit - Node.
Library. Execa. StripFinalNewline - Node.
Library. Execa. Utils - Node.
Library. Execa. Which