bun-types 0.2.0 → 0.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bun-types",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "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.2
 // Project: https://github.com/oven-sh/bun
 // Definitions by: Jarred Sumner <https://github.com/Jarred-Sumner>
 // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
@@ -699,7 +699,7 @@ interface BlobInterface {
   json<TJSONReturnType = unknown>(): Promise<TJSONReturnType>;
 }
 
-type BlobPart = string | Blob | ArrayBufferView | ArrayBuffer;
+type BlobPart = string | Blob | BufferSource | ArrayBuffer;
 interface BlobPropertyBag {
   /** Set a default "type" */
   type?: string;
@@ -753,14 +753,14 @@ declare class Blob implements BlobInterface {
   /**
    * Create a new [Blob](https://developer.mozilla.org/en-US/docs/Web/API/Blob)
    *
-   * @param `parts` - An array of strings, numbers, TypedArray, or [Blob](https://developer.mozilla.org/en-US/docs/Web/API/Blob) objects
+   * @param `parts` - An array of strings, numbers, BufferSource, or [Blob](https://developer.mozilla.org/en-US/docs/Web/API/Blob) objects
    * @param `options` - An object containing properties to be added to the [Blob](https://developer.mozilla.org/en-US/docs/Web/API/Blob)
    */
   constructor(parts?: BlobPart[] | Blob, options?: BlobPropertyBag);
   /**
    * Create a new view **without 🚫 copying** the underlying data.
    *
-   * Similar to [`TypedArray.subarray`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray/subarray)
+   * Similar to [`BufferSource.subarray`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BufferSource/subarray)
    *
    * @param begin The index that sets the beginning of the view.
    * @param end The index that sets the end of the view.
@@ -1227,7 +1227,9 @@ declare class Request implements BlobInterface {
 }
 
 interface Crypto {
-  getRandomValues<T extends TypedArray = TypedArray>(array: T): T;
+  readonly subtle: SubtleCrypto;
+
+  getRandomValues<T extends BufferSource = BufferSource>(array: T): T;
   /**
    * Generate a cryptographically secure random UUID.
    *
@@ -1294,7 +1296,7 @@ declare class TextEncoder {
    * @param src The text to encode.
    * @param dest The array to hold the encode result.
    */
-  encodeInto(src?: string, dest?: TypedArray): EncodeIntoResult;
+  encodeInto(src?: string, dest?: BufferSource): EncodeIntoResult;
 }
 
 /**
@@ -1333,9 +1335,9 @@ declare class TextDecoder {
    * internally and emitted after the next call to `textDecoder.decode()`.
    *
    * If `textDecoder.fatal` is `true`, decoding errors that occur will result in a`TypeError` being thrown.
-   * @param input An `ArrayBuffer`, `DataView` or `TypedArray` instance containing the encoded data.
+   * @param input An `ArrayBuffer`, `DataView` or `BufferSource` instance containing the encoded data.
    */
-  decode(input?: TypedArray | ArrayBuffer): string;
+  decode(input?: BufferSource | ArrayBuffer): string;
 }
 
 /**
@@ -1894,8 +1896,8 @@ interface WebSocket extends EventTarget {
   readonly url: string;
   /** Closes the WebSocket connection, optionally using code as the the WebSocket connection close code and reason as the the WebSocket connection close reason. */
   close(code?: number, reason?: string): void;
-  /** Transmits data using the WebSocket connection. data can be a string, an ArrayBuffer, or an ArrayBufferView. */
-  send(data: string | ArrayBufferLike | ArrayBufferView): void;
+  /** Transmits data using the WebSocket connection. data can be a string, an ArrayBuffer, or an BufferSource. */
+  send(data: string | ArrayBufferLike | BufferSource): void;
   readonly CLOSED: number;
   readonly CLOSING: number;
   readonly CONNECTING: number;
@@ -2070,7 +2072,7 @@ declare var AbortSignal: {
 
 // type AlgorithmIdentifier = Algorithm | string;
 // type BodyInit = ReadableStream | XMLHttpRequestBodyInit;
-type BufferSource = ArrayBufferView | ArrayBuffer;
+type BufferSource = ArrayBufferView | ArrayBuffer | SharedArrayBuffer;
 // type COSEAlgorithmIdentifier = number;
 // type CSSNumberish = number;
 // type CanvasImageSource =
@@ -2176,7 +2178,7 @@ declare var Loader: {
    * @param specifier - module specifier as it appears in transpiled source code
    * @param referrer - module specifier that is resolving this specifier
    */
-  resolve: (specifier: strin, referrer: string) => string;
+  resolve: (specifier: string, 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. */
@@ -2198,7 +2200,7 @@ interface ReadableStream<R = any> {
     thisArg?: any
   ): void;
   [Symbol.asyncIterator](): AsyncIterableIterator<R>;
-  values(options: { preventCancel: boolean }): AsyncIterableIterator<R>;
+  values(options?: { preventCancel: boolean }): AsyncIterableIterator<R>;
 }
 
 declare var ReadableStream: {
@@ -2224,9 +2226,9 @@ interface QueuingStrategyInit {
 }
 
 /** This Streams API interface provides a built-in byte length queuing strategy that can be used when constructing streams. */
-interface ByteLengthQueuingStrategy extends QueuingStrategy<ArrayBufferView> {
+interface ByteLengthQueuingStrategy extends QueuingStrategy<BufferSource> {
   readonly highWaterMark: number;
-  readonly size: QueuingStrategySize<ArrayBufferView>;
+  readonly size: QueuingStrategySize<BufferSource>;
 }
 
 declare var ByteLengthQueuingStrategy: {
@@ -2243,7 +2245,7 @@ interface ReadableStreamDefaultController<R = any> {
 
 interface ReadableStreamDirectController {
   close(error?: Error): void;
-  write(data: ArrayBufferView | ArrayBuffer | string): number | Promise<number>;
+  write(data: BufferSource | ArrayBuffer | string): number | Promise<number>;
   end(): number | Promise<number>;
   flush(): number | Promise<number>;
   start(): void;
@@ -2500,7 +2502,329 @@ interface ErrnoException extends Error {
 declare function alert(message?: string): void;
 declare function confirm(message?: string): boolean;
 declare function prompt(message?: string, _default?: string): string | null;
-declare function require(path: string): import(path);
+
+/* 
+
+ Web Crypto API
+
+*/
+
+type KeyFormat = "jwk" | "pkcs8" | "raw" | "spki";
+type KeyType = "private" | "public" | "secret";
+type KeyUsage =
+  | "decrypt"
+  | "deriveBits"
+  | "deriveKey"
+  | "encrypt"
+  | "sign"
+  | "unwrapKey"
+  | "verify"
+  | "wrapKey";
+type HashAlgorithmIdentifier = AlgorithmIdentifier;
+type NamedCurve = string;
+
+type BigInteger = Uint8Array;
+
+interface KeyAlgorithm {
+  name: string;
+}
+
+interface Algorithm {
+  name: string;
+}
+
+interface AesCbcParams extends Algorithm {
+  iv: BufferSource;
+}
+
+interface AesCtrParams extends Algorithm {
+  counter: BufferSource;
+  length: number;
+}
+
+interface AesDerivedKeyParams extends Algorithm {
+  length: number;
+}
+
+interface AesGcmParams extends Algorithm {
+  additionalData?: BufferSource;
+  iv: BufferSource;
+  tagLength?: number;
+}
+
+interface AesKeyAlgorithm extends KeyAlgorithm {
+  length: number;
+}
+
+interface AesKeyGenParams extends Algorithm {
+  length: number;
+}
+
+interface EcKeyAlgorithm extends KeyAlgorithm {
+  namedCurve: NamedCurve;
+}
+
+interface EcKeyGenParams extends Algorithm {
+  namedCurve: NamedCurve;
+}
+
+interface EcKeyImportParams extends Algorithm {
+  namedCurve: NamedCurve;
+}
+
+interface EcdhKeyDeriveParams extends Algorithm {
+  public: CryptoKey;
+}
+
+interface EcdsaParams extends Algorithm {
+  hash: HashAlgorithmIdentifier;
+}
+
+interface JsonWebKey {
+  alg?: string;
+  crv?: string;
+  d?: string;
+  dp?: string;
+  dq?: string;
+  e?: string;
+  ext?: boolean;
+  k?: string;
+  key_ops?: string[];
+  kty?: string;
+  n?: string;
+  oth?: RsaOtherPrimesInfo[];
+  p?: string;
+  q?: string;
+  qi?: string;
+  use?: string;
+  x?: string;
+  y?: string;
+}
+
+interface HkdfParams extends Algorithm {
+  hash: HashAlgorithmIdentifier;
+  info: BufferSource;
+  salt: BufferSource;
+}
+
+interface HmacImportParams extends Algorithm {
+  hash: HashAlgorithmIdentifier;
+  length?: number;
+}
+
+interface HmacKeyAlgorithm extends KeyAlgorithm {
+  hash: KeyAlgorithm;
+  length: number;
+}
+
+interface HmacKeyGenParams extends Algorithm {
+  hash: HashAlgorithmIdentifier;
+  length?: number;
+}
+
+interface Pbkdf2Params extends Algorithm {
+  hash: HashAlgorithmIdentifier;
+  iterations: number;
+  salt: BufferSource;
+}
+
+interface RsaHashedImportParams extends Algorithm {
+  hash: HashAlgorithmIdentifier;
+}
+
+interface RsaHashedKeyAlgorithm extends RsaKeyAlgorithm {
+  hash: KeyAlgorithm;
+}
+
+interface RsaHashedKeyGenParams extends RsaKeyGenParams {
+  hash: HashAlgorithmIdentifier;
+}
+
+interface RsaKeyAlgorithm extends KeyAlgorithm {
+  modulusLength: number;
+  publicExponent: BigInteger;
+}
+
+interface RsaKeyGenParams extends Algorithm {
+  modulusLength: number;
+  publicExponent: BigInteger;
+}
+
+interface RsaOaepParams extends Algorithm {
+  label?: BufferSource;
+}
+
+interface RsaOtherPrimesInfo {
+  d?: string;
+  r?: string;
+  t?: string;
+}
+
+interface CryptoKeyPair {
+  privateKey: CryptoKey;
+  publicKey: CryptoKey;
+}
+
+type AlgorithmIdentifier = Algorithm | string;
+
+/**
+ * This Web Crypto API interface provides a number of low-level cryptographic functions. It is accessed via the Crypto.subtle properties available in a window context (via Window.crypto).
+ */
+interface SubtleCrypto {
+  decrypt(
+    algorithm:
+      | AlgorithmIdentifier
+      | RsaOaepParams
+      | AesCtrParams
+      | AesCbcParams
+      | AesGcmParams,
+    key: CryptoKey,
+    data: BufferSource
+  ): Promise<ArrayBuffer>;
+  deriveBits(
+    algorithm:
+      | AlgorithmIdentifier
+      | EcdhKeyDeriveParams
+      | HkdfParams
+      | Pbkdf2Params,
+    baseKey: CryptoKey,
+    length: number
+  ): Promise<ArrayBuffer>;
+  deriveKey(
+    algorithm:
+      | AlgorithmIdentifier
+      | EcdhKeyDeriveParams
+      | HkdfParams
+      | Pbkdf2Params,
+    baseKey: CryptoKey,
+    derivedKeyType:
+      | AlgorithmIdentifier
+      | AesDerivedKeyParams
+      | HmacImportParams
+      | HkdfParams
+      | Pbkdf2Params,
+    extractable: boolean,
+    keyUsages: KeyUsage[]
+  ): Promise<CryptoKey>;
+  digest(
+    algorithm: AlgorithmIdentifier,
+    data: BufferSource
+  ): Promise<ArrayBuffer>;
+  encrypt(
+    algorithm:
+      | AlgorithmIdentifier
+      | RsaOaepParams
+      | AesCtrParams
+      | AesCbcParams
+      | AesGcmParams,
+    key: CryptoKey,
+    data: BufferSource
+  ): Promise<ArrayBuffer>;
+  exportKey(format: "jwk", key: CryptoKey): Promise<JsonWebKey>;
+  exportKey(
+    format: Exclude<KeyFormat, "jwk">,
+    key: CryptoKey
+  ): Promise<ArrayBuffer>;
+  generateKey(
+    algorithm: RsaHashedKeyGenParams | EcKeyGenParams,
+    extractable: boolean,
+    keyUsages: ReadonlyArray<KeyUsage>
+  ): Promise<CryptoKeyPair>;
+  generateKey(
+    algorithm: AesKeyGenParams | HmacKeyGenParams | Pbkdf2Params,
+    extractable: boolean,
+    keyUsages: ReadonlyArray<KeyUsage>
+  ): Promise<CryptoKey>;
+  generateKey(
+    algorithm: AlgorithmIdentifier,
+    extractable: boolean,
+    keyUsages: KeyUsage[]
+  ): Promise<CryptoKeyPair | CryptoKey>;
+  importKey(
+    format: "jwk",
+    keyData: JsonWebKey,
+    algorithm:
+      | AlgorithmIdentifier
+      | RsaHashedImportParams
+      | EcKeyImportParams
+      | HmacImportParams
+      | AesKeyAlgorithm,
+    extractable: boolean,
+    keyUsages: ReadonlyArray<KeyUsage>
+  ): Promise<CryptoKey>;
+  importKey(
+    format: Exclude<KeyFormat, "jwk">,
+    keyData: BufferSource,
+    algorithm:
+      | AlgorithmIdentifier
+      | RsaHashedImportParams
+      | EcKeyImportParams
+      | HmacImportParams
+      | AesKeyAlgorithm,
+    extractable: boolean,
+    keyUsages: KeyUsage[]
+  ): Promise<CryptoKey>;
+  sign(
+    algorithm: AlgorithmIdentifier | RsaPssParams | EcdsaParams,
+    key: CryptoKey,
+    data: BufferSource
+  ): Promise<ArrayBuffer>;
+  unwrapKey(
+    format: KeyFormat,
+    wrappedKey: BufferSource,
+    unwrappingKey: CryptoKey,
+    unwrapAlgorithm:
+      | AlgorithmIdentifier
+      | RsaOaepParams
+      | AesCtrParams
+      | AesCbcParams
+      | AesGcmParams,
+    unwrappedKeyAlgorithm:
+      | AlgorithmIdentifier
+      | RsaHashedImportParams
+      | EcKeyImportParams
+      | HmacImportParams
+      | AesKeyAlgorithm,
+    extractable: boolean,
+    keyUsages: KeyUsage[]
+  ): Promise<CryptoKey>;
+  verify(
+    algorithm: AlgorithmIdentifier | RsaPssParams | EcdsaParams,
+    key: CryptoKey,
+    signature: BufferSource,
+    data: BufferSource
+  ): Promise<boolean>;
+  wrapKey(
+    format: KeyFormat,
+    key: CryptoKey,
+    wrappingKey: CryptoKey,
+    wrapAlgorithm:
+      | AlgorithmIdentifier
+      | RsaOaepParams
+      | AesCtrParams
+      | AesCbcParams
+      | AesGcmParams
+  ): Promise<ArrayBuffer>;
+}
+
+interface RsaPssParams extends Algorithm {
+  saltLength: number;
+}
+
+/**
+ * The CryptoKey dictionary of the Web Crypto API represents a cryptographic key.
+ */
+interface CryptoKey {
+  readonly algorithm: KeyAlgorithm;
+  readonly extractable: boolean;
+  readonly type: KeyType;
+  readonly usages: KeyUsage[];
+}
+
+declare var CryptoKey: {
+  prototype: CryptoKey;
+  new (): CryptoKey;
+};
 
 
 // ./string_decoder.d.ts
@@ -11710,6 +12034,9 @@ declare module "stream" {
       read?(this: Readable, size: number): void;
     }
     class Readable<R = any> extends Stream implements ReadableStream {
+      // TODO: improve type later
+      values: any;
+
       readonly locked: boolean;
       cancel(reason?: any): Promise<void>;
       getReader(): ReadableStreamDefaultReader<R>;
@@ -13453,6 +13780,17 @@ declare module "bun" {
    */
   export function pathToFileURL(path: string): URL;
 
+  export interface Peek {
+    <T = undefined>(promise: T | Promise<T>): Promise<T> | T;
+    status<T = undefined>(
+      promise: T | Promise<T>
+    ): "pending" | "fulfilled" | "rejected";
+  }
+  /**
+   * Extract the value from the Promise in the same tick of the event loop
+   */
+  export const peek: Peek;
+
   /**
    * Convert a {@link URL} to a filesystem path.
    * @param url The URL to convert.
@@ -13822,7 +14160,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?: boolean
+    ): 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 +14692,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 {
@@ -13904,19 +14772,7 @@ declare module "bun" {
     syscall?: string;
   }
 
-  export interface SSLAdvancedOptions {
-    passphrase?: string;
-    caFile?: string;
-    dhParamsFile?: string;
-
-    /**
-     * This sets `OPENSSL_RELEASE_BUFFERS` to 1.
-     * It reduces overall performance but saves some memory.
-     * @default false
-     */
-    lowMemoryMode?: boolean;
-  }
-  interface SSLOptions {
+  interface TLSOptions {
     /**
      * File path to a TLS key
      *
@@ -13929,16 +14785,29 @@ declare module "bun" {
      * To enable TLS, this option is required.
      */
     certFile: string;
+
+    passphrase?: string;
+    caFile?: string;
+    dhParamsFile?: string;
+
+    /**
+     * This sets `OPENSSL_RELEASE_BUFFERS` to 1.
+     * It reduces overall performance but saves some memory.
+     * @default false
+     */
+    lowMemoryMode?: boolean;
   }
 
-  export type SSLServeOptions = ServeOptions &
-    SSLOptions &
-    SSLAdvancedOptions & {
+  export type TLSServeOptions<WebSocketDataType = undefined> = (
+    | WebSocketServeOptions<WebSocketDataType>
+    | ServerWebSocket
+  ) &
+    TLSOptions & {
       /**
        *  The keys are [SNI](https://en.wikipedia.org/wiki/Server_Name_Indication) hostnames.
        *  The values are SSL options objects.
        */
-      serverNames: Record<string, SSLOptions & SSLAdvancedOptions>;
+      serverNames: Record<string, TLSOptions>;
     };
 
   /**
@@ -13946,10 +14815,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 +14822,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 +14869,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 +14951,10 @@ declare module "bun" {
     readonly development: boolean;
   }
 
-  export type Serve = SSLServeOptions | ServeOptions;
+  export type Serve<WebSocketDataType = undefined> =
+    | TLSServeOptions<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.
@@ -14798,7 +15723,180 @@ declare module "bun" {
 
   var plugin: BunPlugin;
 
-  declare namespace SpawnOptions {
+  interface Socket<Data = undefined> {
+    /**
+     * Write `data` to the socket
+     *
+     * @param data The data to write to the socket
+     * @param byteOffset The offset in the buffer to start writing from (defaults to 0)
+     * @param byteLength The number of bytes to write (defaults to the length of the buffer)
+     *
+     * When passed a string, `byteOffset` and `byteLength` refer to the UTF-8 offset, not the string character offset.
+     *
+     * This is unbuffered as of Bun v0.2.2. That means individual write() calls
+     * will be slow. In the future, Bun will buffer writes and flush them at the
+     * end of the tick, when the event loop is idle, or sooner if the buffer is full.
+     */
+    write(
+      data: string | BufferSource,
+      byteOffset?: number,
+      byteLength?: number
+    ): number;
+
+    /**
+     * The data context for the socket.
+     */
+    data: Data;
+
+    /**
+     * Like {@link Socket.write} except it includes a TCP FIN packet
+     *
+     * Use it to send your last message and close the connection.
+     */
+    end(
+      data?: string | BufferSource,
+      byteOffset?: number,
+      byteLength?: number
+    ): number;
+
+    /**
+     * Close the socket immediately
+     */
+    end(): void;
+
+    /**
+     * Keep Bun's process alive at least until this socket is closed
+     *
+     * After the socket has closed, the socket is unref'd, the process may exit,
+     * and this becomes a no-op
+     */
+    ref(): void;
+
+    /**
+     * Set a timeout until the socket automatically closes.
+     *
+     * To reset the timeout, call this function again.
+     *
+     * When a timeout happens, the `timeout` callback is called and the socket is closed.
+     */
+    timeout(seconds: number): void;
+
+    /**
+     * Shutdown writes to a socket
+     *
+     * This makes the socket a half-closed socket. It can still receive data.
+     *
+     * This calls [shutdown(2)](https://man7.org/linux/man-pages/man2/shutdown.2.html) internally
+     */
+    shutdown(halfClose?: boolean): void;
+
+    readonly readyState: "open" | "closing" | "closed";
+
+    /**
+     * Allow Bun's process to exit even if this socket is still open
+     *
+     * After the socket has closed, this function does nothing.
+     */
+    unref(): void;
+
+    /**
+     * Reset the socket's callbacks. This is useful with `bun --hot` to facilitate hot reloading.
+     *
+     * This will apply to all sockets from the same {@link Listener}. it is per socket only for {@link Bun.connect}.
+     */
+    reload(handler: SocketHandler): void;
+
+    /**
+     * Get the server that created this socket
+     *
+     * This will return undefined if the socket was created by {@link Bun.connect} or if the listener has already closed.
+     */
+    readonly listener?: SocketListener;
+  }
+
+  interface SocketListener<Options extends SocketOptions = SocketOptions> {
+    stop(): void;
+    ref(): void;
+    unref(): void;
+    reload(options: Pick<Partial<Options>, "socket">): void;
+    data: Options["data"];
+  }
+  interface TCPSocketListener<Options extends TCPSocketOptions<unknown>>
+    extends SocketListener<Options> {
+    readonly port: number;
+    readonly hostname: string;
+  }
+  interface UnixSocketListener<Options extends UnixSocketOptions<unknown>>
+    extends SocketListener<Options> {
+    readonly unix: string;
+  }
+
+  interface TCPSocket extends Socket {}
+  interface TLSSocket extends Socket {}
+
+  interface SocketHandler<Data = unknown> {
+    open(socket: Socket<Data>): void | Promise<void>;
+    close?(socket: Socket<Data>): void | Promise<void>;
+    error?(socket: Socket<Data>, error: Error): void | Promise<void>;
+    data?(socket: Socket<Data>, data: BufferSource): void | Promise<void>;
+    drain?(socket: Socket<Data>): void | Promise<void>;
+  }
+
+  interface SocketOptions<Data = unknown> {
+    socket: SocketHandler<Data>;
+    tls?: TLSOptions;
+    data: Data;
+  }
+  interface TCPSocketOptions<Data = undefined> extends SocketOptions<Data> {
+    hostname: string;
+    port: number;
+  }
+
+  interface UnixSocketOptions<Data = undefined> extends SocketOptions<Data> {
+    unix: string;
+  }
+
+  /**
+   *
+   * Create a TCP client that connects to a server
+   *
+   * @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
+   *
+   */
+  export function connect<Data = undefined>(
+    options: TCPSocketOptions<Data>
+  ): Promise<TCPSocketListener<typeof options>>;
+  export function connect<Data = undefined>(
+    options: UnixSocketOptions<Data>
+  ): Promise<UnixSocketListener<typeof options>>;
+
+  /**
+   *
+   * 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
+   *
+   */
+  export function listen<Data = undefined>(
+    options: TCPSocketOptions<Data>
+  ): TCPSocketListener<typeof options>;
+  export function listen<Data = undefined>(
+    options: UnixSocketOptions<Data>
+  ): UnixSocketListener<typeof options>;
+
+  namespace SpawnOptions {
     type Readable =
       | "inherit"
       | "pipe"