fs/promises ב-Node.js: מערכת הקבצים עם async/await

fs/promises היא הגרסה של המודול fs של Node שמבוססת על promises. הפונקציות שלה (readFile, writeFile, readdir, stat, mkdir, rm, rename וכל השאר) מחזירות promise במקום לקבל callback, כך שעושים להן await ותופסים שגיאות עם try/catch. ייבאו אותה עם require('fs/promises') או 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));

הוא מדפיס [ 'write docs', 'ship it' ]: כל await מחכה לפעולה אחת לפני שהשורה הבאה רצה, כך שההוספה תמיד קורית אחרי הכתיבה הראשונה. ב-ES module, ‏await עובד ברמה העליונה; ב-CommonJS, עטפו את הקוד בפונקציה async.

הפונקציות שתשתמשו בהן הכי הרבה

השמות זהים ל-API של ה-callbacks, רק בלי ה-callback. הדפים על readFile ועל writeFile מכסים את שתיהן בפירוט.

רשימת תיקייה עם readdir ו-stat

readdir מחזיר שמות בלבד. קראו ל-stat על כל אחד כדי לקבל את הגודל שלו או להבדיל בין קבצים לתיקיות, או העבירו { withFileTypes: true } כדי לקבל רשומות שכבר יודעות מה הסוג שלהן.

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

הלולאה מדפיסה README.md 6 bytes, notes.txt 3 bytes ו-src folder. stat נדחה עם ENOENT עבור נתיב שלא קיים, וזה הופך אותו לבדיקת קיום מהירה כשאתם רוצים גם את הפרטים.

שינוי שם, העברה ומחיקה

rename גם משנה שם וגם מעביר קובץ (באותו כונן). rm מוחק; הוא צריך recursive: true בשביל תיקייה שיש בה תוכן, ו-force: true כדי לא להיכשל כשהנתיב כבר לא קיים.

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

הקובץ עובר מ-drafts ל-published בשמו החדש, ואחרי rm התיקייה blog מכילה רק את published. הסירו את force: true מה-rm השני והוא יידחה עם ENOENT.

טיפול בשגיאות עם try/catch

פעולה שנכשלת דוחה את ה-promise שלה. עם await, הדחייה הזו הופכת לחריגה שתופסים כמו כל חריגה אחרת. ה-code של השגיאה אומר מה השתבש.

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

הקריאה הראשונה לא מוצאת קובץ ומחזירה []; השנייה מדפיסה Ada. קודים שכדאי להכיר: ENOENT (אין קובץ כזה), EEXIST (כבר קיים), EISDIR (תיקייה במקום שבו ציפו לקובץ), ENOTEMPTY (בתיקייה עדיין יש תוכן) ו-EACCES (אין הרשאה).

promise שלא עושים לו await ולא .catch() הופך ל-unhandled rejection כשהוא נכשל, ו-Node יוצא עם שגיאה. עשו await לכל קריאה, או החזירו את ה-promise שלה לקוד קורא שעושה זאת.

קריאה של כמה קבצים בבת אחת עם Promise.all

לולאת for עם await קוראת קבצים אחד אחרי השני. כשהקריאות לא תלויות זו בזו, התחילו את כולן וחכו פעם אחת עם Promise.all: הדיסק עובד עליהן באותו זמן.

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 שומר על הסדר של מערך הקלט, כך שהתוצאה היא [ 'alpha', 'beta', 'gamma' ] לא משנה איזו קריאה הסתיימה ראשונה, והאורך המחובר הוא 14. שנו את 'b.txt' במערך ל-'x.txt', וכל ה-await יידחה עם ENOENT.

אם אתם צריכים כל תוצאה גם כשחלק מהקריאות נכשלות, השתמשו ב-Promise.allSettled; הדף על promises מכסה את שתיהן.

טעויות נפוצות

לבלבל בין שני המודולים. require('fs').readFile רוצה callback; require('fs/promises').readFile מחזיר promise. קריאה לגרסת ה-callback בלי callback זורקת The "cb" argument must be of type function.

לשכוח await. const text = fs.readFile(...) הוא promise שעוד ממתין, ו-text.split זורק text.split is not a function.

כתיבות במקביל לקובץ אחד. Promise.all עם כמה כתיבות לאותו נתיב יכול להשאיר תוכן מעורבב. הריצו אותן אחת אחרי השנייה.