fs/promises trong Node.js: API tệp với async/await

fs/promises là phiên bản dựa trên promise của module fs trong Node. Các hàm của nó (readFile, writeFile, readdir, stat, mkdir, rm, rename và các hàm khác) trả về một promise thay vì nhận callback, nên bạn await chúng và bắt lỗi bằng try/catch. Import nó bằng require('fs/promises') hoặc 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));

Chương trình in ra [ 'write docs', 'ship it' ]: mỗi await chờ một thao tác xong rồi dòng tiếp theo mới chạy, nên phần ghi thêm luôn diễn ra sau lần ghi đầu tiên. Trong ES module, await dùng được ở cấp cao nhất; trong CommonJS, hãy bọc code trong một hàm async.

Những hàm bạn dùng nhiều nhất

Tên hàm giống hệt API callback, chỉ bỏ đi callback. Trang readFile và writeFile trình bày chi tiết hai hàm này.

Liệt kê thư mục với readdir và stat

readdir chỉ trả về tên. Gọi stat cho từng tên để lấy kích thước hoặc phân biệt tệp với thư mục, hoặc truyền { withFileTypes: true } để nhận các mục đã biết sẵn kiểu của mình.

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

Vòng lặp in ra README.md 6 bytes, notes.txt 3 bytes và src folder. stat reject với ENOENT khi đường dẫn không tồn tại, nên nó là cách kiểm tra tồn tại nhanh khi bạn cũng cần thêm thông tin chi tiết.

Đổi tên, di chuyển và xóa

rename vừa đổi tên vừa di chuyển tệp (trong cùng một ổ đĩa). rm dùng để xóa; nó cần recursive: true với thư mục có nội dung bên trong, và force: true để không báo lỗi khi đường dẫn đã không còn.

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

Tệp được chuyển từ drafts sang published với tên mới, và sau rm, thư mục blog chỉ còn published. Bỏ force: true khỏi lệnh rm thứ hai thì nó reject với ENOENT.

Xử lý lỗi bằng try/catch

Một thao tác thất bại sẽ reject promise của nó. Với await, lần reject đó trở thành một ngoại lệ (exception) mà bạn bắt như mọi ngoại lệ khác. Thuộc tính code của lỗi cho biết chuyện gì đã xảy ra.

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

Lần gọi đầu không tìm thấy tệp nên trả về []; lần thứ hai in ra Ada. Các mã lỗi nên biết: ENOENT (không có tệp đó), EEXIST (đã tồn tại), EISDIR (gặp thư mục ở chỗ cần một tệp), ENOTEMPTY (thư mục vẫn còn nội dung) và EACCES (không có quyền).

Một promise bạn không await và cũng không .catch() sẽ thành unhandled rejection khi thất bại, và Node thoát kèm lỗi. Hãy await mọi lệnh gọi, hoặc trả promise về cho nơi gọi có await nó.

Đọc nhiều tệp cùng lúc với Promise.all

Một vòng lặp for có await đọc từng tệp nối tiếp nhau. Khi các lần đọc không phụ thuộc vào nhau, hãy bắt đầu tất cả rồi chờ một lần bằng Promise.all: ổ đĩa xử lý chúng cùng lúc.

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 giữ nguyên thứ tự của mảng đầu vào, nên kết quả là [ 'alpha', 'beta', 'gamma' ] dù lần đọc nào xong trước, và độ dài sau khi nối là 14. Đổi 'b.txt' trong mảng thành 'x.txt' thì cả lệnh await reject với ENOENT.

Nếu bạn cần mọi kết quả ngay cả khi vài lần đọc thất bại, hãy dùng Promise.allSettled; trang promise trình bày cả hai.

Lỗi thường gặp

Nhầm lẫn hai module. require('fs').readFile cần callback; require('fs/promises').readFile trả về promise. Gọi bản callback mà không truyền callback sẽ ném lỗi The "cb" argument must be of type function.

Quên await. const text = fs.readFile(...) là một promise đang chờ, và text.split ném lỗi text.split is not a function.

Ghi song song vào một tệp. Promise.all với nhiều lần ghi vào cùng đường dẫn có thể để lại nội dung lẫn lộn. Hãy chạy chúng tuần tự.