@types/node 18.11.5 → 20.2.5

node/readline/promises.d.ts

@@ -1,23 +1,28 @@
 /**
- * The `readline/promise` module provides an API for reading lines of input from a Readable stream one line at a time.
- *
- * @see [source](https://github.com/nodejs/node/blob/v18.0.0/lib/readline/promises.js)
  * @since v17.0.0
+ * @experimental
  */
 declare module 'readline/promises' {
     import { Interface as _Interface, ReadLineOptions, Completer, AsyncCompleter, Direction } from 'node:readline';
     import { Abortable } from 'node:events';
-
+    /**
+     * Instances of the `readlinePromises.Interface` class are constructed using the`readlinePromises.createInterface()` method. Every instance is associated with a
+     * single `input` `Readable` stream and a single `output` `Writable` stream.
+     * The `output` stream is used to print prompts for user input that arrives on,
+     * and is read from, the `input` stream.
+     * @since v17.0.0
+     */
     class Interface extends _Interface {
         /**
-         * The rl.question() method displays the query by writing it to the output, waits for user input to be provided on input,
-         * then invokes the callback function passing the provided input as the first argument.
+         * The `rl.question()` method displays the `query` by writing it to the `output`,
+         * waits for user input to be provided on `input`, then invokes the `callback`function passing the provided input as the first argument.
          *
-         * When called, rl.question() will resume the input stream if it has been paused.
+         * When called, `rl.question()` will resume the `input` stream if it has been
+         * paused.
          *
-         * If the readlinePromises.Interface was created with output set to null or undefined the query is not written.
+         * If the `Interface` was created with `output` set to `null` or`undefined` the `query` is not written.
          *
-         * If the question is called after rl.close(), it returns a rejected promise.
+         * If the question is called after `rl.close()`, it returns a rejected promise.
          *
          * Example usage:
          *
@@ -26,7 +31,7 @@ declare module 'readline/promises' {
          * console.log(`Oh, so your favorite food is ${answer}`);
          * ```
          *
-         * Using an AbortSignal to cancel a question.
+         * Using an `AbortSignal` to cancel a question.
          *
          * ```js
          * const signal = AbortSignal.timeout(10_000);
@@ -38,61 +43,87 @@ declare module 'readline/promises' {
          * const answer = await rl.question('What is your favorite food? ', { signal });
          * console.log(`Oh, so your favorite food is ${answer}`);
          * ```
-         *
          * @since v17.0.0
-         * @param query A statement or query to write to output, prepended to the prompt.
+         * @param query A statement or query to write to `output`, prepended to the prompt.
+         * @return A promise that is fulfilled with the user's input in response to the `query`.
          */
         question(query: string): Promise<string>;
         question(query: string, options: Abortable): Promise<string>;
     }
-
+    /**
+     * @since v17.0.0
+     */
     class Readline {
         /**
          * @param stream A TTY stream.
          */
-        constructor(stream: NodeJS.WritableStream, options?: { autoCommit?: boolean });
+        constructor(
+            stream: NodeJS.WritableStream,
+            options?: {
+                autoCommit?: boolean;
+            }
+        );
         /**
-         * The `rl.clearLine()` method adds to the internal list of pending action an action that clears current line of the associated `stream` in a specified direction identified by `dir`.
-         * Call `rl.commit()` to see the effect of this method, unless `autoCommit: true` was passed to the constructor.
+         * The `rl.clearLine()` method adds to the internal list of pending action an
+         * action that clears current line of the associated `stream` in a specified
+         * direction identified by `dir`.
+         * Call `rl.commit()` to see the effect of this method, unless `autoCommit: true`was passed to the constructor.
+         * @since v17.0.0
+         * @return this
          */
         clearLine(dir: Direction): this;
         /**
-         * The `rl.clearScreenDown()` method adds to the internal list of pending action an action that clears the associated `stream` from the current position of the cursor down.
-         * Call `rl.commit()` to see the effect of this method, unless `autoCommit: true` was passed to the constructor.
+         * The `rl.clearScreenDown()` method adds to the internal list of pending action an
+         * action that clears the associated stream from the current position of the
+         * cursor down.
+         * Call `rl.commit()` to see the effect of this method, unless `autoCommit: true`was passed to the constructor.
+         * @since v17.0.0
+         * @return this
          */
         clearScreenDown(): this;
         /**
-         * The `rl.commit()` method sends all the pending actions to the associated `stream` and clears the internal list of pending actions.
+         * The `rl.commit()` method sends all the pending actions to the associated`stream` and clears the internal list of pending actions.
+         * @since v17.0.0
          */
         commit(): Promise<void>;
         /**
-         * The `rl.cursorTo()` method adds to the internal list of pending action an action that moves cursor to the specified position in the associated `stream`.
-         * Call `rl.commit()` to see the effect of this method, unless `autoCommit: true` was passed to the constructor.
+         * The `rl.cursorTo()` method adds to the internal list of pending action an action
+         * that moves cursor to the specified position in the associated `stream`.
+         * Call `rl.commit()` to see the effect of this method, unless `autoCommit: true`was passed to the constructor.
+         * @since v17.0.0
+         * @return this
          */
         cursorTo(x: number, y?: number): this;
         /**
-         * The `rl.moveCursor()` method adds to the internal list of pending action an action that moves the cursor relative to its current position in the associated `stream`.
-         * Call `rl.commit()` to see the effect of this method, unless autoCommit: true was passed to the constructor.
+         * The `rl.moveCursor()` method adds to the internal list of pending action an
+         * action that moves the cursor _relative_ to its current position in the
+         * associated `stream`.
+         * Call `rl.commit()` to see the effect of this method, unless `autoCommit: true`was passed to the constructor.
+         * @since v17.0.0
+         * @return this
          */
         moveCursor(dx: number, dy: number): this;
         /**
-         * The `rl.rollback()` method clears the internal list of pending actions without sending it to the associated `stream`.
+         * The `rl.rollback` methods clears the internal list of pending actions without
+         * sending it to the associated `stream`.
+         * @since v17.0.0
+         * @return this
          */
         rollback(): this;
     }
-
     /**
-     * The `readlinePromises.createInterface()` method creates a new `readlinePromises.Interface` instance.
+     * The `readlinePromises.createInterface()` method creates a new `readlinePromises.Interface`instance.
      *
      * ```js
      * const readlinePromises = require('node:readline/promises');
      * const rl = readlinePromises.createInterface({
      *   input: process.stdin,
-     *   output: process.stdout
+     *   output: process.stdout,
      * });
      * ```
      *
-     * Once the `readlinePromises.Interface` instance is created, the most common case is to listen for the `'line'` event:
+     * Once the `readlinePromises.Interface` instance is created, the most common case
+     * is to listen for the `'line'` event:
      *
      * ```js
      * rl.on('line', (line) => {
@@ -100,42 +131,13 @@ declare module 'readline/promises' {
      * });
      * ```
      *
-     * If `terminal` is `true` for this instance then the `output` stream will get the best compatibility if it defines an `output.columns` property,
-     * and emits a `'resize'` event on the `output`, if or when the columns ever change (`process.stdout` does this automatically when it is a TTY).
-     *
-     * ## Use of the `completer` function
-     *
-     * The `completer` function takes the current line entered by the user as an argument, and returns an `Array` with 2 entries:
-     *
-     * - An Array with matching entries for the completion.
-     * - The substring that was used for the matching.
-     *
-     * For instance: `[[substr1, substr2, ...], originalsubstring]`.
-     *
-     * ```js
-     * function completer(line) {
-     *   const completions = '.help .error .exit .quit .q'.split(' ');
-     *   const hits = completions.filter((c) => c.startsWith(line));
-     *   // Show all completions if none found
-     *   return [hits.length ? hits : completions, line];
-     * }
-     * ```
-     *
-     * The `completer` function can also returns a `Promise`, or be asynchronous:
-     *
-     * ```js
-     * async function completer(linePartial) {
-     *   await someAsyncWork();
-     *   return [['123'], linePartial];
-     * }
-     * ```
+     * If `terminal` is `true` for this instance then the `output` stream will get
+     * the best compatibility if it defines an `output.columns` property and emits
+     * a `'resize'` event on the `output` if or when the columns ever change
+     * (`process.stdout` does this automatically when it is a TTY).
+     * @since v17.0.0
      */
-    function createInterface(
-        input: NodeJS.ReadableStream,
-        output?: NodeJS.WritableStream,
-        completer?: Completer | AsyncCompleter,
-        terminal?: boolean,
-    ): Interface;
+    function createInterface(input: NodeJS.ReadableStream, output?: NodeJS.WritableStream, completer?: Completer | AsyncCompleter, terminal?: boolean): Interface;
     function createInterface(options: ReadLineOptions): Interface;
 }
 declare module 'node:readline/promises' {

node/readline.d.ts

@@ -1,5 +1,5 @@
 /**
- * The `readline` module provides an interface for reading data from a `Readable` stream (such as `process.stdin`) one line at a time.
+ * The `node:readline` module provides an interface for reading data from a `Readable` stream (such as `process.stdin`) one line at a time.
  *
  * To use the promise-based APIs:
  *
@@ -13,7 +13,7 @@
  * import * as readline from 'node:readline';
  * ```
  *
- * The following simple example illustrates the basic use of the `readline` module.
+ * The following simple example illustrates the basic use of the `node:readline`module.
  *
  * ```js
  * import * as readline from 'node:readline/promises';
@@ -30,12 +30,11 @@
  *
  * 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 be
  * received on the `input` stream.
- * @see [source](https://github.com/nodejs/node/blob/v18.0.0/lib/readline.js)
+ * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/readline.js)
  */
 declare module 'readline' {
     import { Abortable, EventEmitter } from 'node:events';
     import * as promises from 'node:readline/promises';
-
     export { promises };
     export interface Key {
         sequence?: string | undefined;
@@ -74,7 +73,7 @@ declare module 'readline' {
          * const showResults = debounce(() => {
          *   console.log(
          *     '\n',
-         *     values.filter((val) => val.startsWith(rl.line)).join(' ')
+         *     values.filter((val) => val.startsWith(rl.line)).join(' '),
          *   );
          * }, 300);
          * process.stdin.on('keypress', (c, k) => {
@@ -100,7 +99,7 @@ declare module 'readline' {
          * > Instances of the `readline.Interface` class are constructed using the
          * > `readline.createInterface()` method.
          *
-         * @see https://nodejs.org/dist/latest-v10.x/docs/api/readline.html#readline_class_interface
+         * @see https://nodejs.org/dist/latest-v20.x/docs/api/readline.html#class-interfaceconstructor
          */
         protected constructor(input: NodeJS.ReadableStream, output?: NodeJS.WritableStream, completer?: Completer | AsyncCompleter, terminal?: boolean);
         /**
@@ -109,12 +108,12 @@ declare module 'readline' {
          * > Instances of the `readline.Interface` class are constructed using the
          * > `readline.createInterface()` method.
          *
-         * @see https://nodejs.org/dist/latest-v10.x/docs/api/readline.html#readline_class_interface
+         * @see https://nodejs.org/dist/latest-v20.x/docs/api/readline.html#class-interfaceconstructor
          */
         protected constructor(options: ReadLineOptions);
         /**
          * The `rl.getPrompt()` method returns the current prompt used by `rl.prompt()`.
-         * @since v15.3.0
+         * @since v15.3.0, v14.17.0
          * @return the current prompt string
          */
         getPrompt(): string;
@@ -124,13 +123,13 @@ declare module 'readline' {
          */
         setPrompt(prompt: string): void;
         /**
-         * The `rl.prompt()` method writes the `readline.Interface` instances configured`prompt` to a new line in `output` in order to provide a user with a new
+         * The `rl.prompt()` method writes the `Interface` instances configured`prompt` to a new line in `output` in order to provide a user with a new
          * location at which to provide input.
          *
          * When called, `rl.prompt()` will resume the `input` stream if it has been
          * paused.
          *
-         * If the `readline.Interface` was created with `output` set to `null` or`undefined` the prompt is not written.
+         * If the `Interface` was created with `output` set to `null` or`undefined` the prompt is not written.
          * @since v0.1.98
          * @param preserveCursor If `true`, prevents the cursor placement from being reset to `0`.
          */
@@ -142,12 +141,14 @@ declare module 'readline' {
          * When called, `rl.question()` will resume the `input` stream if it has been
          * paused.
          *
-         * If the `readline.Interface` was created with `output` set to `null` or`undefined` the `query` is not written.
+         * If the `Interface` was created with `output` set to `null` or`undefined` the `query` is not written.
          *
          * The `callback` function passed to `rl.question()` does not follow the typical
          * pattern of accepting an `Error` object or `null` as the first argument.
          * The `callback` is called with the provided answer as the only argument.
          *
+         * An error will be thrown if calling `rl.question()` after `rl.close()`.
+         *
          * Example usage:
          *
          * ```js
@@ -172,25 +173,6 @@ declare module 'readline' {
          *
          * setTimeout(() => ac.abort(), 10000);
          * ```
-         *
-         * If this method is invoked as it's util.promisify()ed version, it returns a
-         * Promise that fulfills with the answer. If the question is canceled using
-         * an `AbortController` it will reject with an `AbortError`.
-         *
-         * ```js
-         * const util = require('util');
-         * const question = util.promisify(rl.question).bind(rl);
-         *
-         * async function questionExample() {
-         *   try {
-         *     const answer = await question('What is you favorite food? ');
-         *     console.log(`Oh, so your favorite food is ${answer}`);
-         *   } catch (err) {
-         *     console.error('Question rejected', err);
-         *   }
-         * }
-         * questionExample();
-         * ```
          * @since v0.3.3
          * @param query A statement or query to write to `output`, prepended to the prompt.
          * @param callback A callback function that is invoked with the user's input in response to the `query`.
@@ -201,7 +183,7 @@ declare module 'readline' {
          * The `rl.pause()` method pauses the `input` stream, allowing it to be resumed
          * later if necessary.
          *
-         * Calling `rl.pause()` does not immediately pause other events (including`'line'`) from being emitted by the `readline.Interface` instance.
+         * Calling `rl.pause()` does not immediately pause other events (including`'line'`) from being emitted by the `Interface` instance.
          * @since v0.3.4
          */
         pause(): this;
@@ -211,12 +193,12 @@ declare module 'readline' {
          */
         resume(): this;
         /**
-         * The `rl.close()` method closes the `readline.Interface` instance and
+         * The `rl.close()` method closes the `Interface` instance and
          * relinquishes control over the `input` and `output` streams. When called,
          * the `'close'` event will be emitted.
          *
          * Calling `rl.close()` does not immediately stop other events (including `'line'`)
-         * from being emitted by the `readline.Interface` instance.
+         * from being emitted by the `Interface` instance.
          * @since v0.1.98
          */
         close(): void;
@@ -231,7 +213,7 @@ declare module 'readline' {
          * When called, `rl.write()` will resume the `input` stream if it has been
          * paused.
          *
-         * If the `readline.Interface` was created with `output` set to `null` or`undefined` the `data` and `key` are not written.
+         * If the `Interface` was created with `output` set to `null` or`undefined` the `data` and `key` are not written.
          *
          * ```js
          * rl.write('Delete this!');
@@ -351,10 +333,10 @@ declare module 'readline' {
      * The `readline.createInterface()` method creates a new `readline.Interface`instance.
      *
      * ```js
-     * const readline = require('readline');
+     * const readline = require('node:readline');
      * const rl = readline.createInterface({
      *   input: process.stdin,
-     *   output: process.stdout
+     *   output: process.stdout,
      * });
      * ```
      *
@@ -373,14 +355,8 @@ declare module 'readline' {
      * (`process.stdout` does this automatically when it is a TTY).
      *
      * When creating a `readline.Interface` using `stdin` as input, the program
-     * will not terminate until it receives `EOF` (Ctrl+D on
-     * Linux/macOS, Ctrl+Z followed by Return on
-     * Windows).
-     * If you want your application to exit without waiting for user input, you can `unref()` the standard input stream:
-     *
-     * ```js
-     * process.stdin.unref();
-     * ```
+     * will not terminate until it receives an [EOF character](https://en.wikipedia.org/wiki/End-of-file#EOF_character). To exit without
+     * waiting for user input, call `process.stdin.unref()`.
      * @since v0.1.98
      */
     export function createInterface(input: NodeJS.ReadableStream, output?: NodeJS.WritableStream, completer?: Completer | AsyncCompleter, terminal?: boolean): Interface;
@@ -408,11 +384,11 @@ declare module 'readline' {
      * implement a small command-line interface:
      *
      * ```js
-     * const readline = require('readline');
+     * const readline = require('node:readline');
      * const rl = readline.createInterface({
      *   input: process.stdin,
      *   output: process.stdout,
-     *   prompt: 'OHAI> '
+     *   prompt: 'OHAI> ',
      * });
      *
      * rl.prompt();
@@ -440,15 +416,15 @@ declare module 'readline' {
      * well as a `for await...of` loop:
      *
      * ```js
-     * const fs = require('fs');
-     * const readline = require('readline');
+     * const fs = require('node:fs');
+     * const readline = require('node:readline');
      *
      * async function processLineByLine() {
      *   const fileStream = fs.createReadStream('input.txt');
      *
      *   const rl = readline.createInterface({
      *     input: fileStream,
-     *     crlfDelay: Infinity
+     *     crlfDelay: Infinity,
      *   });
      *   // Note: we use the crlfDelay option to recognize all instances of CR LF
      *   // ('\r\n') in input.txt as a single line break.
@@ -465,12 +441,12 @@ declare module 'readline' {
      * Alternatively, one could use the `'line'` event:
      *
      * ```js
-     * const fs = require('fs');
-     * const readline = require('readline');
+     * const fs = require('node:fs');
+     * const readline = require('node:readline');
      *
      * const rl = readline.createInterface({
      *   input: fs.createReadStream('sample.txt'),
-     *   crlfDelay: Infinity
+     *   crlfDelay: Infinity,
      * });
      *
      * rl.on('line', (line) => {
@@ -481,15 +457,15 @@ declare module 'readline' {
      * 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:
      *
      * ```js
-     * const { once } = require('events');
-     * const { createReadStream } = require('fs');
-     * const { createInterface } = require('readline');
+     * const { once } = require('node:events');
+     * const { createReadStream } = require('node:fs');
+     * const { createInterface } = require('node:readline');
      *
      * (async function processLineByLine() {
      *   try {
      *     const rl = createInterface({
      *       input: createReadStream('big-file.txt'),
-     *       crlfDelay: Infinity
+     *       crlfDelay: Infinity,
      *     });
      *
      *     rl.on('line', (line) => {
@@ -539,109 +515,6 @@ declare module 'readline' {
     /**
      * The `readline.moveCursor()` method moves the cursor _relative_ to its current
      * position in a given `TTY` `stream`.
-     *
-     * ## Example: Tiny CLI
-     *
-     * The following example illustrates the use of `readline.Interface` class to
-     * implement a small command-line interface:
-     *
-     * ```js
-     * const readline = require('readline');
-     * const rl = readline.createInterface({
-     *   input: process.stdin,
-     *   output: process.stdout,
-     *   prompt: 'OHAI> '
-     * });
-     *
-     * rl.prompt();
-     *
-     * rl.on('line', (line) => {
-     *   switch (line.trim()) {
-     *     case 'hello':
-     *       console.log('world!');
-     *       break;
-     *     default:
-     *       console.log(`Say what? I might have heard '${line.trim()}'`);
-     *       break;
-     *   }
-     *   rl.prompt();
-     * }).on('close', () => {
-     *   console.log('Have a great day!');
-     *   process.exit(0);
-     * });
-     * ```
-     *
-     * ## Example: Read file stream line-by-Line
-     *
-     * A common use case for `readline` is to consume an input file one line at a
-     * time. The easiest way to do so is leveraging the `fs.ReadStream` API as
-     * well as a `for await...of` loop:
-     *
-     * ```js
-     * const fs = require('fs');
-     * const readline = require('readline');
-     *
-     * async function processLineByLine() {
-     *   const fileStream = fs.createReadStream('input.txt');
-     *
-     *   const rl = readline.createInterface({
-     *     input: fileStream,
-     *     crlfDelay: Infinity
-     *   });
-     *   // Note: we use the crlfDelay option to recognize all instances of CR LF
-     *   // ('\r\n') in input.txt as a single line break.
-     *
-     *   for await (const line of rl) {
-     *     // Each line in input.txt will be successively available here as `line`.
-     *     console.log(`Line from file: ${line}`);
-     *   }
-     * }
-     *
-     * processLineByLine();
-     * ```
-     *
-     * Alternatively, one could use the `'line'` event:
-     *
-     * ```js
-     * const fs = require('fs');
-     * const readline = require('readline');
-     *
-     * const rl = readline.createInterface({
-     *   input: fs.createReadStream('sample.txt'),
-     *   crlfDelay: Infinity
-     * });
-     *
-     * rl.on('line', (line) => {
-     *   console.log(`Line from file: ${line}`);
-     * });
-     * ```
-     *
-     * 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:
-     *
-     * ```js
-     * const { once } = require('events');
-     * const { createReadStream } = require('fs');
-     * const { createInterface } = require('readline');
-     *
-     * (async function processLineByLine() {
-     *   try {
-     *     const rl = createInterface({
-     *       input: createReadStream('big-file.txt'),
-     *       crlfDelay: Infinity
-     *     });
-     *
-     *     rl.on('line', (line) => {
-     *       // Process the line.
-     *     });
-     *
-     *     await once(rl, 'close');
-     *
-     *     console.log('File processed.');
-     *   } catch (err) {
-     *     console.error(err);
-     *   }
-     * })();
-     * ```
      * @since v0.7.7
      * @param callback Invoked once the operation completes.
      * @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`.