@types/node 24.13.6 → 24.19.0

{node v24.13 → node v24.19}/url.d.ts

@@ -238,9 +238,31 @@ declare module "url" {
      * * `result` is returned.
      * @since v0.1.25
      * @legacy Use the WHATWG URL API instead.
-     * @param urlObject A URL object (as returned by `url.parse()` or constructed otherwise). If a string, it is converted to an object by passing it to `url.parse()`.
+     * @param urlObject A URL object (as returned by `url.parse()` or constructed otherwise).
      */
-    function format(urlObject: UrlObject | string): string;
+    function format(urlObject: UrlObject): string;
+    /**
+     * `url.format(urlString)` is shorthand for `url.format(url.parse(urlString))`.
+     *
+     * Because it invokes the deprecated `url.parse()` internally, passing a string argument
+     * to `url.format()` is itself deprecated.
+     *
+     * Canonicalizing a URL string can be performed using the WHATWG URL API, by
+     * constructing a new URL object and calling `url.toString()`.
+     *
+     * ```js
+     * import { URL } from 'node:url';
+     *
+     * const unformatted = 'http://[fe80:0:0:0:0:0:0:1]:/a/b?a=b#abc';
+     * const formatted = new URL(unformatted).toString();
+     *
+     * console.log(formatted); // Prints: http://[fe80::1]/a/b?a=b#abc
+     * ```
+     * @since v0.1.25
+     * @deprecated Use the WHATWG URL API instead.
+     * @param urlString A string that will be passed to `url.parse()` and then formatted.
+     */
+    function format(urlString: string): string;
     /**
      * The `url.resolve()` method resolves a target URL relative to a base URL in a
      * manner similar to that of a web browser resolving an anchor tag.
@@ -252,6 +274,8 @@ declare module "url" {
      * url.resolve('http://example.com/one', '/two'); // 'http://example.com/two'
      * ```
      *
+     * Because it invokes the deprecated `url.parse()` internally, `url.resolve()` is itself deprecated.
+     *
      * To achieve the same result using the WHATWG URL API:
      *
      * ```js
@@ -270,7 +294,7 @@ declare module "url" {
      * resolve('http://example.com/one', '/two'); // 'http://example.com/two'
      * ```
      * @since v0.1.25
-     * @legacy Use the WHATWG URL API instead.
+     * @deprecated Use the WHATWG URL API instead.
      * @param from The base URL to use if `to` is a relative URL.
      * @param to The target URL to resolve.
      */

{node v24.13 → node v24.19}/util.d.ts

@@ -707,6 +707,28 @@ declare module "util" {
      * @legacy Use ES2015 class syntax and `extends` keyword instead.
      */
     export function inherits(constructor: unknown, superConstructor: unknown): void;
+    /**
+     * The `util.convertProcessSignalToExitCode()` method converts a signal name to its
+     * corresponding POSIX exit code. Following the POSIX standard, the exit code
+     * for a process terminated by a signal is calculated as `128 + signal number`.
+     *
+     * If `signal` is not a valid signal name, then an error will be thrown. See
+     * [`signal(7)`](https://man7.org/linux/man-pages/man7/signal.7.html) for a list of valid signals.
+     *
+     * ```js
+     * import { convertProcessSignalToExitCode } from 'node:util';
+     *
+     * console.log(convertProcessSignalToExitCode('SIGTERM')); // 143 (128 + 15)
+     * console.log(convertProcessSignalToExitCode('SIGKILL')); // 137 (128 + 9)
+     * ```
+     *
+     * This is particularly useful when working with processes to determine
+     * the exit code based on the signal that terminated the process.
+     * @since v24.14.0
+     * @param signal A signal name (e.g. `'SIGTERM'`)
+     * @returns The exit code corresponding to `signal`
+     */
+    export function convertProcessSignalToExitCode(signal: NodeJS.Signals): number;
     export type DebugLoggerFunction = (msg: string, ...param: unknown[]) => void;
     export interface DebugLogger extends DebugLoggerFunction {
         /**
@@ -929,6 +951,8 @@ declare module "util" {
      * `reason`.
      *
      * ```js
+     * import util from 'node:util';
+     *
      * function fn() {
      *   return Promise.reject(null);
      * }
@@ -1256,8 +1280,23 @@ declare module "util" {
      *
      * The special format value `none` applies no additional styling to the text.
      *
+     * In addition to predefined color names, `util.styleText()` supports hex color
+     * strings using ANSI TrueColor (24-bit) escape sequences. Hex colors can be
+     * specified in either 3-digit (`#RGB`) or 6-digit (`#RRGGBB`) format:
+     *
+     * ```js
+     * import { styleText } from 'node:util';
+     *
+     * // 6-digit hex color
+     * console.log(styleText('#ff5733', 'Orange text'));
+     *
+     * // 3-digit hex color (shorthand)
+     * console.log(styleText('#f00', 'Red text'));
+     * ```
+     *
      * The full list of formats can be found in [modifiers](https://nodejs.org/docs/latest-v24.x/api/util.html#modifiers).
-     * @param format A text format or an Array of text formats defined in `util.inspect.colors`.
+     * @param format A text format or an Array of text formats defined in `util.inspect.colors`, or a hex color in `#RGB`
+     * or `#RRGGBB` form.
      * @param text The text to to be formatted.
      * @since v20.12.0
      */
@@ -1266,7 +1305,8 @@ declare module "util" {
             | ForegroundColors
             | BackgroundColors
             | Modifiers
-            | Array<ForegroundColors | BackgroundColors | Modifiers>,
+            | Array<ForegroundColors | BackgroundColors | Modifiers>
+            | `#${string}`,
         text: string,
         options?: StyleTextOptions,
     ): string;

{node v24.13 → node v24.19}/v8.d.ts

@@ -71,7 +71,37 @@ declare module "v8" {
     /**
      * Returns an object with the following properties:
      *
-     * `does_zap_garbage` is a 0/1 boolean, which signifies whether the `--zap_code_space` option is enabled or not. This makes V8 overwrite heap
+     * `total_heap_size` The value of total\_heap\_size is the number of bytes V8 has
+     * allocated for the heap. This can grow if used\_heap needs more memory.
+     *
+     * `total_heap_size_executable` The value of total\_heap\_size\_executable is the
+     * portion of the heap that can contain executable code, in bytes. This includes
+     * memory used by JIT-compiled code and any memory that must be kept executable.
+     *
+     * `total_physical_size` The value of total\_physical\_size is the actual physical memory
+     * used by the V8 heap, in bytes. This is the amount of memory that is committed
+     * (or in use) rather than reserved.
+     *
+     * `total_available_size` The value of total\_available\_size is the number of
+     * bytes of memory available to the V8 heap. This value represents how much
+     * more memory V8 can use before it exceeds the heap limit.
+     *
+     * `used_heap_size` The value of used\_heap\_size is number of bytes currently
+     * being used by V8’s JavaScript objects. This is the actual memory in use and
+     * does not include memory that has been allocated but not yet used.
+     *
+     * `heap_size_limit` The value of heap\_size\_limit is the maximum size of the V8
+     * heap, in bytes (either the default limit, determined by system resources, or
+     * the value passed to the `--max_old_space_size` option).
+     *
+     * `malloced_memory` The value of malloced\_memory is the number of bytes allocated
+     * through `malloc` by V8.
+     *
+     * `peak_malloced_memory` The value of peak\_malloced\_memory is the peak number of
+     * bytes allocated through `malloc` by V8 during the lifetime of the process.
+     *
+     * `does_zap_garbage` is a 0/1 boolean, which signifies whether the
+     * `--zap_code_space` option is enabled or not. This makes V8 overwrite heap
      * garbage with a bit pattern. The RSS footprint (resident set size) gets bigger
      * because it continuously touches all heap pages and that makes them less likely
      * to get swapped out by the operating system.
@@ -93,22 +123,22 @@ declare module "v8" {
      * `external_memory` The value of external\_memory is the memory size of array
      * buffers and external strings.
      *
-     * ```js
+     * ```json
      * {
-     *   total_heap_size: 7326976,
-     *   total_heap_size_executable: 4194304,
-     *   total_physical_size: 7326976,
-     *   total_available_size: 1152656,
-     *   used_heap_size: 3476208,
-     *   heap_size_limit: 1535115264,
-     *   malloced_memory: 16384,
-     *   peak_malloced_memory: 1127496,
-     *   does_zap_garbage: 0,
-     *   number_of_native_contexts: 1,
-     *   number_of_detached_contexts: 0,
-     *   total_global_handles_size: 8192,
-     *   used_global_handles_size: 3296,
-     *   external_memory: 318824
+     *   "total_heap_size": 7326976,
+     *   "total_heap_size_executable": 4194304,
+     *   "total_physical_size": 7326976,
+     *   "total_available_size": 1152656,
+     *   "used_heap_size": 3476208,
+     *   "heap_size_limit": 1535115264,
+     *   "malloced_memory": 16384,
+     *   "peak_malloced_memory": 1127496,
+     *   "does_zap_garbage": 0,
+     *   "number_of_native_contexts": 1,
+     *   "number_of_detached_contexts": 0,
+     *   "total_global_handles_size": 8192,
+     *   "used_global_handles_size": 3296,
+     *   "external_memory": 318824
      * }
      * ```
      * @since v1.0.0
@@ -389,12 +419,12 @@ declare module "v8" {
      * V8 [`GetHeapCodeAndMetadataStatistics`](https://v8docs.nodesource.com/node-13.2/d5/dda/classv8_1_1_isolate.html#a6079122af17612ef54ef3348ce170866) API. Returns an object with the
      * following properties:
      *
-     * ```js
+     * ```json
      * {
-     *   code_and_metadata_size: 212208,
-     *   bytecode_and_metadata_size: 161368,
-     *   external_script_source_size: 1410794,
-     *   cpu_profiler_metadata_size: 0,
+     *   "code_and_metadata_size": 212208,
+     *   "bytecode_and_metadata_size": 161368,
+     *   "external_script_source_size": 1410794,
+     *   "cpu_profiler_metadata_size": 0
      * }
      * ```
      * @since v12.8.0
@@ -883,8 +913,6 @@ declare module "v8" {
      * For example, if the `entry.js` contains the following script:
      *
      * ```js
-     * 'use strict';
-     *
      * import fs from 'node:fs';
      * import zlib from 'node:zlib';
      * import path from 'node:path';

{node v24.13 → node v24.19}/vm.d.ts

@@ -238,16 +238,16 @@ declare module "vm" {
          * The globals are contained in the `context` object.
          *
          * ```js
-         * import vm from 'node:vm';
+         * import { createContext, Script } from 'node:vm';
          *
          * const context = {
          *   animal: 'cat',
          *   count: 2,
          * };
          *
-         * const script = new vm.Script('count += 1; name = "kitty";');
+         * const script = new Script('count += 1; name = "kitty";');
          *
-         * vm.createContext(context);
+         * createContext(context);
          * for (let i = 0; i < 10; ++i) {
          *   script.runInContext(context);
          * }
@@ -281,9 +281,9 @@ declare module "vm" {
          * contained within each individual `context`.
          *
          * ```js
-         * const vm = require('node:vm');
+         * import { constants, Script } from 'node:vm';
          *
-         * const script = new vm.Script('globalVar = "set"');
+         * const script = new Script('globalVar = "set"');
          *
          * const contexts = [{}, {}, {}];
          * contexts.forEach((context) => {
@@ -294,10 +294,10 @@ declare module "vm" {
          * // Prints: [{ globalVar: 'set' }, { globalVar: 'set' }, { globalVar: 'set' }]
          *
          * // This would throw if the context is created from a contextified object.
-         * // vm.constants.DONT_CONTEXTIFY allows creating contexts with ordinary
+         * // constants.DONT_CONTEXTIFY allows creating contexts with ordinary
          * // global objects that can be frozen.
-         * const freezeScript = new vm.Script('Object.freeze(globalThis); globalThis;');
-         * const frozenContext = freezeScript.runInNewContext(vm.constants.DONT_CONTEXTIFY);
+         * const freezeScript = new Script('Object.freeze(globalThis); globalThis;');
+         * const frozenContext = freezeScript.runInNewContext(constants.DONT_CONTEXTIFY);
          * ```
          * @since v0.3.1
          * @param contextObject Either `vm.constants.DONT_CONTEXTIFY` or an object that will be contextified.
@@ -316,11 +316,11 @@ declare module "vm" {
          * executes that code multiple times:
          *
          * ```js
-         * import vm from 'node:vm';
+         * import { Script } from 'node:vm';
          *
          * global.globalVar = 0;
          *
-         * const script = new vm.Script('globalVar += 1', { filename: 'myfile.vm' });
+         * const script = new Script('globalVar += 1', { filename: 'myfile.vm' });
          *
          * for (let i = 0; i < 1000; ++i) {
          *   script.runInThisContext();
@@ -409,14 +409,14 @@ declare module "vm" {
      * variables will remain unchanged.
      *
      * ```js
-     * const vm = require('node:vm');
+     * import { createContext, runInContext } from 'node:vm';
      *
      * global.globalVar = 3;
      *
      * const context = { globalVar: 1 };
-     * vm.createContext(context);
+     * createContext(context);
      *
-     * vm.runInContext('globalVar *= 2;', context);
+     * runInContext('globalVar *= 2;', context);
      *
      * console.log(context);
      * // Prints: { globalVar: 2 }
@@ -467,13 +467,13 @@ declare module "vm" {
      * The following example compiles and executes different scripts using a single `contextified` object:
      *
      * ```js
-     * import vm from 'node:vm';
+     * import { createContext, runInContext } from 'node:vm';
      *
      * const contextObject = { globalVar: 1 };
-     * vm.createContext(contextObject);
+     * createContext(contextObject);
      *
      * for (let i = 0; i < 10; ++i) {
-     *   vm.runInContext('globalVar *= 2;', contextObject);
+     *   runInContext('globalVar *= 2;', contextObject);
      * }
      * console.log(contextObject);
      * // Prints: { globalVar: 1024 }
@@ -504,21 +504,24 @@ declare module "vm" {
      * variable and sets a new one. These globals are contained in the `contextObject`.
      *
      * ```js
-     * const vm = require('node:vm');
+     * import { runInNewContext, constants } from 'node:vm';
      *
      * const contextObject = {
      *   animal: 'cat',
      *   count: 2,
      * };
      *
-     * vm.runInNewContext('count += 1; name = "kitty"', contextObject);
+     * runInNewContext('count += 1; name = "kitty"', contextObject);
      * console.log(contextObject);
      * // Prints: { animal: 'cat', count: 3, name: 'kitty' }
      *
      * // This would throw if the context is created from a contextified object.
      * // vm.constants.DONT_CONTEXTIFY allows creating contexts with ordinary global objects that
      * // can be frozen.
-     * const frozenContext = vm.runInNewContext('Object.freeze(globalThis); globalThis;', vm.constants.DONT_CONTEXTIFY);
+     * const frozenContext = runInNewContext(
+     *   'Object.freeze(globalThis); globalThis;',
+     *   constants.DONT_CONTEXTIFY,
+     * );
      * ```
      * @since v0.3.1
      * @param code The JavaScript code to compile and run.
@@ -542,10 +545,10 @@ declare module "vm" {
      * the JavaScript [`eval()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/eval) function to run the same code:
      *
      * ```js
-     * import vm from 'node:vm';
+     * import { runInThisContext } from 'node:vm';
      * let localVar = 'initial value';
      *
-     * const vmResult = vm.runInThisContext('localVar = "vm";');
+     * const vmResult = runInThisContext('localVar = "vm";');
      * console.log(`vmResult: '${vmResult}', localVar: '${localVar}'`);
      * // Prints: vmResult: 'vm', localVar: 'initial value'
      *
@@ -557,38 +560,6 @@ 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
      * 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
-     *
-     * When using either `script.runInThisContext()` or {@link runInThisContext}, the code is executed within the current V8 global
-     * context. The code passed to this VM context will have its own isolated scope.
-     *
-     * In order to run a simple web server using the `node:http` module the code passed
-     * to the context must either import `node:http` on its own, or have a
-     * reference to the `node:http` module passed to it. For instance:
-     *
-     * ```js
-     * 'use strict';
-     * import vm from 'node:vm';
-     *
-     * const code = `
-     * ((require) => {
-     * const http = require('node:http');
-     *
-     *   http.createServer((request, response) => {
-     *     response.writeHead(200, { 'Content-Type': 'text/plain' });
-     *     response.end('Hello World\\n');
-     *   }).listen(8124);
-     *
-     *   console.log('Server running at http://127.0.0.1:8124/');
-     * })`;
-     *
-     * vm.runInThisContext(code)(require);
-     * ```
-     *
-     * The `require()` in the above case shares the state with the context it is
-     * passed from. This may introduce risks when untrusted code is executed, e.g.
-     * altering objects in the context in unwanted ways.
      * @since v0.3.1
      * @param code The JavaScript code to compile and run.
      * @return the result of the very last statement executed in the script.
@@ -620,44 +591,32 @@ declare module "vm" {
      * the memory occupied by each heap space in the current V8 instance.
      *
      * ```js
-     * import vm from 'node:vm';
+     * import { createContext, measureMemory } from 'node:vm';
      * // Measure the memory used by the main context.
-     * vm.measureMemory({ mode: 'summary' })
+     * measureMemory({ mode: 'summary' })
      *   // This is the same as vm.measureMemory()
      *   .then((result) => {
      *     // The current format is:
      *     // {
-     *     //   total: {
-     *     //      jsMemoryEstimate: 2418479, jsMemoryRange: [ 2418479, 2745799 ]
-     *     //    }
+     *     //   total: { jsMemoryEstimate: 1601828, jsMemoryRange: [1601828, 5275288] },
+     *     //   WebAssembly: { code: 0, metadata: 33962 },
      *     // }
      *     console.log(result);
      *   });
      *
-     * const context = vm.createContext({ a: 1 });
-     * vm.measureMemory({ mode: 'detailed', execution: 'eager' })
-     *   .then((result) => {
-     *     // Reference the context here so that it won't be GC'ed
-     *     // until the measurement is complete.
-     *     console.log(context.a);
-     *     // {
-     *     //   total: {
-     *     //     jsMemoryEstimate: 2574732,
-     *     //     jsMemoryRange: [ 2574732, 2904372 ]
-     *     //   },
-     *     //   current: {
-     *     //     jsMemoryEstimate: 2438996,
-     *     //     jsMemoryRange: [ 2438996, 2768636 ]
-     *     //   },
-     *     //   other: [
-     *     //     {
-     *     //       jsMemoryEstimate: 135736,
-     *     //       jsMemoryRange: [ 135736, 465376 ]
-     *     //     }
-     *     //   ]
-     *     // }
-     *     console.log(result);
-     *   });
+     * const context = createContext({ a: 1 });
+     * measureMemory({ mode: 'detailed', execution: 'eager' }).then((result) => {
+     *   // Reference the context here so that it won't be GC'ed
+     *   // until the measurement is complete.
+     *   console.log('Context:', context.a);
+     *   // {
+     *   //   total: { jsMemoryEstimate: 1767100, jsMemoryRange: [1767100, 5440560] },
+     *   //   WebAssembly: { code: 0, metadata: 33962 },
+     *   //   current: { jsMemoryEstimate: 1601828, jsMemoryRange: [1601828, 5275288] },
+     *   //   other: [{ jsMemoryEstimate: 165272, jsMemoryRange: [Array] }],
+     *   // }
+     *   console.log(result);
+     * });
      * ```
      * @since v13.10.0
      * @experimental
@@ -819,8 +778,8 @@ declare module "vm" {
          */
         status: ModuleStatus;
         /**
-         * Evaluate the module and its depenendencies. Corresponds to the [Evaluate() concrete method](https://tc39.es/ecma262/#sec-moduleevaluation)
-         * field of [Cyclic Module Record](https://tc39.es/ecma262/#sec-cyclic-module-records)s in the ECMAScript specification.
+         * Evaluate the module and its dependencies. Corresponds to the [Evaluate() concrete method](https://tc39.es/ecma262/#sec-moduleevaluation) field of
+         * [Cyclic Module Record](https://tc39.es/ecma262/#sec-cyclic-module-records)s in the ECMAScript specification.
          *
          * If the module is a `vm.SourceTextModule`, `evaluate()` must be called after the module has been instantiated;
          * otherwise `evaluate()` will return a rejected promise.
@@ -1117,15 +1076,21 @@ declare module "vm" {
      * module graphs.
      *
      * ```js
-     * import vm from 'node:vm';
+     * import { SyntheticModule } from 'node:vm';
      *
      * const source = '{ "a": 1 }';
-     * const module = new vm.SyntheticModule(['default'], function() {
+     * const syntheticModule = new SyntheticModule(['default'], function() {
      *   const obj = JSON.parse(source);
      *   this.setExport('default', obj);
      * });
      *
-     * // Use `module` in linking...
+     * // Use `syntheticModule` in linking
+     * (async () => {
+     *   await syntheticModule.link(() => {});
+     *   await syntheticModule.evaluate();
+     *
+     *   console.log('Default export:', syntheticModule.namespace.default);
+     * })();
      * ```
      * @since v13.0.0, v12.16.0
      * @experimental

{node v24.13 → node v24.19}/zlib.d.ts

@@ -125,6 +125,13 @@ declare module "zlib" {
          * @default buffer.kMaxLength
          */
         maxOutputLength?: number | undefined;
+        /**
+         * If `true`, decompression fails when
+         * trailing input is detected after the end of the compressed stream. This
+         * includes unreadable bytes and, when decompressing gzip, additional gzip
+         * members following the first member. **Default:** `false`
+         */
+        rejectGarbageAfterEnd?: boolean | undefined;
     }
     interface BrotliOptions {
         /**
@@ -156,6 +163,11 @@ declare module "zlib" {
          * If `true`, returns an object with `buffer` and `engine`.
          */
         info?: boolean | undefined;
+        /**
+         * If `true`, decompression fails when
+         * input remains after the first complete compressed stream. **Default:** `false`
+         */
+        rejectGarbageAfterEnd?: boolean | undefined;
     }
     interface ZstdOptions {
         /**
@@ -191,6 +203,11 @@ declare module "zlib" {
          * @since v24.6.0
          */
         dictionary?: NodeJS.ArrayBufferView | undefined;
+        /**
+         * If `true`, decompression fails when
+         * input remains after the first complete compressed stream. **Default:** `false`
+         */
+        rejectGarbageAfterEnd?: boolean | undefined;
     }
     interface Zlib {
         readonly bytesWritten: number;