fs/promises Node.js: API File System dengan async/await

fs/promises adalah versi berbasis promise dari module fs milik Node. Fungsi-fungsinya (readFile, writeFile, readdir, stat, mkdir, rm, rename, dan lainnya) mengembalikan promise alih-alih menerima callback, jadi kamu await fungsinya dan menangkap error dengan try/catch. Import dengan require('fs/promises') atau import fs from 'fs/promises'.

import fs from 'fs/promises';

await fs.writeFile('todo.txt', 'write docs\n');
await fs.appendFile('todo.txt', 'ship it\n');

const text = await fs.readFile('todo.txt', 'utf8');
console.log(text.split('\n').filter(Boolean));

Hasilnya [ 'write docs', 'ship it' ]: setiap await menunggu satu operasi sebelum baris berikutnya berjalan, jadi append selalu terjadi setelah penulisan pertama. Di ES module, await bisa dipakai di tingkat atas; di CommonJS, bungkus kodenya dalam fungsi async.

Fungsi yang paling sering kamu pakai

Namanya sama dengan API callback, hanya tanpa callback. Halaman readFile dan writeFile membahas keduanya secara detail.

Menampilkan isi folder dengan readdir dan stat

readdir hanya mengembalikan nama. Panggil stat untuk setiap nama untuk mendapat ukurannya atau membedakan file dari folder, atau berikan { withFileTypes: true } untuk mendapat entri yang sudah tahu tipenya.

import fs from 'fs/promises';

// Setup: a folder with two files and a subfolder
await fs.mkdir('project/src', { recursive: true });
await fs.writeFile('project/README.md', '# Demo');
await fs.writeFile('project/notes.txt', 'abc');

const names = await fs.readdir('project');
console.log(names);

for (const name of names) {
    const info = await fs.stat('project/' + name);
    console.log(name, info.isDirectory() ? 'folder' : info.size + ' bytes');
}

const entries = await fs.readdir('project', { withFileTypes: true });
console.log(entries.filter((e) => e.isFile()).map((e) => e.name));

Perulangannya mencetak README.md 6 bytes, notes.txt 3 bytes, dan src folder. stat reject dengan ENOENT untuk path yang tidak ada, jadi ia bisa dipakai sebagai pengecekan keberadaan yang cepat saat kamu juga butuh detailnya.

Mengganti nama, memindahkan, dan menghapus

rename bisa mengganti nama sekaligus memindahkan file (di drive yang sama). rm menghapus; ia butuh recursive: true untuk folder yang ada isinya, dan force: true supaya tidak gagal saat path-nya sudah tidak ada.

import fs from 'fs/promises';

// Setup
await fs.mkdir('blog/drafts', { recursive: true });
await fs.writeFile('blog/drafts/post.md', 'hello');

await fs.mkdir('blog/published', { recursive: true });
await fs.rename('blog/drafts/post.md', 'blog/published/first-post.md');
console.log(await fs.readdir('blog/drafts'), await fs.readdir('blog/published'));

await fs.rm('blog/drafts', { recursive: true });
await fs.rm('blog/drafts', { recursive: true, force: true }); // already gone: no error
console.log(await fs.readdir('blog'));

File-nya pindah dari drafts ke published dengan nama barunya, dan setelah rm, folder blog hanya berisi published. Hapus force: true dari rm kedua dan ia reject dengan ENOENT.

Menangani error dengan try/catch

Operasi yang gagal membuat promise-nya reject. Dengan await, reject itu menjadi exception yang kamu tangkap seperti exception lain. code milik error memberi tahu apa yang salah.

import fs from 'fs/promises';

async function loadUsers() {
    try {
        const text = await fs.readFile('users.json', 'utf8');
        return JSON.parse(text);
    } catch (err) {
        if (err.code === 'ENOENT') return [];
        throw err;
    }
}

console.log(await loadUsers());

// Setup: create the file, then load again
await fs.writeFile('users.json', '[{"name":"Ada"}]');
console.log((await loadUsers())[0].name);

Panggilan pertama tidak menemukan file dan mengembalikan []; panggilan kedua mencetak Ada. Kode yang perlu kamu kenal: ENOENT (file tidak ada), EEXIST (sudah ada), EISDIR (folder di tempat yang seharusnya file), ENOTEMPTY (folder masih ada isinya), dan EACCES (tidak ada izin).

Promise yang tidak kamu await dan tidak kamu .catch() menjadi unhandled rejection saat gagal, dan Node berhenti dengan error. Await setiap panggilan, atau kembalikan promise-nya ke pemanggil yang meng-await-nya.

Membaca beberapa file sekaligus dengan Promise.all

Perulangan for dengan await membaca file satu per satu. Saat pembacaan tidak saling bergantung, mulai semuanya lalu tunggu sekali dengan Promise.all: disk mengerjakannya bersamaan.

import fs from 'fs/promises';

// Setup: three small files
await fs.writeFile('a.txt', 'alpha');
await fs.writeFile('b.txt', 'beta');
await fs.writeFile('c.txt', 'gamma');

const files = ['a.txt', 'b.txt', 'c.txt'];
const contents = await Promise.all(files.map((f) => fs.readFile(f, 'utf8')));

console.log(contents);
console.log(contents.join('').length);

Promise.all menjaga urutan array input, jadi hasilnya [ 'alpha', 'beta', 'gamma' ] tidak peduli pembacaan mana yang selesai duluan, dan panjang gabungannya 14. Ganti 'b.txt' di array menjadi 'x.txt' dan seluruh await reject dengan ENOENT.

Kalau kamu butuh setiap hasil walaupun sebagian pembacaan gagal, pakai Promise.allSettled; halaman promise membahas keduanya.

Kesalahan umum

Tertukar antara dua module. require('fs').readFile butuh callback; require('fs/promises').readFile mengembalikan promise. Memanggil versi callback tanpa callback melempar The "cb" argument must be of type function.

Lupa await. const text = fs.readFile(...) adalah promise yang masih pending, dan text.split melempar text.split is not a function.

Penulisan paralel ke satu file. Promise.all dengan beberapa penulisan ke path yang sama bisa meninggalkan isi yang tercampur. Jalankan secara berurutan.