bun-types 1.2.13-canary.20250505T140703 → 1.2.13-canary.20250507T140734

package/bun.d.ts

@@ -991,11 +991,9 @@ declare module "bun" {
   function fileURLToPath(url: URL | string): string;
 
   /**
-   * Fast incremental writer that becomes an `ArrayBuffer` on end().
+   * Fast incremental writer that becomes an {@link ArrayBuffer} on end().
    */
   class ArrayBufferSink {
-    constructor();
-
     start(options?: {
       asUint8Array?: boolean;
       /**
@@ -1320,7 +1318,8 @@ declare module "bun" {
    *   }
    * };
    */
-  type SQLOptions = {
+
+  interface SQLOptions {
     /** Connection URL (can be string or URL object) */
     url?: URL | string;
     /** Database server hostname */
@@ -1369,27 +1368,33 @@ declare module "bun" {
     bigint?: boolean;
     /** Automatic creation of prepared statements, defaults to true */
     prepare?: boolean;
-  };
+  }
 
   /**
    * Represents a SQL query that can be executed, with additional control methods
    * Extends Promise to allow for async/await usage
    */
-  interface SQLQuery extends Promise<any> {
+  interface SQLQuery<T = any> extends Promise<T> {
     /** Indicates if the query is currently executing */
     active: boolean;
+
     /** Indicates if the query has been cancelled */
     cancelled: boolean;
+
     /** Cancels the executing query */
-    cancel(): SQLQuery;
+    cancel(): SQLQuery<T>;
+
     /** Execute as a simple query, no parameters are allowed but can execute multiple commands separated by semicolons */
-    simple(): SQLQuery;
+    simple(): SQLQuery<T>;
+
     /** Executes the query */
-    execute(): SQLQuery;
+    execute(): SQLQuery<T>;
+
     /** Returns the raw query result */
-    raw(): SQLQuery;
+    raw(): SQLQuery<T>;
+
     /** Returns only the values from the query result */
-    values(): SQLQuery;
+    values(): SQLQuery<T>;
   }
 
   /**
@@ -1407,65 +1412,117 @@ declare module "bun" {
    * Main SQL client interface providing connection and transaction management
    */
   interface SQL {
-    /** Creates a new SQL client instance
-     * @example
-     * const sql = new SQL("postgres://localhost:5432/mydb");
-     * const sql = new SQL(new URL("postgres://localhost:5432/mydb"));
-     */
-    new (connectionString: string | URL): SQL;
-    /** Creates a new SQL client instance with options
-     * @example
-     * const sql = new SQL("postgres://localhost:5432/mydb", { idleTimeout: 1000 });
-     */
-    new (connectionString: string | URL, options: SQLOptions): SQL;
-    /** Creates a new SQL client instance with options
-     * @example
-     * const sql = new SQL({ url: "postgres://localhost:5432/mydb", idleTimeout: 1000 });
-     */
-    new (options?: SQLOptions): SQL;
-    /** Executes a SQL query using template literals
+    /**
+     * Executes a SQL query using template literals
      * @example
+     * ```ts
      * const [user] = await sql`select * from users where id = ${1}`;
+     * ```
      */
-    (strings: string | TemplateStringsArray, ...values: any[]): SQLQuery;
+    (strings: string[] | TemplateStringsArray, ...values: any[]): SQLQuery;
+
     /**
-     * Helper function to allow easy use to insert values into a query
+     * Helper function for inserting an object into a query
+     *
      * @example
+     * ```ts
+     * // Insert an object
      * const result = await sql`insert into users ${sql(users)} RETURNING *`;
+     *
+     * // Or pick specific columns
+     * const result = await sql`insert into users ${sql(users, "id", "name")} RETURNING *`;
+     *
+     * // Or a single object
+     * const result = await sql`insert into users ${sql(user)} RETURNING *`;
+     * ```
      */
-    (obj: any): SQLQuery;
-    /** Commits a distributed transaction also know as prepared transaction in postgres or XA transaction in MySQL
+    <T extends { [Key in PropertyKey]: unknown }>(obj: T | T[] | readonly T[], ...columns: (keyof T)[]): SQLQuery;
+
+    /**
+     * Helper function for inserting any serializable value into a query
+     *
      * @example
+     * ```ts
+     * const result = await sql`SELECT * FROM users WHERE id IN ${sql([1, 2, 3])}`;
+     * ```
+     */
+    (obj: unknown): SQLQuery;
+
+    /**
+     * Commits a distributed transaction also know as prepared transaction in postgres or XA transaction in MySQL
+     *
+     * @param name - The name of the distributed transaction
+     *
+     * @example
+     * ```ts
      * await sql.commitDistributed("my_distributed_transaction");
+     * ```
      */
     commitDistributed(name: string): Promise<void>;
-    /** Rolls back a distributed transaction also know as prepared transaction in postgres or XA transaction in MySQL
+
+    /**
+     * Rolls back a distributed transaction also know as prepared transaction in postgres or XA transaction in MySQL
+     *
+     * @param name - The name of the distributed transaction
+     *
      * @example
+     * ```ts
      * await sql.rollbackDistributed("my_distributed_transaction");
+     * ```
      */
     rollbackDistributed(name: string): Promise<void>;
+
     /** Waits for the database connection to be established
+     *
      * @example
+     * ```ts
      * await sql.connect();
+     * ```
      */
     connect(): Promise<SQL>;
-    /** Closes the database connection with optional timeout in seconds. If timeout is 0, it will close immediately, if is not provided it will wait for all queries to finish before closing.
+
+    /**
+     * Closes the database connection with optional timeout in seconds. If timeout is 0, it will close immediately, if is not provided it will wait for all queries to finish before closing.
+     *
+     * @param options - The options for the close
+     *
      * @example
+     * ```ts
      * await sql.close({ timeout: 1 });
+     * ```
      */
     close(options?: { timeout?: number }): Promise<void>;
-    /** Closes the database connection with optional timeout in seconds. If timeout is 0, it will close immediately, if is not provided it will wait for all queries to finish before closing.
-     * @alias close
+
+    /**
+     * Closes the database connection with optional timeout in seconds. If timeout is 0, it will close immediately, if is not provided it will wait for all queries to finish before closing.
+     * This is an alias of {@link SQL.close}
+     *
+     * @param options - The options for the close
+     *
      * @example
+     * ```ts
      * await sql.end({ timeout: 1 });
+     * ```
      */
     end(options?: { timeout?: number }): Promise<void>;
-    /** Flushes any pending operations */
+
+    /**
+     * Flushes any pending operations
+     *
+     * @example
+     * ```ts
+     * sql.flush();
+     * ```
+     */
     flush(): void;
-    /**  The reserve method pulls out a connection from the pool, and returns a client that wraps the single connection.
-     *   This can be used for running queries on an isolated connection.
-     *   Calling reserve in a reserved Sql will return a new reserved connection, not the same connection (behavior matches postgres package).
+
+    /**
+     * The reserve method pulls out a connection from the pool, and returns a client that wraps the single connection.
+     * This can be used for running queries on an isolated connection.
+     * Calling reserve in a reserved Sql will return a new reserved connection,  not the same connection (behavior matches postgres package).
+     *
      * @example
+     * ```ts
      * const reserved = await sql.reserve();
      * await reserved`select * from users`;
      * await reserved.release();
@@ -1476,12 +1533,14 @@ declare module "bun" {
      * } finally {
      *   await reserved.release();
      * }
-     * //To make it simpler bun supportsSymbol.dispose and Symbol.asyncDispose
+     *
+     * // Bun supports Symbol.dispose and Symbol.asyncDispose
      * {
-     * // always release after context (safer)
-     * using reserved = await sql.reserve()
-     * await reserved`select * from users`
+     *  // always release after context (safer)
+     *  using reserved = await sql.reserve()
+     *  await reserved`select * from users`
      * }
+     * ```
      */
     reserve(): Promise<ReservedSQL>;
     /** Begins a new transaction
@@ -1626,6 +1685,45 @@ declare module "bun" {
 
     [Symbol.asyncDispose](): Promise<any>;
   }
+  const SQL: {
+    /**
+     * Creates a new SQL client instance
+     *
+     * @param connectionString - The connection string for the SQL client
+     *
+     * @example
+     * ```ts
+     * const sql = new SQL("postgres://localhost:5432/mydb");
+     * const sql = new SQL(new URL("postgres://localhost:5432/mydb"));
+     * ```
+     */
+    new (connectionString: string | URL): SQL;
+
+    /**
+     * Creates a new SQL client instance with options
+     *
+     * @param connectionString - The connection string for the SQL client
+     * @param options - The options for the SQL client
+     *
+     * @example
+     * ```ts
+     * const sql = new SQL("postgres://localhost:5432/mydb", { idleTimeout: 1000 });
+     * ```
+     */
+    new (connectionString: string | URL, options: Omit<SQLOptions, "url">): SQL;
+
+    /**
+     * Creates a new SQL client instance with options
+     *
+     * @param options - The options for the SQL client
+     *
+     * @example
+     * ```ts
+     * const sql = new SQL({ url: "postgres://localhost:5432/mydb", idleTimeout: 1000 });
+     * ```
+     */
+    new (options?: SQLOptions): SQL;
+  };
 
   /**
    * Represents a reserved connection from the connection pool
@@ -1697,21 +1795,14 @@ declare module "bun" {
    *
    * @category Database
    */
-  var sql: SQL;
+  const sql: SQL;
 
   /**
    * SQL client for PostgreSQL
    *
    * @category Database
    */
-  var postgres: SQL;
-
-  /**
-   * The SQL constructor
-   *
-   * @category Database
-   */
-  var SQL: SQL;
+  const postgres: SQL;
 
   /**
    * Generate and verify CSRF tokens
@@ -6522,9 +6613,10 @@ declare module "bun" {
       ipc?(
         message: any,
         /**
-         * The {@link Subprocess} that sent the message
+         * The {@link Subprocess} that received the message
          */
         subprocess: Subprocess<In, Out, Err>,
+        handle?: unknown,
       ): void;
 
       /**

package/docs/api/fetch.md

@@ -337,7 +337,7 @@ This will print the request and response headers to your terminal:
 ```sh
 [fetch] > HTTP/1.1 GET http://example.com/
 [fetch] > Connection: keep-alive
-[fetch] > User-Agent: Bun/1.2.13-canary.20250505T140703
+[fetch] > User-Agent: Bun/1.2.13-canary.20250507T140734
 [fetch] > Accept: */*
 [fetch] > Host: example.com
 [fetch] > Accept-Encoding: gzip, deflate, br

package/docs/api/spawn.md

@@ -120,7 +120,7 @@ You can read results from the subprocess via the `stdout` and `stderr` propertie
 ```ts
 const proc = Bun.spawn(["bun", "--version"]);
 const text = await new Response(proc.stdout).text();
-console.log(text); // => "1.2.13-canary.20250505T140703"
+console.log(text); // => "1.2.13-canary.20250507T140734"
 ```
 
 Configure the output stream by passing one of the following values to `stdout/stderr`:

package/docs/cli/publish.md

@@ -7,7 +7,7 @@ Use `bun publish` to publish a package to the npm registry.
 $ bun publish
 
 ## Output
-bun publish v1.2.13-canary.20250505T140703 (ca7428e9)
+bun publish v1.2.13-canary.20250507T140734 (ca7428e9)
 
 packed 203B package.json
 packed 224B README.md

package/docs/guides/ecosystem/nuxt.md

@@ -9,7 +9,7 @@ $ bunx nuxi init my-nuxt-app
 ✔ Which package manager would you like to use?
 bun
 ◐ Installing dependencies...
-bun install v1.2.13-canary.20250505T140703 (16b4bf34)
+bun install v1.2.13-canary.20250507T140734 (16b4bf34)
  + @nuxt/devtools@0.8.2
  + nuxt@3.7.0
  785 packages installed [2.67s]

package/docs/guides/install/add-peer.md

@@ -16,7 +16,7 @@ This will add the package to `peerDependencies` in `package.json`.
 ```json-diff
 {
   "peerDependencies": {
-+   "@types/bun": "^1.2.13-canary.20250505T140703"
++   "@types/bun": "^1.2.13-canary.20250507T140734"
   }
 }
 ```
@@ -28,7 +28,7 @@ Running `bun install` will install peer dependencies by default, unless marked o
 ```json-diff
 {
   "peerDependencies": {
-    "@types/bun": "^1.2.13-canary.20250505T140703"
+    "@types/bun": "^1.2.13-canary.20250507T140734"
   },
   "peerDependenciesMeta": {
 +   "@types/bun": {

package/docs/guides/install/from-npm-install-to-bun-install.md

@@ -97,7 +97,7 @@ $ bun update
 $ bun update @types/bun --latest
 
 # Update a dependency to a specific version
-$ bun update @types/bun@1.2.13-canary.20250505T140703
+$ bun update @types/bun@1.2.13-canary.20250507T140734
 
 # Update all dependencies to the latest versions
 $ bun update --latest

package/docs/guides/test/run-tests.md

@@ -21,7 +21,7 @@ Here's what the output of a typical test run looks like. In this case, there are
 
 ```sh
 $ bun test
-bun test v1.2.13-canary.20250505T140703 (9c68abdb)
+bun test v1.2.13-canary.20250507T140734 (9c68abdb)
 
 test.test.js:
 ✓ add [0.87ms]
@@ -47,7 +47,7 @@ To only run certain test files, pass a positional argument to `bun test`. The ru
 
 ```sh
 $ bun test test3
-bun test v1.2.13-canary.20250505T140703 (9c68abdb)
+bun test v1.2.13-canary.20250507T140734 (9c68abdb)
 
 test3.test.js:
 ✓ add [1.40ms]
@@ -85,7 +85,7 @@ Adding `-t add` will only run tests with "add" in the name. This works with test
 
 ```sh
 $ bun test -t add
-bun test v1.2.13-canary.20250505T140703 (9c68abdb)
+bun test v1.2.13-canary.20250507T140734 (9c68abdb)
 
 test.test.js:
 ✓ add [1.79ms]

package/docs/guides/test/snapshot.md

@@ -18,7 +18,7 @@ The first time this test is executed, Bun will evaluate the value passed into `e
 
 ```sh
 $ bun test test/snap
-bun test v1.2.13-canary.20250505T140703 (9c68abdb)
+bun test v1.2.13-canary.20250507T140734 (9c68abdb)
 
 test/snap.test.ts:
 ✓ snapshot [1.48ms]
@@ -61,7 +61,7 @@ Later, when this test file is executed again, Bun will read the snapshot file an
 
 ```sh
 $ bun test
-bun test v1.2.13-canary.20250505T140703 (9c68abdb)
+bun test v1.2.13-canary.20250507T140734 (9c68abdb)
 
 test/snap.test.ts:
 ✓ snapshot [1.05ms]
@@ -78,7 +78,7 @@ To update snapshots, use the `--update-snapshots` flag.
 
 ```sh
 $ bun test --update-snapshots
-bun test v1.2.13-canary.20250505T140703 (9c68abdb)
+bun test v1.2.13-canary.20250507T140734 (9c68abdb)
 
 test/snap.test.ts:
 ✓ snapshot [0.86ms]

package/docs/guides/test/update-snapshots.md

@@ -29,7 +29,7 @@ To regenerate snapshots, use the `--update-snapshots` flag.
 
 ```sh
 $ bun test --update-snapshots
-bun test v1.2.13-canary.20250505T140703 (9c68abdb)
+bun test v1.2.13-canary.20250507T140734 (9c68abdb)
 
 test/snap.test.ts:
 ✓ snapshot [0.86ms]

package/docs/guides/util/version.md

@@ -5,7 +5,7 @@ name: Get the current Bun version
 Get the current version of Bun in a semver format.
 
 ```ts#index.ts
-Bun.version; // => "1.2.13-canary.20250505T140703"
+Bun.version; // => "1.2.13-canary.20250507T140734"
 ```
 
 ---

package/docs/installation.md

@@ -14,7 +14,7 @@ Kernel version 5.6 or higher is strongly recommended, but the minimum is 5.1. Us
 ```bash#macOS/Linux_(curl)
 $ curl -fsSL https://bun.sh/install | bash # for macOS, Linux, and WSL
 # to install a specific version
-$ curl -fsSL https://bun.sh/install | bash -s "bun-v1.2.13-canary.20250505T140703"
+$ curl -fsSL https://bun.sh/install | bash -s "bun-v1.2.13-canary.20250507T140734"
 ```
 
 ```bash#npm
@@ -189,10 +189,10 @@ Since Bun is a single binary, you can install older versions of Bun by re-runnin
 
 ### Installing a specific version of Bun on Linux/Mac
 
-To install a specific version of Bun, you can pass the git tag of the version you want to install to the install script, such as `bun-v1.2.0` or `bun-v1.2.13-canary.20250505T140703`.
+To install a specific version of Bun, you can pass the git tag of the version you want to install to the install script, such as `bun-v1.2.0` or `bun-v1.2.13-canary.20250507T140734`.
 
 ```sh
-$ curl -fsSL https://bun.sh/install | bash -s "bun-v1.2.13-canary.20250505T140703"
+$ curl -fsSL https://bun.sh/install | bash -s "bun-v1.2.13-canary.20250507T140734"
 ```
 
 ### Installing a specific version of Bun on Windows
@@ -201,7 +201,7 @@ On Windows, you can install a specific version of Bun by passing the version num
 
 ```sh
 # PowerShell:
-$ iex "& {$(irm https://bun.sh/install.ps1)} -Version 1.2.13-canary.20250505T140703"
+$ iex "& {$(irm https://bun.sh/install.ps1)} -Version 1.2.13-canary.20250507T140734"
 ```
 
 ## Downloading Bun binaries directly

package/docs/runtime/debugger.md

@@ -124,11 +124,11 @@ await fetch("https://example.com", {
 This prints the `fetch` request as a single-line `curl` command to let you copy-paste into your terminal to replicate the request.
 
 ```sh
-[fetch] $ curl --http1.1 "https://example.com/" -X POST -H "content-type: application/json" -H "Connection: keep-alive" -H "User-Agent: Bun/1.2.13-canary.20250505T140703" -H "Accept: */*" -H "Host: example.com" -H "Accept-Encoding: gzip, deflate, br" --compressed -H "Content-Length: 13" --data-raw "{\"foo\":\"bar\"}"
+[fetch] $ curl --http1.1 "https://example.com/" -X POST -H "content-type: application/json" -H "Connection: keep-alive" -H "User-Agent: Bun/1.2.13-canary.20250507T140734" -H "Accept: */*" -H "Host: example.com" -H "Accept-Encoding: gzip, deflate, br" --compressed -H "Content-Length: 13" --data-raw "{\"foo\":\"bar\"}"
 [fetch] > HTTP/1.1 POST https://example.com/
 [fetch] > content-type: application/json
 [fetch] > Connection: keep-alive
-[fetch] > User-Agent: Bun/1.2.13-canary.20250505T140703
+[fetch] > User-Agent: Bun/1.2.13-canary.20250507T140734
 [fetch] > Accept: */*
 [fetch] > Host: example.com
 [fetch] > Accept-Encoding: gzip, deflate, br
@@ -170,7 +170,7 @@ This prints the following to the console:
 [fetch] > HTTP/1.1 POST https://example.com/
 [fetch] > content-type: application/json
 [fetch] > Connection: keep-alive
-[fetch] > User-Agent: Bun/1.2.13-canary.20250505T140703
+[fetch] > User-Agent: Bun/1.2.13-canary.20250507T140734
 [fetch] > Accept: */*
 [fetch] > Host: example.com
 [fetch] > Accept-Encoding: gzip, deflate, br

package/docs/runtime/plugins.md

@@ -25,6 +25,12 @@ Plugins have to be loaded before any other code runs! To achieve this, use the `
 preload = ["./myPlugin.ts"]
 ```
 
+Preloads can be either local files or npm packages. Anything that can be imported/required can be preloaded.
+
+```toml
+preload = ["bun-plugin-foo"]
+```
+
 To preload files before `bun test`:
 
 ```toml
@@ -32,7 +38,7 @@ To preload files before `bun test`:
 preload = ["./myPlugin.ts"]
 ```
 
-## Third-party plugins
+## Plugin conventions
 
 By convention, third-party plugins intended for consumption should export a factory function that accepts some configuration and returns a plugin object.
 

package/docs/test/dom.md

@@ -55,7 +55,7 @@ Let's run this test with `bun test`:
 
 ```bash
 $ bun test
-bun test v1.2.13-canary.20250505T140703
+bun test v1.2.13-canary.20250507T140734
 
 dom.test.ts:
 ✓ dom test [0.82ms]

package/globals.d.ts

@@ -954,13 +954,6 @@ interface ErrorConstructor {
    */
   captureStackTrace(targetObject: object, constructorOpt?: Function): void;
 
-  /**
-   * Optional override for formatting stack traces
-   *
-   * @see https://v8.dev/docs/stack-trace-api#customizing-stack-traces
-   */
-  prepareStackTrace?: ((err: Error, stackTraces: NodeJS.CallSite[]) => any) | undefined;
-
   /**
    * The maximum number of stack frames to capture.
    */

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.2.13-canary.20250505T140703",
+  "version": "1.2.13-canary.20250507T140734",
   "name": "bun-types",
   "license": "MIT",
   "types": "./index.d.ts",