bun-types 1.1.45 → 1.2.0-canary.20250122T140708

package/bun.d.ts

@@ -1300,33 +1300,7 @@ declare module "bun" {
 	}
 
 	var S3Client: S3Client;
-
-	/**
-	 * Creates a new S3File instance for working with a single file.
-	 *
-	 * @param path The path or key of the file
-	 * @param options S3 configuration options
-	 * @returns `S3File` instance for the specified path
-	 *
-	 * @example
-	 *    import { s3 } from "bun";
-	 *    const file = s3("my-file.txt", {
-	 *      bucket: "my-bucket",
-	 *      accessKeyId: "your-access-key",
-	 *      secretAccessKey: "your-secret-key"
-	 *    });
-	 *
-	 *    // Read the file
-	 *    const content = await file.text();
-	 *
-	 * @example
-	 *    // Using s3:// protocol
-	 *    const file = s3("s3://my-bucket/my-file.txt", {
-	 *      accessKeyId: "your-access-key",
-	 *      secretAccessKey: "your-secret-key"
-	 *    });
-	 */
-	function s3(path: string | URL, options?: S3Options): S3File;
+	var s3: S3Client;
 
 	/**
 	 * Configuration options for S3 operations
@@ -1630,7 +1604,7 @@ declare module "bun" {
 		 *
 		 *     // Write large chunks of data efficiently
 		 *     for (const chunk of largeDataChunks) {
-		 *       await writer.write(chunk);
+		 *       writer.write(chunk);
 		 *     }
 		 *     await writer.end();
 		 *
@@ -1638,7 +1612,7 @@ declare module "bun" {
 		 *     // Error handling
 		 *     const writer = file.writer();
 		 *     try {
-		 *       await writer.write(data);
+		 *       writer.write(data);
 		 *       await writer.end();
 		 *     } catch (err) {
 		 *       console.error('Upload failed:', err);
@@ -2037,6 +2011,339 @@ 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 */
+		username: 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;
+		/** By default values outside i32 range are returned as strings. If this is true, values outside i32 range are returned as BigInts. */
+		bigint: 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> {
+		/** 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 SQLTransactionContextCallback = (
+		sql: TransactionSQL,
+	) => Promise<any> | Array<SQLQuery>;
+	/**
+	 * Callback function type for savepoint contexts
+	 * @param sql Function to execute SQL queries within the savepoint
+	 */
+	type SQLSavepointContextCallback = (
+		sql: SavepointSQL,
+	) => Promise<any> | Array<SQLQuery>;
+
+	/**
+	 * 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 | TemplateStringsArray, ...values: any[]): SQLQuery;
+		/**
+		 * Helper function to allow easy use to insert values into a query
+		 * @example
+		 * const result = await sql`insert into users ${sql(users)} RETURNING *`;
+		 */
+		(obj: 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. If timeout is 0, it will close immediately, if is not provided it will wait for all queries to finish before closing.
+		 * @example
+		 * await sql.close({ timeout: 1 });
+		 */
+		close(options?: { timeout?: number }): Promise<undefined>;
+		/** 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
+		 * @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: SQLTransactionContextCallback): 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: SQLTransactionContextCallback): 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: SQLTransactionContextCallback): 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: SQLTransactionContextCallback,
+		): 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: SQLTransactionContextCallback,
+		): Promise<any>;
+		/** Alternative method to begin a distributed transaction
+		 * @alias beginDistributed
+		 */
+		distributed(name: string, fn: SQLTransactionContextCallback): Promise<any>;
+		/**If you know what you're doing, you can use unsafe to pass any string you'd like.
+		 * Please note that this can lead to SQL injection if you're not careful.
+		 * You can also nest sql.unsafe within a safe sql expression. This is useful if only part of your fraction has unsafe elements.
+		 * @example
+		 * const result = await sql.unsafe(`select ${danger} from users where id = ${dragons}`)
+		 */
+		unsafe(string: string, values?: any[]): SQLQuery;
+
+		/** Current client options */
+		options: SQLOptions;
+
+		[Symbol.asyncDispose](): Promise<any>;
+	}
+
+	/**
+	 * 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;
+		[Symbol.dispose](): 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: SQLSavepointContextCallback): Promise<any>;
+		savepoint(fn: SQLSavepointContextCallback): Promise<any>;
+	}
+	/**
+	 * Represents a savepoint within a transaction
+	 */
+	interface SavepointSQL extends SQL {}
+
+	var sql: SQL;
+	var postgres: SQL;
+	var SQL: SQL;
 
 	/**
 	 *   This lets you use macros as regular imports
@@ -2357,7 +2664,8 @@ declare module "bun" {
 		| "import-rule"
 		| "url-token"
 		| "internal"
-		| "entry-point";
+		| "entry-point-run"
+		| "entry-point-build";
 
 	interface Import {
 		path: string;
@@ -2493,31 +2801,6 @@ declare module "bun" {
 		 */
 		footer?: string;
 
-		/**
-		 * **Experimental**
-		 *
-		 * Bundle CSS files.
-		 *
-		 * This will be enabled by default in Bun v1.2.
-		 *
-		 * @default false (until Bunv 1.2)
-		 */
-		experimentalCss?: boolean;
-
-		/**
-		 * **Experimental**
-		 *
-		 * Bundle JavaScript & CSS files from HTML files. JavaScript & CSS files
-		 * from non-external <script> or <link> tags will be bundled.
-		 *
-		 * Underneath, this works similarly to HTMLRewriter.
-		 *
-		 * This will be enabled by default in Bun v1.2.
-		 *
-		 * @default false (until Bun v1.2)
-		 */
-		html?: boolean;
-
 		/**
 		 * Drop function calls to matching property accesses.
 		 */
@@ -2526,9 +2809,7 @@ declare module "bun" {
 		/**
 		 * When set to `true`, the returned promise rejects with an AggregateError when a build failure happens.
 		 * When set to `false`, the `success` property of the returned object will be `false` when a build failure happens.
-		 *
-		 * This defaults to `false` in Bun 1.1 and will change to `true` in Bun 1.2
-		 * as most usage of `Bun.build` forgets to check for errors.
+		 * This defaults to `true`.
 		 */
 		throw?: boolean;
 	}
@@ -2773,7 +3054,7 @@ declare module "bun" {
    * @param {Object} config - Build configuration options
    * @returns {Promise<BuildOutput>} Promise that resolves to build output containing generated artifacts and build status
    * @throws {AggregateError} When build fails and config.throw is true (default in Bun 1.2+)
-   * 
+   *
    * @example Basic usage - Bundle a single entrypoint and check results
    ```ts
    const result = await Bun.build({
@@ -2786,7 +3067,7 @@ declare module "bun" {
       process.exit(1);
     }
    ```
-    * 
+    *
     * @example Set up multiple entrypoints with code splitting enabled
     ```ts
     await Bun.build({
@@ -2796,7 +3077,7 @@ declare module "bun" {
       sourcemap: "external"
     });
     ```
-    * 
+    *
     * @example Configure minification and optimization settings
     ```ts
     await Bun.build({
@@ -2875,7 +3156,6 @@ declare module "bun" {
     try {
       const result = await Bun.build({
         entrypoints: ['./src/index.tsx'],
-        throw: true
       });
     } catch (e) {
       const error = e as AggregateError;
@@ -2913,7 +3193,6 @@ declare module "bun" {
         './src/themes/light.css'
       ],
       outdir: './dist/css',
-      experimentalCss: true
     });
     ```
     @example Define compile-time constants and version 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.45
+[fetch] > User-Agent: Bun/1.2.0-canary.20250122T140708
 [fetch] > Accept: */*
 [fetch] > Host: example.com
 [fetch] > Accept-Encoding: gzip, deflate, br

package/docs/api/s3.md

@@ -68,7 +68,6 @@ const client = new S3Client({
 });
 
 // Bun.s3 is a global singleton that is equivalent to `new Bun.S3Client()`
-Bun.s3 = client;
 ```
 
 ### Working with S3 Files
@@ -375,7 +374,7 @@ If the `S3_*` environment variable is not set, Bun will also check for the `AWS_
 
 These environment variables are read from [`.env` files](/docs/runtime/env) or from the process environment at initialization time (`process.env` is not used for this).
 
-These defaults are overridden by the options you pass to `s3(credentials)`, `new Bun.S3Client(credentials)`, or any of the methods that accept credentials. So if, for example, you use the same credentials for different buckets, you can set the credentials once in your `.env` file and then pass `bucket: "my-bucket"` to the `s3()` helper function without having to specify all the credentials again.
+These defaults are overridden by the options you pass to `s3.file(credentials)`, `new Bun.S3Client(credentials)`, or any of the methods that accept credentials. So if, for example, you use the same credentials for different buckets, you can set the credentials once in your `.env` file and then pass `bucket: "my-bucket"` to the `s3.file()` function without having to specify all the credentials again.
 
 ### `S3Client` objects
 
@@ -459,7 +458,7 @@ const exists = await client.exists("my-file.txt");
 
 ## `S3File`
 
-`S3File` instances are created by calling the `S3` instance method or the `s3()` helper function. Like `Bun.file()`, `S3File` instances are lazy. They don't refer to something that necessarily exists at the time of creation. That's why all the methods that don't involve network requests are fully synchronous.
+`S3File` instances are created by calling the `S3Client` instance method or the `s3.file()` function. Like `Bun.file()`, `S3File` instances are lazy. They don't refer to something that necessarily exists at the time of creation. That's why all the methods that don't involve network requests are fully synchronous.
 
 ```ts
 interface S3File extends Blob {
@@ -482,7 +481,7 @@ interface S3File extends Blob {
       | Response
       | Request,
     options?: BlobPropertyBag,
-  ): Promise<void>;
+  ): Promise<number>;
 
   exists(options?: S3Options): Promise<boolean>;
   unlink(options?: S3Options): Promise<void>;
@@ -600,7 +599,9 @@ const exists = await S3Client.exists("my-file.txt", credentials);
 The same method also works on `S3File` instances.
 
 ```ts
-const s3file = Bun.s3("my-file.txt", {
+import { s3 } from "bun";
+
+const s3file = s3.file("my-file.txt", {
   ...credentials,
 });
 const exists = await s3file.exists();

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.45"
+console.log(text); // => "1.2.0-canary.20250122T140708"
 ```
 
 Configure the output stream by passing one of the following values to `stdout/stderr`: