@types/node 22.7.9 → 22.8.1

node/README.md

@@ -8,7 +8,7 @@ This package contains type definitions for node (https://nodejs.org/).
 Files were exported from https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/node.
 
 ### Additional Details
- * Last updated: Wed, 23 Oct 2024 03:36:41 GMT
+ * Last updated: Fri, 25 Oct 2024 22:02:20 GMT
  * Dependencies: [undici-types](https://npmjs.com/package/undici-types)
 
 # Credits

node/module.d.ts

@@ -238,12 +238,66 @@ declare module "module" {
             context: LoadHookContext,
             nextLoad: (url: string, context?: LoadHookContext) => LoadFnOutput | Promise<LoadFnOutput>,
         ) => LoadFnOutput | Promise<LoadFnOutput>;
+        namespace constants {
+            /**
+             * The following constants are returned as the `status` field in the object returned by
+             * {@link enableCompileCache} to indicate the result of the attempt to enable the
+             * [module compile cache](https://nodejs.org/docs/latest-v22.x/api/module.html#module-compile-cache).
+             * @since v22.8.0
+             */
+            namespace compileCacheStatus {
+                /**
+                 * Node.js has enabled the compile cache successfully. The directory used to store the
+                 * compile cache will be returned in the `directory` field in the
+                 * returned object.
+                 */
+                const ENABLED: number;
+                /**
+                 * The compile cache has already been enabled before, either by a previous call to
+                 * {@link enableCompileCache}, or by the `NODE_COMPILE_CACHE=dir`
+                 * environment variable. The directory used to store the
+                 * compile cache will be returned in the `directory` field in the
+                 * returned object.
+                 */
+                const ALREADY_ENABLED: number;
+                /**
+                 * Node.js fails to enable the compile cache. This can be caused by the lack of
+                 * permission to use the specified directory, or various kinds of file system errors.
+                 * The detail of the failure will be returned in the `message` field in the
+                 * returned object.
+                 */
+                const FAILED: number;
+                /**
+                 * Node.js cannot enable the compile cache because the environment variable
+                 * `NODE_DISABLE_COMPILE_CACHE=1` has been set.
+                 */
+                const DISABLED: number;
+            }
+        }
     }
     interface RegisterOptions<Data> {
         parentURL: string | URL;
         data?: Data | undefined;
         transferList?: any[] | undefined;
     }
+    interface EnableCompileCacheResult {
+        /**
+         * One of the {@link constants.compileCacheStatus}
+         */
+        status: number;
+        /**
+         * If Node.js cannot enable the compile cache, this contains
+         * the error message. Only set if `status` is `module.constants.compileCacheStatus.FAILED`.
+         */
+        message?: string;
+        /**
+         * If the compile cache is enabled, this contains the directory
+         * where the compile cache is stored. Only set if  `status` is
+         * `module.constants.compileCacheStatus.ENABLED` or
+         * `module.constants.compileCacheStatus.ALREADY_ENABLED`.
+         */
+        directory?: string;
+    }
     interface Module extends NodeModule {}
     class Module {
         static runMain(): void;
@@ -258,6 +312,43 @@ declare module "module" {
             options?: RegisterOptions<Data>,
         ): void;
         static register<Data = any>(specifier: string | URL, options?: RegisterOptions<Data>): void;
+        /**
+         * Enable [module compile cache](https://nodejs.org/docs/latest-v22.x/api/module.html#module-compile-cache)
+         * in the current Node.js instance.
+         *
+         * If `cacheDir` is not specified, Node.js will either use the directory specified by the
+         * `NODE_COMPILE_CACHE=dir` environment variable if it's set, or use
+         * `path.join(os.tmpdir(), 'node-compile-cache')` otherwise. For general use cases, it's
+         * recommended to call `module.enableCompileCache()` without specifying the `cacheDir`,
+         * so that the directory can be overridden by the `NODE_COMPILE_CACHE` environment
+         * variable when necessary.
+         *
+         * Since compile cache is supposed to be a quiet optimization that is not required for the
+         * application to be functional, this method is designed to not throw any exception when the
+         * compile cache cannot be enabled. Instead, it will return an object containing an error
+         * message in the `message` field to aid debugging.
+         * If compile cache is enabled successfully, the `directory` field in the returned object
+         * contains the path to the directory where the compile cache is stored. The `status`
+         * field in the returned object would be one of the `module.constants.compileCacheStatus`
+         * values to indicate the result of the attempt to enable the
+         * [module compile cache](https://nodejs.org/docs/latest-v22.x/api/module.html#module-compile-cache).
+         *
+         * This method only affects the current Node.js instance. To enable it in child worker threads,
+         * either call this method in child worker threads too, or set the
+         * `process.env.NODE_COMPILE_CACHE` value to compile cache directory so the behavior can
+         * be inherited into the child workers. The directory can be obtained either from the
+         * `directory` field returned by this method, or with {@link getCompileCacheDir}.
+         * @since v22.8.0
+         * @param cacheDir Optional path to specify the directory where the compile cache
+         * will be stored/retrieved.
+         */
+        static enableCompileCache(cacheDir?: string): EnableCompileCacheResult;
+        /**
+         * @since v22.8.0
+         * @return Path to the [module compile cache](https://nodejs.org/docs/latest-v22.x/api/module.html#module-compile-cache)
+         * directory if it is enabled, or `undefined` otherwise.
+         */
+        static getCompileCacheDir(): string | undefined;
         constructor(id: string, parent?: Module);
     }
     global {

node/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@types/node",
-    "version": "22.7.9",
+    "version": "22.8.1",
     "description": "TypeScript definitions for node",
     "homepage": "https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/node",
     "license": "MIT",
@@ -217,9 +217,9 @@
     },
     "scripts": {},
     "dependencies": {
-        "undici-types": "~6.19.2"
+        "undici-types": "~6.19.8"
     },
     "peerDependencies": {},
-    "typesPublisherContentHash": "49b712614616bc7f8a0b0f6596d6add73e659a4a4d0695f61e4ab90a468876d3",
+    "typesPublisherContentHash": "679317e7cae6b391e6bf63e356e0496420e31113098d850dbc95b3d22c17a6c6",
     "typeScriptVersion": "4.8"
 }

node/perf_hooks.d.ts

@@ -116,6 +116,20 @@ declare module "perf_hooks" {
     class PerformanceMeasure extends PerformanceEntry {
         readonly entryType: "measure";
     }
+    interface UVMetrics {
+        /**
+         * Number of event loop iterations.
+         */
+        readonly loopCount: number;
+        /**
+         * Number of events that have been processed by the event handler.
+         */
+        readonly events: number;
+        /**
+         * Number of events that were waiting to be processed when the event provider was called.
+         */
+        readonly eventsWaiting: number;
+    }
     /**
      * _This property is an extension by Node.js. It is not available in Web browsers._
      *
@@ -166,6 +180,16 @@ declare module "perf_hooks" {
          * @since v8.5.0
          */
         readonly nodeStart: number;
+        /**
+         * This is a wrapper to the `uv_metrics_info` function.
+         * It returns the current set of event loop metrics.
+         *
+         * It is recommended to use this property inside a function whose execution was
+         * scheduled using `setImmediate` to avoid collecting metrics before finishing all
+         * operations scheduled during the current loop iteration.
+         * @since v22.8.0, v20.18.0
+         */
+        readonly uvMetricsInfo: UVMetrics;
         /**
          * The high resolution millisecond timestamp at which the V8 platform was
          * initialized.

node/test.d.ts

@@ -340,11 +340,22 @@ declare module "node:test" {
         globPatterns?: readonly string[] | undefined;
         /**
          * Sets inspector port of test child process.
-         * If a nullish value is provided, each process gets its own port,
-         * incremented from the primary's `process.debugPort`.
+         * This can be a number, or a function that takes no arguments and returns a
+         * number. If a nullish value is provided, each process gets its own port,
+         * incremented from the primary's `process.debugPort`. This option is ignored
+         * if the `isolation` option is set to `'none'` as no child processes are
+         * spawned.
          * @default undefined
          */
         inspectPort?: number | (() => number) | undefined;
+        /**
+         * Configures the type of test isolation. If set to
+         * `'process'`, each test file is run in a separate child process. If set to
+         * `'none'`, all test files run in the current process.
+         * @default 'process'
+         * @since v22.8.0
+         */
+        isolation?: "process" | "none" | undefined;
         /**
          * If truthy, the test context will only run tests that have the `only` option set
          */
@@ -1635,9 +1646,10 @@ declare module "node:test" {
          * This function is used to set a custom resolver for the location of the snapshot file used for snapshot testing.
          * By default, the snapshot filename is the same as the entry point filename with `.snapshot` appended.
          * @since v22.3.0
-         * @param fn A function which returns a string specifying the location of the snapshot file.
-         * The function receives the path of the test file as its only argument.
-         * If `process.argv[1]` is not associated with a file (for example in the REPL), the input is undefined.
+         * @param fn A function used to compute the location of the snapshot file.
+         * The function receives the path of the test file as its only argument. If the
+         * test is not associated with a file (for example in the REPL), the input is
+         * undefined. `fn()` must return a string specifying the location of the snapshot file.
          */
         function setResolveSnapshotPath(fn: (path: string | undefined) => string): void;
     }

node/vm.d.ts

@@ -230,16 +230,23 @@ declare module "vm" {
          */
         runInContext(contextifiedObject: Context, options?: RunningScriptOptions): any;
         /**
-         * First contextifies the given `contextObject`, runs the compiled code contained
-         * by the `vm.Script` object within the created context, and returns the result.
-         * Running code does not have access to local scope.
+         * This method is a shortcut to `script.runInContext(vm.createContext(options), options)`.
+         * It does several things at once:
+         *
+         * 1. Creates a new context.
+         * 2. If `contextObject` is an object, contextifies it with the new context.
+         *    If  `contextObject` is undefined, creates a new object and contextifies it.
+         *    If `contextObject` is `vm.constants.DONT_CONTEXTIFY`, don't contextify anything.
+         * 3. Runs the compiled code contained by the `vm.Script` object within the created context. The code
+         *    does not have access to the scope in which this method is called.
+         * 4. Returns the result.
          *
          * The following example compiles code that sets a global variable, then executes
          * the code multiple times in different contexts. The globals are set on and
          * contained within each individual `context`.
          *
          * ```js
-         * import vm from 'node:vm';
+         * const vm = require('node:vm');
          *
          * const script = new vm.Script('globalVar = "set"');
          *
@@ -250,12 +257,22 @@ declare module "vm" {
          *
          * console.log(contexts);
          * // 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
+         * // global objects that can be frozen.
+         * const freezeScript = new vm.Script('Object.freeze(globalThis); globalThis;');
+         * const frozenContext = freezeScript.runInNewContext(vm.constants.DONT_CONTEXTIFY);
          * ```
          * @since v0.3.1
-         * @param contextObject An object that will be `contextified`. If `undefined`, a new object will be created.
+         * @param contextObject Either `vm.constants.DONT_CONTEXTIFY` or an object that will be contextified.
+         * If `undefined`, an empty contextified object will be created for backwards compatibility.
          * @return the result of the very last statement executed in the script.
          */
-        runInNewContext(contextObject?: Context, options?: RunningScriptInNewContextOptions): any;
+        runInNewContext(
+            contextObject?: Context | typeof constants.DONT_CONTEXTIFY,
+            options?: RunningScriptInNewContextOptions,
+        ): 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.
@@ -347,17 +364,17 @@ declare module "vm" {
         sourceMapURL?: string | undefined;
     }
     /**
-     * If given a `contextObject`, the `vm.createContext()` method will
+     * If the given `contextObject` is an object, the `vm.createContext()` method will
      * [prepare that object](https://nodejs.org/docs/latest-v22.x/api/vm.html#what-does-it-mean-to-contextify-an-object)
-     * and return a reference to it so that it can be used in `{@link runInContext}` or
-     * [`script.runInContext()`](https://nodejs.org/docs/latest-v22.x/api/vm.html#scriptrunincontextcontextifiedobject-options). 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
+     * and return a reference to it so that it can be used in calls to {@link runInContext} or
+     * [`script.runInContext()`](https://nodejs.org/docs/latest-v22.x/api/vm.html#scriptrunincontextcontextifiedobject-options).
+     * Inside such scripts, the global object will be wrapped by the `contextObject`, 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 will remain unchanged.
      *
      * ```js
-     * import vm from 'node:vm';
+     * const vm = require('node:vm');
      *
      * global.globalVar = 3;
      *
@@ -374,7 +391,12 @@ declare module "vm" {
      * ```
      *
      * If `contextObject` is omitted (or passed explicitly as `undefined`), a new,
-     * empty `contextified` object will be returned.
+     * empty contextified object will be returned.
+     *
+     * When the global object in the newly created context is contextified, it has some quirks
+     * compared to ordinary global objects. For example, it cannot be frozen. To create a context
+     * without the contextifying quirks, pass `vm.constants.DONT_CONTEXTIFY` as the `contextObject`
+     * argument. See the documentation of `vm.constants.DONT_CONTEXTIFY` for details.
      *
      * The `vm.createContext()` method is primarily useful for creating a single
      * context that can be used to run multiple scripts. For instance, if emulating a
@@ -385,11 +407,17 @@ declare module "vm" {
      * The provided `name` and `origin` of the context are made visible through the
      * Inspector API.
      * @since v0.3.1
+     * @param contextObject Either `vm.constants.DONT_CONTEXTIFY` or an object that will be contextified.
+     * If `undefined`, an empty contextified object will be created for backwards compatibility.
      * @return contextified object.
      */
-    function createContext(sandbox?: Context, options?: CreateContextOptions): Context;
+    function createContext(
+        contextObject?: Context | typeof constants.DONT_CONTEXTIFY,
+        options?: CreateContextOptions,
+    ): Context;
     /**
-     * Returns `true` if the given `object` object has been `contextified` using {@link createContext}.
+     * Returns `true` if the given `object` object has been contextified using {@link createContext},
+     * or if it's the global object of a context created using `vm.constants.DONT_CONTEXTIFY`.
      * @since v0.11.7
      */
     function isContext(sandbox: Context): boolean;
@@ -422,18 +450,26 @@ declare module "vm" {
      */
     function runInContext(code: string, contextifiedObject: Context, options?: RunningCodeOptions | string): any;
     /**
-     * The `vm.runInNewContext()` first contextifies the given `contextObject` (or
-     * creates a new `contextObject` if passed as `undefined`), compiles the `code`,
-     * runs it within the created context, then returns the result. Running code
-     * does not have access to the local scope.
-     *
+     * This method is a shortcut to
+     * `(new vm.Script(code, options)).runInContext(vm.createContext(options), options)`.
      * If `options` is a string, then it specifies the filename.
      *
+     * It does several things at once:
+     *
+     * 1. Creates a new context.
+     * 2. If `contextObject` is an object, contextifies it with the new context.
+     *    If  `contextObject` is undefined, creates a new object and contextifies it.
+     *    If `contextObject` is `vm.constants.DONT_CONTEXTIFY`, don't contextify anything.
+     * 3. Compiles the code as a`vm.Script`
+     * 4. Runs the compield code within the created context. The code does not have access to the scope in
+     *    which this method is called.
+     * 5. Returns the result.
+     *
      * The following example compiles and executes code that increments a global
      * variable and sets a new one. These globals are contained in the `contextObject`.
      *
      * ```js
-     * import vm from 'node:vm';
+     * const vm = require('node:vm');
      *
      * const contextObject = {
      *   animal: 'cat',
@@ -443,15 +479,21 @@ declare module "vm" {
      * vm.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);
      * ```
      * @since v0.3.1
      * @param code The JavaScript code to compile and run.
-     * @param contextObject An object that will be `contextified`. If `undefined`, a new object will be created.
+     * @param contextObject Either `vm.constants.DONT_CONTEXTIFY` or an object that will be contextified.
+     * If `undefined`, an empty contextified object will be created for backwards compatibility.
      * @return the result of the very last statement executed in the script.
      */
     function runInNewContext(
         code: string,
-        contextObject?: Context,
+        contextObject?: Context | typeof constants.DONT_CONTEXTIFY,
         options?: RunningCodeInNewContextOptions | string,
     ): any;
     /**
@@ -902,19 +944,31 @@ declare module "vm" {
     }
     /**
      * Returns an object containing commonly used constants for VM operations.
-     * @since v20.12.0
+     * @since v21.7.0, v20.12.0
      */
     namespace constants {
         /**
-         * Stability: 1.1 - Active development
-         *
          * A constant that can be used as the `importModuleDynamically` option to `vm.Script`
          * and `vm.compileFunction()` so that Node.js uses the default ESM loader from the main
          * context to load the requested module.
          *
          * For detailed information, see [Support of dynamic `import()` in compilation APIs](https://nodejs.org/docs/latest-v22.x/api/vm.html#support-of-dynamic-import-in-compilation-apis).
+         * @since v21.7.0, v20.12.0
          */
         const USE_MAIN_CONTEXT_DEFAULT_LOADER: number;
+        /**
+         * This constant, when used as the `contextObject` argument in vm APIs, instructs Node.js to create
+         * a context without wrapping its global object with another object in a Node.js-specific manner.
+         * As a result, the `globalThis` value inside the new context would behave more closely to an ordinary
+         * one.
+         *
+         * When `vm.constants.DONT_CONTEXTIFY` is used as the `contextObject` argument to {@link createContext},
+         * the returned object is a proxy-like object to the global object in the newly created context with
+         * fewer Node.js-specific quirks. It is reference equal to the `globalThis` value in the new context,
+         * can be modified from outside the context, and can be used to access built-ins in the new context directly.
+         * @since v22.8.0
+         */
+        const DONT_CONTEXTIFY: number;
     }
 }
 declare module "node:vm" {

node/worker_threads.d.ts

@@ -267,7 +267,7 @@ declare module "worker_threads" {
         trackUnmanagedFds?: boolean | undefined;
         /**
          * An optional `name` to be appended to the worker title
-         * for debuggin/identification purposes, making the final title as
+         * for debugging/identification purposes, making the final title as
          * `[worker ${id}] ${name}`.
          */
         name?: string | undefined;