NOTE

Die auf dieser Seite dokumentierten Bun.file- und Bun.write-APIs sind stark optimiert und stellen die empfohlene Methode zur Durchführung von Dateisystemaufgaben mit Bun dar. Für Operationen, die noch nicht mit Bun.file verfügbar sind, wie mkdir oder readdir, können Sie Buns nahezu vollständige Implementierung des node:fs-Moduls verwenden.

---

Dateien lesen (Bun.file())

Bun.file(path): BunFile

Erstellen Sie eine BunFile-Instanz mit der Bun.file(path)-Funktion. Eine BunFile repräsentiert eine verzögert geladene Datei; die Initialisierung liest die Datei nicht tatsächlich von der Festplatte.

const foo = Bun.file("foo.txt"); // relativ zu cwd
foo.size; // Anzahl der Bytes
foo.type; // MIME-Typ

Die Referenz entspricht der Blob-Schnittstelle, sodass die Inhalte in verschiedenen Formaten gelesen werden können.

const foo = Bun.file("foo.txt");

await foo.text(); // Inhalte als String
await foo.json(); // Inhalte als JSON-Objekt
await foo.stream(); // Inhalte als ReadableStream
await foo.arrayBuffer(); // Inhalte als ArrayBuffer
await foo.bytes(); // Inhalte als Uint8Array

Dateireferenzen können auch mit numerischen Dateideskriptoren oder file://-URLs erstellt werden.

Bun.file(1234);
Bun.file(new URL(import.meta.url)); // Referenz auf die aktuelle Datei

Eine BunFile kann auf einen Speicherort auf der Festplatte zeigen, an dem keine Datei existiert.

const notreal = Bun.file("notreal.txt");
notreal.size; // 0
notreal.type; // "text/plain;charset=utf-8"
const exists = await notreal.exists(); // false

Der Standard-MIME-Typ ist text/plain;charset=utf-8, kann aber durch Übergabe eines zweiten Arguments an Bun.file überschrieben werden.

const notreal = Bun.file("notreal.json", { type: "application/json" });
notreal.type; // => "application/json;charset=utf-8"

Der Einfachheit halber stellt Bun stdin, stdout und stderr als Instanzen von BunFile bereit.

Bun.stdin; // schreibgeschützt
Bun.stdout;
Bun.stderr;

Dateien löschen (file.delete())

Sie können eine Datei löschen, indem Sie die .delete()-Funktion aufrufen.

await Bun.file("logs.json").delete();

---

Dateien schreiben (Bun.write())

Bun.write(destination, data): Promise<number>

Die Bun.write-Funktion ist ein Multitool zum Schreiben von Payloads aller Art auf die Festplatte.

Das erste Argument ist das destination, das einen der folgenden Typen haben kann:

• string: Ein Pfad zu einem Speicherort im Dateisystem. Verwenden Sie das "path"-Modul, um Pfade zu manipulieren.
• URL: Ein file://-Deskriptor.
• BunFile: Eine Dateireferenz.

Das zweite Argument sind die zu schreibenden Daten. Es kann einen der folgenden Werte haben:

• string
• Blob (einschließlich BunFile)
• ArrayBuffer oder SharedArrayBuffer
• TypedArray (Uint8Array, etc.)
• Response

Alle möglichen Permutationen werden unter Verwendung der schnellsten verfügbaren Systemaufrufe auf der aktuellen Plattform verarbeitet.

Systemaufrufe anzeigen

Ausgabe	Eingabe	Systemaufruf	Plattform
file	file	copy_file_range	Linux
file	pipe	sendfile	Linux
pipe	pipe	splice	Linux
terminal	file	sendfile	Linux
terminal	terminal	sendfile	Linux
socket	file oder pipe	sendfile (wenn http, nicht https)	Linux
file (existiert nicht)	file (Pfad)	clonefile	macOS
file (existiert)	file	fcopyfile	macOS
file	Blob oder string	write	macOS
file	Blob oder string	write	Linux

Um einen String auf die Festplatte zu schreiben:

const data = `Es war die beste Zeit, es war die schlimmste Zeit.`;
await Bun.write("output.txt", data);

Um eine Datei an einen anderen Speicherort auf der Festplatte zu kopieren:

const input = Bun.file("input.txt");
const output = Bun.file("output.txt"); // existiert noch nicht!
await Bun.write(output, input);

Um ein Byte-Array auf die Festplatte zu schreiben:

const encoder = new TextEncoder();
const data = encoder.encode("datendatendaten"); // Uint8Array
await Bun.write("output.txt", data);

Um eine Datei nach stdout zu schreiben:

const input = Bun.file("input.txt");
await Bun.write(Bun.stdout, input);

Um den Körper einer HTTP-Antwort auf die Festplatte zu schreiben:

const response = await fetch("https://bun.com");
await Bun.write("index.html", response);

---

Inkrementelles Schreiben mit FileSink

Bun bietet eine native inkrementelle Datei-Schreib-API namens FileSink. Um eine FileSink-Instanz von einer BunFile zu erhalten:

const file = Bun.file("output.txt");
const writer = file.writer();

Um inkrementell in die Datei zu schreiben, rufen Sie .write() auf.

const file = Bun.file("output.txt");
const writer = file.writer();

writer.write("es war die beste Zeit\n");
writer.write("es war die schlimmste Zeit\n");

Diese Chunks werden intern gepuffert. Um den Puffer auf die Festplatte zu schreiben, verwenden Sie .flush(). Dies gibt die Anzahl der geschriebenen Bytes zurück.

writer.flush(); // Puffer auf Festplatte schreiben

Der Puffer wird auch automatisch geleert, wenn die High-Water-Mark des FileSink erreicht wird; das heißt, wenn sein interner Puffer voll ist. Dieser Wert kann konfiguriert werden.

const file = Bun.file("output.txt");
const writer = file.writer({ highWaterMark: 1024 * 1024 }); // 1MB

Um den Puffer zu leeren und die Datei zu schließen:

writer.end();

Beachten Sie, dass der bun-Prozess standardmäßig am Leben bleibt, bis dieser FileSink explizit mit .end() geschlossen wird. Um dieses Verhalten zu deaktivieren, können Sie die Instanz "unref"en.

writer.unref();

// um es später wieder zu "ref"en
writer.ref();

---

Verzeichnisse

Buns Implementierung von node:fs ist schnell, und wir haben noch keine Bun-spezifische API zum Lesen von Verzeichnissen implementiert. Für jetzt sollten Sie node:fs für die Arbeit mit Verzeichnissen in Bun verwenden.

Verzeichnisse lesen (readdir)

Um ein Verzeichnis in Bun zu lesen, verwenden Sie readdir aus node:fs.

import { readdir } from "node:fs/promises";

// alle Dateien im aktuellen Verzeichnis lesen
const files = await readdir(import.meta.dir);

Verzeichnisse rekursiv lesen

Um ein Verzeichnis in Bun rekursiv zu lesen, verwenden Sie readdir mit recursive: true.

import { readdir } from "node:fs/promises";

// alle Dateien im aktuellen Verzeichnis lesen, rekursiv
const files = await readdir("../", { recursive: true });

Verzeichnisse erstellen (mkdir)

Um ein Verzeichnis rekursiv zu erstellen, verwenden Sie mkdir in node:fs:

import { mkdir } from "node:fs/promises";

await mkdir("path/to/dir", { recursive: true });

---

Benchmarks

Das Folgende ist eine 3-zeilige Implementierung des Linux cat-Befehls.

// Verwendung
// 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));

Um die Datei auszuführen:

bun ./cat.ts ./path-to-file

Sie läuft 2x schneller als GNU cat für große Dateien unter Linux.

---

Referenz

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,
  ): Promise<number>;
}

interface BunFile {
  readonly size: number;
  readonly type: string;

  text(): Promise<string>;
  stream(): ReadableStream;
  arrayBuffer(): Promise<ArrayBuffer>;
  json(): Promise<any>;
  writer(params: { highWaterMark?: number }): FileSink;
  exists(): Promise<boolean>;
}

export interface FileSink {
  write(chunk: string | ArrayBufferView | ArrayBuffer | SharedArrayBuffer): number;
  flush(): number | Promise<number>;
  end(error?: Error): number | Promise<number>;
  start(options?: { highWaterMark?: number }): void;
  ref(): void;
  unref(): void;
}