0b3cf47b3b6cf945f0fa2ebd4e3732cb775ff7d347ca3141233871b384c74e3a8ec5d10fad19dce1932b008bbc8a07a28bf51a372953f963db14db89d59bf8 6.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162
  1. /**
  2. * @since v17.0.0
  3. * @experimental
  4. */
  5. declare module "readline/promises" {
  6. import { Abortable } from "node:events";
  7. import {
  8. CompleterResult,
  9. Direction,
  10. Interface as _Interface,
  11. ReadLineOptions as _ReadLineOptions,
  12. } from "node:readline";
  13. /**
  14. * Instances of the `readlinePromises.Interface` class are constructed using the `readlinePromises.createInterface()` method. Every instance is associated with a
  15. * single `input` `Readable` stream and a single `output` `Writable` stream.
  16. * The `output` stream is used to print prompts for user input that arrives on,
  17. * and is read from, the `input` stream.
  18. * @since v17.0.0
  19. */
  20. class Interface extends _Interface {
  21. /**
  22. * The `rl.question()` method displays the `query` by writing it to the `output`,
  23. * waits for user input to be provided on `input`, then invokes the `callback` function passing the provided input as the first argument.
  24. *
  25. * When called, `rl.question()` will resume the `input` stream if it has been
  26. * paused.
  27. *
  28. * If the `Interface` was created with `output` set to `null` or `undefined` the `query` is not written.
  29. *
  30. * If the question is called after `rl.close()`, it returns a rejected promise.
  31. *
  32. * Example usage:
  33. *
  34. * ```js
  35. * const answer = await rl.question('What is your favorite food? ');
  36. * console.log(`Oh, so your favorite food is ${answer}`);
  37. * ```
  38. *
  39. * Using an `AbortSignal` to cancel a question.
  40. *
  41. * ```js
  42. * const signal = AbortSignal.timeout(10_000);
  43. *
  44. * signal.addEventListener('abort', () => {
  45. * console.log('The food question timed out');
  46. * }, { once: true });
  47. *
  48. * const answer = await rl.question('What is your favorite food? ', { signal });
  49. * console.log(`Oh, so your favorite food is ${answer}`);
  50. * ```
  51. * @since v17.0.0
  52. * @param query A statement or query to write to `output`, prepended to the prompt.
  53. * @return A promise that is fulfilled with the user's input in response to the `query`.
  54. */
  55. question(query: string): Promise<string>;
  56. question(query: string, options: Abortable): Promise<string>;
  57. }
  58. /**
  59. * @since v17.0.0
  60. */
  61. class Readline {
  62. /**
  63. * @param stream A TTY stream.
  64. */
  65. constructor(
  66. stream: NodeJS.WritableStream,
  67. options?: {
  68. autoCommit?: boolean;
  69. },
  70. );
  71. /**
  72. * The `rl.clearLine()` method adds to the internal list of pending action an
  73. * action that clears current line of the associated `stream` in a specified
  74. * direction identified by `dir`.
  75. * Call `rl.commit()` to see the effect of this method, unless `autoCommit: true` was passed to the constructor.
  76. * @since v17.0.0
  77. * @return this
  78. */
  79. clearLine(dir: Direction): this;
  80. /**
  81. * The `rl.clearScreenDown()` method adds to the internal list of pending action an
  82. * action that clears the associated stream from the current position of the
  83. * cursor down.
  84. * Call `rl.commit()` to see the effect of this method, unless `autoCommit: true` was passed to the constructor.
  85. * @since v17.0.0
  86. * @return this
  87. */
  88. clearScreenDown(): this;
  89. /**
  90. * The `rl.commit()` method sends all the pending actions to the associated `stream` and clears the internal list of pending actions.
  91. * @since v17.0.0
  92. */
  93. commit(): Promise<void>;
  94. /**
  95. * The `rl.cursorTo()` method adds to the internal list of pending action an action
  96. * that moves cursor to the specified position in the associated `stream`.
  97. * Call `rl.commit()` to see the effect of this method, unless `autoCommit: true` was passed to the constructor.
  98. * @since v17.0.0
  99. * @return this
  100. */
  101. cursorTo(x: number, y?: number): this;
  102. /**
  103. * The `rl.moveCursor()` method adds to the internal list of pending action an
  104. * action that moves the cursor _relative_ to its current position in the
  105. * associated `stream`.
  106. * Call `rl.commit()` to see the effect of this method, unless `autoCommit: true` was passed to the constructor.
  107. * @since v17.0.0
  108. * @return this
  109. */
  110. moveCursor(dx: number, dy: number): this;
  111. /**
  112. * The `rl.rollback` methods clears the internal list of pending actions without
  113. * sending it to the associated `stream`.
  114. * @since v17.0.0
  115. * @return this
  116. */
  117. rollback(): this;
  118. }
  119. type Completer = (line: string) => CompleterResult | Promise<CompleterResult>;
  120. interface ReadLineOptions extends Omit<_ReadLineOptions, "completer"> {
  121. /**
  122. * An optional function used for Tab autocompletion.
  123. */
  124. completer?: Completer | undefined;
  125. }
  126. /**
  127. * The `readlinePromises.createInterface()` method creates a new `readlinePromises.Interface` instance.
  128. *
  129. * ```js
  130. * import readlinePromises from 'node:readline/promises';
  131. * const rl = readlinePromises.createInterface({
  132. * input: process.stdin,
  133. * output: process.stdout,
  134. * });
  135. * ```
  136. *
  137. * Once the `readlinePromises.Interface` instance is created, the most common case
  138. * is to listen for the `'line'` event:
  139. *
  140. * ```js
  141. * rl.on('line', (line) => {
  142. * console.log(`Received: ${line}`);
  143. * });
  144. * ```
  145. *
  146. * If `terminal` is `true` for this instance then the `output` stream will get
  147. * the best compatibility if it defines an `output.columns` property and emits
  148. * a `'resize'` event on the `output` if or when the columns ever change
  149. * (`process.stdout` does this automatically when it is a TTY).
  150. * @since v17.0.0
  151. */
  152. function createInterface(
  153. input: NodeJS.ReadableStream,
  154. output?: NodeJS.WritableStream,
  155. completer?: Completer,
  156. terminal?: boolean,
  157. ): Interface;
  158. function createInterface(options: ReadLineOptions): Interface;
  159. }
  160. declare module "node:readline/promises" {
  161. export * from "readline/promises";
  162. }