Settings

The settings module provides composable terminal mode changes. Each setting produces apply and revert byte sequences you write to stdout.

`Setting`

Every setting helper returns:

interface Setting {
  apply: Uint8Array;
  revert: Uint8Array;
}

Write apply on startup and revert on exit to restore the terminal.

`settings(...sequence)`

Compose multiple settings into one. Revert runs in reverse order.

import {
  
function alternateBuffer(options?: {
    clear?: boolean;
}): Setting
alternateBuffer,
  
function cursor(visible: boolean): Setting
cursor,
  
function mouseTracking(): Setting
mouseTracking,
  
function settings(...sequence: Setting[]): Setting
settings,
} from "@bomb.sh/tty";

let 
let tty: Setting
tty = 
function settings(...sequence: Setting[]): Setting
settings(
  
function alternateBuffer(options?: {
    clear?: boolean;
}): Setting
alternateBuffer(),
  
function cursor(visible: boolean): Setting
cursor(false),
  
function mouseTracking(): Setting
mouseTracking(),
);

var process: NodeJS.Process
process.
NodeJS.Process.stdout: NodeJS.WriteStream & {
    fd: 1;
}
The process.stdout property returns a stream connected tostdout (fd 1). It is a net.Socket (which is a Duplex stream) unless fd 1 refers to a file, in which case it is
a Writable stream.
For example, to copy process.stdin to process.stdout:
import { stdin, stdout } from 'node:process';

stdin.pipe(stdout);
process.stdout differs from other Node.js streams in important ways. See note on process I/O for more information.
stdout.
Socket.write(buffer: Uint8Array | string, cb?: (err?: Error | null) => void): boolean (+1 overload)
Sends data on the socket. The second parameter specifies the encoding in the
case of a string. It defaults to UTF8 encoding.
Returns true if the entire data was flushed successfully to the kernel
buffer. Returns false if all or part of the data was queued in user memory.'drain' will be emitted when the buffer is again free.
The optional callback parameter will be executed when the data is finally
written out, which may not be immediately.
See Writable stream write() method for more
information.
@since ― v0.1.90
@param ― encoding Only used when data is string.
write(
let tty: Setting
tty.
Setting.apply: Uint8Array<ArrayBufferLike>
apply);

// on exit:
var process: NodeJS.Process
process.
NodeJS.Process.stdout: NodeJS.WriteStream & {
    fd: 1;
}
The process.stdout property returns a stream connected tostdout (fd 1). It is a net.Socket (which is a Duplex stream) unless fd 1 refers to a file, in which case it is
a Writable stream.
For example, to copy process.stdin to process.stdout:
import { stdin, stdout } from 'node:process';

stdin.pipe(stdout);
process.stdout differs from other Node.js streams in important ways. See note on process I/O for more information.
stdout.
Socket.write(buffer: Uint8Array | string, cb?: (err?: Error | null) => void): boolean (+1 overload)
Sends data on the socket. The second parameter specifies the encoding in the
case of a string. It defaults to UTF8 encoding.
Returns true if the entire data was flushed successfully to the kernel
buffer. Returns false if all or part of the data was queued in user memory.'drain' will be emitted when the buffer is again free.
The optional callback parameter will be executed when the data is finally
written out, which may not be immediately.
See Writable stream write() method for more
information.
@since ― v0.1.90
@param ― encoding Only used when data is string.
write(
let tty: Setting
tty.
Setting.revert: Uint8Array<ArrayBufferLike>
revert);

`alternateBuffer(options?)`

Switch to the alternate screen buffer.

Option	Type	Default	Description
`clear`	`boolean`	`true`	Clear the alternate buffer on entry

import { 
function alternateBuffer(options?: {
    clear?: boolean;
}): Setting
alternateBuffer } from "@bomb.sh/tty";

function alternateBuffer(options?: {
    clear?: boolean;
}): Setting
alternateBuffer();              // enter, clear
function alternateBuffer(options?: {
    clear?: boolean;
}): Setting
alternateBuffer({ 
clear?: boolean
clear: false }); // enter, preserve contents

Revert switches back to the main screen with scrollback intact.

`cursor(visible)`

Show or hide the terminal cursor (DEC private mode 25).

import { 
function cursor(visible: boolean): Setting
cursor } from "@bomb.sh/tty";

function cursor(visible: boolean): Setting
cursor(false); // hide
function cursor(visible: boolean): Setting
cursor(true);  // show

`saveCursorPosition()`

Save and restore cursor position using DECSC (ESC 7) / DECRC (ESC 8).

import { 
function saveCursorPosition(): Setting
Save and restore cursor position using DECSC (ESC 7) / DECRC (ESC 8).
@see ― https://vt100.net/docs/vt510-rm/DECSC.html VT510 DECSC
@see ― https://vt100.net/docs/vt510-rm/DECRC.html VT510 DECRC
saveCursorPosition } from "@bomb.sh/tty";

let 
let pos: Setting
pos = 
function saveCursorPosition(): Setting
Save and restore cursor position using DECSC (ESC 7) / DECRC (ESC 8).
@see ― https://vt100.net/docs/vt510-rm/DECSC.html VT510 DECSC
@see ― https://vt100.net/docs/vt510-rm/DECRC.html VT510 DECRC
saveCursorPosition();
var process: NodeJS.Process
process.
NodeJS.Process.stdout: NodeJS.WriteStream & {
    fd: 1;
}
The process.stdout property returns a stream connected tostdout (fd 1). It is a net.Socket (which is a Duplex stream) unless fd 1 refers to a file, in which case it is
a Writable stream.
For example, to copy process.stdin to process.stdout:
import { stdin, stdout } from 'node:process';

stdin.pipe(stdout);
process.stdout differs from other Node.js streams in important ways. See note on process I/O for more information.
stdout.
Socket.write(buffer: Uint8Array | string, cb?: (err?: Error | null) => void): boolean (+1 overload)
Sends data on the socket. The second parameter specifies the encoding in the
case of a string. It defaults to UTF8 encoding.
Returns true if the entire data was flushed successfully to the kernel
buffer. Returns false if all or part of the data was queued in user memory.'drain' will be emitted when the buffer is again free.
The optional callback parameter will be executed when the data is finally
written out, which may not be immediately.
See Writable stream write() method for more
information.
@since ― v0.1.90
@param ― encoding Only used when data is string.
write(
let pos: Setting
pos.
Setting.apply: Uint8Array<ArrayBufferLike>
apply);
// ... render ...
var process: NodeJS.Process
process.
NodeJS.Process.stdout: NodeJS.WriteStream & {
    fd: 1;
}
The process.stdout property returns a stream connected tostdout (fd 1). It is a net.Socket (which is a Duplex stream) unless fd 1 refers to a file, in which case it is
a Writable stream.
For example, to copy process.stdin to process.stdout:
import { stdin, stdout } from 'node:process';

stdin.pipe(stdout);
process.stdout differs from other Node.js streams in important ways. See note on process I/O for more information.
stdout.
Socket.write(buffer: Uint8Array | string, cb?: (err?: Error | null) => void): boolean (+1 overload)
Sends data on the socket. The second parameter specifies the encoding in the
case of a string. It defaults to UTF8 encoding.
Returns true if the entire data was flushed successfully to the kernel
buffer. Returns false if all or part of the data was queued in user memory.'drain' will be emitted when the buffer is again free.
The optional callback parameter will be executed when the data is finally
written out, which may not be immediately.
See Writable stream write() method for more
information.
@since ― v0.1.90
@param ― encoding Only used when data is string.
write(
let pos: Setting
pos.
Setting.revert: Uint8Array<ArrayBufferLike>
revert);

`progressiveInput(level)`

Enable the progressive keyboard enhancement protocol.

import { 
function progressiveInput(level: number): Setting
progressiveInput } from "@bomb.sh/tty";

function progressiveInput(level: number): Setting
progressiveInput(2); // Kitty enhancement level 2+

Revert sends CSI <u to disable the protocol.

`mouseTracking()`

Enable SGR mouse reporting (modes 1003 and 1006). Required for pointer hit testing with term.render().

import { 
function mouseTracking(): Setting
mouseTracking } from "@bomb.sh/tty";

let 
let mouse: Setting
mouse = 
function mouseTracking(): Setting
mouseTracking();
var process: NodeJS.Process
process.
NodeJS.Process.stdout: NodeJS.WriteStream & {
    fd: 1;
}
The process.stdout property returns a stream connected tostdout (fd 1). It is a net.Socket (which is a Duplex stream) unless fd 1 refers to a file, in which case it is
a Writable stream.
For example, to copy process.stdin to process.stdout:
import { stdin, stdout } from 'node:process';

stdin.pipe(stdout);
process.stdout differs from other Node.js streams in important ways. See note on process I/O for more information.
stdout.
Socket.write(buffer: Uint8Array | string, cb?: (err?: Error | null) => void): boolean (+1 overload)
Sends data on the socket. The second parameter specifies the encoding in the
case of a string. It defaults to UTF8 encoding.
Returns true if the entire data was flushed successfully to the kernel
buffer. Returns false if all or part of the data was queued in user memory.'drain' will be emitted when the buffer is again free.
The optional callback parameter will be executed when the data is finally
written out, which may not be immediately.
See Writable stream write() method for more
information.
@since ― v0.1.90
@param ― encoding Only used when data is string.
write(
let mouse: Setting
mouse.
Setting.apply: Uint8Array<ArrayBufferLike>
apply);

Pair with the input parser to receive mouse events from stdin.

Typical lifecycle

import {
  
function alternateBuffer(options?: {
    clear?: boolean;
}): Setting
alternateBuffer,
  
function cursor(visible: boolean): Setting
cursor,
  
function mouseTracking(): Setting
mouseTracking,
  
function settings(...sequence: Setting[]): Setting
settings,
  
function createTerm(options: TermOptions): Promise<Term>
createTerm,
  
function createInput(options?: InputOptions): Promise<Input>
createInput,
} from "@bomb.sh/tty";

async function 
function main(): Promise<void>
main() {
  let 
let tty: Setting
tty = 
function settings(...sequence: Setting[]): Setting
settings(
function alternateBuffer(options?: {
    clear?: boolean;
}): Setting
alternateBuffer(), 
function cursor(visible: boolean): Setting
cursor(false), 
function mouseTracking(): Setting
mouseTracking());
  
var process: NodeJS.Process
process.
NodeJS.Process.stdout: NodeJS.WriteStream & {
    fd: 1;
}
The process.stdout property returns a stream connected tostdout (fd 1). It is a net.Socket (which is a Duplex stream) unless fd 1 refers to a file, in which case it is
a Writable stream.
For example, to copy process.stdin to process.stdout:
import { stdin, stdout } from 'node:process';

stdin.pipe(stdout);
process.stdout differs from other Node.js streams in important ways. See note on process I/O for more information.
stdout.
Socket.write(buffer: Uint8Array | string, cb?: (err?: Error | null) => void): boolean (+1 overload)
Sends data on the socket. The second parameter specifies the encoding in the
case of a string. It defaults to UTF8 encoding.
Returns true if the entire data was flushed successfully to the kernel
buffer. Returns false if all or part of the data was queued in user memory.'drain' will be emitted when the buffer is again free.
The optional callback parameter will be executed when the data is finally
written out, which may not be immediately.
See Writable stream write() method for more
information.
@since ― v0.1.90
@param ― encoding Only used when data is string.
write(
let tty: Setting
tty.
Setting.apply: Uint8Array<ArrayBufferLike>
apply);

  let 
let term: Term
term = await 
function createTerm(options: TermOptions): Promise<Term>
createTerm({ 
TermOptions.width: number
width: 80, 
TermOptions.height: number
height: 24 });
  let 
let input: Input
input = await 
function createInput(options?: InputOptions): Promise<Input>
createInput();

  
var process: NodeJS.Process
process.
NodeJS.Process.stdin: NodeJS.ReadStream & {
    fd: 0;
}
The process.stdin property returns a stream connected tostdin (fd 0). It is a net.Socket (which is a Duplex stream) unless fd 0 refers to a file, in which case it is
a Readable stream.
For details of how to read from stdin see readable.read().
As a Duplex stream, process.stdin can also be used in "old" mode that
is compatible with scripts written for Node.js prior to v0.10.
For more information see Stream compatibility.
In "old" streams mode the stdin stream is paused by default, so one
must call process.stdin.resume() to read from it. Note also that calling process.stdin.resume() itself would switch stream to "old" mode.
stdin.
ReadStream.setRawMode(mode: boolean): NodeJS.ReadStream & {
    fd: 0;
}
Allows configuration of tty.ReadStream so that it operates as a raw device.
When in raw mode, input is always available character-by-character, not
including modifiers. Additionally, all special processing of characters by the
terminal is disabled, including echoing input
characters. Ctrl+C will no longer cause a SIGINT when
in this mode.
@since ― v0.7.7
@param ― mode If true, configures the tty.ReadStream to operate as a raw device. If false, configures the tty.ReadStream to operate in its default mode. The readStream.isRaw
property will be set to the resulting mode.
setRawMode(true);

  // ... app loop ...

  
var process: NodeJS.Process
process.
NodeJS.Process.stdin: NodeJS.ReadStream & {
    fd: 0;
}
The process.stdin property returns a stream connected tostdin (fd 0). It is a net.Socket (which is a Duplex stream) unless fd 0 refers to a file, in which case it is
a Readable stream.
For details of how to read from stdin see readable.read().
As a Duplex stream, process.stdin can also be used in "old" mode that
is compatible with scripts written for Node.js prior to v0.10.
For more information see Stream compatibility.
In "old" streams mode the stdin stream is paused by default, so one
must call process.stdin.resume() to read from it. Note also that calling process.stdin.resume() itself would switch stream to "old" mode.
stdin.
ReadStream.setRawMode(mode: boolean): NodeJS.ReadStream & {
    fd: 0;
}
Allows configuration of tty.ReadStream so that it operates as a raw device.
When in raw mode, input is always available character-by-character, not
including modifiers. Additionally, all special processing of characters by the
terminal is disabled, including echoing input
characters. Ctrl+C will no longer cause a SIGINT when
in this mode.
@since ― v0.7.7
@param ― mode If true, configures the tty.ReadStream to operate as a raw device. If false, configures the tty.ReadStream to operate in its default mode. The readStream.isRaw
property will be set to the resulting mode.
setRawMode(false);
  
var process: NodeJS.Process
process.
NodeJS.Process.stdout: NodeJS.WriteStream & {
    fd: 1;
}
The process.stdout property returns a stream connected tostdout (fd 1). It is a net.Socket (which is a Duplex stream) unless fd 1 refers to a file, in which case it is
a Writable stream.
For example, to copy process.stdin to process.stdout:
import { stdin, stdout } from 'node:process';

stdin.pipe(stdout);
process.stdout differs from other Node.js streams in important ways. See note on process I/O for more information.
stdout.
Socket.write(buffer: Uint8Array | string, cb?: (err?: Error | null) => void): boolean (+1 overload)
Sends data on the socket. The second parameter specifies the encoding in the
case of a string. It defaults to UTF8 encoding.
Returns true if the entire data was flushed successfully to the kernel
buffer. Returns false if all or part of the data was queued in user memory.'drain' will be emitted when the buffer is again free.
The optional callback parameter will be executed when the data is finally
written out, which may not be immediately.
See Writable stream write() method for more
information.
@since ― v0.1.90
@param ― encoding Only used when data is string.
write(
let tty: Setting
tty.
Setting.revert: Uint8Array<ArrayBufferLike>
revert);
}

Next steps

Termcodes API (low-level escape sequences)
Getting Started (full quick start)