File and Blob APIs

Relevant source files

• src/bake/DevServer/DirectoryWatchStore.zig
• src/bun.js/api.zig
• src/bun.js/api/BunObject.zig
• src/bun.js/bindings/BunObject+exports.h
• src/bun.js/bindings/BunObject.cpp
• src/bun.js/bindings/c-bindings.cpp
• src/bun.js/node/node_fs.zig
• src/bun.js/node/node_fs_binding.zig
• src/bun.js/node/types.zig
• src/js/builtins/shell.ts
• src/js/node/fs.promises.ts
• src/js/node/http.ts
• src/js/node/stream.ts
• src/main.zig
• src/output.zig
• src/shell/braces.zig
• src/shell/interpreter.zig
• src/shell/shell.zig
• src/sys.zig
• src/windows.zig
• test/js/bun/shell/bunshell.test.ts
• test/js/bun/shell/commands/mv.test.ts
• test/js/bun/shell/commands/rm.test.ts
• test/js/bun/shell/leak.test.ts
• test/js/bun/shell/lex.test.ts
• test/js/bun/shell/parse.test.ts
• test/js/bun/shell/test_builder.ts
• test/js/bun/shell/util.ts
• test/js/node/fs/fs.test.ts
• test/js/node/http/node-http.test.ts
• test/js/node/stream/node-stream.test.js
• test/regression/issue/26460.test.ts

This document describes Bun's file and blob APIs, focusing on Bun.file(), the BunFile interface, and high-performance file I/O operations. These APIs provide lazy file references, efficient data handling, and seamless integration between JavaScript and native code.

For Node.js file system APIs (fs module), see File System APIs. For streaming file I/O, see Streams API.

Overview

Bun's file and blob APIs center around:

• Bun.file(path) - Creates lazy file references without loading data
• BunFile interface - Extends Blob with file-specific properties
• Web-standard Blob API - Compatible with browser Blob/File implementations
• Zero-copy I/O - Minimizes memory copies through reference counting
• Automatic type conversion - Accepts strings, buffers, blobs uniformly

The implementation is in jsc.WebCore.Blob (constructor: WebCore.Blob.constructBunFile) with type conversion utilities in src/bun.js/node/types.zig.

Sources: src/bun.js/api/BunObject.zig20 src/bun.js/node/types.zig1-133

Core API Structure

Diagram: Bun.file() and BunFile Architecture

The BunFile interface returned by Bun.file():

• Extends Blob: All Blob methods available (text(), arrayBuffer(), stream())
• File properties: name, type, lastModified, size
• Lazy loading: File not read until data accessed (checked via needsToReadFile())
• Storage backends: In-memory for small/bundled data, on-disk for files

Sources: src/bun.js/api/BunObject.zig20 src/bun.js/node/types.zig1-85

Bun.file() - Creating File References

Bun.file(path) creates lazy file references without loading data into memory:

Implementation Flow:

Diagram: Lazy File Loading in Bun.file()

File validation timing:

• Bundled assets: Validated at startup for fast failure src/bun.js/api/server.zig169-181
• Runtime files: Validated when first accessed
• Stat operations: Return file metadata without reading contents

Sources: src/bun.js/api/BunObject.zig20 src/bun.js/api/server.zig158-188

BunFile Interface

The BunFile returned by Bun.file() implements the standard File/Blob interface:

Property/Method	Type	Description
name	string	File basename
size	number	File size in bytes (via stat)
type	string	MIME type (inferred from extension)
lastModified	number	Last modified timestamp (milliseconds)
text()	Promise<string>	Read file as UTF-8 text
arrayBuffer()	Promise<ArrayBuffer>	Read file as binary
json()	Promise<any>	Parse file as JSON
stream()	ReadableStream	Stream file contents
slice(start, end)	Blob	Create sub-blob
writer()	FileSink	Get writable stream

Lazy loading behavior:

Memory efficiency: The file is memory-mapped for large files, avoiding full reads when possible.

Sources: src/bun.js/api/BunObject.zig20 src/bun.js/node/types.zig49-85

Type Conversion System

Bun's file APIs accept multiple input types, converted internally through the BlobOrStringOrBuffer union:

Diagram: Input Type Conversion Pipeline

Conversion modes:

• Synchronous (fromJS): References existing memory, no copies
• Asynchronous (fromJSAsync): Copies data via toThreadSafe() for thread safety
• With encoding (fromJSWithEncodingValue): Handles character encodings

Example conversions:

The conversion is handled by BlobOrStringOrBuffer.fromJS() which:

1. Checks JavaScript type via value.jsType()
2. For Blobs: increments reference count via store.ref()
3. For strings/buffers: creates appropriate StringOrBuffer variant
4. Returns union value to native code

Sources: src/bun.js/node/types.zig1-133 src/bun.js/node/types.zig230-339

File I/O Operations

Reading Files

Multiple paths lead to the same blob-based reading mechanism:

Diagram: File Reading Mechanisms

Reading strategies:

Method	Behavior	When to Use
text()	Full read into memory	Small text files
arrayBuffer()	Full read as binary	Small binary files
stream()	Incremental chunks	Large files, backpressure
json()	Parse after full read	JSON files

Example:

Sources: src/bun.js/api/BunObject.zig20 src/sys.zig490-508

Writing Files

Bun.write() provides high-performance file writing with automatic type conversion:

Write implementation:

Diagram: Bun.write() Operation Flow

Optimizations:

• Zero-copy: For blob-to-blob copies, uses sendfile() syscall on Linux src/sys.zig472-488
• Buffering: Small writes are buffered before flushing
• Encoding: UTF-8 encoding applied automatically for strings

Sources: src/bun.js/api/BunObject.zig42 src/sys.zig472-508

Integration with Other APIs

HTTP Server Static File Serving

The server routing system uses Bun.file() for static file serving:

Route types:

• StaticRoute: Pre-loaded bundled assets (memory)
• FileRoute: Lazy-loaded files (disk)

Validation for bundled assets happens at startup to fail fast src/bun.js/api/server.zig169-181

Node.js fs Module

Bun.file() can be used with Node.js fs APIs:

The conversion from BunFile to file descriptor or path happens automatically.

Fetch API

Files integrate seamlessly with fetch:

Sources: src/bun.js/api/server.zig158-188 src/bun.js/node/node_fs.zig1-67

Encoding Support

File operations support multiple character encodings via the Encoding enum:

Encoding	Description	Example
utf8	UTF-8 (default)	file.text()
utf16le	UTF-16 LE	Windows text files
latin1	ISO-8859-1	Binary-as-text
base64	Base64	Data URLs
hex	Hexadecimal	Hash outputs

Usage:

The encoding conversion is handled by Encoding.encodeWithMaxSize() and related functions src/bun.js/node/types.zig448-487

Sources: src/bun.js/node/types.zig344-493

Memory Management and Performance

Reference Counting

Blobs use reference counting to share data without copying:

Diagram: Blob Store Reference Counting Lifecycle

GC integration:

• JavaScript objects use protect()/unprotect() to control GC
• Native stores use reference counting independent of GC
• Async operations call protect() to prevent premature collection src/bun.js/node/types.zig25-32

Thread Safety for Async

When passing data to worker threads or async operations:

Thread-safe conversions:

1. Strings: Copied via toThreadSafeSlice() src/bun.js/node/types.zig143-158
2. Buffers: Protected via protect() to prevent GC
3. Blobs: Store is thread-safe via refcounting

Sources: src/bun.js/node/types.zig25-44 src/bun.js/node/types.zig143-158 src/bun.js/node/types.zig230-281

Zero-Copy Operations

Bun minimizes memory copies through several techniques:

Operation	Mechanism	Benefit
File-to-file copy	sendfile() syscall	No userspace copy src/sys.zig472-488
Blob sharing	Reference counting	Single data, multiple refs
Large files	Memory mapping	No load into memory
Stream chunks	Direct slices	No intermediate buffers

Example - zero-copy file copy:

Memory-Mapped Files

Large files may be memory-mapped instead of loaded:

• Avoids allocating large buffers
• Pages loaded on-demand by OS
• Shared between processes
• Automatically managed by kernel

Sources: src/sys.zig472-488 src/bun.js/node/types.zig18-23

Platform-Specific Details

Windows File Handling

Windows requires special path handling via PathLike.sliceW():

• UTF-16 encoding: Paths converted to wide strings
• Long paths: \\?\ prefix for paths >260 chars src/bun.js/node/types.zig589-598
• Drive letters: Normalized (e.g., C:\ → \\?\C:\)
• UNC paths: Network paths supported

POSIX File Handling

POSIX systems (Linux, macOS) use simpler paths:

• UTF-8 encoding: All paths are byte strings
• Null termination: Via sliceZ()
• No length limits: Beyond system MAX_PATH
• Symlinks: Followed automatically

Sources: src/bun.js/node/types.zig584-661 src/sys.zig309-334

Error Handling

File operations can fail at several stages:

Diagram: Error Sources in File Operations

Error	Description	Example
ENAMETOOLONG	Path exceeds MAX_PATH	Very long file paths
ENOENT	File doesn't exist	Missing file
EACCES	Permission denied	Read-only file
EINVAL	Invalid argument	Bad encoding name
ERR_INVALID_ARG_VALUE	Null bytes in path	Path with \0

Validation functions:

• Valid.pathSlice() - Path length check src/bun.js/node/types.zig763-773
• Valid.pathBuffer() - Buffer path validation src/bun.js/node/types.zig791-805
• Valid.pathNullBytes() - Null byte detection src/bun.js/node/types.zig807-811

Example:

Sources: src/bun.js/node/types.zig763-811 src/sys.zig302-508

Common Patterns

Pattern 1: Type-Safe File Input

Internally uses BlobOrStringOrBuffer.fromJS() to handle all input types uniformly.

Pattern 2: Async-Safe Data Transfer

Uses toThreadSafe() to ensure safe cross-thread access.

Pattern 3: Lazy File Loading

Defers I/O until data is actually accessed.

Sources: src/bun.js/node/types.zig49-85 src/bun.js/node/types.zig724-755