Node.js v25.0.0 ドキュメンテーション

クラス: FileHandle#

<FileHandle> オブジェクトは、数値のファイル記述子のオブジェクトラッパーです。

<FileHandle> オブジェクトのインスタンスは fsPromises.open() メソッドによって作成されます。

すべての <FileHandle> オブジェクトは <EventEmitter> です。

<FileHandle> が filehandle.close() メソッドを使用して閉じられない場合、自動的にファイル記述子を閉じようとし、プロセスの警告を発してメモリリークを防ぐのに役立ちます。この挙動は信頼できない可能性があり、ファイルが閉じられないこともあるため、この挙動に依存しないでください。代わりに、常に明示的に <FileHandle> を閉じてください。Node.js は将来この挙動を変更する可能性があります。

import { open } from 'node:fs/promises';

let filehandle;
try {
  filehandle = await open('thefile.txt', 'r');
} finally {
  await filehandle?.close();
} copy

import { open } from 'node:fs/promises';

const fd = await open('/dev/input/event0');
// Create a stream from some character device.
const stream = fd.createReadStream();
setTimeout(() => {
  stream.close(); // This may not close the stream.
  // Artificially marking end-of-stream, as if the underlying resource had
  // indicated end-of-file by itself, allows the stream to close.
  // This does not cancel pending read operations, and if there is such an
  // operation, the process may still not be able to exit successfully
  // until it finishes.
  stream.push(null);
  stream.read(0);
}, 100); copy

import { open } from 'node:fs/promises';

const fd = await open('sample.txt');
fd.createReadStream({ start: 90, end: 99 }); copy

import {
  open,
} from 'node:fs/promises';

const file = await open('./some/file/to/read');

for await (const chunk of file.readableWebStream())
  console.log(chunk);

await file.close();const {
  open,
} = require('node:fs/promises');

(async () => {
  const file = await open('./some/file/to/read');

  for await (const chunk of file.readableWebStream())
    console.log(chunk);

  await file.close();
})();copy

import { open } from 'node:fs/promises';

const file = await open('./some/file/to/read');

for await (const line of file.readLines()) {
  console.log(line);
}const { open } = require('node:fs/promises');

(async () => {
  const file = await open('./some/file/to/read');

  for await (const line of file.readLines()) {
    console.log(line);
  }
})();copy

import { open } from 'node:fs/promises';

let filehandle = null;
try {
  filehandle = await open('temp.txt', 'r+');
  await filehandle.truncate(4);
} finally {
  await filehandle?.close();
} copy

fsPromises.access(path[, mode])#

• path <string> | <Buffer> | <URL>
• mode <integer> デフォルト: fs.constants.F_OK
• 戻り値: <Promise> 成功すると undefined で履行されます。

path で指定されたファイルまたはディレクトリに対するユーザーのアクセス許可をテストします。mode 引数は、実行するアクセシビリティチェックを指定するオプションの整数です。mode は、値 fs.constants.F_OK または fs.constants.R_OK、fs.constants.W_OK、fs.constants.X_OK のいずれかのビットごとの OR からなるマスクである必要があります (例: fs.constants.W_OK | fs.constants.R_OK)。mode の可能な値については、ファイルアクセス定数を確認してください。

アクセシビリティチェックが成功した場合、promise は値なしで履行されます。アクセシビリティチェックのいずれかが失敗した場合、promise は <Error> オブジェクトで拒否されます。次の例では、ファイル /etc/passwd が現在のプロセスによって読み書きできるかどうかを確認します。

import { access, constants } from 'node:fs/promises';

try {
  await access('/etc/passwd', constants.R_OK | constants.W_OK);
  console.log('can access');
} catch {
  console.error('cannot access');
} copy

fsPromises.open() を呼び出す前にファイルのアクセシビリティをチェックするために fsPromises.access() を使用することは推奨されません。そうすることで、他のプロセスが2つの呼び出しの間にファイルの状態を変更する可能性があるため、競合状態が発生します。代わりに、ユーザーコードは直接ファイルを開いたり、読み書きしたりして、ファイルにアクセスできない場合に発生するエラーを処理する必要があります。

fsPromises.appendFile(path, data[, options])#

• path <string> | <Buffer> | <URL> | <FileHandle> ファイル名または <FileHandle>
• data <string> | <Buffer>
• options <Object> | <string>
  • encoding <string> | <null> デフォルト: 'utf8'
  • mode <integer> デフォルト: 0o666
  • flag <string> ファイルシステム flags のサポート を参照してください。デフォルト: 'a'
  • flush <boolean> true の場合、基礎となるファイル記述子は閉じる前にフラッシュされます。デフォルト: false
• 戻り値: <Promise> 成功すると undefined で履行されます。

非同期にファイルにデータを追記し、ファイルが存在しない場合は作成します。data は文字列または <Buffer> にすることができます。

options が文字列の場合、それは encoding を指定します。

mode オプションは新しく作成されたファイルにのみ影響します。詳細については、fs.open() を参照してください。

path は、追記用に開かれた <FileHandle> (fsPromises.open() を使用) として指定できます。

fsPromises.chmod(path, mode)#

• path <string> | <Buffer> | <URL>
• mode <string> | <integer>
• 戻り値: <Promise> 成功すると undefined で履行されます。

ファイルのパーミッションを変更します。

fsPromises.chown(path, uid, gid)#

• path <string> | <Buffer> | <URL>
• uid <integer>
• gid <integer>
• 戻り値: <Promise> 成功すると undefined で履行されます。

ファイルの所有権を変更します。

fsPromises.copyFile(src, dest[, mode])#

• src <string> | <Buffer> | <URL> コピー元のファイル名
• dest <string> | <Buffer> | <URL> コピー操作のコピー先のファイル名
• mode <integer> コピー操作の動作を指定するオプションの修飾子。2つ以上の値のビットごとのORからなるマスクを作成することが可能です (例: fs.constants.COPYFILE_EXCL | fs.constants.COPYFILE_FICLONE)。デフォルト: 0。
  • fs.constants.COPYFILE_EXCL: コピー操作は dest が既に存在する場合に失敗します。
  • fs.constants.COPYFILE_FICLONE: コピー操作は、コピーオンライトの reflink の作成を試みます。プラットフォームがコピーオンライトをサポートしていない場合、フォールバックのコピーメカニズムが使用されます。
  • fs.constants.COPYFILE_FICLONE_FORCE: コピー操作は、コピーオンライトの reflink の作成を試みます。プラットフォームがコピーオンライトをサポートしていない場合、操作は失敗します。
• 戻り値: <Promise> 成功すると undefined で履行されます。

非同期に src を dest にコピーします。デフォルトでは、dest が既に存在する場合、上書きされます。

コピー操作の原子性については保証されません。書き込みのために宛先ファイルが開かれた後にエラーが発生した場合、宛先を削除する試みが行われます。

import { copyFile, constants } from 'node:fs/promises';

try {
  await copyFile('source.txt', 'destination.txt');
  console.log('source.txt was copied to destination.txt');
} catch {
  console.error('The file could not be copied');
}

// By using COPYFILE_EXCL, the operation will fail if destination.txt exists.
try {
  await copyFile('source.txt', 'destination.txt', constants.COPYFILE_EXCL);
  console.log('source.txt was copied to destination.txt');
} catch {
  console.error('The file could not be copied');
} copy

fsPromises.cp(src, dest[, options])#

• src <string> | <URL> コピーする元のパス。
• dest <string> | <URL> コピー先のパス。
• options <Object>
  • dereference <boolean> シンボリックリンクをデリファレンスします。デフォルト: false
  • errorOnExist <boolean> force が false のとき、コピー先が存在する場合にエラーをスローします。デフォルト: false
  • filter <Function> コピーされるファイル/ディレクトリをフィルタリングする関数。アイテムをコピーするには true を、無視するには false を返します。ディレクトリを無視すると、そのすべての内容もスキップされます。true または false に解決される Promise を返すこともできます。デフォルト: undefined。
    • src <string> コピーする元のパス。
    • dest <string> コピー先のパス。
    • 戻り値: <boolean> | <Promise> boolean に変換可能な値、またはそのような値で履行される Promise。
  • force <boolean> 既存のファイルまたはディレクトリを上書きします。これを false に設定し、コピー先が存在する場合、コピー操作はエラーを無視します。この動作を変更するには errorOnExist オプションを使用します。デフォルト: true
  • mode <integer> コピー操作の修飾子。デフォルト: 0。fsPromises.copyFile() の mode フラグを参照してください。
  • preserveTimestamps <boolean> true の場合、src のタイムスタンプが保持されます。デフォルト: false
  • recursive <boolean> ディレクトリを再帰的にコピーします。デフォルト: false
  • verbatimSymlinks <boolean> true の場合、シンボリックリンクのパス解決がスキップされます。デフォルト: false
• 戻り値: <Promise> 成功すると undefined で履行されます。

非同期に、サブディレクトリやファイルを含む src から dest へのディレクトリ構造全体をコピーします。

ディレクトリを別のディレクトリにコピーする場合、グロブはサポートされず、動作は cp dir1/ dir2/ に似ています。

fsPromises.glob(pattern[, options])#

• pattern <string> | <string[]>
• options <Object>
  • cwd <string> | <URL> 現在の作業ディレクトリ。デフォルト: process.cwd()
  • exclude <Function> | <string[]> ファイル/ディレクトリを除外するための関数、または除外するグロブパターンのリスト。関数が提供された場合、アイテムを除外するには true を、含めるには false を返します。デフォルト: undefined。文字列配列が提供された場合、各文字列は除外するパスを指定するグロブパターンである必要があります。注意: 否定パターン (例: '!foo.js') はサポートされていません。
  • withFileTypes <boolean> グロブがパスを Dirent として返す場合は true、それ以外は false。デフォルト: false
• 戻り値: <AsyncIterator> パターンに一致するファイルのパスを生成する AsyncIterator。

import { glob } from 'node:fs/promises';

for await (const entry of glob('**/*.js'))
  console.log(entry);const { glob } = require('node:fs/promises');

(async () => {
  for await (const entry of glob('**/*.js'))
    console.log(entry);
})();copy

fsPromises.lchmod(path, mode)#

• path <string> | <Buffer> | <URL>
• mode <integer>
• 戻り値: <Promise> 成功すると undefined で履行されます。

シンボリックリンクのパーミッションを変更します。

このメソッドは macOS でのみ実装されています。

fsPromises.lchown(path, uid, gid)#

• path <string> | <Buffer> | <URL>
• uid <integer>
• gid <integer>
• 戻り値: <Promise> 成功すると undefined で履行されます。

シンボリックリンクの所有権を変更します。

fsPromises.lutimes(path, atime, mtime)#

• path <string> | <Buffer> | <URL>
• atime <number> | <string> | <Date>
• mtime <number> | <string> | <Date>
• 戻り値: <Promise> 成功すると undefined で履行されます。

fsPromises.utimes() と同じ方法でファイルのアクセス時刻と変更時刻を変更しますが、パスがシンボリックリンクを参照している場合、リンクはデリファレンスされず、代わりにシンボリックリンク自体のタイムスタンプが変更される点が異なります。

fsPromises.link(existingPath, newPath)#

• existingPath <string> | <Buffer> | <URL>
• newPath <string> | <Buffer> | <URL>
• 戻り値: <Promise> 成功すると undefined で履行されます。

existingPath から newPath への新しいリンクを作成します。詳細については、POSIX の link(2) のドキュメントを参照してください。

fsPromises.lstat(path[, options])#

• path <string> | <Buffer> | <URL>
• options <Object>
  • bigint <boolean> 返される <fs.Stats> オブジェクトの数値が bigint であるべきかどうか。デフォルト: false
• 戻り値: <Promise> 与えられたシンボリックリンク path の <fs.Stats> オブジェクトで履行されます。

path がシンボリックリンクを参照している場合を除き、fsPromises.stat() と同等です。その場合、リンクが参照するファイルではなく、リンク自体が stat されます。詳細については、POSIX の lstat(2) のドキュメントを参照してください。

fsPromises.mkdir(path[, options])#

• path <string> | <Buffer> | <URL>
• options <Object> | <integer>
  • recursive <boolean> デフォルト: false
  • mode <string> | <integer> Windows ではサポートされていません。デフォルト: 0o777。
• 戻り値: <Promise> 成功すると、recursive が false の場合は undefined で、recursive が true の場合は作成された最初のディレクトリパスで履行されます。

非同期にディレクトリを作成します。

オプションの options 引数は、mode (パーミッションとスティッキービット) を指定する整数、または mode プロパティと親ディレクトリを作成すべきかどうかを示す recursive プロパティを持つオブジェクトにすることができます。path が存在するディレクトリである場合に fsPromises.mkdir() を呼び出すと、recursive が false の場合にのみリジェクトされます。

import { mkdir } from 'node:fs/promises';

try {
  const projectFolder = new URL('./test/project/', import.meta.url);
  const createDir = await mkdir(projectFolder, { recursive: true });

  console.log(`created ${createDir}`);
} catch (err) {
  console.error(err.message);
}const { mkdir } = require('node:fs/promises');
const { join } = require('node:path');

async function makeDirectory() {
  const projectFolder = join(__dirname, 'test', 'project');
  const dirCreation = await mkdir(projectFolder, { recursive: true });

  console.log(dirCreation);
  return dirCreation;
}

makeDirectory().catch(console.error);copy

fsPromises.mkdtemp(prefix[, options])#

• prefix <string> | <Buffer> | <URL>
• options <string> | <Object>
  • encoding <string> デフォルト: 'utf8'
• 戻り値: <Promise> 新しく作成された一時ディレクトリのファイルシステムパスを含む文字列で履行されます。

一意の一時ディレクトリを作成します。提供された prefix の末尾に6つのランダムな文字を追加することで、一意のディレクトリ名が生成されます。プラットフォームの不整合のため、prefix の末尾に X 文字を使用することは避けてください。一部のプラットフォーム、特に BSD 系では、6つ以上のランダムな文字を返し、prefix の末尾の X 文字をランダムな文字に置き換えることがあります。

オプションの options 引数は、エンコーディングを指定する文字列、または使用する文字エンコーディングを指定する encoding プロパティを持つオブジェクトにすることができます。

import { mkdtemp } from 'node:fs/promises';
import { join } from 'node:path';
import { tmpdir } from 'node:os';

try {
  await mkdtemp(join(tmpdir(), 'foo-'));
} catch (err) {
  console.error(err);
} copy

fsPromises.mkdtemp() メソッドは、6つのランダムに選択された文字を prefix 文字列に直接追加します。たとえば、ディレクトリ /tmp が与えられた場合、/tmp 内に一時ディレクトリを作成する意図がある場合、prefix はプラットフォーム固有のパス区切り文字 (require('node:path').sep) で終わる必要があります。

fsPromises.mkdtempDisposable(prefix[, options])#

• prefix <string> | <Buffer> | <URL>
• options <string> | <Object>
  • encoding <string> デフォルト: 'utf8'
• 戻り値: <Promise> 非同期で破棄可能なオブジェクトの Promise で履行されます。
  • path <string> 作成されたディレクトリのパス。
  • remove <AsyncFunction> 作成されたディレクトリを削除する関数。
  • [Symbol.asyncDispose] <AsyncFunction> remove と同じです。

結果の Promise は、path プロパティが作成されたディレクトリパスを保持する非同期破棄可能オブジェクトを保持します。オブジェクトが破棄されると、ディレクトリとその内容がまだ存在する場合、非同期に削除されます。ディレクトリが削除できない場合、破棄はエラーをスローします。オブジェクトには、同じタスクを実行する非同期の remove() メソッドがあります。

この関数と結果のオブジェクトの破棄関数の両方が非同期であるため、await using dir = await fsPromises.mkdtempDisposable('prefix') のように await + await using と一緒に使用する必要があります。

詳細については、fsPromises.mkdtemp() のドキュメントを参照してください。

オプションの options 引数は、エンコーディングを指定する文字列、または使用する文字エンコーディングを指定する encoding プロパティを持つオブジェクトにすることができます。

fsPromises.open(path, flags[, mode])#

• path <string> | <Buffer> | <URL>
• flags <string> | <number> ファイルシステム flags のサポート を参照してください。デフォルト: 'r'
• mode <string> | <integer> ファイルが作成された場合にファイルモード (パーミッションとスティッキービット) を設定します。デフォルト: 0o666 (読み書き可能)
• 戻り値: <Promise> <FileHandle> オブジェクトで履行されます。

<FileHandle> を開きます。

詳細については、POSIX の open(2) のドキュメントを参照してください。

一部の文字 (< > : " / \ | ? *) は、ファイル、パス、および名前空間の命名で文書化されているように、Windows で予約されています。NTFS では、ファイル名にコロンが含まれている場合、Node.js は この MSDN ページで説明されているように、ファイルシステムストリームを開きます。

fsPromises.opendir(path[, options])#

• path <string> | <Buffer> | <URL>
• options <Object>
  • encoding <string> | <null> デフォルト: 'utf8'
  • bufferSize <number> ディレクトリから読み取るときに内部的にバッファリングされるディレクトリエンティティの数。値が高いほどパフォーマンスは向上しますが、メモリ使用量も高くなります。デフォルト: 32
  • recursive <boolean> 解決された Dir は、すべてのサブファイルとディレクトリを含む <AsyncIterable> になります。デフォルト: false
• 戻り値: <Promise> <fs.Dir> で履行されます。

反復スキャンのためにディレクトリを非同期に開きます。詳細については、POSIX の opendir(3) のドキュメントを参照してください。

ディレクトリからの読み取りとクリーンアップのためのすべてのさらなる関数を含む <fs.Dir> を作成します。

encoding オプションは、ディレクトリを開くときと後続の読み取り操作で path のエンコーディングを設定します。

非同期イテレーションを使用した例

import { opendir } from 'node:fs/promises';

try {
  const dir = await opendir('./');
  for await (const dirent of dir)
    console.log(dirent.name);
} catch (err) {
  console.error(err);
} copy

非同期イテレータを使用する場合、イテレータが終了した後に <fs.Dir> オブジェクトは自動的に閉じられます。

fsPromises.readdir(path[, options])#

• path <string> | <Buffer> | <URL>
• options <string> | <Object>
  • encoding <string> デフォルト: 'utf8'
  • withFileTypes <boolean> デフォルト: false
  • recursive <boolean> true の場合、ディレクトリの内容を再帰的に読み取ります。再帰モードでは、すべてのファイル、サブファイル、およびディレクトリを一覧表示します。デフォルト: false。
• 戻り値: <Promise> '.' と '..' を除くディレクトリ内のファイル名の配列で履行されます。

ディレクトリの内容を読み取ります。

オプションの options 引数は、エンコーディングを指定する文字列、またはファイル名に使用する文字エンコーディングを指定する encoding プロパティを持つオブジェクトにすることができます。encoding が 'buffer' に設定されている場合、返されるファイル名は <Buffer> オブジェクトとして渡されます。

options.withFileTypes が true に設定されている場合、返される配列には <fs.Dirent> オブジェクトが含まれます。

import { readdir } from 'node:fs/promises';

try {
  const files = await readdir(path);
  for (const file of files)
    console.log(file);
} catch (err) {
  console.error(err);
} copy

fsPromises.readFile(path[, options])#

• path <string> | <Buffer> | <URL> | <FileHandle> ファイル名または FileHandle
• options <Object> | <string>
  • encoding <string> | <null> デフォルト: null
  • flag <string> ファイルシステム flags のサポートを参照してください。 デフォルト: 'r'
  • signal <AbortSignal> 進行中の readFile を中止できます。
• 戻り値: <Promise> ファイルの内容で fulfill されます。

ファイルの内容全体を非同期に読み取ります。

エンコーディングが指定されていない場合 (options.encoding を使用)、データは <Buffer> オブジェクトとして返されます。それ以外の場合、データは文字列になります。

options が文字列の場合、それはエンコーディングを指定します。

path がディレクトリの場合、fsPromises.readFile() の動作はプラットフォーム固有です。macOS、Linux、Windows では、promise はエラーで reject されます。FreeBSD では、ディレクトリの内容の表現が返されます。

実行中のコードと同じディレクトリにある package.json ファイルを読み取る例

import { readFile } from 'node:fs/promises';
try {
  const filePath = new URL('./package.json', import.meta.url);
  const contents = await readFile(filePath, { encoding: 'utf8' });
  console.log(contents);
} catch (err) {
  console.error(err.message);
}const { readFile } = require('node:fs/promises');
const { resolve } = require('node:path');
async function logFile() {
  try {
    const filePath = resolve('./package.json');
    const contents = await readFile(filePath, { encoding: 'utf8' });
    console.log(contents);
  } catch (err) {
    console.error(err.message);
  }
}
logFile();copy

<AbortSignal> を使用して、進行中の readFile を中止することが可能です。リクエストが中止された場合、返される promise は AbortError で reject されます。

import { readFile } from 'node:fs/promises';

try {
  const controller = new AbortController();
  const { signal } = controller;
  const promise = readFile(fileName, { signal });

  // Abort the request before the promise settles.
  controller.abort();

  await promise;
} catch (err) {
  // When a request is aborted - err is an AbortError
  console.error(err);
} copy

進行中のリクエストを中止しても、個々のオペレーティングシステムのリクエストが中止されるわけではなく、fs.readFile が行う内部バッファリングが中止されます。

指定された <FileHandle> は読み取りをサポートしている必要があります。

fsPromises.readlink(path[, options])#

• path <string> | <Buffer> | <URL>
• options <string> | <Object>
  • encoding <string> デフォルト: 'utf8'
• 戻り値: <Promise> 成功すると linkString で fulfill されます。

path が参照するシンボリックリンクの内容を読み取ります。詳細については、POSIX の readlink(2) ドキュメントを参照してください。成功すると、promise は linkString で fulfill されます。

オプションの options 引数は、エンコーディングを指定する文字列、または返されるリンクパスに使用する文字エンコーディングを指定する encoding プロパティを持つオブジェクトにすることができます。encoding が 'buffer' に設定されている場合、返されるリンクパスは <Buffer> オブジェクトとして渡されます。

fsPromises.realpath(path[, options])#

• path <string> | <Buffer> | <URL>
• options <string> | <Object>
  • encoding <string> デフォルト: 'utf8'
• 戻り値: <Promise> 成功すると解決されたパスで fulfill されます。

fs.realpath.native() 関数と同じセマンティクスを使用して path の実際の場所を決定します。

UTF8 文字列に変換できるパスのみがサポートされています。

オプションの options 引数は、エンコーディングを指定する文字列、またはパスに使用する文字エンコーディングを指定する encoding プロパティを持つオブジェクトにすることができます。encoding が 'buffer' に設定されている場合、返されるパスは <Buffer> オブジェクトとして渡されます。

Linux では、Node.js が musl libc に対してリンクされている場合、この関数が機能するためには procfs ファイルシステムが /proc にマウントされている必要があります。Glibc にはこの制限はありません。

fsPromises.rename(oldPath, newPath)#

• oldPath <string> | <Buffer> | <URL>
• newPath <string> | <Buffer> | <URL>
• 戻り値: <Promise> 成功すると undefined で履行されます。

oldPath の名前を newPath に変更します。

fsPromises.rmdir(path[, options])#

• path <string> | <Buffer> | <URL>
• options <Object> 現在公開されているオプションはありません。以前は recursive、maxBusyTries、emfileWait のオプションがありましたが、それらは非推奨となり削除されました。options 引数は後方互換性のためにまだ受け入れられていますが、使用されません。
• 戻り値: <Promise> 成功すると undefined で履行されます。

path で指定されたディレクトリを削除します。

（ディレクトリではなく）ファイルに対して fsPromises.rmdir() を使用すると、Windows では ENOENT エラー、POSIX では ENOTDIR エラーで promise が reject されます。

Unix コマンドの rm -rf と同様の動作を得るには、オプション { recursive: true, force: true } を付けて fsPromises.rm() を使用してください。

fsPromises.rm(path[, options])#

• path <string> | <Buffer> | <URL>
• options <Object>
  • force <boolean> true の場合、path が存在しなくても例外は無視されます。 デフォルト: false
  • maxRetries <integer> EBUSY、EMFILE、ENFILE、ENOTEMPTY、または EPERM エラーが発生した場合、Node.js は毎回 retryDelay ミリ秒長い線形バックオフ待機時間で操作を再試行します。このオプションは再試行の回数を表します。このオプションは recursive オプションが true でない場合は無視されます。 デフォルト: 0
  • recursive <boolean> true の場合、再帰的なディレクトリ削除を実行します。再帰モードでは、操作は失敗時に再試行されます。 デフォルト: false
  • retryDelay <integer> 再試行の間に待機する時間（ミリ秒単位）。このオプションは recursive オプションが true でない場合は無視されます。 デフォルト: 100
• 戻り値: <Promise> 成功すると undefined で履行されます。

ファイルとディレクトリを削除します（標準の POSIX rm ユーティリティをモデルにしています）。

fsPromises.stat(path[, options])#

• path <string> | <Buffer> | <URL>
• options <Object>
  • bigint <boolean> 返される <fs.Stats> オブジェクトの数値が bigint であるべきかどうか。デフォルト: false
• 戻り値: <Promise> 指定された path の <fs.Stats> オブジェクトで fulfill されます。

fsPromises.statfs(path[, options])#

• path <string> | <Buffer> | <URL>
• options <Object>
  • bigint <boolean> 返される <fs.StatFs> オブジェクトの数値が bigint であるべきかどうか。 デフォルト: false
• 戻り値: <Promise> 指定された path の <fs.StatFs> オブジェクトで fulfill されます。

fsPromises.symlink(target, path[, type])#

• target <string> | <Buffer> | <URL>
• path <string> | <Buffer> | <URL>
• type <string> | <null> デフォルト: null
• 戻り値: <Promise> 成功すると undefined で履行されます。

シンボリックリンクを作成します。

type 引数は Windows プラットフォームでのみ使用され、'dir'、'file'、または 'junction' のいずれかになります。type 引数が null の場合、Node.js は target のタイプを自動検出し、'file' または 'dir' を使用します。target が存在しない場合は 'file' が使用されます。Windows のジャンクションポイントでは、リンク先のパスが絶対パスである必要があります。'junction' を使用する場合、target 引数は自動的に絶対パスに正規化されます。NTFS ボリューム上のジャンクションポイントはディレクトリのみを指すことができます。

fsPromises.truncate(path[, len])#

• path <string> | <Buffer> | <URL>
• len <integer> デフォルト: 0
• 戻り値: <Promise> 成功すると undefined で履行されます。

path にあるコンテンツの長さを len バイトに切り詰めます（短くするか、長くします）。

fsPromises.unlink(path)#

• path <string> | <Buffer> | <URL>
• 戻り値: <Promise> 成功すると undefined で履行されます。

path がシンボリックリンクを参照している場合、そのリンクが参照するファイルやディレクトリに影響を与えることなくリンクが削除されます。path がシンボリックリンクではないファイルパスを参照している場合、ファイルが削除されます。詳細については、POSIX の unlink(2) ドキュメントを参照してください。

fsPromises.utimes(path, atime, mtime)#

• path <string> | <Buffer> | <URL>
• atime <number> | <string> | <Date>
• mtime <number> | <string> | <Date>
• 戻り値: <Promise> 成功すると undefined で履行されます。

path が参照するオブジェクトのファイルシステムタイムスタンプを変更します。

atime と mtime 引数は以下のルールに従います

• 値は、Unix エポックタイムを表す数値、Date オブジェクト、または '123456789.0' のような数値文字列のいずれかです。
• 値が数値に変換できない場合、または NaN、Infinity、-Infinity の場合、Error がスローされます。

fsPromises.watch(filename[, options])#

• filename <string> | <Buffer> | <URL>
• options <string> | <Object>
  • persistent <boolean> ファイルが監視されている間、プロセスを実行し続けるかどうかを示します。 デフォルト: true
  • recursive <boolean> すべてのサブディレクトリを監視するか、現在のディレクトリのみを監視するかを示します。これはディレクトリが指定された場合に適用され、サポートされているプラットフォームでのみ有効です（注意事項を参照）。 デフォルト: false
  • encoding <string> リスナーに渡されるファイル名に使用される文字エンコーディングを指定します。 デフォルト: 'utf8'
  • signal <AbortSignal> ウォッチャーを停止するタイミングを通知するために使用される <AbortSignal>。
  • maxQueue <number> 返される <AsyncIterator> のイテレーション間でキューに入れるイベントの数を指定します。 デフォルト: 2048
  • overflow <string> maxQueue が許可するよりも多くのイベントをキューに入れようとした場合の動作で、'ignore' または 'throw' のいずれかです。'ignore' はオーバーフローしたイベントが破棄され警告が出力されることを意味し、'throw' は例外をスローすることを意味します。 デフォルト: 'ignore'
• 戻り値: <AsyncIterator> 以下のプロパティを持つオブジェクトの非同期イテレータ
  • eventType <string> 変更の種類
  • filename <string> | <Buffer> | <null> 変更されたファイルの名前。

filename の変更を監視する非同期イテレータを返します。filename はファイルまたはディレクトリのいずれかです。

const { watch } = require('node:fs/promises');

const ac = new AbortController();
const { signal } = ac;
setTimeout(() => ac.abort(), 10000);

(async () => {
  try {
    const watcher = watch(__filename, { signal });
    for await (const event of watcher)
      console.log(event);
  } catch (err) {
    if (err.name === 'AbortError')
      return;
    throw err;
  }
})(); copy

ほとんどのプラットフォームでは、ディレクトリ内でファイル名が表示されたり消えたりするたびに 'rename' が発行されます。

fs.watch() に関するすべての注意事項は fsPromises.watch() にも適用されます。

fsPromises.writeFile(file, data[, options])#

• file <string> | <Buffer> | <URL> | <FileHandle> ファイル名または FileHandle
• data <string> | <Buffer> | <TypedArray> | <DataView> | <AsyncIterable> | <Iterable> | <Stream>
• options <Object> | <string>
  • encoding <string> | <null> デフォルト: 'utf8'
  • mode <integer> デフォルト: 0o666
  • flag <string> ファイルシステム flags のサポートを参照してください。 デフォルト: 'w'
  • flush <boolean> すべてのデータがファイルに正常に書き込まれ、かつ flush が true の場合、データをフラッシュするために filehandle.sync() が使用されます。 デフォルト: false
  • signal <AbortSignal> 進行中の writeFile を中止できます。
• 戻り値: <Promise> 成功すると undefined で履行されます。

非同期的にファイルにデータを書き込み、ファイルが既に存在する場合は置き換えます。data は文字列、バッファ、<AsyncIterable>、または <Iterable> オブジェクトです。

data がバッファの場合、encoding オプションは無視されます。

options が文字列の場合、それはエンコーディングを指定します。

mode オプションは新しく作成されたファイルにのみ影響します。詳細については、fs.open() を参照してください。

指定された <FileHandle> は書き込みをサポートしている必要があります。

promise が確定するのを待たずに同じファイルに対して fsPromises.writeFile() を複数回使用するのは安全ではありません。

fsPromises.readFile と同様に、fsPromises.writeFile は、渡されたバッファを書き込むために内部で複数の write コールを実行する便利なメソッドです。パフォーマンスが重要なコードでは、fs.createWriteStream() または filehandle.createWriteStream() の使用を検討してください。

<AbortSignal> を使用して fsPromises.writeFile() をキャンセルすることが可能です。キャンセルは「ベストエフォート」であり、ある程度のデータは書き込まれてしまう可能性があります。

import { writeFile } from 'node:fs/promises';
import { Buffer } from 'node:buffer';

try {
  const controller = new AbortController();
  const { signal } = controller;
  const data = new Uint8Array(Buffer.from('Hello Node.js'));
  const promise = writeFile('message.txt', data, { signal });

  // Abort the request before the promise settles.
  controller.abort();

  await promise;
} catch (err) {
  // When a request is aborted - err is an AbortError
  console.error(err);
} copy

進行中のリクエストを中止しても、個々のオペレーティングシステムのリクエストが中止されるわけではなく、fs.writeFile が行う内部バッファリングが中止されます。

fsPromises.constants#

• 型: <Object>

ファイルシステム操作で一般的に使用される定数を含むオブジェクトを返します。オブジェクトは fs.constants と同じです。詳細については、FS 定数を参照してください。

fs.access(path[, mode], callback)#

• path <string> | <Buffer> | <URL>
• mode <integer> デフォルト: fs.constants.F_OK
• callback <Function>
  • `err` <Error>

path で指定されたファイルまたはディレクトリに対するユーザーのアクセス許可をテストします。mode 引数は、実行するアクセシビリティチェックを指定するオプションの整数です。mode は、値 fs.constants.F_OK または fs.constants.R_OK、fs.constants.W_OK、fs.constants.X_OK のいずれかのビットごとの OR からなるマスクである必要があります (例: fs.constants.W_OK | fs.constants.R_OK)。mode の可能な値については、ファイルアクセス定数を確認してください。

最後の引数 callback は、考えられるエラー引数とともに呼び出されるコールバック関数です。アクセシビリティチェックのいずれかが失敗した場合、エラー引数は Error オブジェクトになります。以下の例では、package.json が存在するか、そして読み取り可能か書き込み可能かを確認します。

import { access, constants } from 'node:fs';

const file = 'package.json';

// Check if the file exists in the current directory.
access(file, constants.F_OK, (err) => {
  console.log(`${file} ${err ? 'does not exist' : 'exists'}`);
});

// Check if the file is readable.
access(file, constants.R_OK, (err) => {
  console.log(`${file} ${err ? 'is not readable' : 'is readable'}`);
});

// Check if the file is writable.
access(file, constants.W_OK, (err) => {
  console.log(`${file} ${err ? 'is not writable' : 'is writable'}`);
});

// Check if the file is readable and writable.
access(file, constants.R_OK | constants.W_OK, (err) => {
  console.log(`${file} ${err ? 'is not' : 'is'} readable and writable`);
}); copy

fs.open()、fs.readFile()、または fs.writeFile() を呼び出す前にファイルのアクセシビリティを確認するために fs.access() を使用しないでください。そうすると、2つの呼び出しの間に他のプロセスがファイルの状態を変更する可能性があるため、競合状態が発生します。代わりに、ユーザーコードは直接ファイルを開いたり、読み書きしたりして、ファイルにアクセスできない場合に発生するエラーを処理する必要があります。

書き込み（非推奨）

import { access, open, close } from 'node:fs';

access('myfile', (err) => {
  if (!err) {
    console.error('myfile already exists');
    return;
  }

  open('myfile', 'wx', (err, fd) => {
    if (err) throw err;

    try {
      writeMyData(fd);
    } finally {
      close(fd, (err) => {
        if (err) throw err;
      });
    }
  });
}); copy

書き込み（推奨）

import { open, close } from 'node:fs';

open('myfile', 'wx', (err, fd) => {
  if (err) {
    if (err.code === 'EEXIST') {
      console.error('myfile already exists');
      return;
    }

    throw err;
  }

  try {
    writeMyData(fd);
  } finally {
    close(fd, (err) => {
      if (err) throw err;
    });
  }
}); copy

読み取り（非推奨）

import { access, open, close } from 'node:fs';
access('myfile', (err) => {
  if (err) {
    if (err.code === 'ENOENT') {
      console.error('myfile does not exist');
      return;
    }

    throw err;
  }

  open('myfile', 'r', (err, fd) => {
    if (err) throw err;

    try {
      readMyData(fd);
    } finally {
      close(fd, (err) => {
        if (err) throw err;
      });
    }
  });
}); copy

読み取り（推奨）

import { open, close } from 'node:fs';

open('myfile', 'r', (err, fd) => {
  if (err) {
    if (err.code === 'ENOENT') {
      console.error('myfile does not exist');
      return;
    }

    throw err;
  }

  try {
    readMyData(fd);
  } finally {
    close(fd, (err) => {
      if (err) throw err;
    });
  }
}); copy

上記の「非推奨」の例では、アクセシビリティを確認してからファイルを使用しています。「推奨」の例は、直接ファイルを使用し、もしあればエラーを処理するため、より優れています。

一般的に、ファイルのアクセシビリティを確認するのは、そのファイルを直接使用しない場合、例えばそのアクセシビリティが他のプロセスからのシグナルである場合のみです。

Windows では、ディレクトリのアクセス制御ポリシー（ACL）によってファイルやディレクトリへのアクセスが制限される場合があります。しかし、fs.access() 関数は ACL をチェックしないため、ACL がユーザーによる読み書きを制限している場合でも、パスがアクセス可能であると報告することがあります。

fs.appendFile(path, data[, options], callback)#

• path <string> | <Buffer> | <URL> | <number> ファイル名またはファイル記述子
• data <string> | <Buffer>
• options <Object> | <string>
  • encoding <string> | <null> デフォルト: 'utf8'
  • mode <integer> デフォルト: 0o666
  • flag <string> ファイルシステム flags のサポート を参照してください。デフォルト: 'a'
  • flush <boolean> true の場合、基礎となるファイル記述子は閉じる前にフラッシュされます。デフォルト: false
• callback <Function>
  • `err` <Error>

非同期にファイルにデータを追記し、ファイルが存在しない場合は作成します。data は文字列または <Buffer> にすることができます。

mode オプションは新しく作成されたファイルにのみ影響します。詳細については、fs.open() を参照してください。

import { appendFile } from 'node:fs';

appendFile('message.txt', 'data to append', (err) => {
  if (err) throw err;
  console.log('The "data to append" was appended to file!');
}); copy

options が文字列の場合、それはエンコーディングを指定します。

import { appendFile } from 'node:fs';

appendFile('message.txt', 'data to append', 'utf8', callback); copy

path は、追記用に開かれた（fs.open() または fs.openSync() を使用して）数値ファイル記述子として指定できます。ファイル記述子は自動的に閉じられません。

import { open, close, appendFile } from 'node:fs';

function closeFd(fd) {
  close(fd, (err) => {
    if (err) throw err;
  });
}

open('message.txt', 'a', (err, fd) => {
  if (err) throw err;

  try {
    appendFile(fd, 'data to append', 'utf8', (err) => {
      closeFd(fd);
      if (err) throw err;
    });
  } catch (err) {
    closeFd(fd);
    throw err;
  }
}); copy

fs.chmod(path, mode, callback)#

• path <string> | <Buffer> | <URL>
• mode <string> | <integer>
• callback <Function>
  • `err` <Error>

非同期にファイルのパーミッションを変更します。完了コールバックには、考えられる例外以外の引数は渡されません。

詳細については、POSIX の chmod(2) ドキュメントを参照してください。

import { chmod } from 'node:fs';

chmod('my_file.txt', 0o775, (err) => {
  if (err) throw err;
  console.log('The permissions for file "my_file.txt" have been changed!');
}); copy

fs.chown(path, uid, gid, callback)#

• path <string> | <Buffer> | <URL>
• uid <integer>
• gid <integer>
• callback <Function>
  • `err` <Error>

非同期にファイルの所有者とグループを変更します。完了コールバックには、考えられる例外以外の引数は渡されません。

詳細については、POSIX の chown(2) ドキュメントを参照してください。

fs.close(fd[, callback])#

• fd <integer>
• callback <Function>
  • `err` <Error>

ファイル記述子を閉じます。完了コールバックには、考えられる例外以外の引数は渡されません。

他の fs 操作によって現在使用中のファイル記述子（fd）で fs.close() を呼び出すと、未定義の動作につながる可能性があります。

詳細については、POSIX の close(2) ドキュメントを参照してください。

fs.copyFile(src, dest[, mode], callback)#

• src <string> | <Buffer> | <URL> コピー元のファイル名
• dest <string> | <Buffer> | <URL> コピー操作のコピー先のファイル名
• mode <integer> コピー操作の修飾子。 デフォルト: 0
• callback <Function>
  • `err` <Error>

非同期に src を dest にコピーします。デフォルトでは、dest が既に存在する場合、上書きされます。コールバック関数には、考えられる例外以外の引数は渡されません。Node.js はコピー操作の原子性を保証しません。宛先ファイルが書き込み用に開かれた後にエラーが発生した場合、Node.js は宛先ファイルを削除しようと試みます。

mode は、コピー操作の動作を指定するオプションの整数です。2つ以上の値のビット単位の OR（例：fs.constants.COPYFILE_EXCL | fs.constants.COPYFILE_FICLONE）からなるマスクを作成することが可能です。

• fs.constants.COPYFILE_EXCL: コピー操作は dest が既に存在する場合に失敗します。
• fs.constants.COPYFILE_FICLONE: コピー操作は、コピーオンライトの reflink の作成を試みます。プラットフォームがコピーオンライトをサポートしていない場合、フォールバックのコピーメカニズムが使用されます。
• fs.constants.COPYFILE_FICLONE_FORCE: コピー操作は、コピーオンライトの reflink の作成を試みます。プラットフォームがコピーオンライトをサポートしていない場合、操作は失敗します。

import { copyFile, constants } from 'node:fs';

function callback(err) {
  if (err) throw err;
  console.log('source.txt was copied to destination.txt');
}

// destination.txt will be created or overwritten by default.
copyFile('source.txt', 'destination.txt', callback);

// By using COPYFILE_EXCL, the operation will fail if destination.txt exists.
copyFile('source.txt', 'destination.txt', constants.COPYFILE_EXCL, callback); copy

fs.cp(src, dest[, options], callback)#

• src <string> | <URL> コピーする元のパス。
• dest <string> | <URL> コピー先のパス。
• options <Object>
  • dereference <boolean> シンボリックリンクをデリファレンスします。デフォルト: false
  • errorOnExist <boolean> force が false のとき、コピー先が存在する場合にエラーをスローします。デフォルト: false
  • filter <Function> コピーされるファイル/ディレクトリをフィルタリングする関数。アイテムをコピーするには true を、無視するには false を返します。ディレクトリを無視すると、そのすべての内容もスキップされます。true または false に解決される Promise を返すこともできます。デフォルト: undefined。
    • src <string> コピーする元のパス。
    • dest <string> コピー先のパス。
    • 戻り値: <boolean> | <Promise> boolean に変換可能な値、またはそのような値で履行される Promise。
  • force <boolean> 既存のファイルまたはディレクトリを上書きします。これを false に設定し、コピー先が存在する場合、コピー操作はエラーを無視します。この動作を変更するには errorOnExist オプションを使用します。デフォルト: true
  • mode <integer> コピー操作の修飾子。 デフォルト: 0。fs.copyFile() の mode フラグを参照してください。
  • preserveTimestamps <boolean> true の場合、src のタイムスタンプが保持されます。デフォルト: false
  • recursive <boolean> ディレクトリを再帰的にコピーします。デフォルト: false
  • verbatimSymlinks <boolean> true の場合、シンボリックリンクのパス解決がスキップされます。デフォルト: false
• callback <Function>
  • `err` <Error>

非同期に、サブディレクトリやファイルを含む src から dest へのディレクトリ構造全体をコピーします。

ディレクトリを別のディレクトリにコピーする場合、グロブはサポートされず、動作は cp dir1/ dir2/ に似ています。

fs.createReadStream(path[, options])#

• path <string> | <Buffer> | <URL>
• options <string> | <Object>
  • flags <string> ファイルシステム flags のサポートを参照してください。 デフォルト: 'r'
  • encoding <string> デフォルト: null
  • fd <integer> | <FileHandle> デフォルト: null
  • mode <integer> デフォルト: 0o666
  • autoClose <boolean> デフォルト: true
  • emitClose <boolean> デフォルト: true
  • start <integer>
  • end <integer> デフォルト: Infinity
  • highWaterMark <integer> デフォルト: 64 * 1024
  • fs <Object> | <null> デフォルト: null
  • signal <AbortSignal> | <null> デフォルト: null
• 戻り値: <fs.ReadStream>

options には、ファイル全体ではなくファイルのバイト範囲を読み取るための start と end の値を含めることができます。start と end は両方とも包括的で、0からカウントを開始し、許可される値は [0, Number.MAX_SAFE_INTEGER] の範囲です。fd が指定され、start が省略されるか undefined の場合、fs.createReadStream() は現在のファイル位置から順次読み取ります。encoding は <Buffer> が受け入れるいずれかにすることができます。

fd が指定された場合、ReadStream は path 引数を無視し、指定されたファイル記述子を使用します。これは、'open' イベントが発行されないことを意味します。fd はブロッキングであるべきです。非ブロッキングの fd は <net.Socket> に渡すべきです。

fd がブロッキング読み取りのみをサポートする文字デバイス（キーボードやサウンドカードなど）を指している場合、読み取り操作はデータが利用可能になるまで終了しません。これにより、プロセスが終了せず、ストリームが自然に閉じなくなる可能性があります。

デフォルトでは、ストリームは破棄された後に 'close' イベントを発行します。この動作を変更するには emitClose オプションを false に設定します。

fs オプションを提供することで、対応する open、read、close の fs 実装をオーバーライドすることが可能です。fs オプションを提供する際、read のオーバーライドは必須です。fd が提供されない場合、open のオーバーライドも必須です。autoClose が true の場合、close のオーバーライドも必須です。

import { createReadStream } from 'node:fs';

// Create a stream from some character device.
const stream = createReadStream('/dev/input/event0');
setTimeout(() => {
  stream.close(); // This may not close the stream.
  // Artificially marking end-of-stream, as if the underlying resource had
  // indicated end-of-file by itself, allows the stream to close.
  // This does not cancel pending read operations, and if there is such an
  // operation, the process may still not be able to exit successfully
  // until it finishes.
  stream.push(null);
  stream.read(0);
}, 100); copy

autoClose が false の場合、エラーが発生してもファイル記述子は閉じられません。それを閉じてファイル記述子のリークがないことを確認するのは、アプリケーションの責任です。autoClose が true (デフォルトの動作) に設定されている場合、'error' または 'end' でファイル記述子は自動的に閉じられます。

mode はファイルモード（パーミッションとスティッキービット）を設定しますが、ファイルが作成された場合にのみ設定します。

100 バイト長のファイルの最後の 10 バイトを読み取る例

import { createReadStream } from 'node:fs';

createReadStream('sample.txt', { start: 90, end: 99 }); copy

options が文字列の場合、それはエンコーディングを指定します。

fs.createWriteStream(path[, options])#

• path <string> | <Buffer> | <URL>
• options <string> | <Object>
  • flags <string> ファイルシステム flags のサポートを参照してください。 デフォルト: 'w'
  • encoding <string> デフォルト: 'utf8'
  • fd <integer> | <FileHandle> デフォルト: null
  • mode <integer> デフォルト: 0o666
  • autoClose <boolean> デフォルト: true
  • emitClose <boolean> デフォルト: true
  • start <integer>
  • fs <Object> | <null> デフォルト: null
  • signal <AbortSignal> | <null> デフォルト: null
  • highWaterMark <number> デフォルト: 16384
  • flush <boolean> true の場合、基礎となるファイル記述子は閉じる前にフラッシュされます。デフォルト: false
• 戻り値: <fs.WriteStream>

options には、ファイルの先頭からある位置にデータを書き込むことを許可する start オプションを含めることもできます。許可される値は [0, Number.MAX_SAFE_INTEGER] の範囲です。ファイルを置き換えるのではなく変更する場合、flags オプションをデフォルトの w ではなく r+ に設定する必要がある場合があります。encoding は <Buffer> が受け入れるいずれかにすることができます。

autoClose が true (デフォルトの動作) に設定されている場合、'error' または 'finish' でファイル記述子は自動的に閉じられます。autoClose が false の場合、エラーが発生してもファイル記述子は閉じられません。それを閉じてファイル記述子のリークがないことを確認するのは、アプリケーションの責任です。

デフォルトでは、ストリームは破棄された後に 'close' イベントを発行します。この動作を変更するには emitClose オプションを false に設定します。

fs オプションを提供することで、対応する open、write、writev、close の fs 実装をオーバーライドすることが可能です。writev() なしで write() をオーバーライドすると、一部の最適化（_writev()）が無効になるため、パフォーマンスが低下する可能性があります。fs オプションを提供する際、write と writev の少なくとも一方のオーバーライドは必須です。fd オプションが指定されない場合、open のオーバーライドも必須です。autoClose が true の場合、close のオーバーライドも必須です。

<fs.ReadStream> と同様に、fd が指定された場合、<fs.WriteStream> は path 引数を無視し、指定されたファイル記述子を使用します。これは、'open' イベントが発行されないことを意味します。fd はブロッキングであるべきです。非ブロッキングの fd は <net.Socket> に渡すべきです。

options が文字列の場合、それはエンコーディングを指定します。

fs.exists(path, callback)#

• path <string> | <Buffer> | <URL>
• callback <Function>
  • exists <boolean>

ファイルシステムでチェックすることにより、指定された path の要素が存在するかどうかをテストします。その後、callback 引数を true または false のいずれかで呼び出します。

import { exists } from 'node:fs';

exists('/etc/passwd', (e) => {
  console.log(e ? 'it exists' : 'no passwd!');
}); copy

このコールバックのパラメータは、他の Node.js コールバックと一貫性がありません。通常、Node.js コールバックの最初のパラメータは err パラメータであり、オプションで他のパラメータが続きます。fs.exists() コールバックにはブール型のパラメータが1つしかありません。これが、fs.exists() の代わりに fs.access() が推奨される理由の1つです。

path がシンボリックリンクの場合、それはたどられます。したがって、path が存在しても存在しない要素を指している場合、コールバックは値 false を受け取ります。

fs.open()、fs.readFile()、または fs.writeFile() を呼び出す前にファイルの存在を確認するために fs.exists() を使用することは推奨されません。そうすると、2つの呼び出しの間に他のプロセスがファイルの状態を変更する可能性があるため、競合状態が発生します。代わりに、ユーザーコードは直接ファイルを開いたり、読み書きしたりして、ファイルが存在しない場合に発生するエラーを処理する必要があります。

書き込み（非推奨）

import { exists, open, close } from 'node:fs';

exists('myfile', (e) => {
  if (e) {
    console.error('myfile already exists');
  } else {
    open('myfile', 'wx', (err, fd) => {
      if (err) throw err;

      try {
        writeMyData(fd);
      } finally {
        close(fd, (err) => {
          if (err) throw err;
        });
      }
    });
  }
}); copy

書き込み（推奨）

import { open, close } from 'node:fs';
open('myfile', 'wx', (err, fd) => {
  if (err) {
    if (err.code === 'EEXIST') {
      console.error('myfile already exists');
      return;
    }

    throw err;
  }

  try {
    writeMyData(fd);
  } finally {
    close(fd, (err) => {
      if (err) throw err;
    });
  }
}); copy

読み取り（非推奨）

import { open, close, exists } from 'node:fs';

exists('myfile', (e) => {
  if (e) {
    open('myfile', 'r', (err, fd) => {
      if (err) throw err;

      try {
        readMyData(fd);
      } finally {
        close(fd, (err) => {
          if (err) throw err;
        });
      }
    });
  } else {
    console.error('myfile does not exist');
  }
}); copy

読み取り（推奨）

import { open, close } from 'node:fs';

open('myfile', 'r', (err, fd) => {
  if (err) {
    if (err.code === 'ENOENT') {
      console.error('myfile does not exist');
      return;
    }

    throw err;
  }

  try {
    readMyData(fd);
  } finally {
    close(fd, (err) => {
      if (err) throw err;
    });
  }
}); copy

上記の「非推奨」の例では、存在を確認してからファイルを使用しています。「推奨」の例は、直接ファイルを使用し、もしあればエラーを処理するため、より優れています。

一般的に、ファイルの存在を確認するのは、そのファイルを直接使用しない場合、例えばその存在が他のプロセスからのシグナルである場合のみです。

fs.fchmod(fd, mode, callback)#

• fd <integer>
• mode <string> | <integer>
• callback <Function>
  • `err` <Error>

ファイルのパーミッションを設定します。完了コールバックには、考えられる例外以外の引数は渡されません。

詳細については、POSIX の fchmod(2) ドキュメントを参照してください。

fs.fchown(fd, uid, gid, callback)#

• fd <integer>
• uid <integer>
• gid <integer>
• callback <Function>
  • `err` <Error>

ファイルの所有者を設定します。完了コールバックには、考えられる例外以外の引数は渡されません。

詳細については、POSIX の fchown(2) ドキュメントを参照してください。

fs.fdatasync(fd, callback)#

• fd <integer>
• callback <Function>
  • `err` <Error>

ファイルに関連付けられている現在キューに入れられているすべての I/O 操作を、オペレーティングシステムの同期 I/O 完了状態に強制します。詳細については、POSIX の fdatasync(2) ドキュメントを参照してください。完了コールバックには、考えられる例外以外の引数は渡されません。

fs.fstat(fd[, options], callback)#

• fd <integer>
• options <Object>
  • bigint <boolean> 返される <fs.Stats> オブジェクトの数値が bigint であるべきかどうか。デフォルト: false
• callback <Function>
  • `err` <Error>
  • stats <fs.Stats>

ファイル記述子の <fs.Stats> でコールバックを呼び出します。

詳細については、POSIX の fstat(2) ドキュメントを参照してください。

fs.fsync(fd, callback)#

• fd <integer>
• callback <Function>
  • `err` <Error>

開いているファイル記述子のすべてのデータをストレージデバイスにフラッシュするように要求します。具体的な実装はオペレーティングシステムとデバイスに依存します。詳細については、POSIX の fsync(2) ドキュメントを参照してください。完了コールバックには、考えられる例外以外の引数は渡されません。

fs.ftruncate(fd[, len], callback)#

• fd <integer>
• len <integer> デフォルト: 0
• callback <Function>
  • `err` <Error>

ファイル記述子を切り詰めます。完了コールバックには、考えられる例外以外の引数は渡されません。

詳細については、POSIX の ftruncate(2) ドキュメントを参照してください。

ファイル記述子が参照するファイルが len バイトより大きかった場合、最初の len バイトのみがファイルに保持されます。

たとえば、次のプログラムはファイルの最初の4バイトのみを保持します。

import { open, close, ftruncate } from 'node:fs';

function closeFd(fd) {
  close(fd, (err) => {
    if (err) throw err;
  });
}

open('temp.txt', 'r+', (err, fd) => {
  if (err) throw err;

  try {
    ftruncate(fd, 4, (err) => {
      closeFd(fd);
      if (err) throw err;
    });
  } catch (err) {
    closeFd(fd);
    if (err) throw err;
  }
}); copy

ファイルが以前 len バイトより短かった場合、それは拡張され、拡張された部分はヌルバイト ('\0') で埋められます。

len が負の場合、0 が使用されます。

fs.futimes(fd, atime, mtime, callback)#

• fd <integer>
• atime <number> | <string> | <Date>
• mtime <number> | <string> | <Date>
• callback <Function>
  • `err` <Error>

指定されたファイル記述子が参照するオブジェクトのファイルシステムタイムスタンプを変更します。fs.utimes() を参照してください。

fs.glob(pattern[, options], callback)#

• pattern <string> | <string[]>

• options <Object>

  • cwd <string> | <URL> 現在の作業ディレクトリ。デフォルト: process.cwd()
  • exclude <Function> | <string[]> ファイル/ディレクトリを除外するための関数、または除外するグロブパターンのリスト。関数が提供された場合、項目を除外するには true を、含めるには false を返します。 デフォルト: undefined
  • withFileTypes <boolean> グロブがパスを Dirent として返す場合は true、それ以外は false。デフォルト: false

• callback <Function>

  • `err` <Error>

• 指定されたパターンに一致するファイルを取得します。

import { glob } from 'node:fs';

glob('**/*.js', (err, matches) => {
  if (err) throw err;
  console.log(matches);
});const { glob } = require('node:fs');

glob('**/*.js', (err, matches) => {
  if (err) throw err;
  console.log(matches);
});copy

fs.lchmod(path, mode, callback)#

• path <string> | <Buffer> | <URL>
• mode <integer>
• callback <Function>
  • err <Error> | <AggregateError>

シンボリックリンクのパーミッションを変更します。完了コールバックには、考えられる例外以外の引数は渡されません。

このメソッドは macOS でのみ実装されています。

詳細については、POSIX の lchmod(2) ドキュメントを参照してください。

fs.lchown(path, uid, gid, callback)#

• path <string> | <Buffer> | <URL>
• uid <integer>
• gid <integer>
• callback <Function>
  • `err` <Error>

シンボリックリンクの所有者を設定します。完了コールバックには、考えられる例外以外の引数は渡されません。

詳細については、POSIX の lchown(2) ドキュメントを参照してください。

fs.lutimes(path, atime, mtime, callback)#

• path <string> | <Buffer> | <URL>
• atime <number> | <string> | <Date>
• mtime <number> | <string> | <Date>
• callback <Function>
  • `err` <Error>

fs.utimes() と同様にファイルのアクセス時刻と変更時刻を変更しますが、パスがシンボリックリンクを参照している場合、リンクはデリファレンスされず、代わりにシンボリックリンク自体のタイムスタンプが変更される点が異なります。

完了コールバックには、考えられる例外以外の引数は渡されません。

fs.link(existingPath, newPath, callback)#

• existingPath <string> | <Buffer> | <URL>
• newPath <string> | <Buffer> | <URL>
• callback <Function>
  • `err` <Error>

existingPath から newPath への新しいリンクを作成します。詳細については、POSIX の link(2) ドキュメントを参照してください。完了コールバックには、考えられる例外以外の引数は渡されません。

fs.lstat(path[, options], callback)#

• path <string> | <Buffer> | <URL>
• options <Object>
  • bigint <boolean> 返される <fs.Stats> オブジェクトの数値が bigint であるべきかどうか。デフォルト: false
• callback <Function>
  • `err` <Error>
  • stats <fs.Stats>

パスが参照するシンボリックリンクの <fs.Stats> を取得します。コールバックは2つの引数 (err, stats) を受け取ります。ここで stats は <fs.Stats> オブジェクトです。lstat() は stat() と同じですが、path がシンボリックリンクの場合、それが参照するファイルではなく、リンク自体が stat されます。

詳細については、POSIX の lstat(2) ドキュメントを参照してください。

fs.mkdir(path[, options], callback)#

• path <string> | <Buffer> | <URL>
• options <Object> | <integer>
  • recursive <boolean> デフォルト: false
  • mode <string> | <integer> Windows ではサポートされていません。デフォルト: 0o777。
• callback <Function>
  • `err` <Error>
  • path <string> | <undefined> recursive を true に設定してディレクトリが作成された場合にのみ存在します。

非同期にディレクトリを作成します。

コールバックには、考えられる例外と、recursive が true の場合は最初に作成されたディレクトリパス (err[, path]) が渡されます。recursive が true であっても、ディレクトリが作成されなかった場合（たとえば、以前に作成されていた場合）は path が undefined になることがあります。

オプションの options 引数は、mode（パーミッションとスティッキービット）を指定する整数、または親ディレクトリを作成すべきかどうかを示す recursive プロパティと mode プロパティを持つオブジェクトにすることができます。path が存在するディレクトリである場合に fs.mkdir() を呼び出すと、recursive が false の場合にのみエラーになります。recursive が false でディレクトリが存在する場合、EEXIST エラーが発生します。

import { mkdir } from 'node:fs';

// Create ./tmp/a/apple, regardless of whether ./tmp and ./tmp/a exist.
mkdir('./tmp/a/apple', { recursive: true }, (err) => {
  if (err) throw err;
}); copy

Windows では、再帰を指定してもルートディレクトリで fs.mkdir() を使用するとエラーになります。

import { mkdir } from 'node:fs';

mkdir('/', { recursive: true }, (err) => {
  // => [Error: EPERM: operation not permitted, mkdir 'C:\']
}); copy

詳細については、POSIX の mkdir(2) ドキュメントを参照してください。

fs.mkdtemp(prefix[, options], callback)#

• prefix <string> | <Buffer> | <URL>
• options <string> | <Object>
  • encoding <string> デフォルト: 'utf8'
• callback <Function>
  • `err` <Error>
  • directory <string>

一意の一時ディレクトリを作成します。

必須の prefix の後ろに追加される6つのランダムな文字を生成し、一意の一時ディレクトリを作成します。プラットフォームの不整合のため、prefix の末尾に X 文字を付けないでください。一部のプラットフォーム、特に BSD では、6文字以上のランダムな文字が返され、prefix の末尾の X 文字がランダムな文字に置き換えられることがあります。

作成されたディレクトリパスは、コールバックの2番目のパラメータに文字列として渡されます。

オプションの options 引数は、エンコーディングを指定する文字列、または使用する文字エンコーディングを指定する encoding プロパティを持つオブジェクトにすることができます。

import { mkdtemp } from 'node:fs';
import { join } from 'node:path';
import { tmpdir } from 'node:os';

mkdtemp(join(tmpdir(), 'foo-'), (err, directory) => {
  if (err) throw err;
  console.log(directory);
  // Prints: /tmp/foo-itXde2 or C:\Users\...\AppData\Local\Temp\foo-itXde2
}); copy

fs.mkdtemp() メソッドは、ランダムに選択された6文字を prefix 文字列に直接追加します。たとえば、/tmp ディレクトリが与えられた場合、/tmp 内に一時ディレクトリを作成することが目的であれば、prefix はプラットフォーム固有のパス区切り文字（require('node:path').sep）で終わる必要があります。

import { tmpdir } from 'node:os';
import { mkdtemp } from 'node:fs';

// The parent directory for the new temporary directory
const tmpDir = tmpdir();

// This method is *INCORRECT*:
mkdtemp(tmpDir, (err, directory) => {
  if (err) throw err;
  console.log(directory);
  // Will print something similar to `/tmpabc123`.
  // A new temporary directory is created at the file system root
  // rather than *within* the /tmp directory.
});

// This method is *CORRECT*:
import { sep } from 'node:path';
mkdtemp(`${tmpDir}${sep}`, (err, directory) => {
  if (err) throw err;
  console.log(directory);
  // Will print something similar to `/tmp/abc123`.
  // A new temporary directory is created within
  // the /tmp directory.
}); copy

fs.open(path[, flags[, mode]], callback)#

• path <string> | <Buffer> | <URL>
• flags <string> | <number> ファイルシステム flags のサポート を参照してください。デフォルト: 'r'
• mode <string> | <integer> デフォルト: 0o666（読み書き可能）
• callback <Function>
  • `err` <Error>
  • fd <integer>

非同期ファイルオープン。詳細については、POSIX の open(2) ドキュメントを参照してください。

mode はファイルモード（パーミッションとスティッキービット）を設定しますが、ファイルが作成された場合にのみ設定します。Windows では、書き込みパーミッションのみ操作できます。fs.chmod() を参照してください。

コールバックは2つの引数 (err, fd) を受け取ります。

一部の文字 (< > : " / \ | ? *) は、ファイル、パス、および名前空間の命名で文書化されているように、Windows で予約されています。NTFS では、ファイル名にコロンが含まれている場合、Node.js は この MSDN ページで説明されているように、ファイルシステムストリームを開きます。

fs.open() に基づく関数もこの動作を示します： fs.writeFile()、fs.readFile() など。

fs.openAsBlob(path[, options])#

• path <string> | <Buffer> | <URL>
• options <Object>
  • type <string> BLOB のオプションの MIME タイプ。
• 戻り値: <Promise> 成功すると <Blob> で fulfill されます。

指定されたファイルによってデータがバックアップされる <Blob> を返します。

<Blob> が作成された後、ファイルは変更されてはなりません。いかなる変更も、<Blob> データの読み取りが DOMException エラーで失敗する原因となります。Blob が作成されたとき、およびファイルデータがディスク上で変更されたかどうかを検出するために各読み取りの前に、ファイルに対して同期 stat 操作が行われます。

import { openAsBlob } from 'node:fs';

const blob = await openAsBlob('the.file.txt');
const ab = await blob.arrayBuffer();
blob.stream();const { openAsBlob } = require('node:fs');

(async () => {
  const blob = await openAsBlob('the.file.txt');
  const ab = await blob.arrayBuffer();
  blob.stream();
})();copy

fs.opendir(path[, options], callback)#

• path <string> | <Buffer> | <URL>
• options <Object>
  • encoding <string> | <null> デフォルト: 'utf8'
  • bufferSize <number> ディレクトリから読み取るときに内部的にバッファリングされるディレクトリエンティティの数。値が高いほどパフォーマンスは向上しますが、メモリ使用量も高くなります。デフォルト: 32
  • recursive <boolean> デフォルト: false
• callback <Function>
  • `err` <Error>
  • dir <fs.Dir>

非同期にディレクトリを開きます。詳細については、POSIX の opendir(3) ドキュメントを参照してください。

ディレクトリからの読み取りとクリーンアップのためのすべてのさらなる関数を含む <fs.Dir> を作成します。

encoding オプションは、ディレクトリを開くときと後続の読み取り操作で path のエンコーディングを設定します。

fs.read(fd, buffer, offset, length, position, callback)#

• fd <integer>
• buffer <Buffer> | <TypedArray> | <DataView> データが書き込まれるバッファ。
• offset <integer> データを書き込む buffer 内の位置。
• length <integer> 読み取るバイト数。
• position <integer> | <bigint> | <null> ファイル内のどこから読み取りを開始するかを指定します。position が null または -1 の場合、データは現在のファイル位置から読み取られ、ファイル位置が更新されます。position が非負の整数の場合、ファイル位置は変更されません。
• callback <Function>
  • `err` <Error>
  • bytesRead <integer>
  • buffer <Buffer>

fd で指定されたファイルからデータを読み取ります。

コールバックには3つの引数 (err, bytesRead, buffer) が渡されます。

ファイルが同時に変更されない場合、読み取られたバイト数がゼロになるとファイルの終わりに達します。

このメソッドが util.promisify() されたバージョンとして呼び出された場合、bytesRead と buffer プロパティを持つ Object の promise を返します。

fs.read() メソッドは、ファイル記述子（fd）で指定されたファイルからデータを読み取ります。length 引数は、Node.js がカーネルから読み取ろうとする最大バイト数を示します。しかし、実際に読み取られるバイト数（bytesRead）は、さまざまな理由で指定された length よりも少なくなることがあります。

例:

• ファイルが指定された length より短い場合、bytesRead は実際に読み取られたバイト数に設定されます。
• バッファが埋まる前にファイルが EOF（End of File）に達した場合、Node.js は EOF に達するまで利用可能なすべてのバイトを読み取り、コールバックの bytesRead パラメータは実際に読み取られたバイト数を示し、これは指定された length より少ない場合があります。
• ファイルが低速なネットワーク filesystem 上にあるか、読み取り中に他の問題が発生した場合、bytesRead は指定された length よりも少なくなることがあります。

したがって、fs.read() を使用する場合、bytesRead の値をチェックして、ファイルから実際に何バイト読み取られたかを確認することが重要です。アプリケーションのロジックによっては、最小限のバイト数が必要な場合は読み取り呼び出しをループでラップするなど、bytesRead が指定された length よりも少ない場合のケースを処理する必要があるかもしれません。

この動作は POSIX の preadv2 関数に似ています。

fs.read(fd[, options], callback)#

• fd <integer>
• options <Object>
  • buffer <Buffer> | <TypedArray> | <DataView> デフォルト: Buffer.alloc(16384)
  • offset <integer> デフォルト: 0
  • length <integer> デフォルト: buffer.byteLength - offset
  • position <integer> | <bigint> | <null> デフォルト: null
• callback <Function>
  • `err` <Error>
  • bytesRead <integer>
  • buffer <Buffer>

fs.read() 関数と同様に、このバージョンはオプションの options オブジェクトを取ります。options オブジェクトが指定されていない場合、上記の値でデフォルト設定されます。

fs.read(fd, buffer[, options], callback)#

• fd <integer>
• buffer <Buffer> | <TypedArray> | <DataView> データが書き込まれるバッファ。
• options <Object>
  • offset <integer> デフォルト: 0
  • length <integer> デフォルト: buffer.byteLength - offset
  • position <integer> | <bigint> デフォルト: null
• callback <Function>
  • `err` <Error>
  • bytesRead <integer>
  • buffer <Buffer>

fs.read() 関数と同様に、このバージョンはオプションの options オブジェクトを取ります。options オブジェクトが指定されていない場合、上記の値でデフォルト設定されます。

fs.readdir(path[, options], callback)#

• path <string> | <Buffer> | <URL>
• options <string> | <Object>
  • encoding <string> デフォルト: 'utf8'
  • withFileTypes <boolean> デフォルト: false
  • recursive <boolean> true の場合、ディレクトリの内容を再帰的に読み取ります。再帰モードでは、すべてのファイル、サブファイル、ディレクトリを一覧表示します。 デフォルト: false
• callback <Function>
  • `err` <Error>
  • files <string[]> | <Buffer[]> | <fs.Dirent[]>

ディレクトリの内容を読み取ります。コールバックは2つの引数 (err, files) を受け取ります。ここで files は、'.' と '..' を除くディレクトリ内のファイル名の配列です。

詳細については、POSIX の readdir(3) ドキュメントを参照してください。

オプションの options 引数は、エンコーディングを指定する文字列、またはコールバックに渡されるファイル名に使用する文字エンコーディングを指定する encoding プロパティを持つオブジェクトにすることができます。encoding が 'buffer' に設定されている場合、返されるファイル名は <Buffer> オブジェクトとして渡されます。

options.withFileTypes が true に設定されている場合、files 配列には <fs.Dirent> オブジェクトが含まれます。

fs.readFile(path[, options], callback)#

• path <string> | <Buffer> | <URL> | <integer> ファイル名またはファイル記述子
• options <Object> | <string>
  • encoding <string> | <null> デフォルト: null
  • flag <string> ファイルシステム flags のサポートを参照してください。 デフォルト: 'r'
  • signal <AbortSignal> 進行中の readFile を中止できます。
• callback <Function>
  • err <Error> | <AggregateError>
  • data <string> | <Buffer>

ファイルの内容全体を非同期に読み取ります。

import { readFile } from 'node:fs';

readFile('/etc/passwd', (err, data) => {
  if (err) throw err;
  console.log(data);
}); copy

コールバックには2つの引数 (err, data) が渡されます。ここで data はファイルの内容です。

エンコーディングが指定されていない場合、生のバッファが返されます。

options が文字列の場合、それはエンコーディングを指定します。

import { readFile } from 'node:fs';

readFile('/etc/passwd', 'utf8', callback); copy

パスがディレクトリの場合、fs.readFile() と fs.readFileSync() の動作はプラットフォーム固有です。macOS、Linux、Windows ではエラーが返されます。FreeBSD では、ディレクトリの内容の表現が返されます。

import { readFile } from 'node:fs';

// macOS, Linux, and Windows
readFile('<directory>', (err, data) => {
  // => [Error: EISDIR: illegal operation on a directory, read <directory>]
});

//  FreeBSD
readFile('<directory>', (err, data) => {
  // => null, <data>
}); copy

AbortSignal を使用して進行中のリクエストを中止することが可能です。リクエストが中止された場合、コールバックは AbortError で呼び出されます。

import { readFile } from 'node:fs';

const controller = new AbortController();
const signal = controller.signal;
readFile(fileInfo[0].name, { signal }, (err, buf) => {
  // ...
});
// When you want to abort the request
controller.abort(); copy

fs.readFile() 関数はファイル全体をバッファリングします。メモリコストを最小限に抑えるため、可能であれば fs.createReadStream() を介したストリーミングを優先してください。

進行中のリクエストを中止しても、個々のオペレーティングシステムのリクエストが中止されるわけではなく、fs.readFile が行う内部バッファリングが中止されます。

fs.readlink(path[, options], callback)#

• path <string> | <Buffer> | <URL>
• options <string> | <Object>
  • encoding <string> デフォルト: 'utf8'
• callback <Function>
  • `err` <Error>
  • linkString <string> | <Buffer>

path が参照するシンボリックリンクの内容を読み取ります。コールバックは2つの引数 (err, linkString) を受け取ります。

詳細については、POSIX の readlink(2) ドキュメントを参照してください。

オプションの options 引数は、エンコーディングを指定する文字列、またはコールバックに渡されるリンクパスに使用する文字エンコーディングを指定する encoding プロパティを持つオブジェクトにすることができます。encoding が 'buffer' に設定されている場合、返されるリンクパスは <Buffer> オブジェクトとして渡されます。

fs.readv(fd, buffers[, position], callback)#

• fd <integer>
• buffers <ArrayBufferView[]>
• position <integer> | <null> デフォルト: null
• callback <Function>
  • `err` <Error>
  • bytesRead <integer>
  • buffers <ArrayBufferView[]>

fd で指定されたファイルから読み取り、readv() を使用して ArrayBufferView の配列に書き込みます。

position は、データの読み取りを開始するファイルの先頭からのオフセットです。typeof position !== 'number' の場合、データは現在の位置から読み取られます。

コールバックには3つの引数が渡されます： err、bytesRead、buffers。bytesRead はファイルから読み取られたバイト数です。

このメソッドが util.promisify() 化されたバージョンとして呼び出された場合、bytesRead と buffers プロパティを持つ Object の Promise を返します。

fs.realpath(path[, options], callback)#

• path <string> | <Buffer> | <URL>
• options <string> | <Object>
  • encoding <string> デフォルト: 'utf8'
• callback <Function>
  • `err` <Error>
  • resolvedPath <string> | <Buffer>

.、..、およびシンボリックリンクを解決することにより、正規のパス名を非同期に計算します。

正規のパス名は必ずしも一意ではありません。ハードリンクやバインドマウントは、ファイルシステムエンティティを多くのパス名を通して公開できます。

この関数はいくつかの例外を除き、realpath(3) のように動作します。

1. 大文字と小文字を区別しないファイルシステムでは、大文字小文字の変換は行われません。

2. シンボリックリンクの最大数はプラットフォームに依存せず、一般的にネイティブの realpath(3) 実装がサポートするものよりも（はるかに）高くなっています。

callback は (err, resolvedPath) の2つの引数を取ります。相対パスを解決するために process.cwd を使用する場合があります。

UTF8 文字列に変換できるパスのみがサポートされています。

オプションの options 引数は、エンコーディングを指定する文字列、またはコールバックに渡されるパスに使用する文字エンコーディングを指定する encoding プロパティを持つオブジェクトです。encoding が 'buffer' に設定されている場合、返されるパスは <Buffer> オブジェクトとして渡されます。

path がソケットまたはパイプに解決される場合、この関数はそのオブジェクトのシステム依存の名前を返します。

存在しないパスは ENOENT エラーになります。error.path は絶対ファイルパスです。

fs.realpath.native(path[, options], callback)#

• path <string> | <Buffer> | <URL>
• options <string> | <Object>
  • encoding <string> デフォルト: 'utf8'
• callback <Function>
  • `err` <Error>
  • resolvedPath <string> | <Buffer>

非同期の realpath(3) です。

callback は (err, resolvedPath) の2つの引数を取ります。

UTF8 文字列に変換できるパスのみがサポートされています。

オプションの options 引数は、エンコーディングを指定する文字列、またはコールバックに渡されるパスに使用する文字エンコーディングを指定する encoding プロパティを持つオブジェクトです。encoding が 'buffer' に設定されている場合、返されるパスは <Buffer> オブジェクトとして渡されます。

Linux では、Node.js が musl libc に対してリンクされている場合、この関数が機能するためには procfs ファイルシステムが /proc にマウントされている必要があります。Glibc にはこの制限はありません。

fs.rename(oldPath, newPath, callback)#

• oldPath <string> | <Buffer> | <URL>
• newPath <string> | <Buffer> | <URL>
• callback <Function>
  • `err` <Error>

oldPath のファイルを newPath として提供されたパス名に非同期で名前変更します。newPath が既に存在する場合、上書きされます。newPath にディレクトリがある場合、代わりにエラーが発生します。完了コールバックには、考えられる例外以外の引数は与えられません。

参照: rename(2)。

import { rename } from 'node:fs';

rename('oldFile.txt', 'newFile.txt', (err) => {
  if (err) throw err;
  console.log('Rename complete!');
}); copy

fs.rmdir(path[, options], callback)#

• path <string> | <Buffer> | <URL>
• options <Object> 現在公開されているオプションはありません。以前は recursive、maxBusyTries、emfileWait のオプションがありましたが、それらは非推奨となり削除されました。options 引数は後方互換性のためにまだ受け入れられていますが、使用されません。
• callback <Function>
  • `err` <Error>

非同期の rmdir(2) です。完了コールバックには、考えられる例外以外の引数は与えられません。

ファイル（ディレクトリではない）に対して fs.rmdir() を使用すると、Windows では ENOENT エラー、POSIX では ENOTDIR エラーになります。

Unix コマンド rm -rf と同様の動作を得るには、オプション { recursive: true, force: true } を付けて fs.rm() を使用してください。

fs.rm(path[, options], callback)#

• path <string> | <Buffer> | <URL>
• options <Object>
  • force <boolean> true の場合、path が存在しなくても例外は無視されます。 デフォルト: false
  • maxRetries <integer> EBUSY、EMFILE、ENFILE、ENOTEMPTY、または EPERM エラーが発生した場合、Node.js は毎回 retryDelay ミリ秒長い線形バックオフ待機時間で操作を再試行します。このオプションは再試行の回数を表します。このオプションは recursive オプションが true でない場合は無視されます。 デフォルト: 0
  • recursive <boolean> true の場合、再帰的な削除を実行します。再帰モードでは、失敗した操作は再試行されます。デフォルト: false。
  • retryDelay <integer> 再試行の間に待機する時間（ミリ秒単位）。このオプションは recursive オプションが true でない場合は無視されます。 デフォルト: 100
• callback <Function>
  • `err` <Error>

ファイルとディレクトリを非同期に削除します（標準の POSIX rm ユーティリティをモデルにしています）。完了コールバックには、考えられる例外以外の引数は与えられません。

fs.stat(path[, options], callback)#

• path <string> | <Buffer> | <URL>
• options <Object>
  • bigint <boolean> 返される <fs.Stats> オブジェクトの数値が bigint であるべきかどうか。デフォルト: false
• callback <Function>
  • `err` <Error>
  • stats <fs.Stats>

非同期の stat(2) です。コールバックは (err, stats) の2つの引数を取ります。ここで stats は <fs.Stats> オブジェクトです。

エラーの場合、err.code は 共通システムエラー のいずれかになります。

fs.stat() はシンボリックリンクをたどります。リンク自体を調べるには fs.lstat() を使用してください。

fs.open()、fs.readFile()、または fs.writeFile() を呼び出す前にファイルの存在を確認するために fs.stat() を使用することは推奨されません。代わりに、ユーザーコードは直接ファイルを開く/読む/書くべきであり、ファイルが利用できない場合に発生するエラーを処理する必要があります。

ファイルを操作せずにその存在を確認するには、fs.access() が推奨されます。

例えば、以下のディレクトリ構造があるとします。

- txtDir
-- file.txt
- app.js copy

次のプログラムは、与えられたパスの stats をチェックします。

import { stat } from 'node:fs';

const pathsToCheck = ['./txtDir', './txtDir/file.txt'];

for (let i = 0; i < pathsToCheck.length; i++) {
  stat(pathsToCheck[i], (err, stats) => {
    console.log(stats.isDirectory());
    console.log(stats);
  });
} copy

結果の出力は次のようになります。

true
Stats {
  dev: 16777220,
  mode: 16877,
  nlink: 3,
  uid: 501,
  gid: 20,
  rdev: 0,
  blksize: 4096,
  ino: 14214262,
  size: 96,
  blocks: 0,
  atimeMs: 1561174653071.963,
  mtimeMs: 1561174614583.3518,
  ctimeMs: 1561174626623.5366,
  birthtimeMs: 1561174126937.2893,
  atime: 2019-06-22T03:37:33.072Z,
  mtime: 2019-06-22T03:36:54.583Z,
  ctime: 2019-06-22T03:37:06.624Z,
  birthtime: 2019-06-22T03:28:46.937Z
}
false
Stats {
  dev: 16777220,
  mode: 33188,
  nlink: 1,
  uid: 501,
  gid: 20,
  rdev: 0,
  blksize: 4096,
  ino: 14214074,
  size: 8,
  blocks: 8,
  atimeMs: 1561174616618.8555,
  mtimeMs: 1561174614584,
  ctimeMs: 1561174614583.8145,
  birthtimeMs: 1561174007710.7478,
  atime: 2019-06-22T03:36:56.619Z,
  mtime: 2019-06-22T03:36:54.584Z,
  ctime: 2019-06-22T03:36:54.584Z,
  birthtime: 2019-06-22T03:26:47.711Z
} copy

fs.statfs(path[, options], callback)#

• path <string> | <Buffer> | <URL>
• options <Object>
  • bigint <boolean> 返される <fs.StatFs> オブジェクトの数値が bigint であるべきかどうか。 デフォルト: false
• callback <Function>
  • `err` <Error>
  • stats <fs.StatFs>

非同期の statfs(2) です。path を含むマウントされたファイルシステムの情報を返します。コールバックは (err, stats) の2つの引数を取ります。ここで stats は <fs.StatFs> オブジェクトです。