@types/node 16.11.39 → 18.11.2

node v16.11/util.d.ts → node/ts4.8/util.d.ts

@@ -6,7 +6,7 @@
  * ```js
  * const util = require('util');
  * ```
- * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/util.js)
+ * @see [source](https://github.com/nodejs/node/blob/v18.0.0/lib/util.js)
  */
 declare module 'util' {
     import * as types from 'node:util/types';
@@ -139,7 +139,7 @@ declare module 'util' {
      *   console.error(name);  // ENOENT
      * });
      * ```
-     * @since v16.0.0
+     * @since v16.0.0, v14.17.0
      */
     export function getSystemErrorMap(): Map<number, [string, string]>;
     /**
@@ -159,9 +159,30 @@ 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
+     * @since v16.8.0, v14.18.0
      */
     export function toUSVString(string: string): string;
+    /**
+     * Creates and returns an `AbortController` instance whose `AbortSignal` is marked
+     * as transferable and can be used with `structuredClone()` or `postMessage()`.
+     * @since v18.11.0
+     * @returns A transferable AbortController
+     */
+    export function transferableAbortController(): AbortController;
+    /**
+     * Marks the given {AbortSignal} as transferable so that it can be used with
+     * `structuredClone()` and `postMessage()`.
+     *
+     * ```js
+     * const signal = transferableAbortSignal(AbortSignal.timeout(100));
+     * const channel = new MessageChannel();
+     * channel.port2.postMessage(signal, [signal]);
+     * ```
+     * @since v18.11.0
+     * @param signal The AbortSignal
+     * @returns The same AbortSignal
+     */
+    export function transferableAbortSignal(signal: AbortSignal): AbortSignal;
     /**
      * The `util.inspect()` method returns a string representation of `object` that is
      * intended for debugging. The output of `util.inspect` may change at any time
@@ -309,6 +330,21 @@ declare module 'util' {
      * );
      * ```
      *
+     * The `numericSeparator` option adds an underscore every three digits to all
+     * numbers.
+     *
+     * ```js
+     * const { inspect } = require('util');
+     *
+     * const thousand = 1_000;
+     * const million = 1_000_000;
+     * const bigNumber = 123_456_789n;
+     * const bigDecimal = 1_234.123_45;
+     *
+     * console.log(thousand, million, bigNumber, bigDecimal);
+     * // 1_000 1_000_000 123_456_789n 1_234.123_45
+     * ```
+     *
      * `util.inspect()` is a synchronous method intended for debugging. Its maximum
      * output length is approximately 128 MB. Inputs that result in longer output will
      * be truncated.
@@ -317,7 +353,7 @@ declare module 'util' {
      * @return The representation of `object`.
      */
     export function inspect(object: any, showHidden?: boolean, depth?: number | null, color?: boolean): string;
-    export function inspect(object: any, options: InspectOptions): string;
+    export function inspect(object: any, options?: InspectOptions): string;
     export namespace inspect {
         let colors: NodeJS.Dict<[number, number]>;
         let styles: {
@@ -859,7 +895,7 @@ declare module 'util' {
      * callbackFunction((err, ret) => {
      *   // When the Promise was rejected with `null` it is wrapped with an Error and
      *   // the original value is stored in `reason`.
-     *   err &#x26;&#x26; err.hasOwnProperty('reason') &#x26;&#x26; err.reason === null;  // true
+     *   err &#x26;&#x26; Object.hasOwn(err, 'reason') &#x26;&#x26; err.reason === null;  // true
      * });
      * ```
      * @since v8.2.0
@@ -998,13 +1034,9 @@ declare module 'util' {
      * An implementation of the [WHATWG Encoding Standard](https://encoding.spec.whatwg.org/) `TextDecoder` API.
      *
      * ```js
-     * const decoder = new TextDecoder('shift_jis');
-     * let string = '';
-     * let buffer;
-     * while (buffer = getNextChunkSomehow()) {
-     *   string += decoder.decode(buffer, { stream: true });
-     * }
-     * string += decoder.decode(); // end-of-stream
+     * const decoder = new TextDecoder();
+     * const u8arr = new Uint8Array([72, 101, 108, 108, 111]);
+     * console.log(decoder.decode(u8arr)); // Hello
      * ```
      * @since v8.3.0
      */
@@ -1056,6 +1088,8 @@ declare module 'util' {
         written: number;
     }
     export { types };
+
+    //// TextEncoder/Decoder
     /**
      * An implementation of the [WHATWG Encoding Standard](https://encoding.spec.whatwg.org/) `TextEncoder` API. All
      * instances of `TextEncoder` only support UTF-8 encoding.
@@ -1094,6 +1128,228 @@ declare module 'util' {
          */
         encodeInto(src: string, dest: Uint8Array): EncodeIntoResult;
     }
+
+    import { TextDecoder as _TextDecoder, TextEncoder as _TextEncoder } from 'util';
+    global {
+        /**
+         * `TextDecoder` class is a global reference for `require('util').TextDecoder`
+         * https://nodejs.org/api/globals.html#textdecoder
+         * @since v11.0.0
+         */
+         var TextDecoder: typeof globalThis extends {
+            onmessage: any;
+            TextDecoder: infer TextDecoder;
+        }
+            ? TextDecoder
+            : typeof _TextDecoder;
+
+        /**
+         * `TextEncoder` class is a global reference for `require('util').TextEncoder`
+         * https://nodejs.org/api/globals.html#textencoder
+         * @since v11.0.0
+         */
+         var TextEncoder: typeof globalThis extends {
+            onmessage: any;
+            TextEncoder: infer TextEncoder;
+        }
+            ? TextEncoder
+            : typeof _TextEncoder;
+    }
+
+    //// parseArgs
+    /**
+     * Provides a high-level API for command-line argument parsing. Takes a
+     * specification for the expected arguments and returns a structured object
+     * with the parsed values and positionals.
+     *
+     * `config` provides arguments for parsing and configures the parser. It
+     * supports the following properties:
+     *
+     *   - `args` The array of argument strings. **Default:** `process.argv` with
+     *     `execPath` and `filename` removed.
+     *   - `options` Arguments known to the parser. Keys of `options` are the long
+     *     names of options and values are objects accepting the following properties:
+     *
+     *     - `type` Type of argument, which must be either `boolean` (for options
+     *        which do not take values) or `string` (for options which do).
+     *     - `multiple` Whether this option can be provided multiple
+     *       times. If `true`, all values will be collected in an array. If
+     *       `false`, values for the option are last-wins. **Default:** `false`.
+     *     - `short` A single character alias for the option.
+     *     - `default` The default option value when it is not set by args. It
+     *       must be of the same type as the `type` property. When `multiple`
+     *       is `true`, it must be an array.
+     *
+     *   - `strict`: Whether an error should be thrown when unknown arguments
+     *     are encountered, or when arguments are passed that do not match the
+     *     `type` configured in `options`. **Default:** `true`.
+     *   - `allowPositionals`: Whether this command accepts positional arguments.
+     *     **Default:** `false` if `strict` is `true`, otherwise `true`.
+     *   - `tokens`: Whether tokens {boolean} Return the parsed tokens. This is useful
+     *     for extending the built-in behavior, from adding additional checks through
+     *     to reprocessing the tokens in different ways.
+     *     **Default:** `false`.
+     *
+     * @returns The parsed command line arguments:
+     *
+     *   - `values` A mapping of parsed option names with their string
+     *     or boolean values.
+     *   - `positionals` Positional arguments.
+     *   - `tokens` Detailed parse information (only if `tokens` was specified).
+     *
+     */
+    export function parseArgs<T extends ParseArgsConfig>(config: T): ParsedResults<T>;
+
+    interface ParseArgsOptionConfig {
+        type: 'string' | 'boolean';
+        short?: string;
+        multiple?: boolean;
+        /**
+         * @since v18.11.0
+         */
+        default?: string | boolean | string[] | boolean[];
+    }
+
+    interface ParseArgsOptionsConfig {
+        [longOption: string]: ParseArgsOptionConfig;
+    }
+
+    export interface ParseArgsConfig {
+        strict?: boolean;
+        allowPositionals?: boolean;
+        tokens?: boolean;
+        options?: ParseArgsOptionsConfig;
+        args?: string[];
+    }
+
+    /*
+    IfDefaultsTrue and IfDefaultsFalse are helpers to handle default values for missing boolean properties.
+    TypeScript does not have exact types for objects: https://github.com/microsoft/TypeScript/issues/12936
+    This means it is impossible to distinguish between "field X is definitely not present" and "field X may or may not be present".
+    But we expect users to generally provide their config inline or `as const`, which means TS will always know whether a given field is present.
+    So this helper treats "not definitely present" (i.e., not `extends boolean`) as being "definitely not present", i.e. it should have its default value.
+    This is technically incorrect but is a much nicer UX for the common case.
+    The IfDefaultsTrue version is for things which default to true; the IfDefaultsFalse version is for things which default to false.
+    */
+    type IfDefaultsTrue<T, IfTrue, IfFalse> = T extends true
+        ? IfTrue
+        : T extends false
+        ? IfFalse
+        : IfTrue;
+
+    // we put the `extends false` condition first here because `undefined` compares like `any` when `strictNullChecks: false`
+    type IfDefaultsFalse<T, IfTrue, IfFalse> = T extends false
+        ? IfFalse
+        : T extends true
+        ? IfTrue
+        : IfFalse;
+
+    type ExtractOptionValue<T extends ParseArgsConfig, O extends ParseArgsOptionConfig> = IfDefaultsTrue<
+        T['strict'],
+        O['type'] extends 'string' ? string : O['type'] extends 'boolean' ? boolean : string | boolean,
+        string | boolean
+    >;
+
+    type ParsedValues<T extends ParseArgsConfig> =
+        & IfDefaultsTrue<T['strict'], unknown, { [longOption: string]: undefined | string | boolean }>
+        & (T['options'] extends ParseArgsOptionsConfig
+            ? {
+                -readonly [LongOption in keyof T['options']]: IfDefaultsFalse<
+                    T['options'][LongOption]['multiple'],
+                    undefined | Array<ExtractOptionValue<T, T['options'][LongOption]>>,
+                    undefined | ExtractOptionValue<T, T['options'][LongOption]>
+                >;
+            }
+            : {});
+
+    type ParsedPositionals<T extends ParseArgsConfig> = IfDefaultsTrue<
+        T['strict'],
+        IfDefaultsFalse<T['allowPositionals'], string[], []>,
+        IfDefaultsTrue<T['allowPositionals'], string[], []>
+    >;
+
+    type PreciseTokenForOptions<
+        K extends string,
+        O extends ParseArgsOptionConfig,
+    > = O['type'] extends 'string'
+        ? {
+              kind: 'option';
+              index: number;
+              name: K;
+              rawName: string;
+              value: string;
+              inlineValue: boolean;
+          }
+        : O['type'] extends 'boolean'
+        ? {
+              kind: 'option';
+              index: number;
+              name: K;
+              rawName: string;
+              value: undefined;
+              inlineValue: undefined;
+          }
+        : OptionToken & { name: K };
+
+    type TokenForOptions<
+        T extends ParseArgsConfig,
+        K extends keyof T['options'] = keyof T['options'],
+    > = K extends unknown
+        ? T['options'] extends ParseArgsOptionsConfig
+            ? PreciseTokenForOptions<K & string, T['options'][K]>
+            : OptionToken
+        : never;
+
+    type ParsedOptionToken<T extends ParseArgsConfig> = IfDefaultsTrue<T['strict'], TokenForOptions<T>, OptionToken>;
+
+    type ParsedPositionalToken<T extends ParseArgsConfig> = IfDefaultsTrue<
+        T['strict'],
+        IfDefaultsFalse<T['allowPositionals'], { kind: 'positional'; index: number; value: string }, never>,
+        IfDefaultsTrue<T['allowPositionals'], { kind: 'positional'; index: number; value: string }, never>
+    >;
+
+    type ParsedTokens<T extends ParseArgsConfig> = Array<
+        ParsedOptionToken<T> | ParsedPositionalToken<T> | { kind: 'option-terminator'; index: number }
+    >;
+
+    type PreciseParsedResults<T extends ParseArgsConfig> = IfDefaultsFalse<
+        T['tokens'],
+        {
+            values: ParsedValues<T>;
+            positionals: ParsedPositionals<T>;
+            tokens: ParsedTokens<T>;
+        },
+        {
+            values: ParsedValues<T>;
+            positionals: ParsedPositionals<T>;
+        }
+    >;
+
+    type OptionToken =
+        | { kind: 'option'; index: number; name: string; rawName: string; value: string; inlineValue: boolean }
+        | {
+              kind: 'option';
+              index: number;
+              name: string;
+              rawName: string;
+              value: undefined;
+              inlineValue: undefined;
+          };
+
+    type Token =
+        | OptionToken
+        | { kind: 'positional'; index: number; value: string }
+        | { kind: 'option-terminator'; index: number };
+
+    // If ParseArgsConfig extends T, then the user passed config constructed elsewhere.
+    // So we can't rely on the `"not definitely present" implies "definitely not present"` assumption mentioned above.
+    type ParsedResults<T extends ParseArgsConfig> = ParseArgsConfig extends T
+        ? {
+              values: { [longOption: string]: undefined | string | boolean | Array<string | boolean> };
+              positionals: string[];
+              tokens?: Token[];
+          }
+        : PreciseParsedResults<T>;
 }
 declare module 'util/types' {
     export * from 'util/types';

node v16.11/v8.d.ts → node/ts4.8/v8.d.ts

@@ -4,7 +4,7 @@
  * ```js
  * const v8 = require('v8');
  * ```
- * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/v8.js)
+ * @see [source](https://github.com/nodejs/node/blob/v18.0.0/lib/v8.js)
  */
 declare module 'v8' {
     import { Readable } from 'node:stream';
@@ -163,6 +163,13 @@ declare module 'v8' {
      * Chrome DevTools. The JSON schema is undocumented and specific to the
      * V8 engine. Therefore, the schema may change from one version of V8 to the next.
      *
+     * Creating a heap snapshot requires memory about twice the size of the heap at
+     * the time the snapshot is created. This results in the risk of OOM killers
+     * terminating the process.
+     *
+     * Generating a snapshot is a synchronous operation which blocks the event loop
+     * for a duration depending on the heap size.
+     *
      * ```js
      * // Print heap snapshot to the console
      * const v8 = require('v8');
@@ -182,6 +189,13 @@ declare module 'v8' {
      * A heap snapshot is specific to a single V8 isolate. When using `worker threads`, a heap snapshot generated from the main thread will
      * not contain any information about the workers, and vice versa.
      *
+     * Creating a heap snapshot requires memory about twice the size of the heap at
+     * the time the snapshot is created. This results in the risk of OOM killers
+     * terminating the process.
+     *
+     * Generating a snapshot is a synchronous operation which blocks the event loop
+     * for a duration depending on the heap size.
+     *
      * ```js
      * const { writeHeapSnapshot } = require('v8');
      * const {
@@ -344,6 +358,10 @@ declare module 'v8' {
     class DefaultDeserializer extends Deserializer {}
     /**
      * Uses a `DefaultSerializer` to serialize `value` into a buffer.
+     *
+     * `ERR_BUFFER_TOO_LARGE` will be thrown when trying to
+     * serialize a huge object which requires buffer
+     * larger than `buffer.constants.MAX_LENGTH`.
      * @since v8.0.0
      */
     function serialize(value: any): Buffer;
@@ -362,14 +380,14 @@ declare module 'v8' {
      *
      * When the process is about to exit, one last coverage will still be written to
      * disk unless {@link stopCoverage} is invoked before the process exits.
-     * @since v15.1.0, v12.22.0
+     * @since v15.1.0, v14.18.0, v12.22.0
      */
     function takeCoverage(): void;
     /**
      * The `v8.stopCoverage()` method allows the user to stop the coverage collection
      * started by `NODE_V8_COVERAGE`, so that V8 can release the execution count
      * records and optimize code. This can be used in conjunction with {@link takeCoverage} if the user wants to collect the coverage on demand.
-     * @since v15.1.0, v12.22.0
+     * @since v15.1.0, v14.18.0, v12.22.0
      */
     function stopCoverage(): void;
 }

node v16.11/vm.d.ts → node/ts4.8/vm.d.ts

@@ -1,7 +1,9 @@
 /**
  * The `vm` module enables compiling and running code within V8 Virtual
- * Machine contexts. **The `vm` module is not a security mechanism. Do**
- * **not use it to run untrusted code.**
+ * Machine contexts.
+ *
+ * **The `vm` module is not a security**
+ * **mechanism. Do not use it to run untrusted code.**
  *
  * JavaScript code can be compiled and run immediately or
  * compiled, saved, and run later.
@@ -32,7 +34,7 @@
  *
  * console.log(x); // 1; y is not defined.
  * ```
- * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/vm.js)
+ * @see [source](https://github.com/nodejs/node/blob/v18.0.0/lib/vm.js)
  */
 declare module 'vm' {
     interface Context extends NodeJS.Dict<any> {}
@@ -221,7 +223,7 @@ declare module 'vm' {
         runInNewContext(contextObject?: Context, options?: RunningScriptOptions): any;
         /**
          * Runs the compiled code contained by the `vm.Script` within the context of the
-         * current `global` object. Running code does not have access to local scope, but_does_ have access to the current `global` object.
+         * current `global` object. Running code does not have access to local scope, but _does_ have access to the current `global` object.
          *
          * The following example compiles code that increments a `global` variable then
          * executes that code multiple times:

node v16.11/wasi.d.ts → node/ts4.8/wasi.d.ts

@@ -68,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.9.0/lib/wasi.js)
+ * @see [source](https://github.com/nodejs/node/blob/v18.0.0/lib/wasi.js)
  */
 declare module 'wasi' {
     interface WASIOptions {

node v16.11/worker_threads.d.ts → node/ts4.8/worker_threads.d.ts

@@ -39,7 +39,7 @@
  * }
  * ```
  *
- * The above example spawns a Worker thread for each `parse()` call. In actual
+ * The above example spawns a Worker thread for each `parseJSAsync()` call. In
  * practice, use a pool of Workers for these kinds of tasks. Otherwise, the
  * overhead of creating Workers would likely exceed their benefit.
  *
@@ -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.9.0/lib/worker_threads.js)
+ * @see [source](https://github.com/nodejs/node/blob/v18.0.0/lib/worker_threads.js)
  */
 declare module 'worker_threads' {
     import { Blob } from 'node:buffer';
@@ -175,7 +175,7 @@ declare module 'worker_threads' {
          */
         postMessage(value: any, transferList?: ReadonlyArray<TransferListItem>): void;
         /**
-         * Opposite of `unref()`. Calling `ref()` on a previously `unref()`ed port does_not_ let the program exit if it's the only active handle left (the default
+         * Opposite of `unref()`. Calling `ref()` on a previously `unref()`ed port does _not_ let the program exit if it's the only active handle left (the default
          * behavior). If the port is `ref()`ed, calling `ref()` again has no effect.
          *
          * If listeners are attached or removed using `.on('message')`, the port
@@ -384,7 +384,7 @@ declare module 'worker_threads' {
         /**
          * An object that can be used to query performance information from a worker
          * instance. Similar to `perf_hooks.performance`.
-         * @since v15.1.0, v12.22.0
+         * @since v15.1.0, v14.17.0, v12.22.0
          */
         readonly performance: WorkerPerformance;
         /**
@@ -400,7 +400,7 @@ declare module 'worker_threads' {
          */
         postMessage(value: any, transferList?: ReadonlyArray<TransferListItem>): void;
         /**
-         * Opposite of `unref()`, calling `ref()` on a previously `unref()`ed worker does_not_ let the program exit if it's the only active handle left (the default
+         * Opposite of `unref()`, calling `ref()` on a previously `unref()`ed worker does _not_ let the program exit if it's the only active handle left (the default
          * behavior). If the worker is `ref()`ed, calling `ref()` again has
          * no effect.
          * @since v10.5.0
@@ -507,7 +507,6 @@ declare module 'worker_threads' {
      * }
      * ```
      * @since v15.4.0
-     * @experimental
      */
     class BroadcastChannel {
         readonly name: string;
@@ -629,20 +628,61 @@ declare module 'worker_threads' {
      *   console.log(getEnvironmentData('Hello'));  // Prints 'World!'.
      * }
      * ```
-     * @since v15.12.0
-     * @experimental
+     * @since v15.12.0, v14.18.0
      * @param key Any arbitrary, cloneable JavaScript value that can be used as a {Map} key.
      */
     function getEnvironmentData(key: Serializable): Serializable;
     /**
      * The `worker.setEnvironmentData()` API sets the content of`worker.getEnvironmentData()` in the current thread and all new `Worker`instances spawned from the current context.
-     * @since v15.12.0
-     * @experimental
+     * @since v15.12.0, v14.18.0
      * @param key Any arbitrary, cloneable JavaScript value that can be used as a {Map} key.
      * @param value Any arbitrary, cloneable JavaScript value that will be cloned and passed automatically to all new `Worker` instances. If `value` is passed as `undefined`, any previously set value
      * for the `key` will be deleted.
      */
     function setEnvironmentData(key: Serializable, value: Serializable): void;
+
+    import {
+        BroadcastChannel as _BroadcastChannel,
+        MessageChannel as _MessageChannel,
+        MessagePort as _MessagePort,
+    } from 'worker_threads';
+    global {
+        /**
+         * `BroadcastChannel` class is a global reference for `require('worker_threads').BroadcastChannel`
+         * https://nodejs.org/api/globals.html#broadcastchannel
+         * @since v18.0.0
+         */
+        var BroadcastChannel: typeof globalThis extends {
+            onmessage: any;
+            BroadcastChannel: infer T;
+        }
+            ? T
+            : typeof _BroadcastChannel;
+
+        /**
+         * `MessageChannel` class is a global reference for `require('worker_threads').MessageChannel`
+         * https://nodejs.org/api/globals.html#messagechannel
+         * @since v15.0.0
+         */
+        var MessageChannel: typeof globalThis extends {
+            onmessage: any;
+            MessageChannel: infer T;
+        }
+            ? T
+            : typeof _MessageChannel;
+
+        /**
+         * `MessagePort` class is a global reference for `require('worker_threads').MessagePort`
+         * https://nodejs.org/api/globals.html#messageport
+         * @since v15.0.0
+         */
+         var MessagePort: typeof globalThis extends {
+            onmessage: any;
+            MessagePort: infer T;
+        }
+            ? T
+            : typeof _MessagePort;
+    }
 }
 declare module 'node:worker_threads' {
     export * from 'worker_threads';

node v16.11/zlib.d.ts → node/ts4.8/zlib.d.ts

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