Node.Library.Execa

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 Gid, ipc :: Maybe Boolean, maxBuffer :: Maybe Number, preferLocal :: Maybe { execPath :: Maybe String, localDir :: Maybe String }, shell :: Maybe String, stderr :: Maybe StdIO, stdin :: Maybe StdIO, stdioExtra :: Maybe (Array StdIO), stdout :: Maybe StdIO, stripFinalNewline :: Maybe Boolean, timeout :: Maybe { killSignal :: KillSignal, milliseconds :: Milliseconds }, uid :: Maybe Uid, 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): When Just, includes and prefers locally-installed node_modules/.bin binaries when looking for a binary to execute. In short, if you npm install foo``, you can runexeca "foo"`.
  • localDir (if Nothing, Process.cwd is used) - Preferred path to find locally installed binaries in
  • execPath (if Nothing, Process.execPath is 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.
• stripFinalNewline - (default: true). If enabled, trims the newline character of stdout/stderr (e.g. /(?:/r/n)|\r|\n$/
• extendEnv (default: true) - Extends the child process' env with Process.env
• argv0 - see Node docs
• stdin - stdio[0]. Defaults to null.
• stdout - stdio[1]. Defaults to null.
• stderr - stdio[2]. Defaults to null.
• ipc - stdio[3]. When true, uses ipc. Otherwise, uses null.
• stdioExtra - Append any other stdio values to the array. The stdio array used is always [stdin, stdout, stderr, ipc] <> fromMaybe [] options.stdioExtra
• detached - see Node docs
• uid - see Node docs
• gid - see Node docs
• shell - see Node docs. The Boolean variant is not supported
• timeout - the amount of time to wait before killing the child process with the given kill signal
• maxBuffer - the amount of buffer space available to stdout/stderr. If more data is written to their buffers, child process will error with a max buffer size exceeded error.
• windowsVerbatimArguments - see Node docs
• windowsHide - see Node docs
• windowsEnableCmdEcho (default: true) - Enables the \q flag when using the cmd shell. See https://github.com/nodejs/node/issues/27120 This goes against the Windows' defaults but makes the stdout/stderr behavior more consistent across different operating systems.

type ExecaProcess = { cancel :: Aff Unit, childProcess :: UnsafeChildProcess, connected :: Aff Boolean, disconnect :: Aff Unit, getResult :: Aff ExecaResult, getResult' :: (Pid -> Aff Unit) -> Aff ExecaResult, kill :: Aff Boolean, killForced :: Milliseconds -> Aff Boolean, killForcedWithSignal :: KillSignal -> Milliseconds -> Aff Boolean, killWithSignal :: KillSignal -> Aff Boolean, killed :: Aff Boolean, ref :: Aff Unit, spawnArgs :: Array String, spawnFile :: String, stderr :: Maybe { pipeToParentStderr :: Aff Unit, stream :: Readable () }, stdin :: Maybe { end :: Aff Unit, stream :: Writable (), writeUtf8 :: String -> Aff Unit, writeUtf8End :: String -> Aff Unit }, stdout :: Maybe { pipeToParentStdout :: Aff Unit, stream :: Readable () }, unref :: Aff Unit, unsafeChannelRef :: Aff Unit, unsafeChannelUnref :: Aff Unit, waitSpawned :: Aff (Either SystemError Pid) }

Re-exposes most of the bindings for ChildProcess. In addition exposes, the following:

• getResult - gets the result of the process
• getResult' \pid -> ... - Runs the hook after process spawns but before it ends and gets the result of the process.
• cancel - kill the child process, but indicate it was cancelled rather than killed in the error message
• killForced* - kills the child process with the given signal or SIGTERM if not defined. If child is still alive after timeout, sends SIGKILL to child.
• Convenience functions for stdin/stdout/stderr

for_ spawned.stdin \{ stream, writeUtf8, writeUtf8End, end } -> do
  stream -- access the child process' `stdin`
  writeUt8 -- Write a string to the child process' `stdin`
  writeUt8End -- Write a string to the child process' `stdin` and then `end` the stream
  end -- End the child process' `stdin`

type ExecaResult = { canceled :: Boolean, escapedCommand :: String, exit :: Exit, exitCode :: Maybe Int, killed :: Boolean, message :: String, originalMessage :: Maybe String, pid :: Maybe Pid, shortMessage :: String, signal :: Maybe KillSignal, signalDescription :: Maybe String, stderr :: String, stderrError :: Maybe Error, stdinError :: Maybe Error, stdout :: String, stdoutError :: Maybe Error, timedOut :: Boolean }

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.getResult: execa ... >>= \spawned -> spawned.getResult.

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"]
   })
result <- spawned2.getResult
case result.exit of
  Normally 0 -> ...
  _ -> ...

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 Gid, input :: Maybe Buffer, maxBuffer :: Maybe Number, preferLocal :: Maybe { execPath :: Maybe String, localDir :: Maybe String }, shell :: Maybe String, stderr :: Maybe StdIO, stdin :: Maybe StdIO, stdioExtra :: Maybe (Array StdIO), stdout :: Maybe StdIO, stripFinalNewline :: Maybe Boolean, timeout :: Maybe { killSignal :: KillSignal, milliseconds :: Milliseconds }, uid :: Maybe Uid, 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): When Just, includes and prefers locally-installed node_modules/.bin binaries when looking for a binary to execute. In short, if you npm install foo``, you can runexeca "foo".localDir(ifNothing,Process.cwdis used) - Preferred path to find locally installed binaries inexecPath(ifNothing,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 thelocalDir` option.
• stripFinalNewline - (default: true). If enabled, trims the newline character of stdout/stderr (e.g. /(?:/r/n)|\r|\n$/
• extendEnv (default: true) - Extends the child process' env with Process.env
• argv0 - see Node docs
• input - When defined, the input is piped into the child's stdin and then stdin is ended.
• stdin - stdio[0]. Defaults to null. Note: this value has no effect if input is defined.
• stdout - stdio[1]. Defaults to null.
• stderr - stdio[2]. Defaults to null.
• stdioExtra - Append any other stdio values to the array. The stdio array used is always [stdin, stdout, stderr] <> fromMaybe [] options.stdioExtra
• detached - see Node docs
• uid - see Node docs
• gid - see Node docs
• shell - see Node docs. The Boolean variant is not supported
• timeout - the amount of time to wait before killing the child process with the given kill signal
• maxBuffer - the amount of buffer space available to stdout/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 decode stdout/stderr to a String
• windowsVerbatimArguments - see Node docs
• windowsHide - see Node docs
• windowsEnableCmdEcho (default: true) - Enables the \q flag when using the cmd shell. See https://github.com/nodejs/node/issues/27120 This goes against the Windows' defaults but makes the stdout/stderr behavior more consistent across different operating systems.

execaSync :: String -> Array String -> (ExecaSyncOptions -> ExecaSyncOptions) -> Effect ExecaResult

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

To get the result, use _.getResult

git <- execaSync "git checkout -b my-branch" identity
result <- git.getResult
case result.exit of
  Normally 0 -> ...
  _ -> ...

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

To get the result, use _.getResult

git <- execaCommand "git checkout -b my-branch" identity
result <- git.getResult
case result.exit of
  Normally 0 -> ...
  _ -> ...

execaCommandSync :: String -> (ExecaSyncOptions -> ExecaSyncOptions) -> Effect ExecaResult

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

To get the result, use _.getResult

git <- execaCommandSync "git checkout -b my-branch" identity
result <- git.getResult
case result.exit of
  Normally 0 -> ...
  _ -> ...