bun-types 1.2.10-canary.20250414T140624 → 1.2.10-canary.20250415T140641

package/bun.d.ts

@@ -57,7 +57,7 @@ declare module "bun" {
      *
      * Uses the lib.dom.d.ts definition if it exists, otherwise defines it locally.
      *
-     * This is to avoid type conflicts between lib.dom.d.ts and @types/bun.
+     * This is to avoid type conflicts between lib.dom.d.ts and \@types/bun.
      *
      * Unfortunately some symbols cannot be defined when both Bun types and lib.dom.d.ts types are loaded,
      * and since we can't redeclare the symbol in a way that satisfies both, we need to fallback
@@ -162,17 +162,6 @@ declare module "bun" {
     open: Event;
   }
 
-  interface EventInit {
-    bubbles?: boolean;
-    cancelable?: boolean;
-    composed?: boolean;
-  }
-
-  interface EventListenerOptions {
-    /** Not directly used by Node.js. Added for API completeness. Default: `false`. */
-    capture?: boolean;
-  }
-
   interface AddEventListenerOptions extends EventListenerOptions {
     /** When `true`, the listener is automatically removed when it is first invoked. Default: `false`. */
     once?: boolean;
@@ -560,7 +549,6 @@ declare module "bun" {
    *
    * @returns The width of the string in columns
    *
-   * ## Examples
    * @example
    * ```ts
    * import { stringWidth } from "bun";
@@ -571,7 +559,6 @@ declare module "bun" {
    * console.log(stringWidth("\u001b[31mhello\u001b[39m", { countAnsiEscapeCodes: false })); // 5
    * console.log(stringWidth("\u001b[31mhello\u001b[39m", { countAnsiEscapeCodes: true })); // 13
    * ```
-   *
    */
   function stringWidth(
     /**
@@ -594,367 +581,6 @@ declare module "bun" {
     },
   ): number;
 
-  type ShellFunction = (input: Uint8Array) => Uint8Array;
-
-  type ShellExpression =
-    | { toString(): string }
-    | Array<ShellExpression>
-    | string
-    | { raw: string }
-    | Subprocess
-    | SpawnOptions.Readable
-    | SpawnOptions.Writable
-    | ReadableStream;
-
-  class ShellPromise extends Promise<ShellOutput> {
-    get stdin(): WritableStream;
-    /**
-     * Change the current working directory of the shell.
-     * @param newCwd - The new working directory
-     */
-    cwd(newCwd: string): this;
-    /**
-     * Set environment variables for the shell.
-     * @param newEnv - The new environment variables
-     *
-     * @example
-     * ```ts
-     * await $`echo $FOO`.env({ ...process.env, FOO: "LOL!" })
-     * expect(stdout.toString()).toBe("LOL!");
-     * ```
-     */
-    env(newEnv: Record<string, string> | undefined): this;
-    /**
-     * By default, the shell will write to the current process's stdout and stderr, as well as buffering that output.
-     *
-     * This configures the shell to only buffer the output.
-     */
-    quiet(): this;
-
-    /**
-     * Read from stdout as a string, line by line
-     *
-     * Automatically calls {@link quiet} to disable echoing to stdout.
-     */
-    lines(): AsyncIterable<string>;
-
-    /**
-     * Read from stdout as a string
-     *
-     * Automatically calls {@link quiet} to disable echoing to stdout.
-     * @param encoding - The encoding to use when decoding the output
-     * @returns A promise that resolves with stdout as a string
-     * @example
-     *
-     * ## Read as UTF-8 string
-     *
-     * ```ts
-     * const output = await $`echo hello`.text();
-     * console.log(output); // "hello\n"
-     * ```
-     *
-     * ## Read as base64 string
-     *
-     * ```ts
-     * const output = await $`echo ${atob("hello")}`.text("base64");
-     * console.log(output); // "hello\n"
-     * ```
-     *
-     */
-    text(encoding?: BufferEncoding): Promise<string>;
-
-    /**
-     * Read from stdout as a JSON object
-     *
-     * Automatically calls {@link quiet}
-     *
-     * @returns A promise that resolves with stdout as a JSON object
-     * @example
-     *
-     * ```ts
-     * const output = await $`echo '{"hello": 123}'`.json();
-     * console.log(output); // { hello: 123 }
-     * ```
-     *
-     */
-    json(): Promise<any>;
-
-    /**
-     * Read from stdout as an ArrayBuffer
-     *
-     * Automatically calls {@link quiet}
-     * @returns A promise that resolves with stdout as an ArrayBuffer
-     * @example
-     *
-     * ```ts
-     * const output = await $`echo hello`.arrayBuffer();
-     * console.log(output); // ArrayBuffer { byteLength: 6 }
-     * ```
-     */
-    arrayBuffer(): Promise<ArrayBuffer>;
-
-    /**
-     * Read from stdout as a Blob
-     *
-     * Automatically calls {@link quiet}
-     * @returns A promise that resolves with stdout as a Blob
-     * @example
-     * ```ts
-     * const output = await $`echo hello`.blob();
-     * console.log(output); // Blob { size: 6, type: "" }
-     * ```
-     */
-    blob(): Promise<Blob>;
-
-    /**
-     * Configure the shell to not throw an exception on non-zero exit codes. Throwing can be re-enabled with `.throws(true)`.
-     *
-     * By default, the shell with throw an exception on commands which return non-zero exit codes.
-     */
-    nothrow(): this;
-
-    /**
-     * Configure whether or not the shell should throw an exception on non-zero exit codes.
-     *
-     * By default, this is configured to `true`.
-     */
-    throws(shouldThrow: boolean): this;
-  }
-
-  interface ShellConstructor {
-    new (): Shell;
-  }
-
-  interface Shell {
-    (strings: TemplateStringsArray, ...expressions: ShellExpression[]): ShellPromise;
-
-    readonly Shell: ShellConstructor;
-    readonly ShellPromise: typeof ShellPromise;
-    readonly ShellError: typeof ShellError;
-
-    /**
-     * Perform bash-like brace expansion on the given pattern.
-     * @param pattern - Brace pattern to expand
-     *
-     * @example
-     * ```js
-     * const result = braces('index.{js,jsx,ts,tsx}');
-     * console.log(result) // ['index.js', 'index.jsx', 'index.ts', 'index.tsx']
-     * ```
-     */
-    braces(pattern: string): string[];
-
-    /**
-     * Escape strings for input into shell commands.
-     * @param input
-     */
-    escape(input: string): string;
-
-    /**
-     *
-     * Change the default environment variables for shells created by this instance.
-     *
-     * @param newEnv Default environment variables to use for shells created by this instance.
-     * @default process.env
-     *
-     * ## Example
-     *
-     * ```js
-     * import {$} from 'bun';
-     * $.env({ BUN: "bun" });
-     * await $`echo $BUN`;
-     * // "bun"
-     * ```
-     */
-    env(newEnv?: Record<string, string | undefined>): this;
-
-    /**
-     *
-     * @param newCwd Default working directory to use for shells created by this instance.
-     */
-    cwd(newCwd?: string): this;
-
-    /**
-     * Configure the shell to not throw an exception on non-zero exit codes.
-     */
-    nothrow(): this;
-
-    /**
-     * Configure whether or not the shell should throw an exception on non-zero exit codes.
-     */
-    throws(shouldThrow: boolean): this;
-  }
-
-  class ShellError extends Error implements ShellOutput {
-    readonly stdout: Buffer;
-    readonly stderr: Buffer;
-    readonly exitCode: number;
-
-    /**
-     * Read from stdout as a string
-     *
-     * @param encoding - The encoding to use when decoding the output
-     * @returns Stdout as a string with the given encoding
-     * @example
-     *
-     * ## Read as UTF-8 string
-     *
-     * ```ts
-     * const output = await $`echo hello`;
-     * console.log(output.text()); // "hello\n"
-     * ```
-     *
-     * ## Read as base64 string
-     *
-     * ```ts
-     * const output = await $`echo ${atob("hello")}`;
-     * console.log(output.text("base64")); // "hello\n"
-     * ```
-     *
-     */
-    text(encoding?: BufferEncoding): string;
-
-    /**
-     * Read from stdout as a JSON object
-     *
-     * @returns Stdout as a JSON object
-     * @example
-     *
-     * ```ts
-     * const output = await $`echo '{"hello": 123}'`;
-     * console.log(output.json()); // { hello: 123 }
-     * ```
-     *
-     */
-    json(): any;
-
-    /**
-     * Read from stdout as an ArrayBuffer
-     *
-     * @returns Stdout as an ArrayBuffer
-     * @example
-     *
-     * ```ts
-     * const output = await $`echo hello`;
-     * console.log(output.arrayBuffer()); // ArrayBuffer { byteLength: 6 }
-     * ```
-     */
-    arrayBuffer(): ArrayBuffer;
-
-    /**
-     * Read from stdout as a Blob
-     *
-     * @returns Stdout as a blob
-     * @example
-     * ```ts
-     * const output = await $`echo hello`;
-     * console.log(output.blob()); // Blob { size: 6, type: "" }
-     * ```
-     */
-    blob(): Blob;
-
-    /**
-     * Read from stdout as an Uint8Array
-     *
-     * @returns Stdout as an Uint8Array
-     * @example
-     *```ts
-     * const output = await $`echo hello`;
-     * console.log(output.bytes()); // Uint8Array { byteLength: 6 }
-     * ```
-     */
-    bytes(): Uint8Array;
-  }
-
-  interface ShellOutput {
-    readonly stdout: Buffer;
-    readonly stderr: Buffer;
-    readonly exitCode: number;
-
-    /**
-     * Read from stdout as a string
-     *
-     * @param encoding - The encoding to use when decoding the output
-     * @returns Stdout as a string with the given encoding
-     * @example
-     *
-     * ## Read as UTF-8 string
-     *
-     * ```ts
-     * const output = await $`echo hello`;
-     * console.log(output.text()); // "hello\n"
-     * ```
-     *
-     * ## Read as base64 string
-     *
-     * ```ts
-     * const output = await $`echo ${atob("hello")}`;
-     * console.log(output.text("base64")); // "hello\n"
-     * ```
-     *
-     */
-    text(encoding?: BufferEncoding): string;
-
-    /**
-     * Read from stdout as a JSON object
-     *
-     * @returns Stdout as a JSON object
-     * @example
-     *
-     * ```ts
-     * const output = await $`echo '{"hello": 123}'`;
-     * console.log(output.json()); // { hello: 123 }
-     * ```
-     *
-     */
-    json(): any;
-
-    /**
-     * Read from stdout as an ArrayBuffer
-     *
-     * @returns Stdout as an ArrayBuffer
-     * @example
-     *
-     * ```ts
-     * const output = await $`echo hello`;
-     * console.log(output.arrayBuffer()); // ArrayBuffer { byteLength: 6 }
-     * ```
-     */
-    arrayBuffer(): ArrayBuffer;
-
-    /**
-     * Read from stdout as an Uint8Array
-     *
-     * @returns Stdout as an Uint8Array
-     * @example
-     *
-     * ```ts
-     * const output = await $`echo hello`;
-     * console.log(output.bytes()); // Uint8Array { byteLength: 6 }
-     * ```
-     */
-    bytes(): Uint8Array;
-
-    /**
-     * Read from stdout as a Blob
-     *
-     * @returns Stdout as a blob
-     * @example
-     * ```ts
-     * const output = await $`echo hello`;
-     * console.log(output.blob()); // Blob { size: 6, type: "" }
-     * ```
-     */
-    blob(): Blob;
-  }
-
-  /**
-   * The Bun shell
-   *
-   * @category Process Management
-   */
-  const $: Shell;
-
   const TOML: {
     /**
      * Parse a TOML string into a JavaScript object.
@@ -1227,8 +853,7 @@ declare module "bun" {
    * @param multipartBoundaryExcludingDashes Optional boundary to use for multipart form data. If none is provided, assumes it is a URLEncoded form.
    * @returns A promise that resolves with the data encoded into a {@link FormData} object.
    *
-   * ## Multipart form data example
-   *
+   * @example Multipart form data example
    * ```ts
    * // without dashes
    * const boundary = "WebKitFormBoundary" + Math.random().toString(16).slice(2);
@@ -1237,8 +862,8 @@ declare module "bun" {
    * const formData = await Bun.readableStreamToFormData(stream, boundary);
    * formData.get("foo"); // "bar"
    * ```
-   * ## URL-encoded form data example
    *
+   * @example URL-encoded form data example
    * ```ts
    * const stream = new Response("hello=123").body;
    * const formData = await Bun.readableStreamToFormData(stream);
@@ -2043,22 +1668,6 @@ declare module "bun" {
      */
     maxAge?: number;
   }
-  interface CSRF {
-    /**
-     * Generate a CSRF token.
-     * @param secret The secret to use for the token. If not provided, a random default secret will be generated in memory and used.
-     * @param options The options for the token.
-     * @returns The generated token.
-     */
-    generate(secret?: string, options?: CSRFGenerateOptions): string;
-    /**
-     * Verify a CSRF token.
-     * @param token The token to verify.
-     * @param options The options for the token.
-     * @returns True if the token is valid, false otherwise.
-     */
-    verify(token: string, options?: CSRFVerifyOptions): boolean;
-  }
 
   /**
    * SQL client
@@ -2086,7 +1695,23 @@ declare module "bun" {
    *
    * @category Security
    */
-  var CSRF: CSRF;
+  var CSRF: {
+    /**
+     * Generate a CSRF token.
+     * @param secret The secret to use for the token. If not provided, a random default secret will be generated in memory and used.
+     * @param options The options for the token.
+     * @returns The generated token.
+     */
+    generate(secret?: string, options?: CSRFGenerateOptions): string;
+
+    /**
+     * Verify a CSRF token.
+     * @param token The token to verify.
+     * @param options The options for the token.
+     * @returns True if the token is valid, false otherwise.
+     */
+    verify(token: string, options?: CSRFVerifyOptions): boolean;
+  };
 
   /**
    *   This lets you use macros as regular imports
@@ -2449,6 +2074,7 @@ declare module "bun" {
      * @see {@link publicPath} to customize the base url of linked source maps
      */
     sourcemap?: "none" | "linked" | "inline" | "external" | "linked" | boolean;
+
     /**
      * package.json `exports` conditions used when resolving imports
      *
@@ -2477,6 +2103,7 @@ declare module "bun" {
      * ```
      */
     env?: "inline" | "disable" | `${string}*`;
+
     /**
      * Whether to enable minification.
      *
@@ -2492,16 +2119,19 @@ declare module "bun" {
           syntax?: boolean;
           identifiers?: boolean;
         };
+
     /**
      * Ignore dead code elimination/tree-shaking annotations such as @__PURE__ and package.json
      * "sideEffects" fields. This should only be used as a temporary workaround for incorrect
      * annotations in libraries.
      */
     ignoreDCEAnnotations?: boolean;
+
     /**
      * Force emitting @__PURE__ annotations even if minify.whitespace is true.
      */
     emitDCEAnnotations?: boolean;
+
     // treeshaking?: boolean;
 
     // jsx?:
@@ -2528,10 +2158,12 @@ declare module "bun" {
      * @default false
      */
     bytecode?: boolean;
+
     /**
      * Add a banner to the bundled code such as "use client";
      */
     banner?: string;
+
     /**
      * Add a footer to the bundled code such as a comment block like
      *
@@ -2562,10 +2194,9 @@ declare module "bun" {
    * @category Security
    */
   namespace Password {
-    type AlgorithmLabel = "bcrypt" | "argon2id" | "argon2d" | "argon2i";
-
     interface Argon2Algorithm {
       algorithm: "argon2id" | "argon2d" | "argon2i";
+
       /**
        * Memory cost, which defines the memory usage, given in kibibytes.
        */
@@ -2579,11 +2210,14 @@ declare module "bun" {
 
     interface BCryptAlgorithm {
       algorithm: "bcrypt";
+
       /**
        * A number between 4 and 31. The default is 10.
        */
       cost?: number;
     }
+
+    type AlgorithmLabel = (BCryptAlgorithm | Argon2Algorithm)["algorithm"];
   }
 
   /**
@@ -2594,7 +2228,7 @@ declare module "bun" {
    * @see [Bun.password API docs](https://bun.sh/guides/util/hash-a-password)
    *
    * The underlying implementation of these functions are provided by the Zig
-   * Standard Library. Thanks to @jedisct1 and other Zig contributors for their
+   * Standard Library. Thanks to \@jedisct1 and other Zig contributors for their
    * work on this.
    *
    * ### Example with argon2
@@ -2686,9 +2320,9 @@ declare module "bun" {
        */
       password: Bun.StringOrBuffer,
       /**
-       * @default "argon2id"
-       *
        * When using bcrypt, passwords exceeding 72 characters will be SHA512'd before
+       *
+       * @default "argon2id"
        */
       algorithm?: Password.AlgorithmLabel | Password.Argon2Algorithm | Password.BCryptAlgorithm,
     ): Promise<string>;
@@ -2699,7 +2333,7 @@ declare module "bun" {
      * instead which runs in a worker thread.
      *
      * The underlying implementation of these functions are provided by the Zig
-     * Standard Library. Thanks to @jedisct1 and other Zig contributors for their
+     * Standard Library. Thanks to \@jedisct1 and other Zig contributors for their
      * work on this.
      *
      * ### Example with argon2
@@ -2724,7 +2358,13 @@ declare module "bun" {
      * ```
      */
     verifySync(
+      /**
+       * The password to verify.
+       */
       password: Bun.StringOrBuffer,
+      /**
+       * The hash to verify against.
+       */
       hash: Bun.StringOrBuffer,
       /**
        * If not specified, the algorithm will be inferred from the hash.
@@ -2738,7 +2378,7 @@ declare module "bun" {
      * instead which runs in a worker thread.
      *
      * The underlying implementation of these functions are provided by the Zig
-     * Standard Library. Thanks to @jedisct1 and other Zig contributors for their
+     * Standard Library. Thanks to \@jedisct1 and other Zig contributors for their
      * work on this.
      *
      * ### Example with argon2
@@ -2770,10 +2410,11 @@ declare module "bun" {
        * mistake to hash an empty password.
        */
       password: Bun.StringOrBuffer,
+
       /**
-       * @default "argon2id"
-       *
        * When using bcrypt, passwords exceeding 72 characters will be SHA256'd before
+       *
+       * @default "argon2id"
        */
       algorithm?: Password.AlgorithmLabel | Password.Argon2Algorithm | Password.BCryptAlgorithm,
     ): string;
@@ -4618,6 +4259,211 @@ declare module "bun" {
     compact?: boolean;
   }
 
+  type WebSocketOptionsProtocolsOrProtocol =
+    | {
+        /**
+         * Protocols to use for the WebSocket connection
+         */
+        protocols?: string | string[];
+      }
+    | {
+        /**
+         * Protocol to use for the WebSocket connection
+         */
+        protocol?: string;
+      };
+
+  type WebSocketOptionsTLS = {
+    /**
+     * Options for the TLS connection
+     */
+    tls?: {
+      /**
+       * Whether to reject the connection if the certificate is not valid
+       *
+       * @default true
+       */
+      rejectUnauthorized?: boolean;
+    };
+  };
+
+  type WebSocketOptionsHeaders = {
+    /**
+     * Headers to send to the server
+     */
+    headers?: import("node:http").OutgoingHttpHeaders;
+  };
+
+  /**
+   * Constructor options for the `Bun.WebSocket` client
+   */
+  type WebSocketOptions = WebSocketOptionsProtocolsOrProtocol & WebSocketOptionsTLS & WebSocketOptionsHeaders;
+
+  interface WebSocketEventMap {
+    close: CloseEvent;
+    error: Event;
+    message: MessageEvent;
+    open: Event;
+  }
+
+  /**
+   * A WebSocket client implementation
+   *
+   * @example
+   * ```ts
+   * const ws = new WebSocket("ws://localhost:8080", {
+   *  headers: {
+   *    "x-custom-header": "hello",
+   *  },
+   * });
+   *
+   * ws.addEventListener("open", () => {
+   *   console.log("Connected to server");
+   * });
+   *
+   * ws.addEventListener("message", (event) => {
+   *   console.log("Received message:", event.data);
+   * });
+   *
+   * ws.send("Hello, server!");
+   * ws.terminate();
+   * ```
+   */
+  interface WebSocket extends EventTarget {
+    /**
+     * The URL of the WebSocket connection
+     */
+    readonly url: string;
+
+    /**
+     * Legacy URL property (same as url)
+     * @deprecated Use url instead
+     */
+    readonly URL: string;
+
+    /**
+     * The current state of the connection
+     */
+    readonly readyState:
+      | typeof WebSocket.CONNECTING
+      | typeof WebSocket.OPEN
+      | typeof WebSocket.CLOSING
+      | typeof WebSocket.CLOSED;
+
+    /**
+     * The number of bytes of data that have been queued using send() but not yet transmitted to the network
+     */
+    readonly bufferedAmount: number;
+
+    /**
+     * The protocol selected by the server
+     */
+    readonly protocol: string;
+
+    /**
+     * The extensions selected by the server
+     */
+    readonly extensions: string;
+
+    /**
+     * The type of binary data being received.
+     */
+    binaryType: "arraybuffer" | "nodebuffer";
+
+    /**
+     * Event handler for open event
+     */
+    onopen: ((this: WebSocket, ev: Event) => any) | null;
+
+    /**
+     * Event handler for message event
+     */
+    onmessage: ((this: WebSocket, ev: MessageEvent) => any) | null;
+
+    /**
+     * Event handler for error event
+     */
+    onerror: ((this: WebSocket, ev: Event) => any) | null;
+
+    /**
+     * Event handler for close event
+     */
+    onclose: ((this: WebSocket, ev: CloseEvent) => any) | null;
+
+    /**
+     * Transmits data to the server
+     * @param data The data to send to the server
+     */
+    send(data: string | ArrayBufferLike | ArrayBufferView): void;
+
+    /**
+     * Closes the WebSocket connection
+     * @param code A numeric value indicating the status code
+     * @param reason A human-readable string explaining why the connection is closing
+     */
+    close(code?: number, reason?: string): void;
+
+    /**
+     * Sends a ping frame to the server
+     * @param data Optional data to include in the ping frame
+     */
+    ping(data?: string | ArrayBufferLike | ArrayBufferView): void;
+
+    /**
+     * Sends a pong frame to the server
+     * @param data Optional data to include in the pong frame
+     */
+    pong(data?: string | ArrayBufferLike | ArrayBufferView): void;
+
+    /**
+     * Immediately terminates the connection
+     */
+    terminate(): void;
+
+    /**
+     * Registers an event handler of a specific event type on the WebSocket.
+     * @param type A case-sensitive string representing the event type to listen for
+     * @param listener The function to be called when the event occurs
+     * @param options An options object that specifies characteristics about the event listener
+     */
+    addEventListener<K extends keyof WebSocketEventMap>(
+      type: K,
+      listener: (this: WebSocket, ev: WebSocketEventMap[K]) => any,
+      options?: boolean | AddEventListenerOptions,
+    ): void;
+    addEventListener(
+      type: string,
+      listener: EventListenerOrEventListenerObject,
+      options?: boolean | AddEventListenerOptions,
+    ): void;
+
+    /**
+     * Removes an event listener previously registered with addEventListener()
+     * @param type A case-sensitive string representing the event type to remove
+     * @param listener The function to remove from the event target
+     * @param options An options object that specifies characteristics about the event listener
+     */
+    removeEventListener<K extends keyof WebSocketEventMap>(
+      type: K,
+      listener: (this: WebSocket, ev: WebSocketEventMap[K]) => any,
+      options?: boolean | EventListenerOptions,
+    ): void;
+    removeEventListener(
+      type: string,
+      listener: EventListenerOrEventListenerObject,
+      options?: boolean | EventListenerOptions,
+    ): void;
+
+    /** @deprecated Use instance property instead */
+    readonly CONNECTING: 0;
+    /** @deprecated Use instance property instead */
+    readonly OPEN: 1;
+    /** @deprecated Use instance property instead */
+    readonly CLOSING: 2;
+    /** @deprecated Use instance property instead */
+    readonly CLOSED: 3;
+  }
+
   /**
    * Pretty-print an object the same as {@link console.log} to a `string`
    *
@@ -5863,6 +5709,12 @@ declare module "bun" {
      */
     shutdown(halfClose?: boolean): void;
 
+    // -1 = detached
+    // 0 = closed
+    // 1 = open
+    // -2 = closing
+    // 2 = everything else
+    // positive = open
     readonly readyState: "open" | "closing" | "closed";
 
     /**
@@ -6206,68 +6058,159 @@ declare module "bun" {
   }
 
   interface SocketOptions<Data = unknown> {
+    /**
+     * Handlers for socket events
+     */
     socket: SocketHandler<Data>;
+    /**
+     * The per-instance data context
+     */
     data?: Data;
   }
-  // interface TCPSocketOptions<Data = undefined> extends SocketOptions<Data> {
-  //   hostname: string;
-  //   port: number;
-  // }
 
   interface TCPSocketListenOptions<Data = undefined> extends SocketOptions<Data> {
+    /**
+     * The hostname to listen on
+     */
     hostname: string;
+    /**
+     * The port to listen on
+     */
     port: number;
+    /**
+     * The TLS configuration object with which to create the server
+     */
     tls?: TLSOptions;
+    /**
+     * Whether to use exclusive mode.
+     *
+     * When set to `true`, the socket binds exclusively to the specified address:port
+     * combination, preventing other processes from binding to the same port.
+     *
+     * When `false` (default), other sockets may be able to bind to the same port
+     * depending on the operating system's socket sharing capabilities and settings.
+     *
+     * Exclusive mode is useful in scenarios where you want to ensure only one
+     * instance of your server can bind to a specific port at a time.
+     *
+     * @default false
+     */
     exclusive?: boolean;
+    /**
+     * Whether to allow half-open connections.
+     *
+     * A half-open connection occurs when one end of the connection has called `close()`
+     * or sent a FIN packet, while the other end remains open. When set to `true`:
+     *
+     * - The socket won't automatically send FIN when the remote side closes its end
+     * - The local side can continue sending data even after the remote side has closed
+     * - The application must explicitly call `end()` to fully close the connection
+     *
+     * When `false` (default), the socket automatically closes both ends of the connection
+     * when either side closes.
+     *
+     * @default false
+     */
     allowHalfOpen?: boolean;
   }
 
   interface TCPSocketConnectOptions<Data = undefined> extends SocketOptions<Data> {
+    /**
+     * The hostname to connect to
+     */
     hostname: string;
+    /**
+     * The port to connect to
+     */
     port: number;
+    /**
+     * TLS Configuration with which to create the socket
+     */
     tls?: boolean;
+    /**
+     * Whether to use exclusive mode.
+     *
+     * When set to `true`, the socket binds exclusively to the specified address:port
+     * combination, preventing other processes from binding to the same port.
+     *
+     * When `false` (default), other sockets may be able to bind to the same port
+     * depending on the operating system's socket sharing capabilities and settings.
+     *
+     * Exclusive mode is useful in scenarios where you want to ensure only one
+     * instance of your server can bind to a specific port at a time.
+     *
+     * @default false
+     */
     exclusive?: boolean;
+    /**
+     * Whether to allow half-open connections.
+     *
+     * A half-open connection occurs when one end of the connection has called `close()`
+     * or sent a FIN packet, while the other end remains open. When set to `true`:
+     *
+     * - The socket won't automatically send FIN when the remote side closes its end
+     * - The local side can continue sending data even after the remote side has closed
+     * - The application must explicitly call `end()` to fully close the connection
+     *
+     * When `false` (default), the socket automatically closes both ends of the connection
+     * when either side closes.
+     *
+     * @default false
+     */
     allowHalfOpen?: boolean;
   }
 
   interface UnixSocketOptions<Data = undefined> extends SocketOptions<Data> {
-    tls?: TLSOptions;
+    /**
+     * The unix socket to listen on or connect to
+     */
     unix: string;
+    /**
+     * TLS Configuration with which to create the socket
+     */
+    tls?: TLSOptions;
   }
 
   interface FdSocketOptions<Data = undefined> extends SocketOptions<Data> {
+    /**
+     * TLS Configuration with which to create the socket
+     */
     tls?: TLSOptions;
+    /**
+     * The file descriptor to connect to
+     */
     fd: number;
   }
 
   /**
-   * Create a TCP client that connects to a server
+   * Create a TCP client that connects to a server via a TCP socket
    *
-   * @param options The options to use when creating the client
-   * @param options.socket The socket handler to use
-   * @param options.data The per-instance data context
-   * @param options.hostname The hostname to connect to
-   * @param options.port The port to connect to
-   * @param options.tls The TLS configuration object
-   * @param options.unix The unix socket to connect to
+   * @category HTTP & Networking
    */
   function connect<Data = undefined>(options: TCPSocketConnectOptions<Data>): Promise<Socket<Data>>;
+  /**
+   * Create a TCP client that connects to a server via a unix socket
+   *
+   * @category HTTP & Networking
+   */
   function connect<Data = undefined>(options: UnixSocketOptions<Data>): Promise<Socket<Data>>;
 
   /**
    * Create a TCP server that listens on a port
    *
-   * @param options The options to use when creating the server
-   * @param options.socket The socket handler to use
-   * @param options.data The per-instance data context
-   * @param options.hostname The hostname to connect to
-   * @param options.port The port to connect to
-   * @param options.tls The TLS configuration object
-   * @param options.unix The unix socket to connect to
+   * @category HTTP & Networking
    */
   function listen<Data = undefined>(options: TCPSocketListenOptions<Data>): TCPSocketListener<Data>;
+  /**
+   * Create a TCP server that listens on a unix socket
+   *
+   * @category HTTP & Networking
+   */
   function listen<Data = undefined>(options: UnixSocketOptions<Data>): UnixSocketListener<Data>;
 
+  /**
+   * @category HTTP & Networking
+   */
   namespace udp {
     type Data = string | ArrayBufferView | ArrayBufferLike;
 
@@ -6345,6 +6288,8 @@ declare module "bun" {
    * @param options.port The port to listen on
    * @param options.binaryType The binary type to use for the socket
    * @param options.connect The hostname and port to connect to
+   *
+   * @category HTTP & Networking
    */
   export function udpSocket<DataBinaryType extends BinaryType = "buffer">(
     options: udp.SocketOptions<DataBinaryType>,