ae1e186ca06f4e5d47517501a63f0f4bf0fb3f01440eaec233c2b4bc4a5525d4819c9d3489c743835f62161fa3dee78ab18c289de0b0b79be85d3cb3a27f24 9.8 KB

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