@types/node - npm Package Compare versions

Comparing version 22.7.9 to 22.8.0

node/module.d.ts

@@ -241,2 +241,38 @@ /**
         ) => 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;
+            }
+        }
     }
@@ -248,2 +284,20 @@ interface RegisterOptions<Data> {
     }
+    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 {}
@@ -263,2 +317,39 @@ class Module {
         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);
@@ -265,0 +356,0 @@ }

node/package.json

 {
     "name": "@types/node",
-    "version": "22.7.9",
+    "version": "22.8.0",
     "description": "TypeScript definitions for node",
@@ -220,7 +220,7 @@ "homepage": "https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/node",
     "dependencies": {
-        "undici-types": "~6.19.2"
+        "undici-types": "~6.19.8"
     },
     "peerDependencies": {},
-    "typesPublisherContentHash": "49b712614616bc7f8a0b0f6596d6add73e659a4a4d0695f61e4ab90a468876d3",
+    "typesPublisherContentHash": "6b33d9eaa9566c6f6d63bb36c4bda33e9a42edb78634926e6442dbc972a1c8b0",
     "typeScriptVersion": "4.8"
 }

node/perf_hooks.d.ts

@@ -119,2 +119,16 @@ /**
     }
+    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;
+    }
     /**
@@ -171,2 +185,12 @@ * _This property is an extension by Node.js. It is not available in Web browsers._
         /**
+         * 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
@@ -173,0 +197,0 @@ * initialized.

node/README.md

@@ -11,3 +11,3 @@ # Installation
 ### Additional Details
- * Last updated: Wed, 23 Oct 2024 03:36:41 GMT
+ * Last updated: Fri, 25 Oct 2024 12:43:47 GMT
  * Dependencies: [undici-types](https://npmjs.com/package/undici-types)
@@ -14,0 +14,0 @@

node/vm.d.ts

@@ -233,6 +233,13 @@ /**
         /**
-         * 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
@@ -243,3 +250,3 @@ * the code multiple times in different contexts. The globals are set on and
          * ```js
-         * import vm from 'node:vm';
+         * const vm = require('node:vm');
          *
@@ -255,8 +262,18 @@ * const script = new vm.Script('globalVar = "set"');
          * // 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;
         /**
@@ -353,13 +370,13 @@ * Runs the compiled code contained by the `vm.Script` within the context of the
     /**
-     * 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');
      *
@@ -381,4 +398,9 @@ * global.globalVar = 3;
      * 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
@@ -393,7 +415,13 @@ * context that can be used to run multiple scripts. For instance, if emulating a
      * @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
@@ -431,9 +459,17 @@ */
     /**
-     * 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
@@ -443,3 +479,3 @@ * variable and sets a new one. These globals are contained in the `contextObject`.
      * ```js
-     * import vm from 'node:vm';
+     * const vm = require('node:vm');
      *
@@ -454,6 +490,12 @@ * const 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.
@@ -463,3 +505,3 @@ */
         code: string,
-        contextObject?: Context,
+        contextObject?: Context | typeof constants.DONT_CONTEXTIFY,
         options?: RunningCodeInNewContextOptions | string,
@@ -915,8 +957,6 @@ ): any;
      * 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`
@@ -927,4 +967,18 @@ * and `vm.compileFunction()` so that Node.js uses the default ESM loader from the main
          * 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;
     }
@@ -931,0 +985,0 @@ }

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

2268735

increased by0.45%

Lines of code

50187

increased by0.36%

Worsened metrics

Published versions last two months

68

decreased by-4.23%

Dependency changes

• Updatedundici-types@~6.19.8