bun-types 0.2.0 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bun-types",
-  "version": "0.2.0",
+  "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.2.0
+// 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
@@ -13822,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"
@@ -13884,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 {
@@ -13931,7 +14461,10 @@ declare module "bun" {
     certFile: string;
   }
 
-  export type SSLServeOptions = ServeOptions &
+  export type SSLServeOptions<WebSocketDataType = undefined> = (
+    | WebSocketServeOptions<WebSocketDataType>
+    | ServerWebSocket
+  ) &
     SSLOptions &
     SSLAdvancedOptions & {
       /**
@@ -13946,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).
@@ -13957,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.
      *
@@ -14004,10 +14533,67 @@ declare module "bun" {
      */
     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
@@ -14029,7 +14615,10 @@ declare module "bun" {
     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.