bun-types 1.2.1-canary.20250126T140515 → 1.2.1-canary.20250128T140616

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/1.2.1-canary.20250126T140515
+[fetch] > User-Agent: Bun/1.2.1-canary.20250128T140616
 [fetch] > Accept: */*
 [fetch] > Host: example.com
 [fetch] > Accept-Encoding: gzip, deflate, br

package/docs/api/http.md

@@ -513,6 +513,241 @@ Bun.serve({
 });
 ```
 
+## Server Lifecycle Methods
+
+### server.stop() - Stop the server
+
+To stop the server from accepting new connections:
+
+```ts
+const server = Bun.serve({
+  fetch(req) {
+    return new Response("Hello!");
+  },
+});
+
+// Gracefully stop the server (waits for in-flight requests)
+await server.stop();
+
+// Force stop and close all active connections
+await server.stop(true);
+```
+
+By default, `stop()` allows in-flight requests and WebSocket connections to complete. Pass `true` to immediately terminate all connections.
+
+### server.ref() and server.unref() - Process lifecycle control
+
+Control whether the server keeps the Bun process alive:
+
+```ts
+// Don't keep process alive if server is the only thing running
+server.unref();
+
+// Restore default behavior - keep process alive
+server.ref();
+```
+
+### server.reload() - Hot reload handlers
+
+Update the server's handlers without restarting:
+
+```ts
+const server = Bun.serve({
+  static: {
+    "/api/version": Response.json({ version: "v1" }),
+  },
+  fetch(req) {
+    return new Response("v1");
+  },
+});
+
+// Update to new handler
+server.reload({
+  static: {
+    "/api/version": Response.json({ version: "v2" }),
+  },
+  fetch(req) {
+    return new Response("v2");
+  },
+});
+```
+
+This is useful for development and hot reloading. Only `fetch`, `error`, and `static` handlers can be updated.
+
+## Per-Request Controls
+
+<!-- ### server.abort(Request) - Abort requests
+
+The `server.abort(request: Request)` method:
+
+- Returns `true` if request was aborted, `false` if already aborted/completed
+- Triggers the request's `AbortSignal`
+- Cancels any attached `ReadableStream`
+- Rejects any pending body promises (like `.text()`)
+
+```ts
+const server = Bun.serve({
+  fetch(req, server) {
+    // abort if the url contains "slow"
+    if (req.url.includes("slow")) {
+      server.abort(req);
+
+      // When aborted, the server will not error due to the lack of a `Response` object
+      // If you return a `Response` anyway, it will be ignored.
+      return;
+    }
+
+    return new Response("Processing...");
+  },
+});
+``` -->
+
+### server.timeout(Request, seconds) - Custom request timeouts
+
+Set a custom idle timeout for individual requests:
+
+```ts
+const server = Bun.serve({
+  fetch(req, server) {
+    // Set 60 second timeout for this request
+    server.timeout(req, 60);
+
+    // Long operation
+    await someSlowOperation();
+
+    return new Response("Done!");
+  },
+});
+```
+
+Pass `0` to disable the timeout for a request.
+
+### server.requestIP(Request) - Get client information
+
+Get client IP and port information:
+
+```ts
+const server = Bun.serve({
+  fetch(req, server) {
+    const address = server.requestIP(req);
+    if (address) {
+      return new Response(
+        `Client IP: ${address.address}, Port: ${address.port}`,
+      );
+    }
+    return new Response("Unknown client");
+  },
+});
+```
+
+Returns `null` for closed requests or Unix domain sockets.
+
+## Server Metrics
+
+### server.pendingRequests and server.pendingWebSockets
+
+Monitor server activity with built-in counters:
+
+```ts
+const server = Bun.serve({
+  fetch(req, server) {
+    return new Response(
+      `Active requests: ${server.pendingRequests}\n` +
+        `Active WebSockets: ${server.pendingWebSockets}`,
+    );
+  },
+});
+```
+
+### server.subscriberCount(topic) - WebSocket subscribers
+
+Get count of subscribers for a WebSocket topic:
+
+```ts
+const server = Bun.serve({
+  fetch(req, server) {
+    const chatUsers = server.subscriberCount("chat");
+    return new Response(`${chatUsers} users in chat`);
+  },
+  websocket: {
+    message(ws) {
+      ws.subscribe("chat");
+    },
+  },
+});
+```
+
+## WebSocket Configuration
+
+### server.publish(topic, data, compress) - WebSocket Message Publishing
+
+The server can publish messages to all WebSocket clients subscribed to a topic:
+
+```ts
+const server = Bun.serve({
+  websocket: {
+    message(ws) {
+      // Publish to all "chat" subscribers
+      server.publish("chat", "Hello everyone!");
+    },
+  },
+
+  fetch(req) {
+    // ...
+  },
+});
+```
+
+The `publish()` method returns:
+
+- Number of bytes sent if successful
+- `0` if the message was dropped
+- `-1` if backpressure was applied
+
+### WebSocket Handler Options
+
+When configuring WebSockets, several advanced options are available through the `websocket` handler:
+
+```ts
+Bun.serve({
+  websocket: {
+    // Maximum message size (in bytes)
+    maxPayloadLength: 64 * 1024,
+
+    // Backpressure limit before messages are dropped
+    backpressureLimit: 1024 * 1024,
+
+    // Close connection if backpressure limit is hit
+    closeOnBackpressureLimit: true,
+
+    // Handler called when backpressure is relieved
+    drain(ws) {
+      console.log("Backpressure relieved");
+    },
+
+    // Enable per-message deflate compression
+    perMessageDeflate: {
+      compress: true,
+      decompress: true,
+    },
+
+    // Send ping frames to keep connection alive
+    sendPings: true,
+
+    // Handlers for ping/pong frames
+    ping(ws, data) {
+      console.log("Received ping");
+    },
+    pong(ws, data) {
+      console.log("Received pong");
+    },
+
+    // Whether server receives its own published messages
+    publishToSelf: false,
+  },
+});
+```
+
 ## Benchmarks
 
 Below are Bun and Node.js implementations of a simple HTTP server that responds `Bun!` to each incoming `Request`.
@@ -561,100 +796,174 @@ The `Bun.serve` server can handle roughly 2.5x more requests per second than Nod
 {% details summary="See TypeScript definitions" %}
 
 ```ts
-interface Bun {
-  serve(options: {
-    development?: boolean;
-    error?: (
-      request: ErrorLike,
-    ) => Response | Promise<Response> | undefined | Promise<undefined>;
-    fetch(request: Request, server: Server): Response | Promise<Response>;
-    hostname?: string;
-    id?: string | null;
-    maxRequestBodySize?: number;
-    port?: string | number;
-    reusePort?: boolean;
-    tls?: TLSOptions | Array<TLSOptions>;
-    unix: string;
-    websocket: WebSocketHandler<WebSocketDataType>;
-  }): Server;
-}
+interface Server extends Disposable {
+  /**
+   * Stop the server from accepting new connections.
+   * @param closeActiveConnections If true, immediately terminates all connections
+   * @returns Promise that resolves when the server has stopped
+   */
+  stop(closeActiveConnections?: boolean): Promise<void>;
+
+  /**
+   * Update handlers without restarting the server.
+   * Only fetch and error handlers can be updated.
+   */
+  reload(options: Serve): void;
 
-interface TLSOptions {
-  ca?: string | Buffer | BunFile | Array<string | Buffer | BunFile> | undefined;
-  cert?:
-    | string
-    | Buffer
-    | BunFile
-    | Array<string | Buffer | BunFile>
-    | undefined;
-  dhParamsFile?: string;
-  key?:
-    | string
-    | Buffer
-    | BunFile
-    | Array<string | Buffer | BunFile>
-    | undefined;
-  lowMemoryMode?: boolean;
-  passphrase?: string;
-  secureOptions?: number | undefined;
-  serverName?: string;
+  /**
+   * Make a request to the running server.
+   * Useful for testing or internal routing.
+   */
+  fetch(request: Request | string): Response | Promise<Response>;
+
+  /**
+   * Upgrade an HTTP request to a WebSocket connection.
+   * @returns true if upgrade successful, false if failed
+   */
+  upgrade<T = undefined>(
+    request: Request,
+    options?: {
+      headers?: Bun.HeadersInit;
+      data?: T;
+    },
+  ): boolean;
+
+  /**
+   * Publish a message to all WebSocket clients subscribed to a topic.
+   * @returns Bytes sent, 0 if dropped, -1 if backpressure applied
+   */
+  publish(
+    topic: string,
+    data: string | ArrayBufferView | ArrayBuffer | SharedArrayBuffer,
+    compress?: boolean,
+  ): ServerWebSocketSendStatus;
+
+  /**
+   * Get count of WebSocket clients subscribed to a topic.
+   */
+  subscriberCount(topic: string): number;
+
+  /**
+   * Get client IP address and port.
+   * @returns null for closed requests or Unix sockets
+   */
+  requestIP(request: Request): SocketAddress | null;
+
+  /**
+   * Set custom idle timeout for a request.
+   * @param seconds Timeout in seconds, 0 to disable
+   */
+  timeout(request: Request, seconds: number): void;
+
+  /**
+   * Keep process alive while server is running.
+   */
+  ref(): void;
+
+  /**
+   * Allow process to exit if server is only thing running.
+   */
+  unref(): void;
+
+  /** Number of in-flight HTTP requests */
+  readonly pendingRequests: number;
+
+  /** Number of active WebSocket connections */
+  readonly pendingWebSockets: number;
+
+  /** Server URL including protocol, hostname and port */
+  readonly url: URL;
+
+  /** Port server is listening on */
+  readonly port: number;
+
+  /** Hostname server is bound to */
+  readonly hostname: string;
+
+  /** Whether server is in development mode */
+  readonly development: boolean;
+
+  /** Server instance identifier */
+  readonly id: string;
 }
 
 interface WebSocketHandler<T = undefined> {
+  /** Maximum WebSocket message size in bytes */
+  maxPayloadLength?: number;
+
+  /** Bytes of queued messages before applying backpressure */
   backpressureLimit?: number;
-  close?(
-    ws: ServerWebSocket<T>,
-    code: number,
-    reason: string,
-  ): void | Promise<void>;
+
+  /** Whether to close connection when backpressure limit hit */
   closeOnBackpressureLimit?: boolean;
+
+  /** Called when backpressure is relieved */
   drain?(ws: ServerWebSocket<T>): void | Promise<void>;
+
+  /** Seconds before idle timeout */
   idleTimeout?: number;
-  maxPayloadLength?: number;
-  message(
-    ws: ServerWebSocket<T>,
-    message: string | Buffer,
-  ): void | Promise<void>;
-  open?(ws: ServerWebSocket<T>): void | Promise<void>;
+
+  /** Enable per-message deflate compression */
   perMessageDeflate?:
     | boolean
     | {
         compress?: WebSocketCompressor | boolean;
         decompress?: WebSocketCompressor | boolean;
       };
+
+  /** Send ping frames to keep connection alive */
+  sendPings?: boolean;
+
+  /** Whether server receives its own published messages */
+  publishToSelf?: boolean;
+
+  /** Called when connection opened */
+  open?(ws: ServerWebSocket<T>): void | Promise<void>;
+
+  /** Called when message received */
+  message(
+    ws: ServerWebSocket<T>,
+    message: string | Buffer,
+  ): void | Promise<void>;
+
+  /** Called when connection closed */
+  close?(
+    ws: ServerWebSocket<T>,
+    code: number,
+    reason: string,
+  ): void | Promise<void>;
+
+  /** Called when ping frame received */
   ping?(ws: ServerWebSocket<T>, data: Buffer): void | Promise<void>;
+
+  /** Called when pong frame received */
   pong?(ws: ServerWebSocket<T>, data: Buffer): void | Promise<void>;
-  publishToSelf?: boolean;
-  sendPings?: boolean;
 }
 
-interface Server {
-  fetch(request: Request | string): Response | Promise<Response>;
-  publish(
-    compress?: boolean,
-    data: string | ArrayBufferView | ArrayBuffer | SharedArrayBuffer,
-    topic: string,
-  ): ServerWebSocketSendStatus;
-  ref(): void;
-  reload(options: Serve): void;
-  requestIP(request: Request): SocketAddress | null;
-  stop(closeActiveConnections?: boolean): void;
-  unref(): void;
-  upgrade<T = undefined>(
-    options?: {
-      data?: T;
-      headers?: Bun.HeadersInit;
-    },
-    request: Request,
-  ): boolean;
+interface TLSOptions {
+  /** Certificate authority chain */
+  ca?: string | Buffer | BunFile | Array<string | Buffer | BunFile>;
 
-  readonly development: boolean;
-  readonly hostname: string;
-  readonly id: string;
-  readonly pendingRequests: number;
-  readonly pendingWebSockets: number;
-  readonly port: number;
-  readonly url: URL;
+  /** Server certificate */
+  cert?: string | Buffer | BunFile | Array<string | Buffer | BunFile>;
+
+  /** Path to DH parameters file */
+  dhParamsFile?: string;
+
+  /** Private key */
+  key?: string | Buffer | BunFile | Array<string | Buffer | BunFile>;
+
+  /** Reduce TLS memory usage */
+  lowMemoryMode?: boolean;
+
+  /** Private key passphrase */
+  passphrase?: string;
+
+  /** OpenSSL options flags */
+  secureOptions?: number;
+
+  /** Server name for SNI */
+  serverName?: string;
 }
 ```
 

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.1-canary.20250126T140515"
+console.log(text); // => "1.2.1-canary.20250128T140616"
 ```
 
 Configure the output stream by passing one of the following values to `stdout/stderr`:

package/docs/bundler/fullstack.md

@@ -6,7 +6,7 @@ To get started, import your HTML files and pass them to the `static` option in `
 import dashboard from "./dashboard.html";
 import homepage from "./index.html";
 
-Bun.serve({
+const server = Bun.serve({
   // Add HTML imports to `static`
   static: {
     // Bundle & route index.html to "/"
@@ -32,6 +32,8 @@ Bun.serve({
     return new Response("Not Found", { status: 404 });
   },
 });
+
+console.log(`Listening on ${server.url}`)
 ```
 
 ```bash
@@ -107,7 +109,7 @@ To use React in your client-side code, import `react-dom/client` and render your
 {% codetabs %}
 
 ```ts#src/backend.ts
-import dashboard from "./public/dashboard.html";
+import dashboard from "../public/dashboard.html";
 import { serve } from "bun";
 
 serve({
@@ -204,18 +206,19 @@ To configure plugins for `Bun.serve`, add a `plugins` array in the `[serve.stati
 
 ### Using TailwindCSS in HTML routes
 
-For example, enable TailwindCSS on your routes by adding add the `bun-plugin-tailwind` plugin:
+For example, enable TailwindCSS on your routes by installing and adding the `bun-plugin-tailwind` plugin:
 
-```toml
+```sh
+$ bun add bun-plugin-tailwind
+```
+```toml#bunfig.toml
 [serve.static]
 plugins = ["bun-plugin-tailwind"]
-
 ```
 
 This will allow you to use TailwindCSS utility classes in your HTML and CSS files. All you need to do is import `tailwindcss` somewhere:
 
-```html
-<!-- index.html -->
+```html#index.html
 <!doctype html>
 <html>
   <head>
@@ -230,14 +233,15 @@ This will allow you to use TailwindCSS utility classes in your HTML and CSS file
 
 Or in your CSS:
 
-```css
-/* style.css */
+```css#style.css
 @import "tailwindcss";
 ```
 
+### Custom plugins
+
 Any JS file or module which exports a [valid bundler plugin object](https://bun.sh/docs/bundler/plugins#usage) (essentially an object with a `name` and `setup` field) can be placed inside the `plugins` array:
 
-```toml
+```toml#bunfig.toml
 [serve.static]
 plugins = ["./my-plugin-implementation.ts"]
 ```

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.1-canary.20250126T140515 (ca7428e9)
+bun publish v1.2.1-canary.20250128T140616 (ca7428e9)
 
 packed 203B package.json
 packed 224B README.md

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.1-canary.20250126T140515" -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.1-canary.20250128T140616" -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.1-canary.20250126T140515
+[fetch] > User-Agent: Bun/1.2.1-canary.20250128T140616
 [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.1-canary.20250126T140515
+[fetch] > User-Agent: Bun/1.2.1-canary.20250128T140616
 [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.1-canary.20250126T140515
+bun test v1.2.1-canary.20250128T140616
 
 dom.test.ts:
 ✓ dom test [0.82ms]

package/package.json

@@ -1,5 +1,5 @@
 {
-	"version": "1.2.1-canary.20250126T140515",
+	"version": "1.2.1-canary.20250128T140616",
 	"name": "bun-types",
 	"license": "MIT",
 	"main": "",