Node.js fs/promises: async/await ile Dosya Sistemi

fs/promises, Node'un fs modülünün promise tabanlı sürümüdür. Fonksiyonları (readFile, writeFile, readdir, stat, mkdir, rm, rename ve diğerleri) callback almak yerine bir promise döndürür, böylece onları await eder ve hataları try/catch ile yakalarsın. require('fs/promises') ya da import fs from 'fs/promises' ile import et.

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

Çıktı [ 'write docs', 'ship it' ] olur: her await sonraki satır çalışmadan önce bir işlemi bekler, bu yüzden ekleme her zaman ilk yazmadan sonra olur. Bir ES modülünde await en üst seviyede çalışır; CommonJS'te kodu bir async fonksiyonun içine sar.

En çok kullanacağın fonksiyonlar

İsimler callback API'siyle aynı, sadece callback yok. O ikisini readFile ve writeFile sayfaları ayrıntılı anlatıyor.

readdir ve stat ile bir klasörü listele

readdir yalnızca isimleri döndürür. Boyutunu almak ya da dosyaları klasörlerden ayırmak için her birinde stat çağır, ya da tipini zaten bilen girdiler almak için { withFileTypes: true } ver.

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

Döngü README.md 6 bytes, notes.txt 3 bytes ve src folder yazdırır. stat, var olmayan bir path için ENOENT ile reject olur, bu da ayrıntıları da istediğinde onu hızlı bir varlık kontrolü yapar.

Yeniden adlandır, taşı ve sil

rename bir dosyayı hem yeniden adlandırır hem de taşır (aynı sürücü içinde). rm siler; içi dolu bir klasör için recursive: true, path zaten yoksa hata vermemesi için de force: true gerekir.

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'));

Dosya yeni ismiyle drafts klasöründen published klasörüne taşınır ve rm sonrasında blog klasörü yalnızca published listeler. İkinci rm çağrısından force: true seçeneğini kaldırırsan ENOENT ile reject olur.

Hataları try/catch ile yakala

Başarısız bir işlem kendi promise'ini reject eder. await ile bu reject, diğerleri gibi yakaladığın bir exception'a dönüşür. Hatanın code değeri neyin ters gittiğini söyler.

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

İlk çağrı dosya bulamaz ve [] döndürür; ikincisi Ada yazdırır. Bilmen gereken kodlar: ENOENT (böyle bir dosya yok), EEXIST (zaten var), EISDIR (dosya beklenen yerde klasör var), ENOTEMPTY (klasörün içinde hâlâ bir şeyler var) ve EACCES (izin yok).

await etmediğin ve .catch() eklemediğin bir promise başarısız olduğunda unhandled rejection'a dönüşür ve Node hata ile çıkar. Her çağrıyı await et ya da promise'ini await eden bir çağırana döndür.

Promise.all ile birkaç dosyayı aynı anda oku

await içeren bir for döngüsü dosyaları birbiri ardına okur. Okumalar birbirine bağlı değilse hepsini başlat ve Promise.all ile bir kez bekle: disk onlar üzerinde aynı anda çalışır.

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 giriş dizisinin sırasını korur, bu yüzden hangi okuma önce biterse bitsin sonuç [ 'alpha', 'beta', 'gamma' ] olur ve birleştirilmiş uzunluk 14 olur. Dizideki 'b.txt' değerini 'x.txt' yap, bütün await ENOENT ile reject olur.

Bazı okumalar başarısız olsa bile her sonuca ihtiyacın varsa Promise.allSettled kullan; ikisini de promise'ler sayfası anlatıyor.

Sık yapılan hatalar

İki modülü karıştırmak. require('fs').readFile bir callback ister; require('fs/promises').readFile ise bir promise döndürür. Callback sürümünü callback olmadan çağırmak The "cb" argument must be of type function fırlatır.

await unutmak. const text = fs.readFile(...) bekleyen bir promise'tir ve text.split, text.split is not a function fırlatır.

Tek bir dosyaya paralel yazmak. Aynı path'e birkaç yazma içeren bir Promise.all karışık içerik bırakabilir. Bunları sırayla çalıştır.