diff --git a/types/node/assert.d.ts b/types/node/assert.d.ts index 9b7144eeefc029..c4cc77e432da08 100644 --- a/types/node/assert.d.ts +++ b/types/node/assert.d.ts @@ -1,8 +1,3 @@ -/** - * The `node:assert` module provides a set of assertion functions for verifying - * invariants. - * @see [source](https://github.com/nodejs/node/blob/v25.x/lib/assert.js) - */ declare module "node:assert" { import strict = require("node:assert/strict"); /** diff --git a/types/node/assert/strict.d.ts b/types/node/assert/strict.d.ts index 51bb35201211b9..7a9dcf5714b860 100644 --- a/types/node/assert/strict.d.ts +++ b/types/node/assert/strict.d.ts @@ -1,49 +1,3 @@ -/** - * In strict assertion mode, non-strict methods behave like their corresponding - * strict methods. For example, `assert.deepEqual()` will behave like - * `assert.deepStrictEqual()`. - * - * In strict assertion mode, error messages for objects display a diff. In legacy - * assertion mode, error messages for objects display the objects, often truncated. - * - * To use strict assertion mode: - * - * ```js - * import { strict as assert } from 'node:assert'; - * ``` - * - * ```js - * import assert from 'node:assert/strict'; - * ``` - * - * Example error diff: - * - * ```js - * import { strict as assert } from 'node:assert'; - * - * assert.deepEqual([[[1, 2, 3]], 4, 5], [[[1, 2, '3']], 4, 5]); - * // AssertionError: Expected inputs to be strictly deep-equal: - * // + actual - expected ... Lines skipped - * // - * // [ - * // [ - * // ... - * // 2, - * // + 3 - * // - '3' - * // ], - * // ... - * // 5 - * // ] - * ``` - * - * To deactivate the colors, use the `NO_COLOR` or `NODE_DISABLE_COLORS` - * environment variables. This will also deactivate the colors in the REPL. For - * more on color support in terminal environments, read the tty - * [`getColorDepth()`](https://nodejs.org/docs/latest-v25.x/api/tty.html#writestreamgetcolordepthenv) documentation. - * @since v15.0.0 - * @see [source](https://github.com/nodejs/node/blob/v25.x/lib/assert/strict.js) - */ declare module "node:assert/strict" { import { Assert, diff --git a/types/node/async_hooks.d.ts b/types/node/async_hooks.d.ts index aa692c1060a5f2..bb82b8a3f0b16f 100644 --- a/types/node/async_hooks.d.ts +++ b/types/node/async_hooks.d.ts @@ -1,19 +1,3 @@ -/** - * We strongly discourage the use of the `async_hooks` API. - * Other APIs that can cover most of its use cases include: - * - * * [`AsyncLocalStorage`](https://nodejs.org/docs/latest-v25.x/api/async_context.html#class-asynclocalstorage) tracks async context - * * [`process.getActiveResourcesInfo()`](https://nodejs.org/docs/latest-v25.x/api/process.html#processgetactiveresourcesinfo) tracks active resources - * - * The `node:async_hooks` module provides an API to track asynchronous resources. - * It can be accessed using: - * - * ```js - * import async_hooks from 'node:async_hooks'; - * ``` - * @experimental - * @see [source](https://github.com/nodejs/node/blob/v25.x/lib/async_hooks.js) - */ declare module "node:async_hooks" { /** * ```js @@ -123,37 +107,31 @@ declare module "node:async_hooks" { function triggerAsyncId(): number; interface HookCallbacks { /** - * Called when a class is constructed that has the possibility to emit an asynchronous event. - * @param asyncId A unique ID for the async resource - * @param type The type of the async resource - * @param triggerAsyncId The unique ID of the async resource in whose execution context this async resource was created - * @param resource Reference to the resource representing the async operation, needs to be released during destroy + * The [`init` callback](https://nodejs.org/docs/latest-v25.x/api/async_hooks.html#initasyncid-type-triggerasyncid-resource). */ init?(asyncId: number, type: string, triggerAsyncId: number, resource: object): void; /** - * When an asynchronous operation is initiated or completes a callback is called to notify the user. - * The before callback is called just before said callback is executed. - * @param asyncId the unique identifier assigned to the resource about to execute the callback. + * The [`before` callback](https://nodejs.org/docs/latest-v25.x/api/async_hooks.html#beforeasyncid). */ before?(asyncId: number): void; /** - * Called immediately after the callback specified in `before` is completed. - * - * If an uncaught exception occurs during execution of the callback, then `after` will run after the `'uncaughtException'` event is emitted or a `domain`'s handler runs. - * @param asyncId the unique identifier assigned to the resource which has executed the callback. + * The [`after` callback](https://nodejs.org/docs/latest-v25.x/api/async_hooks.html#afterasyncid). */ after?(asyncId: number): void; /** - * Called when a promise has resolve() called. This may not be in the same execution id - * as the promise itself. - * @param asyncId the unique id for the promise that was resolve()d. + * The [`promiseResolve` callback](https://nodejs.org/docs/latest-v25.x/api/async_hooks.html#promiseresolveasyncid). */ promiseResolve?(asyncId: number): void; /** - * Called after the resource corresponding to asyncId is destroyed - * @param asyncId a unique ID for the async resource + * The [`destroy` callback](https://nodejs.org/docs/latest-v25.x/api/async_hooks.html#destroyasyncid). */ destroy?(asyncId: number): void; + /** + * Whether the hook should track `Promise`s. Cannot be `false` if + * `promiseResolve` is set. + * @default true + */ + trackPromises?: boolean | undefined; } interface AsyncHook { /** @@ -174,7 +152,8 @@ declare module "node:async_hooks" { * * All callbacks are optional. For example, if only resource cleanup needs to * be tracked, then only the `destroy` callback needs to be passed. The - * specifics of all functions that can be passed to `callbacks` is in the `Hook Callbacks` section. + * specifics of all functions that can be passed to `callbacks` is in the + * [Hook Callbacks](https://nodejs.org/docs/latest-v25.x/api/async_hooks.html#hook-callbacks) section. * * ```js * import { createHook } from 'node:async_hooks'; @@ -202,12 +181,13 @@ declare module "node:async_hooks" { * ``` * * Because promises are asynchronous resources whose lifecycle is tracked - * via the async hooks mechanism, the `init()`, `before()`, `after()`, and`destroy()` callbacks _must not_ be async functions that return promises. + * via the async hooks mechanism, the `init()`, `before()`, `after()`, and + * `destroy()` callbacks _must not_ be async functions that return promises. * @since v8.1.0 - * @param callbacks The `Hook Callbacks` to register - * @return Instance used for disabling and enabling hooks + * @param options The [Hook Callbacks](https://nodejs.org/docs/latest-v25.x/api/async_hooks.html#hook-callbacks) to register + * @returns Instance used for disabling and enabling hooks */ - function createHook(callbacks: HookCallbacks): AsyncHook; + function createHook(options: HookCallbacks): AsyncHook; interface AsyncResourceOptions { /** * The ID of the execution context that created this async event. diff --git a/types/node/buffer.buffer.d.ts b/types/node/buffer.buffer.d.ts index a3c23046ced397..a6c4b256c987aa 100644 --- a/types/node/buffer.buffer.d.ts +++ b/types/node/buffer.buffer.d.ts @@ -174,7 +174,7 @@ declare module "node:buffer" { * If `totalLength` is not provided, it is calculated from the `Buffer` instances * in `list` by adding their lengths. * - * If `totalLength` is provided, it is coerced to an unsigned integer. If the + * If `totalLength` is provided, it must be an unsigned integer. If the * combined length of the `Buffer`s in `list` exceeds `totalLength`, the result is * truncated to `totalLength`. If the combined length of the `Buffer`s in `list` is * less than `totalLength`, the remaining space is filled with zeros. diff --git a/types/node/buffer.d.ts b/types/node/buffer.d.ts index bb0f00441de594..7cff31fa790754 100644 --- a/types/node/buffer.d.ts +++ b/types/node/buffer.d.ts @@ -1,48 +1,3 @@ -/** - * `Buffer` objects are used to represent a fixed-length sequence of bytes. Many - * Node.js APIs support `Buffer`s. - * - * The `Buffer` class is a subclass of JavaScript's [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) class and - * extends it with methods that cover additional use cases. Node.js APIs accept - * plain [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) s wherever `Buffer`s are supported as well. - * - * While the `Buffer` class is available within the global scope, it is still - * recommended to explicitly reference it via an import or require statement. - * - * ```js - * import { Buffer } from 'node:buffer'; - * - * // Creates a zero-filled Buffer of length 10. - * const buf1 = Buffer.alloc(10); - * - * // Creates a Buffer of length 10, - * // filled with bytes which all have the value `1`. - * const buf2 = Buffer.alloc(10, 1); - * - * // Creates an uninitialized buffer of length 10. - * // This is faster than calling Buffer.alloc() but the returned - * // Buffer instance might contain old data that needs to be - * // overwritten using fill(), write(), or other functions that fill the Buffer's - * // contents. - * const buf3 = Buffer.allocUnsafe(10); - * - * // Creates a Buffer containing the bytes [1, 2, 3]. - * const buf4 = Buffer.from([1, 2, 3]); - * - * // Creates a Buffer containing the bytes [1, 1, 1, 1] – the entries - * // are all truncated using `(value & 255)` to fit into the range 0–255. - * const buf5 = Buffer.from([257, 257.5, -255, '1']); - * - * // Creates a Buffer containing the UTF-8-encoded bytes for the string 'tést': - * // [0x74, 0xc3, 0xa9, 0x73, 0x74] (in hexadecimal notation) - * // [116, 195, 169, 115, 116] (in decimal notation) - * const buf6 = Buffer.from('tést'); - * - * // Creates a Buffer containing the Latin-1 bytes [0x74, 0xe9, 0x73, 0x74]. - * const buf7 = Buffer.from('tést', 'latin1'); - * ``` - * @see [source](https://github.com/nodejs/node/blob/v25.x/lib/buffer.js) - */ declare module "node:buffer" { import { ReadableStream } from "node:stream/web"; /** diff --git a/types/node/child_process.d.ts b/types/node/child_process.d.ts index d71fed18def569..e3964ab96fba03 100644 --- a/types/node/child_process.d.ts +++ b/types/node/child_process.d.ts @@ -1,70 +1,3 @@ -/** - * The `node:child_process` module provides the ability to spawn subprocesses in - * a manner that is similar, but not identical, to [`popen(3)`](http://man7.org/linux/man-pages/man3/popen.3.html). This capability - * is primarily provided by the {@link spawn} function: - * - * ```js - * import { spawn } from 'node:child_process'; - * import { once } from 'node:events'; - * const ls = spawn('ls', ['-lh', '/usr']); - * - * ls.stdout.on('data', (data) => { - * console.log(`stdout: ${data}`); - * }); - * - * ls.stderr.on('data', (data) => { - * console.error(`stderr: ${data}`); - * }); - * - * 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 - * the parent Node.js process and the spawned subprocess. These pipes have - * limited (and platform-specific) capacity. If the subprocess writes to - * stdout in excess of that limit without the output being captured, the - * subprocess blocks, waiting for the pipe buffer to accept more data. This is - * identical to the behavior of pipes in the shell. Use the `{ stdio: 'ignore' }` option if the output will not be consumed. - * - * The command lookup is performed using the `options.env.PATH` environment - * variable if `env` is in the `options` object. Otherwise, `process.env.PATH` is - * used. If `options.env` is set without `PATH`, lookup on Unix is performed - * on a default search path search of `/usr/bin:/bin` (see your operating system's - * manual for execvpe/execvp), on Windows the current processes environment - * variable `PATH` is used. - * - * On Windows, environment variables are case-insensitive. Node.js - * lexicographically sorts the `env` keys and uses the first one that - * case-insensitively matches. Only first (in lexicographic order) entry will be - * passed to the subprocess. This might lead to issues on Windows when passing - * objects to the `env` option that have multiple variants of the same key, such as `PATH` and `Path`. - * - * The {@link spawn} method spawns the child process asynchronously, - * without blocking the Node.js event loop. The {@link spawnSync} function provides equivalent functionality in a synchronous manner that blocks - * the event loop until the spawned process either exits or is terminated. - * - * For convenience, the `node:child_process` module provides a handful of - * synchronous and asynchronous alternatives to {@link spawn} and {@link spawnSync}. Each of these alternatives are implemented on - * top of {@link spawn} or {@link spawnSync}. - * - * * {@link exec}: spawns a shell and runs a command within that - * shell, passing the `stdout` and `stderr` to a callback function when - * complete. - * * {@link execFile}: similar to {@link exec} except - * that it spawns the command directly without first spawning a shell by - * default. - * * {@link fork}: spawns a new Node.js process and invokes a - * specified module with an IPC communication channel established that allows - * sending messages between parent and child. - * * {@link execSync}: a synchronous version of {@link exec} that will block the Node.js event loop. - * * {@link execFileSync}: a synchronous version of {@link execFile} that will block the Node.js event loop. - * - * For certain use cases, such as automating shell scripts, the `synchronous counterparts` may be more convenient. In many cases, however, - * the synchronous methods can have significant impact on performance due to - * stalling the event loop while spawned processes complete. - * @see [source](https://github.com/nodejs/node/blob/v25.x/lib/child_process.js) - */ declare module "node:child_process" { import { NonSharedBuffer } from "node:buffer"; import * as dgram from "node:dgram"; diff --git a/types/node/cluster.d.ts b/types/node/cluster.d.ts index 4e5efbfb54c106..80f55aeb71c91c 100644 --- a/types/node/cluster.d.ts +++ b/types/node/cluster.d.ts @@ -1,57 +1,3 @@ -/** - * Clusters of Node.js processes can be used to run multiple instances of Node.js - * that can distribute workloads among their application threads. When process isolation - * is not needed, use the [`worker_threads`](https://nodejs.org/docs/latest-v25.x/api/worker_threads.html) - * module instead, which allows running multiple application threads within a single Node.js instance. - * - * The cluster module allows easy creation of child processes that all share - * server ports. - * - * ```js - * import cluster from 'node:cluster'; - * import http from 'node:http'; - * import { availableParallelism } from 'node:os'; - * import process from 'node:process'; - * - * const numCPUs = availableParallelism(); - * - * if (cluster.isPrimary) { - * console.log(`Primary ${process.pid} is running`); - * - * // Fork workers. - * for (let i = 0; i < numCPUs; i++) { - * cluster.fork(); - * } - * - * cluster.on('exit', (worker, code, signal) => { - * console.log(`worker ${worker.process.pid} died`); - * }); - * } else { - * // Workers can share any TCP connection - * // In this case it is an HTTP server - * http.createServer((req, res) => { - * res.writeHead(200); - * res.end('hello world\n'); - * }).listen(8000); - * - * console.log(`Worker ${process.pid} started`); - * } - * ``` - * - * Running Node.js will now share port 8000 between the workers: - * - * ```console - * $ node server.js - * Primary 3596 is running - * Worker 4324 started - * Worker 4520 started - * Worker 6056 started - * Worker 5644 started - * ``` - * - * On Windows, it is not yet possible to set up a named pipe server in a worker. - * @see [source](https://github.com/nodejs/node/blob/v25.x/lib/cluster.js) - */ declare module "node:cluster" { import * as child_process from "node:child_process"; import { EventEmitter, InternalEventEmitter } from "node:events"; diff --git a/types/node/console.d.ts b/types/node/console.d.ts index 394344214f86a7..b7f883363a1b6e 100644 --- a/types/node/console.d.ts +++ b/types/node/console.d.ts @@ -1,61 +1,3 @@ -/** - * The `node:console` module provides a simple debugging console that is similar to - * the JavaScript console mechanism provided by web browsers. - * - * The module exports two specific components: - * - * * A `Console` class with methods such as `console.log()`, `console.error()`, and `console.warn()` that can be used to write to any Node.js stream. - * * A global `console` instance configured to write to [`process.stdout`](https://nodejs.org/docs/latest-v25.x/api/process.html#processstdout) and - * [`process.stderr`](https://nodejs.org/docs/latest-v25.x/api/process.html#processstderr). The global `console` can be used without importing the `node:console` module. - * - * _**Warning**_: The global console object's methods are neither consistently - * synchronous like the browser APIs they resemble, nor are they consistently - * asynchronous like all other Node.js streams. See the [`note on process I/O`](https://nodejs.org/docs/latest-v25.x/api/process.html#a-note-on-process-io) for - * more information. - * - * Example using the global `console`: - * - * ```js - * console.log('hello world'); - * // Prints: hello world, to stdout - * console.log('hello %s', 'world'); - * // Prints: hello world, to stdout - * console.error(new Error('Whoops, something bad happened')); - * // Prints error message and stack trace to stderr: - * // Error: Whoops, something bad happened - * // at [eval]:5:15 - * // at Script.runInThisContext (node:vm:132:18) - * // at Object.runInThisContext (node:vm:309:38) - * // at node:internal/process/execution:77:19 - * // at [eval]-wrapper:6:22 - * // at evalScript (node:internal/process/execution:76:60) - * // at node:internal/main/eval_string:23:3 - * - * const name = 'Will Robinson'; - * console.warn(`Danger ${name}! Danger!`); - * // Prints: Danger Will Robinson! Danger!, to stderr - * ``` - * - * Example using the `Console` class: - * - * ```js - * const out = getStreamSomehow(); - * const err = getStreamSomehow(); - * const myConsole = new console.Console(out, err); - * - * myConsole.log('hello world'); - * // Prints: hello world, to out - * myConsole.log('hello %s', 'world'); - * // Prints: hello world, to out - * myConsole.error(new Error('Whoops, something bad happened')); - * // Prints: [Error: Whoops, something bad happened], to err - * - * const name = 'Will Robinson'; - * myConsole.warn(`Danger ${name}! Danger!`); - * // Prints: Danger Will Robinson! Danger!, to err - * ``` - * @see [source](https://github.com/nodejs/node/blob/v25.x/lib/console.js) - */ declare module "node:console" { import { InspectOptions } from "node:util"; namespace console { diff --git a/types/node/constants.d.ts b/types/node/constants.d.ts index c24ad989a21e15..a271f9aaad1944 100644 --- a/types/node/constants.d.ts +++ b/types/node/constants.d.ts @@ -1,9 +1,3 @@ -/** - * @deprecated The `node:constants` module is deprecated. When requiring access to constants - * relevant to specific Node.js builtin modules, developers should instead refer - * to the `constants` property exposed by the relevant module. For instance, - * `require('node:fs').constants` and `require('node:os').constants`. - */ declare module "node:constants" { const constants: & typeof import("node:os").constants.dlopen diff --git a/types/node/crypto.d.ts b/types/node/crypto.d.ts index 15b46ce0dc87b8..3ebfec684c2cb7 100644 --- a/types/node/crypto.d.ts +++ b/types/node/crypto.d.ts @@ -1,21 +1,3 @@ -/** - * The `node:crypto` module provides cryptographic functionality that includes a - * set of wrappers for OpenSSL's hash, HMAC, cipher, decipher, sign, and verify - * functions. - * - * ```js - * const { createHmac } = await import('node:crypto'); - * - * const secret = 'abcdefg'; - * const hash = createHmac('sha256', secret) - * .update('I love cupcakes') - * .digest('hex'); - * console.log(hash); - * // Prints: - * // c0fa1bc00531bd78ef38c628449c5102aeabd49b5dc3a2a516ea6ea959d6658e - * ``` - * @see [source](https://github.com/nodejs/node/blob/v25.x/lib/crypto.js) - */ declare module "node:crypto" { import { NonSharedBuffer } from "node:buffer"; import * as stream from "node:stream"; diff --git a/types/node/dgram.d.ts b/types/node/dgram.d.ts index 3672e08b892151..8665497b4ef202 100644 --- a/types/node/dgram.d.ts +++ b/types/node/dgram.d.ts @@ -1,30 +1,3 @@ -/** - * The `node:dgram` module provides an implementation of UDP datagram sockets. - * - * ```js - * import dgram from 'node:dgram'; - * - * const server = dgram.createSocket('udp4'); - * - * server.on('error', (err) => { - * console.error(`server error:\n${err.stack}`); - * server.close(); - * }); - * - * server.on('message', (msg, rinfo) => { - * console.log(`server got: ${msg} from ${rinfo.address}:${rinfo.port}`); - * }); - * - * server.on('listening', () => { - * const address = server.address(); - * console.log(`server listening ${address.address}:${address.port}`); - * }); - * - * server.bind(41234); - * // Prints: server listening 0.0.0.0:41234 - * ``` - * @see [source](https://github.com/nodejs/node/blob/v25.x/lib/dgram.js) - */ declare module "node:dgram" { import { NonSharedBuffer } from "node:buffer"; import * as dns from "node:dns"; diff --git a/types/node/diagnostics_channel.d.ts b/types/node/diagnostics_channel.d.ts index 206592bd0392fe..fa8361272e6c75 100644 --- a/types/node/diagnostics_channel.d.ts +++ b/types/node/diagnostics_channel.d.ts @@ -1,27 +1,3 @@ -/** - * The `node:diagnostics_channel` module provides an API to create named channels - * to report arbitrary message data for diagnostics purposes. - * - * It can be accessed using: - * - * ```js - * import diagnostics_channel from 'node:diagnostics_channel'; - * ``` - * - * It is intended that a module writer wanting to report diagnostics messages - * will create one or many top-level channels to report messages through. - * Channels may also be acquired at runtime but it is not encouraged - * due to the additional overhead of doing so. Channels may be exported for - * convenience, but as long as the name is known it can be acquired anywhere. - * - * If you intend for your module to produce diagnostics data for others to - * consume it is recommended that you include documentation of what named - * channels are used along with the shape of the message data. Channel names - * should generally include the module name to avoid collisions with data from - * other modules. - * @since v15.1.0, v14.17.0 - * @see [source](https://github.com/nodejs/node/blob/v25.x/lib/diagnostics_channel.js) - */ declare module "node:diagnostics_channel" { import { AsyncLocalStorage } from "node:async_hooks"; /** diff --git a/types/node/dns.d.ts b/types/node/dns.d.ts index 80a2272c76068b..2e0941e58e1c3c 100644 --- a/types/node/dns.d.ts +++ b/types/node/dns.d.ts @@ -1,49 +1,3 @@ -/** - * The `node:dns` module enables name resolution. For example, use it to look up IP - * addresses of host names. - * - * Although named for the [Domain Name System (DNS)](https://en.wikipedia.org/wiki/Domain_Name_System), it does not always use the - * DNS protocol for lookups. {@link lookup} uses the operating system - * facilities to perform name resolution. It may not need to perform any network - * communication. To perform name resolution the way other applications on the same - * system do, use {@link lookup}. - * - * ```js - * import dns from 'node:dns'; - * - * dns.lookup('example.org', (err, address, family) => { - * console.log('address: %j family: IPv%s', address, family); - * }); - * // address: "93.184.216.34" family: IPv4 - * ``` - * - * All other functions in the `node:dns` module connect to an actual DNS server to - * perform name resolution. They will always use the network to perform DNS - * queries. These functions do not use the same set of configuration files used by {@link lookup} (e.g. `/etc/hosts`). Use these functions to always perform - * DNS queries, bypassing other name-resolution facilities. - * - * ```js - * import dns from 'node:dns'; - * - * dns.resolve4('archive.org', (err, addresses) => { - * if (err) throw err; - * - * console.log(`addresses: ${JSON.stringify(addresses)}`); - * - * addresses.forEach((a) => { - * dns.reverse(a, (err, hostnames) => { - * if (err) { - * throw err; - * } - * console.log(`reverse for ${a}: ${JSON.stringify(hostnames)}`); - * }); - * }); - * }); - * ``` - * - * See the [Implementation considerations section](https://nodejs.org/docs/latest-v25.x/api/dns.html#implementation-considerations) for more information. - * @see [source](https://github.com/nodejs/node/blob/v25.x/lib/dns.js) - */ declare module "node:dns" { // Supported getaddrinfo flags. /** diff --git a/types/node/dns/promises.d.ts b/types/node/dns/promises.d.ts index 8d5f98989b1a7c..b9e091caf47394 100644 --- a/types/node/dns/promises.d.ts +++ b/types/node/dns/promises.d.ts @@ -1,9 +1,3 @@ -/** - * The `dns.promises` API provides an alternative set of asynchronous DNS methods - * that return `Promise` objects rather than using callbacks. The API is accessible - * via `import { promises as dnsPromises } from 'node:dns'` or `import dnsPromises from 'node:dns/promises'`. - * @since v10.6.0 - */ declare module "node:dns/promises" { import { AnyRecord, diff --git a/types/node/domain.d.ts b/types/node/domain.d.ts index 24a098140a6c64..8e03a7d6db6ea2 100644 --- a/types/node/domain.d.ts +++ b/types/node/domain.d.ts @@ -1,19 +1,3 @@ -/** - * **This module is pending deprecation.** Once a replacement API has been - * finalized, this module will be fully deprecated. Most developers should - * **not** have cause to use this module. Users who absolutely must have - * the functionality that domains provide may rely on it for the time being - * but should expect to have to migrate to a different solution - * in the future. - * - * Domains provide a way to handle multiple different IO operations as a - * single group. If any of the event emitters or callbacks registered to a - * domain emit an `'error'` event, or throw an error, then the domain object - * will be notified, rather than losing the context of the error in the `process.on('uncaughtException')` handler, or causing the program to - * exit immediately with an error code. - * @deprecated Since v1.4.2 - Deprecated - * @see [source](https://github.com/nodejs/node/blob/v25.x/lib/domain.js) - */ declare module "node:domain" { import { EventEmitter } from "node:events"; /** diff --git a/types/node/events.d.ts b/types/node/events.d.ts index 6870cf5b1388dc..b4cd8c3d41dbe6 100644 --- a/types/node/events.d.ts +++ b/types/node/events.d.ts @@ -1,39 +1,3 @@ -/** - * Much of the Node.js core API is built around an idiomatic asynchronous - * event-driven architecture in which certain kinds of objects (called "emitters") - * emit named events that cause `Function` objects ("listeners") to be called. - * - * For instance: a `net.Server` object emits an event each time a peer - * connects to it; a `fs.ReadStream` emits an event when the file is opened; - * a `stream` emits an event whenever data is available to be read. - * - * All objects that emit events are instances of the `EventEmitter` class. These - * objects expose an `eventEmitter.on()` function that allows one or more - * functions to be attached to named events emitted by the object. Typically, - * event names are camel-cased strings but any valid JavaScript property key - * can be used. - * - * When the `EventEmitter` object emits an event, all of the functions attached - * to that specific event are called _synchronously_. Any values returned by the - * called listeners are _ignored_ and discarded. - * - * The following example shows a simple `EventEmitter` instance with a single - * listener. The `eventEmitter.on()` method is used to register listeners, while - * the `eventEmitter.emit()` method is used to trigger the event. - * - * ```js - * import { EventEmitter } from 'node:events'; - * - * class MyEmitter extends EventEmitter {} - * - * const myEmitter = new MyEmitter(); - * myEmitter.on('event', () => { - * console.log('an event occurred!'); - * }); - * myEmitter.emit('event'); - * ``` - * @see [source](https://github.com/nodejs/node/blob/v25.x/lib/events.js) - */ declare module "node:events" { import { AsyncResource, AsyncResourceOptions } from "node:async_hooks"; // #region Event map helpers diff --git a/types/node/fs.d.ts b/types/node/fs.d.ts index 4e16bbc7aaa95c..b74033c8d504e3 100644 --- a/types/node/fs.d.ts +++ b/types/node/fs.d.ts @@ -1,23 +1,3 @@ -/** - * The `node:fs` module enables interacting with the file system in a - * way modeled on standard POSIX functions. - * - * To use the promise-based APIs: - * - * ```js - * import * as fs from 'node:fs/promises'; - * ``` - * - * To use the callback and sync APIs: - * - * ```js - * import * as fs from 'node:fs'; - * ``` - * - * All file system operations have synchronous, callback, and promise-based - * forms, and are accessible using both CommonJS syntax and ES6 Modules (ESM). - * @see [source](https://github.com/nodejs/node/blob/v25.x/lib/fs.js) - */ declare module "node:fs" { import { NonSharedBuffer } from "node:buffer"; import { Abortable, EventEmitter, InternalEventEmitter } from "node:events"; diff --git a/types/node/fs/promises.d.ts b/types/node/fs/promises.d.ts index e4d249d9924193..419112a5b6ada1 100644 --- a/types/node/fs/promises.d.ts +++ b/types/node/fs/promises.d.ts @@ -1,13 +1,3 @@ -/** - * The `fs/promises` API provides asynchronous file system methods that return - * promises. - * - * The promise APIs use the underlying Node.js threadpool to perform file - * system operations off the event loop thread. These operations are not - * synchronized or threadsafe. Care must be taken when performing multiple - * concurrent modifications on the same file or data corruption may occur. - * @since v10.0.0 - */ declare module "node:fs/promises" { import { NonSharedBuffer } from "node:buffer"; import { Abortable } from "node:events"; diff --git a/types/node/http.d.ts b/types/node/http.d.ts index f88f49f54a963c..c2e00e7c2fce77 100644 --- a/types/node/http.d.ts +++ b/types/node/http.d.ts @@ -1,44 +1,3 @@ -/** - * To use the HTTP server and client one must import the `node:http` module. - * - * The HTTP interfaces in Node.js are designed to support many features - * of the protocol which have been traditionally difficult to use. - * In particular, large, possibly chunk-encoded, messages. The interface is - * careful to never buffer entire requests or responses, so the - * user is able to stream data. - * - * HTTP message headers are represented by an object like this: - * - * ```json - * { "content-length": "123", - * "content-type": "text/plain", - * "connection": "keep-alive", - * "host": "example.com", - * "accept": "*" } - * ``` - * - * Keys are lowercased. Values are not modified. - * - * In order to support the full spectrum of possible HTTP applications, the Node.js - * HTTP API is very low-level. It deals with stream handling and message - * parsing only. It parses a message into headers and body but it does not - * parse the actual headers or the body. - * - * See `message.headers` for details on how duplicate headers are handled. - * - * The raw headers as they were received are retained in the `rawHeaders` property, which is an array of `[key, value, key2, value2, ...]`. For - * example, the previous message header object might have a `rawHeaders` list like the following: - * - * ```js - * [ 'ConTent-Length', '123456', - * 'content-LENGTH', '123', - * 'content-type', 'text/plain', - * 'CONNECTION', 'keep-alive', - * 'Host', 'example.com', - * 'accepT', '*' ] - * ``` - * @see [source](https://github.com/nodejs/node/blob/v25.x/lib/http.js) - */ declare module "node:http" { import { NonSharedBuffer } from "node:buffer"; import { LookupOptions } from "node:dns"; diff --git a/types/node/http2.d.ts b/types/node/http2.d.ts index 4130bfe2e04a4f..b2fcc591ba9e36 100644 --- a/types/node/http2.d.ts +++ b/types/node/http2.d.ts @@ -1,13 +1,3 @@ -/** - * The `node:http2` module provides an implementation of the [HTTP/2](https://tools.ietf.org/html/rfc7540) protocol. - * It can be accessed using: - * - * ```js - * import http2 from 'node:http2'; - * ``` - * @since v8.4.0 - * @see [source](https://github.com/nodejs/node/blob/v25.x/lib/http2.js) - */ declare module "node:http2" { import { NonSharedBuffer } from "node:buffer"; import { InternalEventEmitter } from "node:events"; diff --git a/types/node/https.d.ts b/types/node/https.d.ts index 6b025690f351b0..b10aad0c28c574 100644 --- a/types/node/https.d.ts +++ b/types/node/https.d.ts @@ -1,8 +1,3 @@ -/** - * HTTPS is the HTTP protocol over TLS/SSL. In Node.js this is implemented as a - * separate module. - * @see [source](https://github.com/nodejs/node/blob/v25.x/lib/https.js) - */ declare module "node:https" { import * as http from "node:http"; import { Duplex } from "node:stream"; diff --git a/types/node/inspector.d.ts b/types/node/inspector.d.ts index 34140df6dc6ec3..cf385b76dc1587 100644 --- a/types/node/inspector.d.ts +++ b/types/node/inspector.d.ts @@ -1,8 +1,3 @@ -/** - * The `node:inspector` module provides an API for interacting with the V8 - * inspector. - * @see [source](https://github.com/nodejs/node/blob/v25.x/lib/inspector.js) - */ declare module "node:inspector" { import { EventEmitter } from "node:events"; /** diff --git a/types/node/inspector/promises.d.ts b/types/node/inspector/promises.d.ts index 54e12506673e78..e75ff20a354957 100644 --- a/types/node/inspector/promises.d.ts +++ b/types/node/inspector/promises.d.ts @@ -1,9 +1,3 @@ -/** - * The `node:inspector/promises` module provides an API for interacting with the V8 - * inspector. - * @see [source](https://github.com/nodejs/node/blob/v25.x/lib/inspector/promises.js) - * @since v19.0.0 - */ declare module "node:inspector/promises" { import { EventEmitter } from "node:events"; export { close, console, NetworkResources, open, url, waitForDebugger } from "node:inspector"; diff --git a/types/node/module.d.ts b/types/node/module.d.ts index 6a8e339c17aa9c..7f61a678e67fc0 100644 --- a/types/node/module.d.ts +++ b/types/node/module.d.ts @@ -1,6 +1,3 @@ -/** - * @since v0.3.7 - */ declare module "node:module" { import { URL } from "node:url"; class Module { diff --git a/types/node/net.d.ts b/types/node/net.d.ts index a104853b1ad8d8..bb6d3a3930a956 100644 --- a/types/node/net.d.ts +++ b/types/node/net.d.ts @@ -1,17 +1,3 @@ -/** - * > Stability: 2 - Stable - * - * The `node:net` module provides an asynchronous network API for creating stream-based - * TCP or `IPC` servers ({@link createServer}) and clients - * ({@link createConnection}). - * - * It can be accessed using: - * - * ```js - * import net from 'node:net'; - * ``` - * @see [source](https://github.com/nodejs/node/blob/v25.x/lib/net.js) - */ declare module "node:net" { import { NonSharedBuffer } from "node:buffer"; import * as dns from "node:dns"; @@ -38,6 +24,7 @@ declare module "node:net" { keepAlive?: boolean | undefined; keepAliveInitialDelay?: number | undefined; blockList?: BlockList | undefined; + typeOfService?: number | undefined; } interface OnReadOpts { buffer: Uint8Array | (() => Uint8Array); @@ -231,6 +218,37 @@ declare module "node:net" { * @return The socket itself. */ setKeepAlive(enable?: boolean, initialDelay?: number): this; + /** + * Returns the current Type of Service (TOS) field for IPv4 packets or Traffic + * Class for IPv6 packets for this socket. + * + * `setTypeOfService()` may be called before the socket is connected; the value + * will be cached and applied when the socket establishes a connection. + * `getTypeOfService()` will return the currently set value even before connection. + * + * On some platforms (e.g., Linux), certain TOS/ECN bits may be masked or ignored, + * and behavior can differ between IPv4 and IPv6 or dual-stack sockets. Callers + * should verify platform-specific semantics. + * @since v25.6.0 + * @returns The current TOS value. + */ + getTypeOfService(): number; + /** + * Sets the Type of Service (TOS) field for IPv4 packets or Traffic Class for IPv6 + * Packets sent from this socket. This can be used to prioritize network traffic. + * + * `setTypeOfService()` may be called before the socket is connected; the value + * will be cached and applied when the socket establishes a connection. + * `getTypeOfService()` will return the currently set value even before connection. + * + * On some platforms (e.g., Linux), certain TOS/ECN bits may be masked or ignored, + * and behavior can differ between IPv4 and IPv6 or dual-stack sockets. Callers + * should verify platform-specific semantics. + * @since v25.6.0 + * @param tos The TOS value to set (0-255). + * @returns The socket itself. + */ + setTypeOfService(tos: number): this; /** * Returns the bound `address`, the address `family` name and `port` of the * socket as reported by the operating system:`{ port: 12346, family: 'IPv4', address: '127.0.0.1' }` diff --git a/types/node/node-tests/async_hooks.ts b/types/node/node-tests/async_hooks.ts index 588825e35c4fc3..99c96b5a31e21e 100644 --- a/types/node/node-tests/async_hooks.ts +++ b/types/node/node-tests/async_hooks.ts @@ -16,6 +16,7 @@ import { after() {}, destroy() {}, promiseResolve() {}, + trackPromises: true, }; const asyncHook = createHook(hooks); diff --git a/types/node/node-tests/net.ts b/types/node/node-tests/net.ts index 172411925e294e..8d95b8e5c74450 100644 --- a/types/node/node-tests/net.ts +++ b/types/node/node-tests/net.ts @@ -64,6 +64,7 @@ import * as net from "node:net"; keepAliveInitialDelay: 1000, noDelay: false, blockList: new net.BlockList(), + typeOfService: 0b00000111, }); let bool: boolean; @@ -451,6 +452,16 @@ import * as net from "node:net"; }); } +{ + const socket = new net.Socket(); + + // $ExpectType number + socket.getTypeOfService(); + + // $ExpectType Socket + socket.setTypeOfService(0b00000111); +} + { const sockAddr: net.SocketAddress = new net.SocketAddress({ address: "123.123.123.123", diff --git a/types/node/node-tests/stream.ts b/types/node/node-tests/stream.ts index 705b92856726d1..69cb4450ca2f1f 100644 --- a/types/node/node-tests/stream.ts +++ b/types/node/node-tests/stream.ts @@ -498,6 +498,8 @@ async function testConsumers() { await consumers.blob(consumable); // $ExpectType NonSharedBuffer await consumers.buffer(consumable); + // $ExpectType NonSharedUint8Array + await consumers.bytes(consumable); // $ExpectType unknown await consumers.json(consumable); // $ExpectType string diff --git a/types/node/node-tests/test.ts b/types/node/node-tests/test.ts index de79564145bb14..9d2585da1b1bfe 100644 --- a/types/node/node-tests/test.ts +++ b/types/node/node-tests/test.ts @@ -69,6 +69,9 @@ run({ branchCoverage: 50, functionCoverage: 80, rerunFailuresFilePath: "/path/to/file.json", + env: { + MY_TEST_PATH: "/path/to/tests", + }, }); // TestsStream should be a NodeJS.ReadableStream diff --git a/types/node/node-tests/tls.ts b/types/node/node-tests/tls.ts index b0186d18511f4a..47cd796d22b6b2 100644 --- a/types/node/node-tests/tls.ts +++ b/types/node/node-tests/tls.ts @@ -40,6 +40,7 @@ import { psk: Buffer.from("asd"), }; }, + requestOCSP: true, }; const tlsSocket = connect(connOpts); diff --git a/types/node/os.d.ts b/types/node/os.d.ts index db86e9b324b9cb..562c463ba1201a 100644 --- a/types/node/os.d.ts +++ b/types/node/os.d.ts @@ -1,12 +1,3 @@ -/** - * The `node:os` module provides operating system-related utility methods and - * properties. It can be accessed using: - * - * ```js - * import os from 'node:os'; - * ``` - * @see [source](https://github.com/nodejs/node/blob/v25.x/lib/os.js) - */ declare module "node:os" { import { NonSharedBuffer } from "buffer"; interface CpuInfo { diff --git a/types/node/package.json b/types/node/package.json index 937f11915a9174..f40218da2ed75f 100644 --- a/types/node/package.json +++ b/types/node/package.json @@ -1,7 +1,7 @@ { "private": true, "name": "@types/node", - "version": "25.5.9999", + "version": "25.6.9999", "nonNpm": "conflict", "nonNpmDescription": "Node.js", "projects": [ @@ -18,7 +18,7 @@ } }, "dependencies": { - "undici-types": "~7.18.0" + "undici-types": "~7.19.0" }, "devDependencies": { "@types/node": "workspace:." diff --git a/types/node/path.d.ts b/types/node/path.d.ts index c0b22f686b63cb..ae8fd973fd96a6 100644 --- a/types/node/path.d.ts +++ b/types/node/path.d.ts @@ -1,12 +1,3 @@ -/** - * The `node:path` module provides utilities for working with file and directory - * paths. It can be accessed using: - * - * ```js - * import path from 'node:path'; - * ``` - * @see [source](https://github.com/nodejs/node/blob/v25.x/lib/path.js) - */ declare module "node:path" { namespace path { /** diff --git a/types/node/perf_hooks.d.ts b/types/node/perf_hooks.d.ts index 4dd063284a53b7..46e725c314c53a 100644 --- a/types/node/perf_hooks.d.ts +++ b/types/node/perf_hooks.d.ts @@ -1,34 +1,3 @@ -/** - * This module provides an implementation of a subset of the W3C [Web Performance APIs](https://w3c.github.io/perf-timing-primer/) as well as additional APIs for - * Node.js-specific performance measurements. - * - * Node.js supports the following [Web Performance APIs](https://w3c.github.io/perf-timing-primer/): - * - * * [High Resolution Time](https://www.w3.org/TR/hr-time-2) - * * [Performance Timeline](https://w3c.github.io/performance-timeline/) - * * [User Timing](https://www.w3.org/TR/user-timing/) - * * [Resource Timing](https://www.w3.org/TR/resource-timing-2/) - * - * ```js - * import { PerformanceObserver, performance } from 'node:perf_hooks'; - * - * const obs = new PerformanceObserver((items) => { - * console.log(items.getEntries()[0].duration); - * performance.clearMarks(); - * }); - * obs.observe({ type: 'measure' }); - * performance.measure('Start to Now'); - * - * performance.mark('A'); - * doSomeLongRunningProcess(() => { - * performance.measure('A to Now', 'A'); - * - * performance.mark('B'); - * performance.measure('A to B', 'A', 'B'); - * }); - * ``` - * @see [source](https://github.com/nodejs/node/blob/v25.x/lib/perf_hooks.js) - */ declare module "node:perf_hooks" { import { InternalEventTargetEventProperties } from "node:events"; // #region web types diff --git a/types/node/punycode.d.ts b/types/node/punycode.d.ts index d293553f71ea8f..87fdec970362b0 100644 --- a/types/node/punycode.d.ts +++ b/types/node/punycode.d.ts @@ -1,31 +1,3 @@ -/** - * **The version of the punycode module bundled in Node.js is being deprecated. **In a future major version of Node.js this module will be removed. Users - * currently depending on the `punycode` module should switch to using the - * userland-provided [Punycode.js](https://github.com/bestiejs/punycode.js) module instead. For punycode-based URL - * encoding, see `url.domainToASCII` or, more generally, the `WHATWG URL API`. - * - * The `punycode` module is a bundled version of the [Punycode.js](https://github.com/bestiejs/punycode.js) module. It - * can be accessed using: - * - * ```js - * import punycode from 'node:punycode'; - * ``` - * - * [Punycode](https://tools.ietf.org/html/rfc3492) is a character encoding scheme defined by RFC 3492 that is - * primarily intended for use in Internationalized Domain Names. Because host - * names in URLs are limited to ASCII characters only, Domain Names that contain - * non-ASCII characters must be converted into ASCII using the Punycode scheme. - * For instance, the Japanese character that translates into the English word, `'example'` is `'例'`. The Internationalized Domain Name, `'例.com'` (equivalent - * to `'example.com'`) is represented by Punycode as the ASCII string `'xn--fsq.com'`. - * - * The `punycode` module provides a simple implementation of the Punycode standard. - * - * The `punycode` module is a third-party dependency used by Node.js and - * made available to developers as a convenience. Fixes or other modifications to - * the module must be directed to the [Punycode.js](https://github.com/bestiejs/punycode.js) project. - * @deprecated - * @see [source](https://github.com/nodejs/node/blob/v25.x/lib/punycode.js) - */ declare module "node:punycode" { /** * The `punycode.decode()` method converts a [Punycode](https://tools.ietf.org/html/rfc3492) string of ASCII-only diff --git a/types/node/querystring.d.ts b/types/node/querystring.d.ts index dc421bcc6b4e9e..6d821a4e06be58 100644 --- a/types/node/querystring.d.ts +++ b/types/node/querystring.d.ts @@ -1,16 +1,3 @@ -/** - * The `node:querystring` module provides utilities for parsing and formatting URL - * query strings. It can be accessed using: - * - * ```js - * import querystring from 'node:querystring'; - * ``` - * - * `querystring` is more performant than `URLSearchParams` but is not a - * standardized API. Use `URLSearchParams` when performance is not critical or - * when compatibility with browser code is desirable. - * @see [source](https://github.com/nodejs/node/blob/v25.x/lib/querystring.js) - */ declare module "node:querystring" { interface StringifyOptions { /** diff --git a/types/node/quic.d.ts b/types/node/quic.d.ts index 9a6fd97ea1d49e..7fe6188d187079 100644 --- a/types/node/quic.d.ts +++ b/types/node/quic.d.ts @@ -1,16 +1,3 @@ -/** - * The 'node:quic' module provides an implementation of the QUIC protocol. - * To access it, start Node.js with the `--experimental-quic` option and: - * - * ```js - * import quic from 'node:quic'; - * ``` - * - * The module is only available under the `node:` scheme. - * @since v23.8.0 - * @experimental - * @see [source](https://github.com/nodejs/node/blob/v25.x/lib/quic.js) - */ declare module "node:quic" { import { KeyObject, webcrypto } from "node:crypto"; import { SocketAddress } from "node:net"; diff --git a/types/node/readline.d.ts b/types/node/readline.d.ts index 9e3714fde46532..5042975a79b55e 100644 --- a/types/node/readline.d.ts +++ b/types/node/readline.d.ts @@ -1,38 +1,3 @@ -/** - * The `node:readline` module provides an interface for reading data from a [Readable](https://nodejs.org/docs/latest-v25.x/api/stream.html#readable-streams) stream - * (such as [`process.stdin`](https://nodejs.org/docs/latest-v25.x/api/process.html#processstdin)) one line at a time. - * - * To use the promise-based APIs: - * - * ```js - * import * as readline from 'node:readline/promises'; - * ``` - * - * To use the callback and sync APIs: - * - * ```js - * import * as readline from 'node:readline'; - * ``` - * - * The following simple example illustrates the basic use of the `node:readline` module. - * - * ```js - * import * as readline from 'node:readline/promises'; - * import { stdin as input, stdout as output } from 'node:process'; - * - * const rl = readline.createInterface({ input, output }); - * - * const answer = await rl.question('What do you think of Node.js? '); - * - * console.log(`Thank you for your valuable feedback: ${answer}`); - * - * rl.close(); - * ``` - * - * Once this code is invoked, the Node.js application will not terminate until the `readline.Interface` is closed because the interface waits for data to be - * received on the `input` stream. - * @see [source](https://github.com/nodejs/node/blob/v25.x/lib/readline.js) - */ declare module "node:readline" { import { Abortable, EventEmitter, InternalEventEmitter } from "node:events"; interface Key { diff --git a/types/node/readline/promises.d.ts b/types/node/readline/promises.d.ts index f449e1bbc85ad5..ccee49037635bf 100644 --- a/types/node/readline/promises.d.ts +++ b/types/node/readline/promises.d.ts @@ -1,6 +1,3 @@ -/** - * @since v17.0.0 - */ declare module "node:readline/promises" { import { Abortable } from "node:events"; import { diff --git a/types/node/repl.d.ts b/types/node/repl.d.ts index 2d06294f2a11a7..7481bead57902b 100644 --- a/types/node/repl.d.ts +++ b/types/node/repl.d.ts @@ -1,13 +1,3 @@ -/** - * The `node:repl` module provides a Read-Eval-Print-Loop (REPL) implementation - * that is available both as a standalone program or includible in other - * applications. It can be accessed using: - * - * ```js - * import repl from 'node:repl'; - * ``` - * @see [source](https://github.com/nodejs/node/blob/v25.x/lib/repl.js) - */ declare module "node:repl" { import { AsyncCompleter, Completer, Interface, InterfaceEventMap } from "node:readline"; import { InspectOptions } from "node:util"; diff --git a/types/node/scripts/generate-docs/ast-processing.ts b/types/node/scripts/generate-docs/ast-processing.ts index f778318a4d4dae..ce7516c9fa9968 100644 --- a/types/node/scripts/generate-docs/ast-processing.ts +++ b/types/node/scripts/generate-docs/ast-processing.ts @@ -16,7 +16,6 @@ import { isTypeLiteralNode, JSDocParameterTag, JSDocReturnTag, - JSDocSeeTag, JSDocTag, JSDocUnknownTag, MethodDeclaration, @@ -29,13 +28,7 @@ import { TransformationContext, TypeChecker, } from "typescript"; -import { - getIndent, - getPropertyName, - isNamedModuleDeclaration, - nodeWarning, - removeCommentsRecursive, -} from "./ast-utils"; +import { getIndent, getPropertyName, nodeWarning, removeCommentsRecursive } from "./ast-utils"; import { fixupHtmlDocs, fixupLocalLinks } from "./html-doc-processing"; import { ClassDocNode, MethodDocNode, ModuleDocNode, PropertyDocNode, SignatureDocNode } from "./node-doc-processing"; import { contextDeduper, replaceLineBreaks, wordWrap } from "./utils"; @@ -149,15 +142,6 @@ class TagHelper { return this.createUnknownTag("legacy", this.fixupCommentFormatting(text, "legacy")); } - createSeeLinkTag(url: string, text: string): JSDocSeeTag { - const { factory } = this.docContext.transformationContext; - return this.docContext.transformationContext.factory.createJSDocSeeTag( - factory.createIdentifier("see"), - undefined, - `[${text}](${url})`, - ); - } - private createReturnTag(text: string): JSDocReturnTag { const { factory } = this.docContext.transformationContext; return factory.createJSDocReturnTag( @@ -402,31 +386,6 @@ export class NodeProcessingContext { }; } - /** - * Processes named module declarations. - */ - private handleModuleDeclaration(): JSDocResult { - const { moduleDocs } = this.context; - const tags = this.tagHelper.extractCommonTags(moduleDocs, moduleDocs.name); - - // Get rid of bloaty source label - let desc = moduleDocs.desc ?? ""; - const removeSourceRegex = /

Source Code:<\/strong> .*?<\/a><\/p>/; - const match = removeSourceRegex.exec(desc); - if (match) { - tags.push(this.tagHelper.createSeeLinkTag(match[1]!, "source")); - desc = desc.replace(removeSourceRegex, ``); - } - - return { - status: JSDocMatchResult.Ok, - data: { - text: this.fixupDescriptionFormatting(desc, moduleDocs.name), - tags, - }, - }; - } - /** * Processes class declarations */ @@ -522,12 +481,6 @@ export class NodeProcessingContext { this.context.indent = getIndent(node); if (isFunctionDeclaration(node)) { processRes = this.processFunctionDeclaration(node); - } else if ( - isNamedModuleDeclaration(node) - && !(node.name.text.startsWith("node:") && node.name.text !== "node:test" - && node.name.text !== "node:sqlite") // apparently everything is a module - ) { - processRes = this.handleModuleDeclaration(); } else if (isClassDeclaration(node)) { processRes = this.handleClassDeclaration(node); } else if (isMethodDeclaration(node) || isMethodSignature(node)) { diff --git a/types/node/sea.d.ts b/types/node/sea.d.ts index 2930c82bc0bccb..85ab108b886968 100644 --- a/types/node/sea.d.ts +++ b/types/node/sea.d.ts @@ -1,118 +1,3 @@ -/** - * This feature allows the distribution of a Node.js application conveniently to a - * system that does not have Node.js installed. - * - * Node.js supports the creation of [single executable applications](https://github.com/nodejs/single-executable) by allowing - * the injection of a blob prepared by Node.js, which can contain a bundled script, - * into the `node` binary. During start up, the program checks if anything has been - * injected. If the blob is found, it executes the script in the blob. Otherwise - * Node.js operates as it normally does. - * - * The single executable application feature currently only supports running a - * single embedded script using the `CommonJS` module system. - * - * Users can create a single executable application from their bundled script - * with the `node` binary itself and any tool which can inject resources into the - * binary. - * - * Here are the steps for creating a single executable application using one such - * tool, [postject](https://github.com/nodejs/postject): - * - * 1. Create a JavaScript file: - * ```bash - * echo 'console.log(`Hello, ${process.argv[2]}!`);' > hello.js - * ``` - * 2. Create a configuration file building a blob that can be injected into the - * single executable application (see `Generating single executable preparation blobs` for details): - * ```bash - * echo '{ "main": "hello.js", "output": "sea-prep.blob" }' > sea-config.json - * ``` - * 3. Generate the blob to be injected: - * ```bash - * node --experimental-sea-config sea-config.json - * ``` - * 4. Create a copy of the `node` executable and name it according to your needs: - * * On systems other than Windows: - * ```bash - * cp $(command -v node) hello - * ``` - * * On Windows: - * ```text - * node -e "require('fs').copyFileSync(process.execPath, 'hello.exe')" - * ``` - * The `.exe` extension is necessary. - * 5. Remove the signature of the binary (macOS and Windows only): - * * On macOS: - * ```bash - * codesign --remove-signature hello - * ``` - * * On Windows (optional): - * [signtool](https://learn.microsoft.com/en-us/windows/win32/seccrypto/signtool) can be used from the installed [Windows SDK](https://developer.microsoft.com/en-us/windows/downloads/windows-sdk/). - * If this step is - * skipped, ignore any signature-related warning from postject. - * ```powershell - * signtool remove /s hello.exe - * ``` - * 6. Inject the blob into the copied binary by running `postject` with - * the following options: - * * `hello` / `hello.exe` \- The name of the copy of the `node` executable - * created in step 4. - * * `NODE_SEA_BLOB` \- The name of the resource / note / section in the binary - * where the contents of the blob will be stored. - * * `sea-prep.blob` \- The name of the blob created in step 1. - * * `--sentinel-fuse NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2` \- The [fuse](https://www.electronjs.org/docs/latest/tutorial/fuses) used by the Node.js project to detect if a file has been - * injected. - * * `--macho-segment-name NODE_SEA` (only needed on macOS) - The name of the - * segment in the binary where the contents of the blob will be - * stored. - * To summarize, here is the required command for each platform: - * * On Linux: - * ```bash - * npx postject hello NODE_SEA_BLOB sea-prep.blob \ - * --sentinel-fuse NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2 - * ``` - * * On Windows - PowerShell: - * ```powershell - * npx postject hello.exe NODE_SEA_BLOB sea-prep.blob ` - * --sentinel-fuse NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2 - * ``` - * * On Windows - Command Prompt: - * ```text - * npx postject hello.exe NODE_SEA_BLOB sea-prep.blob ^ - * --sentinel-fuse NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2 - * ``` - * * On macOS: - * ```bash - * npx postject hello NODE_SEA_BLOB sea-prep.blob \ - * --sentinel-fuse NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2 \ - * --macho-segment-name NODE_SEA - * ``` - * 7. Sign the binary (macOS and Windows only): - * * On macOS: - * ```bash - * codesign --sign - hello - * ``` - * * On Windows (optional): - * A certificate needs to be present for this to work. However, the unsigned - * binary would still be runnable. - * ```powershell - * signtool sign /fd SHA256 hello.exe - * ``` - * 8. Run the binary: - * * On systems other than Windows - * ```console - * $ ./hello world - * Hello, world! - * ``` - * * On Windows - * ```console - * $ .\hello.exe world - * Hello, world! - * ``` - * @since v19.7.0, v18.16.0 - * @experimental - * @see [source](https://github.com/nodejs/node/blob/v25.x/src/node_sea.cc) - */ declare module "node:sea" { type AssetKey = string; /** diff --git a/types/node/sqlite.d.ts b/types/node/sqlite.d.ts index 44a9b66c899fe1..d2111bbef626ef 100644 --- a/types/node/sqlite.d.ts +++ b/types/node/sqlite.d.ts @@ -1,47 +1,3 @@ -/** - * The `node:sqlite` module facilitates working with SQLite databases. - * To access it: - * - * ```js - * import sqlite from 'node:sqlite'; - * ``` - * - * This module is only available under the `node:` scheme. The following will not - * work: - * - * ```js - * import sqlite from 'sqlite'; - * ``` - * - * The following example shows the basic usage of the `node:sqlite` module to open - * an in-memory database, write data to the database, and then read the data back. - * - * ```js - * import { DatabaseSync } from 'node:sqlite'; - * const database = new DatabaseSync(':memory:'); - * - * // Execute SQL statements from strings. - * database.exec(` - * CREATE TABLE data( - * key INTEGER PRIMARY KEY, - * value TEXT - * ) STRICT - * `); - * // Create a prepared statement to insert data into the database. - * const insert = database.prepare('INSERT INTO data (key, value) VALUES (?, ?)'); - * // Execute the prepared statement with bound values. - * insert.run(1, 'hello'); - * insert.run(2, 'world'); - * // Create a prepared statement to read data from the database. - * const query = database.prepare('SELECT * FROM data ORDER BY key'); - * // Execute the prepared statement and log the result set. - * console.log(query.all()); - * // Prints: [ { key: 1, value: 'hello' }, { key: 2, value: 'world' } ] - * ``` - * @since v22.5.0 - * @experimental - * @see [source](https://github.com/nodejs/node/blob/v25.x/lib/sqlite.js) - */ declare module "node:sqlite" { import { PathLike } from "node:fs"; type SQLInputValue = null | number | bigint | string | NodeJS.ArrayBufferView; diff --git a/types/node/stream.d.ts b/types/node/stream.d.ts index f625e711ec37c3..1591667a40d8d2 100644 --- a/types/node/stream.d.ts +++ b/types/node/stream.d.ts @@ -1,22 +1,3 @@ -/** - * A stream is an abstract interface for working with streaming data in Node.js. - * The `node:stream` module provides an API for implementing the stream interface. - * - * There are many stream objects provided by Node.js. For instance, a [request to an HTTP server](https://nodejs.org/docs/latest-v25.x/api/http.html#class-httpincomingmessage) - * and [`process.stdout`](https://nodejs.org/docs/latest-v25.x/api/process.html#processstdout) are both stream instances. - * - * Streams can be readable, writable, or both. All streams are instances of [`EventEmitter`](https://nodejs.org/docs/latest-v25.x/api/events.html#class-eventemitter). - * - * To access the `node:stream` module: - * - * ```js - * import stream from 'node:stream'; - * ``` - * - * The `node:stream` module is useful for creating new types of stream instances. - * It is usually not necessary to use the `node:stream` module to consume streams. - * @see [source](https://github.com/nodejs/node/blob/v25.x/lib/stream.js) - */ declare module "node:stream" { import { Blob } from "node:buffer"; import { Abortable, EventEmitter } from "node:events"; diff --git a/types/node/stream/consumers.d.ts b/types/node/stream/consumers.d.ts index 97f260da130f07..27a474c5e18b8c 100644 --- a/types/node/stream/consumers.d.ts +++ b/types/node/stream/consumers.d.ts @@ -1,33 +1,109 @@ -/** - * The utility consumer functions provide common options for consuming - * streams. - * @since v16.7.0 - */ declare module "node:stream/consumers" { import { Blob, NonSharedBuffer } from "node:buffer"; import { ReadableStream } from "node:stream/web"; /** + * ```js + * import { arrayBuffer } from 'node:stream/consumers'; + * import { Readable } from 'node:stream'; + * import { TextEncoder } from 'node:util'; + * + * const encoder = new TextEncoder(); + * const dataArray = encoder.encode('hello world from consumers!'); + * + * const readable = Readable.from(dataArray); + * const data = await arrayBuffer(readable); + * console.log(`from readable: ${data.byteLength}`); + * // Prints: from readable: 76 + * ``` * @since v16.7.0 * @returns Fulfills with an `ArrayBuffer` containing the full contents of the stream. */ function arrayBuffer(stream: ReadableStream | NodeJS.ReadableStream | AsyncIterable): Promise; /** + * ```js + * import { blob } from 'node:stream/consumers'; + * + * const dataBlob = new Blob(['hello world from consumers!']); + * + * const readable = dataBlob.stream(); + * const data = await blob(readable); + * console.log(`from readable: ${data.size}`); + * // Prints: from readable: 27 + * ``` * @since v16.7.0 * @returns Fulfills with a `Blob` containing the full contents of the stream. */ function blob(stream: ReadableStream | NodeJS.ReadableStream | AsyncIterable): Promise; /** + * ```js + * import { buffer } from 'node:stream/consumers'; + * import { Readable } from 'node:stream'; + * import { Buffer } from 'node:buffer'; + * + * const dataBuffer = Buffer.from('hello world from consumers!'); + * + * const readable = Readable.from(dataBuffer); + * const data = await buffer(readable); + * console.log(`from readable: ${data.length}`); + * // Prints: from readable: 27 + * ``` * @since v16.7.0 * @returns Fulfills with a `Buffer` containing the full contents of the stream. */ function buffer(stream: ReadableStream | NodeJS.ReadableStream | AsyncIterable): Promise; /** + * ```js + * import { bytes } from 'node:stream/consumers'; + * import { Readable } from 'node:stream'; + * import { Buffer } from 'node:buffer'; + * + * const dataBuffer = Buffer.from('hello world from consumers!'); + * + * const readable = Readable.from(dataBuffer); + * const data = await bytes(readable); + * console.log(`from readable: ${data.length}`); + * // Prints: from readable: 27 + * ``` + * @since v25.6.0 + * @returns Fulfills with a `Uint8Array` containing the full contents of the stream. + */ + function bytes( + stream: ReadableStream | NodeJS.ReadableStream | AsyncIterable, + ): Promise; + /** + * ```js + * import { json } from 'node:stream/consumers'; + * import { Readable } from 'node:stream'; + * + * const items = Array.from( + * { + * length: 100, + * }, + * () => ({ + * message: 'hello world from consumers!', + * }), + * ); + * + * const readable = Readable.from(JSON.stringify(items)); + * const data = await json(readable); + * console.log(`from readable: ${data.length}`); + * // Prints: from readable: 100 + * ``` * @since v16.7.0 * @returns Fulfills with the contents of the stream parsed as a * UTF-8 encoded string that is then passed through `JSON.parse()`. */ function json(stream: ReadableStream | NodeJS.ReadableStream | AsyncIterable): Promise; /** + * ```js + * import { text } from 'node:stream/consumers'; + * import { Readable } from 'node:stream'; + * + * const readable = Readable.from('Hello world from consumers!'); + * const data = await text(readable); + * console.log(`from readable: ${data.length}`); + * // Prints: from readable: 27 + * ``` * @since v16.7.0 * @returns Fulfills with the contents of the stream parsed as a UTF-8 encoded string. */ diff --git a/types/node/string_decoder.d.ts b/types/node/string_decoder.d.ts index a72c374741ec52..568e3f654fad09 100644 --- a/types/node/string_decoder.d.ts +++ b/types/node/string_decoder.d.ts @@ -1,43 +1,3 @@ -/** - * The `node:string_decoder` module provides an API for decoding `Buffer` objects - * into strings in a manner that preserves encoded multi-byte UTF-8 and UTF-16 - * characters. It can be accessed using: - * - * ```js - * import { StringDecoder } from 'node:string_decoder'; - * ``` - * - * The following example shows the basic use of the `StringDecoder` class. - * - * ```js - * import { StringDecoder } from 'node:string_decoder'; - * const decoder = new StringDecoder('utf8'); - * - * const cent = Buffer.from([0xC2, 0xA2]); - * console.log(decoder.write(cent)); // Prints: ¢ - * - * const euro = Buffer.from([0xE2, 0x82, 0xAC]); - * console.log(decoder.write(euro)); // Prints: € - * ``` - * - * When a `Buffer` instance is written to the `StringDecoder` instance, an - * internal buffer is used to ensure that the decoded string does not contain - * any incomplete multibyte characters. These are held in the buffer until the - * next call to `stringDecoder.write()` or until `stringDecoder.end()` is called. - * - * In the following example, the three UTF-8 encoded bytes of the European Euro - * symbol (`€`) are written over three separate operations: - * - * ```js - * import { StringDecoder } from 'node:string_decoder'; - * const decoder = new StringDecoder('utf8'); - * - * decoder.write(Buffer.from([0xE2])); - * decoder.write(Buffer.from([0x82])); - * console.log(decoder.end(Buffer.from([0xAC]))); // Prints: € - * ``` - * @see [source](https://github.com/nodejs/node/blob/v25.x/lib/string_decoder.js) - */ declare module "node:string_decoder" { class StringDecoder { constructor(encoding?: BufferEncoding); diff --git a/types/node/test.d.ts b/types/node/test.d.ts index 4207cda116ca19..a3ec5e28b560fd 100644 --- a/types/node/test.d.ts +++ b/types/node/test.d.ts @@ -1,83 +1,3 @@ -/** - * The `node:test` module facilitates the creation of JavaScript tests. - * To access it: - * - * ```js - * import test from 'node:test'; - * ``` - * - * This module is only available under the `node:` scheme. The following will not - * work: - * - * ```js - * import test from 'node:test'; - * ``` - * - * Tests created via the `test` module consist of a single function that is - * processed in one of three ways: - * - * 1. A synchronous function that is considered failing if it throws an exception, - * and is considered passing otherwise. - * 2. A function that returns a `Promise` that is considered failing if the `Promise` rejects, and is considered passing if the `Promise` fulfills. - * 3. A function that receives a callback function. If the callback receives any - * truthy value as its first argument, the test is considered failing. If a - * falsy value is passed as the first argument to the callback, the test is - * considered passing. If the test function receives a callback function and - * also returns a `Promise`, the test will fail. - * - * The following example illustrates how tests are written using the `test` module. - * - * ```js - * test('synchronous passing test', (t) => { - * // This test passes because it does not throw an exception. - * assert.strictEqual(1, 1); - * }); - * - * test('synchronous failing test', (t) => { - * // This test fails because it throws an exception. - * assert.strictEqual(1, 2); - * }); - * - * test('asynchronous passing test', async (t) => { - * // This test passes because the Promise returned by the async - * // function is settled and not rejected. - * assert.strictEqual(1, 1); - * }); - * - * test('asynchronous failing test', async (t) => { - * // This test fails because the Promise returned by the async - * // function is rejected. - * assert.strictEqual(1, 2); - * }); - * - * test('failing test using Promises', (t) => { - * // Promises can be used directly as well. - * return new Promise((resolve, reject) => { - * setImmediate(() => { - * reject(new Error('this will cause the test to fail')); - * }); - * }); - * }); - * - * test('callback passing test', (t, done) => { - * // done() is the callback function. When the setImmediate() runs, it invokes - * // done() with no arguments. - * setImmediate(done); - * }); - * - * test('callback failing test', (t, done) => { - * // When the setImmediate() runs, done() is invoked with an Error object and - * // the test fails. - * setImmediate(() => { - * done(new Error('callback failure')); - * }); - * }); - * ``` - * - * If any tests fail, the process exit code is set to `1`. - * @since v18.0.0, v16.17.0 - * @see [source](https://github.com/nodejs/node/blob/v25.x/lib/test.js) - */ declare module "node:test" { import { AssertMethodNames } from "node:assert"; import { Readable, ReadableEventMap } from "node:stream"; @@ -409,6 +329,13 @@ declare module "node:test" { * @default 0 */ functionCoverage?: number | undefined; + /** + * Specify environment variables to be passed along to the test process. + * This options is not compatible with `isolation='none'`. These variables will override + * those from the main process, and are not merged with `process.env`. + * @since v25.6.0 + */ + env?: NodeJS.ProcessEnv | undefined; } interface TestsStreamEventMap extends ReadableEventMap { "data": [data: TestEvent]; diff --git a/types/node/test/reporters.d.ts b/types/node/test/reporters.d.ts index 465e80d9243b32..e04d669dbe0959 100644 --- a/types/node/test/reporters.d.ts +++ b/types/node/test/reporters.d.ts @@ -1,41 +1,3 @@ -/** - * The `node:test` module supports passing `--test-reporter` - * flags for the test runner to use a specific reporter. - * - * The following built-reporters are supported: - * - * * `spec` - * The `spec` reporter outputs the test results in a human-readable format. This - * is the default reporter. - * - * * `tap` - * The `tap` reporter outputs the test results in the [TAP](https://testanything.org/) format. - * - * * `dot` - * The `dot` reporter outputs the test results in a compact format, - * where each passing test is represented by a `.`, - * and each failing test is represented by a `X`. - * - * * `junit` - * The junit reporter outputs test results in a jUnit XML format - * - * * `lcov` - * The `lcov` reporter outputs test coverage when used with the - * `--experimental-test-coverage` flag. - * - * The exact output of these reporters is subject to change between versions of - * Node.js, and should not be relied on programmatically. If programmatic access - * to the test runner's output is required, use the events emitted by the - * `TestsStream`. - * - * The reporters are available via the `node:test/reporters` module: - * - * ```js - * import { tap, spec, dot, junit, lcov } from 'node:test/reporters'; - * ``` - * @since v19.9.0, v18.17.0 - * @see [source](https://github.com/nodejs/node/blob/v25.x/lib/test/reporters.js) - */ declare module "node:test/reporters" { import { Transform, TransformOptions } from "node:stream"; import { EventData } from "node:test"; diff --git a/types/node/timers.d.ts b/types/node/timers.d.ts index 00a8cd09ddfa8b..5b74b894f8ae09 100644 --- a/types/node/timers.d.ts +++ b/types/node/timers.d.ts @@ -1,13 +1,3 @@ -/** - * The `timer` module exposes a global API for scheduling functions to - * be called at some future period of time. Because the timer functions are - * globals, there is no need to import `node:timers` to use the API. - * - * The timer functions within Node.js implement a similar API as the timers API - * provided by Web Browsers but use a different internal implementation that is - * built around the Node.js [Event Loop](https://nodejs.org/en/docs/guides/event-loop-timers-and-nexttick/#setimmediate-vs-settimeout). - * @see [source](https://github.com/nodejs/node/blob/v25.x/lib/timers.js) - */ declare module "node:timers" { import { Abortable } from "node:events"; import * as promises from "node:timers/promises"; diff --git a/types/node/timers/promises.d.ts b/types/node/timers/promises.d.ts index 85bc8317fb0e97..8e178eafe6cb61 100644 --- a/types/node/timers/promises.d.ts +++ b/types/node/timers/promises.d.ts @@ -1,18 +1,3 @@ -/** - * The `timers/promises` API provides an alternative set of timer functions - * that return `Promise` objects. The API is accessible via - * `require('node:timers/promises')`. - * - * ```js - * import { - * setTimeout, - * setImmediate, - * setInterval, - * } from 'node:timers/promises'; - * ``` - * @since v15.0.0 - * @see [source](https://github.com/nodejs/node/blob/v25.x/lib/timers/promises.js) - */ declare module "node:timers/promises" { import { TimerOptions } from "node:timers"; /** diff --git a/types/node/tls.d.ts b/types/node/tls.d.ts index a2c29dff549899..3efd2ae2027e8f 100644 --- a/types/node/tls.d.ts +++ b/types/node/tls.d.ts @@ -1,13 +1,3 @@ -/** - * The `node:tls` module provides an implementation of the Transport Layer Security - * (TLS) and Secure Socket Layer (SSL) protocols that is built on top of OpenSSL. - * The module can be accessed using: - * - * ```js - * import tls from 'node:tls'; - * ``` - * @see [source](https://github.com/nodejs/node/blob/v25.x/lib/tls.js) - */ declare module "node:tls" { import { NonSharedBuffer } from "node:buffer"; import { X509Certificate } from "node:crypto"; @@ -200,12 +190,6 @@ declare module "node:tls" { * An optional Buffer instance containing a TLS session. */ session?: Buffer | undefined; - /** - * If true, specifies that the OCSP status request extension will be - * added to the client hello and an 'OCSPResponse' event will be - * emitted on the socket before establishing a secure communication - */ - requestOCSP?: boolean | undefined; } interface TLSSocketEventMap extends net.SocketEventMap { "keylog": [line: NonSharedBuffer]; @@ -577,6 +561,12 @@ declare module "node:tls" { * @default true */ rejectUnauthorized?: boolean | undefined; + /** + * If true, specifies that the OCSP status request extension will be + * added to the client hello and an 'OCSPResponse' event will be + * emitted on the socket before establishing a secure communication. + */ + requestOCSP?: boolean | undefined; } interface TlsOptions extends SecureContextOptions, CommonConnectionOptions, net.ServerOpts { /** diff --git a/types/node/trace_events.d.ts b/types/node/trace_events.d.ts index b2c6b3231ad2e5..5fa7a3957a9884 100644 --- a/types/node/trace_events.d.ts +++ b/types/node/trace_events.d.ts @@ -1,97 +1,3 @@ -/** - * The `node:trace_events` module provides a mechanism to centralize tracing information - * generated by V8, Node.js core, and userspace code. - * - * Tracing can be enabled with the `--trace-event-categories` command-line flag - * or by using the `trace_events` module. The `--trace-event-categories` flag - * accepts a list of comma-separated category names. - * - * The available categories are: - * - * * `node`: An empty placeholder. - * * `node.async_hooks`: Enables capture of detailed [`async_hooks`](https://nodejs.org/docs/latest-v25.x/api/async_hooks.html) trace data. - * The [`async_hooks`](https://nodejs.org/docs/latest-v25.x/api/async_hooks.html) events have a unique `asyncId` and a special `triggerId` `triggerAsyncId` property. - * * `node.bootstrap`: Enables capture of Node.js bootstrap milestones. - * * `node.console`: Enables capture of `console.time()` and `console.count()` output. - * * `node.threadpoolwork.sync`: Enables capture of trace data for threadpool synchronous operations, such as `blob`, `zlib`, `crypto` and `node_api`. - * * `node.threadpoolwork.async`: Enables capture of trace data for threadpool asynchronous operations, such as `blob`, `zlib`, `crypto` and `node_api`. - * * `node.dns.native`: Enables capture of trace data for DNS queries. - * * `node.net.native`: Enables capture of trace data for network. - * * `node.environment`: Enables capture of Node.js Environment milestones. - * * `node.fs.sync`: Enables capture of trace data for file system sync methods. - * * `node.fs_dir.sync`: Enables capture of trace data for file system sync directory methods. - * * `node.fs.async`: Enables capture of trace data for file system async methods. - * * `node.fs_dir.async`: Enables capture of trace data for file system async directory methods. - * * `node.perf`: Enables capture of [Performance API](https://nodejs.org/docs/latest-v25.x/api/perf_hooks.html) measurements. - * * `node.perf.usertiming`: Enables capture of only Performance API User Timing - * measures and marks. - * * `node.perf.timerify`: Enables capture of only Performance API timerify - * measurements. - * * `node.promises.rejections`: Enables capture of trace data tracking the number - * of unhandled Promise rejections and handled-after-rejections. - * * `node.vm.script`: Enables capture of trace data for the `node:vm` module's `runInNewContext()`, `runInContext()`, and `runInThisContext()` methods. - * * `v8`: The [V8](https://nodejs.org/docs/latest-v25.x/api/v8.html) events are GC, compiling, and execution related. - * * `node.http`: Enables capture of trace data for http request / response. - * - * By default the `node`, `node.async_hooks`, and `v8` categories are enabled. - * - * ```bash - * node --trace-event-categories v8,node,node.async_hooks server.js - * ``` - * - * Prior versions of Node.js required the use of the `--trace-events-enabled` flag to enable trace events. This requirement has been removed. However, the `--trace-events-enabled` flag _may_ still be - * used and will enable the `node`, `node.async_hooks`, and `v8` trace event categories by default. - * - * ```bash - * node --trace-events-enabled - * - * # is equivalent to - * - * node --trace-event-categories v8,node,node.async_hooks - * ``` - * - * Alternatively, trace events may be enabled using the `node:trace_events` module: - * - * ```js - * import trace_events from 'node:trace_events'; - * const tracing = trace_events.createTracing({ categories: ['node.perf'] }); - * tracing.enable(); // Enable trace event capture for the 'node.perf' category - * - * // do work - * - * tracing.disable(); // Disable trace event capture for the 'node.perf' category - * ``` - * - * Running Node.js with tracing enabled will produce log files that can be opened - * in the [`chrome://tracing`](https://www.chromium.org/developers/how-tos/trace-event-profiling-tool) tab of Chrome. - * - * The logging file is by default called `node_trace.${rotation}.log`, where `${rotation}` is an incrementing log-rotation id. The filepath pattern can - * be specified with `--trace-event-file-pattern` that accepts a template - * string that supports `${rotation}` and `${pid}`: - * - * ```bash - * node --trace-event-categories v8 --trace-event-file-pattern '${pid}-${rotation}.log' server.js - * ``` - * - * To guarantee that the log file is properly generated after signal events like `SIGINT`, `SIGTERM`, or `SIGBREAK`, make sure to have the appropriate handlers - * in your code, such as: - * - * ```js - * process.on('SIGINT', function onSigint() { - * console.info('Received SIGINT.'); - * process.exit(130); // Or applicable exit code depending on OS and signal - * }); - * ``` - * - * The tracing system uses the same time source - * as the one used by `process.hrtime()`. - * However the trace-event timestamps are expressed in microseconds, - * unlike `process.hrtime()` which returns nanoseconds. - * - * The features from this module are not available in [`Worker`](https://nodejs.org/docs/latest-v25.x/api/worker_threads.html#class-worker) threads. - * @experimental - * @see [source](https://github.com/nodejs/node/blob/v25.x/lib/trace_events.js) - */ declare module "node:trace_events" { /** * The `Tracing` object is used to enable or disable tracing for sets of diff --git a/types/node/ts5.6/buffer.buffer.d.ts b/types/node/ts5.6/buffer.buffer.d.ts index bd32dc686ef282..118041bae095c7 100644 --- a/types/node/ts5.6/buffer.buffer.d.ts +++ b/types/node/ts5.6/buffer.buffer.d.ts @@ -172,7 +172,7 @@ declare module "node:buffer" { * If `totalLength` is not provided, it is calculated from the `Buffer` instances * in `list` by adding their lengths. * - * If `totalLength` is provided, it is coerced to an unsigned integer. If the + * If `totalLength` is provided, it must be an unsigned integer. If the * combined length of the `Buffer`s in `list` exceeds `totalLength`, the result is * truncated to `totalLength`. * diff --git a/types/node/tty.d.ts b/types/node/tty.d.ts index 9b97a1e1693886..39b4a7f26e8cf8 100644 --- a/types/node/tty.d.ts +++ b/types/node/tty.d.ts @@ -1,28 +1,3 @@ -/** - * The `node:tty` module provides the `tty.ReadStream` and `tty.WriteStream` classes. In most cases, it will not be necessary or possible to use this module - * directly. However, it can be accessed using: - * - * ```js - * import tty from 'node:tty'; - * ``` - * - * When Node.js detects that it is being run with a text terminal ("TTY") - * attached, `process.stdin` will, by default, be initialized as an instance of `tty.ReadStream` and both `process.stdout` and `process.stderr` will, by - * default, be instances of `tty.WriteStream`. The preferred method of determining - * whether Node.js is being run within a TTY context is to check that the value of - * the `process.stdout.isTTY` property is `true`: - * - * ```console - * $ node -p -e "Boolean(process.stdout.isTTY)" - * true - * $ node -p -e "Boolean(process.stdout.isTTY)" | cat - * false - * ``` - * - * In most cases, there should be little to no reason for an application to - * manually create instances of the `tty.ReadStream` and `tty.WriteStream` classes. - * @see [source](https://github.com/nodejs/node/blob/v25.x/lib/tty.js) - */ declare module "node:tty" { import * as net from "node:net"; /** diff --git a/types/node/url.d.ts b/types/node/url.d.ts index b0a8ed056fa2e3..8803a037059c83 100644 --- a/types/node/url.d.ts +++ b/types/node/url.d.ts @@ -1,12 +1,3 @@ -/** - * The `node:url` module provides utilities for URL resolution and parsing. It can - * be accessed using: - * - * ```js - * import url from 'node:url'; - * ``` - * @see [source](https://github.com/nodejs/node/blob/v25.x/lib/url.js) - */ declare module "node:url" { import { Blob, NonSharedBuffer } from "node:buffer"; import { ClientRequestArgs } from "node:http"; diff --git a/types/node/util.d.ts b/types/node/util.d.ts index 10062f655ca763..90f12aa21416cb 100644 --- a/types/node/util.d.ts +++ b/types/node/util.d.ts @@ -1,13 +1,3 @@ -/** - * The `node:util` module supports the needs of Node.js internal APIs. Many of the - * utilities are useful for application and module developers as well. To access - * it: - * - * ```js - * import util from 'node:util'; - * ``` - * @see [source](https://github.com/nodejs/node/blob/v25.x/lib/util.js) - */ declare module "node:util" { export * as types from "node:util/types"; export type InspectStyle = diff --git a/types/node/v8.d.ts b/types/node/v8.d.ts index 3c3eff29a735e6..c121c61c924fbe 100644 --- a/types/node/v8.d.ts +++ b/types/node/v8.d.ts @@ -1,11 +1,3 @@ -/** - * The `node:v8` module exposes APIs that are specific to the version of [V8](https://developers.google.com/v8/) built into the Node.js binary. It can be accessed using: - * - * ```js - * import v8 from 'node:v8'; - * ``` - * @see [source](https://github.com/nodejs/node/blob/v25.x/lib/v8.js) - */ declare module "node:v8" { import { NonSharedBuffer } from "node:buffer"; import { Readable } from "node:stream"; diff --git a/types/node/vm.d.ts b/types/node/vm.d.ts index d5e437e129407c..a349741ec0df79 100644 --- a/types/node/vm.d.ts +++ b/types/node/vm.d.ts @@ -1,41 +1,3 @@ -/** - * The `node:vm` module enables compiling and running code within V8 Virtual - * Machine contexts. - * - * **The `node: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. - * - * A common use case is to run the code in a different V8 Context. This means - * invoked code has a different global object than the invoking code. - * - * One can provide the context by `contextifying` an - * object. The invoked code treats any property in the context like a - * global variable. Any changes to global variables caused by the invoked - * code are reflected in the context object. - * - * ```js - * import vm from 'node:vm'; - * - * const x = 1; - * - * const context = { x: 2 }; - * vm.createContext(context); // Contextify the object. - * - * const code = 'x += 40; var y = 17;'; - * // `x` and `y` are global variables in the context. - * // Initially, x has the value 2 because that is the value of context.x. - * vm.runInContext(code, context); - * - * console.log(context.x); // 42 - * console.log(context.y); // 17 - * - * console.log(x); // 1; y is not defined. - * ``` - * @see [source](https://github.com/nodejs/node/blob/v25.x/lib/vm.js) - */ declare module "node:vm" { import { NonSharedBuffer } from "node:buffer"; import { ImportAttributes, ImportPhase } from "node:module"; diff --git a/types/node/wasi.d.ts b/types/node/wasi.d.ts index c206ae5d538899..a0d56cf89643f2 100644 --- a/types/node/wasi.d.ts +++ b/types/node/wasi.d.ts @@ -1,74 +1,3 @@ -/** - * **The `node:wasi` module does not currently provide the** - * **comprehensive file system security properties provided by some WASI runtimes.** - * **Full support for secure file system sandboxing may or may not be implemented in** - * **future. In the mean time, do not rely on it to run untrusted code.** - * - * The WASI API provides an implementation of the [WebAssembly System Interface](https://wasi.dev/) specification. WASI gives WebAssembly applications access to the underlying - * operating system via a collection of POSIX-like functions. - * - * ```js - * import { readFile } from 'node:fs/promises'; - * import { WASI } from 'node:wasi'; - * import { argv, env } from 'node:process'; - * - * const wasi = new WASI({ - * version: 'preview1', - * args: argv, - * env, - * preopens: { - * '/local': '/some/real/path/that/wasm/can/access', - * }, - * }); - * - * const wasm = await WebAssembly.compile( - * await readFile(new URL('./demo.wasm', import.meta.url)), - * ); - * const instance = await WebAssembly.instantiate(wasm, wasi.getImportObject()); - * - * wasi.start(instance); - * ``` - * - * To run the above example, create a new WebAssembly text format file named `demo.wat`: - * - * ```text - * (module - * ;; Import the required fd_write WASI function which will write the given io vectors to stdout - * ;; The function signature for fd_write is: - * ;; (File Descriptor, *iovs, iovs_len, nwritten) -> Returns number of bytes written - * (import "wasi_snapshot_preview1" "fd_write" (func $fd_write (param i32 i32 i32 i32) (result i32))) - * - * (memory 1) - * (export "memory" (memory 0)) - * - * ;; Write 'hello world\n' to memory at an offset of 8 bytes - * ;; Note the trailing newline which is required for the text to appear - * (data (i32.const 8) "hello world\n") - * - * (func $main (export "_start") - * ;; Creating a new io vector within linear memory - * (i32.store (i32.const 0) (i32.const 8)) ;; iov.iov_base - This is a pointer to the start of the 'hello world\n' string - * (i32.store (i32.const 4) (i32.const 12)) ;; iov.iov_len - The length of the 'hello world\n' string - * - * (call $fd_write - * (i32.const 1) ;; file_descriptor - 1 for stdout - * (i32.const 0) ;; *iovs - The pointer to the iov array, which is stored at memory location 0 - * (i32.const 1) ;; iovs_len - We're printing 1 string stored in an iov - so one. - * (i32.const 20) ;; nwritten - A place in memory to store the number of bytes written - * ) - * drop ;; Discard the number of bytes written from the top of the stack - * ) - * ) - * ``` - * - * Use [wabt](https://github.com/WebAssembly/wabt) to compile `.wat` to `.wasm` - * - * ```bash - * wat2wasm demo.wat - * ``` - * @experimental - * @see [source](https://github.com/nodejs/node/blob/v25.x/lib/wasi.js) - */ declare module "node:wasi" { interface WASIOptions { /** diff --git a/types/node/worker_threads.d.ts b/types/node/worker_threads.d.ts index 9a24e0bb751b62..fb602c3ff0bef6 100644 --- a/types/node/worker_threads.d.ts +++ b/types/node/worker_threads.d.ts @@ -1,59 +1,3 @@ -/** - * The `node:worker_threads` module enables the use of threads that execute - * JavaScript in parallel. To access it: - * - * ```js - * import worker from 'node:worker_threads'; - * ``` - * - * Workers (threads) are useful for performing CPU-intensive JavaScript operations. - * They do not help much with I/O-intensive work. The Node.js built-in - * asynchronous I/O operations are more efficient than Workers can be. - * - * Unlike `child_process` or `cluster`, `worker_threads` can share memory. They do - * so by transferring `ArrayBuffer` instances or sharing `SharedArrayBuffer` instances. - * - * ```js - * import { - * Worker, - * isMainThread, - * parentPort, - * workerData, - * } from 'node:worker_threads'; - * - * if (!isMainThread) { - * const { parse } = await import('some-js-parsing-library'); - * const script = workerData; - * parentPort.postMessage(parse(script)); - * } - * - * export default function parseJSAsync(script) { - * return new Promise((resolve, reject) => { - * const worker = new Worker(new URL(import.meta.url), { - * workerData: script, - * }); - * worker.on('message', resolve); - * worker.once('error', reject); - * worker.once('exit', (code) => { - * if (code !== 0) - * reject(new Error(`Worker stopped with exit code ${code}`)); - * }); - * }); - * }; - * ``` - * - * 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. - * - * When implementing a worker pool, use the `AsyncResource` API to inform - * diagnostic tools (e.g. to provide asynchronous stack traces) about the - * correlation between tasks and their outcomes. See `"Using AsyncResource for a Worker thread pool"` in the `async_hooks` documentation for an example implementation. - * - * 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/v25.x/lib/worker_threads.js) - */ declare module "node:worker_threads" { import { EventEmitter, @@ -396,11 +340,15 @@ declare module "node:worker_threads" { interface Worker extends InternalEventEmitter {} /** * Mark an object as not transferable. If `object` occurs in the transfer list of - * a `port.postMessage()` call, it is ignored. + * a [`port.postMessage()`](https://nodejs.org/docs/latest-v25.x/api/worker_threads.html#portpostmessagevalue-transferlist) call, an error is thrown. This is a no-op if + * `object` is a primitive value. * * In particular, this makes sense for objects that can be cloned, rather than * transferred, and which are used by other objects on the sending side. - * For example, Node.js marks the `ArrayBuffer`s it uses for its `Buffer pool` with this. + * For example, Node.js marks the `ArrayBuffer`s it uses for its + * [`Buffer` pool](https://nodejs.org/docs/latest-v25.x/api/buffer.html#static-method-bufferallocunsafesize) with this. + * `ArrayBuffer.prototype.transfer()` is disallowed on such array buffer + * instances. * * This operation cannot be undone. * @@ -414,11 +362,17 @@ declare module "node:worker_threads" { * markAsUntransferable(pooledBuffer); * * const { port1 } = new MessageChannel(); - * port1.postMessage(typedArray1, [ typedArray1.buffer ]); + * try { + * // This will throw an error, because pooledBuffer is not transferable. + * port1.postMessage(typedArray1, [ typedArray1.buffer ]); + * } catch (error) { + * // error.name === 'DataCloneError' + * } * * // The following line prints the contents of typedArray1 -- it still owns - * // its memory and has been cloned, not transferred. Without - * // `markAsUntransferable()`, this would print an empty Uint8Array. + * // its memory and has not been transferred. Without + * // `markAsUntransferable()`, this would print an empty Uint8Array and the + * // postMessage call would have succeeded. * // typedArray2 is intact as well. * console.log(typedArray1); * console.log(typedArray2); diff --git a/types/node/zlib.d.ts b/types/node/zlib.d.ts index 81d2aadb25426a..e19743008495bd 100644 --- a/types/node/zlib.d.ts +++ b/types/node/zlib.d.ts @@ -1,96 +1,3 @@ -/** - * The `node:zlib` module provides compression functionality implemented using - * Gzip, Deflate/Inflate, and Brotli. - * - * To access it: - * - * ```js - * import zlib from 'node:zlib'; - * ``` - * - * Compression and decompression are built around the Node.js - * [Streams API](https://nodejs.org/docs/latest-v25.x/api/stream.html). - * - * Compressing or decompressing a stream (such as a file) can be accomplished by - * piping the source stream through a `zlib` `Transform` stream into a destination - * stream: - * - * ```js - * import { createGzip } from 'node:zlib'; - * import { pipeline } from 'node:stream'; - * import { - * createReadStream, - * createWriteStream, - * } from 'node:fs'; - * - * const gzip = createGzip(); - * const source = createReadStream('input.txt'); - * const destination = createWriteStream('input.txt.gz'); - * - * pipeline(source, gzip, destination, (err) => { - * if (err) { - * console.error('An error occurred:', err); - * process.exitCode = 1; - * } - * }); - * - * // Or, Promisified - * - * import { promisify } from 'node:util'; - * const pipe = promisify(pipeline); - * - * async function do_gzip(input, output) { - * const gzip = createGzip(); - * const source = createReadStream(input); - * const destination = createWriteStream(output); - * await pipe(source, gzip, destination); - * } - * - * do_gzip('input.txt', 'input.txt.gz') - * .catch((err) => { - * console.error('An error occurred:', err); - * process.exitCode = 1; - * }); - * ``` - * - * It is also possible to compress or decompress data in a single step: - * - * ```js - * import { deflate, unzip } from 'node:zlib'; - * - * const input = '.................................'; - * deflate(input, (err, buffer) => { - * if (err) { - * console.error('An error occurred:', err); - * process.exitCode = 1; - * } - * console.log(buffer.toString('base64')); - * }); - * - * const buffer = Buffer.from('eJzT0yMAAGTvBe8=', 'base64'); - * unzip(buffer, (err, buffer) => { - * if (err) { - * console.error('An error occurred:', err); - * process.exitCode = 1; - * } - * console.log(buffer.toString()); - * }); - * - * // Or, Promisified - * - * import { promisify } from 'node:util'; - * const do_unzip = promisify(unzip); - * - * do_unzip(buffer) - * .then((buf) => console.log(buf.toString())) - * .catch((err) => { - * console.error('An error occurred:', err); - * process.exitCode = 1; - * }); - * ``` - * @since v0.5.8 - * @see [source](https://github.com/nodejs/node/blob/v25.x/lib/zlib.js) - */ declare module "node:zlib" { import { NonSharedBuffer } from "node:buffer"; import * as stream from "node:stream";