closeout/cursor

import { showCursor, hideCursor, alternateScreen, … } from 'closeout/cursor';

FunctionsCopy Anchor Link

alternateScreenCopy Anchor Link

Enter the alternate screen, and register leaving it.

function alternateScreen(stream: OutputStream, onExit: Registrar): () => void;

Returns () => void

bracketedPasteCopy Anchor Link

Turn bracketed paste on, and register turning it off, with {@link alternateScreen}'s contract: once only, early calls unregister, and a non-TTY gets nothing in either direction.

function bracketedPaste(stream: OutputStream, onExit: Registrar): () => void;

Returns () => void

hideCursorCopy Anchor Link

Hide the cursor, and register its restore.

function hideCursor(stream: OutputStream, onExit: Registrar): () => void;

Returns () => void

rawModeCopy Anchor Link

Turn raw mode on, and register turning it off.

function rawMode(input: InputStream, onExit: Registrar): () => void;

Returns () => void

showCursorCopy Anchor Link

Show the cursor. Safe to call when it was never hidden, and safe to call twice — the sequence is idempotent, which is what makes it usable from an exit path that may run after a caller has already cleaned up.

function showCursor(stream: OutputStream): void;

Returns void

ConstantsCopy Anchor Link

DISABLE_BRACKETED_PASTECopy Anchor Link

const DISABLE_BRACKETED_PASTE = "\u001B[?2004l";

ENABLE_BRACKETED_PASTECopy Anchor Link

Bracketed paste, DEC private mode 2004: while it is on, the terminal wraps pasted text in ESC[200~ … ESC[201~, so a line editor can take a multi-line paste as text instead of as keys — Enter included — and a terminal left with it on wraps every later paste in the shell.

const ENABLE_BRACKETED_PASTE = "\u001B[?2004h";

ENTER_ALTERNATE_SCREENCopy Anchor Link

The alternate screen, DEC private mode 1049: entering saves the cursor and switches to a blank buffer; leaving switches back and restores it, so the user's scrollback is as it was.

const ENTER_ALTERNATE_SCREEN = "\u001B[?1049h";

HIDE_CURSORCopy Anchor Link

The sequences this layer exists to undo, published because they are its vocabulary: anything that hides a cursor owes a show on every exit path, and a caller writing them by hand should be writing the same bytes we restore.

const HIDE_CURSOR = "\u001B[?25l";

LEAVE_ALTERNATE_SCREENCopy Anchor Link

const LEAVE_ALTERNATE_SCREEN = "\u001B[?1049l";

SHOW_CURSORCopy Anchor Link

const SHOW_CURSOR = "\u001B[?25h";

InterfacesCopy Anchor Link

InputStreamCopy Anchor Link

The half of tty.ReadStream raw mode needs. setRawMode is optional because a piped process.stdin has none, and a caller should be able to pass process.stdin either way.

interface InputStream {
    isTTY?: boolean;
    /** Node's own record of the mode, read to learn whether somebody else turned it on. */
    isRaw?: boolean;
    setRawMode?(mode: boolean): unknown;
}

OutputStreamCopy Anchor Link

The half of NodeJS.WriteStream this needs, so a test can pass a recorder.

interface OutputStream {
    write(chunk: string): unknown;
    isTTY?: boolean;
}

TypesCopy Anchor Link

RegistrarCopy Anchor Link

Where a pairing registers its undo — closeout's registry, or a caller's own.

type Registrar = (handler: () => void) => () => void;