function

write

function write(
destination: BunFile | PathLike | S3File,
input: string | ArrayBufferLike | TypedArray<ArrayBufferLike> | Blob | Archive | BlobPart[],
options?: { createPath: boolean; mode: number }
): Promise<number>;

Use the fastest syscalls available to copy from input into destination.

If destination exists, it must be a regular file or symlink to a file. If destination's directory does not exist, it is created by default.

@param destination

The file or file path to write to

@param input

The data to copy into destination

@param options

Options for the write

@returns

A promise that resolves with the number of bytes written.

function write(
destination: BunFile,
input: Response,
options?: { createPath: boolean }
): Promise<number>;

Persist a Response body to disk.

@param destination

The file to write to. If the file doesn't exist, it is created; if it does, it is overwritten. If input is smaller than destination, destination is truncated.

@param input

The Response whose body is written

@param options

Options for the write

@returns

A promise that resolves with the number of bytes written.

function write(
destinationPath: PathLike,
input: Response,
options?: { createPath: boolean }
): Promise<number>;

Persist a Response body to disk.

@param destinationPath

The file path to write to. If the file doesn't exist, it is created; if it does, it is overwritten. If input is smaller than the existing file, the file is truncated.

@param input

The Response whose body is written

@returns

A promise that resolves with the number of bytes written.

function write(
destination: BunFile,
input: BunFile,
options?: { createPath: boolean; mode: number }
): Promise<number>;

Use the fastest syscalls available to copy from input into destination.

If destination exists, it must be a regular file or symlink to a file.

On Linux, this uses copy_file_range.

On macOS, when the destination doesn't already exist, this uses clonefile() and falls back to fcopyfile().

@param destination

The file to write to. If the file doesn't exist, it is created; if it does, it is overwritten. If input is smaller than destination, destination is truncated.

@param input

The file to copy from

@returns

A promise that resolves with the number of bytes written.

function write(
destinationPath: PathLike,
input: BunFile,
options?: { createPath: boolean; mode: number }
): Promise<number>;

Use the fastest syscalls available to copy from input into destination.

If destination exists, it must be a regular file or symlink to a file.

On Linux, this uses copy_file_range.

On macOS, when the destination doesn't already exist, this uses clonefile() and falls back to fcopyfile().

@param destinationPath

The file path to write to. If the file doesn't exist, it is created; if it does, it is overwritten. If input is smaller than the existing file, the file is truncated.

@param input

The file to copy from

@returns

A promise that resolves with the number of bytes written.

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
  • readonly type: string

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

  • bytes(): Promise<Uint8Array<ArrayBufferLike>>;

    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.

  • 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.

  • begin?: number,
    end?: number,
    contentType?: string

    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

    begin?: number,
    contentType?: string

    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

    contentType?: string

    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.

  • 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

  • data: string | ArrayBuffer | SharedArrayBuffer | BunFile | Request | Response | 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.

  • options?: { highWaterMark: number }

    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
  • readonly type: string

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

  • bytes(): Promise<Uint8Array<ArrayBufferLike>>;

    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.

  • 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.

  • 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
});
  • 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();
    begin?: number,
    contentType?: string
    ): S3File;
    contentType?: string
    ): S3File;
  • stat(): Promise<S3Stats>;

    Get the stat of the file.

    @returns

    Promise resolving to S3Stats

  • text(): Promise<string>;

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

  • 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"
});
  • options?: S3Options

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

class Blob

A file-like object of immutable, raw data. Blobs represent data that isn't necessarily in a JavaScript-native format. The File interface is based on Blob, inheriting blob functionality and expanding it to support files on the user's system.

MDN Reference

  • readonly size: number
  • readonly type: string

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

  • bytes(): Promise<Uint8Array<ArrayBufferLike>>;

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

  • 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.

  • 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.

  • start?: number,
    end?: number,
    contentType?: string
    ): Blob;

  • 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

class Archive

Create and extract tar archives, with optional gzip compression.

Bun.Archive builds an archive from in-memory data, or wraps an existing archive so you can extract it to disk or memory.

Create an archive from an object:

const archive = new Bun.Archive({
  "hello.txt": "Hello, World!",
  "data.json": JSON.stringify({ foo: "bar" }),
  "binary.bin": new Uint8Array([1, 2, 3, 4]),
});
  • blob(): Promise<Blob>;

    Get the archive contents as a Blob.

    Uses the compression settings specified when the Archive was created.

    @returns

    A promise that resolves with the archive data as a Blob

    Get tarball as Blob:

    const archive = new Bun.Archive(data);
const blob = await archive.blob();

  • Get the archive contents as a Uint8Array.

    Uses the compression settings specified when the Archive was created.

    @returns

    A promise that resolves with the archive data as a Uint8Array

    Get tarball bytes:

    const archive = new Bun.Archive(data);
const bytes = await archive.bytes();
  • path: string,
    options?: ArchiveExtractOptions
    ): Promise<number>;

    Extract the archive contents to a directory on disk.

    Creates the target directory and any necessary parent directories if they don't exist. Existing files are overwritten.

    @param path

    The directory path to extract to

    @param options

    Optional extraction options

    @returns

    A promise that resolves with the number of entries extracted (files, directories, and symlinks)

    Extract all entries:

    const archive = new Bun.Archive(tarballBytes);
const count = await archive.extract("./extracted");
console.log(`Extracted ${count} entries`);
  • glob?: string | readonly string[]
    ): Promise<Map<string, File>>;

    Get the archive contents as a Map of File objects.

    Each file in the archive is returned as a File object with:

    • name: The file path within the archive
    • lastModified: The file's modification time from the archive
    • Standard Blob methods (text(), arrayBuffer(), stream(), etc.)

    Only regular files are included; directories are not returned. File contents are loaded into memory, so for large archives consider using extract() instead.

    @param glob

    Optional glob pattern(s) to filter files. Supports the same syntax as Bun.Glob, including negation patterns (prefixed with !). Patterns are matched against paths normalized to use forward slashes (/).

    @returns

    A promise that resolves with a Map where keys are file paths (always using forward slashes / as separators) and values are File objects

    Get all files:

    const entries = await archive.files();
for (const [path, file] of entries) {
  console.log(`${path}: ${file.size} bytes`);
}
  • static write(
    path: string,
    data: Archive | ArchiveInput,
    options?: ArchiveOptions
    ): Promise<void>;

    Create an archive and write it to disk in one operation.

    The data streams directly to disk, which is more efficient than creating an archive and then writing it separately.

    @param path

    The file path to write the archive to

    @param data

    The input data for the archive (same as new Archive())

    @param options

    Optional archive options including compression settings

    @returns

    A promise that resolves when the write is complete

    Write uncompressed tarball:

    await Bun.Archive.write("output.tar", {
  "file1.txt": "content1",
  "file2.txt": "content2",
});
type BlobPart = string | Blob | BufferSource

class Response

This Fetch API interface represents the response to a request.

MDN Reference