tty.d.ts (9856B)
1 /** 2 * The `tty` module provides the `tty.ReadStream` and `tty.WriteStream` classes. 3 * In most cases, it will not be necessary or possible to use this module directly. 4 * However, it can be accessed using: 5 * 6 * ```js 7 * import tty from 'node:tty'; 8 * ``` 9 * 10 * When Node.js detects that it is being run with a text terminal ("TTY") 11 * attached, `process.stdin` will, by default, be initialized as an instance of`tty.ReadStream` and both `process.stdout` and `process.stderr` will, by 12 * default, be instances of `tty.WriteStream`. The preferred method of determining 13 * whether Node.js is being run within a TTY context is to check that the value of 14 * the `process.stdout.isTTY` property is `true`: 15 * 16 * ```console 17 * $ node -p -e "Boolean(process.stdout.isTTY)" 18 * true 19 * $ node -p -e "Boolean(process.stdout.isTTY)" | cat 20 * false 21 * ``` 22 * 23 * In most cases, there should be little to no reason for an application to 24 * manually create instances of the `tty.ReadStream` and `tty.WriteStream` classes. 25 * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/tty.js) 26 */ 27 declare module "tty" { 28 import * as net from "node:net"; 29 /** 30 * The `tty.isatty()` method returns `true` if the given `fd` is associated with 31 * a TTY and `false` if it is not, including whenever `fd` is not a non-negative 32 * integer. 33 * @since v0.5.8 34 * @param fd A numeric file descriptor 35 */ 36 function isatty(fd: number): boolean; 37 /** 38 * Represents the readable side of a TTY. In normal circumstances `process.stdin` will be the only `tty.ReadStream` instance in a Node.js 39 * process and there should be no reason to create additional instances. 40 * @since v0.5.8 41 */ 42 class ReadStream extends net.Socket { 43 constructor(fd: number, options?: net.SocketConstructorOpts); 44 /** 45 * A `boolean` that is `true` if the TTY is currently configured to operate as a 46 * raw device. Defaults to `false`. 47 * @since v0.7.7 48 */ 49 isRaw: boolean; 50 /** 51 * Allows configuration of `tty.ReadStream` so that it operates as a raw device. 52 * 53 * When in raw mode, input is always available character-by-character, not 54 * including modifiers. Additionally, all special processing of characters by the 55 * terminal is disabled, including echoing input characters.Ctrl+C will no longer cause a `SIGINT` when in this mode. 56 * @since v0.7.7 57 * @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` 58 * property will be set to the resulting mode. 59 * @return The read stream instance. 60 */ 61 setRawMode(mode: boolean): this; 62 /** 63 * A `boolean` that is always `true` for `tty.ReadStream` instances. 64 * @since v0.5.8 65 */ 66 isTTY: boolean; 67 } 68 /** 69 * -1 - to the left from cursor 70 * 0 - the entire line 71 * 1 - to the right from cursor 72 */ 73 type Direction = -1 | 0 | 1; 74 /** 75 * Represents the writable side of a TTY. In normal circumstances,`process.stdout` and `process.stderr` will be the only`tty.WriteStream` instances created for a Node.js process and there 76 * should be no reason to create additional instances. 77 * @since v0.5.8 78 */ 79 class WriteStream extends net.Socket { 80 constructor(fd: number); 81 addListener(event: string, listener: (...args: any[]) => void): this; 82 addListener(event: "resize", listener: () => void): this; 83 emit(event: string | symbol, ...args: any[]): boolean; 84 emit(event: "resize"): boolean; 85 on(event: string, listener: (...args: any[]) => void): this; 86 on(event: "resize", listener: () => void): this; 87 once(event: string, listener: (...args: any[]) => void): this; 88 once(event: "resize", listener: () => void): this; 89 prependListener(event: string, listener: (...args: any[]) => void): this; 90 prependListener(event: "resize", listener: () => void): this; 91 prependOnceListener(event: string, listener: (...args: any[]) => void): this; 92 prependOnceListener(event: "resize", listener: () => void): this; 93 /** 94 * `writeStream.clearLine()` clears the current line of this `WriteStream` in a 95 * direction identified by `dir`. 96 * @since v0.7.7 97 * @param callback Invoked once the operation completes. 98 * @return `false` if the stream wishes for the calling code to wait for the `'drain'` event to be emitted before continuing to write additional data; otherwise `true`. 99 */ 100 clearLine(dir: Direction, callback?: () => void): boolean; 101 /** 102 * `writeStream.clearScreenDown()` clears this `WriteStream` from the current 103 * cursor down. 104 * @since v0.7.7 105 * @param callback Invoked once the operation completes. 106 * @return `false` if the stream wishes for the calling code to wait for the `'drain'` event to be emitted before continuing to write additional data; otherwise `true`. 107 */ 108 clearScreenDown(callback?: () => void): boolean; 109 /** 110 * `writeStream.cursorTo()` moves this `WriteStream`'s cursor to the specified 111 * position. 112 * @since v0.7.7 113 * @param callback Invoked once the operation completes. 114 * @return `false` if the stream wishes for the calling code to wait for the `'drain'` event to be emitted before continuing to write additional data; otherwise `true`. 115 */ 116 cursorTo(x: number, y?: number, callback?: () => void): boolean; 117 cursorTo(x: number, callback: () => void): boolean; 118 /** 119 * `writeStream.moveCursor()` moves this `WriteStream`'s cursor _relative_ to its 120 * current position. 121 * @since v0.7.7 122 * @param callback Invoked once the operation completes. 123 * @return `false` if the stream wishes for the calling code to wait for the `'drain'` event to be emitted before continuing to write additional data; otherwise `true`. 124 */ 125 moveCursor(dx: number, dy: number, callback?: () => void): boolean; 126 /** 127 * Returns: 128 * 129 * * `1` for 2, 130 * * `4` for 16, 131 * * `8` for 256, 132 * * `24` for 16,777,216 colors supported. 133 * 134 * Use this to determine what colors the terminal supports. Due to the nature of 135 * colors in terminals it is possible to either have false positives or false 136 * negatives. It depends on process information and the environment variables that 137 * may lie about what terminal is used. 138 * It is possible to pass in an `env` object to simulate the usage of a specific 139 * terminal. This can be useful to check how specific environment settings behave. 140 * 141 * To enforce a specific color support, use one of the below environment settings. 142 * 143 * * 2 colors: `FORCE_COLOR = 0` (Disables colors) 144 * * 16 colors: `FORCE_COLOR = 1` 145 * * 256 colors: `FORCE_COLOR = 2` 146 * * 16,777,216 colors: `FORCE_COLOR = 3` 147 * 148 * Disabling color support is also possible by using the `NO_COLOR` and `NODE_DISABLE_COLORS` environment variables. 149 * @since v9.9.0 150 * @param [env=process.env] An object containing the environment variables to check. This enables simulating the usage of a specific terminal. 151 */ 152 getColorDepth(env?: object): number; 153 /** 154 * Returns `true` if the `writeStream` supports at least as many colors as provided 155 * in `count`. Minimum support is 2 (black and white). 156 * 157 * This has the same false positives and negatives as described in `writeStream.getColorDepth()`. 158 * 159 * ```js 160 * process.stdout.hasColors(); 161 * // Returns true or false depending on if `stdout` supports at least 16 colors. 162 * process.stdout.hasColors(256); 163 * // Returns true or false depending on if `stdout` supports at least 256 colors. 164 * process.stdout.hasColors({ TMUX: '1' }); 165 * // Returns true. 166 * process.stdout.hasColors(2 ** 24, { TMUX: '1' }); 167 * // Returns false (the environment setting pretends to support 2 ** 8 colors). 168 * ``` 169 * @since v11.13.0, v10.16.0 170 * @param [count=16] The number of colors that are requested (minimum 2). 171 * @param [env=process.env] An object containing the environment variables to check. This enables simulating the usage of a specific terminal. 172 */ 173 hasColors(count?: number): boolean; 174 hasColors(env?: object): boolean; 175 hasColors(count: number, env?: object): boolean; 176 /** 177 * `writeStream.getWindowSize()` returns the size of the TTY 178 * corresponding to this `WriteStream`. The array is of the type`[numColumns, numRows]` where `numColumns` and `numRows` represent the number 179 * of columns and rows in the corresponding TTY. 180 * @since v0.7.7 181 */ 182 getWindowSize(): [number, number]; 183 /** 184 * A `number` specifying the number of columns the TTY currently has. This property 185 * is updated whenever the `'resize'` event is emitted. 186 * @since v0.7.7 187 */ 188 columns: number; 189 /** 190 * A `number` specifying the number of rows the TTY currently has. This property 191 * is updated whenever the `'resize'` event is emitted. 192 * @since v0.7.7 193 */ 194 rows: number; 195 /** 196 * A `boolean` that is always `true`. 197 * @since v0.5.8 198 */ 199 isTTY: boolean; 200 } 201 } 202 declare module "node:tty" { 203 export * from "tty"; 204 }