@types/node 16.11.39 → 18.11.2

node v16.11/stream.d.ts → node/stream.d.ts

@@ -14,12 +14,14 @@
  *
  * The `stream` module is useful for creating new types of stream instances. It is
  * usually not necessary to use the `stream` module to consume streams.
- * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/stream.js)
+ * @see [source](https://github.com/nodejs/node/blob/v18.0.0/lib/stream.js)
  */
 declare module 'stream' {
     import { EventEmitter, Abortable } from 'node:events';
+    import { Blob as NodeBlob } from "node:buffer";
     import * as streamPromises from 'node:stream/promises';
     import * as streamConsumers from 'node:stream/consumers';
+    import * as streamWeb from 'node:stream/web';
     class internal extends EventEmitter {
         pipe<T extends NodeJS.WritableStream>(
             destination: T,
@@ -52,11 +54,23 @@ declare module 'stream' {
              * A utility method for creating Readable Streams out of iterators.
              */
             static from(iterable: Iterable<any> | AsyncIterable<any>, options?: ReadableOptions): Readable;
+            /**
+             * A utility method for creating a `Readable` from a web `ReadableStream`.
+             * @since v17.0.0
+             * @experimental
+             */
+            static fromWeb(readableStream: streamWeb.ReadableStream, options?: Pick<ReadableOptions, 'encoding' | 'highWaterMark' | 'objectMode' | 'signal'>): Readable;
             /**
              * Returns whether the stream has been read from or cancelled.
              * @since v16.8.0
              */
             static isDisturbed(stream: Readable | NodeJS.ReadableStream): boolean;
+            /**
+             * A utility method for creating a web `ReadableStream` from a `Readable`.
+             * @since v17.0.0
+             * @experimental
+             */
+            static toWeb(streamReadable: Readable): streamWeb.ReadableStream;
             /**
              * Returns whether the stream was destroyed or errored before emitting `'end'`.
              * @since v16.8.0
@@ -71,7 +85,7 @@ declare module 'stream' {
             readable: boolean;
             /**
              * Returns whether `'data'` has been emitted.
-             * @since v16.7.0
+             * @since v16.7.0, v14.18.0
              * @experimental
              */
             readonly readableDidRead: boolean;
@@ -110,16 +124,26 @@ declare module 'stream' {
             readonly readableObjectMode: boolean;
             /**
              * Is `true` after `readable.destroy()` has been called.
-             * @since v8.0.0
+             * @since v18.0.0
              */
             destroyed: boolean;
+            /**
+             * Is true after 'close' has been emitted.
+             * @since v8.0.0
+             */
+            readonly closed: boolean;
+            /**
+             * Returns error if the stream has been destroyed with an error.
+             * @since v18.0.0
+             */
+            readonly errored: Error | null;
             constructor(opts?: ReadableOptions);
             _construct?(callback: (error?: Error | null) => void): void;
             _read(size: number): void;
             /**
-             * The `readable.read()` method pulls some data out of the internal buffer and
-             * returns it. If no data available to be read, `null` is returned. By default,
-             * the data will be returned as a `Buffer` object unless an encoding has been
+             * The `readable.read()` method reads data out of the internal buffer and
+             * returns it. If no data is available to be read, `null` is returned. By default,
+             * the data is returned as a `Buffer` object unless an encoding has been
              * specified using the `readable.setEncoding()` method or the stream is operating
              * in object mode.
              *
@@ -334,7 +358,7 @@ declare module 'stream' {
              *     let chunk;
              *     while (null !== (chunk = stream.read())) {
              *       const str = decoder.write(chunk);
-             *       if (str.match(/\n\n/)) {
+             *       if (str.includes('\n\n')) {
              *         // Found the header boundary.
              *         const split = str.split(/\n\n/);
              *         header += split.shift();
@@ -347,10 +371,10 @@ declare module 'stream' {
              *           stream.unshift(buf);
              *         // Now the body of the message can be read from the stream.
              *         callback(null, header, stream);
-             *       } else {
-             *         // Still reading the header.
-             *         header += str;
+             *         return;
              *       }
+             *       // Still reading the header.
+             *       header += str;
              *     }
              *   }
              * }
@@ -496,6 +520,18 @@ declare module 'stream' {
          * @since v0.9.4
          */
         class Writable extends Stream implements NodeJS.WritableStream {
+            /**
+             * A utility method for creating a `Writable` from a web `WritableStream`.
+             * @since v17.0.0
+             * @experimental
+             */
+            static fromWeb(writableStream: streamWeb.WritableStream, options?: Pick<WritableOptions, 'decodeStrings' | 'highWaterMark' | 'objectMode' | 'signal'>): Writable;
+            /**
+             * A utility method for creating a web `WritableStream` from a `Writable`.
+             * @since v17.0.0
+             * @experimental
+             */
+            static toWeb(streamWritable: Writable): streamWeb.WritableStream;
             /**
              * Is `true` if it is safe to call `writable.write()`, which means
              * the stream has not been destroyed, errored or ended.
@@ -541,6 +577,21 @@ declare module 'stream' {
              * @since v8.0.0
              */
             destroyed: boolean;
+            /**
+             * Is true after 'close' has been emitted.
+             * @since v8.0.0
+             */
+            readonly closed: boolean;
+            /**
+             * Returns error if the stream has been destroyed with an error.
+             * @since v18.0.0
+             */
+            readonly errored: Error | null;
+            /**
+             * Is `true` if the stream's buffer has been full and stream will emit 'drain'.
+             * @since v15.2.0, v14.17.0
+             */
+            readonly writableNeedDrain: boolean;
             constructor(opts?: WritableOptions);
             _write(chunk: any, encoding: BufferEncoding, callback: (error?: Error | null) => void): void;
             _writev?(
@@ -567,7 +618,7 @@ declare module 'stream' {
              * While a stream is not draining, calls to `write()` will buffer `chunk`, and
              * return false. Once all currently buffered chunks are drained (accepted for
              * delivery by the operating system), the `'drain'` event will be emitted.
-             * It is recommended that once `write()` returns false, no more chunks be written
+             * Once `write()` returns false, do not write more chunks
              * until the `'drain'` event is emitted. While calling `write()` on a stream that
              * is not draining is allowed, Node.js will buffer all written chunks until
              * maximum memory usage occurs, at which point it will abort unconditionally.
@@ -661,8 +712,8 @@ declare module 'stream' {
              * The `writable.uncork()` method flushes all data buffered since {@link cork} was called.
              *
              * When using `writable.cork()` and `writable.uncork()` to manage the buffering
-             * of writes to a stream, it is recommended that calls to `writable.uncork()` be
-             * deferred using `process.nextTick()`. Doing so allows batching of all`writable.write()` calls that occur within a given Node.js event loop phase.
+             * of writes to a stream, defer calls to `writable.uncork()` using`process.nextTick()`. Doing so allows batching of all`writable.write()` calls that occur within a given Node.js event
+             * loop phase.
              *
              * ```js
              * stream.cork();
@@ -807,6 +858,9 @@ declare module 'stream' {
             readonly writableLength: number;
             readonly writableObjectMode: boolean;
             readonly writableCorked: number;
+            readonly writableNeedDrain: boolean;
+            readonly closed: boolean;
+            readonly errored: Error | null;
             /**
              * If `false` then the stream will automatically end the writable side when the
              * readable side ends. Set initially by the `allowHalfOpen` constructor option,
@@ -839,7 +893,7 @@ declare module 'stream' {
              *
              * @since v16.8.0
              */
-            static from(src: Stream | Blob | ArrayBuffer | string | Iterable<any> | AsyncIterable<any> | AsyncGeneratorFunction | Promise<any> | Object): Duplex;
+            static from(src: Stream | NodeBlob | ArrayBuffer | string | Iterable<any> | AsyncIterable<any> | AsyncGeneratorFunction | Promise<any> | Object): Duplex;
             _write(chunk: any, encoding: BufferEncoding, callback: (error?: Error | null) => void): void;
             _writev?(
                 chunks: Array<{
@@ -1106,7 +1160,7 @@ declare module 'stream' {
          * async function run() {
          *   await pipeline(
          *     fs.createReadStream('lowercase.txt'),
-         *     async function* (source, signal) {
+         *     async function* (source, { signal }) {
          *       source.setEncoding('utf8');  // Work with strings rather than `Buffer`s.
          *       for await (const chunk of source) {
          *         yield await processChunk(chunk, { signal });
@@ -1130,7 +1184,7 @@ declare module 'stream' {
          *
          * async function run() {
          *   await pipeline(
-         *     async function * (signal) {
+         *     async function* ({ signal }) {
          *       await someLongRunningfn({ signal });
          *       yield 'asd';
          *     },
@@ -1149,7 +1203,31 @@ declare module 'stream' {
          *
          * `stream.pipeline()` leaves dangling event listeners on the streams
          * after the `callback` has been invoked. In the case of reuse of streams after
-         * failure, this can cause event listener leaks and swallowed errors.
+         * failure, this can cause event listener leaks and swallowed errors. If the last
+         * stream is readable, dangling event listeners will be removed so that the last
+         * stream can be consumed later.
+         *
+         * `stream.pipeline()` closes all the streams when an error is raised.
+         * The `IncomingRequest` usage with `pipeline` could lead to an unexpected behavior
+         * once it would destroy the socket without sending the expected response.
+         * See the example below:
+         *
+         * ```js
+         * const fs = require('fs');
+         * const http = require('http');
+         * const { pipeline } = require('stream');
+         *
+         * const server = http.createServer((req, res) => {
+         *   const fileStream = fs.createReadStream('./fileNotExist.txt');
+         *   pipeline(fileStream, res, (err) => {
+         *     if (err) {
+         *       console.log(err); // No such file
+         *       // this message can't be sent once `pipeline` already destroyed the socket
+         *       return res.end('error!!!');
+         *     }
+         *   });
+         * });
+         * ```
          * @since v10.0.0
          * @param callback Called when the pipeline is fully done.
          */
@@ -1241,13 +1319,13 @@ declare module 'stream' {
 
         /**
          * Returns whether the stream has encountered an error.
-         * @since v16.14.0
+         * @since v17.3.0
          */
         function isErrored(stream: Readable | Writable | NodeJS.ReadableStream | NodeJS.WritableStream): boolean;
 
         /**
          * Returns whether the stream is readable.
-         * @since v16.14.0
+         * @since v17.4.0
          */
         function isReadable(stream: Readable | NodeJS.ReadableStream): boolean;
 

node v16.11/string_decoder.d.ts → node/string_decoder.d.ts

@@ -36,7 +36,7 @@
  * decoder.write(Buffer.from([0x82]));
  * console.log(decoder.end(Buffer.from([0xAC])));
  * ```
- * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/string_decoder.js)
+ * @see [source](https://github.com/nodejs/node/blob/v18.0.0/lib/string_decoder.js)
  */
 declare module 'string_decoder' {
     class StringDecoder {

node/test.d.ts

@@ -0,0 +1,314 @@
+/**
+ * The `node:test` module provides a standalone testing module.
+ * @see [source](https://github.com/nodejs/node/blob/v18.0.0/lib/test.js)
+ */
+declare module 'node:test' {
+    /**
+     * Programmatically start the test runner.
+     * @since v18.9.0
+     * @param options Configuration options for running tests.
+     * @returns A {@link TapStream} that emits events about the test execution.
+     */
+    function run(options?: RunOptions): TapStream;
+
+    /**
+     * The `test()` function is the value imported from the test module. Each invocation of this
+     * function results in the creation of a test point in the TAP output.
+     *
+     * The {@link TestContext} object passed to the fn argument can be used to perform actions
+     * related to the current test. Examples include skipping the test, adding additional TAP
+     * diagnostic information, or creating subtests.
+     *
+     * `test()` returns a {@link Promise} that resolves once the test completes. The return value
+     * can usually be discarded for top level tests. However, the return value from subtests should
+     * be used to prevent the parent test from finishing first and cancelling the subtest as shown
+     * in the following example.
+     *
+     * ```js
+     * test('top level test', async (t) => {
+     *   // The setTimeout() in the following subtest would cause it to outlive its
+     *   // parent test if 'await' is removed on the next line. Once the parent test
+     *   // completes, it will cancel any outstanding subtests.
+     *   await t.test('longer running subtest', async (t) => {
+     *     return new Promise((resolve, reject) => {
+     *       setTimeout(resolve, 1000);
+     *     });
+     *   });
+     * });
+     * ```
+     * @since v18.0.0
+     * @param name The name of the test, which is displayed when reporting test results.
+     *    Default: The `name` property of fn, or `'<anonymous>'` if `fn` does not have a name.
+     * @param options Configuration options for the test
+     * @param fn The function under test. The first argument to this function is a
+     *    {@link TestContext} object. If the test uses callbacks, the callback function is
+     *    passed as the second argument. Default: A no-op function.
+     * @returns A {@link Promise} resolved with `undefined` once the test completes.
+     */
+    function test(name?: string, fn?: TestFn): Promise<void>;
+    function test(name?: string, options?: TestOptions, fn?: TestFn): Promise<void>;
+    function test(options?: TestOptions, fn?: TestFn): Promise<void>;
+    function test(fn?: TestFn): Promise<void>;
+
+    /**
+     * @since v18.6.0
+     * @param name The name of the suite, which is displayed when reporting suite results.
+     *    Default: The `name` property of fn, or `'<anonymous>'` if `fn` does not have a name.
+     * @param options Configuration options for the suite
+     * @param fn The function under suite. Default: A no-op function.
+     */
+    function describe(name?: string, options?: TestOptions, fn?: SuiteFn): void;
+    function describe(name?: string, fn?: SuiteFn): void;
+    function describe(options?: TestOptions, fn?: SuiteFn): void;
+    function describe(fn?: SuiteFn): void;
+
+    /**
+     * @since v18.6.0
+     * @param name The name of the test, which is displayed when reporting test results.
+     *    Default: The `name` property of fn, or `'<anonymous>'` if `fn` does not have a name.
+     * @param options Configuration options for the test
+     * @param fn The function under test. If the test uses callbacks, the callback function is
+     *    passed as the second argument. Default: A no-op function.
+     */
+    function it(name?: string, options?: TestOptions, fn?: ItFn): void;
+    function it(name?: string, fn?: ItFn): void;
+    function it(options?: TestOptions, fn?: ItFn): void;
+    function it(fn?: ItFn): void;
+
+    /**
+     * The type of a function under test. The first argument to this function is a
+     * {@link TestContext} object. If the test uses callbacks, the callback function is passed as
+     * the second argument.
+     */
+    type TestFn = (t: TestContext, done: (result?: any) => void) => any;
+
+    /**
+     * The type of a function under Suite.
+     * If the test uses callbacks, the callback function is passed as an argument
+     */
+    type SuiteFn = (done: (result?: any) => void) => void;
+
+    /**
+     * The type of a function under test.
+     * If the test uses callbacks, the callback function is passed as an argument
+     */
+    type ItFn = (done: (result?: any) => void) => any;
+
+    interface RunOptions {
+        /**
+         * @default false
+         */
+        concurrency?: number | boolean;
+
+        /**
+         * An array containing the list of files to run. If unspecified, the test runner execution model will be used.
+         */
+        files?: readonly string[];
+
+        /**
+         * Allows aborting an in-progress test.
+         * @default undefined
+         */
+        signal?: AbortSignal;
+
+        /**
+         * A number of milliseconds the test will fail after. If unspecified, subtests inherit this
+         * value from their parent.
+         * @default Infinity
+         */
+        timeout?: number;
+    }
+
+    /**
+     * A successful call of the run() method will return a new TapStream object, streaming a TAP output.
+     * TapStream will emit events in the order of the tests' definitions.
+     * @since v18.9.0
+     */
+    interface TapStream extends NodeJS.ReadableStream {
+        addListener(event: 'test:diagnostic', listener: (message: string) => void): this;
+        addListener(event: 'test:fail', listener: (data: TestFail) => void): this;
+        addListener(event: 'test:pass', listener: (data: TestPass) => void): this;
+        addListener(event: string, listener: (...args: any[]) => void): this;
+        emit(event: 'test:diagnostic', message: string): boolean;
+        emit(event: 'test:fail', data: TestFail): boolean;
+        emit(event: 'test:pass', data: TestPass): boolean;
+        emit(event: string | symbol, ...args: any[]): boolean;
+        on(event: 'test:diagnostic', listener: (message: string) => void): this;
+        on(event: 'test:fail', listener: (data: TestFail) => void): this;
+        on(event: 'test:pass', listener: (data: TestPass) => void): this;
+        on(event: string, listener: (...args: any[]) => void): this;
+        once(event: 'test:diagnostic', listener: (message: string) => void): this;
+        once(event: 'test:fail', listener: (data: TestFail) => void): this;
+        once(event: 'test:pass', listener: (data: TestPass) => void): this;
+        once(event: string, listener: (...args: any[]) => void): this;
+        prependListener(event: 'test:diagnostic', listener: (message: string) => void): this;
+        prependListener(event: 'test:fail', listener: (data: TestFail) => void): this;
+        prependListener(event: 'test:pass', listener: (data: TestPass) => void): this;
+        prependListener(event: string, listener: (...args: any[]) => void): this;
+        prependOnceListener(event: 'test:diagnostic', listener: (message: string) => void): this;
+        prependOnceListener(event: 'test:fail', listener: (data: TestFail) => void): this;
+        prependOnceListener(event: 'test:pass', listener: (data: TestPass) => void): this;
+        prependOnceListener(event: string, listener: (...args: any[]) => void): this;
+    }
+
+    interface TestFail {
+        /**
+         * The test duration.
+         */
+        duration: number;
+
+        /**
+         * The failure casing test to fail.
+         */
+        error: Error;
+
+        /**
+         * The test name.
+         */
+        name: string;
+
+        /**
+         * The ordinal number of the test.
+         */
+        testNumber: number;
+
+        /**
+         * Present if `context.todo` is called.
+         */
+        todo?: string;
+
+        /**
+         * Present if `context.skip` is called.
+         */
+        skip?: string;
+    }
+
+    interface TestPass {
+        /**
+         * The test duration.
+         */
+        duration: number;
+
+        /**
+         * The test name.
+         */
+        name: string;
+
+        /**
+         * The ordinal number of the test.
+         */
+        testNumber: number;
+
+        /**
+         * Present if `context.todo` is called.
+         */
+        todo?: string;
+
+        /**
+         * Present if `context.skip` is called.
+         */
+        skip?: string;
+    }
+
+    /**
+     * An instance of `TestContext` is passed to each test function in order to interact with the
+     * test runner. However, the `TestContext` constructor is not exposed as part of the API.
+     * @since v18.0.0
+     */
+    interface TestContext {
+        /**
+         * This function is used to write TAP diagnostics to the output. Any diagnostic information is
+         * included at the end of the test's results. This function does not return a value.
+         * @param message Message to be displayed as a TAP diagnostic.
+         * @since v18.0.0
+         */
+        diagnostic(message: string): void;
+
+        /**
+         * If `shouldRunOnlyTests` is truthy, the test context will only run tests that have the `only`
+         * option set. Otherwise, all tests are run. If Node.js was not started with the `--test-only`
+         * command-line option, this function is a no-op.
+         * @param shouldRunOnlyTests Whether or not to run `only` tests.
+         * @since v18.0.0
+         */
+        runOnly(shouldRunOnlyTests: boolean): void;
+
+        /**
+         * This function causes the test's output to indicate the test as skipped. If `message` is
+         * provided, it is included in the TAP output. Calling `skip()` does not terminate execution of
+         * the test function. This function does not return a value.
+         * @param message Optional skip message to be displayed in TAP output.
+         * @since v18.0.0
+         */
+        skip(message?: string): void;
+
+        /**
+         * This function adds a `TODO` directive to the test's output. If `message` is provided, it is
+         * included in the TAP output. Calling `todo()` does not terminate execution of the test
+         * function. This function does not return a value.
+         * @param message Optional `TODO` message to be displayed in TAP output.
+         * @since v18.0.0
+         */
+        todo(message?: string): void;
+
+        /**
+         * This function is used to create subtests under the current test. This function behaves in
+         * the same fashion as the top level {@link test} function.
+         * @since v18.0.0
+         * @param name The name of the test, which is displayed when reporting test results.
+         *    Default: The `name` property of fn, or `'<anonymous>'` if `fn` does not have a name.
+         * @param options Configuration options for the test
+         * @param fn The function under test. This first argument to this function is a
+         *    {@link TestContext} object. If the test uses callbacks, the callback function is
+         *    passed as the second argument. Default: A no-op function.
+         * @returns A {@link Promise} resolved with `undefined` once the test completes.
+         */
+        test: typeof test;
+    }
+
+    interface TestOptions {
+        /**
+         * The number of tests that can be run at the same time. If unspecified, subtests inherit this
+         * value from their parent.
+         * @default 1
+         */
+        concurrency?: number;
+
+        /**
+         * If truthy, and the test context is configured to run `only` tests, then this test will be
+         * run. Otherwise, the test is skipped.
+         * @default false
+         */
+        only?: boolean;
+
+        /**
+         * Allows aborting an in-progress test.
+         * @since v18.8.0
+         */
+        signal?: AbortSignal;
+
+        /**
+         * If truthy, the test is skipped. If a string is provided, that string is displayed in the
+         * test results as the reason for skipping the test.
+         * @default false
+         */
+        skip?: boolean | string;
+
+        /**
+         * A number of milliseconds the test will fail after. If unspecified, subtests inherit this
+         * value from their parent.
+         * @default Infinity
+         * @since v18.7.0
+         */
+        timeout?: number;
+
+        /**
+         * If truthy, the test marked as `TODO`. If a string is provided, that string is displayed in
+         * the test results as the reason why the test is `TODO`.
+         * @default false
+         */
+        todo?: boolean | string;
+    }
+
+    export { test as default, run, test, describe, it };
+}

node v16.11/timers.d.ts → node/timers.d.ts

@@ -6,7 +6,7 @@
  * The timer functions within Node.js implement a similar API as the timers API
  * provided by Web Browsers but use a different internal implementation that is
  * built around the Node.js [Event Loop](https://nodejs.org/en/docs/guides/event-loop-timers-and-nexttick/#setimmediate-vs-settimeout).
- * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/timers.js)
+ * @see [source](https://github.com/nodejs/node/blob/v18.0.0/lib/timers.js)
  */
 declare module 'timers' {
     import { Abortable } from 'node:events';