🤖 Merge PR DefinitelyTyped#74607 [@types/node]: v24.12.0 by @kshitijanurag

Author: kshitijanurag

types/node/v24/child_process.d.ts

@@ -5,6 +5,7 @@
  *
  * ```js
  * import { spawn } from 'node:child_process';
+ * import { once } from 'node:events';
  * const ls = spawn('ls', ['-lh', '/usr']);
  *
  * ls.stdout.on('data', (data) => {
@@ -15,9 +16,8 @@
  *   console.error(`stderr: ${data}`);
  * });
  *
- * ls.on('close', (code) => {
- *   console.log(`child process exited with code ${code}`);
- * });
+ * const [code] = await once(ls, 'close');
+ * console.log(`child process exited with code ${code}`);
  * ```
  *
  * By default, pipes for `stdin`, `stdout`, and `stderr` are established between
@@ -719,6 +719,7 @@ declare module "child_process" {
      *
      * ```js
      * import { spawn } from 'node:child_process';
+     * import { once } from 'node:events';
      * const ls = spawn('ls', ['-lh', '/usr']);
      *
      * ls.stdout.on('data', (data) => {
@@ -729,9 +730,8 @@ declare module "child_process" {
      *   console.error(`stderr: ${data}`);
      * });
      *
-     * ls.on('close', (code) => {
-     *   console.log(`child process exited with code ${code}`);
-     * });
+     * const [code] = await once(ls, 'close');
+     * console.log(`child process exited with code ${code}`);
      * ```
      *
      * Example: A very elaborate way to run `ps ax | grep ssh`

types/node/v24/crypto.d.ts

@@ -2709,12 +2709,12 @@ declare module "crypto" {
         privateKey: T2;
     }
     /**
-     * Generates a new asymmetric key pair of the given `type`. RSA, RSA-PSS, DSA, EC,
-     * Ed25519, Ed448, X25519, X448, DH, and ML-DSA are currently supported.
+     * Generates a new asymmetric key pair of the given `type`.
+     * See the supported [asymmetric key types](https://nodejs.org/docs/latest-v24.x/api/crypto.html#asymmetric-key-types).
      *
      * If a `publicKeyEncoding` or `privateKeyEncoding` was specified, this function
-     * behaves as if `keyObject.export()` had been called on its result. Otherwise,
-     * the respective part of the key is returned as a `KeyObject`.
+     * behaves as if {@link KeyObject.export `keyObject.export()`} had been called on its result. Otherwise,
+     * the respective part of the key is returned as a {@link KeyObject `KeyObject`}.
      *
      * When encoding public keys, it is recommended to use `'spki'`. When encoding
      * private keys, it is recommended to use `'pkcs8'` with a strong passphrase,
@@ -3007,12 +3007,12 @@ declare module "crypto" {
         options?: SLHDSAKeyPairKeyObjectOptions,
     ): KeyPairKeyObjectResult;
     /**
-     * Generates a new asymmetric key pair of the given `type`. RSA, RSA-PSS, DSA, EC,
-     * Ed25519, Ed448, X25519, X448, and DH are currently supported.
+     * Generates a new asymmetric key pair of the given `type`.
+     * See the supported [asymmetric key types](https://nodejs.org/docs/latest-v24.x/api/crypto.html#asymmetric-key-types).
      *
      * If a `publicKeyEncoding` or `privateKeyEncoding` was specified, this function
-     * behaves as if `keyObject.export()` had been called on its result. Otherwise,
-     * the respective part of the key is returned as a `KeyObject`.
+     * behaves as if {@link KeyObject.export `keyObject.export()`} had been called on its result. Otherwise,
+     * the respective part of the key is returned as a {@link KeyObject `KeyObject`}.
      *
      * It is recommended to encode public keys as `'spki'` and private keys as `'pkcs8'` with encryption for long-term storage:
      *

types/node/v24/http.d.ts

@@ -357,6 +357,14 @@ declare module "http" {
          * @since v18.17.0, v20.2.0
          */
         rejectNonStandardBodyWrites?: boolean | undefined;
+        /**
+         * If set to `true`, requests without `Content-Length` or `Transfer-Encoding` headers (indicating no body)
+         * will be initialized with an already-ended body stream, so they will never emit any stream events
+         * (like `'data'` or `'end'`). You can use `req.readableEnded` to detect this case.
+         * @default false
+         * @since v24.12.0
+         */
+        optimizeEmptyRequests?: boolean | undefined;
     }
     type RequestListener<
         Request extends typeof IncomingMessage = typeof IncomingMessage,
@@ -1020,6 +1028,7 @@ declare module "http" {
          *
          * ```js
          * import http from 'node:http';
+         * const agent = new http.Agent({ keepAlive: true });
          *
          * // Server has a 5 seconds keep-alive timeout by default
          * http
@@ -1661,20 +1670,31 @@ declare module "http" {
         /**
          * Produces a socket/stream to be used for HTTP requests.
          *
-         * By default, this function is the same as `net.createConnection()`. However,
-         * custom agents may override this method in case greater flexibility is desired.
+         * By default, this function behaves identically to `net.createConnection()`, synchronously
+         * returning the created socket. The optional `callback` parameter in the signature is not
+         * used by this default implementation.
          *
-         * A socket/stream can be supplied in one of two ways: by returning the
-         * socket/stream from this function, or by passing the socket/stream to `callback`.
+         * However, custom agents may override this method to provide greater flexibility,
+         * for example, to create sockets asynchronously. When overriding `createConnection`:
          *
-         * This method is guaranteed to return an instance of the `net.Socket` class,
-         * a subclass of `stream.Duplex`, unless the user specifies a socket
-         * type other than `net.Socket`.
+         * 1. **Synchronous socket creation**: The overriding method can return the socket/stream directly.
+         * 2. **Asynchronous socket creation**: The overriding method can accept the `callback` and pass
+         * the created socket/stream to it (e.g., `callback(null, newSocket)`). If an error occurs during
+         * socket creation, it should be passed as the first argument to the `callback` (e.g., `callback(err)`).
          *
-         * `callback` has a signature of `(err, stream)`.
+         * The agent will call the provided `createConnection` function with `options` and this internal
+         * `callback`. The `callback` provided by the agent has a signature of `(err, stream)`.
          * @since v0.11.4
-         * @param options Options containing connection details. Check `createConnection` for the format of the options
-         * @param callback Callback function that receives the created socket
+         * @param options Options containing connection details. Check `net.createConnection()`
+         *                for the format of the options. For custom agents, this object is passed
+         *                to the custom `createConnection` function.
+         * @param callback (Optional, primarily for custom agents) A function to be called by a custom
+         *                 `createConnection` implementation when the socket is created, especially for
+         *                 asynchronous operations.
+         * @returns `stream.Duplex` The created socket. This is returned by the default implementation
+         *                          or by a custom synchronous `createConnection` implementation. If a
+         *                          custom `createConnection` uses the `callback` for asynchronous operation,
+         *                          this return value might not be the primary way to obtain the socket.
          */
         createConnection(
             options: ClientRequestArgs,

types/node/v24/https.d.ts

@@ -25,6 +25,12 @@ declare module "https" {
     }
     /**
      * An `Agent` object for HTTPS similar to `http.Agent`. See {@link request} for more information.
+     *
+     * Like `http.Agent`, the `createConnection(options[, callback])` method can be overridden to customize
+     * how TLS connections are established.
+     *
+     * > See [`agent.createConnection()`](https://nodejs.org/docs/latest-v24.x/api/http.html#agentcreateconnectionoptions-callback)
+     * for details on overriding this method, including asynchronous socket creation with a callback.
      * @since v0.4.5
      */
     class Agent extends http.Agent {

types/node/v24/module.d.ts

@@ -80,37 +80,48 @@ declare module "module" {
              */
             directory?: string;
         }
+        interface EnableCompileCacheOptions {
+            /**
+             * Optional. Directory to store the compile cache. If not specified, the directory specified by
+             * the [`NODE_COMPILE_CACHE=dir`](https://nodejs.org/docs/latest-v24.x/api/cli.html#node_compile_cachedir)
+             * environment variable will be used if it's set, or `path.join(os.tmpdir(), 'node-compile-cache')` otherwise.
+             * @since v24.12.0
+             */
+            directory?: string | undefined;
+            /**
+             * Optional. If `true`, enables portable compile cache so that the cache can be reused even if the project directory
+             * is moved. This is a best-effort feature. If not specified, it will depend on whether the environment variable
+             * [NODE_COMPILE_CACHE_PORTABLE=1](https://nodejs.org/docs/latest-v24.x/api/cli.html#node_compile_cache_portable1) is set.
+             * @since v24.12.0
+             */
+            portable?: boolean | undefined;
+        }
         /**
          * Enable [module compile cache](https://nodejs.org/docs/latest-v24.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
+         * For general use cases, it's recommended to call `module.enableCompileCache()` without specifying the
+         * `options.directory`, 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
+         * Since compile cache is supposed to be a optimization that is not mission critical, 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-v24.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}.
+         * `directory` field returned by this method, or with {@link getCompileCacheDir `module.getCompileCacheDir()`}.
          * @since v22.8.0
-         * @param cacheDir Optional path to specify the directory where the compile cache
+         * @param options Optional. If a string is passed, it is considered to be `options.directory`.
          * will be stored/retrieved.
          */
-        function enableCompileCache(cacheDir?: string): EnableCompileCacheResult;
+        function enableCompileCache(options?: string | EnableCompileCacheOptions): EnableCompileCacheResult;
         /**
          * Flush the [module compile cache](https://nodejs.org/docs/latest-v24.x/api/module.html#module-compile-cache)
          * accumulated from modules already loaded

types/node/v24/package.json

@@ -1,7 +1,7 @@
 {
     "private": true,
     "name": "@types/node",
-    "version": "24.11.9999",
+    "version": "24.12.9999",
     "nonNpm": "conflict",
     "nonNpmDescription": "Node.js",
     "projects": [