AK-21/Graphite-Industrial-Intelligence

1/**2 * The `node:readline` module provides an interface for reading data from a [Readable](https://nodejs.org/docs/latest-v24.x/api/stream.html#readable-streams) stream3 * (such as [`process.stdin`](https://nodejs.org/docs/latest-v24.x/api/process.html#processstdin)) one line at a time.4 *5 * To use the promise-based APIs:6 *7 * ```js8 * import * as readline from 'node:readline/promises';9 * ```10 *11 * To use the callback and sync APIs:12 *13 * ```js14 * import * as readline from 'node:readline';15 * ```16 *17 * The following simple example illustrates the basic use of the `node:readline` module.18 *19 * ```js20 * import * as readline from 'node:readline/promises';21 * import { stdin as input, stdout as output } from 'node:process';22 *23 * const rl = readline.createInterface({ input, output });24 *25 * const answer = await rl.question('What do you think of Node.js? ');26 *27 * console.log(`Thank you for your valuable feedback: ${answer}`);28 *29 * rl.close();30 * ```31 *32 * Once this code is invoked, the Node.js application will not terminate until the `readline.Interface` is closed because the interface waits for data to be33 * received on the `input` stream.34 * @see [source](https://github.com/nodejs/node/blob/v24.x/lib/readline.js)35 */36declare module "readline" {37    import { Abortable, EventEmitter } from "node:events";38    import * as promises from "node:readline/promises";39    export { promises };40    export interface Key {41        sequence?: string | undefined;42        name?: string | undefined;43        ctrl?: boolean | undefined;44        meta?: boolean | undefined;45        shift?: boolean | undefined;46    }47    /**48     * Instances of the `readline.Interface` class are constructed using the `readline.createInterface()` method. Every instance is associated with a49     * single `input` [Readable](https://nodejs.org/docs/latest-v24.x/api/stream.html#readable-streams) stream and a single `output` [Writable](https://nodejs.org/docs/latest-v24.x/api/stream.html#writable-streams) stream.50     * The `output` stream is used to print prompts for user input that arrives on,51     * and is read from, the `input` stream.52     * @since v0.1.10453     */54    export class Interface extends EventEmitter implements Disposable {55        readonly terminal: boolean;56        /**57         * The current input data being processed by node.58         *59         * This can be used when collecting input from a TTY stream to retrieve the60         * current value that has been processed thus far, prior to the `line` event61         * being emitted. Once the `line` event has been emitted, this property will62         * be an empty string.63         *64         * Be aware that modifying the value during the instance runtime may have65         * unintended consequences if `rl.cursor` is not also controlled.66         *67         * **If not using a TTY stream for input, use the `'line'` event.**68         *69         * One possible use case would be as follows:70         *71         * ```js72         * const values = ['lorem ipsum', 'dolor sit amet'];73         * const rl = readline.createInterface(process.stdin);74         * const showResults = debounce(() => {75         *   console.log(76         *     '\n',77         *     values.filter((val) => val.startsWith(rl.line)).join(' '),78         *   );79         * }, 300);80         * process.stdin.on('keypress', (c, k) => {81         *   showResults();82         * });83         * ```84         * @since v0.1.9885         */86        readonly line: string;87        /**88         * The cursor position relative to `rl.line`.89         *90         * This will track where the current cursor lands in the input string, when91         * reading input from a TTY stream. The position of cursor determines the92         * portion of the input string that will be modified as input is processed,93         * as well as the column where the terminal caret will be rendered.94         * @since v0.1.9895         */96        readonly cursor: number;97        /**98         * NOTE: According to the documentation:99         *100         * > Instances of the `readline.Interface` class are constructed using the101         * > `readline.createInterface()` method.102         *103         * @see https://nodejs.org/dist/latest-v24.x/docs/api/readline.html#class-interfaceconstructor104         */105        protected constructor(106            input: NodeJS.ReadableStream,107            output?: NodeJS.WritableStream,108            completer?: Completer | AsyncCompleter,109            terminal?: boolean,110        );111        /**112         * NOTE: According to the documentation:113         *114         * > Instances of the `readline.Interface` class are constructed using the115         * > `readline.createInterface()` method.116         *117         * @see https://nodejs.org/dist/latest-v24.x/docs/api/readline.html#class-interfaceconstructor118         */119        protected constructor(options: ReadLineOptions);120        /**121         * The `rl.getPrompt()` method returns the current prompt used by `rl.prompt()`.122         * @since v15.3.0, v14.17.0123         * @return the current prompt string124         */125        getPrompt(): string;126        /**127         * The `rl.setPrompt()` method sets the prompt that will be written to `output` whenever `rl.prompt()` is called.128         * @since v0.1.98129         */130        setPrompt(prompt: string): void;131        /**132         * The `rl.prompt()` method writes the `Interface` instances configured`prompt` to a new line in `output` in order to provide a user with a new133         * location at which to provide input.134         *135         * When called, `rl.prompt()` will resume the `input` stream if it has been136         * paused.137         *138         * If the `Interface` was created with `output` set to `null` or `undefined` the prompt is not written.139         * @since v0.1.98140         * @param preserveCursor If `true`, prevents the cursor placement from being reset to `0`.141         */142        prompt(preserveCursor?: boolean): void;143        /**144         * The `rl.question()` method displays the `query` by writing it to the `output`,145         * waits for user input to be provided on `input`, then invokes the `callback` function passing the provided input as the first argument.146         *147         * When called, `rl.question()` will resume the `input` stream if it has been148         * paused.149         *150         * If the `Interface` was created with `output` set to `null` or `undefined` the `query` is not written.151         *152         * The `callback` function passed to `rl.question()` does not follow the typical153         * pattern of accepting an `Error` object or `null` as the first argument.154         * The `callback` is called with the provided answer as the only argument.155         *156         * An error will be thrown if calling `rl.question()` after `rl.close()`.157         *158         * Example usage:159         *160         * ```js161         * rl.question('What is your favorite food? ', (answer) => {162         *   console.log(`Oh, so your favorite food is ${answer}`);163         * });164         * ```165         *166         * Using an `AbortController` to cancel a question.167         *168         * ```js169         * const ac = new AbortController();170         * const signal = ac.signal;171         *172         * rl.question('What is your favorite food? ', { signal }, (answer) => {173         *   console.log(`Oh, so your favorite food is ${answer}`);174         * });175         *176         * signal.addEventListener('abort', () => {177         *   console.log('The food question timed out');178         * }, { once: true });179         *180         * setTimeout(() => ac.abort(), 10000);181         * ```182         * @since v0.3.3183         * @param query A statement or query to write to `output`, prepended to the prompt.184         * @param callback A callback function that is invoked with the user's input in response to the `query`.185         */186        question(query: string, callback: (answer: string) => void): void;187        question(query: string, options: Abortable, callback: (answer: string) => void): void;188        /**189         * The `rl.pause()` method pauses the `input` stream, allowing it to be resumed190         * later if necessary.191         *192         * Calling `rl.pause()` does not immediately pause other events (including `'line'`) from being emitted by the `Interface` instance.193         * @since v0.3.4194         */195        pause(): this;196        /**197         * The `rl.resume()` method resumes the `input` stream if it has been paused.198         * @since v0.3.4199         */200        resume(): this;201        /**202         * The `rl.close()` method closes the `Interface` instance and203         * relinquishes control over the `input` and `output` streams. When called,204         * the `'close'` event will be emitted.205         *206         * Calling `rl.close()` does not immediately stop other events (including `'line'`)207         * from being emitted by the `Interface` instance.208         * @since v0.1.98209         */210        close(): void;211        /**212         * Alias for `rl.close()`.213         * @since v22.15.0214         */215        [Symbol.dispose](): void;216        /**217         * The `rl.write()` method will write either `data` or a key sequence identified218         * by `key` to the `output`. The `key` argument is supported only if `output` is219         * a `TTY` text terminal. See `TTY keybindings` for a list of key220         * combinations.221         *222         * If `key` is specified, `data` is ignored.223         *224         * When called, `rl.write()` will resume the `input` stream if it has been225         * paused.226         *227         * If the `Interface` was created with `output` set to `null` or `undefined` the `data` and `key` are not written.228         *229         * ```js230         * rl.write('Delete this!');231         * // Simulate Ctrl+U to delete the line written previously232         * rl.write(null, { ctrl: true, name: 'u' });233         * ```234         *235         * The `rl.write()` method will write the data to the `readline` `Interface`'s `input` _as if it were provided by the user_.236         * @since v0.1.98237         */238        write(data: string | Buffer, key?: Key): void;239        write(data: undefined | null | string | Buffer, key: Key): void;240        /**241         * Returns the real position of the cursor in relation to the input242         * prompt + string. Long input (wrapping) strings, as well as multiple243         * line prompts are included in the calculations.244         * @since v13.5.0, v12.16.0245         */246        getCursorPos(): CursorPos;247        /**248         * events.EventEmitter249         * 1. close250         * 2. line251         * 3. pause252         * 4. resume253         * 5. SIGCONT254         * 6. SIGINT255         * 7. SIGTSTP256         * 8. history257         */258        addListener(event: string, listener: (...args: any[]) => void): this;259        addListener(event: "close", listener: () => void): this;260        addListener(event: "error", listener: (error: Error) => void): this;261        addListener(event: "line", listener: (input: string) => void): this;262        addListener(event: "pause", listener: () => void): this;263        addListener(event: "resume", listener: () => void): this;264        addListener(event: "SIGCONT", listener: () => void): this;265        addListener(event: "SIGINT", listener: () => void): this;266        addListener(event: "SIGTSTP", listener: () => void): this;267        addListener(event: "history", listener: (history: string[]) => void): this;268        emit(event: string | symbol, ...args: any[]): boolean;269        emit(event: "close"): boolean;270        emit(event: "error", error: Error): boolean;271        emit(event: "line", input: string): boolean;272        emit(event: "pause"): boolean;273        emit(event: "resume"): boolean;274        emit(event: "SIGCONT"): boolean;275        emit(event: "SIGINT"): boolean;276        emit(event: "SIGTSTP"): boolean;277        emit(event: "history", history: string[]): boolean;278        on(event: string, listener: (...args: any[]) => void): this;279        on(event: "close", listener: () => void): this;280        on(event: "error", listener: (error: Error) => void): this;281        on(event: "line", listener: (input: string) => void): this;282        on(event: "pause", listener: () => void): this;283        on(event: "resume", listener: () => void): this;284        on(event: "SIGCONT", listener: () => void): this;285        on(event: "SIGINT", listener: () => void): this;286        on(event: "SIGTSTP", listener: () => void): this;287        on(event: "history", listener: (history: string[]) => void): this;288        once(event: string, listener: (...args: any[]) => void): this;289        once(event: "close", listener: () => void): this;290        once(event: "error", listener: (error: Error) => void): this;291        once(event: "line", listener: (input: string) => void): this;292        once(event: "pause", listener: () => void): this;293        once(event: "resume", listener: () => void): this;294        once(event: "SIGCONT", listener: () => void): this;295        once(event: "SIGINT", listener: () => void): this;296        once(event: "SIGTSTP", listener: () => void): this;297        once(event: "history", listener: (history: string[]) => void): this;298        prependListener(event: string, listener: (...args: any[]) => void): this;299        prependListener(event: "close", listener: () => void): this;300        prependListener(event: "error", listener: (error: Error) => void): this;301        prependListener(event: "line", listener: (input: string) => void): this;302        prependListener(event: "pause", listener: () => void): this;303        prependListener(event: "resume", listener: () => void): this;304        prependListener(event: "SIGCONT", listener: () => void): this;305        prependListener(event: "SIGINT", listener: () => void): this;306        prependListener(event: "SIGTSTP", listener: () => void): this;307        prependListener(event: "history", listener: (history: string[]) => void): this;308        prependOnceListener(event: string, listener: (...args: any[]) => void): this;309        prependOnceListener(event: "close", listener: () => void): this;310        prependOnceListener(event: "error", listener: (error: Error) => void): this;311        prependOnceListener(event: "line", listener: (input: string) => void): this;312        prependOnceListener(event: "pause", listener: () => void): this;313        prependOnceListener(event: "resume", listener: () => void): this;314        prependOnceListener(event: "SIGCONT", listener: () => void): this;315        prependOnceListener(event: "SIGINT", listener: () => void): this;316        prependOnceListener(event: "SIGTSTP", listener: () => void): this;317        prependOnceListener(event: "history", listener: (history: string[]) => void): this;318        [Symbol.asyncIterator](): NodeJS.AsyncIterator<string>;319    }320    export type ReadLine = Interface; // type forwarded for backwards compatibility321    export type Completer = (line: string) => CompleterResult;322    export type AsyncCompleter = (323        line: string,324        callback: (err?: null | Error, result?: CompleterResult) => void,325    ) => void;326    export type CompleterResult = [string[], string];327    export interface ReadLineOptions {328        /**329         * The [`Readable`](https://nodejs.org/docs/latest-v24.x/api/stream.html#readable-streams) stream to listen to330         */331        input: NodeJS.ReadableStream;332        /**333         * The [`Writable`](https://nodejs.org/docs/latest-v24.x/api/stream.html#writable-streams) stream to write readline data to.334         */335        output?: NodeJS.WritableStream | undefined;336        /**337         * An optional function used for Tab autocompletion.338         */339        completer?: Completer | AsyncCompleter | undefined;340        /**341         * `true` if the `input` and `output` streams should be treated like a TTY,342         * and have ANSI/VT100 escape codes written to it.343         * Default: checking `isTTY` on the `output` stream upon instantiation.344         */345        terminal?: boolean | undefined;346        /**347         * Initial list of history lines.348         * This option makes sense only if `terminal` is set to `true` by the user or by an internal `output` check,349         * otherwise the history caching mechanism is not initialized at all.350         * @default []351         */352        history?: string[] | undefined;353        /**354         * Maximum number of history lines retained.355         * To disable the history set this value to `0`.356         * This option makes sense only if `terminal` is set to `true` by the user or by an internal `output` check,357         * otherwise the history caching mechanism is not initialized at all.358         * @default 30359         */360        historySize?: number | undefined;361        /**362         * If `true`, when a new input line added to the history list duplicates an older one,363         * this removes the older line from the list.364         * @default false365         */366        removeHistoryDuplicates?: boolean | undefined;367        /**368         * The prompt string to use.369         * @default "> "370         */371        prompt?: string | undefined;372        /**373         * If the delay between `\r` and `\n` exceeds `crlfDelay` milliseconds,374         * both `\r` and `\n` will be treated as separate end-of-line input.375         * `crlfDelay` will be coerced to a number no less than `100`.376         * It can be set to `Infinity`, in which case377         * `\r` followed by `\n` will always be considered a single newline378         * (which may be reasonable for [reading files](https://nodejs.org/docs/latest-v24.x/api/readline.html#example-read-file-stream-line-by-line) with `\r\n` line delimiter).379         * @default 100380         */381        crlfDelay?: number | undefined;382        /**383         * The duration `readline` will wait for a character384         * (when reading an ambiguous key sequence in milliseconds385         * one that can both form a complete key sequence using the input read so far386         * and can take additional input to complete a longer key sequence).387         * @default 500388         */389        escapeCodeTimeout?: number | undefined;390        /**391         * The number of spaces a tab is equal to (minimum 1).392         * @default 8393         */394        tabSize?: number | undefined;395        /**396         * Allows closing the interface using an AbortSignal.397         * Aborting the signal will internally call `close` on the interface.398         */399        signal?: AbortSignal | undefined;400    }401    /**402     * The `readline.createInterface()` method creates a new `readline.Interface` instance.403     *404     * ```js405     * import readline from 'node:readline';406     * const rl = readline.createInterface({407     *   input: process.stdin,408     *   output: process.stdout,409     * });410     * ```411     *412     * Once the `readline.Interface` instance is created, the most common case is to413     * listen for the `'line'` event:414     *415     * ```js416     * rl.on('line', (line) => {417     *   console.log(`Received: ${line}`);418     * });419     * ```420     *421     * If `terminal` is `true` for this instance then the `output` stream will get422     * the best compatibility if it defines an `output.columns` property and emits423     * a `'resize'` event on the `output` if or when the columns ever change424     * (`process.stdout` does this automatically when it is a TTY).425     *426     * When creating a `readline.Interface` using `stdin` as input, the program427     * will not terminate until it receives an [EOF character](https://en.wikipedia.org/wiki/End-of-file#EOF_character). To exit without428     * waiting for user input, call `process.stdin.unref()`.429     * @since v0.1.98430     */431    export function createInterface(432        input: NodeJS.ReadableStream,433        output?: NodeJS.WritableStream,434        completer?: Completer | AsyncCompleter,435        terminal?: boolean,436    ): Interface;437    export function createInterface(options: ReadLineOptions): Interface;438    /**439     * The `readline.emitKeypressEvents()` method causes the given `Readable` stream to begin emitting `'keypress'` events corresponding to received input.440     *441     * Optionally, `interface` specifies a `readline.Interface` instance for which442     * autocompletion is disabled when copy-pasted input is detected.443     *444     * If the `stream` is a `TTY`, then it must be in raw mode.445     *446     * This is automatically called by any readline instance on its `input` if the `input` is a terminal. Closing the `readline` instance does not stop447     * the `input` from emitting `'keypress'` events.448     *449     * ```js450     * readline.emitKeypressEvents(process.stdin);451     * if (process.stdin.isTTY)452     *   process.stdin.setRawMode(true);453     * ```454     *455     * ## Example: Tiny CLI456     *457     * The following example illustrates the use of `readline.Interface` class to458     * implement a small command-line interface:459     *460     * ```js461     * import readline from 'node:readline';462     * const rl = readline.createInterface({463     *   input: process.stdin,464     *   output: process.stdout,465     *   prompt: 'OHAI> ',466     * });467     *468     * rl.prompt();469     *470     * rl.on('line', (line) => {471     *   switch (line.trim()) {472     *     case 'hello':473     *       console.log('world!');474     *       break;475     *     default:476     *       console.log(`Say what? I might have heard '${line.trim()}'`);477     *       break;478     *   }479     *   rl.prompt();480     * }).on('close', () => {481     *   console.log('Have a great day!');482     *   process.exit(0);483     * });484     * ```485     *486     * ## Example: Read file stream line-by-Line487     *488     * A common use case for `readline` is to consume an input file one line at a489     * time. The easiest way to do so is leveraging the `fs.ReadStream` API as490     * well as a `for await...of` loop:491     *492     * ```js493     * import fs from 'node:fs';494     * import readline from 'node:readline';495     *496     * async function processLineByLine() {497     *   const fileStream = fs.createReadStream('input.txt');498     *499     *   const rl = readline.createInterface({500     *     input: fileStream,501     *     crlfDelay: Infinity,502     *   });503     *   // Note: we use the crlfDelay option to recognize all instances of CR LF504     *   // ('\r\n') in input.txt as a single line break.505     *506     *   for await (const line of rl) {507     *     // Each line in input.txt will be successively available here as `line`.508     *     console.log(`Line from file: ${line}`);509     *   }510     * }511     *512     * processLineByLine();513     * ```514     *515     * Alternatively, one could use the `'line'` event:516     *517     * ```js518     * import fs from 'node:fs';519     * import readline from 'node:readline';520     *521     * const rl = readline.createInterface({522     *   input: fs.createReadStream('sample.txt'),523     *   crlfDelay: Infinity,524     * });525     *526     * rl.on('line', (line) => {527     *   console.log(`Line from file: ${line}`);528     * });529     * ```530     *531     * Currently, `for await...of` loop can be a bit slower. If `async` / `await` flow and speed are both essential, a mixed approach can be applied:532     *533     * ```js534     * import { once } from 'node:events';535     * import { createReadStream } from 'node:fs';536     * import { createInterface } from 'node:readline';537     *538     * (async function processLineByLine() {539     *   try {540     *     const rl = createInterface({541     *       input: createReadStream('big-file.txt'),542     *       crlfDelay: Infinity,543     *     });544     *545     *     rl.on('line', (line) => {546     *       // Process the line.547     *     });548     *549     *     await once(rl, 'close');550     *551     *     console.log('File processed.');552     *   } catch (err) {553     *     console.error(err);554     *   }555     * })();556     * ```557     * @since v0.7.7558     */559    export function emitKeypressEvents(stream: NodeJS.ReadableStream, readlineInterface?: Interface): void;560    export type Direction = -1 | 0 | 1;561    export interface CursorPos {562        rows: number;563        cols: number;564    }565    /**566     * The `readline.clearLine()` method clears current line of given [TTY](https://nodejs.org/docs/latest-v24.x/api/tty.html) stream567     * in a specified direction identified by `dir`.568     * @since v0.7.7569     * @param callback Invoked once the operation completes.570     * @return `false` if `stream` wishes for the calling code to wait for the `'drain'` event to be emitted before continuing to write additional data; otherwise `true`.571     */572    export function clearLine(stream: NodeJS.WritableStream, dir: Direction, callback?: () => void): boolean;573    /**574     * The `readline.clearScreenDown()` method clears the given [TTY](https://nodejs.org/docs/latest-v24.x/api/tty.html) stream from575     * the current position of the cursor down.576     * @since v0.7.7577     * @param callback Invoked once the operation completes.578     * @return `false` if `stream` wishes for the calling code to wait for the `'drain'` event to be emitted before continuing to write additional data; otherwise `true`.579     */580    export function clearScreenDown(stream: NodeJS.WritableStream, callback?: () => void): boolean;581    /**582     * The `readline.cursorTo()` method moves cursor to the specified position in a583     * given [TTY](https://nodejs.org/docs/latest-v24.x/api/tty.html) `stream`.584     * @since v0.7.7585     * @param callback Invoked once the operation completes.586     * @return `false` if `stream` wishes for the calling code to wait for the `'drain'` event to be emitted before continuing to write additional data; otherwise `true`.587     */588    export function cursorTo(stream: NodeJS.WritableStream, x: number, y?: number, callback?: () => void): boolean;589    /**590     * The `readline.moveCursor()` method moves the cursor _relative_ to its current591     * position in a given [TTY](https://nodejs.org/docs/latest-v24.x/api/tty.html) `stream`.592     * @since v0.7.7593     * @param callback Invoked once the operation completes.594     * @return `false` if `stream` wishes for the calling code to wait for the `'drain'` event to be emitted before continuing to write additional data; otherwise `true`.595     */596    export function moveCursor(stream: NodeJS.WritableStream, dx: number, dy: number, callback?: () => void): boolean;597}598declare module "node:readline" {599    export * from "readline";600}601