bun-types 1.1.44 → 1.1.45-canary.20250119T140626

package/bun.d.ts

@@ -22,6 +22,7 @@ declare module "bun" {
 		PeerCertificate,
 	} from "tls";
 	import type { Stats } from "node:fs";
+	import type { X509Certificate } from "node:crypto";
 	interface Env {
 		NODE_ENV?: string;
 		/**
@@ -2036,6 +2037,300 @@ declare module "bun" {
 		 */
 		stat(path: string, options?: S3Options): Promise<S3Stats>;
 	};
+	/**
+	 * Configuration options for SQL client connection and behavior
+	 *  @example
+	 * const config: SQLOptions = {
+	 *   host: 'localhost',
+	 *   port: 5432,
+	 *   user: 'dbuser',
+	 *   password: 'secretpass',
+	 *   database: 'myapp',
+	 *   idleTimeout: 30000,
+	 *   max: 20,
+	 *   onconnect: (client) => {
+	 *     console.log('Connected to database');
+	 *   }
+	 * };
+	 */
+	type SQLOptions = {
+		/** Connection URL (can be string or URL object) */
+		url: URL | string;
+		/** Database server hostname */
+		host: string;
+		/** Database server port number */
+		port: number | string;
+		/** Database user for authentication */
+		user: string;
+		/** Database password for authentication */
+		password: string;
+		/** Name of the database to connect to */
+		database: string;
+		/** Database adapter/driver to use */
+		adapter: string;
+		/** Maximum time in milliseconds to wait for connection to become available */
+		idleTimeout: number;
+		/** Maximum time in milliseconds to wait when establishing a connection */
+		connectionTimeout: number;
+		/** Maximum lifetime in milliseconds of a connection */
+		maxLifetime: number;
+		/** Whether to use TLS/SSL for the connection */
+		tls: boolean;
+		/** Callback function executed when a connection is established */
+		onconnect: (client: SQL) => void;
+		/** Callback function executed when a connection is closed */
+		onclose: (client: SQL) => void;
+		/** Maximum number of connections in the pool */
+		max: number;
+	};
+
+	/**
+	 * 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> {
+		/** Indicates if the query is currently executing */
+		active: boolean;
+		/** Indicates if the query has been cancelled */
+		cancelled: boolean;
+		/** Cancels the executing query */
+		cancel(): SQLQuery;
+		/** Executes the query */
+		execute(): SQLQuery;
+		/** Returns the raw query result */
+		raw(): SQLQuery;
+		/** Returns only the values from the query result */
+		values(): SQLQuery;
+	}
+
+	/**
+	 * Callback function type for transaction contexts
+	 * @param sql Function to execute SQL queries within the transaction
+	 */
+	type SQLContextCallback = (
+		sql: (strings: string, ...values: any[]) => SQLQuery | Array<SQLQuery>,
+	) => Promise<any>;
+
+	/**
+	 * 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
+		 * @example
+		 * const [user] = await sql`select * from users where id = ${1}`;
+		 */
+		(strings: string, ...values: any[]): SQLQuery;
+		/** Commits a distributed transaction also know as prepared transaction in postgres or XA transaction in MySQL
+		 * @example
+		 * await sql.commitDistributed("my_distributed_transaction");
+		 */
+		commitDistributed(name: string): Promise<undefined>;
+		/** Rolls back a distributed transaction also know as prepared transaction in postgres or XA transaction in MySQL
+		 * @example
+		 * await sql.rollbackDistributed("my_distributed_transaction");
+		 */
+		rollbackDistributed(name: string): Promise<undefined>;
+		/** Waits for the database connection to be established
+		 * @example
+		 * await sql.connect();
+		 */
+		connect(): Promise<SQL>;
+		/** Closes the database connection with optional timeout in seconds
+		 * @example
+		 * await sql.close({ timeout: 1 });
+		 */
+		close(options?: { timeout?: number }): Promise<undefined>;
+		/** Closes the database connection with optional timeout in seconds
+		 * @alias close
+		 * @example
+		 * await sql.end({ timeout: 1 });
+		 */
+		end(options?: { timeout?: number }): Promise<undefined>;
+		/** Flushes any pending operations */
+		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).
+		 * @example
+		 * const reserved = await sql.reserve();
+		 * await reserved`select * from users`;
+		 * await reserved.release();
+		 * // with in a production scenario would be something more like
+		 * const reserved = await sql.reserve();
+		 * try {
+		 *   // ... queries
+		 * } finally {
+		 *   await reserved.release();
+		 * }
+		 * //To make it simpler bun supportsSymbol.dispose and Symbol.asyncDispose
+		 * {
+		 * // always release after context (safer)
+		 * using reserved = await sql.reserve()
+		 * await reserved`select * from users`
+		 * }
+		 */
+		reserve(): Promise<ReservedSQL>;
+		/** Begins a new transaction
+		 * Will reserve a connection for the transaction and supply a scoped sql instance for all transaction uses in the callback function. sql.begin will resolve with the returned value from the callback function.
+		 * BEGIN is automatically sent with the optional options, and if anything fails ROLLBACK will be called so the connection can be released and execution can continue.
+		 * @example
+		 * const [user, account] = await sql.begin(async sql => {
+		 *   const [user] = await sql`
+		 *     insert into users (
+		 *       name
+		 *     ) values (
+		 *       'Murray'
+		 *     )
+		 *     returning *
+		 *   `
+		 *   const [account] = await sql`
+		 *     insert into accounts (
+		 *       user_id
+		 *     ) values (
+		 *       ${ user.user_id }
+		 *     )
+		 *     returning *
+		 *   `
+		 *   return [user, account]
+		 * })
+		 */
+		begin(fn: SQLContextCallback): Promise<any>;
+		/** Begins a new transaction with options
+		 * Will reserve a connection for the transaction and supply a scoped sql instance for all transaction uses in the callback function. sql.begin will resolve with the returned value from the callback function.
+		 * BEGIN is automatically sent with the optional options, and if anything fails ROLLBACK will be called so the connection can be released and execution can continue.
+		 * @example
+		 * const [user, account] = await sql.begin("read write", async sql => {
+		 *   const [user] = await sql`
+		 *     insert into users (
+		 *       name
+		 *     ) values (
+		 *       'Murray'
+		 *     )
+		 *     returning *
+		 *   `
+		 *   const [account] = await sql`
+		 *     insert into accounts (
+		 *       user_id
+		 *     ) values (
+		 *       ${ user.user_id }
+		 *     )
+		 *     returning *
+		 *   `
+		 *   return [user, account]
+		 * })
+		 */
+		begin(options: string, fn: SQLContextCallback): Promise<any>;
+		/** Alternative method to begin a transaction
+		 * Will reserve a connection for the transaction and supply a scoped sql instance for all transaction uses in the callback function. sql.transaction will resolve with the returned value from the callback function.
+		 * BEGIN is automatically sent with the optional options, and if anything fails ROLLBACK will be called so the connection can be released and execution can continue.
+		 * @alias begin
+		 * @example
+		 * const [user, account] = await sql.transaction(async sql => {
+		 *   const [user] = await sql`
+		 *     insert into users (
+		 *       name
+		 *     ) values (
+		 *       'Murray'
+		 *     )
+		 *     returning *
+		 *   `
+		 *   const [account] = await sql`
+		 *     insert into accounts (
+		 *       user_id
+		 *     ) values (
+		 *       ${ user.user_id }
+		 *     )
+		 *     returning *
+		 *   `
+		 *   return [user, account]
+		 * })
+		 */
+		transaction(fn: SQLContextCallback): Promise<any>;
+		/** Alternative method to begin a transaction with options
+		 * Will reserve a connection for the transaction and supply a scoped sql instance for all transaction uses in the callback function. sql.transaction will resolve with the returned value from the callback function.
+		 * BEGIN is automatically sent with the optional options, and if anything fails ROLLBACK will be called so the connection can be released and execution can continue.
+		 * @alias begin
+		 * @example
+		 * const [user, account] = await sql.transaction("read write", async sql => {
+		 *   const [user] = await sql`
+		 *     insert into users (
+		 *       name
+		 *     ) values (
+		 *       'Murray'
+		 *     )
+		 *     returning *
+		 *   `
+		 *   const [account] = await sql`
+		 *     insert into accounts (
+		 *       user_id
+		 *     ) values (
+		 *       ${ user.user_id }
+		 *     )
+		 *     returning *
+		 *   `
+		 *   return [user, account]
+		 * })
+		 */
+		transaction(options: string, fn: SQLContextCallback): Promise<any>;
+		/** Begins a distributed transaction
+		 * Also know as Two-Phase Commit, in a distributed transaction, Phase 1 involves the coordinator preparing nodes by ensuring data is written and ready to commit, while Phase 2 finalizes with nodes committing or rolling back based on the coordinator's decision, ensuring durability and releasing locks.
+		 * In PostgreSQL and MySQL distributed transactions persist beyond the original session, allowing privileged users or coordinators to commit/rollback them, ensuring support for distributed transactions, recovery, and administrative tasks.
+		 * beginDistributed will automatic rollback if any exception are not caught, and you can commit and rollback later if everything goes well.
+		 * PostgreSQL natively supports distributed transactions using PREPARE TRANSACTION, while MySQL uses XA Transactions, and MSSQL also supports distributed/XA transactions. However, in MSSQL, distributed transactions are tied to the original session, the DTC coordinator, and the specific connection.
+		 * These transactions are automatically committed or rolled back following the same rules as regular transactions, with no option for manual intervention from other sessions, in MSSQL distributed transactions are used to coordinate transactions using Linked Servers.
+		 * @example
+		 * await sql.beginDistributed("numbers", async sql => {
+		 *   await sql`create table if not exists numbers (a int)`;
+		 *   await sql`insert into numbers values(1)`;
+		 * });
+		 * // later you can call
+		 * await sql.commitDistributed("numbers");
+		 * // or await sql.rollbackDistributed("numbers");
+		 */
+		beginDistributed(name: string, fn: SQLContextCallback): Promise<any>;
+		/** Alternative method to begin a distributed transaction
+		 * @alias beginDistributed
+		 */
+		distributed(name: string, fn: SQLContextCallback): Promise<any>;
+		/** Current client options */
+		options: SQLOptions;
+	}
+
+	/**
+	 * Represents a reserved connection from the connection pool
+	 * Extends SQL with additional release functionality
+	 */
+	interface ReservedSQL extends SQL {
+		/** Releases the client back to the connection pool */
+		release(): void;
+	}
+
+	/**
+	 * Represents a client within a transaction context
+	 * Extends SQL with savepoint functionality
+	 */
+	interface TransactionSQL extends SQL {
+		/** Creates a savepoint within the current transaction */
+		savepoint(name: string, fn: SQLContextCallback): Promise<undefined>;
+	}
+
+	var sql: SQL;
 
 	/**
 	 *   This lets you use macros as regular imports
@@ -2356,7 +2651,8 @@ declare module "bun" {
 		| "import-rule"
 		| "url-token"
 		| "internal"
-		| "entry-point";
+		| "entry-point-run"
+		| "entry-point-build";
 
 	interface Import {
 		path: string;
@@ -5594,6 +5890,7 @@ declare module "bun" {
 		 * socket has been destroyed, `null` will be returned.
 		 */
 		getCertificate(): PeerCertificate | object | null;
+		getX509Certificate(): X509Certificate | undefined;
 
 		/**
 		 * Returns an object containing information on the negotiated cipher suite.
@@ -5632,6 +5929,7 @@ declare module "bun" {
 		 * @return A certificate object.
 		 */
 		getPeerCertificate(): PeerCertificate;
+		getPeerX509Certificate(): X509Certificate;
 
 		/**
 		 * See [SSL\_get\_shared\_sigalgs](https://www.openssl.org/docs/man1.1.1/man3/SSL_get_shared_sigalgs.html) for more information.

package/docs/api/fetch.md

@@ -195,7 +195,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/bun-v1.1.44
+[fetch] > User-Agent: Bun/1.1.45-canary.20250119T140626
 [fetch] > Accept: */*
 [fetch] > Host: example.com
 [fetch] > Accept-Encoding: gzip, deflate, br

package/docs/api/spawn.md

@@ -110,7 +110,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); // => "bun-v1.1.44"
+console.log(text); // => "1.1.45-canary.20250119T140626"
 ```
 
 Configure the output stream by passing one of the following values to `stdout/stderr`:

package/docs/api/transpiler.md

@@ -137,7 +137,8 @@ Each import in the `imports` array has a `path` and `kind`. Bun categories impor
 - `import-rule`: `@import 'foo.css'`
 - `url-token`: `url('./foo.png')`
 <!-- - `internal`: `import {foo} from 'bun:internal'`
-- `entry-point`: `import {foo} from 'bun:entry'` -->
+- `entry-point-build`: `import {foo} from 'bun:entry'`
+- `entry-point-run`: `bun ./mymodule` -->
 
 ## `.scanImports()`
 
@@ -267,7 +268,8 @@ type Import = {
   // The import was injected by Bun
   | "internal" 
   // Entry point (not common)
-  | "entry-point"
+  | "entry-point-build"
+  | "entry-point-run"
 }
 
 const transpiler = new Bun.Transpiler({ loader: "jsx" });

package/docs/bundler/index.md

@@ -533,7 +533,8 @@ export type BuildManifest = {
 };
 
 export type ImportKind =
-  | "entry-point"
+  | "entry-point-build"
+  | "entry-point-run"
   | "import-statement"
   | "require-call"
   | "dynamic-import"

package/docs/bundler/loaders.md

@@ -152,19 +152,6 @@ export default "Hello, world!";
 
 {% /codetabs %}
 
-### `wasm`
-
-**WebAssembly loader**. Default for `.wasm`.
-
-In the runtime, WebAssembly files can be directly imported. The file is read and returned as a `WebAssembly.Module`.
-
-```ts
-import wasm from "./module.wasm";
-console.log(wasm); // => WebAssembly.Module
-```
-
-In the bundler, `.wasm` files are handled using the [`file`](#file) loader.
-
 ### `napi`
 
 **Native addon loader**. Default for `.node`.

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 vbun-v1.1.44 (ca7428e9)
+bun publish v1.1.45-canary.20250119T140626 (ca7428e9)
 
 packed 203B package.json
 packed 224B README.md

package/docs/cli/run.md

@@ -106,13 +106,13 @@ $ bun run clean
  Done.
 ```
 
-Bun executes the script command in a subshell. It checks for the following shells in order, using the first one it finds: `bash`, `sh`, `zsh`.
+Bun executes the script command in a subshell. On Linux & macOS, it checks for the following shells in order, using the first one it finds: `bash`, `sh`, `zsh`. On windows, it uses [bun shell](https://bun.sh/docs/runtime/shell) to support bash-like syntax and many common commands.
 
 {% callout %}
 ⚡️ The startup time for `npm run` on Linux is roughly 170ms; with Bun it is `6ms`.
 {% /callout %}
 
-If there is a name conflict between a `package.json` script and a built-in `bun` command (`install`, `dev`, `upgrade`, etc.) Bun's built-in command takes precedence. In this case, use the more explicit `bun run` command to execute your package script.
+Scripts can also be run with the shorter command `bun <script>`, however if there is a built-in bun command with the same name, the built-in command takes precedence. In this case, use the more explicit `bun run <script>` command to execute your package script.
 
 ```bash
 $ bun run dev
@@ -194,3 +194,14 @@ $ bun --smol run index.tsx
 ```
 
 This causes the garbage collector to run more frequently, which can slow down execution. However, it can be useful in environments with limited memory. Bun automatically adjusts the garbage collector's heap size based on the available memory (accounting for cgroups and other memory limits) with and without the `--smol` flag, so this is mostly useful for cases where you want to make the heap size grow more slowly.
+
+## Resolution order
+
+Absolute paths and paths starting with `./` or `.\\` are always executed as source files. Unless using `bun run`, running a file with an allowed extension will prefer the file over a package.json script.
+
+When there is a package.json script and a file with the same name, `bun run` prioritizes the package.json script. The full resolution order is:
+
+1. package.json scripts, eg `bun run build`
+2. Source files, eg `bun run src/main.js`
+3. Binaries from project packages, eg `bun add eslint && bun run eslint`
+4. (`bun run` only) System commands, eg `bun run ls`

package/docs/guides/ecosystem/ssr-react.md

@@ -2,11 +2,11 @@
 name: Server-side render (SSR) a React component
 ---
 
-To get started, install the canary version of `react` & `react-dom`:
+To get started, install `react` & `react-dom`:
 
 ```sh
 # Any package manager can be used
-$ bun add react@canary react-dom@canary
+$ bun add react react-dom
 ```
 
 ---
@@ -48,4 +48,4 @@ Bun.serve({
 
 ---
 
-React `19` and later includes an [SSR optimization](https://github.com/facebook/react/pull/25597) that takes advantage of Bun's "direct" `ReadableStream` implementation. If you run into an error like `export named 'renderToReadableStream' not found`, please make sure to install the canary version of `react` & `react-dom`, or import from `react-dom/server.browser` instead of `react-dom/server`. See [facebook/react#28941](https://github.com/facebook/react/issues/28941) for more information.
+React `19` and later includes an [SSR optimization](https://github.com/facebook/react/pull/25597) that takes advantage of Bun's "direct" `ReadableStream` implementation. If you run into an error like `export named 'renderToReadableStream' not found`, please make sure to install version `19` of `react` & `react-dom`, or import from `react-dom/server.browser` instead of `react-dom/server`. See [facebook/react#28941](https://github.com/facebook/react/issues/28941) for more information.

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/bun-v1.1.44" -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.1.45-canary.20250119T140626" -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/bun-v1.1.44
+[fetch] > User-Agent: Bun/1.1.45-canary.20250119T140626
 [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/bun-v1.1.44
+[fetch] > User-Agent: Bun/1.1.45-canary.20250119T140626
 [fetch] > Accept: */*
 [fetch] > Host: example.com
 [fetch] > Accept-Encoding: gzip, deflate, br

package/docs/runtime/nodejs-apis.md

@@ -58,6 +58,10 @@ This page is updated regularly to reflect compatibility status of the latest ver
 
 🟢 Fully implemented.
 
+### [`node:stream`](https://nodejs.org/api/stream.html)
+
+🟢 Fully implemented.
+
 ### [`node:string_decoder`](https://nodejs.org/api/string_decoder.html)
 
 🟢 Fully implemented. 100% of Node.js's test suite passes.
@@ -92,7 +96,7 @@ This page is updated regularly to reflect compatibility status of the latest ver
 
 ### [`node:crypto`](https://nodejs.org/api/crypto.html)
 
-🟡 Missing `Certificate` `ECDH` `X509Certificate` `checkPrime` `checkPrimeSync` `diffieHellman` `generatePrime` `generatePrimeSync` `getCipherInfo` `getFips` `hkdf` `hkdfSync` `secureHeapUsed` `setEngine` `setFips`
+🟡 Missing `ECDH` `checkPrime` `checkPrimeSync` `generatePrime` `generatePrimeSync` `hkdf` `hkdfSync` `secureHeapUsed` `setEngine` `setFips`
 
 Some methods are not optimized yet.
 
@@ -129,10 +133,6 @@ Some methods are not optimized yet.
 
 🟡 See [`process`](#process) Global.
 
-### [`node:stream`](https://nodejs.org/api/stream.html)
-
-🟡 Missing `toWeb`
-
 ### [`node:sys`](https://nodejs.org/api/util.html)
 
 🟡 See [`node:util`](#node-util).

package/docs/test/dom.md

@@ -55,7 +55,7 @@ Let's run this test with `bun test`:
 
 ```bash
 $ bun test
-bun test vbun-v1.1.44
+bun test v1.1.45-canary.20250119T140626
 
 dom.test.ts:
 ✓ dom test [0.82ms]

package/package.json

@@ -1,5 +1,5 @@
 {
-	"version": "1.1.44",
+	"version": "1.1.45-canary.20250119T140626",
 	"name": "bun-types",
 	"license": "MIT",
 	"main": "",