Node.Process

data Process

process :: Process

beforeExitH :: EventHandle1 Process Int

The 'beforeExit' event is emitted when Node.js empties its event loop and has no additional work to schedule. Normally, the Node.js process will exit when there is no work scheduled, but a listener registered on the 'beforeExit' event can make asynchronous calls, and thereby cause the Node.js process to continue.

The listener callback function is invoked with the value of process.exitCode passed as the only argument. The 'beforeExit' event is not emitted for conditions causing explicit termination, such as calling process.exit() or uncaught exceptions. The 'beforeExit' should not be used as an alternative to the 'exit' event unless the intention is to schedule additional work.

disconnectH :: EventHandle0 Process

exitH :: EventHandle1 Process Int

The 'exit' event is emitted when the Node.js process is about to exit as a result of either:

• The process.exit() method being called explicitly;
• The Node.js event loop no longer having any additional work to perform.

Listener functions must only perform synchronous operations. The Node.js process will exit immediately after calling the 'exit' event listeners causing any additional work still queued in the event loop to be abandoned. (Maintainer note: I believe the above translates to "Only synchronous (i.e. Effect) code can be run in the resulting handler. If you need asynchronous (i.e. Aff) code, use beforeExitH.")

There is no way to prevent the exiting of the event loop at this point, and once all 'exit' listeners have finished running the Node.js process will terminate. The listener callback function is invoked with the exit code specified either by the process.exitCode property, or the exitCode argument passed to the process.exit() method.

messageH :: EventHandle Process (Foreign -> Maybe Foreign -> Effect Unit) (EffectFn2 Foreign (Nullable Foreign) Unit)

rejectionHandledH :: EventHandle1 Process Foreign

The 'rejectionHandled' event is emitted whenever a Promise has been rejected and an error handler was attached to it (using promise.catch(), for example) later than one turn of the Node.js event loop.

The Promise object would have previously been emitted in an 'unhandledRejection' event, but during the course of processing gained a rejection handler.

There is no notion of a top level for a Promise chain at which rejections can always be handled. Being inherently asynchronous in nature, a Promise rejection can be handled at a future point in time, possibly much later than the event loop turn it takes for the 'unhandledRejection' event to be emitted.

Another way of stating this is that, unlike in synchronous code where there is an ever-growing list of unhandled exceptions, with Promises there can be a growing-and-shrinking list of unhandled rejections.

In synchronous code, the 'uncaughtException' event is emitted when the list of unhandled exceptions grows.

In asynchronous code, the 'unhandledRejection' event is emitted when the list of unhandled rejections grows, and the 'rejectionHandled' event is emitted when the list of unhandled rejections shrinks.

uncaughtExceptionH :: EventHandle2 Process Error String

Args:

• err <Error> The uncaught exception.
• origin <string> Indicates if the exception originates from an unhandled rejection or from a synchronous error. Can either be 'uncaughtException' or 'unhandledRejection'. The latter is used when an exception happens in a Promise based async context (or if a Promise is rejected) and --unhandled-rejections flag set to strict or throw (which is the default) and the rejection is not handled, or when a rejection happens during the command line entry point's ES module static loading phase.

The 'uncaughtException' event is emitted when an uncaught JavaScript exception bubbles all the way back to the event loop. By default, Node.js handles such exceptions by printing the stack trace to stderr and exiting with code 1, overriding any previously set process.exitCode. Adding a handler for the 'uncaughtException' event overrides this default behavior. Alternatively, change the process.exitCode in the 'uncaughtException' handler which will result in the process exiting with the provided exit code. Otherwise, in the presence of such handler the process will exit with 0.

'uncaughtException' is a crude mechanism for exception handling intended to be used only as a last resort. The event should not be used as an equivalent to On Error Resume Next. Unhandled exceptions inherently mean that an application is in an undefined state. Attempting to resume application code without properly recovering from the exception can cause additional unforeseen and unpredictable issues.

Exceptions thrown from within the event handler will not be caught. Instead the process will exit with a non-zero exit code and the stack trace will be printed. This is to avoid infinite recursion.

Attempting to resume normally after an uncaught exception can be similar to pulling out the power cord when upgrading a computer. Nine out of ten times, nothing happens. But the tenth time, the system becomes corrupted.

The correct use of 'uncaughtException' is to perform synchronous cleanup of allocated resources (e.g. file descriptors, handles, etc) before shutting down the process. It is not safe to resume normal operation after 'uncaughtException'.

To restart a crashed application in a more reliable way, whether 'uncaughtException' is emitted or not, an external monitor should be employed in a separate process to detect application failures and recover or restart as needed.

unhandledRejectionH :: EventHandle2 Process Foreign Foreign

Args:

• reason <Error> | <any> The object with which the promise was rejected (typically an Error object).
• promise <Promise> The rejected promise.

The 'unhandledRejection' event is emitted whenever a Promise is rejected and no error handler is attached to the promise within a turn of the event loop. When programming with Promises, exceptions are encapsulated as "rejected promises". Rejections can be caught and handled using promise.catch() and are propagated through a Promise chain. The 'unhandledRejection' event is useful for detecting and keeping track of promises that were rejected whose rejections have not yet been handled.

mkSignalH :: Signal -> EventHandle Process (Effect Unit) (Effect Unit)

Rather than support an EventHandle for every possible Signal, this function provides one a convenient way for constructing one for any given signal.

See Node docs: https://nodejs.org/dist/latest-v18.x/docs/api/process.html#signal-events

mkSignalH' :: String -> EventHandle Process (Effect Unit) (Effect Unit)

Same as mkSignalH but allows for more options in case the Signal ADT is missing any.

See Node docs: https://nodejs.org/dist/latest-v18.x/docs/api/process.html#signal-events

warningH :: EventHandle1 Process Error

Args:

• warning <Error> Key properties of the warning are:
  • name <string> The name of the warning. Default: 'Warning'.
  • message <string> A system-provided description of the warning.
  • stack <string> A stack trace to the location in the code where the warning was issued.

The 'warning' event is emitted whenever Node.js emits a process warning.

A process warning is similar to an error in that it describes exceptional conditions that are being brought to the user's attention. However, warnings are not part of the normal Node.js and JavaScript error handling flow. Node.js can emit warnings whenever it detects bad coding practices that could lead to sub-optimal application performance, bugs, or security vulnerabilities. By default, Node.js will print process warnings to stderr. The --no-warnings command-line option can be used to suppress the default console output but the 'warning' event will still be emitted by the process object.

workerH :: EventHandle1 Process Foreign

Args:

• worker <Worker> The <Worker> that was created.

The 'worker' event is emitted after a new <Worker> thread has been created.

abort :: Maybe (Effect Unit)

The process.abort() method causes the Node.js process to exit immediately and generate a core file. This feature is not available in Worker threads.

argv :: Effect (Array String)

Get a copy of the array containing the command line arguments.

argv0 :: Effect String

The process.argv0 property stores a read-only copy of the original value of argv[0] passed when Node.js starts.

channelRef :: Maybe (Effect Unit)

This method makes the IPC channel keep the event loop of the process running if .unref() has been called before. Typically, this is managed through the number of 'disconnect' and 'message' listeners on the process object. However, this method can be used to explicitly request a specific behavior.

Context: if the Node.js process was spawned with an IPC channel (see the Child Process documentation), the process.channel property is a reference to the IPC channel. If no IPC channel exists, this property is undefined.

channelUnref :: Maybe (Effect Unit)

This method makes the IPC channel not keep the event loop of the process running, and lets it finish even while the channel is open. Typically, this is managed through the number of 'disconnect' and 'message' listeners on the process object. However, this method can be used to explicitly request a specific behavior.

Context: if the Node.js process was spawned with an IPC channel (see the Child Process documentation), the process.channel property is a reference to the IPC channel. If no IPC channel exists, this property is undefined.

chdir :: String -> Effect Unit

Change the current working directory of the process. If the current directory could not be changed, an exception will be thrown.

config :: Effect (Foreign)

Returns a copy of the Config value. The process.config property returns an Object containing the JavaScript representation of the configure options used to compile the current Node.js executable. This is the same as the config.gypi file that was produced when running the ./configure script.

connected :: Effect (Boolean)

If the Node.js process is spawned with an IPC channel (see the Child Process and Cluster documentation), the process.connected property will return true so long as the IPC channel is connected and will return false after process.disconnect() is called. Once process.connected is false, it is no longer possible to send messages over the IPC channel using process.send().

newtype CpuUsage

Instances

• Eq CpuUsage
• Show CpuUsage

cpuUsageToRecord :: CpuUsage -> { system :: Int, user :: Int }

cpuUsage :: Effect (CpuUsage)

cpuUsageDiff :: CpuUsage -> Effect CpuUsage

cwd :: Effect (String)

Get the current working directory of the process.

debugPort :: Int

disconnect :: Maybe (Effect Unit)

If the Node.js process is spawned with an IPC channel (see the Child Process and Cluster documentation), the process.disconnect() method will close the IPC channel to the parent process, allowing the child process to exit gracefully once there are no other connections keeping it alive. The effect of calling process.disconnect() is the same as calling ChildProcess.disconnect() from the parent process.

If the Node.js process was not spawned with an IPC channel, process.disconnect() will be undefined.

getEnv :: Effect (Object String)

Get a copy of the current environment. If you only want to look up a value without paying for the overhead of the copy, use lookupEnv.

lookupEnv :: String -> Effect (Maybe String)

Lookup a particular environment variable.

setEnv :: String -> String -> Effect Unit

Set an environment variable.

unsetEnv :: String -> Effect Unit

Delete an environment variable. Use case: to hide secret environment variable from child processes.

execArgv :: Effect (Array String)

Get a copy of the Node-specific options passed to the node executable.

execPath :: Effect (String)

The absolute pathname of the node executable that started the process.

exit :: forall a. Effect a

Cause the process to exit immediately without completing any pending asynchronous operations including I/O operations to process.stdout and process.stderr. Process will exit with the process.exitCode value if it has been set or 0 (i.e. exit successfully) otherwise.

Rather than using this function to exit, one should set process.exitCode and let Node gracefully exit once all pending asynchronous operations have completed. If it is necessary to terminate the Node.js process due to an error condition, throwing an uncaught error and allowing the process to terminate accordingly is safer than calling process.exit().

exit' :: forall a. Int -> Effect a

Cause the process to exit immediately without completing any pending asynchronous operations including I/O operations to process.stdout and process.stderr. An exit code of 0 is normally considered successful, and anything else is considered a failure.

Rather than using this function to exit, one should set process.exitCode and let Node gracefully exit once all pending asynchronous operations have completed. If it is necessary to terminate the Node.js process due to an error condition, throwing an uncaught error and allowing the process to terminate accordingly is safer than calling process.exit().

setExitCode :: Int -> Effect Unit

Sets the exit code to use when the process exits. An exit code of 0 is normally considered successful, and anything else is considered a failure.

In comparison to exit/exit', this is the safer way to exit a Node.js process because any pending asynchronous operations including I/O operations to process.stdout and process.stderr will complete before the Node.js process exits.

getExitCode :: Effect (Maybe Int)

Gets the currently set exit code. This will be Nothing if the exit code has not been previously set.

getGid :: Effect (Maybe Gid)

getUid :: Effect (Maybe Uid)

hasUncaughtExceptionCaptureCallback :: Effect (Boolean)

kill :: Pid -> Effect Unit

killStr :: Pid -> String -> Effect Unit

killInt :: Pid -> Int -> Effect Unit

type MemoryUsage = { arrayBuffers :: Int, external :: Int, heapTotal :: Int, heapUsed :: Int, rss :: Int }

• heapTotal and heapUsed refer to V8's memory usage.
• external refers to the memory usage of C++ objects bound to JavaScript objects managed by V8.
• rss, Resident Set Size, is the amount of space occupied in the main memory device (that is a subset of the total allocated memory) for the process, including all C++ and JavaScript objects and code.
• arrayBuffers refers to memory allocated for ArrayBuffers and SharedArrayBuffers, including all Node.js Buffers. This is also included in the external value. When Node.js is used as an embedded library, this value may be 0 because allocations for ArrayBuffers may not be tracked in that case.

memoryUsage :: Effect (MemoryUsage)

Returns an object describing the memory usage of the Node.js process measured in bytes. When using Worker threads, rss will be a value that is valid for the entire process, while the other fields will only refer to the current thread. The process.memoryUsage() method iterates over each page to gather information about memory usage which might be slow depending on the program memory allocations.

Note: if one just wants the rss value, use memoryUsageRss, which is faster to compute.

memoryUsageRss :: Effect Int

The process.memoryUsage.rss() method returns an integer representing the Resident Set Size (RSS) in bytes. The Resident Set Size, is the amount of space occupied in the main memory device (that is a subset of the total allocated memory) for the process, including all C++ and JavaScript objects and code. This is the same value as the rss property provided by process.memoryUsage() but process.memoryUsage.rss() is faster.

nextTick :: Effect Unit -> Effect Unit

Register a callback to run as soon as the current event loop runs to completion. One should use queueMicroTask instead for most situations instead of nextTick. See Node docs for more info.

nextTick' :: forall r. (Record r -> Effect Unit) -> Record r -> Effect Unit

Register a callback that will receive the record arg as an argument to run as soon as the current event loop runs to completion. One should use queueMicroTask instead for most situations instead of nextTick. See Node docs for more info.

pid :: Pid

Returns the PID of the current process.

platform :: Maybe Platform

platformStr :: String

ppid :: Pid

Returns the PID of the parent of the current process.

type ResourceUsage = { fsRead :: Int, fsWrite :: Int, involuntaryContextSwitches :: Int, ipcReceived :: Int, ipcSent :: Int, majorPageFault :: Int, maxRSS :: Int, minorPageFault :: Int, sharedMemorySize :: Int, signalsCount :: Int, swappedOut :: Int, systemCPUTime :: Int, unsharedDataSize :: Int, unsharedStackSize :: Int, userCPUTime :: Int, voluntaryContextSwitches :: Int }

• userCPUTime <integer> maps to ru_utime computed in microseconds. It is the same value as process.cpuUsage().user.
• systemCPUTime <integer> maps to ru_stime computed in microseconds. It is the same value as process.cpuUsage().system.
• maxRSS <integer> maps to ru_maxrss which is the maximum resident set size used in kilobytes.
• sharedMemorySize <integer> maps to ru_ixrss but is not supported by any platform.
• unsharedDataSize <integer> maps to ru_idrss but is not supported by any platform.
• unsharedStackSize <integer> maps to ru_isrss but is not supported by any platform.
• minorPageFault <integer> maps to ru_minflt which is the number of minor page faults for the process, see this article for more details.
• majorPageFault <integer> maps to ru_majflt which is the number of major page faults for the process, see this article for more details. This field is not supported on Windows.
• swappedOut <integer> maps to ru_nswap but is not supported by any platform.
• fsRead <integer> maps to ru_inblock which is the number of times the file system had to perform input.
• fsWrite <integer> maps to ru_oublock which is the number of times the file system had to perform output.
• ipcSent <integer> maps to ru_msgsnd but is not supported by any platform.
• ipcReceived <integer> maps to ru_msgrcv but is not supported by any platform.
• signalsCount <integer> maps to ru_nsignals but is not supported by any platform.
• voluntaryContextSwitches <integer> maps to ru_nvcsw which is the number of times a CPU context switch resulted due to a process voluntarily giving up the processor before its time slice was completed (usually to await availability of a resource). This field is not supported on Windows.
• involuntaryContextSwitches <integer> maps to ru_nivcsw which is the number of times a CPU context switch resulted due to a higher priority process becoming runnable or because the current process exceeded its time slice. This field is not supported on Windows.

resourceUsage :: Effect (ResourceUsage)

unsafeSend :: forall messageRows. Record messageRows -> Nullable Foreign -> Effect Boolean

Unsafe because child process must be a Node child process and an IPC channel must exist.

type JsSendOptions :: Row Typetype JsSendOptions = (keepAlive :: Boolean)

• keepAlive <boolean> A value that can be used when passing instances of net.Socket as the Handle. When true, the socket is kept open in the sending process. Default: false.

unsafeSendOpts :: forall r trash messageRows. Union r trash JsSendOptions => Record messageRows -> Nullable Foreign -> Record r -> Effect Boolean

Unsafe because process must be a Node child process and an IPC channel must exist.

unsafeSendCb :: forall messageRows. Record messageRows -> Nullable Foreign -> (Maybe Error -> Effect Unit) -> Effect Boolean

Unsafe because process must be a Node child process and an IPC channel must exist.

unsafeSendOptsCb :: forall r trash messageRows. Union r trash JsSendOptions => Record messageRows -> Nullable Foreign -> Record r -> (Maybe Error -> Effect Unit) -> Effect Boolean

Unsafe because process must be a Node child process and an IPC channel must exist.

setUncaughtExceptionCaptureCallback :: Effect Unit -> Effect Unit

clearUncaughtExceptionCaptureCallback :: Effect Unit

stdin :: Readable ()

The standard input stream. Note that this stream will never emit an end event, so any handlers attached via onEnd will never be called.

stdout :: Writable ()

The standard output stream. Note that this stream cannot be closed; calling end will result in an exception being thrown.

stderr :: Writable ()

The standard error stream. Note that this stream cannot be closed; calling end will result in an exception being thrown.

stdinIsTTY :: Boolean

Check whether the standard input stream appears to be attached to a TTY. It is a good idea to check this before processing the input data from stdin.

stdoutIsTTY :: Boolean

Check whether the standard output stream appears to be attached to a TTY. It is a good idea to check this before printing ANSI codes to stdout (e.g. for coloured text in the terminal).

stderrIsTTY :: Boolean

Check whether the standard error stream appears to be attached to a TTY. It is a good idea to check this before printing ANSI codes to stderr (e.g. for coloured text in the terminal).

getTitle :: Effect (String)

The process.title property returns the current process title (i.e. returns the current value of ps).

setTitle :: String -> Effect Unit

The process.title property returns the current process title (i.e. returns the current value of ps). Assigning a new value to process.title modifies the current value of ps.

When a new value is assigned, different platforms will impose different maximum length restrictions on the title. Usually such restrictions are quite limited. For instance, on Linux and macOS, process.title is limited to the size of the binary name plus the length of the command-line arguments because setting the process.title overwrites the argv memory of the process. Node.js v0.8 allowed for longer process title strings by also overwriting the environ memory but that was potentially insecure and confusing in some (rather obscure) cases.

Assigning a value to process.title might not result in an accurate label within process manager applications such as macOS Activity Monitor or Windows Services Manager.

uptime :: Effect (Number)

The process.uptime() method returns the number of seconds the current Node.js process has been running. The return value includes fractions of a second. Use Data.Int.floor to get whole seconds.

version :: String

Get the Node.js version.