@types/node 16.9.3 → 16.10.0

node/stream.d.ts

@@ -14,7 +14,7 @@
  *
  * 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.7.0/lib/stream.js)
+ * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/stream.js)
  */
 declare module 'stream' {
     import { EventEmitter, Abortable } from 'node:events';
@@ -60,6 +60,7 @@ declare module 'stream' {
             /**
              * Returns whether the stream was destroyed or errored before emitting `'end'`.
              * @since v16.8.0
+             * @experimental
              */
             readonly readableAborted: boolean;
             /**
@@ -71,6 +72,7 @@ declare module 'stream' {
             /**
              * Returns whether `'data'` has been emitted.
              * @since v16.7.0
+             * @experimental
              */
             readonly readableDidRead: boolean;
             /**
@@ -805,6 +807,15 @@ declare module 'stream' {
             readonly writableLength: number;
             readonly writableObjectMode: boolean;
             readonly writableCorked: number;
+            /**
+             * If `false` then the stream will automatically end the writable side when the
+             * readable side ends. Set initially by the `allowHalfOpen` constructor option,
+             * which defaults to `false`.
+             *
+             * This can be changed manually to change the half-open behavior of an existing`Duplex` stream instance, but must be changed before the `'end'` event is
+             * emitted.
+             * @since v0.9.4
+             */
             allowHalfOpen: boolean;
             constructor(opts?: DuplexOptions);
             /**
@@ -1072,16 +1083,14 @@ declare module 'stream' {
          *
          * async function run() {
          *   const ac = new AbortController();
-         *   const options = {
-         *     signal: ac.signal,
-         *   };
+         *   const signal = ac.signal;
          *
          *   setTimeout(() => ac.abort(), 1);
          *   await pipeline(
          *     fs.createReadStream('archive.tar'),
          *     zlib.createGzip(),
          *     fs.createWriteStream('archive.tar.gz'),
-         *     options,
+         *     { signal },
          *   );
          * }
          *
@@ -1097,10 +1106,10 @@ declare module 'stream' {
          * async function run() {
          *   await pipeline(
          *     fs.createReadStream('lowercase.txt'),
-         *     async function* (source) {
+         *     async function* (source, signal) {
          *       source.setEncoding('utf8');  // Work with strings rather than `Buffer`s.
          *       for await (const chunk of source) {
-         *         yield chunk.toUpperCase();
+         *         yield await processChunk(chunk, { signal });
          *       }
          *     },
          *     fs.createWriteStream('uppercase.txt')
@@ -1111,6 +1120,28 @@ declare module 'stream' {
          * run().catch(console.error);
          * ```
          *
+         * Remember to handle the `signal` argument passed into the async generator.
+         * Especially in the case where the async generator is the source for the
+         * pipeline (i.e. first argument) or the pipeline will never complete.
+         *
+         * ```js
+         * const { pipeline } = require('stream/promises');
+         * const fs = require('fs');
+         *
+         * async function run() {
+         *   await pipeline(
+         *     async function * (signal) {
+         *       await someLongRunningfn({ signal });
+         *       yield 'asd';
+         *     },
+         *     fs.createWriteStream('uppercase.txt')
+         *   );
+         *   console.log('Pipeline succeeded.');
+         * }
+         *
+         * run().catch(console.error);
+         * ```
+         *
          * `stream.pipeline()` will call `stream.destroy(err)` on all streams except:
          *
          * * `Readable` streams which have emitted `'end'` or `'close'`.

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.7.0/lib/string_decoder.js)
+ * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/string_decoder.js)
  */
 declare module 'string_decoder' {
     class StringDecoder {

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.7.0/lib/timers.js)
+ * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/timers.js)
  */
 declare module 'timers' {
     import { Abortable } from 'node:events';

node/tls.d.ts

@@ -6,7 +6,7 @@
  * ```js
  * const tls = require('tls');
  * ```
- * @see [source](https://github.com/nodejs/node/blob/v16.7.0/lib/tls.js)
+ * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/tls.js)
  */
 declare module 'tls' {
     import { X509Certificate } from 'node:crypto';
@@ -189,7 +189,7 @@ declare module 'tls' {
          * }
          * ```
          *
-         * See[SSL\_CIPHER\_get\_name](https://www.openssl.org/docs/man1.1.1/man3/SSL_CIPHER_get_name.html)for more information.
+         * See [SSL\_CIPHER\_get\_name](https://www.openssl.org/docs/man1.1.1/man3/SSL_CIPHER_get_name.html) for more information.
          * @since v0.11.4
          */
         getCipher(): CipherNameAndProtocol;
@@ -274,7 +274,7 @@ declare module 'tls' {
          */
         getSession(): Buffer | undefined;
         /**
-         * See[SSL\_get\_shared\_sigalgs](https://www.openssl.org/docs/man1.1.1/man3/SSL_get_shared_sigalgs.html)for more information.
+         * See [SSL\_get\_shared\_sigalgs](https://www.openssl.org/docs/man1.1.1/man3/SSL_get_shared_sigalgs.html) for more information.
          * @since v12.11.0
          * @return List of signature algorithms shared between the server and the client in the order of decreasing preference.
          */
@@ -810,8 +810,8 @@ declare module 'tls' {
     /**
      * Verifies the certificate `cert` is issued to `hostname`.
      *
-     * Returns [<Error>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) object, populating it with `reason`, `host`, and `cert` on
-     * failure. On success, returns [<undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Undefined_type).
+     * Returns [Error](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) object, populating it with `reason`, `host`, and `cert` on
+     * failure. On success, returns [undefined](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Undefined_type).
      *
      * This function can be overwritten by providing alternative function as part of
      * the `options.checkServerIdentity` option passed to `tls.connect()`. The
@@ -962,7 +962,7 @@ declare module 'tls' {
      *
      * A key is _required_ for ciphers that use certificates. Either `key` or`pfx` can be used to provide it.
      *
-     * If the `ca` option is not given, then Node.js will default to using[Mozilla's publicly trusted list of
+     * If the `ca` option is not given, then Node.js will default to using [Mozilla's publicly trusted list of
      * CAs](https://hg.mozilla.org/mozilla-central/raw-file/tip/security/nss/lib/ckfw/builtins/certdata.txt).
      * @since v0.11.13
      */

node/trace_events.d.ts

@@ -56,7 +56,7 @@
  * ```
  *
  * Running Node.js with tracing enabled will produce log files that can be opened
- * in the [`chrome://tracing`](https://www.chromium.org/developers/how-tos/trace-event-profiling-tool)tab of Chrome.
+ * in the [`chrome://tracing`](https://www.chromium.org/developers/how-tos/trace-event-profiling-tool) tab of Chrome.
  *
  * The logging file is by default called `node_trace.${rotation}.log`, where`${rotation}` is an incrementing log-rotation id. The filepath pattern can
  * be specified with `--trace-event-file-pattern` that accepts a template
@@ -73,7 +73,7 @@
  *
  * The features from this module are not available in `Worker` threads.
  * @experimental
- * @see [source](https://github.com/nodejs/node/blob/v16.7.0/lib/trace_events.js)
+ * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/trace_events.js)
  */
 declare module 'trace_events' {
     /**

node/tty.d.ts

@@ -22,7 +22,7 @@
  *
  * In most cases, there should be little to no reason for an application to
  * manually create instances of the `tty.ReadStream` and `tty.WriteStream`classes.
- * @see [source](https://github.com/nodejs/node/blob/v16.7.0/lib/tty.js)
+ * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/tty.js)
  */
 declare module 'tty' {
     import * as net from 'node:net';
@@ -129,9 +129,7 @@ declare module 'tty' {
          * * `1` for 2,
          * * `4` for 16,
          * * `8` for 256,
-         * * `24` for 16,777,216
-         *
-         * colors supported.
+         * * `24` for 16,777,216 colors supported.
          *
          * Use this to determine what colors the terminal supports. Due to the nature of
          * colors in terminals it is possible to either have false positives or false

node/url.d.ts

@@ -5,7 +5,7 @@
  * ```js
  * import url from 'url';
  * ```
- * @see [source](https://github.com/nodejs/node/blob/v16.7.0/lib/url.js)
+ * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/url.js)
  */
 declare module 'url' {
     import { Blob } from 'node:buffer';

node/util.d.ts

@@ -6,7 +6,7 @@
  * ```js
  * const util = require('util');
  * ```
- * @see [source](https://github.com/nodejs/node/blob/v16.7.0/lib/util.js)
+ * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/util.js)
  */
 declare module 'util' {
     import * as types from 'node:util/types';
@@ -145,7 +145,6 @@ declare module 'util' {
      * Returns the `string` after replacing any surrogate code points
      * (or equivalently, any unpaired surrogate code units) with the
      * Unicode "replacement character" U+FFFD.
-     *
      * @since v16.8.0
      */
     export function toUSVString(string: string): string;
@@ -253,7 +252,7 @@ declare module 'util' {
      * The `showHidden` option allows [`WeakMap`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakMap) and
      * [`WeakSet`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakSet) entries to be
      * inspected. If there are more entries than `maxArrayLength`, there is no
-     * guarantee which entries are displayed. That means retrieving the same[`WeakSet`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakSet) entries twice may
+     * guarantee which entries are displayed. That means retrieving the same [`WeakSet`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakSet) entries twice may
      * result in different output. Furthermore, entries
      * with no remaining strong references may be garbage collected at any time.
      *
@@ -965,7 +964,7 @@ declare module 'util' {
         const custom: unique symbol;
     }
     /**
-     * An implementation of the [WHATWG Encoding Standard](https://encoding.spec.whatwg.org/)`TextDecoder` API.
+     * An implementation of the [WHATWG Encoding Standard](https://encoding.spec.whatwg.org/) `TextDecoder` API.
      *
      * ```js
      * const decoder = new TextDecoder('shift_jis');
@@ -1027,7 +1026,7 @@ declare module 'util' {
     }
     export { types };
     /**
-     * An implementation of the [WHATWG Encoding Standard](https://encoding.spec.whatwg.org/)`TextEncoder` API. All
+     * An implementation of the [WHATWG Encoding Standard](https://encoding.spec.whatwg.org/) `TextEncoder` API. All
      * instances of `TextEncoder` only support UTF-8 encoding.
      *
      * ```js
@@ -1071,8 +1070,8 @@ declare module 'util/types' {
 declare module 'util/types' {
     import { KeyObject, webcrypto } from 'node:crypto';
     /**
-     * Returns `true` if the value is a built-in [`ArrayBuffer`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer)
-     * or[`SharedArrayBuffer`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer) instance.
+     * Returns `true` if the value is a built-in [`ArrayBuffer`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer) or
+     * [`SharedArrayBuffer`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer) instance.
      *
      * See also `util.types.isArrayBuffer()` and `util.types.isSharedArrayBuffer()`.
      *
@@ -1107,9 +1106,9 @@ declare module 'util/types' {
      */
     function isArrayBuffer(object: unknown): object is ArrayBuffer;
     /**
-     * Returns `true` if the value is an instance of one of the [`ArrayBuffer`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer)views, such as typed array
-     * objects or [`DataView`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView). Equivalent
-     * to[`ArrayBuffer.isView()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer/isView).
+     * Returns `true` if the value is an instance of one of the [`ArrayBuffer`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer) views, such as typed
+     * array objects or [`DataView`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView). Equivalent to
+     * [`ArrayBuffer.isView()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer/isView).
      *
      * ```js
      * util.types.isArrayBufferView(new Int8Array());  // true
@@ -1337,7 +1336,7 @@ declare module 'util/types' {
      */
     function isMap<T>(object: T | {}): object is T extends ReadonlyMap<any, any> ? (unknown extends T ? never : ReadonlyMap<any, any>) : Map<unknown, unknown>;
     /**
-     * Returns `true` if the value is an iterator returned for a built-in[`Map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) instance.
+     * Returns `true` if the value is an iterator returned for a built-in [`Map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) instance.
      *
      * ```js
      * const map = new Map();
@@ -1423,7 +1422,7 @@ declare module 'util/types' {
      */
     function isSet<T>(object: T | {}): object is T extends ReadonlySet<any> ? (unknown extends T ? never : ReadonlySet<any>) : Set<unknown>;
     /**
-     * Returns `true` if the value is an iterator returned for a built-in[`Set`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set) instance.
+     * Returns `true` if the value is an iterator returned for a built-in [`Set`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set) instance.
      *
      * ```js
      * const set = new Set();

node/v8.d.ts

@@ -1,10 +1,10 @@
 /**
- * The `v8` module exposes APIs that are specific to the version of [V8](https://developers.google.com/v8/)built into the Node.js binary. It can be accessed using:
+ * The `v8` module exposes APIs that are specific to the version of [V8](https://developers.google.com/v8/) built into the Node.js binary. It can be accessed using:
  *
  * ```js
  * const v8 = require('v8');
  * ```
- * @see [source](https://github.com/nodejs/node/blob/v16.7.0/lib/v8.js)
+ * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/v8.js)
  */
 declare module 'v8' {
     import { Readable } from 'node:stream';

node/vm.d.ts

@@ -32,7 +32,7 @@
  *
  * console.log(x); // 1; y is not defined.
  * ```
- * @see [source](https://github.com/nodejs/node/blob/v16.7.0/lib/vm.js)
+ * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/vm.js)
  */
 declare module 'vm' {
     interface Context extends NodeJS.Dict<any> {}
@@ -267,7 +267,6 @@ declare module 'vm' {
          * @since v10.6.0
          */
         createCachedData(): Buffer;
-
         /** @deprecated in favor of `script.createCachedData()` */
         cachedDataProduced?: boolean | undefined;
         cachedDataRejected?: boolean | undefined;
@@ -277,7 +276,7 @@ declare module 'vm' {
      * If given a `contextObject`, the `vm.createContext()` method will `prepare
      * that object` so that it can be used in calls to {@link runInContext} or `script.runInContext()`. Inside such scripts,
      * the `contextObject` will be the global object, retaining all of its existing
-     * properties but also having the built-in objects and functions any standard[global object](https://es5.github.io/#x15.1) has. Outside of scripts run by the vm module, global variables
+     * properties but also having the built-in objects and functions any standard [global object](https://es5.github.io/#x15.1) has. Outside of scripts run by the vm module, global variables
      * will remain unchanged.
      *
      * ```js
@@ -398,7 +397,7 @@ declare module 'vm' {
      * ```
      *
      * Because `vm.runInThisContext()` does not have access to the local scope,`localVar` is unchanged. In contrast,
-     * [`eval()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/eval)_does_ have access to the
+     * [`eval()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/eval) _does_ have access to the
      * local scope, so the value `localVar` is changed. In this way`vm.runInThisContext()` is much like an [indirect `eval()` call](https://es5.github.io/#x10.4.2), e.g.`(0,eval)('code')`.
      *
      * ## Example: Running an HTTP server within a VM

node/wasi.d.ts

@@ -1,9 +1,9 @@
 /**
- * The WASI API provides an implementation of the [WebAssembly System Interface](https://wasi.dev/)specification. WASI gives sandboxed WebAssembly applications access to the
+ * The WASI API provides an implementation of the [WebAssembly System Interface](https://wasi.dev/) specification. WASI gives sandboxed WebAssembly applications access to the
  * underlying operating system via a collection of POSIX-like functions.
  *
  * ```js
- * import fs from 'fs';
+ * import { readFile } from 'fs/promises';
  * import { WASI } from 'wasi';
  * import { argv, env } from 'process';
  *
@@ -14,9 +14,14 @@
  *     '/sandbox': '/some/real/path/that/wasm/can/access'
  *   }
  * });
+ *
+ * // Some WASI binaries require:
+ * //   const importObject = { wasi_unstable: wasi.wasiImport };
  * const importObject = { wasi_snapshot_preview1: wasi.wasiImport };
  *
- * const wasm = await WebAssembly.compile(fs.readFileSync('./demo.wasm'));
+ * const wasm = await WebAssembly.compile(
+ *   await readFile(new URL('./demo.wasm', import.meta.url))
+ * );
  * const instance = await WebAssembly.instantiate(wasm, importObject);
  *
  * wasi.start(instance);
@@ -63,7 +68,7 @@
  * The `--experimental-wasi-unstable-preview1` CLI argument is needed for this
  * example to run.
  * @experimental
- * @see [source](https://github.com/nodejs/node/blob/v16.7.0/lib/wasi.js)
+ * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/wasi.js)
  */
 declare module 'wasi' {
     interface WASIOptions {

node/worker_threads.d.ts

@@ -49,7 +49,7 @@
  *
  * Worker threads inherit non-process-specific options by default. Refer to `Worker constructor options` to know how to customize worker thread options,
  * specifically `argv` and `execArgv` options.
- * @see [source](https://github.com/nodejs/node/blob/v16.7.0/lib/worker_threads.js)
+ * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/worker_threads.js)
  */
 declare module 'worker_threads' {
     import { Blob } from 'node:buffer';
@@ -94,7 +94,7 @@ declare module 'worker_threads' {
      * asynchronous, two-way communications channel. It can be used to transfer
      * structured data, memory regions and other `MessagePort`s between different `Worker` s.
      *
-     * This implementation matches [browser `MessagePort`](https://developer.mozilla.org/en-US/docs/Web/API/MessagePort)s.
+     * This implementation matches [browser `MessagePort`](https://developer.mozilla.org/en-US/docs/Web/API/MessagePort) s.
      * @since v10.5.0
      */
     class MessagePort extends EventEmitter {
@@ -572,11 +572,11 @@ declare module 'worker_threads' {
      * takes its place.
      *
      * The returned `MessagePort` is an object in the target context and
-     * inherits from its global `Object` class. Objects passed to the[`port.onmessage()`](https://developer.mozilla.org/en-US/docs/Web/API/MessagePort/onmessage) listener are also created in the
+     * inherits from its global `Object` class. Objects passed to the [`port.onmessage()`](https://developer.mozilla.org/en-US/docs/Web/API/MessagePort/onmessage) listener are also created in the
      * target context
      * and inherit from its global `Object` class.
      *
-     * However, the created `MessagePort` no longer inherits from[`EventTarget`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget), and only
+     * However, the created `MessagePort` no longer inherits from [`EventTarget`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget), and only
      * [`port.onmessage()`](https://developer.mozilla.org/en-US/docs/Web/API/MessagePort/onmessage) can be used to receive
      * events using it.
      * @since v11.13.0

node/zlib.d.ts

@@ -88,7 +88,7 @@
  *   });
  * ```
  * @since v0.5.8
- * @see [source](https://github.com/nodejs/node/blob/v16.7.0/lib/zlib.js)
+ * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/zlib.js)
  */
 declare module 'zlib' {
     import * as stream from 'node:stream';