bun-types 1.1.43-canary.20250103T140555 → 1.1.43-canary.20250104T140550

package/bun.d.ts

@@ -1257,45 +1257,326 @@ declare module "bun" {
 		 */
 		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";
 
-	interface S3FileOptions extends BlobPropertyBag {
 		/**
-		 * The bucket to use for the S3 client. by default will use the `S3_BUCKET` and `AWS_BUCKET` environment variable, or deduce as first part of the path.
+		 * 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 region to use for the S3 client. By default, it will use the `S3_REGION` and `AWS_REGION` environment variable.
+		 * 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 to use for the S3 client. By default, it will use the `S3_ACCESS_KEY_ID` and `AWS_ACCESS_KEY_ID` environment variable.
+		 * 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 to use for the S3 client. By default, it will use the `S3_SECRET_ACCESS_KEY and `AWS_SECRET_ACCESS_KEY` environment variable.
+		 * The secret access key for authentication.
+		 * Can be set via `S3_SECRET_ACCESS_KEY` or `AWS_SECRET_ACCESS_KEY` environment variables.
 		 */
 		secretAccessKey?: string;
 
 		/**
-		 * The endpoint to use for the S3 client. Defaults to `https://s3.{region}.amazonaws.com`, it will also use the `S3_ENDPOINT` and `AWS_ENDPOINT`  environment variable.
+		 * 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 MiB. Minimum and Default is 5 MiB and maximum is 5120 MiB.
+		 * 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;
+
 		/**
-		 * The number of parts to upload in parallel. Default is 5 and maximum is 255. This can speed up the upload of large files but will also use more memory.
+		 * 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;
+
 		/**
-		 * The number of times to retry the upload if it fails. Default is 3 and maximum is 255.
+		 * 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. If not provided, it is automatically set based on the file extension when possible.
+		 * 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;
 
@@ -1305,93 +1586,253 @@ declare module "bun" {
 		highWaterMark?: number;
 	}
 
-	interface S3FilePresignOptions extends S3FileOptions {
+	/**
+	 * Options for generating presigned URLs
+	 */
+	interface S3FilePresignOptions extends S3Options {
 		/**
-		 * The number of seconds the presigned URL will be valid for. Defaults to 86400 (1 day).
+		 * 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 to use for the presigned URL. Defaults to GET.
+		 * 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?: string;
+		method?: "GET" | "POST" | "PUT" | "DELETE" | "HEAD";
 	}
 
-	interface S3File extends BunFile {
-		/**
-		 * @param path - The path to the file. If bucket options is not provided or set in the path, it will be deduced from the path.
-		 * @param options - The options to use for the S3 client.
-		 */
-		new (path: string | URL, options?: S3FileOptions): S3File;
+	/**
+	 * 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.
-		 */
-		size: Promise<number>;
-		/**
-		 * Offset any operation on the file starting at `begin` and ending at `end`. `end` is relative to 0
-		 *
-		 * Similar to [`TypedArray.subarray`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray/subarray). Does not copy the file, open the file, or modify the file.
+		 * This is a Promise because it requires a network request to determine the size.
 		 *
-		 * It will use [`range`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Range) to download only the bytes you need.
+		 * @example
+		 *     // Getting file size
+		 *     const size = await file.size;
+		 *     console.log(`File size: ${size} bytes`);
 		 *
-		 * @param begin - start offset in bytes
-		 * @param end - absolute offset in bytes (relative to 0)
-		 * @param contentType - MIME type for the new S3File
+		 * @example
+		 *     // Check if file is larger than 1MB
+		 *     if (await file.size > 1024 * 1024) {
+		 *       console.log("Large file detected");
+		 *     }
 		 */
-		slice(begin?: number, end?: number, contentType?: string): S3File;
+		/**
+		 * TODO: figure out how to get the typescript types to not error for this property.
+		 */
+		// size: Promise<number>;
 
-		/** */
 		/**
-		 * Offset any operation on the file starting at `begin`
+		 * Creates a new S3File representing a slice of the original file.
+		 * Uses HTTP Range headers for efficient partial downloads.
 		 *
-		 * Similar to [`TypedArray.subarray`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray/subarray). Does not copy the file, open the file, or modify the file.
+		 * @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
 		 *
-		 * It will use [`range`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Range) to download only the bytes you need.
+		 * @example
+		 *  // Reading file header
+		 *     const header = file.slice(0, 1024);
+		 *     const headerText = await header.text();
 		 *
-		 * @param begin - start offset in bytes
-		 * @param contentType - MIME type for the new S3File
+		 * @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;
-
-		/**
-		 * @param contentType - MIME type for the new S3File
-		 */
 		slice(contentType?: string): S3File;
 
 		/**
-		 * Incremental writer to stream writes to S3, this is equivalent of using MultipartUpload and is suitable for large files.
+		 * 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?: S3FileOptions): FileSink;
+		writer(options?: S3Options): NetworkSink;
 
 		/**
-		 * The readable stream of the file.
+		 * 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;
-
-		/**
-		 * Get a readable stream of the file.
-		 */
 		stream(): ReadableStream;
 
 		/**
-		 * The name or path of the file, as specified in the constructor.
+		 * 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 of the file.
+		 * The bucket name containing the file.
+		 *
+		 * @example
+		 *    const file = s3("s3://my-bucket/file.txt");
+		 *    console.log(file.bucket); // "my-bucket"
 		 */
 		readonly bucket?: string;
 
 		/**
-		 * Does the file exist?
-		 * It will use [`head`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/HEAD) to check if the file exists.
+		 * 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 the data to S3. This is equivalent of using {@link S3File.upload} with a {@link S3File}.
-		 * @param data - The data to write.
-		 * @param options - The options to use for the S3 client.
+		 * 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:
@@ -1404,29 +1845,133 @@ declare module "bun" {
 				| BunFile
 				| S3File
 				| Blob,
-			options?: S3FileOptions,
+			options?: S3Options,
 		): Promise<number>;
 
 		/**
-		 * Returns a presigned URL for the file.
-		 * @param options - The options to use for the presigned URL.
+		 * 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);
+		 *     }
 		 */
-		unlink(): Promise<void>;
+		delete(): Promise<void>;
+
+		/**
+		 * Alias for delete() method.
+		 * Provided for compatibility with Node.js fs API naming.
+		 *
+		 * @example
+		 * await file.unlink();
+		 */
+		unlink: S3File["delete"];
 	}
 
-	namespace S3File {
+	/**
+	 * 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 = {
 		/**
-		 * Uploads the data to S3.
-		 * @param data - The data to write.
-		 * @param options - The options to use for the S3 client.
+		 * 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"
+		 * });
 		 */
-		function upload(
-			path: string | S3File,
+		(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
@@ -1435,43 +1980,93 @@ declare module "bun" {
 				| Request
 				| Response
 				| BunFile
-				| S3File,
-			options?: S3FileOptions,
+				| S3File
+				| Blob
+				| File,
+			options?: S3Options,
 		): Promise<number>;
 
 		/**
-		 * Returns a presigned URL for the file.
-		 * @param options - The options to use for the presigned URL.
+		 * 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"
+		 *     });
 		 */
-		function presign(
-			path: string | S3File,
-			options?: S3FilePresignOptions,
-		): string;
+		presign(path: string, options?: S3FilePresignOptions): string;
 
 		/**
-		 * Deletes the file from S3.
+		 * 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);
+		 *     }
 		 */
-		function unlink(
-			path: string | S3File,
-			options?: S3FileOptions,
-		): Promise<void>;
+		unlink(path: string, options?: S3Options): Promise<void>;
 
 		/**
-		 * The size of the file in bytes.
+		 * 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");
+		 *     }
 		 */
-		function size(
-			path: string | S3File,
-			options?: S3FileOptions,
-		): Promise<number>;
+		size(path: string, options?: S3Options): Promise<number>;
 
 		/**
-		 * The size of the file in bytes.
+		 * 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);
+		 *     }
 		 */
-		function exists(
-			path: string | S3File,
-			options?: S3FileOptions,
-		): Promise<boolean>;
-	}
+		exists(path: string, options?: S3Options): Promise<boolean>;
+	};
 
 	/**
 	 *   This lets you use macros as regular imports
@@ -3417,17 +4012,6 @@ declare module "bun" {
 	// tslint:disable-next-line:unified-signatures
 	function file(fileDescriptor: number, options?: BlobPropertyBag): BunFile;
 
-	/**
-	 * Lazily load/upload a file from S3.
-	 * @param path - The path to the file. If bucket options is not provided or set in the path, it will be deduced from the path.
-	 * @param options - The options to use for the S3 client.
-	 */
-	function s3(path: string | URL, options?: S3FileOptions): S3File;
-	/**
-	 * The S3 file class.
-	 */
-	const S3: typeof S3File;
-
 	/**
 	 * Allocate a new [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) without zeroing the bytes.
 	 *