method

Image.write

dest: number | BunFile | PathLike | S3File

): Promise<number>;

Run the pipeline and write the encoded result via Bun.write — dest may be a path string, BunFile, S3File, or fd. Resolves to the number of bytes written.

If no format method was chained and dest is a path string, the format is inferred from its extension when it's one Bun can encode (.jpg/.png/.webp/.heic/.avif); otherwise the source format is reused.

Referenced types

interface BunFile

Blob powered by the fastest system calls available for operating on files.

This Blob is lazy: it does no work until you read from it.

size is not valid until the contents of the file are read at least once.
type is auto-set based on the file extension when possible

const file = Bun.file("./hello.json");
console.log(file.type); // "application/json"
console.log(await file.text()); // '{"hello":"world"}'

lastModified: number
A UNIX timestamp indicating when the file was last modified.
readonly name?: string
The name or path of the file, as specified in the constructor.
readonly size: number
MDN Reference
readonly type: string
MDN Reference
arrayBuffer(): Promise<ArrayBuffer>;
Returns a promise that resolves to the contents of the blob as an ArrayBuffer
bytes(): Promise<Uint8Array<ArrayBufferLike>>;
MDN Reference
bytes(): Promise<Uint8Array<ArrayBuffer>>;
Returns a promise that resolves to the contents of the blob as a Uint8Array (array of bytes). Equivalent to new Uint8Array(await blob.arrayBuffer())
delete(): Promise<void>;
Deletes the file (same as unlink)
exists(): Promise<boolean>;
Does the file exist?
This returns true for regular files and FIFOs. It returns false for directories. A race condition can occur where the file is deleted or renamed after this is called but before you open it.
This does a system call to check if the file exists, which can be slow.
If using this in an HTTP server, it's faster to instead use return new Response(Bun.file(path)) and then an error handler to handle exceptions.
Instead of checking for a file's existence and then performing the operation, it is faster to just perform the operation and handle the error.
For empty Blob, this always returns true.
formData(): Promise<FormData>;
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 an application/x-www-form-urlencoded body.
The blob's type property determines 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.
image(
options?: ConstructorOptions
): Image;
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");
json(): Promise<any>;
Read the data from the blob as a JSON object.
This first decodes the data from UTF-8, then parses it as JSON.
slice(
begin?: number,
end?: number,
contentType?: string
): BunFile;
Offset any operation on the file starting at begin and ending at end. end is relative to 0
Similar to TypedArray.subarray. Does not copy the file, open the file, or modify the file.
If begin > 0, () is slower on macOS
@param begin
start offset in bytes
@param end
absolute offset in bytes (relative to 0)
@param contentType
MIME type for the new BunFile
slice(
begin?: number,
contentType?: string
): BunFile;
Offset any operation on the file starting at begin
Similar to TypedArray.subarray. Does not copy the file, open the file, or modify the file.
If begin > 0, Bun.write() is slower on macOS
@param begin
start offset in bytes
@param contentType
MIME type for the new BunFile
slice(
contentType?: string
): BunFile;
Slice the file from the beginning to the end, optionally with a new MIME type.
@param contentType
MIME type for the new BunFile
stat(): Promise<Stats>;
Provides useful information about the file.
stream(): ReadableStream<Uint8Array<ArrayBufferLike>>;
MDN Reference
stream(): ReadableStream<Uint8Array<ArrayBuffer>>;
Returns a readable stream of the blob's contents
text(): Promise<string>;
Returns a promise that resolves to the contents of the blob as a string
unlink(): Promise<void>;
Deletes the file.
write(
data: string | ArrayBuffer | SharedArrayBuffer | BunFile | Request | Response | ReadableStream<any> | ArrayBufferView<ArrayBufferLike>,
options?: { highWaterMark: number }
): Promise<number>;
Write data to the file. This is equivalent to using Bun.write with a BunFile.
@param data
The data to write.
@param options
The options to use for the write.
writer(
options?: { highWaterMark: number }
): FileSink;
Incremental writer for files and pipes.

type PathLike =

| string

| NodeJS.TypedArray

| ArrayBufferLike

| URL

interface S3File

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

readonly bucket?: string

The bucket name containing the file.

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

readonly name?: string

The name or path of the file in the bucket.

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

readonly readable: ReadableStream<Uint8Array<ArrayBuffer>>
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); }
readonly size: number
MDN Reference
readonly type: string
MDN Reference
unlink: () => Promise<void>
Alias for delete(), matching the Node.js fs API naming.
await file.unlink();
arrayBuffer(): Promise<ArrayBuffer>;
Returns a promise that resolves to the contents of the blob as an ArrayBuffer
bytes(): Promise<Uint8Array<ArrayBufferLike>>;
MDN Reference
bytes(): Promise<Uint8Array<ArrayBuffer>>;
Returns a promise that resolves to the contents of the blob as a Uint8Array (array of bytes). Equivalent to new Uint8Array(await blob.arrayBuffer())
delete(): Promise<void>;
Deletes the file from S3.
@returns
Promise that resolves when deletion is complete
// Basic deletion await file.delete();
exists(): Promise<boolean>;
Checks if the file exists in S3, using an HTTP HEAD request that does not download the file.
@returns
Promise resolving to true if file exists, false otherwise
// Basic existence check if (await file.exists()) { console.log("File exists in S3"); }
formData(): Promise<FormData>;
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 an application/x-www-form-urlencoded body.
The blob's type property determines 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.
image(
options?: ConstructorOptions
): Image;
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");
json(): Promise<any>;
Read the data from the blob as a JSON object.
This first decodes the data from UTF-8, then parses it as JSON.
presign(
options?: S3FilePresignOptions
): string;
Generates a presigned URL for the file. The URL grants temporary access to the file without exposing credentials.
@param options
Configuration for the presigned URL
@returns
Presigned URL string
// Basic download URL const url = file.presign({ expiresIn: 3600 // 1 hour });
slice(
begin?: number,
end?: number,
contentType?: string
): S3File;
Creates a new S3File representing a slice of the original file. Uses HTTP Range headers for efficient partial downloads.
@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
// Reading file header const header = file.slice(0, 1024); const headerText = await header.text();
slice(
begin?: number,
contentType?: string
): S3File;
MDN Reference
slice(
contentType?: string
): S3File;
MDN Reference
stat(): Promise<S3Stats>;
Get the stat of the file.
@returns
Promise resolving to S3Stats
stream(): ReadableStream<Uint8Array<ArrayBuffer>>;
MDN Reference
text(): Promise<string>;
Returns a promise that resolves to the contents of the blob as a string
write(
data: string | ArrayBuffer | SharedArrayBuffer | Blob | BunFile | Request | Response | ArrayBufferView<ArrayBufferLike> | S3File | Archive,
options?: S3Options
): Promise<number>;
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
// Writing string data await file.write("Hello World", { type: "text/plain" });
writer(
options?: S3Options
): NetworkSink;
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
// Basic streaming write const writer = file.writer({ type: "application/json" }); writer.write('{"hello": '); writer.write('"world"}'); await writer.end();