S3Client.constructor constructor | Bun module | Bun

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.

The default options to use for the S3 client. Can be overriden by passing options to the methods.

A new S3Client instance

const bucket = new Bun.S3Client({
accessKeyId: "your-access-key",
secretAccessKey: "your-secret-key",
bucket: "my-bucket",
endpoint: "https://s3.us-east-1.amazonaws.com",
sessionToken: "your-session-token",
});

// S3Client is callable, so you can do this:
const file = bucket.file("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!");

Configuration options for S3 operations

The access key ID for authentication. Defaults to S3_ACCESS_KEY_ID or AWS_ACCESS_KEY_ID environment variables.

The Access Control List (ACL) policy for the file. Controls who can access the file and what permissions they have.

// Setting public read access
const file = s3.file("public-file.txt", {
acl: "public-read",
bucket: "my-bucket"
});

The S3 bucket name. Defaults to S3_BUCKET or AWS_BUCKET environment variables.

// Using explicit bucket
const file = s3.file("my-file.txt", { bucket: "my-bucket" });

The Content-Disposition header value. Controls how the file is presented when downloaded.

// Setting attachment disposition with filename
const file = s3.file("report.pdf", {
contentDisposition: "attachment; filename=\"quarterly-report.pdf\""
});

The Content-Encoding header value. Specifies what content encodings have been applied to the object, for example to indicate that it has been compressed.

// Setting gzip encoding
const file = s3.file("data.json.gz", {
contentEncoding: "gzip"
});

The S3-compatible service endpoint URL. Defaults to S3_ENDPOINT or AWS_ENDPOINT environment variables.

// AWS S3
const file = s3.file("my-file.txt", {
endpoint: "https://s3.us-east-1.amazonaws.com"
});

The size of each part in multipart uploads (in bytes).

// Configuring multipart uploads
const file = s3.file("large-file.dat", {
partSize: 10 * 1024 * 1024, // 10 MiB parts
queueSize: 4 // Upload 4 parts in parallel
});

const writer = file.writer();
// ... write large file in chunks

Number of parts to upload in parallel for multipart uploads.

Increasing this value can improve upload speeds for large files but will use more memory.

The AWS region. Defaults to S3_REGION or AWS_REGION environment variables.

const file = s3.file("my-file.txt", {
bucket: "my-bucket",
region: "us-west-2"
});

When set to true, confirms that the requester knows they will be charged for the request and data transfer costs. Required for accessing objects in Requester Pays buckets.

// Accessing a file in a Requester Pays bucket
const file = s3.file("data.csv", {
bucket: "requester-pays-bucket",
requestPayer: true
});
const content = await file.text();

Number of retry attempts for failed uploads.

// Setting retry attempts
const file = s3.file("my-file.txt", {
retry: 5 // Retry failed uploads up to 5 times
});

The secret access key for authentication. Defaults to S3_SECRET_ACCESS_KEY or AWS_SECRET_ACCESS_KEY environment variables.

Optional session token for temporary credentials. Defaults to S3_SESSION_TOKEN or AWS_SESSION_TOKEN environment variables.

// Using temporary credentials
const file = s3.file("my-file.txt", {
accessKeyId: tempAccessKey,
secretAccessKey: tempSecretKey,
sessionToken: tempSessionToken
});

By default, Amazon S3 uses the STANDARD Storage Class to store newly created objects.

// Setting explicit Storage class
const file = s3.file("my-file.json", {
storageClass: "STANDARD_IA"
});

The Content-Type of the file. Automatically set based on file extension when possible.

// Setting explicit content type
const file = s3.file("data.bin", {
type: "application/octet-stream"
});

Use virtual hosted style endpoint. default to false, when true if endpoint is informed it will ignore the bucket

// Using virtual hosted style
const file = s3.file("my-file.txt", {
virtualHostedStyle: true,
endpoint: "https://my-bucket.s3.us-east-1.amazonaws.com"
});

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