{ } qjs-modules

readline

Source: lib/readline.js — compiled into qjsm; also readline/promises (lib/readlinePromises.js)

Node's readline (also Bun's and Deno's) for line-by-line input, without Node streams. test-readline.js (line mode) and test-readline-terminal.js (keystrokes; the expected bytes are recorded from node) run on qjsm, node, bun and deno; test-readline-file.js covers the FILE input (process.stdin).

import * as readline from 'readline';

const rl = readline.createInterface({ input: process.stdin, output: process.stdout });

for await (const line of rl) console.log(line);        // every line of stdin
rl.question('name? ', name => console.log(name));      // prompt, take one line

input

InputHow it is read
process.stdin, any FILE (fileno())os.setReadHandler() on the fd; UTF-8 decoded, never cut inside a character
WHATWG ReadableStream, async iterablepulled chunk by chunk; strings or bytes (Uint8Array, ArrayBuffer)
emitter with 'data' / 'end'what node, bun and deno pass (a Readable); pause()/resume() forwarded

A missing or unusable input throws TypeError.

Exports

ExportDescription
createInterface(input, output?, completer?, terminal?) / createInterface({ input, output, prompt, signal, terminal, completer, history, historySize, removeHistoryDuplicates, tabSize, crlfDelay, escapeCodeTimeout })A new Interface. prompt defaults to '> '; an aborted signal closes it.
InterfaceEventEmitter; events 'line', 'pause', 'resume', 'close'
emitKeypressEvents(stream)make an emitter stream emit 'keypress' (char, key) for its 'data'
promises{ Interface, createInterface } of readline/promises
cursorTo(stream, x, y?, cb?)ESC[<x+1>G, or ESC[<y+1>;<x+1>H with y
moveCursor(stream, dx, dy, cb?)ESC[nD/C then ESC[nA/B
clearLine(stream, dir, cb?)ESC[1K (dir < 0), ESC[0K (dir > 0), ESC[2K
clearScreenDown(stream, cb?)ESC[0J

The helpers write to anything with write() or puts(); a null stream does nothing.

Interface

MemberDescription
question(query, [options], cb)writes query to output; the next line goes to cb instead of 'line'. options.signal cancels it. Throws ERR_USE_AFTER_CLOSE once closed. A second question() while one is pending only prompts.
prompt(), setPrompt(s), getPrompt()write / change / read the prompt; prompt() resumes a paused interface
write(data)feeds data to the line splitter as if it had been typed
pause(), resume()stop / restart reading; emit 'pause' / 'resume'
close()emits 'pause' then 'close', once; the end of the input closes it too
[Symbol.asyncIterator]()the lines; ends at 'close'
terminal, line, cursor, history, input, output, columns, closedterminal defaults to whether output is a tty; closed is undefined until closed, as in Node
getCursorPos(){ rows, cols } of the cursor, counting the prompt, wide characters and wrapping at columns
clearLine()moves to the end of the line, writes \r\n and empties the line
'history' event(history) after every non-empty line
'SIGINT', 'SIGTSTP' eventsctrl-c / ctrl-z when there is a listener; ctrl-c without one closes the interface

Lines end at \n, \r\n or \r (a \n at the start of the next chunk after a chunk-final \r belongs to it); a last line without a terminator is emitted at the end of the input. Lines of one chunk are all delivered, even if a handler closes the interface in the middle, as in Node.

Terminal mode

With terminal: true (the default when output is a tty) the input is read as keystrokes and the line is edited and redrawn with the same escape sequences as Node. A tty FILE input (process.stdin) is put into raw mode and restored on close(). Any other input works too, which is how the tests drive it. Reads, writes to a FILE output, keys and widths go through terminal, so a Windows console without VT processing gets the same keys and redraws.

KeysAction
printable text, pasteinserted at the cursor; a line ending presses enter
return, enteremit 'line' (\r\n counts once within crlfDelay), add to history
left / right, ctrl-b / ctrl-fone character (a surrogate pair is one)
home / end, ctrl-a / ctrl-estart / end of the line
ctrl-left / right, meta-b / meta-fprevious / next word
backspace, ctrl-h / delete, ctrl-ddelete left / right; ctrl-d on an empty line closes
ctrl-u / ctrl-kdelete to the start / end of the line (kept for ctrl-y)
ctrl-w, ctrl-backspace, meta-backspace / meta-d, ctrl-deletedelete the word left / right
ctrl-yinsert the last deleted text
up / downhistory, limited to entries starting with the text before the cursor
ctrl-p / ctrl-nhistory, without the prefix filter
tabwith a completer: complete; without: insert a tab
ctrl-lclear the screen and redraw
ctrl-c, ctrl-z'SIGINT' / 'SIGTSTP' if listened to; ctrl-c otherwise closes

completer(line) returns [completions, completeOn], or a promise of it; `completer(line, callback)callscallback(err, [completions, completeOn])`. A common prefix is inserted; a second tab lists the completions in columns. The interface is paused while it runs. historySize defaults to 30, history seeds it (newest first), removeHistoryDuplicates drops older equal entries.

A lone escape key is held escapeCodeTimeout ms (500) in case it starts a sequence. Two tabs arriving in one chunk are not special-cased (Node inserts a literal tab then).

Not implemented

Kill-ring rotation (meta-y), undo/redo, the Readline class of readline/promises, and output resize events from a FILE (an emitter output's 'resize' redraws).

Export list

Generated by utilities/doc-api.js from the readline dump of utilities/api-surface.sh: 35 members. Edit the text above this block, not the block.

Functions: clearLine(), clearScreenDown(), createInterface(), cursorTo(), emitKeypressEvents(), moveCursor()

Interface

class, constructible

  • methods: clearLine(), close(), getCursorPos(), getPrompt(), pause(), prompt(), question(), resume(), setPrompt(), write(), [Symbol.asyncIterator]()
  • properties: closed (get), columns (get), input (get), output (get)

default

object

  • static methods: Interface(), clearLine(), clearScreenDown(), createInterface(), cursorTo(), emitKeypressEvents(), moveCursor()
  • static values: promises

promises

object

  • static methods: Interface(), createInterface()