Node.Library.Execa

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 }

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): 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
• stdioExtra - Append any other stdio values to the array. The stdio array used is always ["pipe", "pipe", "pipe", "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, 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

type ExecaSuccess = { command :: String, escapedCommand :: String, exitCode :: Int, stderr :: String, stdout :: String }

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

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): 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.
• stdioExtra - Append any other stdio values to the array. The stdio array used is always ["pipe", "pipe", "pipe", "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.
• 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.

type ExecaSyncResult = { command :: String, escapedCommand :: String, exitCode :: Int, stderr :: String, stdout :: String }

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 :: 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 :: 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

data Handle

A handle for inter-process communication (IPC).

type ChildProcessError = { code :: String, errno :: String, message :: Nullable String, syscall :: String }

An error which occurred inside a child process.