bun-types 0.1.11 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bun-types",
-  "version": "0.1.11",
+  "version": "0.2.1",
   "description": "Type definitions for Bun, an incredibly fast JavaScript runtime",
   "types": "types.d.ts",
   "files": [

package/types.d.ts

@@ -1,4 +1,4 @@
-// Type definitions for bun 0.1.11
+// Type definitions for bun 0.2.1
 // Project: https://github.com/oven-sh/bun
 // Definitions by: Jarred Sumner <https://github.com/Jarred-Sumner>
 // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
@@ -823,7 +823,10 @@ interface ResponseInit {
  * ```
  */
 declare class Response implements BlobInterface {
-  constructor(body: BlobPart | BlobPart[], options?: ResponseInit);
+  constructor(
+    body?: ReadableStream | BlobPart | BlobPart[] | null,
+    options?: ResponseInit
+  );
 
   /**
    * Create a new {@link Response} with a JSON body
@@ -885,6 +888,21 @@ declare class Response implements BlobInterface {
    */
   readonly headers: Headers;
 
+  /**
+   * HTTP response body as a [ReadableStream](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream)
+   *
+   * This is part of web Streams
+   *
+   * @example
+   * ```ts
+   * const {body} = await fetch("https://remix.run");
+   * const reader = body.getReader();
+   * const {done, value} = await reader.read();
+   * console.log(value); // Uint8Array
+   * ```
+   */
+  readonly body: ReadableStream | null;
+
   /**
    * Has the body of the response already been consumed?
    */
@@ -1020,7 +1038,9 @@ interface RequestInit {
   /**
    * A boolean to set request's keepalive.
    *
-   * Note: as of Bun v0.0.74, this is not implemented yet.
+   * Available in Bun v0.2.0 and above.
+   *
+   * This is enabled by default
    */
   keepalive?: boolean;
   /**
@@ -1055,6 +1075,11 @@ interface RequestInit {
    * This does nothing in Bun
    */
   window?: any;
+
+  /**
+   * Enable or disable HTTP request timeout
+   */
+  timeout?: boolean;
 }
 
 /**
@@ -1105,6 +1130,19 @@ declare class Request implements BlobInterface {
    */
   text(): Promise<string>;
 
+  /**
+   * Consume the [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request) body as a {@link ReadableStream}.
+   *
+   * Streaming **outgoing** HTTP request bodies via `fetch()` is not yet supported in
+   * Bun.
+   *
+   * Reading **incoming** HTTP request bodies via `ReadableStream` in `Bun.serve()` is supported
+   * as of Bun v0.2.0.
+   *
+   *
+   */
+  get body(): ReadableStream | null;
+
   /**
    * Consume the [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request) body as an ArrayBuffer.
    *
@@ -1436,7 +1474,21 @@ declare function clearTimeout(id?: number): void;
  *
  *
  */
-declare function fetch(url: string, init?: RequestInit): Promise<Response>;
+declare function fetch(
+  url: string,
+  init?: RequestInit,
+  /**
+   * This is a custom property that is not part of the Fetch API specification.
+   * It exists mostly as a debugging tool
+   */
+  bunOnlyOptions?: {
+    /**
+     * Log the raw HTTP request & response to stdout. This API may be
+     * removed in a future version of Bun without notice.
+     */
+    verbose: boolean;
+  }
+): Promise<Response>;
 
 /**
  * Send a HTTP(s) request
@@ -1449,7 +1501,21 @@ declare function fetch(url: string, init?: RequestInit): Promise<Response>;
  *
  */
 // tslint:disable-next-line:unified-signatures
-declare function fetch(request: Request, init?: RequestInit): Promise<Response>;
+declare function fetch(
+  request: Request,
+  init?: RequestInit,
+  /**
+   * This is a custom property that is not part of the Fetch API specification.
+   * It exists mostly as a debugging tool
+   */
+  bunOnlyOptions?: {
+    /**
+     * Log the raw HTTP request & response to stdout. This API may be
+     * removed in a future version of Bun without notice.
+     */
+    verbose: boolean;
+  }
+): Promise<Response>;
 
 declare function queueMicrotask(callback: () => void): void;
 /**
@@ -2108,17 +2174,9 @@ declare var Loader: {
    * instead.
    *
    * @param specifier - module specifier as it appears in transpiled source code
+   * @param referrer - module specifier that is resolving this specifier
    */
-  resolve: (specifier: string) => Promise<string>;
-  /**
-   * Synchronously resolve a module specifier
-   *
-   * This may return a path to `node_modules.server.bun`, which will be confusing.
-   *
-   * Consider {@link Bun.resolveSync}
-   * instead.
-   */
-  resolveSync: (specifier: string, from: string) => string;
+  resolve: (specifier: strin, referrer: string) => string;
 };
 
 /** This Streams API interface represents a readable stream of byte data. The Fetch API offers a concrete instance of a ReadableStream through the body property of a Response object. */
@@ -2139,6 +2197,8 @@ interface ReadableStream<R = any> {
     callbackfn: (value: any, key: number, parent: ReadableStream<R>) => void,
     thisArg?: any
   ): void;
+  [Symbol.asyncIterator](): AsyncIterableIterator<R>;
+  values(options: { preventCancel: boolean }): AsyncIterableIterator<R>;
 }
 
 declare var ReadableStream: {
@@ -13440,6 +13500,28 @@ declare module "bun" {
     end(): ArrayBuffer | Uint8Array;
   }
 
+  /**
+   * Fast incremental writer for files and pipes.
+   *
+   * This uses the same interface as {@link ArrayBufferSink}, but writes to a file or pipe.
+   */
+  export interface FileSink {
+    /**
+     * Write a chunk of data to the file.
+     *
+     * If the file descriptor is not writable yet, the data is buffered.
+     */
+    write(chunk: string | ArrayBufferView | ArrayBuffer): number;
+    /**
+     * Flush the internal buffer, committing the data to disk or the pipe.
+     */
+    flush(): number | Promise<number>;
+    /**
+     * Close the file descriptor. This also flushes the internal buffer.
+     */
+    end(error?: Error): number | Promise<number>;
+  }
+
   /**
    * [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob) powered by the fastest system calls available for operating on files.
    *
@@ -13476,6 +13558,15 @@ declare module "bun" {
      * @param end - absolute offset in bytes (relative to 0)
      */
     slice(begin?: number, end?: number): FileBlob;
+
+    /**
+     * Incremental writer for files and pipes.
+     */
+    writer(): FileSink;
+
+    readonly readable: ReadableStream;
+
+    // TODO: writable: WritableStream;
   }
 
   /**
@@ -13731,7 +13822,477 @@ declare module "bun" {
       | "entry-point";
   }
 
-  export interface ServeOptions {
+  /**
+   * **0** means the message was **dropped**
+   *
+   * **-1** means **backpressure**
+   *
+   * **> 0** is the **number of bytes sent**
+   *
+   */
+  type ServerWebSocketSendStatus = 0 | -1 | number;
+
+  /**
+   * Fast WebSocket API designed for server environments.
+   *
+   * Features:
+   * - **Message compression** - Messages can be compressed
+   * - **Backpressure** - If the client is not ready to receive data, the server will tell you.
+   * - **Dropped messages** - If the client cannot receive data, the server will tell you.
+   * - **Topics** - Messages can be {@link ServerWebSocket.publish}ed to a specific topic and the client can {@link ServerWebSocket.subscribe} to topics
+   *
+   * This is slightly different than the browser {@link WebSocket} which Bun supports for clients.
+   *
+   * Powered by [uWebSockets](https://github.com/uNetworking/uWebSockets)
+   */
+  export interface ServerWebSocket<T = undefined> {
+    /**
+     *
+     * Send a message to the client.
+     *
+     * @param data The message to send
+     * @param compress Should the data be compressed? Ignored if the client does not support compression.
+     *
+     * @returns 0 if the message was dropped, -1 if backpressure was applied, or the number of bytes sent.
+     *
+     * @example
+     *
+     * ```js
+     * const status = ws.send("Hello World");
+     * if (status === 0) {
+     *   console.log("Message was dropped");
+     * } else if (status === -1) {
+     *   console.log("Backpressure was applied");
+     * } else {
+     *   console.log(`Message sent! ${status} bytes sent`);
+     * }
+     * ```
+     *
+     * @example
+     *
+     * ```js
+     * ws.send("Feeling very compressed", true);
+     * ```
+     *
+     * @example
+     *
+     * ```js
+     * ws.send(new Uint8Array([1, 2, 3, 4]));
+     * ```
+     *
+     * @example
+     *
+     * ```js
+     * ws.send(new ArrayBuffer(4));
+     * ```
+     *
+     * @example
+     *
+     * ```js
+     * ws.send(new DataView(new ArrayBuffer(4)));
+     * ```
+     *
+     */
+    send(
+      data: string | ArrayBufferView | ArrayBuffer,
+      compress?: boolean
+    ): ServerWebSocketSendStatus;
+
+    /**
+     *
+     * Send a message to the client.
+     *
+     * This function is the same as {@link ServerWebSocket.send} but it only accepts a string. This function includes a fast path.
+     *
+     * @param data The message to send
+     * @param compress Should the data be compressed? Ignored if the client does not support compression.
+     *
+     * @returns 0 if the message was dropped, -1 if backpressure was applied, or the number of bytes sent.
+     *
+     * @example
+     *
+     * ```js
+     * const status = ws.send("Hello World");
+     * if (status === 0) {
+     *   console.log("Message was dropped");
+     * } else if (status === -1) {
+     *   console.log("Backpressure was applied");
+     * } else {
+     *   console.log(`Message sent! ${status} bytes sent`);
+     * }
+     * ```
+     *
+     * @example
+     *
+     * ```js
+     * ws.send("Feeling very compressed", true);
+     * ```
+     *
+     *
+     */
+    sendText(data: string, compress?: boolean): ServerWebSocketSendStatus;
+
+    /**
+     *
+     * Send a message to the client.
+     *
+     * This function is the same as {@link ServerWebSocket.send} but it only accepts Uint8Array.
+     *
+     * @param data The message to send
+     * @param compress Should the data be compressed? Ignored if the client does not support compression.
+     *
+     * @returns 0 if the message was dropped, -1 if backpressure was applied, or the number of bytes sent.
+     *
+     *
+     * ```js
+     * ws.sendBinary(new Uint8Array([1, 2, 3, 4]));
+     * ```
+     *
+     * @example
+     *
+     * ```js
+     * ws.sendBinary(new ArrayBuffer(4));
+     * ```
+     *
+     * @example
+     *
+     * ```js
+     * ws.sendBinary(new DataView(new ArrayBuffer(4)));
+     * ```
+     *
+     */
+    sendBinary(data: Uint8Array, compress?: boolean): ServerWebSocketSendStatus;
+
+    /**
+     * Gently close the connection.
+     *
+     * @param code The close code
+     *
+     * @param reason The close reason
+     *
+     * To close the connection abruptly, use `close(0, "")`
+     */
+    close(code?: number, reason?: string): void;
+
+    /**
+     * Send a message to all subscribers of a topic
+     *
+     * @param topic The topic to publish to
+     * @param data The data to send
+     * @param compress Should the data be compressed? Ignored if the client does not support compression.
+     *
+     * @returns 0 if the message was dropped, -1 if backpressure was applied, or the number of bytes sent.
+     *
+     * @example
+     *
+     * ```js
+     * ws.publish("chat", "Hello World");
+     * ```
+     *
+     * @example
+     * ```js
+     * ws.publish("chat", new Uint8Array([1, 2, 3, 4]));
+     * ```
+     *
+     * @example
+     * ```js
+     * ws.publish("chat", new ArrayBuffer(4), true);
+     * ```
+     *
+     * @example
+     * ```js
+     * ws.publish("chat", new DataView(new ArrayBuffer(4)));
+     * ```
+     */
+    publish(
+      topic: string,
+      data: string | ArrayBufferView | ArrayBuffer,
+      compress?: boolean
+    ): ServerWebSocketSendStatus;
+
+    /**
+     * Send a message to all subscribers of a topic
+     *
+     * This function is the same as {@link publish} but only accepts string input. This function has a fast path.
+     *
+     * @param topic The topic to publish to
+     * @param data The data to send
+     * @param compress Should the data be compressed? Ignored if the client does not support compression.
+     *
+     * @returns 0 if the message was dropped, -1 if backpressure was applied, or the number of bytes sent.
+     *
+     * @example
+     *
+     * ```js
+     * ws.publishText("chat", "Hello World");
+     * ```
+     *
+     */
+    publishText(
+      topic: string,
+      data: string,
+      compress?: bool
+    ): ServerWebSocketSendStatus;
+
+    /**
+     * Send a message to all subscribers of a topic
+     *
+     * This function is the same as {@link publish} but only accepts a Uint8Array. This function has a fast path.
+     *
+     * @param topic The topic to publish to
+     * @param data The data to send
+     * @param compress Should the data be compressed? Ignored if the client does not support compression.
+     *
+     * @returns 0 if the message was dropped, -1 if backpressure was applied, or the number of bytes sent.
+     *
+     * @example
+     *
+     * ```js
+     * ws.publishBinary("chat", "Hello World");
+     * ```
+     *
+     * @example
+     * ```js
+     * ws.publishBinary("chat", new Uint8Array([1, 2, 3, 4]));
+     * ```
+     *
+     * @example
+     * ```js
+     * ws.publishBinary("chat", new ArrayBuffer(4), true);
+     * ```
+     *
+     * @example
+     * ```js
+     * ws.publishBinary("chat", new DataView(new ArrayBuffer(4)));
+     * ```
+     */
+    publishBinary(
+      topic: string,
+      data: Uint8Array,
+      compress?: boolean
+    ): ServerWebSocketSendStatus;
+
+    /**
+     * Subscribe to a topic
+     * @param topic The topic to subscribe to
+     *
+     * @example
+     * ```js
+     * ws.subscribe("chat");
+     * ```
+     */
+    subscribe(topic: string): void;
+
+    /**
+     * Unsubscribe from a topic
+     * @param topic The topic to unsubscribe from
+     *
+     * @example
+     * ```js
+     * ws.unsubscribe("chat");
+     * ```
+     *
+     */
+    unsubscribe(topic: string): void;
+
+    /**
+     * Is the socket subscribed to a topic?
+     * @param topic The topic to check
+     *
+     * @returns `true` if the socket is subscribed to the topic, `false` otherwise
+     */
+    isSubscribed(topic: string): boolean;
+
+    /**
+     * The remote address of the client
+     * @example
+     * ```js
+     * console.log(socket.remoteAddress); // "127.0.0.1"
+     * ```
+     */
+    readonly remoteAddress: string;
+
+    /**
+     * Ready state of the socket
+     *
+     * @example
+     * ```js
+     * console.log(socket.readyState); // 1
+     * ```
+     */
+    readonly readyState: -1 | 0 | 1 | 2 | 3;
+
+    /**
+     * The data from the {@link Server.upgrade} function
+     *
+     * Put any data you want to share between the `fetch` function and the websocket here.
+     *
+     * You can read/write to this property at any time.
+     */
+    data: T;
+
+    /**
+     * Batch data sent to a {@link ServerWebSocket}
+     *
+     * This makes it significantly faster to {@link ServerWebSocket.send} or {@link ServerWebSocket.publish} multiple messages
+     *
+     * The `message`, `open`, and `drain` callbacks are automatically corked, so
+     * you only need to call this if you are sending messages outside of those
+     * callbacks or in async functions
+     */
+    cork?: (callback: (ws: ServerWebSocket<T>) => any) => void | Promise<void>;
+
+    /**
+     * Configure the {@link WebSocketHandler.message} callback to return a {@link ArrayBuffer} instead of a {@link Uint8Array}
+     *
+     * @default "uint8array"
+     */
+    binaryType?: "arraybuffer" | "uint8array";
+  }
+
+  type WebSocketCompressor =
+    | "disable"
+    | "shared"
+    | "dedicated"
+    | "3KB"
+    | "4KB"
+    | "8KB"
+    | "16KB"
+    | "32KB"
+    | "64KB"
+    | "128KB"
+    | "256KB";
+
+  /**
+   * Create a server-side {@link ServerWebSocket} handler for use with {@link Bun.serve}
+   *
+   * @example
+   * ```ts
+   * import { websocket, serve } from "bun";
+   *
+   * serve({
+   *   port: 3000,
+   *   websocket: websocket<{name: string}>({
+   *     open: (ws) => {
+   *       console.log("Client connected");
+   *    },
+   *     message: (ws, message) => {
+   *       console.log(`${ws.data.name}: ${message}`);
+   *    },
+   *     close: (ws) => {
+   *       console.log("Client disconnected");
+   *    },
+   *  }),
+   *
+   *   fetch(req, server) {
+   *     if (req.url === "/chat") {
+   *       const upgraded = server.upgrade(req, {
+   *         data: {
+   *           name: new URL(req.url).searchParams.get("name"),
+   *        },
+   *      });
+   *       if (!upgraded) {
+   *         return new Response("Upgrade failed", { status: 400 });
+   *      }
+   *      return;
+   *    }
+   *     return new Response("Hello World");
+   *  },
+   * });
+   */
+  export interface WebSocketHandler<T = undefined> {
+    /**
+     * Handle an incoming message to a {@link ServerWebSocket}
+     *
+     * @param ws The {@link ServerWebSocket} that received the message
+     * @param message The message received
+     *
+     * To change `message` to be an `ArrayBuffer` instead of a `Uint8Array`, set `ws.binaryType = "arraybuffer"`
+     */
+    message: (
+      ws: ServerWebSocket<T>,
+      message: string | Uint8Array
+    ) => void | Promise<void>;
+
+    /**
+     * The {@link ServerWebSocket} has been opened
+     *
+     * @param ws The {@link ServerWebSocket} that was opened
+     */
+    open?: (ws: ServerWebSocket<T>) => void | Promise<void>;
+    /**
+     * The {@link ServerWebSocket} is ready for more data
+     *
+     * @param ws The {@link ServerWebSocket} that is ready
+     */
+    drain?: (ws: ServerWebSocket<T>) => void | Promise<void>;
+    /**
+     * The {@link ServerWebSocket} is being closed
+     * @param ws The {@link ServerWebSocket} that was closed
+     * @param code The close code
+     * @param message The close message
+     */
+    close?: (
+      ws: ServerWebSocket<T>,
+      code: number,
+      message: string
+    ) => void | Promise<void>;
+
+    /**
+     * Enable compression for clients that support it. By default, compression is disabled.
+     *
+     * @default false
+     *
+     * `true` is equivalent to `"shared"
+     */
+    perMessageDeflate?:
+      | true
+      | false
+      | {
+          /**
+           * Enable compression on the {@link ServerWebSocket}
+           *
+           * @default false
+           *
+           * `true` is equivalent to `"shared"
+           */
+          compress?: WebSocketCompressor | false | true;
+          /**
+           * Configure decompression
+           *
+           * @default false
+           *
+           * `true` is equivalent to `"shared"
+           */
+          decompress?: WebSocketCompressor | false | true;
+        };
+
+    /**
+     * The maximum size of a message
+     */
+    maxPayloadLength?: number;
+    /**
+     * After a connection has not received a message for this many seconds, it will be closed.
+     * @default 120 (2 minutes)
+     */
+    idleTimeout?: number;
+    /**
+     * The maximum number of bytes that can be buffered for a single connection.
+     * @default 16MB
+     */
+    backpressureLimit?: number;
+    /**
+     * Close the connection if the backpressure limit is reached.
+     * @default false
+     * @see {@link backpressureLimit}
+     * @see {@link ServerWebSocketSendStatus}
+     * @see {@link ServerWebSocket.send}
+     * @see {@link ServerWebSocket.publish}
+     */
+    closeOnBackpressureLimit?: boolean;
+  }
+
+  interface GenericServeOptions {
     /**
      * What port should the server listen on?
      * @default process.env.PORT || "3000"
@@ -13793,18 +14354,78 @@ declare module "bun" {
      */
     development?: boolean;
 
+    error?: (
+      this: Server,
+      request: Errorlike
+    ) => Response | Promise<Response> | undefined | Promise<undefined>;
+  }
+
+  export interface ServeOptions extends GenericServeOptions {
     /**
      * Handle HTTP requests
      *
      * Respond to {@link Request} objects with a {@link Response} object.
      *
      */
-    fetch(this: Server, request: Request): Response | Promise<Response>;
+    fetch(
+      this: Server,
+      request: Request,
+      server: Server
+    ): Response | Promise<Response>;
+  }
 
-    error?: (
+  export interface WebSocketServeOptions<WebSocketDataType = undefined>
+    extends GenericServeOptions {
+    /**
+     * Enable websockets with {@link Bun.serve}
+     *
+     * For simpler type safety, see {@link Bun.websocket}
+     *
+     * @example
+     * ```js
+     *import { serve, websocket } from "bun";
+     *serve({
+     *  websocket: websocket({
+     *    open: (ws) => {
+     *      console.log("Client connected");
+     *    },
+     *    message: (ws, message) => {
+     *      console.log("Client sent message", message);
+     *    },
+     *    close: (ws) => {
+     *      console.log("Client disconnected");
+     *    },
+     *  }),
+     *  fetch(req, server) {
+     *    if (req.url === "/chat") {
+     *      const upgraded = server.upgrade(req);
+     *      if (!upgraded) {
+     *        return new Response("Upgrade failed", { status: 400 });
+     *      }
+     *    }
+     *    return new Response("Hello World");
+     *  },
+     *});
+     *```
+     * Upgrade a {@link Request} to a {@link ServerWebSocket} via {@link Server.upgrade}
+     *
+     * Pass `data` in @{link Server.upgrade} to attach data to the {@link ServerWebSocket.data} property
+     *
+     *
+     */
+    websocket: WebSocketHandler<WebSocketDataType>;
+
+    /**
+     * Handle HTTP requests or upgrade them to a {@link ServerWebSocket}
+     *
+     * Respond to {@link Request} objects with a {@link Response} object.
+     *
+     */
+    fetch(
       this: Server,
-      request: Errorlike
-    ) => Response | Promise<Response> | undefined | Promise<undefined>;
+      request: Request,
+      server: Server
+    ): Response | undefined | Promise<Response | undefined>;
   }
 
   export interface Errorlike extends Error {
@@ -13840,7 +14461,10 @@ declare module "bun" {
     certFile: string;
   }
 
-  export type SSLServeOptions = ServeOptions &
+  export type SSLServeOptions<WebSocketDataType = undefined> = (
+    | WebSocketServeOptions<WebSocketDataType>
+    | ServerWebSocket
+  ) &
     SSLOptions &
     SSLAdvancedOptions & {
       /**
@@ -13855,10 +14479,6 @@ declare module "bun" {
    *
    * To start the server, see {@link serve}
    *
-   * Often, you don't need to interact with this object directly. It exists to help you with the following tasks:
-   * - Stop the server
-   * - How many requests are currently being handled?
-   *
    * For performance, Bun pre-allocates most of the data for 2048 concurrent requests.
    * That means starting a new server allocates about 500 KB of memory. Try to
    * avoid starting and stopping the server often (unless it's a new instance of bun).
@@ -13866,7 +14486,7 @@ declare module "bun" {
    * Powered by a fork of [uWebSockets](https://github.com/uNetworking/uWebSockets). Thank you @alexhultman.
    *
    */
-  interface Server {
+  export interface Server {
     /**
      * Stop listening to prevent new connections from being accepted.
      *
@@ -13876,16 +14496,129 @@ declare module "bun" {
      */
     stop(): void;
 
+    /**
+     * Update the `fetch` and `error` handlers without restarting the server.
+     *
+     * This is useful if you want to change the behavior of your server without
+     * restarting it or for hot reloading.
+     *
+     * @example
+     *
+     * ```js
+     * // create the server
+     * const server = Bun.serve({
+     *  fetch(request) {
+     *    return new Response("Hello World v1")
+     *  }
+     * });
+     *
+     * // Update the server to return a different response
+     * server.update({
+     *   fetch(request) {
+     *     return new Response("Hello World v2")
+     *   }
+     * });
+     * ```
+     *
+     * Passing other options such as `port` or `hostname` won't do anything.
+     */
+    reload(options: Serve): void;
+
+    /**
+     * Mock the fetch handler for a running server.
+     *
+     * This feature is not fully implemented yet. It doesn't normalize URLs
+     * consistently in all cases and it doesn't yet call the `error` handler
+     * consistently. This needs to be fixed
+     */
+    fetch(request: Request): Response | Promise<Response>;
+
+    /**
+     * Upgrade a {@link Request} to a {@link ServerWebSocket}
+     *
+     * @param request The {@link Request} to upgrade
+     * @param options Pass headers or attach data to the {@link ServerWebSocket}
+     *
+     * @returns `true` if the upgrade was successful and `false` if it failed
+     *
+     * @example
+     * ```js
+     * import { serve, websocket } from "bun";
+     *  serve({
+     *    websocket: websocket({
+     *      open: (ws) => {
+     *        console.log("Client connected");
+     *      },
+     *      message: (ws, message) => {
+     *        console.log("Client sent message", message);
+     *      },
+     *      close: (ws) => {
+     *        console.log("Client disconnected");
+     *      },
+     *    }),
+     *    fetch(req, server) {
+     *      if (req.url === "/chat") {
+     *        const upgraded = server.upgrade(req);
+     *        if (!upgraded) {
+     *          return new Response("Upgrade failed", { status: 400 });
+     *        }
+     *      }
+     *      return new Response("Hello World");
+     *    },
+     *  });
+     * ```
+     *  What you pass to `data` is available on the {@link ServerWebSocket.data} property
+     *
+     */
+    upgrade<T = undefined>(
+      request: Request,
+      options?: {
+        /**
+         * Send any additional headers while upgrading, like cookies
+         */
+        headers?: HeadersInit;
+        /**
+         * This value is passed to the {@link ServerWebSocket.data} property
+         */
+        data?: T;
+      }
+    ): boolean;
+
     /**
      * How many requests are in-flight right now?
      */
     readonly pendingRequests: number;
+
+    /**
+     * How many {@link ServerWebSocket}s are in-flight right now?
+     */
+    readonly pendingWebSockets: number;
+
     readonly port: number;
+    /**
+     * The hostname the server is listening on. Does not include the port
+     * @example
+     * ```js
+     * "localhost"
+     * ```
+     */
     readonly hostname: string;
+    /**
+     * Is the server running in development mode?
+     *
+     * In development mode, `Bun.serve()` returns rendered error messages with
+     * stack traces instead of a generic 500 error. This makes debugging easier,
+     * but development mode shouldn't be used in production or you will risk
+     * leaking sensitive information.
+     *
+     */
     readonly development: boolean;
   }
 
-  export type Serve = SSLServeOptions | ServeOptions;
+  export type Serve<WebSocketDataType = undefined> =
+    | SSLServeOptions<WebSocketDataType>
+    | WebSocketServeOptions<WebSocketDataType>
+    | ServeOptions;
 
   /**
    * [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob) powered by the fastest system calls available for operating on files.
@@ -14653,6 +15386,271 @@ declare module "bun" {
   }
 
   var plugin: BunPlugin;
+
+  declare namespace SpawnOptions {
+    type Readable =
+      | "inherit"
+      | "pipe"
+      | null
+      | undefined
+      | FileBlob
+      | ArrayBufferView
+      | number;
+
+    type Writable =
+      | "inherit"
+      | "pipe"
+      | null
+      | undefined
+      | FileBlob
+      | ArrayBufferView
+      | Blob
+      | number
+      | Response
+      | Request;
+
+    interface OptionsObject {
+      /**
+       * The current working directory of the process
+       *
+       * Defaults to `process.cwd()`
+       */
+      cwd?: string;
+
+      /**
+       * The environment variables of the process
+       *
+       * Defaults to `process.env` as it was when the current Bun process launched.
+       *
+       * Changes to `process.env` at runtime won't automatically be reflected in the default value. For that, you can pass `process.env` explicitly.
+       *
+       */
+      env?: Record<string, string>;
+
+      /**
+       * The standard file descriptors of the process
+       * - `inherit`: The process will inherit the standard input of the current process
+       * - `pipe`: The process will have a new pipe for standard input
+       * - `null`: The process will have no standard input
+       * - `ArrayBufferView`, `Blob`: The process will read from the buffer
+       * - `number`: The process will read from the file descriptor
+       * - `undefined`: The default value
+       */
+      stdio?: [
+        SpawnOptions.Writable,
+        SpawnOptions.Readable,
+        SpawnOptions.Readable
+      ];
+      stdin?: SpawnOptions.Writable;
+      stdout?: SpawnOptions.Readable;
+      stderr?: SpawnOptions.Readable;
+
+      /**
+       * Callback that runs when the {@link Subprocess} exits
+       *
+       * You can also do `await subprocess.exited` to wait for the process to exit.
+       *
+       * @example
+       *
+       * ```ts
+       * const subprocess = spawn({
+       *  cmd: ["echo", "hello"],
+       *  onExit: (code) => {
+       *    console.log(`Process exited with code ${code}`);
+       *   },
+       * });
+       * ```
+       */
+      onExit?: (exitCode: number) => void | Promise<void>;
+    }
+  }
+
+  interface Subprocess {
+    readonly stdin: undefined | number | FileSink;
+    readonly stdout: undefined | number | ReadableStream;
+    readonly stderr: undefined | number | ReadableStream;
+
+    /**
+     * This returns the same value as {@link Subprocess.stdout}
+     *
+     * It exists for compatibility with {@link ReadableStream.pipeThrough}
+     */
+    readonly readable: undefined | number | ReadableStream;
+
+    /**
+     * The process ID of the child process
+     * @example
+     * ```ts
+     * const { pid } = Bun.spawn({ cmd: ["echo", "hello"] });
+     * console.log(pid); // 1234
+     * ```
+     */
+    readonly pid: number;
+    /**
+     * The exit code of the process
+     *
+     * The promise will resolve when the process exits
+     */
+    readonly exited: Promise<number>;
+
+    /**
+     * Has the process exited?
+     */
+    readonly killed: boolean;
+
+    /**
+     * Kill the process
+     * @param exitCode The exitCode to send to the process
+     */
+    kill(exitCode?: number): void;
+
+    /**
+     * This method will tell Bun to wait for this process to exit after you already
+     * called `unref()`.
+     *
+     * Before shutting down, Bun will wait for all subprocesses to exit by default
+     */
+    ref(): void;
+
+    /**
+     * Before shutting down, Bun will wait for all subprocesses to exit by default
+     *
+     * This method will tell Bun to not wait for this process to exit before shutting down.
+     */
+    unref(): void;
+  }
+
+  interface SyncSubprocess {
+    stdout?: Buffer;
+    stderr?: Buffer;
+    exitCode: number;
+    success: boolean;
+  }
+
+  /**
+   * Spawn a new process
+   *
+   * ```js
+   * const subprocess = Bun.spawn({
+   *  cmd: ["echo", "hello"],
+   *  stdout: "pipe",
+   * });
+   * const text = await readableStreamToText(subprocess.stdout);
+   * console.log(text); // "hello\n"
+   * ```
+   *
+   * Internally, this uses [posix_spawn(2)](https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/posix_spawn.2.html)
+   */
+  function spawn(
+    options: SpawnOptions.OptionsObject & {
+      /**
+       * The command to run
+       *
+       * The first argument will be resolved to an absolute executable path. It must be a file, not a directory.
+       *
+       * If you explicitly set `PATH` in `env`, that `PATH` will be used to resolve the executable instead of the default `PATH`.
+       *
+       * To check if the command exists before running it, use `Bun.which(bin)`.
+       *
+       */
+      cmd: [string, ...string[]];
+    }
+  ): Subprocess;
+
+  /**
+   * Spawn a new process
+   *
+   * ```js
+   * const {stdout} = Bun.spawn(["echo", "hello"]));
+   * const text = await readableStreamToText(stdout);
+   * console.log(text); // "hello\n"
+   * ```
+   *
+   * Internally, this uses [posix_spawn(2)](https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/posix_spawn.2.html)
+   */
+  function spawn(
+    /**
+     * The command to run
+     * @example
+     * ```ts
+     * const subprocess = Bun.spawn(["echo", "hello"]);
+     */
+    cmds: [
+      /** One command is required */
+      string,
+      /** Additional arguments */
+      ...string[]
+    ],
+    options?: SpawnOptions.OptionsObject
+  ): Subprocess;
+
+  /**
+   * Spawn a new process
+   *
+   * ```js
+   * const {stdout} = Bun.spawnSync({
+   *  cmd: ["echo", "hello"],
+   * });
+   * console.log(stdout.toString()); // "hello\n"
+   * ```
+   *
+   * Internally, this uses [posix_spawn(2)](https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/posix_spawn.2.html)
+   */
+  function spawnSync(
+    options: SpawnOptions.OptionsObject & {
+      /**
+       * The command to run
+       *
+       * The first argument will be resolved to an absolute executable path. It must be a file, not a directory.
+       *
+       * If you explicitly set `PATH` in `env`, that `PATH` will be used to resolve the executable instead of the default `PATH`.
+       *
+       * To check if the command exists before running it, use `Bun.which(bin)`.
+       *
+       */
+      cmd: [string, ...string[]];
+    }
+  ): SyncSubprocess;
+
+  /**
+   * Synchronously spawn a new process
+   *
+   * ```js
+   * const {stdout} = Bun.spawnSync(["echo", "hello"]));
+   * console.log(stdout.toString()); // "hello\n"
+   * ```
+   *
+   * Internally, this uses [posix_spawn(2)](https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/posix_spawn.2.html)
+   */
+  function spawnSync(
+    /**
+     * The command to run
+     * @example
+     * ```ts
+     * const subprocess = Bun.spawn(["echo", "hello"]);
+     */
+    cmds: [
+      /** One command is required */
+      string,
+      /** Additional arguments */
+      ...string[]
+    ],
+    options?: SpawnOptions.OptionsObject
+  ): SyncSubprocess;
+
+  /**
+   * The current version of Bun
+   * @example
+   * "0.2.0"
+   */
+  export const version: string;
+
+  /**
+   * The git sha at the time the currently-running version of Bun was compiled
+   * @example
+   * "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2"
+   */
+  export const revision: string;
 }
 
 type TypedArray =