@types/node 16.4.1 → 16.4.5

node/repl.d.ts

@@ -1,8 +1,17 @@
+/**
+ * The `repl` module provides a Read-Eval-Print-Loop (REPL) implementation that
+ * is available both as a standalone program or includible in other applications.
+ * It can be accessed using:
+ *
+ * ```js
+ * const repl = require('repl');
+ * ```
+ * @see [source](https://github.com/nodejs/node/blob/v16.4.2/lib/repl.js)
+ */
 declare module 'repl' {
     import { Interface, Completer, AsyncCompleter } from 'node:readline';
     import { Context } from 'node:vm';
     import { InspectOptions } from 'node:util';
-
     interface ReplOptions {
         /**
          * The input prompt to display.
@@ -90,18 +99,16 @@ declare module 'repl' {
          */
         breakEvalOnSigint?: boolean | undefined;
     }
-
     type REPLEval = (this: REPLServer, evalCmd: string, context: Context, file: string, cb: (err: Error | null, result: any) => void) => void;
     type REPLWriter = (this: REPLServer, obj: any) => string;
-
     /**
      * This is the default "writer" value, if none is passed in the REPL options,
      * and it can be overridden by custom print functions.
      */
-    const writer: REPLWriter & { options: InspectOptions };
-
+    const writer: REPLWriter & {
+        options: InspectOptions;
+    };
     type REPLCommandAction = (this: REPLServer, text: string) => void;
-
     interface REPLCommand {
         /**
          * Help text to be displayed when `.help` is entered.
@@ -112,22 +119,19 @@ declare module 'repl' {
          */
         action: REPLCommandAction;
     }
-
     /**
-     * Provides a customizable Read-Eval-Print-Loop (REPL).
+     * Instances of `repl.REPLServer` are created using the {@link start} method
+     * or directly using the JavaScript `new` keyword.
      *
-     * Instances of `repl.REPLServer` will accept individual lines of user input, evaluate those
-     * according to a user-defined evaluation function, then output the result. Input and output
-     * may be from `stdin` and `stdout`, respectively, or may be connected to any Node.js `stream`.
+     * ```js
+     * const repl = require('repl');
      *
-     * Instances of `repl.REPLServer` support automatic completion of inputs, simplistic Emacs-style
-     * line editing, multi-line inputs, ANSI-styled output, saving and restoring current REPL session
-     * state, error recovery, and customizable evaluation functions.
+     * const options = { useColors: true };
      *
-     * Instances of `repl.REPLServer` are created using the `repl.start()` method and _should not_
-     * be created directly using the JavaScript `new` keyword.
-     *
-     * @see https://nodejs.org/dist/latest-v10.x/docs/api/repl.html#repl_repl
+     * const firstInstance = repl.start(options);
+     * const secondInstance = new repl.REPLServer(options);
+     * ```
+     * @since v0.1.91
      */
     class REPLServer extends Interface {
         /**
@@ -228,7 +232,6 @@ declare module 'repl' {
          *    prefacing every repl statement with `'use strict'`.
          */
         readonly replMode: typeof REPL_MODE_SLOPPY | typeof REPL_MODE_STRICT;
-
         /**
          * NOTE: According to the documentation:
          *
@@ -240,49 +243,76 @@ declare module 'repl' {
          * @see https://nodejs.org/dist/latest-v10.x/docs/api/repl.html#repl_class_replserver
          */
         private constructor();
-
         /**
-         * Used to add new `.`-prefixed commands to the REPL instance. Such commands are invoked
-         * by typing a `.` followed by the `keyword`.
+         * The `replServer.defineCommand()` method is used to add new `.`\-prefixed commands
+         * to the REPL instance. Such commands are invoked by typing a `.` followed by the`keyword`. The `cmd` is either a `Function` or an `Object` with the following
+         * properties:
          *
-         * @param keyword The command keyword (_without_ a leading `.` character).
-         * @param cmd The function to invoke when the command is processed.
+         * The following example shows two new commands added to the REPL instance:
+         *
+         * ```js
+         * const repl = require('repl');
+         *
+         * const replServer = repl.start({ prompt: '> ' });
+         * replServer.defineCommand('sayhello', {
+         *   help: 'Say hello',
+         *   action(name) {
+         *     this.clearBufferedCommand();
+         *     console.log(`Hello, ${name}!`);
+         *     this.displayPrompt();
+         *   }
+         * });
+         * replServer.defineCommand('saybye', function saybye() {
+         *   console.log('Goodbye!');
+         *   this.close();
+         * });
+         * ```
+         *
+         * The new commands can then be used from within the REPL instance:
          *
-         * @see https://nodejs.org/dist/latest-v10.x/docs/api/repl.html#repl_replserver_definecommand_keyword_cmd
+         * ```console
+         * > .sayhello Node.js User
+         * Hello, Node.js User!
+         * > .saybye
+         * Goodbye!
+         * ```
+         * @since v0.3.0
+         * @param keyword The command keyword (*without* a leading `.` character).
+         * @param cmd The function to invoke when the command is processed.
          */
         defineCommand(keyword: string, cmd: REPLCommandAction | REPLCommand): void;
         /**
-         * Readies the REPL instance for input from the user, printing the configured `prompt` to a
-         * new line in the `output` and resuming the `input` to accept new input.
+         * The `replServer.displayPrompt()` method readies the REPL instance for input
+         * from the user, printing the configured `prompt` to a new line in the `output`and resuming the `input` to accept new input.
          *
-         * When multi-line input is being entered, an ellipsis is printed rather than the 'prompt'.
+         * When multi-line input is being entered, an ellipsis is printed rather than the
+         * 'prompt'.
          *
-         * This method is primarily intended to be called from within the action function for
-         * commands registered using the `replServer.defineCommand()` method.
+         * When `preserveCursor` is `true`, the cursor placement will not be reset to `0`.
          *
-         * @param preserveCursor When `true`, the cursor placement will not be reset to `0`.
+         * The `replServer.displayPrompt` method is primarily intended to be called from
+         * within the action function for commands registered using the`replServer.defineCommand()` method.
+         * @since v0.1.91
          */
         displayPrompt(preserveCursor?: boolean): void;
         /**
-         * Clears any command that has been buffered but not yet executed.
-         *
-         * This method is primarily intended to be called from within the action function for
-         * commands registered using the `replServer.defineCommand()` method.
-         *
+         * The `replServer.clearBufferedCommand()` method clears any command that has been
+         * buffered but not yet executed. This method is primarily intended to be
+         * called from within the action function for commands registered using the`replServer.defineCommand()` method.
          * @since v9.0.0
          */
         clearBufferedCommand(): void;
-
         /**
          * Initializes a history log file for the REPL instance. When executing the
-         * Node.js binary and using the command line REPL, a history file is initialized
+         * Node.js binary and using the command-line REPL, a history file is initialized
          * by default. However, this is not the case when creating a REPL
          * programmatically. Use this method to initialize a history log file when working
          * with REPL instances programmatically.
-         * @param path The path to the history file
+         * @since v11.10.0
+         * @param historyPath the path to the history file
+         * @param callback called when history writes are ready or upon error
          */
-        setupHistory(path: string, cb: (err: Error | null, repl: this) => void): void;
-
+        setupHistory(path: string, callback: (err: Error | null, repl: this) => void): void;
         /**
          * events.EventEmitter
          * 1. close - inherited from `readline.Interface`
@@ -295,93 +325,90 @@ declare module 'repl' {
          * 8. exit
          * 9. reset
          */
-
         addListener(event: string, listener: (...args: any[]) => void): this;
-        addListener(event: "close", listener: () => void): this;
-        addListener(event: "line", listener: (input: string) => void): this;
-        addListener(event: "pause", listener: () => void): this;
-        addListener(event: "resume", listener: () => void): this;
-        addListener(event: "SIGCONT", listener: () => void): this;
-        addListener(event: "SIGINT", listener: () => void): this;
-        addListener(event: "SIGTSTP", listener: () => void): this;
-        addListener(event: "exit", listener: () => void): this;
-        addListener(event: "reset", listener: (context: Context) => void): this;
-
+        addListener(event: 'close', listener: () => void): this;
+        addListener(event: 'line', listener: (input: string) => void): this;
+        addListener(event: 'pause', listener: () => void): this;
+        addListener(event: 'resume', listener: () => void): this;
+        addListener(event: 'SIGCONT', listener: () => void): this;
+        addListener(event: 'SIGINT', listener: () => void): this;
+        addListener(event: 'SIGTSTP', listener: () => void): this;
+        addListener(event: 'exit', listener: () => void): this;
+        addListener(event: 'reset', listener: (context: Context) => void): this;
         emit(event: string | symbol, ...args: any[]): boolean;
-        emit(event: "close"): boolean;
-        emit(event: "line", input: string): boolean;
-        emit(event: "pause"): boolean;
-        emit(event: "resume"): boolean;
-        emit(event: "SIGCONT"): boolean;
-        emit(event: "SIGINT"): boolean;
-        emit(event: "SIGTSTP"): boolean;
-        emit(event: "exit"): boolean;
-        emit(event: "reset", context: Context): boolean;
-
+        emit(event: 'close'): boolean;
+        emit(event: 'line', input: string): boolean;
+        emit(event: 'pause'): boolean;
+        emit(event: 'resume'): boolean;
+        emit(event: 'SIGCONT'): boolean;
+        emit(event: 'SIGINT'): boolean;
+        emit(event: 'SIGTSTP'): boolean;
+        emit(event: 'exit'): boolean;
+        emit(event: 'reset', context: Context): boolean;
         on(event: string, listener: (...args: any[]) => void): this;
-        on(event: "close", listener: () => void): this;
-        on(event: "line", listener: (input: string) => void): this;
-        on(event: "pause", listener: () => void): this;
-        on(event: "resume", listener: () => void): this;
-        on(event: "SIGCONT", listener: () => void): this;
-        on(event: "SIGINT", listener: () => void): this;
-        on(event: "SIGTSTP", listener: () => void): this;
-        on(event: "exit", listener: () => void): this;
-        on(event: "reset", listener: (context: Context) => void): this;
-
+        on(event: 'close', listener: () => void): this;
+        on(event: 'line', listener: (input: string) => void): this;
+        on(event: 'pause', listener: () => void): this;
+        on(event: 'resume', listener: () => void): this;
+        on(event: 'SIGCONT', listener: () => void): this;
+        on(event: 'SIGINT', listener: () => void): this;
+        on(event: 'SIGTSTP', listener: () => void): this;
+        on(event: 'exit', listener: () => void): this;
+        on(event: 'reset', listener: (context: Context) => void): this;
         once(event: string, listener: (...args: any[]) => void): this;
-        once(event: "close", listener: () => void): this;
-        once(event: "line", listener: (input: string) => void): this;
-        once(event: "pause", listener: () => void): this;
-        once(event: "resume", listener: () => void): this;
-        once(event: "SIGCONT", listener: () => void): this;
-        once(event: "SIGINT", listener: () => void): this;
-        once(event: "SIGTSTP", listener: () => void): this;
-        once(event: "exit", listener: () => void): this;
-        once(event: "reset", listener: (context: Context) => void): this;
-
+        once(event: 'close', listener: () => void): this;
+        once(event: 'line', listener: (input: string) => void): this;
+        once(event: 'pause', listener: () => void): this;
+        once(event: 'resume', listener: () => void): this;
+        once(event: 'SIGCONT', listener: () => void): this;
+        once(event: 'SIGINT', listener: () => void): this;
+        once(event: 'SIGTSTP', listener: () => void): this;
+        once(event: 'exit', listener: () => void): this;
+        once(event: 'reset', listener: (context: Context) => void): this;
         prependListener(event: string, listener: (...args: any[]) => void): this;
-        prependListener(event: "close", listener: () => void): this;
-        prependListener(event: "line", listener: (input: string) => void): this;
-        prependListener(event: "pause", listener: () => void): this;
-        prependListener(event: "resume", listener: () => void): this;
-        prependListener(event: "SIGCONT", listener: () => void): this;
-        prependListener(event: "SIGINT", listener: () => void): this;
-        prependListener(event: "SIGTSTP", listener: () => void): this;
-        prependListener(event: "exit", listener: () => void): this;
-        prependListener(event: "reset", listener: (context: Context) => void): this;
-
+        prependListener(event: 'close', listener: () => void): this;
+        prependListener(event: 'line', listener: (input: string) => void): this;
+        prependListener(event: 'pause', listener: () => void): this;
+        prependListener(event: 'resume', listener: () => void): this;
+        prependListener(event: 'SIGCONT', listener: () => void): this;
+        prependListener(event: 'SIGINT', listener: () => void): this;
+        prependListener(event: 'SIGTSTP', listener: () => void): this;
+        prependListener(event: 'exit', listener: () => void): this;
+        prependListener(event: 'reset', listener: (context: Context) => void): this;
         prependOnceListener(event: string, listener: (...args: any[]) => void): this;
-        prependOnceListener(event: "close", listener: () => void): this;
-        prependOnceListener(event: "line", listener: (input: string) => void): this;
-        prependOnceListener(event: "pause", listener: () => void): this;
-        prependOnceListener(event: "resume", listener: () => void): this;
-        prependOnceListener(event: "SIGCONT", listener: () => void): this;
-        prependOnceListener(event: "SIGINT", listener: () => void): this;
-        prependOnceListener(event: "SIGTSTP", listener: () => void): this;
-        prependOnceListener(event: "exit", listener: () => void): this;
-        prependOnceListener(event: "reset", listener: (context: Context) => void): this;
+        prependOnceListener(event: 'close', listener: () => void): this;
+        prependOnceListener(event: 'line', listener: (input: string) => void): this;
+        prependOnceListener(event: 'pause', listener: () => void): this;
+        prependOnceListener(event: 'resume', listener: () => void): this;
+        prependOnceListener(event: 'SIGCONT', listener: () => void): this;
+        prependOnceListener(event: 'SIGINT', listener: () => void): this;
+        prependOnceListener(event: 'SIGTSTP', listener: () => void): this;
+        prependOnceListener(event: 'exit', listener: () => void): this;
+        prependOnceListener(event: 'reset', listener: (context: Context) => void): this;
     }
-
     /**
      * A flag passed in the REPL options. Evaluates expressions in sloppy mode.
      */
     const REPL_MODE_SLOPPY: unique symbol;
-
     /**
      * A flag passed in the REPL options. Evaluates expressions in strict mode.
      * This is equivalent to prefacing every repl statement with `'use strict'`.
      */
     const REPL_MODE_STRICT: unique symbol;
-
     /**
-     * Creates and starts a `repl.REPLServer` instance.
+     * The `repl.start()` method creates and starts a {@link REPLServer} instance.
+     *
+     * If `options` is a string, then it specifies the input prompt:
+     *
+     * ```js
+     * const repl = require('repl');
      *
-     * @param options The options for the `REPLServer`. If `options` is a string, then it specifies
-     * the input prompt.
+     * // a Unix style prompt
+     * repl.start('$ ');
+     * ```
+     * @since v0.1.91
      */
     function start(options?: string | ReplOptions): REPLServer;
-
     /**
      * Indicates a recoverable error that a `REPLServer` can use to support multi-line input.
      *
@@ -389,11 +416,9 @@ declare module 'repl' {
      */
     class Recoverable extends SyntaxError {
         err: Error;
-
         constructor(err: Error);
     }
 }
-
 declare module 'node:repl' {
     export * from 'repl';
 }

node/stream/promises.d.ts

@@ -1,71 +1,42 @@
-declare module "stream/promises" {
-    import { FinishedOptions, PipelineSource, PipelineTransform,
-        PipelineDestination, PipelinePromise, PipelineOptions } from "node:stream";
-
+declare module 'stream/promises' {
+    import { FinishedOptions, PipelineSource, PipelineTransform, PipelineDestination, PipelinePromise, PipelineOptions } from 'node:stream';
     function finished(stream: NodeJS.ReadableStream | NodeJS.WritableStream | NodeJS.ReadWriteStream, options?: FinishedOptions): Promise<void>;
-
-    function pipeline<A extends PipelineSource<any>,
-        B extends PipelineDestination<A, any>>(
-        source: A,
-        destination: B,
-        options?: PipelineOptions
-    ): PipelinePromise<B>;
-    function pipeline<A extends PipelineSource<any>,
-        T1 extends PipelineTransform<A, any>,
-        B extends PipelineDestination<T1, any>>(
+    function pipeline<A extends PipelineSource<any>, B extends PipelineDestination<A, any>>(source: A, destination: B, options?: PipelineOptions): PipelinePromise<B>;
+    function pipeline<A extends PipelineSource<any>, T1 extends PipelineTransform<A, any>, B extends PipelineDestination<T1, any>>(
         source: A,
         transform1: T1,
         destination: B,
         options?: PipelineOptions
     ): PipelinePromise<B>;
-    function pipeline<A extends PipelineSource<any>,
-        T1 extends PipelineTransform<A, any>,
-        T2 extends PipelineTransform<T1, any>,
-        B extends PipelineDestination<T2, any>>(
+    function pipeline<A extends PipelineSource<any>, T1 extends PipelineTransform<A, any>, T2 extends PipelineTransform<T1, any>, B extends PipelineDestination<T2, any>>(
         source: A,
         transform1: T1,
         transform2: T2,
         destination: B,
         options?: PipelineOptions
     ): PipelinePromise<B>;
-    function pipeline<A extends PipelineSource<any>,
+    function pipeline<
+        A extends PipelineSource<any>,
         T1 extends PipelineTransform<A, any>,
         T2 extends PipelineTransform<T1, any>,
         T3 extends PipelineTransform<T2, any>,
-        B extends PipelineDestination<T3, any>>(
-        source: A,
-        transform1: T1,
-        transform2: T2,
-        transform3: T3,
-        destination: B,
-        options?: PipelineOptions
-    ): PipelinePromise<B>;
-    function pipeline<A extends PipelineSource<any>,
+        B extends PipelineDestination<T3, any>
+    >(source: A, transform1: T1, transform2: T2, transform3: T3, destination: B, options?: PipelineOptions): PipelinePromise<B>;
+    function pipeline<
+        A extends PipelineSource<any>,
         T1 extends PipelineTransform<A, any>,
         T2 extends PipelineTransform<T1, any>,
         T3 extends PipelineTransform<T2, any>,
         T4 extends PipelineTransform<T3, any>,
-        B extends PipelineDestination<T4, any>>(
-        source: A,
-        transform1: T1,
-        transform2: T2,
-        transform3: T3,
-        transform4: T4,
-        destination: B,
-        options?: PipelineOptions
-    ): PipelinePromise<B>;
-
-    function pipeline(
-        streams: ReadonlyArray<NodeJS.ReadableStream | NodeJS.WritableStream | NodeJS.ReadWriteStream>,
-        options?: PipelineOptions
-    ): Promise<void>;
+        B extends PipelineDestination<T4, any>
+    >(source: A, transform1: T1, transform2: T2, transform3: T3, transform4: T4, destination: B, options?: PipelineOptions): PipelinePromise<B>;
+    function pipeline(streams: ReadonlyArray<NodeJS.ReadableStream | NodeJS.WritableStream | NodeJS.ReadWriteStream>, options?: PipelineOptions): Promise<void>;
     function pipeline(
         stream1: NodeJS.ReadableStream,
         stream2: NodeJS.ReadWriteStream | NodeJS.WritableStream,
-        ...streams: Array<NodeJS.ReadWriteStream | NodeJS.WritableStream | PipelineOptions>,
+        ...streams: Array<NodeJS.ReadWriteStream | NodeJS.WritableStream | PipelineOptions>
     ): Promise<void>;
 }
-
 declare module 'node:stream/promises' {
     export * from 'stream/promises';
 }