Node.js fs/promisesの使い方：async/awaitでファイル操作

fs/promises は、Node.jsの fs モジュールのPromiseベース版です。その関数（readFile、writeFile、readdir、stat、mkdir、rm、rename など）はコールバックを受け取る代わりにPromiseを返すので、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 は1つの操作が終わるまで次の行に進まないので、追記は必ず最初の書き込みの後に行われます。ESモジュールではトップレベルで await が使えます。CommonJSでは、コードを async 関数で包みましょう。

よく使う関数

名前はコールバックAPIと同じで、コールバックがないだけです。そのうち2つは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 でrejectするので、詳細も欲しいときは手軽な存在確認になります。

名前変更、移動、削除

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 だけが残ります。2つ目の rm から force: true を外すと、ENOENT でrejectします。

try/catchでエラーを処理する

失敗した操作はPromiseをrejectします。await を使えば、そのrejectはほかの例外と同じように捕まえられます。何が起きたかはエラーの 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);

1回目の呼び出しはファイルが見つからず [] を返し、2回目は Ada を表示します。覚えておきたいコードは、ENOENT（ファイルがない）、EEXIST（すでにある）、EISDIR（ファイルのはずがフォルダだった）、ENOTEMPTY（フォルダに中身が残っている）、EACCES（権限がない）です。

await も .catch() もしていないPromiseが失敗すると、未処理のrejectになり、Node.jsはエラーで終了します。すべての呼び出しを await するか、それを処理する呼び出し元にPromiseを返しましょう。

Promise.allで複数のファイルを一度に読む

await を使った for ループは、ファイルを1つずつ順に読みます。読み込み同士が依存していないなら、全部を開始して 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 でrejectします。

一部の読み込みが失敗してもすべての結果が欲しいなら、Promise.allSettled を使います。両方ともPromiseのページで扱っています。

よくある間違い

2つのモジュールを取り違える。 require('fs').readFile はコールバックを必要とし、require('fs/promises').readFile はPromiseを返します。コールバック版をコールバックなしで呼ぶと The "cb" argument must be of type function が投げられます。

await を忘れる。 const text = fs.readFile(...) は待機中のPromiseで、text.split は text.split is not a function を投げます。

1つのファイルへの並列の書き込み。 同じパスへの書き込みを複数 Promise.all に入れると、中身が混ざることがあります。そういう書き込みは順番に実行しましょう。