NOTE

Les API Bun.file et Bun.write documentées sur cette page sont fortement optimisées et représentent la manière recommandée d'effectuer des tâches de système de fichiers avec Bun. Pour les opérations qui ne sont pas encore disponibles avec Bun.file, telles que mkdir ou readdir, vous pouvez utiliser l'implémentation presque complète de Bun du module node:fs.

---

Lire des fichiers (Bun.file())

Bun.file(path): BunFile

Créez une instance BunFile avec la fonction Bun.file(path). Un BunFile représente un fichier chargé paresseusement ; l'initialisation ne lit pas réellement le fichier depuis le disque.

const foo = Bun.file("foo.txt"); // relatif à cwd
foo.size; // nombre d'octets
foo.type; // type MIME

La référence est conforme à l'interface Blob, donc le contenu peut être lu dans différents formats.

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

await foo.text(); // contenu sous forme de chaîne
await foo.json(); // contenu sous forme d'objet JSON
await foo.stream(); // contenu sous forme de ReadableStream
await foo.arrayBuffer(); // contenu sous forme d'ArrayBuffer
await foo.bytes(); // contenu sous forme de Uint8Array

Les références de fichiers peuvent également être créées en utilisant des descripteurs de fichiers numériques ou des URL file://.

Bun.file(1234);
Bun.file(new URL(import.meta.url)); // référence au fichier actuel

Un BunFile peut pointer vers un emplacement sur le disque où un fichier n'existe pas.

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

Le type MIME par défaut est text/plain;charset=utf-8, mais il peut être remplacé en passant un deuxième argument à Bun.file.

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

Pour plus de commodité, Bun expose stdin, stdout et stderr comme des instances de BunFile.

Bun.stdin; // lecture seule
Bun.stdout;
Bun.stderr;

Supprimer des fichiers (file.delete())

Vous pouvez supprimer un fichier en appelant la fonction .delete().

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

---

Écrire des fichiers (Bun.write())

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

La fonction Bun.write est un outil polyvalent pour écrire des charges utiles de toutes sortes sur le disque.

Le premier argument est la destination qui peut avoir l'un des types suivants :

• string : Un chemin vers un emplacement sur le système de fichiers. Utilisez le module "path" pour manipuler les chemins.
• URL : Un descripteur file://.
• BunFile : Une référence de fichier.

Le deuxième argument correspond aux données à écrire. Il peut s'agir de l'un des éléments suivants :

• string
• Blob (y compris BunFile)
• ArrayBuffer ou SharedArrayBuffer
• TypedArray (Uint8Array, etc.)
• Response

Toutes les permutations possibles sont gérées en utilisant les appels système les plus rapides disponibles sur la plateforme actuelle.

Voir les appels système">

Sortie	Entrée	Appel système	Plateforme
fichier	fichier	copy_file_range	Linux
fichier	pipe	sendfile	Linux
pipe	pipe	splice	Linux
terminal	fichier	sendfile	Linux
terminal	terminal	sendfile	Linux
socket	fichier ou pipe	sendfile (si http, pas https)	Linux
fichier (n'existe pas)	fichier (chemin)	clonefile	macOS
fichier (existe)	fichier	fcopyfile	macOS
fichier	Blob ou string	write	macOS
fichier	Blob ou string	write	Linux

Pour écrire une chaîne sur le disque :

const data = `C'était le meilleur des temps, c'était le pire des temps.`;
await Bun.write("output.txt", data);

Pour copier un fichier vers un autre emplacement sur le disque :

const input = Bun.file("input.txt");
const output = Bun.file("output.txt"); // n'existe pas encore !
await Bun.write(output, input);

Pour écrire un tableau d'octets sur le disque :

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

Pour écrire un fichier vers stdout :

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

Pour écrire le corps d'une réponse HTTP sur le disque :

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

---

Écriture incrémentale avec FileSink

Bun fournit une API d'écriture de fichier incrémentale native appelée FileSink. Pour récupérer une instance FileSink depuis un BunFile :

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

Pour écrire de manière incrémentale dans le fichier, appelez .write().

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

writer.write("c'était le meilleur des temps\n");
writer.write("c'était le pire des temps\n");

Ces fragments seront mis en tampon en interne. Pour vider le tampon sur le disque, utilisez .flush(). Cela retourne le nombre d'octets vidés.

writer.flush(); // écrire le tampon sur le disque

Le tampon se videra également automatiquement lorsque le high water mark de FileSink est atteint ; c'est-à-dire lorsque son tampon interne est plein. Cette valeur peut être configurée.

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

Pour vider le tampon et fermer le fichier :

writer.end();

Notez que, par défaut, le processus bun restera actif jusqu'à ce que ce FileSink soit explicitement fermé avec .end(). Pour vous désinscrire de ce comportement, vous pouvez "unref" l'instance.

writer.unref();

// pour le "re-ref" plus tard
writer.ref();

---

Répertoires

L'implémentation de node:fs par Bun est rapide, et nous n'avons pas encore implémenté d'API spécifique à Bun pour lire les répertoires. Pour l'instant, vous devriez utiliser node:fs pour travailler avec les répertoires dans Bun.

Lire les répertoires (readdir)

Pour lire un répertoire dans Bun, utilisez readdir depuis node:fs.

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

// lire tous les fichiers du répertoire actuel
const files = await readdir(import.meta.dir);

Lire les répertoires de manière récursive

Pour lire un répertoire de manière récursive dans Bun, utilisez readdir avec recursive: true.

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

// lire tous les fichiers du répertoire actuel, récursivement
const files = await readdir("../", { recursive: true });

Créer des répertoires (mkdir)

Pour créer un répertoire de manière récursive, utilisez mkdir dans node:fs :

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

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

---

Benchmarks

Ce qui suit est une implémentation en 3 lignes de la commande Linux cat.

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

Pour exécuter le fichier :

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

Il s'exécute 2 fois plus vite que GNU cat pour les gros fichiers sur Linux.

---

Référence

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;
}