File I/O - BunDocumentation Index
Fetch the complete documentation index at: /docs/llms.txt
Use this file to discover all available pages before exploring further.
Skip to main contentBun home pageBun provides a set of optimized APIs for reading and writing files.
const foo = Bun.file("foo.txt"); // relative to cwd
foo.size; // number of bytes
foo.type; // MIME type
The reference conforms to the Blob interface, so the contents can be read in various formats.
const foo = Bun.file("foo.txt");
await foo.text(); // contents as a string
await foo.json(); // contents as a JSON object
await foo.stream(); // contents as ReadableStream
await foo.arrayBuffer(); // contents as ArrayBuffer
await foo.bytes(); // contents as Uint8Array
File references can also be created using numerical file descriptors or file:http:// URLs.
Bun.file(1234); Bun.file(new URL(import.meta.url)); // reference to the current fileA BunFile can point to a location on disk where a file does not exist.
const notreal = Bun.file("notreal.txt");
notreal.size; // 0
notreal.type; // "text/plain;charset=utf-8"
const exists = await notreal.exists(); // false
The default MIME type is text/plain;charset=utf-8, but it can be overridden by passing a second argument to Bun.file.
const notreal = Bun.file("notreal.json", { type: "application/json" });
notreal.type; // => "application/json;charset=utf-8"
For convenience, Bun exposes stdin, stdout and stderr as instances of BunFile.
Bun.stdin; // readonly Bun.stdout; Bun.stderr;Deleting files (file.delete()) You can delete a file by calling the .delete() function.
await Bun.file("logs.json").delete();
Writing files (Bun.write())
Bun.write(destination, data): Promise
The Bun.write function is a multi-tool for writing payloads of all kinds to disk.
The first argument is the destination which can have any of the following types:
string: A path to a location on the file system. Use the "path" module to manipulate paths.
URL: A file:http:// descriptor.
BunFile: A file reference.
The second argument is the data to be written. It can be any of the following:
string
Blob (including BunFile)
ArrayBuffer or SharedArrayBuffer
TypedArray (Uint8Array, et. al.)
Response
All possible permutations are handled using the fastest available system calls on the current platform.
See syscalls
OutputInputSystem callPlatformfilefilecopy_file_rangeLinuxfilepipesendfileLinuxpipepipespliceLinuxterminalfilesendfileLinuxterminalterminalsendfileLinuxsocketfile or pipesendfile (if http, not https)Linuxfile (doesn’t exist)file (path)clonefilemacOSfile (exists)filefcopyfilemacOSfileBlob or stringwritemacOSfileBlob or stringwriteLinux To write a string to disk:const data = `It was the best of times, it was the worst of times.`;
await Bun.write("output.txt", data);
To copy a file to another location on disk:
const input = Bun.file("input.txt");
const output = Bun.file("output.txt"); // doesn't exist yet!
await Bun.write(output, input);
To write a byte array to disk:
const encoder = new TextEncoder();
const data = encoder.encode("datadatadata"); // Uint8Array
await Bun.write("output.txt", data);
To write a file to stdout:
const input = Bun.file("input.txt");
await Bun.write(Bun.stdout, input);
To write the body of an HTTP response to disk:
const response = await fetch("https://bun.com");
await Bun.write("index.html", response);
Incremental writing with FileSink
Bun provides a native incremental file writing API called FileSink. To retrieve a FileSink instance from a BunFile:
const file = Bun.file("output.txt");
const writer = file.writer();
To incrementally write to the file, call .write().
const file = Bun.file("output.txt");
const writer = file.writer();
writer.write("it was the best of times\n");
writer.write("it was the worst of times\n");
These chunks will be buffered internally. To flush the buffer to disk, use .flush(). This returns the number of flushed bytes.
writer.flush(); // write buffer to diskThe buffer will also auto-flush when the FileSink’s high water mark is reached; that is, when its internal buffer is full. This value can be configured.
const file = Bun.file("output.txt");
const writer = file.writer({ highWaterMark: 1024 * 1024 }); // 1MB
To flush the buffer and close the file:
writer.end();Note that, by default, the bun process will stay alive until this FileSink is explicitly closed with .end(). To opt out of this behavior, you can “unref” the instance.
writer.unref(); // to "re-ref" it later writer.ref();Directories Bun’s implementation of node:fs is fast. Use node:fs for working with directories in Bun. Reading directories (readdir) To read a directory in Bun, use readdir from node:fs.
import { readdir } from "node:fs/promises";
// read all the files in the current directory
const files = await readdir(import.meta.dir);
Reading directories recursively
To recursively read a directory in Bun, use readdir with recursive: true.
import { readdir } from "node:fs/promises";
// read all the files in the current directory, recursively
const files = await readdir("../", { recursive: true });
Creating directories (mkdir)
To recursively create a directory, use mkdir in node:fs:
import { mkdir } from "node:fs/promises";
await mkdir("path/to/dir", { recursive: true });
Benchmarks
The following is a 3-line implementation of the Linux cat command.
cat.ts// Usage
// bun ./cat.ts ./path-to-file
import { resolve } from "path";
const path = resolve(process.argv.at(-1));
await Bun.write(Bun.stdout, Bun.file(path));
To run the file:
terminalbun ./cat.ts ./path-to-fileIt runs 2x faster than GNU cat for large files on Linux.
interface Bun {
stdin: BunFile;
stdout: BunFile;
stderr: BunFile;
file(path: string | number | URL, options?: { type?: string }): BunFile;
write(
destination: string | number | BunFile | URL,
input: string | Blob | ArrayBuffer | SharedArrayBuffer | TypedArray | Response,
): Promisenumber>;
}
interface BunFile {
readonly size: number;
readonly type: string;
text(): Promisestring>;
stream(): ReadableStream;
arrayBuffer(): PromiseArrayBuffer>;
json(): Promiseany>;
writer(params: { highWaterMark?: number }): FileSink;
exists(): Promiseboolean>;
}
export interface FileSink {
write(chunk: string | ArrayBufferView | ArrayBuffer | SharedArrayBuffer): number;
flush(): number | Promisenumber>;
end(error?: Error): number | Promisenumber>;
start(options?: { highWaterMark?: number }): void;
ref(): void;
unref(): void;
}
Was this page helpful?
File I/O - Bun,AI智能索引,全网链接索引,智能导航,网页索引
- Bun provides a set of optimized APIs for reading and writing files.