Bun S3Client class | API Reference | Bun

A configured S3 bucket instance for managing files. The instance is callable to create S3File instances and provides methods for common operations.

// Basic bucket setup
const bucket = new S3Client({
bucket: "my-bucket",
accessKeyId: "key",
secretAccessKey: "secret"
});

// Get file instance
const file = bucket.file("image.jpg");

// Common operations
await bucket.write("data.json", JSON.stringify({hello: "world"}));
const url = bucket.presign("file.pdf");
await bucket.unlink("old.txt");

Delete a file from the bucket. Alias for S3Client.unlink.

The path to the file in the bucket

Additional S3 options to override defaults

A promise that resolves when deletion is complete

// Simple delete
await bucket.delete("old-file.txt");

// With error handling
try {
await bucket.delete("file.dat");
console.log("File deleted");
} catch (err) {
console.error("Delete failed:", err);
}

Check if a file exists in the bucket. Uses HEAD request to check existence.

The path to the file in the bucket

Additional S3 options to override defaults

A promise that resolves to true if the file exists, false otherwise

// Check existence
if (await bucket.exists("config.json")) {
const file = bucket.file("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);
}

Creates an S3File instance for the given path.

The path to the file in the bucket

Additional S3 options to override defaults

An S3File instance

const file = bucket.file("image.jpg");
await file.write(imageData);

const configFile = bucket.file("config.json", {
type: "application/json",
acl: "private"
});

Returns some or all (up to 1,000) of the objects in a bucket with each request.

You can use the request parameters as selection criteria to return a subset of the objects in a bucket.

Options for listing objects in the bucket

Additional S3 options to override defaults

A promise that resolves to the list response

// List (up to) 1000 objects in the bucket
const allObjects = await bucket.list();

// List (up to) 500 objects under `uploads/` prefix, with owner field for each object
const uploads = await bucket.list({
prefix: 'uploads/',
maxKeys: 500,
fetchOwner: true,
});

// Check if more results are available
if (uploads.isTruncated) {
// List next batch of objects under `uploads/` prefix
const moreUploads = await bucket.list({
prefix: 'uploads/',
maxKeys: 500,
startAfter: uploads.contents!.at(-1).key
fetchOwner: true,
});
}

Generate a presigned URL for temporary access to a file. Useful for generating upload/download URLs without exposing credentials.

The path to the file in the bucket

Options for generating the presigned URL

A presigned URL string

// 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"
});

Get the size of a file in bytes. Uses HEAD request to efficiently get size.

The path to the file in the bucket

Additional S3 options to override defaults

A promise that resolves to the file size in bytes

// 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");
}

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

The path to the file in the bucket

Additional S3 options to override defaults

A promise that resolves to the file stats

const stat = await bucket.stat("my-file.txt");

Delete a file from the bucket.

The path to the file in the bucket

Additional S3 options to override defaults

A promise that resolves when deletion is complete

// 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);
}

Writes data directly to a path in the bucket. Supports strings, buffers, streams, and web API types.

The path to the file in the bucket

The data to write to the file

Additional S3 options to override defaults

The number of bytes written

// 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"
});

Delete a file from the bucket. Alias for S3Client.unlink.

The path to the file in the bucket

S3 credentials and configuration options

A promise that resolves when deletion is complete

// Simple delete
await S3Client.delete("old-file.txt", credentials);

// With error handling
try {
await S3Client.delete("file.dat", credentials);
console.log("File deleted");
} catch (err) {
console.error("Delete failed:", err);
}

Check if a file exists in the bucket. Uses HEAD request to check existence.

The path to the file in the bucket

S3 credentials and configuration options

A promise that resolves to true if the file exists, false otherwise

// Check existence
if (await S3Client.exists("config.json", credentials)) {
const file = bucket.file("config.json");
const config = await file.json();
}

// With error handling
try {
if (!await S3Client.exists("required.txt", credentials)) {
throw new Error("Required file missing");
}
} catch (err) {
console.error("Check failed:", err);
}

Creates an S3File instance for the given path.

The path to the file in the bucket

S3 credentials and configuration options

An S3File instance

const file = S3Client.file("image.jpg", credentials);
await file.write(imageData);

const configFile = S3Client.file("config.json", {
...credentials,
type: "application/json",
acl: "private"
});

Returns some or all (up to 1,000) of the objects in a bucket with each request.

You can use the request parameters as selection criteria to return a subset of the objects in a bucket.

Options for listing objects in the bucket

S3 credentials and configuration options

A promise that resolves to the list response

// List (up to) 1000 objects in the bucket
const allObjects = await S3Client.list(null, credentials);

// List (up to) 500 objects under `uploads/` prefix, with owner field for each object
const uploads = await S3Client.list({
prefix: 'uploads/',
maxKeys: 500,
fetchOwner: true,
}, credentials);

// Check if more results are available
if (uploads.isTruncated) {
// List next batch of objects under `uploads/` prefix
const moreUploads = await S3Client.list({
prefix: 'uploads/',
maxKeys: 500,
startAfter: uploads.contents!.at(-1).key
fetchOwner: true,
}, credentials);
}

Generate a presigned URL for temporary access to a file. Useful for generating upload/download URLs without exposing credentials.

The path to the file in the bucket

S3 credentials and presigned URL configuration

A presigned URL string

// Download URL
const downloadUrl = S3Client.presign("file.pdf", {
...credentials,
expiresIn: 3600 // 1 hour
});

// Upload URL
const uploadUrl = S3Client.presign("uploads/image.jpg", {
...credentials,
method: "PUT",
expiresIn: 3600,
type: "image/jpeg",
acl: "public-read"
});

// Long-lived public URL
const publicUrl = S3Client.presign("public/doc.pdf", {
...credentials,
expiresIn: 7 * 24 * 60 * 60, // 7 days
acl: "public-read"
});

Get the size of a file in bytes. Uses HEAD request to efficiently get size.

The path to the file in the bucket

S3 credentials and configuration options

A promise that resolves to the file size in bytes

// Get size
const bytes = await S3Client.size("video.mp4", credentials);
console.log(`Size: ${bytes} bytes`);

// Check if file is large
if (await S3Client.size("data.zip", credentials) > 100 * 1024 * 1024) {
console.log("File is larger than 100MB");
}

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

The path to the file in the bucket

S3 credentials and configuration options

A promise that resolves to the file stats

const stat = await S3Client.stat("my-file.txt", credentials);

Delete a file from the bucket.

The path to the file in the bucket

S3 credentials and configuration options

A promise that resolves when deletion is complete

// Simple delete
await S3Client.unlink("old-file.txt", credentials);

// With error handling
try {
await S3Client.unlink("file.dat", credentials);
console.log("File deleted");
} catch (err) {
console.error("Delete failed:", err);
}

Writes data directly to a path in the bucket. Supports strings, buffers, streams, and web API types.

The path to the file in the bucket

The data to write to the file

S3 credentials and configuration options

The number of bytes written

// Write string
await S3Client.write("hello.txt", "Hello World", credentials);

// Write JSON with type
await S3Client.write(
"data.json",
JSON.stringify({hello: "world"}),
{
...credentials,
type: "application/json"
}
);

// Write from fetch
const res = await fetch("https://example.com/data");
await S3Client.write("data.bin", res, credentials);

// Write with ACL
await S3Client.write("public.html", html, {
...credentials,
acl: "public-read",
type: "text/html"
});