Home > @rushstack/terminal > TerminalWritable

TerminalWritable class

The abstract base class for objects that can present, route, or process text output for a console application. This output is typically prepared using the Terminal API.

Signature:

export declare abstract class TerminalWritable 

Remarks

The design is based loosely on the WritableStream and TransformStream classes from the system Streams API, except that instead of asynchronous byte streams, the TerminalWritable system synchronously transmits human readable messages intended to be rendered on a text console or log file.

Consider a console application whose output may need to be processed in different ways before finally being output. The conceptual block diagram might look like this:

         [Terminal API]
                |
                V
       [normalize newlines]
                |
                V
      +----[splitter]-------+
      |                     |
      V                     V
  [shell console]     [remove ANSI colors]
                            |
                            V
                      [write to build.log]

The application uses the Terminal API to print stdout and stderr messages, for example with standardized formatting for errors and warnings, and ANSI escapes to make nice colors. Maybe it also includes text received from external processes, whose newlines may be inconsistent. Ultimately we want to write the output to the shell console and a build.log file, but we don't want to put ANSI colors in the build log.

For the above example, [shell console] and [write to build.log] would be modeled as subclasses of TerminalWritable. The [normalize newlines] and [remove ANSI colors] steps are modeled as subclasses of TerminalTransform, because they output to a "destination" object. The [splitter] would be implemented using SplitterTransform.

The stream of messages are ITerminalChunk objects, which can represent both stdout and stderr channels. The pipeline operates synchronously on each chunk, but by processing one chunk at a time, it avoids storing the entire output in memory. This means that operations like [remove ANSI colors] cannot be simple regular expressions -- they must be implemented as state machines (TextRewriter subclasses) capable of matching substrings that span multiple chunks.

Constructors

Constructor	Modifiers	Description
(constructor)(options)		Constructs a new instance of the TerminalWritable class

Properties

Property	Modifiers	Type	Description
isOpen	readonly	boolean	This property is initially true when the object is constructed, and becomes false when close() is called.
preventAutoclose	readonly	boolean

Methods

Method	Modifiers	Description
close()		Calling this method flushes any remaining outputs and permanently transitions the TerminalWritable to a "closed" state, where no further chunks can be written.
onClose()	protected	Subclasses can override this empty method to perform additional operations such as closing a file handle.
onWriteChunk(chunk)	protected abstract	Subclasses should implement this abstract method to process the chunk.
writeChunk(chunk)		Upstream objects call this method to provide inputs to this object.