Node でファイルシステムをどのように扱いますか？

Question

Accepted Answer

組み込みの **`fs`** モジュールは、ファイルやディレクトリの読み書きを行います。3 つの API スタイル — **promise**（モダンで推奨）、**コールバック**（元来の非同期）、**同期**（ブロッキング）— を提供しており、状況に応じて適切なものを選べます。

## promise API（推奨）

```js
import { readFile, writeFile, mkdir, readdir } from "fs/promises";

async function work() {
  const data = await readFile("input.txt", "utf8");     // 読み取り (utf8 → 文字列)
  await writeFile("output.txt", "Hello");                // 書き込み（上書き）
  await mkdir("new-dir", { recursive: true });           // ディレクトリ作成 (recursive = mkdir -p)
  const files = await readdir("./");                      // ディレクトリの内容を一覧表示
}
```

`fs/promises` API は async/await ときれいに連携します — ファイル I/O のモダンなデフォルトです。

## コールバック版と同期版

```js
import fs from "fs";

fs.readFile("file.txt", "utf8", (err, data) => { ... }); // 非同期コールバック
const data = fs.readFileSync("file.txt", "utf8");         // 同期 — イベントループをブロックする！
```

**注意:** `*Sync` メソッドは、操作が完了するまで**イベントループ全体をブロック**します。起動時（設定を一度だけ読み込むなど）には問題ありませんが、リクエストハンドラ内では避けるべきです — ブロッキングな読み取りはすべての並行リクエストをフリーズさせます。

## 一般的な操作

```js
await fs.promises.appendFile("log.txt", "new line
"); // 追記
await fs.promises.unlink("old.txt");                    // ファイル削除
await fs.promises.rename("a.txt", "b.txt");             // リネーム／移動
const stats = await fs.promises.stat("file.txt");       // メタデータ（サイズ、mtime）
const exists = fs.existsSync("file.txt");               // 存在確認
```

## 大きなファイルの場合: stream を使う

```js
// ❌ readFile はファイル全体をメモリに読み込む — 巨大ファイルでは危険
const huge = await readFile("10gb.txt"); // メモリを使い果たす可能性

// ✅ チャンク単位でストリーム処理する（一定のメモリ）
fs.createReadStream("10gb.txt").pipe(fs.createWriteStream("copy.txt"));
```

大きなファイルの場合、`readFile` はすべてを一度にメモリに読み込みますが、**stream** は一定のメモリでデータをチャンク単位で処理します。

## なぜ重要なのか

ファイル I/O は、設定の読み込み、ロギング、ファイルのアップロード／ダウンロード、ツール作成における中核的な Node の機能です。

3 つの API スタイルを知ること — そして特に、**同期メソッドはイベントループをブロックする**こと（サーバーでは避ける）、**大きなファイルには stream が必要**であること（`readFile` ではない）を知ることは、並行処理下で正しくかつ高性能なファイル処理コードを書くために不可欠です。

async/await を伴う promise API が、日常的な利用におけるクリーンなデフォルトです。