bun-types 1.2.3-canary.20250214T140552 → 1.2.3-canary.20250216T140609

package/bun.d.ts

@@ -475,44 +475,181 @@ declare module "bun" {
 		| UnixWebSocketServeOptions<WebSocketDataType>
 		| UnixTLSWebSocketServeOptions<WebSocketDataType>;
 
-	/**
-	 * Start a fast HTTP server.
-	 *
-	 * @param options Server options (port defaults to $PORT || 3000)
-	 *
-	 * -----
-	 *
-	 * @example
-	 *
-	 * ```ts
-	 * Bun.serve({
-	 *   fetch(req: Request): Response | Promise<Response> {
-	 *     return new Response("Hello World!");
-	 *   },
-	 *
-	 *   // Optional port number - the default value is 3000
-	 *   port: process.env.PORT || 3000,
-	 * });
-	 * ```
-	 * -----
-	 *
-	 * @example
-	 *
-	 * Send a file
-	 *
-	 * ```ts
-	 * Bun.serve({
-	 *   fetch(req: Request): Response | Promise<Response> {
-	 *     return new Response(Bun.file("./package.json"));
-	 *   },
-	 *
-	 *   // Optional port number - the default value is 3000
-	 *   port: process.env.PORT || 3000,
-	 * });
-	 * ```
-	 */
-	// eslint-disable-next-line @definitelytyped/no-unnecessary-generics
-	function serve<T>(options: Serve<T>): Server;
+	/** 
+    Bun.serve provides a high-performance HTTP server with built-in routing support.
+    It enables both function-based and object-based route handlers with type-safe 
+    parameters and method-specific handling.
+
+    @example Basic Usage
+    ```ts
+    Bun.serve({
+      port: 3000,
+      fetch(req) {
+        return new Response("Hello World");
+      }
+    });
+    ```
+
+    @example Route-based Handlers
+    ```ts
+    Bun.serve({
+      routes: {
+        // Static responses
+        "/": new Response("Home page"),
+        
+        // Function handlers with type-safe parameters
+        "/users/:id": (req) => {
+          // req.params.id is typed as string
+          return new Response(`User ${req.params.id}`);
+        },
+        
+        // Method-specific handlers
+        "/api/posts": {
+          GET: () => new Response("Get posts"),
+          POST: async (req) => {
+            const body = await req.json();
+            return new Response("Created post");
+          },
+          DELETE: (req) => new Response("Deleted post")
+        },
+        
+        // Wildcard routes
+        "/static/*": (req) => {
+          // Handle any path under /static/
+          return new Response("Static file");
+        },
+        
+        // Disable route (fall through to fetch handler)
+        "/api/legacy": false
+      },
+      
+      // Fallback handler for unmatched routes
+      fetch(req) {
+        return new Response("Not Found", { status: 404 });
+      }
+    });
+    ```
+
+    @example Path Parameters
+    ```ts
+    Bun.serve({
+      routes: {
+        // Single parameter
+        "/users/:id": (req: BunRequest<"/users/:id">) => {
+          return new Response(`User ID: ${req.params.id}`);
+        },
+        
+        // Multiple parameters
+        "/posts/:postId/comments/:commentId": (
+          req: BunRequest<"/posts/:postId/comments/:commentId">
+        ) => {
+          return new Response(JSON.stringify(req.params));
+          // Output: {"postId": "123", "commentId": "456"}
+        }
+      }
+    });
+    ```
+
+    @example Route Precedence
+    ```ts
+    // Routes are matched in the following order:
+    // 1. Exact static routes ("/about")
+    // 2. Parameter routes ("/users/:id") 
+    // 3. Wildcard routes ("/api/*")
+
+    Bun.serve({
+      routes: {
+        "/api/users": () => new Response("Users list"),
+        "/api/users/:id": (req) => new Response(`User ${req.params.id}`),
+        "/api/*": () => new Response("API catchall"),
+        "/*": () => new Response("Root catchall")
+      }
+    });
+    ```
+
+    @example Error Handling
+    ```ts
+    Bun.serve({
+      routes: {
+        "/error": () => {
+          throw new Error("Something went wrong");
+        }
+      },
+      error(error) {
+        // Custom error handler
+        console.error(error);
+        return new Response(`Error: ${error.message}`, { 
+          status: 500 
+        });
+      }
+    });
+    ```
+
+    @example Server Lifecycle
+    ```ts
+    const server = Bun.serve({
+      // Server config...
+    });
+
+    // Update routes at runtime
+    server.reload({
+      routes: {
+        "/": () => new Response("Updated route")
+      }
+    });
+
+    // Stop the server
+    server.stop();
+    ```
+
+    @example Development Mode
+    ```ts
+    Bun.serve({
+      development: true, // Enable hot reloading
+      routes: {
+        // Routes will auto-reload on changes
+      }
+    });
+    ```
+
+    @example Type-Safe Request Handling
+    ```ts
+    type Post = {
+      id: string;
+      title: string;
+    };
+
+    Bun.serve({
+      routes: {
+        "/api/posts/:id": async (
+          req: BunRequest<"/api/posts/:id">
+        ) => {
+          if (req.method === "POST") {
+            const body: Post = await req.json();
+            return Response.json(body);
+          }
+          return new Response("Method not allowed", { 
+            status: 405 
+          });
+        }
+      }
+    });
+    ```
+    @param options - Server configuration options
+    @param options.routes - Route definitions mapping paths to handlers
+    */
+	function serve<
+		T,
+		R extends { [K in keyof R]: RouterTypes.RouteValue<K & string> },
+	>(
+		options: Serve<T> & {
+			routes?: R;
+			/**
+			 * @deprecated Use {@link routes} instead in new code
+			 */
+			static?: R;
+		},
+	): Server;
 
 	/**
 	 * Synchronously resolve a `moduleId` as though it were imported from `parent`
@@ -3805,6 +3942,45 @@ declare module "bun" {
 			  };
 	}
 
+	namespace RouterTypes {
+		type ExtractRouteParams<T> =
+			T extends `${string}:${infer Param}/${infer Rest}`
+				? { [K in Param]: string } & ExtractRouteParams<Rest>
+				: T extends `${string}:${infer Param}`
+					? { [K in Param]: string }
+					: T extends `${string}*`
+						? {}
+						: {};
+
+		type RouteHandler<T extends string> = (
+			req: BunRequest<T>,
+			server: Server,
+		) => Response | Promise<Response>;
+
+		type HTTPMethod =
+			| "GET"
+			| "POST"
+			| "PUT"
+			| "DELETE"
+			| "PATCH"
+			| "HEAD"
+			| "OPTIONS";
+
+		type RouteHandlerObject<T extends string> = {
+			[K in HTTPMethod]?: RouteHandler<T>;
+		};
+
+		type RouteValue<T extends string> =
+			| Response
+			| false
+			| RouteHandler<T>
+			| RouteHandlerObject<T>;
+	}
+
+	interface BunRequest<T extends string = string> extends Request {
+		params: RouterTypes.ExtractRouteParams<T>;
+	}
+
 	interface GenericServeOptions {
 		/**
 		 * What URI should be used to make {@link Request.url} absolute?
@@ -3869,26 +4045,6 @@ declare module "bun" {
 		 * This string will currently do nothing. But in the future it could be useful for logs or metrics.
 		 */
 		id?: string | null;
-
-		/**
-		 * Server static Response objects by route.
-		 *
-		 * @example
-		 * ```ts
-		 * Bun.serve({
-		 *   static: {
-		 *     "/": new Response("Hello World"),
-		 *     "/about": new Response("About"),
-		 *   },
-		 *   fetch(req) {
-		 *     return new Response("Fallback response");
-		 *   },
-		 * });
-		 * ```
-		 *
-		 * @experimental
-		 */
-		static?: Record<`/${string}`, Response>;
 	}
 
 	interface ServeOptions extends GenericServeOptions {

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.3-canary.20250214T140552
+[fetch] > User-Agent: Bun/1.2.3-canary.20250216T140609
 [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); // => "1.2.3-canary.20250214T140552"
+console.log(text); // => "1.2.3-canary.20250216T140609"
 ```
 
 Configure the output stream by passing one of the following values to `stdout/stderr`:

package/docs/api/sql.md

@@ -165,6 +165,24 @@ await sql`
 `;
 ```
 
+## `sql``.simple()`
+
+The PostgreSQL wire protocol supports two types of queries: "simple" and "extended". Simple queries can contain multiple statements but don't support parameters, while extended queries (the default) support parameters but only allow one statement.
+
+To run multiple statements in a single query, use `sql``.simple()`:
+
+```ts
+// Multiple statements in one query
+await sql`
+  SELECT 1;
+  SELECT 2;
+`.simple();
+```
+
+Simple queries are often useful for database migrations and setup scripts.
+
+Note that simple queries cannot use parameters (`${value}`). If you need parameters, you must split your query into separate statements.
+
 ### Unsafe Queries
 
 You can use the `sql.unsafe` function to execute raw SQL strings. Use this with caution, as it will not escape user input.
@@ -431,6 +449,33 @@ try {
 } // Automatically released
 ```
 
+## Prepared Statements
+
+By default, Bun's SQL client automatically creates prepared statements for queries where it can be inferred that the query is static. This provides better performance and security. However, you can disable prepared statements by setting `prepare: false` in the connection options:
+
+```ts
+const sql = new SQL({
+  // ... other options ...
+  prepare: false, // Disable prepared statements
+});
+```
+
+When prepared statements are disabled:
+
+- Queries are executed using simple query protocol
+- Each query is sent to the server as a raw SQL string
+- Multiple statements can be executed in a single query (using `sql``.simple()`)
+- Parameter binding is still safe against SQL injection, but simple queries cannot include parameters
+- Each query is parsed and planned from scratch by the server
+
+You might want to disable prepared statements when:
+
+- Using PGBouncer in transaction mode (though since PGBouncer 1.21.0, protocol-level named prepared statements are supported when configured properly)
+- Debugging query execution plans
+- Working with dynamic SQL where query plans need to be regenerated frequently
+
+Note that disabling prepared statements may impact performance for queries that are executed frequently with different parameters, as the server needs to parse and plan each query from scratch.
+
 ## Error Handling
 
 The client provides typed errors for different failure scenarios:
@@ -501,7 +546,7 @@ The client provides typed errors for different failure scenarios:
 
 ## Numbers and BigInt
 
-Bun's SQL client includes special handling for large numbers that exceed the range of a 53-bit integer. Here’s how it works:
+Bun's SQL client includes special handling for large numbers that exceed the range of a 53-bit integer. Here's how it works:
 
 ```ts
 import { sql } from "bun";

package/docs/bundler/fullstack.md

@@ -1,33 +1,39 @@
-Using `Bun.serve()`'s `static` option, you can run your frontend and backend in the same app with no extra steps.
+Using `Bun.serve()`'s `routes` option, you can run your frontend and backend in the same app with no extra steps.
 
-To get started, import HTML files and pass them to the `static` option in `Bun.serve()`.
+To get started, import HTML files and pass them to the `routes` option in `Bun.serve()`.
 
 ```ts
 import dashboard from "./dashboard.html";
 import homepage from "./index.html";
 
 const server = Bun.serve({
-  // Add HTML imports to `static`
-  static: {
+  // Add HTML imports to `routes` (before Bun v1.2.3, this was called `static`)
+  routes: {
     // Bundle & route index.html to "/"
     "/": homepage,
     // Bundle & route dashboard.html to "/dashboard"
     "/dashboard": dashboard,
+
+    // API endpoints:
+    "/api/users": async req => {
+      const users = await Bun.sql`SELECT * FROM users`;
+      return Response.json(users);
+    },
+
+    "/api/users/:id": async req => {
+      const { id } = req.params;
+      const [user] = await Bun.sql`SELECT * FROM users WHERE id = ${id}`;
+      return Response.json(user);
+    },
   },
 
   // Enable development mode for:
   // - Detailed error messages
-  // - Rebuild on request
+  // - Hot reloading (Bun v1.2.3+ required)
   development: true,
 
   // Handle API requests
   async fetch(req) {
-    // ...your API code
-    if (req.url.endsWith("/api/users")) {
-      const users = await Bun.sql`SELECT * FROM users`;
-      return Response.json(users);
-    }
-
     // Return 404 for unmatched routes
     return new Response("Not Found", { status: 404 });
   },
@@ -55,7 +61,7 @@ These HTML files are used as routes in Bun's dev server you can pass to `Bun.ser
 
 ```ts
 Bun.serve({
-  static: {
+  routes: {
     "/": homepage,
     "/dashboard": dashboard,
   }
@@ -113,7 +119,7 @@ import dashboard from "../public/dashboard.html";
 import { serve } from "bun";
 
 serve({
-  static: {
+  routes: {
     "/": dashboard,
   },
 
@@ -171,7 +177,7 @@ import homepage from "./index.html";
 import dashboard from "./dashboard.html";
 
 Bun.serve({
-  static: {
+  routes: {
     "/": homepage,
     "/dashboard": dashboard,
   }
@@ -249,6 +255,8 @@ plugins = ["./my-plugin-implementation.ts"]
 
 Bun will lazily resolve and load each plugin and use them to bundle your routes.
 
+Note: this is currently in `bunfig.toml` to make it possible to know statically which plugins are in use when we eventually integrate this with the `bun build` CLI. These plugins work in `Bun.build()`'s JS API, but are not yet supported in the CLI.
+
 ## How this works
 
 Bun uses [`HTMLRewriter`](/docs/api/html-rewriter) to scan for `<script>` and `<link>` tags in HTML files, uses them as entrypoints for [Bun's bundler](/docs/bundler), generates an optimized bundle for the JavaScript/TypeScript/TSX/JSX and CSS files, and serves the result.
@@ -293,5 +301,5 @@ This works similarly to how [`Bun.build` processes HTML files](/docs/bundler/htm
 
 ## This is a work in progress
 
-- Client-side hot reloading isn't wired up yet. It will be in the future.
+- ~Client-side hot reloading isn't wired up yet. It will be in the future.~ New in Bun v1.2.3
 - This doesn't support `bun build` yet. It also will in the future.

package/docs/bundler/html.md

@@ -301,6 +301,6 @@ This is a small wrapper around Bun's support for HTML imports in JavaScript.
 
 ### Adding a backend to your frontend
 
-To add a backend to your frontend, you can use the `"static"` option in `Bun.serve`.
+To add a backend to your frontend, you can use the `"routes"` option in `Bun.serve`.
 
 Learn more in [the full-stack docs](/docs/bundler/fullstack).

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.3-canary.20250214T140552 (ca7428e9)
+bun publish v1.2.3-canary.20250216T140609 (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.3-canary.20250214T140552 (16b4bf34)
+bun install v1.2.3-canary.20250216T140609 (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.3-canary.20250214T140552"
++   "@types/bun": "^1.2.3-canary.20250216T140609"
   }
 }
 ```
@@ -28,7 +28,7 @@ Running `bun install` will install peer dependencies by default, unless marked o
 ```json-diff
 {
   "peerDependencies": {
-    "@types/bun": "^1.2.3-canary.20250214T140552"
+    "@types/bun": "^1.2.3-canary.20250216T140609"
   },
   "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.3-canary.20250214T140552
+$ bun update @types/bun@1.2.3-canary.20250216T140609
 
 # 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.3-canary.20250214T140552 (9c68abdb)
+bun test v1.2.3-canary.20250216T140609 (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.3-canary.20250214T140552 (9c68abdb)
+bun test v1.2.3-canary.20250216T140609 (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.3-canary.20250214T140552 (9c68abdb)
+bun test v1.2.3-canary.20250216T140609 (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.3-canary.20250214T140552 (9c68abdb)
+bun test v1.2.3-canary.20250216T140609 (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.3-canary.20250214T140552 (9c68abdb)
+bun test v1.2.3-canary.20250216T140609 (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.3-canary.20250214T140552 (9c68abdb)
+bun test v1.2.3-canary.20250216T140609 (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.3-canary.20250214T140552 (9c68abdb)
+bun test v1.2.3-canary.20250216T140609 (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.3-canary.20250214T140552"
+Bun.version; // => "1.2.3-canary.20250216T140609"
 ```
 
 ---

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.3-canary.20250214T140552"
+$ curl -fsSL https://bun.sh/install | bash -s "bun-v1.2.3-canary.20250216T140609"
 ```
 
 ```bash#npm
@@ -188,10 +188,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.3-canary.20250214T140552`.
+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.3-canary.20250216T140609`.
 
 ```sh
-$ curl -fsSL https://bun.sh/install | bash -s "bun-v1.2.3-canary.20250214T140552"
+$ curl -fsSL https://bun.sh/install | bash -s "bun-v1.2.3-canary.20250216T140609"
 ```
 
 ### Installing a specific version of Bun on Windows
@@ -200,7 +200,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.3-canary.20250214T140552"
+$ iex "& {$(irm https://bun.sh/install.ps1)} -Version 1.2.3-canary.20250216T140609"
 ```
 
 ## 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.3-canary.20250214T140552" -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.3-canary.20250216T140609" -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.3-canary.20250214T140552
+[fetch] > User-Agent: Bun/1.2.3-canary.20250216T140609
 [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.3-canary.20250214T140552
+[fetch] > User-Agent: Bun/1.2.3-canary.20250216T140609
 [fetch] > Accept: */*
 [fetch] > Host: example.com
 [fetch] > Accept-Encoding: gzip, deflate, br

package/docs/test/dom.md

@@ -55,7 +55,7 @@ Let's run this test with `bun test`:
 
 ```bash
 $ bun test
-bun test v1.2.3-canary.20250214T140552
+bun test v1.2.3-canary.20250216T140609
 
 dom.test.ts:
 ✓ dom test [0.82ms]

package/package.json

@@ -1,5 +1,5 @@
 {
-	"version": "1.2.3-canary.20250214T140552",
+	"version": "1.2.3-canary.20250216T140609",
 	"name": "bun-types",
 	"license": "MIT",
 	"main": "",