@types/node 24.12.0 → 25.5.0

node v24.12/sqlite.d.ts → node/sqlite.d.ts

@@ -6,7 +6,12 @@
  * import sqlite from 'node:sqlite';
  * ```
  *
- * This module is only available under the `node:` scheme.
+ * 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.
@@ -35,7 +40,7 @@
  * ```
  * @since v22.5.0
  * @experimental
- * @see [source](https://github.com/nodejs/node/blob/v24.x/lib/sqlite.js)
+ * @see [source](https://github.com/nodejs/node/blob/v25.x/lib/sqlite.js)
  */
 declare module "node:sqlite" {
     import { PathLike } from "node:fs";
@@ -120,9 +125,9 @@ declare module "node:sqlite" {
         allowUnknownNamedParameters?: boolean | undefined;
         /**
          * If `true`, enables the defensive flag. When the defensive flag is enabled,
-         * language features that allow ordinary SQL to deliberately corrupt the database
-         * file are disabled. The defensive flag can also be set using `enableDefensive()`.
-         * @since v24.12.0
+         * language features that allow ordinary SQL to deliberately corrupt the database file are disabled.
+         * The defensive flag can also be set using `enableDefensive()`.
+         * @since v25.1.0
          * @default true
          */
         defensive?: boolean | undefined;
@@ -228,6 +233,28 @@ declare module "node:sqlite" {
          */
         inverse?: ((accumulator: T, ...args: SQLOutputValue[]) => T) | undefined;
     }
+    interface PrepareOptions {
+        /**
+         * If `true`, integer fields are read as `BigInt`s.
+         * @since v25.5.0
+         */
+        readBigInts?: boolean | undefined;
+        /**
+         * If `true`, results are returned as arrays.
+         * @since v25.5.0
+         */
+        returnArrays?: boolean | undefined;
+        /**
+         * If `true`, allows binding named parameters without the prefix character.
+         * @since v25.5.0
+         */
+        allowBareNamedParameters?: boolean | undefined;
+        /**
+         * If `true`, unknown named parameters are ignored.
+         * @since v25.5.0
+         */
+        allowUnknownNamedParameters?: boolean | undefined;
+    }
     /**
      * This class represents a single [connection](https://www.sqlite.org/c3ref/sqlite3.html) to a SQLite database. All APIs
      * exposed by this class execute synchronously.
@@ -299,11 +326,9 @@ declare module "node:sqlite" {
         enableLoadExtension(allow: boolean): void;
         /**
          * Enables or disables the defensive flag. When the defensive flag is active,
-         * language features that allow ordinary SQL to deliberately corrupt the
-         * database file are disabled.
-         * See [`SQLITE_DBCONFIG_DEFENSIVE`](https://www.sqlite.org/c3ref/c_dbconfig_defensive.html#sqlitedbconfigdefensive)
-         * in the SQLite documentation for details.
-         * @since v24.12.0
+         * language features that allow ordinary SQL to deliberately corrupt the database file are disabled.
+         * See [`SQLITE_DBCONFIG_DEFENSIVE`](https://www.sqlite.org/c3ref/c_dbconfig_defensive.html#sqlitedbconfigdefensive) in the SQLite documentation for details.
+         * @since v25.1.0
          * @param active Whether to set the defensive flag.
          */
         enableDefensive(active: boolean): void;
@@ -333,7 +358,7 @@ declare module "node:sqlite" {
          * @param func The JavaScript function to call when the SQLite
          * function is invoked. The return value of this function should be a valid
          * SQLite data type: see
-         * [Type conversion between JavaScript and SQLite](https://nodejs.org/docs/latest-v24.x/api/sqlite.html#type-conversion-between-javascript-and-sqlite).
+         * [Type conversion between JavaScript and SQLite](https://nodejs.org/docs/latest-v25.x/api/sqlite.html#type-conversion-between-javascript-and-sqlite).
          * The result defaults to `NULL` if the return value is `undefined`.
          */
         function(
@@ -422,25 +447,79 @@ declare module "node:sqlite" {
          * around [`sqlite3_prepare_v2()`](https://www.sqlite.org/c3ref/prepare.html).
          * @since v22.5.0
          * @param sql A SQL string to compile to a prepared statement.
+         * @param options Optional configuration for the prepared statement.
          * @return The prepared statement.
          */
-        prepare(sql: string): StatementSync;
+        prepare(sql: string, options?: PrepareOptions): StatementSync;
         /**
-         * Creates a new {@link SQLTagStore `SQLTagStore`}, which is an LRU (Least Recently Used) cache for
-         * storing prepared statements. This allows for the efficient reuse of prepared
-         * statements by tagging them with a unique identifier.
+         * Creates a new {@link SQLTagStore}, which is a Least Recently Used (LRU) cache
+         * for storing prepared statements. This allows for the efficient reuse of
+         * prepared statements by tagging them with a unique identifier.
          *
          * When a tagged SQL literal is executed, the `SQLTagStore` checks if a prepared
-         * statement for that specific SQL string already exists in the cache. If it does,
-         * the cached statement is used. If not, a new prepared statement is created,
-         * executed, and then stored in the cache for future use. This mechanism helps to
-         * avoid the overhead of repeatedly parsing and preparing the same SQL statements.
+         * statement for the corresponding SQL query string already exists in the cache.
+         * If it does, the cached statement is used. If not, a new prepared statement is
+         * created, executed, and then stored in the cache for future use. This mechanism
+         * helps to avoid the overhead of repeatedly parsing and preparing the same SQL
+         * statements.
+         *
+         * Tagged statements bind the placeholder values from the template literal as
+         * parameters to the underlying prepared statement. For example:
+         *
+         * ```js
+         * sqlTagStore.get`SELECT ${value}`;
+         * ```
+         *
+         * is equivalent to:
+         *
+         * ```js
+         * db.prepare('SELECT ?').get(value);
+         * ```
+         *
+         * However, in the first example, the tag store will cache the underlying prepared
+         * statement for future use.
+         *
+         * > **Note:** The `${value}` syntax in tagged statements _binds_ a parameter to
+         * > the prepared statement. This differs from its behavior in _untagged_ template
+         * > literals, where it performs string interpolation.
+         * >
+         * > ```js
+         * > // This a safe example of binding a parameter to a tagged statement.
+         * > sqlTagStore.run`INSERT INTO t1 (id) VALUES (${id})`;
+         * >
+         * > // This is an *unsafe* example of an untagged template string.
+         * > // `id` is interpolated into the query text as a string.
+         * > // This can lead to SQL injection and data corruption.
+         * > db.run(`INSERT INTO t1 (id) VALUES (${id})`);
+         * > ```
+         *
+         * The tag store will match a statement from the cache if the query strings
+         * (including the positions of any bound placeholders) are identical.
+         *
+         * ```js
+         * // The following statements will match in the cache:
+         * sqlTagStore.get`SELECT * FROM t1 WHERE id = ${id} AND active = 1`;
+         * sqlTagStore.get`SELECT * FROM t1 WHERE id = ${12345} AND active = 1`;
+         *
+         * // The following statements will not match, as the query strings
+         * // and bound placeholders differ:
+         * sqlTagStore.get`SELECT * FROM t1 WHERE id = ${id} AND active = 1`;
+         * sqlTagStore.get`SELECT * FROM t1 WHERE id = 12345 AND active = 1`;
+         *
+         * // The following statements will not match, as matches are case-sensitive:
+         * sqlTagStore.get`SELECT * FROM t1 WHERE id = ${id} AND active = 1`;
+         * sqlTagStore.get`select * from t1 where id = ${id} and active = 1`;
+         * ```
+         *
+         * The only way of binding parameters in tagged statements is with the `${value}`
+         * syntax. Do not add parameter binding placeholders (`?` etc.) to the SQL query
+         * string itself.
          *
          * ```js
          * import { DatabaseSync } from 'node:sqlite';
          *
          * const db = new DatabaseSync(':memory:');
-         * const sql = db.createTagStore();
+         * const sql = db.createSQLTagStore();
          *
          * db.exec('CREATE TABLE users (id INT, name TEXT)');
          *
@@ -450,8 +529,8 @@ declare module "node:sqlite" {
          * sql.run`INSERT INTO users VALUES (2, 'Bob')`;
          *
          * // Using the 'get' method to retrieve a single row.
-         * const id = 1;
-         * const user = sql.get`SELECT * FROM users WHERE id = ${id}`;
+         * const name = 'Alice';
+         * const user = sql.get`SELECT * FROM users WHERE name = ${name}`;
          * console.log(user); // { id: 1, name: 'Alice' }
          *
          * // Using the 'all' method to retrieve all rows.
@@ -463,7 +542,6 @@ declare module "node:sqlite" {
          * // ]
          * ```
          * @since v24.9.0
-         * @param maxSize The maximum number of prepared statements to cache. **Default**: `1000`.
          * @returns A new SQL tag store for caching prepared statements.
          */
         createTagStore(maxSize?: number): SQLTagStore;
@@ -551,21 +629,29 @@ declare module "node:sqlite" {
      * This class represents a single LRU (Least Recently Used) cache for storing
      * prepared statements.
      *
-     * Instances of this class are created via the database.createTagStore() method,
-     * not by using a constructor. The store caches prepared statements based on the
-     * provided SQL query string. When the same query is seen again, the store
+     * Instances of this class are created via the `database.createTagStore()`
+     * method, not by using a constructor. The store caches prepared statements based
+     * on the provided SQL query string. When the same query is seen again, the store
      * retrieves the cached statement and safely applies the new values through
      * parameter binding, thereby preventing attacks like SQL injection.
      *
      * The cache has a maxSize that defaults to 1000 statements, but a custom size can
-     * be provided (e.g., database.createTagStore(100)). All APIs exposed by this
+     * be provided (e.g., `database.createTagStore(100)`). All APIs exposed by this
      * class execute synchronously.
      * @since v24.9.0
      */
     interface SQLTagStore {
         /**
-         * Executes the given SQL query and returns all resulting rows as an array of objects.
+         * Executes the given SQL query and returns all resulting rows as an array of
+         * objects.
+         *
+         * This function is intended to be used as a template literal tag, not to be
+         * called directly.
          * @since v24.9.0
+         * @param stringElements Template literal elements containing the SQL
+         * query.
+         * @param boundParameters Parameter values to be bound to placeholders in the template string.
+         * @returns An array of objects representing the rows returned by the query.
          */
         all(
             stringElements: TemplateStringsArray,
@@ -573,7 +659,15 @@ declare module "node:sqlite" {
         ): Record<string, SQLOutputValue>[];
         /**
          * Executes the given SQL query and returns the first resulting row as an object.
+         *
+         * This function is intended to be used as a template literal tag, not to be
+         * called directly.
          * @since v24.9.0
+         * @param stringElements Template literal elements containing the SQL
+         * query.
+         * @param boundParameters Parameter values to be bound to placeholders in the template string.
+         * @returns An object representing the first row returned by
+         * the query, or `undefined` if no rows are returned.
          */
         get(
             stringElements: TemplateStringsArray,
@@ -581,7 +675,14 @@ declare module "node:sqlite" {
         ): Record<string, SQLOutputValue> | undefined;
         /**
          * Executes the given SQL query and returns an iterator over the resulting rows.
+         *
+         * This function is intended to be used as a template literal tag, not to be
+         * called directly.
          * @since v24.9.0
+         * @param stringElements Template literal elements containing the SQL
+         * query.
+         * @param boundParameters Parameter values to be bound to placeholders in the template string.
+         * @returns An iterator that yields objects representing the rows returned by the query.
          */
         iterate(
             stringElements: TemplateStringsArray,
@@ -589,15 +690,21 @@ declare module "node:sqlite" {
         ): NodeJS.Iterator<Record<string, SQLOutputValue>>;
         /**
          * Executes the given SQL query, which is expected to not return any rows (e.g., INSERT, UPDATE, DELETE).
+         *
+         * This function is intended to be used as a template literal tag, not to be
+         * called directly.
          * @since v24.9.0
+         * @param stringElements Template literal elements containing the SQL
+         * query.
+         * @param boundParameters Parameter values to be bound to placeholders in the template string.
+         * @returns An object containing information about the execution, including `changes` and `lastInsertRowid`.
          */
         run(stringElements: TemplateStringsArray, ...boundParameters: SQLInputValue[]): StatementResultingChanges;
         /**
          * A read-only property that returns the number of prepared statements currently in the cache.
          * @since v24.9.0
-         * @returns The maximum number of prepared statements the cache can hold.
          */
-        size(): number;
+        readonly size: number;
         /**
          * A read-only property that returns the maximum number of prepared statements the cache can hold.
          * @since v24.9.0

node v24.12/stream/consumers.d.ts → node/stream/consumers.d.ts

@@ -3,36 +3,36 @@
  * streams.
  * @since v16.7.0
  */
-declare module "stream/consumers" {
-    import { Blob as NodeBlob, NonSharedBuffer } from "node:buffer";
-    import { ReadableStream as WebReadableStream } from "node:stream/web";
+declare module "node:stream/consumers" {
+    import { Blob, NonSharedBuffer } from "node:buffer";
+    import { ReadableStream } from "node:stream/web";
     /**
      * @since v16.7.0
      * @returns Fulfills with an `ArrayBuffer` containing the full contents of the stream.
      */
-    function arrayBuffer(stream: WebReadableStream | NodeJS.ReadableStream | AsyncIterable<any>): Promise<ArrayBuffer>;
+    function arrayBuffer(stream: ReadableStream | NodeJS.ReadableStream | AsyncIterable<any>): Promise<ArrayBuffer>;
     /**
      * @since v16.7.0
      * @returns Fulfills with a `Blob` containing the full contents of the stream.
      */
-    function blob(stream: WebReadableStream | NodeJS.ReadableStream | AsyncIterable<any>): Promise<NodeBlob>;
+    function blob(stream: ReadableStream | NodeJS.ReadableStream | AsyncIterable<any>): Promise<Blob>;
     /**
      * @since v16.7.0
      * @returns Fulfills with a `Buffer` containing the full contents of the stream.
      */
-    function buffer(stream: WebReadableStream | NodeJS.ReadableStream | AsyncIterable<any>): Promise<NonSharedBuffer>;
+    function buffer(stream: ReadableStream | NodeJS.ReadableStream | AsyncIterable<any>): Promise<NonSharedBuffer>;
     /**
      * @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: WebReadableStream | NodeJS.ReadableStream | AsyncIterable<any>): Promise<unknown>;
+    function json(stream: ReadableStream | NodeJS.ReadableStream | AsyncIterable<any>): Promise<unknown>;
     /**
      * @since v16.7.0
      * @returns Fulfills with the contents of the stream parsed as a UTF-8 encoded string.
      */
-    function text(stream: WebReadableStream | NodeJS.ReadableStream | AsyncIterable<any>): Promise<string>;
+    function text(stream: ReadableStream | NodeJS.ReadableStream | AsyncIterable<any>): Promise<string>;
 }
-declare module "node:stream/consumers" {
-    export * from "stream/consumers";
+declare module "stream/consumers" {
+    export * from "node:stream/consumers";
 }

node/stream/promises.d.ts

@@ -0,0 +1,211 @@
+declare module "node:stream/promises" {
+    import { Abortable } from "node:events";
+    import {
+        FinishedOptions as _FinishedOptions,
+        PipelineDestination,
+        PipelineSource,
+        PipelineTransform,
+    } from "node:stream";
+    import { ReadableStream, WritableStream } from "node:stream/web";
+    interface FinishedOptions extends _FinishedOptions {
+        /**
+         * If true, removes the listeners registered by this function before the promise is fulfilled.
+         * @default false
+         */
+        cleanup?: boolean | undefined;
+    }
+    /**
+     * ```js
+     * import { finished } from 'node:stream/promises';
+     * import { createReadStream } from 'node:fs';
+     *
+     * const rs = createReadStream('archive.tar');
+     *
+     * async function run() {
+     *   await finished(rs);
+     *   console.log('Stream is done reading.');
+     * }
+     *
+     * run().catch(console.error);
+     * rs.resume(); // Drain the stream.
+     * ```
+     *
+     * The `finished` API also provides a [callback version](https://nodejs.org/docs/latest-v25.x/api/stream.html#streamfinishedstream-options-callback).
+     *
+     * `stream.finished()` leaves dangling event listeners (in particular
+     * `'error'`, `'end'`, `'finish'` and `'close'`) after the returned promise is
+     * resolved or rejected. The reason for this is so that unexpected `'error'`
+     * events (due to incorrect stream implementations) do not cause unexpected
+     * crashes. If this is unwanted behavior then `options.cleanup` should be set to
+     * `true`:
+     *
+     * ```js
+     * await finished(rs, { cleanup: true });
+     * ```
+     * @since v15.0.0
+     * @returns Fulfills when the stream is no longer readable or writable.
+     */
+    function finished(
+        stream: NodeJS.ReadableStream | NodeJS.WritableStream | ReadableStream | WritableStream,
+        options?: FinishedOptions,
+    ): Promise<void>;
+    interface PipelineOptions extends Abortable {
+        end?: boolean | undefined;
+    }
+    type PipelineResult<S extends PipelineDestination<any, any>> = S extends (...args: any[]) => PromiseLike<infer R>
+        ? Promise<R>
+        : Promise<void>;
+    /**
+     * ```js
+     * import { pipeline } from 'node:stream/promises';
+     * import { createReadStream, createWriteStream } from 'node:fs';
+     * import { createGzip } from 'node:zlib';
+     *
+     * await pipeline(
+     *   createReadStream('archive.tar'),
+     *   createGzip(),
+     *   createWriteStream('archive.tar.gz'),
+     * );
+     * console.log('Pipeline succeeded.');
+     * ```
+     *
+     * To use an `AbortSignal`, pass it inside an options object, as the last argument.
+     * When the signal is aborted, `destroy` will be called on the underlying pipeline,
+     * with an `AbortError`.
+     *
+     * ```js
+     * import { pipeline } from 'node:stream/promises';
+     * import { createReadStream, createWriteStream } from 'node:fs';
+     * import { createGzip } from 'node:zlib';
+     *
+     * const ac = new AbortController();
+     * const { signal } = ac;
+     * setImmediate(() => ac.abort());
+     * try {
+     *   await pipeline(
+     *     createReadStream('archive.tar'),
+     *     createGzip(),
+     *     createWriteStream('archive.tar.gz'),
+     *     { signal },
+     *   );
+     * } catch (err) {
+     *   console.error(err); // AbortError
+     * }
+     * ```
+     *
+     * The `pipeline` API also supports async generators:
+     *
+     * ```js
+     * import { pipeline } from 'node:stream/promises';
+     * import { createReadStream, createWriteStream } from 'node:fs';
+     *
+     * await pipeline(
+     *   createReadStream('lowercase.txt'),
+     *   async function* (source, { signal }) {
+     *     source.setEncoding('utf8');  // Work with strings rather than `Buffer`s.
+     *     for await (const chunk of source) {
+     *       yield await processChunk(chunk, { signal });
+     *     }
+     *   },
+     *   createWriteStream('uppercase.txt'),
+     * );
+     * console.log('Pipeline succeeded.');
+     * ```
+     *
+     * Remember to handle the `signal` argument passed into the async generator.
+     * Especially in the case where the async generator is the source for the
+     * pipeline (i.e. first argument) or the pipeline will never complete.
+     *
+     * ```js
+     * import { pipeline } from 'node:stream/promises';
+     * import fs from 'node:fs';
+     * await pipeline(
+     *   async function* ({ signal }) {
+     *     await someLongRunningfn({ signal });
+     *     yield 'asd';
+     *   },
+     *   fs.createWriteStream('uppercase.txt'),
+     * );
+     * console.log('Pipeline succeeded.');
+     * ```
+     *
+     * The `pipeline` API provides [callback version](https://nodejs.org/docs/latest-v25.x/api/stream.html#streampipelinesource-transforms-destination-callback):
+     * @since v15.0.0
+     * @returns Fulfills when the pipeline is complete.
+     */
+    function pipeline<A extends PipelineSource<any>, B extends PipelineDestination<A, any>>(
+        source: A,
+        destination: B,
+        options?: PipelineOptions,
+    ): PipelineResult<B>;
+    function pipeline<
+        A extends PipelineSource<any>,
+        T1 extends PipelineTransform<A, any>,
+        B extends PipelineDestination<T1, any>,
+    >(
+        source: A,
+        transform1: T1,
+        destination: B,
+        options?: PipelineOptions,
+    ): PipelineResult<B>;
+    function pipeline<
+        A extends PipelineSource<any>,
+        T1 extends PipelineTransform<A, any>,
+        T2 extends PipelineTransform<T1, any>,
+        B extends PipelineDestination<T2, any>,
+    >(
+        source: A,
+        transform1: T1,
+        transform2: T2,
+        destination: B,
+        options?: PipelineOptions,
+    ): PipelineResult<B>;
+    function pipeline<
+        A extends PipelineSource<any>,
+        T1 extends PipelineTransform<A, any>,
+        T2 extends PipelineTransform<T1, any>,
+        T3 extends PipelineTransform<T2, any>,
+        B extends PipelineDestination<T3, any>,
+    >(
+        source: A,
+        transform1: T1,
+        transform2: T2,
+        transform3: T3,
+        destination: B,
+        options?: PipelineOptions,
+    ): PipelineResult<B>;
+    function pipeline<
+        A extends PipelineSource<any>,
+        T1 extends PipelineTransform<A, any>,
+        T2 extends PipelineTransform<T1, any>,
+        T3 extends PipelineTransform<T2, any>,
+        T4 extends PipelineTransform<T3, any>,
+        B extends PipelineDestination<T4, any>,
+    >(
+        source: A,
+        transform1: T1,
+        transform2: T2,
+        transform3: T3,
+        transform4: T4,
+        destination: B,
+        options?: PipelineOptions,
+    ): PipelineResult<B>;
+    function pipeline(
+        streams: readonly [PipelineSource<any>, ...PipelineTransform<any, any>[], PipelineDestination<any, any>],
+        options?: PipelineOptions,
+    ): Promise<void>;
+    function pipeline(
+        ...streams: [PipelineSource<any>, ...PipelineTransform<any, any>[], PipelineDestination<any, any>]
+    ): Promise<void>;
+    function pipeline(
+        ...streams: [
+            PipelineSource<any>,
+            ...PipelineTransform<any, any>[],
+            PipelineDestination<any, any>,
+            options: PipelineOptions,
+        ]
+    ): Promise<void>;
+}
+declare module "stream/promises" {
+    export * from "node:stream/promises";
+}