S3File.writer method | Bun module | Bun

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();

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

Fast incremental writer for files and pipes.

This uses the same interface as ArrayBufferSink, but writes to a file or pipe.

Finish the upload. This also flushes the internal buffer.

Optional error to associate with the end operation

Number of bytes written or a Promise resolving to the number of bytes

Flush the internal buffer, committing the data to the network.

Number of bytes flushed or a Promise resolving to the number of bytes

For FIFOs & pipes, this lets you decide whether Bun's process should remain alive until the pipe is closed.

By default, it is automatically managed. While the stream is open, the process remains alive and once the other end hangs up or the stream closes, the process exits.

If you previously called unref, you can call this again to re-enable automatic management.

Internally, it will reference count the number of times this is called. By default, that number is 1

If the file is not a FIFO or pipe, ref and unref do nothing. If the pipe is already closed, this does nothing.

Start the file sink with provided options.

Configuration options for the file sink

Get the stat of the file.

Promise resolving to the file stats

For FIFOs & pipes, this lets you decide whether Bun's process should remain alive until the pipe is closed.

If you want to allow Bun's process to terminate while the stream is open, call this.

If the file is not a FIFO or pipe, ref and unref do nothing. If the pipe is already closed, this does nothing.

Write a chunk of data to the network.

If the network is not writable yet, the data is buffered.

The data to write

Number of bytes written or, if the write is pending, a Promise resolving to the number of bytes