bun-types 1.1.42 → 1.1.43-canary.20250104T140550

package/bun.d.ts

@@ -539,7 +539,7 @@ declare module "bun" {
 	 */
 	// tslint:disable-next-line:unified-signatures
 	function write(
-		destination: BunFile | Bun.PathLike,
+		destination: BunFile | S3File | Bun.PathLike,
 		input: Blob | NodeJS.TypedArray | ArrayBufferLike | string | Bun.BlobPart[],
 		options?: {
 			/** If writing to a PathLike, set the permissions of the file. */
@@ -1234,8 +1234,840 @@ declare module "bun" {
 		 * For empty Blob, this always returns true.
 		 */
 		exists(): Promise<boolean>;
+
+		/**
+		 * Write data to the file. This is equivalent to using {@link Bun.write} with a {@link BunFile}.
+		 * @param data - The data to write.
+		 * @param options - The options to use for the write.
+		 */
+		write(
+			data:
+				| string
+				| ArrayBufferView
+				| ArrayBuffer
+				| SharedArrayBuffer
+				| Request
+				| Response
+				| BunFile,
+			options?: { highWaterMark?: number },
+		): Promise<number>;
+
+		/**
+		 * Deletes the file.
+		 */
+		unlink(): Promise<void>;
+	}
+	interface NetworkSink extends FileSink {
+		/**
+		 * Write a chunk of data to the network.
+		 *
+		 * If the network is not writable yet, the data is buffered.
+		 */
+		write(
+			chunk: string | ArrayBufferView | ArrayBuffer | SharedArrayBuffer,
+		): number;
+		/**
+		 * Flush the internal buffer, committing the data to the network.
+		 */
+		flush(): number | Promise<number>;
+		/**
+		 * Finish the upload. This also flushes the internal buffer.
+		 */
+		end(error?: Error): number | Promise<number>;
+	}
+
+	type S3 = {
+		/**
+		 * Create a new instance of an S3 bucket so that credentials can be managed
+		 * from a single instance instead of being passed to every method.
+		 *
+		 * @param options The default options to use for the S3 client. Can be
+		 * overriden by passing options to the methods.
+		 *
+		 * ## Keep S3 credentials in a single instance
+		 *
+		 * @example
+		 *     const bucket = new Bun.S3({
+		 *       accessKeyId: "your-access-key",
+		 *       secretAccessKey: "your-secret-key",
+		 *       bucket: "my-bucket",
+		 *       endpoint: "https://s3.us-east-1.amazonaws.com",
+		 *       sessionToken: "your-session-token",
+		 *     });
+		 *
+		 *     // S3Bucket is callable, so you can do this:
+		 *     const file = bucket("my-file.txt");
+		 *
+		 *     // or this:
+		 *     await file.write("Hello Bun!");
+		 *     await file.text();
+		 *
+		 *     // To delete the file:
+		 *     await bucket.delete("my-file.txt");
+		 *
+		 *     // To write a file without returning the instance:
+		 *     await bucket.write("my-file.txt", "Hello Bun!");
+		 *
+		 */
+		new (options?: S3Options): S3Bucket;
+
+		/**
+		 * Delete a file from an S3-compatible object storage service.
+		 *
+		 * @param path The path to the file.
+		 * @param options The options to use for the S3 client.
+		 *
+		 * For an instance method version, {@link S3File.unlink}. You can also use {@link S3Bucket.unlink}.
+		 *
+		 * @example
+		 *     import { S3 } from "bun";
+		 *     await S3.unlink("s3://my-bucket/my-file.txt", {
+		 *       accessKeyId: "your-access-key",
+		 *       secretAccessKey: "your-secret-key",
+		 *     });
+		 *
+		 * @example
+		 *     await S3.unlink("key", {
+		 *       bucket: "my-bucket",
+		 *       accessKeyId: "your-access-key",
+		 *       secretAccessKey: "your-secret-key",
+		 *     });
+		 */
+		delete(path: string, options?: S3Options): Promise<void>;
+		/**
+		 * unlink is an alias for {@link S3.delete}
+		 */
+		unlink: S3["delete"];
+
+		/**
+		 * Writes data to an S3-compatible storage service.
+		 * Supports various input types and handles large files with multipart uploads.
+		 *
+		 * @param path The path or key where the file will be written
+		 * @param data The data to write
+		 * @param options S3 configuration and upload options
+		 * @returns promise that resolves with the number of bytes written
+		 *
+		 * @example
+		 *   // Writing a string
+		 *   await S3.write("hello.txt", "Hello World!", {
+		 *     bucket: "my-bucket",
+		 *     type: "text/plain"
+		 *   });
+		 *
+		 * @example
+		 *   // Writing JSON
+		 *   await S3.write(
+		 *     "data.json",
+		 *     JSON.stringify({ hello: "world" }),
+		 *     { type: "application/json" }
+		 *   );
+		 *
+		 * @example
+		 *   // Writing a large file with multipart upload
+		 *   await S3.write("large-file.dat", largeBuffer, {
+		 *     partSize: 10 * 1024 * 1024, // 10MB parts
+		 *     queueSize: 4, // Upload 4 parts in parallel
+		 *     retry: 3 // Retry failed parts up to 3 times
+		 *   });
+		 */
+		write(
+			path: string,
+			data:
+				| string
+				| ArrayBufferView
+				| ArrayBufferLike
+				| Response
+				| Request
+				| ReadableStream
+				| Blob
+				| File,
+			options?: S3Options,
+		): Promise<number>;
+	};
+	var S3: S3;
+
+	/**
+	 * Creates a new S3File instance for working with a single file.
+	 *
+	 * @param path The path or key of the file
+	 * @param options S3 configuration options
+	 * @returns `S3File` instance for the specified path
+	 *
+	 * @example
+	 *    import { s3 } from "bun";
+	 *    const file = s3("my-file.txt", {
+	 *      bucket: "my-bucket",
+	 *      accessKeyId: "your-access-key",
+	 *      secretAccessKey: "your-secret-key"
+	 *    });
+	 *
+	 *    // Read the file
+	 *    const content = await file.text();
+	 *
+	 * @example
+	 *    // Using s3:// protocol
+	 *    const file = s3("s3://my-bucket/my-file.txt", {
+	 *      accessKeyId: "your-access-key",
+	 *      secretAccessKey: "your-secret-key"
+	 *    });
+	 */
+	function s3(path: string | URL, options?: S3Options): S3File;
+
+	/**
+	 * Configuration options for S3 operations
+	 */
+	interface S3Options extends BlobPropertyBag {
+		/**
+		 * The Access Control List (ACL) policy for the file.
+		 * Controls who can access the file and what permissions they have.
+		 *
+		 * @example
+		 *     // Setting public read access
+		 *     const file = s3("public-file.txt", {
+		 *       acl: "public-read",
+		 *       bucket: "my-bucket"
+		 *     });
+		 *
+		 * @example
+		 *     // Using with presigned URLs
+		 *     const url = file.presign({
+		 *       acl: "public-read",
+		 *       expiresIn: 3600
+		 *     });
+		 */
+		acl?:
+			| "private"
+			| "public-read"
+			| "public-read-write"
+			| "aws-exec-read"
+			| "authenticated-read"
+			| "bucket-owner-read"
+			| "bucket-owner-full-control"
+			| "log-delivery-write";
+
+		/**
+		 * The S3 bucket name. Can be set via `S3_BUCKET` or `AWS_BUCKET` environment variables.
+		 *
+		 * @example
+		 *     // Using explicit bucket
+		 *     const file = s3("my-file.txt", { bucket: "my-bucket" });
+		 *
+		 * @example
+		 *     // Using environment variables
+		 *     // With S3_BUCKET=my-bucket in .env
+		 *     const file = s3("my-file.txt");
+		 */
+		bucket?: string;
+
+		/**
+		 * The AWS region. Can be set via `S3_REGION` or `AWS_REGION` environment variables.
+		 *
+		 * @example
+		 *     const file = s3("my-file.txt", {
+		 *       bucket: "my-bucket",
+		 *       region: "us-west-2"
+		 *     });
+		 */
+		region?: string;
+
+		/**
+		 * The access key ID for authentication.
+		 * Can be set via `S3_ACCESS_KEY_ID` or `AWS_ACCESS_KEY_ID` environment variables.
+		 */
+		accessKeyId?: string;
+
+		/**
+		 * The secret access key for authentication.
+		 * Can be set via `S3_SECRET_ACCESS_KEY` or `AWS_SECRET_ACCESS_KEY` environment variables.
+		 */
+		secretAccessKey?: string;
+
+		/**
+		 * Optional session token for temporary credentials.
+		 * Can be set via `S3_SESSION_TOKEN` or `AWS_SESSION_TOKEN` environment variables.
+		 *
+		 * @example
+		 *     // Using temporary credentials
+		 *     const file = s3("my-file.txt", {
+		 *       accessKeyId: tempAccessKey,
+		 *       secretAccessKey: tempSecretKey,
+		 *       sessionToken: tempSessionToken
+		 *     });
+		 */
+		sessionToken?: string;
+
+		/**
+		 * The S3-compatible service endpoint URL.
+		 * Can be set via `S3_ENDPOINT` or `AWS_ENDPOINT` environment variables.
+		 *
+		 * @example
+		 *     // AWS S3
+		 *     const file = s3("my-file.txt", {
+		 *       endpoint: "https://s3.us-east-1.amazonaws.com"
+		 *     });
+		 *
+		 * @example
+		 *     // Cloudflare R2
+		 *     const file = s3("my-file.txt", {
+		 *       endpoint: "https://<account-id>.r2.cloudflarestorage.com"
+		 *     });
+		 *
+		 * @example
+		 *     // DigitalOcean Spaces
+		 *     const file = s3("my-file.txt", {
+		 *       endpoint: "https://<region>.digitaloceanspaces.com"
+		 *     });
+		 *
+		 * @example
+		 *     // MinIO (local development)
+		 *     const file = s3("my-file.txt", {
+		 *       endpoint: "http://localhost:9000"
+		 *     });
+		 */
+		endpoint?: string;
+
+		/**
+		 * The size of each part in multipart uploads (in MiB).
+		 * - Minimum: 5 MiB
+		 * - Maximum: 5120 MiB
+		 * - Default: 5 MiB
+		 *
+		 * @example
+		 *     // Configuring multipart uploads
+		 *     const file = s3("large-file.dat", {
+		 *       partSize: 10, // 10 MiB parts
+		 *       queueSize: 4  // Upload 4 parts in parallel
+		 *     });
+		 *
+		 *     const writer = file.writer();
+		 *     // ... write large file in chunks
+		 */
+		partSize?: number;
+
+		/**
+		 * Number of parts to upload in parallel for multipart uploads.
+		 * - Default: 5
+		 * - Maximum: 255
+		 *
+		 * Increasing this value can improve upload speeds for large files
+		 * but will use more memory.
+		 */
+		queueSize?: number;
+
+		/**
+		 * Number of retry attempts for failed uploads.
+		 * - Default: 3
+		 * - Maximum: 255
+		 *
+		 * @example
+		 *    // Setting retry attempts
+		 *     const file = s3("my-file.txt", {
+		 *       retry: 5 // Retry failed uploads up to 5 times
+		 *     });
+		 */
+		retry?: number;
+
+		/**
+		 * The Content-Type of the file.
+		 * Automatically set based on file extension when possible.
+		 *
+		 * @example
+		 *    // Setting explicit content type
+		 *     const file = s3("data.bin", {
+		 *       type: "application/octet-stream"
+		 *     });
+		 */
+		type?: string;
+
+		/**
+		 * @deprecated The size of the internal buffer in bytes. Defaults to 5 MiB. use `partSize` and `queueSize` instead.
+		 */
+		highWaterMark?: number;
+	}
+
+	/**
+	 * Options for generating presigned URLs
+	 */
+	interface S3FilePresignOptions extends S3Options {
+		/**
+		 * Number of seconds until the presigned URL expires.
+		 * - Default: 86400 (1 day)
+		 *
+		 * @example
+		 *     // Short-lived URL
+		 *     const url = file.presign({
+		 *       expiresIn: 3600 // 1 hour
+		 *     });
+		 *
+		 * @example
+		 *     // Long-lived public URL
+		 *     const url = file.presign({
+		 *       expiresIn: 7 * 24 * 60 * 60, // 7 days
+		 *       acl: "public-read"
+		 *     });
+		 */
+		expiresIn?: number;
+
+		/**
+		 * The HTTP method allowed for the presigned URL.
+		 *
+		 * @example
+		 *     // GET URL for downloads
+		 *     const downloadUrl = file.presign({
+		 *       method: "GET",
+		 *       expiresIn: 3600
+		 *     });
+		 *
+		 * @example
+		 *     // PUT URL for uploads
+		 *     const uploadUrl = file.presign({
+		 *       method: "PUT",
+		 *       expiresIn: 3600,
+		 *       type: "application/json"
+		 *     });
+		 */
+		method?: "GET" | "POST" | "PUT" | "DELETE" | "HEAD";
+	}
+
+	/**
+	 * Represents a file in an S3-compatible storage service.
+	 * Extends the Blob interface for compatibility with web APIs.
+	 */
+	interface S3File extends Blob {
+		/**
+		 * The size of the file in bytes.
+		 * This is a Promise because it requires a network request to determine the size.
+		 *
+		 * @example
+		 *     // Getting file size
+		 *     const size = await file.size;
+		 *     console.log(`File size: ${size} bytes`);
+		 *
+		 * @example
+		 *     // Check if file is larger than 1MB
+		 *     if (await file.size > 1024 * 1024) {
+		 *       console.log("Large file detected");
+		 *     }
+		 */
+		/**
+		 * TODO: figure out how to get the typescript types to not error for this property.
+		 */
+		// size: Promise<number>;
+
+		/**
+		 * Creates a new S3File representing a slice of the original file.
+		 * Uses HTTP Range headers for efficient partial downloads.
+		 *
+		 * @param begin - Starting byte offset
+		 * @param end - Ending byte offset (exclusive)
+		 * @param contentType - Optional MIME type for the slice
+		 * @returns A new S3File representing the specified range
+		 *
+		 * @example
+		 *  // Reading file header
+		 *     const header = file.slice(0, 1024);
+		 *     const headerText = await header.text();
+		 *
+		 * @example
+		 *     // Reading with content type
+		 *     const jsonSlice = file.slice(1024, 2048, "application/json");
+		 *     const data = await jsonSlice.json();
+		 *
+		 * @example
+		 *     // Reading from offset to end
+		 *     const remainder = file.slice(1024);
+		 *     const content = await remainder.text();
+		 */
+		slice(begin?: number, end?: number, contentType?: string): S3File;
+		slice(begin?: number, contentType?: string): S3File;
+		slice(contentType?: string): S3File;
+
+		/**
+		 * Creates a writable stream for uploading data.
+		 * Suitable for large files as it uses multipart upload.
+		 *
+		 * @param options - Configuration for the upload
+		 * @returns A NetworkSink for writing data
+		 *
+		 * @example
+		 *     // Basic streaming write
+		 *     const writer = file.writer({
+		 *       type: "application/json"
+		 *     });
+		 *     writer.write('{"hello": ');
+		 *     writer.write('"world"}');
+		 *     await writer.end();
+		 *
+		 * @example
+		 *     // Optimized large file upload
+		 *     const writer = file.writer({
+		 *       partSize: 10 * 1024 * 1024, // 10MB parts
+		 *       queueSize: 4, // Upload 4 parts in parallel
+		 *       retry: 3 // Retry failed parts
+		 *     });
+		 *
+		 *     // Write large chunks of data efficiently
+		 *     for (const chunk of largeDataChunks) {
+		 *       await writer.write(chunk);
+		 *     }
+		 *     await writer.end();
+		 *
+		 * @example
+		 *     // Error handling
+		 *     const writer = file.writer();
+		 *     try {
+		 *       await writer.write(data);
+		 *       await writer.end();
+		 *     } catch (err) {
+		 *       console.error('Upload failed:', err);
+		 *       // Writer will automatically abort multipart upload on error
+		 *     }
+		 */
+		writer(options?: S3Options): NetworkSink;
+
+		/**
+		 * Gets a readable stream of the file's content.
+		 * Useful for processing large files without loading them entirely into memory.
+		 *
+		 * @returns A ReadableStream for the file content
+		 *
+		 * @example
+		 *     // Basic streaming read
+		 *     const stream = file.stream();
+		 *     for await (const chunk of stream) {
+		 *       console.log('Received chunk:', chunk);
+		 *     }
+		 *
+		 * @example
+		 *     // Piping to response
+		 *     const stream = file.stream();
+		 *     return new Response(stream, {
+		 *       headers: { 'Content-Type': file.type }
+		 *     });
+		 *
+		 * @example
+		 *     // Processing large files
+		 *     const stream = file.stream();
+		 *     const textDecoder = new TextDecoder();
+		 *     for await (const chunk of stream) {
+		 *       const text = textDecoder.decode(chunk);
+		 *       // Process text chunk by chunk
+		 *     }
+		 */
+		readonly readable: ReadableStream;
+		stream(): ReadableStream;
+
+		/**
+		 * The name or path of the file in the bucket.
+		 *
+		 * @example
+		 * const file = s3("folder/image.jpg");
+		 * console.log(file.name); // "folder/image.jpg"
+		 */
+		readonly name?: string;
+
+		/**
+		 * The bucket name containing the file.
+		 *
+		 * @example
+		 *    const file = s3("s3://my-bucket/file.txt");
+		 *    console.log(file.bucket); // "my-bucket"
+		 */
+		readonly bucket?: string;
+
+		/**
+		 * Checks if the file exists in S3.
+		 * Uses HTTP HEAD request to efficiently check existence without downloading.
+		 *
+		 * @returns Promise resolving to true if file exists, false otherwise
+		 *
+		 * @example
+		 *     // Basic existence check
+		 *    if (await file.exists()) {
+		 *      console.log("File exists in S3");
+		 *    }
+		 *
+		 * @example
+		 *  // With error handling
+		 *  try {
+		 *    const exists = await file.exists();
+		 *    if (!exists) {
+		 *      console.log("File not found");
+		 *    }
+		 *  } catch (err) {
+		 *    console.error("Error checking file:", err);
+		 *  }
+		 */
+		exists(): Promise<boolean>;
+
+		/**
+		 * Uploads data to S3.
+		 * Supports various input types and automatically handles large files.
+		 *
+		 * @param data - The data to upload
+		 * @param options - Upload configuration options
+		 * @returns Promise resolving to number of bytes written
+		 *
+		 * @example
+		 *     // Writing string data
+		 *     await file.write("Hello World", {
+		 *       type: "text/plain"
+		 *     });
+		 *
+		 * @example
+		 *     // Writing JSON
+		 *     const data = { hello: "world" };
+		 *     await file.write(JSON.stringify(data), {
+		 *       type: "application/json"
+		 *     });
+		 *
+		 * @example
+		 *     // Writing from Response
+		 *     const response = await fetch("https://example.com/data");
+		 *     await file.write(response);
+		 *
+		 * @example
+		 *     // Writing with ACL
+		 *     await file.write(data, {
+		 *       acl: "public-read",
+		 *       type: "application/octet-stream"
+		 *     });
+		 */
+		write(
+			data:
+				| string
+				| ArrayBufferView
+				| ArrayBuffer
+				| SharedArrayBuffer
+				| Request
+				| Response
+				| BunFile
+				| S3File
+				| Blob,
+			options?: S3Options,
+		): Promise<number>;
+
+		/**
+		 * Generates a presigned URL for the file.
+		 * Allows temporary access to the file without exposing credentials.
+		 *
+		 * @param options - Configuration for the presigned URL
+		 * @returns Presigned URL string
+		 *
+		 * @example
+		 *     // Basic download URL
+		 *     const url = file.presign({
+		 *       expiresIn: 3600 // 1 hour
+		 *     });
+		 *
+		 * @example
+		 *     // Upload URL with specific content type
+		 *     const uploadUrl = file.presign({
+		 *       method: "PUT",
+		 *       expiresIn: 3600,
+		 *       type: "image/jpeg",
+		 *       acl: "public-read"
+		 *     });
+		 *
+		 * @example
+		 *     // URL with custom permissions
+		 *     const url = file.presign({
+		 *       method: "GET",
+		 *       expiresIn: 7 * 24 * 60 * 60, // 7 days
+		 *       acl: "public-read"
+		 *     });
+		 */
+		presign(options?: S3FilePresignOptions): string;
+
+		/**
+		 * Deletes the file from S3.
+		 *
+		 * @returns Promise that resolves when deletion is complete
+		 *
+		 * @example
+		 *     // Basic deletion
+		 *     await file.delete();
+		 *
+		 * @example
+		 *     // With error handling
+		 *     try {
+		 *       await file.delete();
+		 *       console.log("File deleted successfully");
+		 *     } catch (err) {
+		 *       console.error("Failed to delete file:", err);
+		 *     }
+		 */
+		delete(): Promise<void>;
+
+		/**
+		 * Alias for delete() method.
+		 * Provided for compatibility with Node.js fs API naming.
+		 *
+		 * @example
+		 * await file.unlink();
+		 */
+		unlink: S3File["delete"];
 	}
 
+	/**
+	 * A configured S3 bucket instance for managing files.
+	 * The instance is callable to create S3File instances and provides methods
+	 * for common operations.
+	 *
+	 * @example
+	 *     // Basic bucket setup
+	 *     const bucket = new S3({
+	 *       bucket: "my-bucket",
+	 *       accessKeyId: "key",
+	 *       secretAccessKey: "secret"
+	 *     });
+	 *
+	 *     // Get file instance
+	 *     const file = bucket("image.jpg");
+	 *
+	 *     // Common operations
+	 *     await bucket.write("data.json", JSON.stringify({hello: "world"}));
+	 *     const url = bucket.presign("file.pdf");
+	 *     await bucket.unlink("old.txt");
+	 */
+	type S3Bucket = {
+		/**
+		 * Creates an S3File instance for the given path.
+		 *
+		 * @example
+		 * const file = bucket("image.jpg");
+		 * await file.write(imageData);
+		 * const configFile = bucket("config.json", {
+		 *   type: "application/json",
+		 *   acl: "private"
+		 * });
+		 */
+		(path: string, options?: S3Options): S3File;
+
+		/**
+		 * Writes data directly to a path in the bucket.
+		 * Supports strings, buffers, streams, and web API types.
+		 *
+		 * @example
+		 *     // Write string
+		 *     await bucket.write("hello.txt", "Hello World");
+		 *
+		 *     // Write JSON with type
+		 *     await bucket.write(
+		 *       "data.json",
+		 *       JSON.stringify({hello: "world"}),
+		 *       {type: "application/json"}
+		 *     );
+		 *
+		 *     // Write from fetch
+		 *     const res = await fetch("https://example.com/data");
+		 *     await bucket.write("data.bin", res);
+		 *
+		 *     // Write with ACL
+		 *     await bucket.write("public.html", html, {
+		 *       acl: "public-read",
+		 *       type: "text/html"
+		 *     });
+		 */
+		write(
+			path: string,
+			data:
+				| string
+				| ArrayBufferView
+				| ArrayBuffer
+				| SharedArrayBuffer
+				| Request
+				| Response
+				| BunFile
+				| S3File
+				| Blob
+				| File,
+			options?: S3Options,
+		): Promise<number>;
+
+		/**
+		 * Generate a presigned URL for temporary access to a file.
+		 * Useful for generating upload/download URLs without exposing credentials.
+		 *
+		 * @example
+		 *     // Download URL
+		 *     const downloadUrl = bucket.presign("file.pdf", {
+		 *       expiresIn: 3600 // 1 hour
+		 *     });
+		 *
+		 *     // Upload URL
+		 *     const uploadUrl = bucket.presign("uploads/image.jpg", {
+		 *       method: "PUT",
+		 *       expiresIn: 3600,
+		 *       type: "image/jpeg",
+		 *       acl: "public-read"
+		 *     });
+		 *
+		 *     // Long-lived public URL
+		 *     const publicUrl = bucket.presign("public/doc.pdf", {
+		 *       expiresIn: 7 * 24 * 60 * 60, // 7 days
+		 *       acl: "public-read"
+		 *     });
+		 */
+		presign(path: string, options?: S3FilePresignOptions): string;
+
+		/**
+		 * Delete a file from the bucket.
+		 *
+		 * @example
+		 *     // Simple delete
+		 *     await bucket.unlink("old-file.txt");
+		 *
+		 *     // With error handling
+		 *     try {
+		 *       await bucket.unlink("file.dat");
+		 *       console.log("File deleted");
+		 *     } catch (err) {
+		 *       console.error("Delete failed:", err);
+		 *     }
+		 */
+		unlink(path: string, options?: S3Options): Promise<void>;
+
+		/**
+		 * Get the size of a file in bytes.
+		 * Uses HEAD request to efficiently get size.
+		 *
+		 * @example
+		 *     // Get size
+		 *     const bytes = await bucket.size("video.mp4");
+		 *     console.log(`Size: ${bytes} bytes`);
+		 *
+		 *     // Check if file is large
+		 *     if (await bucket.size("data.zip") > 100 * 1024 * 1024) {
+		 *       console.log("File is larger than 100MB");
+		 *     }
+		 */
+		size(path: string, options?: S3Options): Promise<number>;
+
+		/**
+		 * Check if a file exists in the bucket.
+		 * Uses HEAD request to check existence.
+		 *
+		 * @example
+		 *     // Check existence
+		 *     if (await bucket.exists("config.json")) {
+		 *       const file = bucket("config.json");
+		 *       const config = await file.json();
+		 *     }
+		 *
+		 *     // With error handling
+		 *     try {
+		 *       if (!await bucket.exists("required.txt")) {
+		 *         throw new Error("Required file missing");
+		 *       }
+		 *     } catch (err) {
+		 *       console.error("Check failed:", err);
+		 *     }
+		 */
+		exists(path: string, options?: S3Options): Promise<boolean>;
+	};
+
 	/**
 	 *   This lets you use macros as regular imports
 	 *   @example
@@ -1682,10 +2514,28 @@ declare module "bun" {
 		/**
 		 * **Experimental**
 		 *
-		 * Enable CSS support.
+		 * Bundle CSS files.
+		 *
+		 * This will be enabled by default in Bun v1.2.
+		 *
+		 * @default false (until Bunv 1.2)
 		 */
 		experimentalCss?: boolean;
 
+		/**
+		 * **Experimental**
+		 *
+		 * Bundle JavaScript & CSS files from HTML files. JavaScript & CSS files
+		 * from non-external <script> or <link> tags will be bundled.
+		 *
+		 * Underneath, this works similarly to HTMLRewriter.
+		 *
+		 * This will be enabled by default in Bun v1.2.
+		 *
+		 * @default false (until Bun v1.2)
+		 */
+		html?: boolean;
+
 		/**
 		 * Drop function calls to matching property accesses.
 		 */
@@ -3111,7 +3961,7 @@ declare module "bun" {
 	 *   "Hello, world!"
 	 * );
 	 * ```
-	 * @param path The path to the file (lazily loaded)
+	 * @param path The path to the file (lazily loaded) if the path starts with `s3://` it will behave like {@link S3File}
 	 */
 	// tslint:disable-next-line:unified-signatures
 	function file(path: string | URL, options?: BlobPropertyBag): BunFile;
@@ -3137,7 +3987,7 @@ declare module "bun" {
 	 * console.log(file.type); // "application/json"
 	 * ```
 	 *
-	 * @param path The path to the file as a byte buffer (the buffer is copied)
+	 * @param path The path to the file as a byte buffer (the buffer is copied) if the path starts with `s3://` it will behave like {@link S3File}
 	 */
 	// tslint:disable-next-line:unified-signatures
 	function file(
@@ -3483,9 +4333,24 @@ declare module "bun" {
 	function nanoseconds(): number;
 
 	/**
-	 * Generate a heap snapshot for seeing where the heap is being used
+	 * Show precise statistics about memory usage of your application
+	 *
+	 * Generate a heap snapshot in JavaScriptCore's format that can be viewed with `bun --inspect` or Safari's Web Inspector
+	 */
+	function generateHeapSnapshot(format?: "jsc"): HeapSnapshot;
+
+	/**
+	 * Show precise statistics about memory usage of your application
+	 *
+	 * Generate a V8 Heap Snapshot that can be used with Chrome DevTools & Visual Studio Code
+	 *
+	 * This is a JSON string that can be saved to a file.
+	 * ```ts
+	 * const snapshot = Bun.generateHeapSnapshot("v8");
+	 * await Bun.write("heap.heapsnapshot", snapshot);
+	 * ```
 	 */
-	function generateHeapSnapshot(): HeapSnapshot;
+	function generateHeapSnapshot(format: "v8"): string;
 
 	/**
 	 * The next time JavaScriptCore is idle, clear unused memory and attempt to reduce the heap size.
@@ -3979,7 +4844,8 @@ declare module "bun" {
 		| "napi"
 		| "wasm"
 		| "text"
-		| "css";
+		| "css"
+		| "html";
 
 	interface PluginConstraints {
 		/**