File and Blob APIs

Relevant source files

• .gitignore
• src/jsc/array_buffer.rs
• src/jsc/bindings/IsolatedModuleCache.cpp
• src/jsc/bindings/IsolatedModuleCache.h
• src/jsc/rare_data.rs
• src/jsc/webcore_types.rs
• src/runtime/api/BunObject.rs
• src/runtime/cli/test/Scanner.rs
• src/runtime/cli/test/parallel/runner.rs
• src/runtime/cli/test_command.rs
• src/runtime/dns_jsc/dns.rs
• src/runtime/ffi/FFIObject.rs
• src/runtime/image/Image.rs
• src/runtime/node/node_fs_stat_watcher.rs
• src/runtime/server/FileRoute.rs
• src/runtime/webcore/Blob.rs
• src/runtime/webcore/Body.rs
• src/runtime/webcore/ByteBlobLoader.rs
• src/runtime/webcore/ObjectURLRegistry.rs
• src/runtime/webcore/blob/read_file.rs
• test/cli/test/bun-test.test.ts
• test/js/bun/dns/resolve-dns.test.ts
• test/js/bun/io/bun-write.test.js
• test/js/web/fetch/blob.test.ts

This page documents Bun's internal implementation and public interfaces for file and binary data handling. Bun provides a high-performance, web-standard compliant Blob and File implementation, optimized for server-side I/O with features like lazy loading and zero-copy transfers.

Overview

Bun's file and blob APIs are designed to bridge the gap between high-level JavaScript web standards and low-level native system calls. The architecture centers around a unified storage backend that can represent data in memory, on disk, or even in remote storage like S3.

Key components include:

• Bun.file(path): Creates a lazy BunFile reference.
• Blob / File: Web-standard binary containers with Bun-specific convenience methods like .json(), .text(), and .bytes(). packages/bun-types/overrides.d.ts11-26
• S3Client / S3File: High-performance S3-compatible storage API integrated into the Bun namespace. packages/bun-types/globals.d.ts705-728
• High-Performance I/O: Specialized paths for memory mapping, asynchronous thread-pool based reads, and direct streaming.

Sources: packages/bun-types/overrides.d.ts1-66 packages/bun-types/globals.d.ts705-750

Core Entity Architecture

The following diagram maps the JavaScript entities to their corresponding native and type-space definitions.

Diagram: Mapping JS File Entities to Native Code

Sources: packages/bun-types/index.d.ts7-28 packages/bun-types/overrides.d.ts38-66 src/jsc/webcore_types.rs1-100 src/runtime/webcore/Blob.rs50-54

The Blob and BunFile Interface

In Bun, a Blob is backed by a Store, which can represent different sources (filesystem, memory, S3). This allows Bun to optimize operations, such as using copy_file syscalls when writing one file-backed blob to another file path. src/runtime/webcore/Blob.rs1-5

Convenience Methods

Bun adds BunConsumerConvenienceMethods to Blob, File, Response, and Request. These allow for direct consumption of binary data without manual stream management:

• text(): Consume as a UTF-8 string. packages/bun-types/overrides.d.ts15
• json(): Parse the contents as JSON. packages/bun-types/overrides.d.ts25
• bytes(): Returns a Uint8Array backed by an ArrayBuffer. packages/bun-types/overrides.d.ts20

BunFile Specifics

A BunFile represents a reference to a file on disk. It is lazy; the file is not opened until a read or write operation is performed.

• writer(): Returns a FileSink for high-performance incremental writes.
• slice(start, end): Creates a new BunFile representing a sub-range of the original file without copying data.

Sources: packages/bun-types/overrides.d.ts11-66 test/integration/bun-types/fixture/index.ts304-307 src/runtime/webcore/Blob.rs1-10

S3 Integration (Bun.S3Client)

Bun includes a native S3 client designed for high throughput. It supports AWS S3, Cloudflare R2, and other S3-compatible providers.

Implementation and Data Flow

The S3 implementation in Bun uses a dedicated S3File structure that integrates with the standard Blob interface. When a read is requested from an S3File, Bun handles the HTTP request setup, including proxy detection. src/runtime/webcore/Blob.rs36-47

Diagram: S3 Read Operation Flow

Sources: src/runtime/webcore/Blob.rs36-47 packages/bun-types/globals.d.ts705-728

S3File Operations

An S3File behaves similarly to a BunFile but targets cloud storage.

Operation	Description
write(data)	Uploads data to S3.
text() / json()	Downloads the object and parses it.
presign()	Generates a pre-signed URL for temporary access.

Sources: packages/bun-types/globals.d.ts705-728 test/integration/bun-types/fixture/index.ts60-70

Asynchronous Context and I/O

Bun maintains context across I/O boundaries. This is critical for tracing and logging in asynchronous file operations.

Context Tracking Implementation

Bun patches JavaScriptCore (JSC) to include $asyncContext. When an I/O operation (like a file read via Bun.write or an S3 request) is initiated, the current context is "snapshotted". When the native operation completes and returns to JavaScript, the context is restored. src/js/node/async_hooks.ts6-19

Sources: src/js/node/async_hooks.ts6-109

High-Performance I/O Patterns

Integration with Subprocesses

Bun's spawn API allows for direct piping of BunFile or Blob objects to subprocess stdin. test/integration/bun-types/fixture/spawn.ts67-79

• Input: Bun.spawn(["cat"], { stdin: Bun.file("input.txt") }) test/integration/bun-types/fixture/spawn.ts21-26
• Output: Bun.spawn(["ls"], { stdout: "pipe" }) returns a ReadableStream of Uint8Array. test/integration/bun-types/fixture/spawn.ts52

Serialization and Cloning

Bun supports structuredClone for Blob and File objects. The serialization process includes a versioning system (SERIALIZATION_VERSION = 3) to handle metadata like lastModified and stored_name during inter-worker communication or persistence. src/runtime/webcore/Blob.rs112-116

Sources: test/integration/bun-types/fixture/spawn.ts1-229 src/runtime/webcore/Blob.rs112-174 packages/bun-types/overrides.d.ts28-66