bun-types 1.2.3-canary.20250215T140625 → 1.2.3-canary.20250217T140554

package/bun.d.ts

@@ -465,55 +465,6 @@ declare module "bun" {
 	}
 	const TOML: TOML;
 
-	type Serve<WebSocketDataType = undefined> =
-		| ServeOptions
-		| TLSServeOptions
-		| UnixServeOptions
-		| UnixTLSServeOptions
-		| WebSocketServeOptions<WebSocketDataType>
-		| TLSWebSocketServeOptions<WebSocketDataType>
-		| 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;
-
 	/**
 	 * Synchronously resolve a `moduleId` as though it were imported from `parent`
 	 *
@@ -3805,6 +3756,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,37 +3859,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
-			/**
-			 * An HTML import.
-			 */
-			| HTMLBundle
-			/**
-			 * false to force fetch() to handle the route
-			 */
-			| false
-		>;
 	}
 
 	interface ServeOptions extends GenericServeOptions {
@@ -4305,7 +4264,32 @@ declare module "bun" {
 		 *
 		 * Passing other options such as `port` or `hostname` won't do anything.
 		 */
-		reload(options: Serve): void;
+		reload<T, R extends { [K in keyof R]: RouterTypes.RouteValue<K & string> }>(
+			options: (
+				| (Omit<ServeOptions, "fetch"> & {
+						routes: R;
+						fetch?: (
+							this: Server,
+							request: Request,
+							server: Server,
+						) => Response | Promise<Response>;
+				  })
+				| (Omit<ServeOptions, "routes"> & {
+						routes?: never;
+						fetch: (
+							this: Server,
+							request: Request,
+							server: Server,
+						) => Response | Promise<Response>;
+				  })
+				| WebSocketServeOptions<T>
+			) & {
+				/**
+				 * @deprecated Use `routes` instead in new code. This will continue to work for awhile though.
+				 */
+				static?: R;
+			},
+		): Server;
 
 		/**
 		 * Mock the fetch handler for a running server.
@@ -4503,6 +4487,209 @@ declare module "bun" {
 		readonly id: string;
 	}
 
+	type Serve<WebSocketDataType = undefined> =
+		| ServeOptions
+		| TLSServeOptions
+		| UnixServeOptions
+		| UnixTLSServeOptions
+		| WebSocketServeOptions<WebSocketDataType>
+		| TLSWebSocketServeOptions<WebSocketDataType>
+		| UnixWebSocketServeOptions<WebSocketDataType>
+		| UnixTLSWebSocketServeOptions<WebSocketDataType>;
+
+	/** 
+    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: (
+			| (Omit<ServeOptions, "fetch"> & {
+					routes: R;
+					fetch?: (
+						this: Server,
+						request: Request,
+						server: Server,
+					) => Response | Promise<Response>;
+			  })
+			| (Omit<ServeOptions, "routes"> & {
+					routes?: never;
+					fetch: (
+						this: Server,
+						request: Request,
+						server: Server,
+					) => Response | Promise<Response>;
+			  })
+			| WebSocketServeOptions<T>
+		) & {
+			/**
+			 * @deprecated Use `routes` instead in new code. This will continue to work for awhile though.
+			 */
+			static?: R;
+		},
+	): Server;
+
 	/**
 	 * [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob) powered by the fastest system calls available for operating on files.
 	 *

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.20250215T140625
+[fetch] > User-Agent: Bun/1.2.3-canary.20250217T140554
 [fetch] > Accept: */*
 [fetch] > Host: example.com
 [fetch] > Accept-Encoding: gzip, deflate, br

package/docs/api/http.md

@@ -8,130 +8,158 @@ To start a high-performance HTTP server with a clean API, the recommended approa
 
 ## `Bun.serve()`
 
-Start an HTTP server in Bun with `Bun.serve`.
+Use `Bun.serve` to start an HTTP server in Bun.
 
 ```ts
 Bun.serve({
-  fetch(req) {
-    return new Response("Bun!");
-  },
-});
-```
+  // `routes` requires Bun v1.2.3+
+  routes: {
+    // Static routes
+    "/api/status": new Response("OK"),
+
+    // Dynamic routes
+    "/users/:id": req => {
+      return new Response(`Hello User ${req.params.id}!`);
+    },
 
-### `fetch` request handler
+    // Per-HTTP method handlers
+    "/api/posts": {
+      GET: () => new Response("List posts"),
+      POST: async req => {
+        const body = await req.json();
+        return Response.json({ created: true, ...body });
+      },
+    },
 
-The `fetch` handler handles incoming requests. It receives a [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request) object and returns a [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response) or `Promise<Response>`.
+    // Wildcard route for all routes that start with "/api/" and aren't otherwise matched
+    "/api/*": Response.json({ message: "Not found" }, { status: 404 }),
 
-```ts
-Bun.serve({
+    // Redirect from /blog/hello to /blog/hello/world
+    "/blog/hello": Response.redirect("/blog/hello/world"),
+
+    // Serve a file by buffering it in memory
+    "/favicon.ico": new Response(await Bun.file("./favicon.ico").bytes(), {
+      headers: {
+        "Content-Type": "image/x-icon",
+      },
+    }),
+  },
+
+  // (optional) fallback for unmatched routes:
+  // Required if Bun's version < 1.2.3
   fetch(req) {
-    const url = new URL(req.url);
-    if (url.pathname === "/") return new Response("Home page!");
-    if (url.pathname === "/blog") return new Response("Blog!");
-    return new Response("404!");
+    return new Response("Not Found", { status: 404 });
   },
 });
 ```
 
-The `fetch` handler supports async/await:
+### Routing
+
+Routes in `Bun.serve()` receive a `BunRequest` (which extends [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request)) and return a [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response) or `Promise<Response>`. This makes it easier to use the same code for both sending & receiving HTTP requests.
 
 ```ts
-import { sleep, serve } from "bun";
-serve({
-  async fetch(req) {
-    const start = performance.now();
-    await sleep(10);
-    const end = performance.now();
-    return new Response(`Slept for ${end - start}ms`);
-  },
-});
+// Simplified for brevity
+interface BunRequest<T extends string> extends Request {
+  params: Record<T, string>;
+}
 ```
 
-Promise-based responses are also supported:
+#### Async/await in routes
+
+You can use async/await in route handlers to return a `Promise<Response>`.
 
 ```ts
-Bun.serve({
-  fetch(req) {
-    // Forward the request to another server.
-    return fetch("https://example.com");
+import { sql, serve } from "bun";
+
+serve({
+  port: 3001,
+  routes: {
+    "/api/version": async () => {
+      const [version] = await sql`SELECT version()`;
+      return Response.json(version);
+    },
   },
 });
 ```
 
-You can also access the `Server` object from the `fetch` handler. It's the second argument passed to the `fetch` function.
+#### Promise in routes
+
+You can also return a `Promise<Response>` from a route handler.
 
 ```ts
-// `server` is passed in as the second argument to `fetch`.
-const server = Bun.serve({
-  fetch(req, server) {
-    const ip = server.requestIP(req);
-    return new Response(`Your IP is ${ip}`);
+import { sql, serve } from "bun";
+
+serve({
+  routes: {
+    "/api/version": () => {
+      return new Promise(resolve => {
+        setTimeout(async () => {
+          const [version] = await sql`SELECT version()`;
+          resolve(Response.json(version));
+        }, 100);
+      });
+    },
   },
 });
 ```
 
-### Static routes
+#### Type-safe route parameters
 
-Use the `static` option to serve static `Response` objects by route.
+TypeScript parses route parameters when passed as a string literal, so that your editor will show autocomplete when accessing `request.params`.
 
 ```ts
-// Bun v1.1.27+ required
-Bun.serve({
-  static: {
-    // health-check endpoint
-    "/api/health-check": new Response("All good!"),
+import type { BunRequest } from "bun";
 
-    // redirect from /old-link to /new-link
-    "/old-link": Response.redirect("/new-link", 301),
-
-    // serve static text
-    "/": new Response("Hello World"),
-
-    // serve a file by buffering it in memory
-    "/index.html": new Response(await Bun.file("./index.html").bytes(), {
-      headers: {
-        "Content-Type": "text/html",
-      },
-    }),
-    "/favicon.ico": new Response(await Bun.file("./favicon.ico").bytes(), {
-      headers: {
-        "Content-Type": "image/x-icon",
-      },
-    }),
-
-    // serve JSON
-    "/api/version.json": Response.json({ version: "1.0.0" }),
-  },
+Bun.serve({
+  routes: {
+    // TypeScript knows the shape of params when passed as a string literal
+    "/orgs/:orgId/repos/:repoId": req => {
+      const { orgId, repoId } = req.params;
+      return Response.json({ orgId, repoId });
+    },
 
-  fetch(req) {
-    return new Response("404!");
+    "/orgs/:orgId/repos/:repoId/settings": (
+      // optional: you can explicitly pass a type to BunRequest:
+      req: BunRequest<"/orgs/:orgId/repos/:repoId/settings">,
+    ) => {
+      const { orgId, repoId } = req.params;
+      return Response.json({ orgId, repoId });
+    },
   },
 });
 ```
 
-Static routes support headers, status code, and other `Response` options.
+Percent-encoded route parameter values are automatically decoded. Unicode characters are supported. Invalid unicode is replaced with the unicode replacement character `&0xFFFD;`.
+
+### Static responses
+
+Routes can also be `Response` objects (without the handler function). Bun.serve() optimizes it for zero-allocation dispatch - perfect for health checks, redirects, and fixed content:
 
 ```ts
 Bun.serve({
-  static: {
-    "/api/time": new Response(new Date().toISOString(), {
+  routes: {
+    // Health checks
+    "/health": new Response("OK"),
+    "/ready": new Response("Ready", {
       headers: {
-        "X-Custom-Header": "Bun!",
+        // Pass custom headers
+        "X-Ready": "1",
       },
     }),
-  },
 
-  fetch(req) {
-    return new Response("404!");
+    // Redirects
+    "/blog": Response.redirect("https://bun.sh/blog"),
+
+    // API responses
+    "/api/config": Response.json({
+      version: "1.0.0",
+      env: "production",
+    }),
   },
 });
 ```
 
-Static routes can serve Response bodies faster than `fetch` handlers because they don't create `Request` objects, they don't create `AbortSignal`, they don't create additional `Response` objects. The only per-request memory allocation is the TCP/TLS socket data needed for each request.
-
-{% note %}
-`static` is experimental
-{% /note %}
+Static responses do not allocate additional memory after initialization. You can generally expect at least a 15% performance improvement over manually returning a `Response` object.
 
 Static route responses are cached for the lifetime of the server object. To reload static routes, call `server.reload(options)`.
 
@@ -160,7 +188,7 @@ setInterval(() => {
 }, 1000);
 ```
 
-Reloading static routes only impact the next request. In-flight requests continue to use the old static routes. After in-flight requests to old static routes are finished, the old static routes are freed from memory.
+Reloading routes only impact the next request. In-flight requests continue to use the old routes. After in-flight requests to old routes are finished, the old routes are freed from memory.
 
 To simplify error handling, static routes do not support streaming response bodies from `ReadableStream` or an `AsyncIterator`. Fortunately, you can still buffer the response in memory first:
 
@@ -180,6 +208,270 @@ const server = Bun.serve({
 });
 ```
 
+### Route precedence
+
+Routes are matched in order of specificity:
+
+1. Exact routes (`/users/all`)
+2. Parameter routes (`/users/:id`)
+3. Wildcard routes (`/users/*`)
+4. Global catch-all (`/*`)
+
+```ts
+Bun.serve({
+  routes: {
+    // Most specific first
+    "/api/users/me": () => new Response("Current user"),
+    "/api/users/:id": req => new Response(`User ${req.params.id}`),
+    "/api/*": () => new Response("API catch-all"),
+    "/*": () => new Response("Global catch-all"),
+  },
+});
+```
+
+### Per-HTTP Method Routes
+
+Route handlers can be specialized by HTTP method:
+
+```ts
+Bun.serve({
+  routes: {
+    "/api/posts": {
+      // Different handlers per method
+      GET: () => new Response("List posts"),
+      POST: async req => {
+        const post = await req.json();
+        return Response.json({ id: crypto.randomUUID(), ...post });
+      },
+      PUT: async req => {
+        const updates = await req.json();
+        return Response.json({ updated: true, ...updates });
+      },
+      DELETE: () => new Response(null, { status: 204 }),
+    },
+  },
+});
+```
+
+You can pass any of the following methods:
+
+| Method    | Usecase example                 |
+| --------- | ------------------------------- |
+| `GET`     | Fetch a resource                |
+| `HEAD`    | Check if a resource exists      |
+| `OPTIONS` | Get allowed HTTP methods (CORS) |
+| `DELETE`  | Delete a resource               |
+| `PATCH`   | Update a resource               |
+| `POST`    | Create a resource               |
+| `PUT`     | Update a resource               |
+
+When passing a function instead of an object, all methods will be handled by that function:
+
+```ts
+const server = Bun.serve({
+  routes: {
+    "/api/version": () => Response.json({ version: "1.0.0" }),
+  },
+});
+
+await fetch(new URL("/api/version", server.url));
+await fetch(new URL("/api/version", server.url), { method: "PUT" });
+// ... etc
+```
+
+### Hot Route Reloading
+
+Update routes without server restarts using `server.reload()`:
+
+```ts
+const server = Bun.serve({
+  routes: {
+    "/api/version": () => Response.json({ version: "1.0.0" }),
+  },
+});
+
+// Deploy new routes without downtime
+server.reload({
+  routes: {
+    "/api/version": () => Response.json({ version: "2.0.0" }),
+  },
+});
+```
+
+### Error Handling
+
+Bun provides structured error handling for routes:
+
+```ts
+Bun.serve({
+  routes: {
+    // Errors are caught automatically
+    "/api/risky": () => {
+      throw new Error("Something went wrong");
+    },
+  },
+  // Global error handler
+  error(error) {
+    console.error(error);
+    return new Response(`Internal Error: ${error.message}`, {
+      status: 500,
+      headers: {
+        "Content-Type": "text/plain",
+      },
+    });
+  },
+});
+```
+
+### HTML imports
+
+To add a client-side single-page app, you can use an HTML import:
+
+```ts
+import myReactSinglePageApp from "./index.html";
+
+Bun.serve({
+  routes: {
+    "/": myReactSinglePageApp,
+  },
+});
+```
+
+HTML imports don't just serve HTML. It's a full-featured frontend bundler, transpiler, and toolkit built using Bun's [bundler](https://bun.sh/docs/bundler), JavaScript transpiler and CSS parser.
+
+You can use this to build a full-featured frontend with React, TypeScript, Tailwind CSS, and more. Check out [/docs/bundler/fullstack](https://bun.sh/docs/bundler/fullstack) to learn more.
+
+### Practical example: REST API
+
+Here's a basic database-backed REST API using Bun's router with zero dependencies:
+
+{% codetabs %}
+
+```ts#server.ts
+import type { Post } from "./types.ts";
+import { Database } from "bun:sqlite";
+
+const db = new Database("posts.db");
+db.exec(`
+  CREATE TABLE IF NOT EXISTS posts (
+    id TEXT PRIMARY KEY,
+    title TEXT NOT NULL,
+    content TEXT NOT NULL,
+    created_at TEXT NOT NULL
+  )
+`);
+
+Bun.serve({
+  routes: {
+    // List posts
+    "/api/posts": {
+      GET: () => {
+        const posts = db.query("SELECT * FROM posts").all();
+        return Response.json(posts);
+      },
+
+      // Create post
+      POST: async req => {
+        const post: Omit<Post, "id" | "created_at"> = await req.json();
+        const id = crypto.randomUUID();
+
+        db.query(
+          `INSERT INTO posts (id, title, content, created_at)
+           VALUES (?, ?, ?, ?)`,
+        ).run(id, post.title, post.content, new Date().toISOString());
+
+        return Response.json({ id, ...post }, { status: 201 });
+      },
+    },
+
+    // Get post by ID
+    "/api/posts/:id": req => {
+      const post = db
+        .query("SELECT * FROM posts WHERE id = ?")
+        .get(req.params.id);
+
+      if (!post) {
+        return new Response("Not Found", { status: 404 });
+      }
+
+      return Response.json(post);
+    },
+  },
+
+  error(error) {
+    console.error(error);
+    return new Response("Internal Server Error", { status: 500 });
+  },
+});
+```
+
+```ts#types.ts
+export interface Post {
+  id: string;
+  title: string;
+  content: string;
+  created_at: string;
+}
+```
+
+{% /codetabs %}
+
+### Routing performance
+
+`Bun.serve()`'s router builds on top uWebSocket's [tree-based approach](https://github.com/oven-sh/bun/blob/0d1a00fa0f7830f8ecd99c027fce8096c9d459b6/packages/bun-uws/src/HttpRouter.h#L57-L64) to add [SIMD-accelerated route parameter decoding](https://github.com/oven-sh/bun/blob/jarred/optional-fetch/src/bun.js/bindings/decodeURIComponentSIMD.cpp#L21-L271) and [JavaScriptCore structure caching](https://github.com/oven-sh/bun/blob/jarred/optional-fetch/src/bun.js/bindings/ServerRouteList.cpp#L100-L101) to push the performance limits of what modern hardware allows.
+
+### `fetch` request handler
+
+The `fetch` handler handles incoming requests that weren't matched by any route. It receives a [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request) object and returns a [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response) or [`Promise<Response>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise).
+
+```ts
+Bun.serve({
+  fetch(req) {
+    const url = new URL(req.url);
+    if (url.pathname === "/") return new Response("Home page!");
+    if (url.pathname === "/blog") return new Response("Blog!");
+    return new Response("404!");
+  },
+});
+```
+
+The `fetch` handler supports async/await:
+
+```ts
+import { sleep, serve } from "bun";
+serve({
+  async fetch(req) {
+    const start = performance.now();
+    await sleep(10);
+    const end = performance.now();
+    return new Response(`Slept for ${end - start}ms`);
+  },
+});
+```
+
+Promise-based responses are also supported:
+
+```ts
+Bun.serve({
+  fetch(req) {
+    // Forward the request to another server.
+    return fetch("https://example.com");
+  },
+});
+```
+
+You can also access the `Server` object from the `fetch` handler. It's the second argument passed to the `fetch` function.
+
+```ts
+// `server` is passed in as the second argument to `fetch`.
+const server = Bun.serve({
+  fetch(req, server) {
+    const ip = server.requestIP(req);
+    return new Response(`Your IP is ${ip}`);
+  },
+});
+```
+
 ### Changing the `port` and `hostname`
 
 To configure which port and hostname the server will listen on, set `port` and `hostname` in the options object.
@@ -553,7 +845,7 @@ Update the server's handlers without restarting:
 
 ```ts
 const server = Bun.serve({
-  static: {
+  routes: {
     "/api/version": Response.json({ version: "v1" }),
   },
   fetch(req) {
@@ -563,7 +855,7 @@ const server = Bun.serve({
 
 // Update to new handler
 server.reload({
-  static: {
+  routes: {
     "/api/version": Response.json({ version: "v2" }),
   },
   fetch(req) {
@@ -572,7 +864,7 @@ server.reload({
 });
 ```
 
-This is useful for development and hot reloading. Only `fetch`, `error`, and `static` handlers can be updated.
+This is useful for development and hot reloading. Only `fetch`, `error`, and `routes` can be updated.
 
 ## Per-Request Controls
 

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.20250215T140625"
+console.log(text); // => "1.2.3-canary.20250217T140554"
 ```
 
 Configure the output stream by passing one of the following values to `stdout/stderr`:

package/docs/api/sql.md

@@ -165,13 +165,39 @@ 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.
+You can use the `sql.unsafe` function to execute raw SQL strings. Use this with caution, as it will not escape user input. Executing more than one command per query is allowed if no parameters are used.
 
 ```ts
+// Multiple commands without parameters
+const result = await sql.unsafe(`
+  SELECT ${userColumns} FROM users;
+  SELECT ${accountColumns} FROM accounts;
+`);
+
+// Using parameters (only one command is allowed)
 const result = await sql.unsafe(
-  "SELECT " + columns + " FROM users WHERE id = " + id,
+  "SELECT " + dangerous + " FROM users WHERE id = $1",
+  [id],
 );
 ```
 
@@ -431,6 +457,34 @@ try {
 } // Automatically released
 ```
 
+## Prepared Statements
+
+By default, Bun's SQL client automatically creates named prepared statements for queries where it can be inferred that the query is static. This provides better performance. However, you can change this behavior by setting `prepare: false` in the connection options:
+
+```ts
+const sql = new SQL({
+  // ... other options ...
+  prepare: false, // Disable persisting named prepared statements on the server
+});
+```
+
+When `prepare: false` is set:
+
+Queries are still executed using the "extended" protocol, but they are executed using [unnamed prepared statements](https://www.postgresql.org/docs/current/protocol-flow.html#PROTOCOL-FLOW-EXT-QUERY), an unnamed prepared statement lasts only until the next Parse statement specifying the unnamed statement as destination is issued.
+
+- Parameter binding is still safe against SQL injection
+- Each query is parsed and planned from scratch by the server
+- Queries will not be [pipelined](https://www.postgresql.org/docs/current/protocol-flow.html#PROTOCOL-FLOW-PIPELINING)
+
+You might want to use `prepare: false` 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
+- More than one command per query will not be supported (unless you use `sql``.simple()`)
+
+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 +555,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,36 +1,50 @@
-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 { sql, serve } from "bun";
 import dashboard from "./dashboard.html";
 import homepage from "./index.html";
 
-const server = Bun.serve({
-  // Add HTML imports to `static`
-  static: {
-    // Bundle & route index.html to "/"
+const server = serve({
+  routes: {
+    // ** HTML imports **
+    // Bundle & route index.html to "/". This uses HTMLRewriter to scan the HTML for `<script>` and `<link>` tags, run's Bun's JavaScript & CSS bundler on them, transpiles any TypeScript, JSX, and TSX, downlevels CSS with Bun's CSS parser and serves the result.
     "/": homepage,
     // Bundle & route dashboard.html to "/dashboard"
     "/dashboard": dashboard,
+
+    // ** API endpoints ** (Bun v1.2.3+ required)
+    "/api/users": {
+      async GET(req) {
+        const users = await sql`SELECT * FROM users`;
+        return Response.json(users);
+      },
+      async POST(req) {
+        const { name, email } = await req.json();
+        const [user] =
+          await sql`INSERT INTO users (name, email) VALUES (${name}, ${email})`;
+        return Response.json(user);
+      },
+    },
+    "/api/users/:id": async req => {
+      const { id } = req.params;
+      const [user] = await 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 });
-  },
+  // Prior to v1.2.3, the `fetch` option was used to handle all API requests. It is now optional.
+  // async fetch(req) {
+  //   // Return 404 for unmatched routes
+  //   return new Response("Not Found", { status: 404 });
+  // },
 });
 
 console.log(`Listening on ${server.url}`);
@@ -55,7 +69,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 +127,7 @@ import dashboard from "../public/dashboard.html";
 import { serve } from "bun";
 
 serve({
-  static: {
+  routes: {
     "/": dashboard,
   },
 
@@ -171,7 +185,7 @@ import homepage from "./index.html";
 import dashboard from "./dashboard.html";
 
 Bun.serve({
-  static: {
+  routes: {
     "/": homepage,
     "/dashboard": dashboard,
   }
@@ -249,6 +263,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 +309,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.20250215T140625 (ca7428e9)
+bun publish v1.2.3-canary.20250217T140554 (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.20250215T140625 (16b4bf34)
+bun install v1.2.3-canary.20250217T140554 (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.20250215T140625"
++   "@types/bun": "^1.2.3-canary.20250217T140554"
   }
 }
 ```
@@ -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.20250215T140625"
+    "@types/bun": "^1.2.3-canary.20250217T140554"
   },
   "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.20250215T140625
+$ bun update @types/bun@1.2.3-canary.20250217T140554
 
 # 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.20250215T140625 (9c68abdb)
+bun test v1.2.3-canary.20250217T140554 (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.20250215T140625 (9c68abdb)
+bun test v1.2.3-canary.20250217T140554 (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.20250215T140625 (9c68abdb)
+bun test v1.2.3-canary.20250217T140554 (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.20250215T140625 (9c68abdb)
+bun test v1.2.3-canary.20250217T140554 (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.20250215T140625 (9c68abdb)
+bun test v1.2.3-canary.20250217T140554 (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.20250215T140625 (9c68abdb)
+bun test v1.2.3-canary.20250217T140554 (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.20250215T140625 (9c68abdb)
+bun test v1.2.3-canary.20250217T140554 (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.20250215T140625"
+Bun.version; // => "1.2.3-canary.20250217T140554"
 ```
 
 ---

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.20250215T140625"
+$ curl -fsSL https://bun.sh/install | bash -s "bun-v1.2.3-canary.20250217T140554"
 ```
 
 ```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.20250215T140625`.
+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.20250217T140554`.
 
 ```sh
-$ curl -fsSL https://bun.sh/install | bash -s "bun-v1.2.3-canary.20250215T140625"
+$ curl -fsSL https://bun.sh/install | bash -s "bun-v1.2.3-canary.20250217T140554"
 ```
 
 ### 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.20250215T140625"
+$ iex "& {$(irm https://bun.sh/install.ps1)} -Version 1.2.3-canary.20250217T140554"
 ```
 
 ## 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.20250215T140625" -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.20250217T140554" -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.20250215T140625
+[fetch] > User-Agent: Bun/1.2.3-canary.20250217T140554
 [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.20250215T140625
+[fetch] > User-Agent: Bun/1.2.3-canary.20250217T140554
 [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.20250215T140625
+bun test v1.2.3-canary.20250217T140554
 
 dom.test.ts:
 ✓ dom test [0.82ms]

package/package.json

@@ -1,5 +1,5 @@
 {
-	"version": "1.2.3-canary.20250215T140625",
+	"version": "1.2.3-canary.20250217T140554",
 	"name": "bun-types",
 	"license": "MIT",
 	"main": "",