Bun.S3File TypeScript interface | API Reference | Bun

Represents a file in an S3-compatible storage service. Extends the Blob interface for compatibility with web APIs.

The bucket name containing the file.

const file = s3.file("s3:http://my-bucket/file.txt");
console.log(file.bucket); // "my-bucket"

The name or path of the file in the bucket.

const file = s3.file("folder/image.jpg");
console.log(file.name); // "folder/image.jpg"

Gets a readable stream of the file's content. Useful for processing large files without loading them entirely into memory.

// Basic streaming read
const stream = file.stream();
for await (const chunk of stream) {
console.log('Received chunk:', chunk);
}

MDN Reference

MDN Reference

Alias for delete() method. Provided for compatibility with Node.js fs API naming.

await file.unlink();

Returns a promise that resolves to the contents of the blob as an ArrayBuffer

MDN Reference

Returns a promise that resolves to the contents of the blob as a Uint8Array (array of bytes) its the same as new Uint8Array(await blob.arrayBuffer())

Deletes the file from S3.

Promise that resolves when deletion is complete

// Basic deletion
await file.delete();

Checks if the file exists in S3. Uses HTTP HEAD request to efficiently check existence without downloading.

Promise resolving to true if file exists, false otherwise

// Basic existence check
if (await file.exists()) {
console.log("File exists in S3");
}

Read the data from the blob as a FormData object.

This first decodes the data from UTF-8, then parses it as a multipart/form-data body or a application/x-www-form-urlencoded body.

The type property of the blob is used to determine the format of the body.

This is a non-standard addition to the Blob API, to make it conform more closely to the BodyMixin API.

Wrap this blob in a Bun.Image pipeline. Equivalent to new Bun.Image(this, options) — the constructor is synchronous (the underlying read happens lazily when an Image terminal is awaited), so this works on Bun.file(), Bun.s3(), fd-backed and in-memory blobs alike:

await Bun.file("photo.jpg").image().resize(400).webp().write("thumb.webp");

Read the data from the blob as a JSON object.

This first decodes the data from UTF-8, then parses it as JSON.

Generates a presigned URL for the file. Allows temporary access to the file without exposing credentials.

Configuration for the presigned URL

Presigned URL string

// Basic download URL
const url = file.presign({
expiresIn: 3600 // 1 hour
});

Creates a new S3File representing a slice of the original file. Uses HTTP Range headers for efficient partial downloads.

Starting byte offset

Ending byte offset (exclusive)

Optional MIME type for the slice

A new S3File representing the specified range

// Reading file header
const header = file.slice(0, 1024);
const headerText = await header.text();

MDN Reference

MDN Reference

Get the stat of a file in an S3-compatible storage service.

Promise resolving to S3Stat

MDN Reference

Returns a promise that resolves to the contents of the blob as a string

Uploads data to S3. Supports various input types and automatically handles large files.

The data to upload

Upload configuration options

Promise resolving to number of bytes written

// Writing string data
await file.write("Hello World", {
type: "text/plain"
});

Creates a writable stream for uploading data. Suitable for large files as it uses multipart upload.

Configuration for the upload

A NetworkSink for writing data

// Basic streaming write
const writer = file.writer({
type: "application/json"
});
writer.write('{"hello": ');
writer.write('"world"}');
await writer.end();