@types/node 25.5.1 → 25.6.0

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 {
         /**

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<WorkerEventMap> {}
     /**
      * 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);

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";