fs/promises في Node.js: نظام الملفات مع async/await

fs/promises هي النسخة المبنية على الوعود من وحدة fs في Node. دوالها (readFile وwriteFile وreaddir وstat وmkdir وrm وrename وغيرها) تعيد وعدًا بدلًا من أخذ 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.

الدوال التي ستستخدمها أكثر

الأسماء مطابقة لواجهة callback، دون الـ 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

العملية الفاشلة ترفض وعدها. ومع 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 (لا صلاحية).

الوعد الذي لا تنتظره بـ await ولا تضيف إليه .catch() يصبح رفضًا غير معالج (unhandled rejection) حين يفشل، فيخرج Node بخطأ. انتظر كل استدعاء، أو أعد وعده إلى مستدعٍ ينتظره.

قراءة عدة ملفات في الوقت نفسه عبر 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؛ وتغطي صفحة الوعود الاثنتين.

أخطاء شائعة

الخلط بين الوحدتين. require('fs').readFile تريد callback؛ وrequire('fs/promises').readFile تعيد وعدًا. استدعاء نسخة callback دون callback يرمي The "cb" argument must be of type function.

نسيان await. const text = fs.readFile(...) وعد معلّق، وtext.split يرمي text.split is not a function.

الكتابة المتوازية إلى ملف واحد. Promise.all مع عدة عمليات كتابة إلى المسار نفسه قد تترك محتوى مختلطًا. نفّذها بالتتابع.