Класс: 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

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 (например, fs.constants.W_OK | fs.constants.R_OK). Возможные значения mode см. в разделе Константы доступа к файлам.

Если проверка доступности завершилась успешно, промис выполняется без значения. Если одна или несколько проверок доступности завершаются неудачно, промис отклоняется с объектом <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.access() для проверки доступности файла перед вызовом fsPromises.open(). Это приводит к состоянию гонки, поскольку другие процессы могут изменить состояние файла между двумя вызовами. Вместо этого пользовательский код должен напрямую открывать, читать или записывать файл и обрабатывать ошибку, возникающую, если файл недоступен.

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> Необязательные модификаторы, задающие поведение операции копирования. Можно создать маску, выполнив побитовое ИЛИ для двух или более значений (например, 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, чтобы пропустить его. При пропуске каталога пропускается и всё его содержимое. Также можно вернуть Promise, который разрешается в true или false По умолчанию: undefined.
    • src <string> исходный путь для копирования.
    • dest <string> путь назначения для копирования.
    • Возвращает: <boolean> | <Promise> Значение, преобразуемое в boolean, или Promise, который выполняется с таким значением.
  • force <boolean> перезаписывать существующий файл или каталог. Если задать значение false и целевой объект существует, операция копирования будет игнорировать ошибки. Чтобы изменить это поведение, используйте параметр errorOnExist. По умолчанию: true.
  • mode <integer> модификаторы операции копирования. По умолчанию: 0. См. флаг mode функции fsPromises.copyFile().
  • preserveTimestamps <boolean> При значении true временные метки из src будут сохранены. По умолчанию: false.
  • recursive <boolean> рекурсивно копировать каталоги По умолчанию: false
  • verbatimSymlinks <boolean> Если задано значение true, разрешение путей для символических ссылок будет пропущено. По умолчанию: false
• Возвращает: <Promise> В случае успеха выполняется с undefined.

Асинхронно копирует всю структуру каталогов из src в dest, включая подкаталоги и файлы.

При копировании каталога в другой каталог glob-шаблоны не поддерживаются, а поведение аналогично cp dir1/ dir2/.

fsPromises.glob(pattern[, options])

• pattern <string> | <string[]>
• options <Object>
  • cwd <string> | <URL> текущий рабочий каталог. По умолчанию: process.cwd()
  • exclude <Function> | <string[]> Функция для фильтрации файлов и каталогов или список glob-шаблонов для исключения. Если указана функция, верните true, чтобы исключить элемент, или false, чтобы включить его. По умолчанию: undefined. Если указан массив строк, каждая строка должна быть glob-шаблоном, задающим пути для исключения. Примечание: шаблоны отрицания (например, '!foo.js') не поддерживаются.
  • withFileTypes <boolean> true, если glob должен возвращать пути в виде Dirent, и false в противном случае. По умолчанию: false.
• Возвращает: <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);
})();

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> При успешном выполнении разрешается объектом <fs.Stats> для указанной символической ссылки path.

Эквивалентно fsPromises.stat(), если только path не указывает на символическую ссылку; в этом случае сведения извлекаются о самой ссылке, а не о файле, на который она указывает. Дополнительные сведения см. в документации POSIX для lstat(2).

fsPromises.mkdir(path[, options])

• path <string> | <Buffer> | <URL>
• options <Object> | <integer>
  • recursive <boolean> По умолчанию: false
  • mode <string> | <integer> Не поддерживается в Windows. Дополнительные сведения см. в разделе Режимы доступа к файлам. По умолчанию: 0o777.
• Возвращает: <Promise> При успешном выполнении разрешается значением undefined, если recursive имеет значение false, либо путём первого созданного каталога, если recursive имеет значение true.

Асинхронно создаёт каталог.

Необязательный аргумент options может быть целым числом, задающим mode (биты разрешений и sticky-биты), или объектом со свойством mode и свойством recursive, указывающим, следует ли создавать родительские каталоги. Вызов fsPromises.mkdir(), когда path — уже существующий каталог, приводит к отклонению промиса только в том случае, если 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);

fsPromises.mkdtemp(prefix[, options])

• prefix <string> | <Buffer> | <URL>
• options <string> | <Object>
  • encoding <string> По умолчанию: 'utf8'
• Возвращает: <Promise> При успешном выполнении разрешается строкой, содержащей путь в файловой системе к созданному временному каталогу.

Создаёт уникальный временный каталог. Уникальное имя каталога формируется добавлением шести случайных символов в конец указанного prefix. Из-за различий между платформами не используйте завершающие символы X в prefix. Некоторые платформы, в частности BSD, могут возвращать более шести случайных символов и заменять завершающие символы X в prefix случайными символами.

Необязательный аргумент 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() добавляет шесть случайно выбранных символов непосредственно к строке prefix. Например, если задан каталог /tmp и требуется создать временный каталог внутри /tmp, строка prefix должна оканчиваться разделителем путей, используемым на платформе (require('node:path').sep).

fsPromises.mkdtempDisposable(prefix[, options])

• prefix <string> | <Buffer> | <URL>
• options <string> | <Object>
  • encoding <string> По умолчанию: 'utf8'
• Возвращает: <Promise> Разрешается промисом для асинхронно освобождаемого объекта:
  • path <string> Путь к созданному каталогу.
  • remove <AsyncFunction> Функция, удаляющая созданный каталог.
  • [Symbol.asyncDispose] <AsyncFunction> То же, что и remove.

Возвращаемый промис содержит асинхронно освобождаемый объект, свойство path которого содержит путь к созданному каталогу. При освобождении объекта каталог и его содержимое будут удалены асинхронно, если они ещё существуют. Если каталог не удастся удалить, при освобождении будет выброшена ошибка. У объекта есть асинхронный метод remove(), выполняющий ту же задачу.

Эта функция и функция освобождения возвращаемого объекта являются асинхронными, поэтому их следует использовать с await + await using, как в await using dir = await fsPromises.mkdtempDisposable('prefix').

Подробные сведения см. в документации к fsPromises.mkdtemp().

Необязательный аргумент options может быть строкой, задающей кодировку, или объектом со свойством encoding, задающим используемую кодировку символов.

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

• path <string> | <Buffer> | <URL>
• flags <string> | <number> См. раздел поддержка флагов файловой системы flags. По умолчанию: 'r'.
• mode <string> | <integer> Задаёт режим доступа к файлу (биты разрешений и sticky-биты), если файл создаётся. Дополнительные сведения см. в разделе Режимы доступа к файлам. По умолчанию: 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> Выполняется с содержимым файла.

Асинхронно читает всё содержимое файла.

Если кодировка не указана (с помощью options.encoding), данные возвращаются в виде объекта <Buffer>. В противном случае данные будут строкой.

Если options — строка, она задает кодировку.

Если path является каталогом, поведение fsPromises.readFile() зависит от платформы. В macOS, Linux и Windows промис будет отклонен с ошибкой. Во 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();

Выполняющийся запрос readFile можно отменить с помощью <AbortSignal>. Если запрос отменен, возвращенный промис будет отклонен с ошибкой AbortError:

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.

Читает содержимое символической ссылки, на которую указывает path. Дополнительные сведения см. в документации POSIX readlink(2). В случае успеха промис выполняется с linkString.

Необязательный аргумент options может быть строкой, задающей кодировку, или объектом со свойством encoding, задающим кодировку символов для возвращаемого пути ссылки. Если для encoding задано значение 'buffer', возвращаемый путь ссылки будет представлен объектом <Buffer>.

fsPromises.realpath(path[, options])

• path <string> | <Buffer> | <URL>
• options <string> | <Object>
  • encoding <string> По умолчанию: 'utf8'
• Возвращает: <Promise> В случае успеха выполняется с разрешенным путем.

Определяет фактическое расположение path, используя ту же семантику, что и функция fs.realpath.native().

Поддерживаются только пути, которые можно преобразовать в строки UTF-8.

Необязательный аргумент 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>
  • maxRetries <integer> При возникновении ошибки EBUSY, EMFILE, ENFILE, ENOTEMPTY или EPERM Node.js повторяет операцию, увеличивая время ожидания при линейной задержке на retryDelay миллисекунд после каждой попытки. Этот параметр задаёт количество повторных попыток. Этот параметр игнорируется, если параметр recursive не равен true. По умолчанию: 0.
  • recursive <boolean> Если значение равно true, выполняется рекурсивное удаление каталога. В рекурсивном режиме операции повторяются при сбое. По умолчанию: false. Устарел.
  • retryDelay <integer> Время ожидания между повторными попытками в миллисекундах. Этот параметр игнорируется, если параметр recursive не равен true. По умолчанию: 100.
• Возвращает: <Promise> При успешном выполнении разрешается значением undefined.

Удаляет каталог, указанный в path.

Использование fsPromises.rmdir() для файла (не каталога) приводит к отклонению промиса с ошибкой ENOENT в Windows и ошибкой ENOTDIR в POSIX.

Чтобы получить поведение, аналогичное поведению команды Unix rm -rf, используйте fsPromises.rm() с параметрами { recursive: true, force: true }.

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> При успешном выполнении разрешается объектом <fs.Stats> для указанного path.

fsPromises.statfs(path[, options])

• path <string> | <Buffer> | <URL>
• options <Object>
  • bigint <boolean> Должны ли числовые значения в возвращаемом объекте <fs.StatFs> иметь тип bigint. По умолчанию: false.
• Возвращает: <Promise> При успешном выполнении разрешается объектом <fs.StatFs> для указанного path.

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, Dates или числовая строка, например '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'.
  • ignore <string> | <RegExp> | <Function> | <Array> Шаблон(ы), которые следует игнорировать. Строки являются шаблонами glob (с использованием minimatch), шаблоны RegExp проверяются на соответствие имени файла, а функциям передается имя файла; они возвращают true, если его нужно игнорировать. По умолчанию: undefined.
• Возвращает: <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>.

Параметр encoding игнорируется, если data является буфером.

Если options является строкой, он задает кодировку.

Параметр mode влияет только на вновь созданный файл. Подробнее см. fs.open().

Указанный объект <FileHandle> должен поддерживать запись.

Небезопасно вызывать fsPromises.writeFile() несколько раз для одного файла, не дождавшись завершения промиса.

Подобно fsPromises.readFile, fsPromises.writeFile — это удобный метод, который внутри выполняет несколько вызовов write для записи переданного ему буфера. Для кода, чувствительного к производительности, рассмотрите возможность использования fs.createWriteStream() или filehandle.createWriteStream().

Для отмены fsPromises.writeFile() можно использовать <AbortSignal>. Отмена выполняется «по возможности», и, вероятно, некоторый объем данных все еще будет записан.

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 (например, 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.access() для проверки доступности файла перед вызовом fs.open(), fs.readFile() или fs.writeFile(). Это создает состояние гонки, поскольку другие процессы могут изменить состояние файла между двумя вызовами. Вместо этого пользовательский код должен непосредственно открыть, прочитать или записать файл и обработать ошибку, возникающую, если файл недоступен.

запись (НЕ РЕКОМЕНДУЕТСЯ)

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.close() для любого файлового дескриптора (fd), который в данный момент используется другой операцией fs, может привести к неопределенному поведению.

Дополнительные сведения см. в документации 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 — необязательное целое число, указывающее поведение операции копирования. Можно создать маску, объединив поразрядной операцией ИЛИ два или более значений (например, 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, чтобы пропустить его. При пропуске каталога пропускается также все его содержимое. Может также возвращать Promise, результатом выполнения которого является true или false. По умолчанию: undefined.
    • src <string> исходный путь для копирования.
    • dest <string> путь назначения, куда следует скопировать данные.
    • Возвращает: <boolean> | <Promise> Значение, которое можно привести к boolean, или Promise, выполняющийся с таким значением.
  • force <boolean> перезаписывать существующий файл или каталог. Если задать значение false и назначение существует, операция копирования будет игнорировать ошибки. Используйте параметр errorOnExist, чтобы изменить это поведение. По умолчанию: true.
  • mode <integer> модификаторы операции копирования. По умолчанию: 0. См. флаг mode метода fs.copyFile().
  • preserveTimestamps <boolean> Если true, временные метки из src будут сохранены. По умолчанию: false.
  • recursive <boolean> рекурсивно копировать каталоги По умолчанию: false
  • verbatimSymlinks <boolean> Если true, разрешение путей символических ссылок будет пропущено. По умолчанию: false
• callback <Function>
  • err <Error>

Асинхронно копирует всю структуру каталогов из src в dest, включая подкаталоги и файлы.

При копировании каталога в другой каталог шаблоны glob не поддерживаются, а поведение аналогично 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 позволяет переопределить соответствующие реализации fs для open, read и close. При указании параметра 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 задает режим файла (права доступа и sticky-биты), но только если файл был создан.

Пример чтения последних 10 байтов файла длиной 100 байт:

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 значение r+ вместо значения по умолчанию w. encoding может иметь любое из значений, принимаемых <Buffer>.

Если для 'error' или 'finish' установлено значение true (поведение по умолчанию) для autoClose, файловый дескриптор будет закрыт автоматически. Если autoClose имеет значение false, файловый дескриптор не будет закрыт, даже при возникновении ошибки. Приложение должно самостоятельно закрыть его и убедиться, что утечки файловых дескрипторов не происходит.

По умолчанию поток генерирует событие 'close' после уничтожения. Чтобы изменить это поведение, установите для опции emitClose значение false.

С помощью опции fs можно переопределить соответствующие реализации fs для open, write, writev и close. Переопределение write() без writev() может снизить производительность, поскольку некоторые оптимизации (_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() принимает только один логический параметр. Это одна из причин, по которой рекомендуется использовать fs.access() вместо fs.exists().

Если path является символической ссылкой, она отслеживается. Поэтому, если path существует, но указывает на несуществующий элемент, обратный вызов получит значение false.

Не рекомендуется использовать fs.exists() для проверки существования файла перед вызовом fs.open(), fs.readFile() или fs.writeFile(). Это создает состояние гонки, поскольку другие процессы могут изменить состояние файла между двумя вызовами. Вместо этого пользовательский код должен напрямую открыть, прочитать или записать файл и обработать ошибку, возникающую, если файл не существует.

запись (НЕ РЕКОМЕНДУЕТСЯ)

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>

Принудительно переводит все находящиеся в очереди операции ввода-вывода, связанные с файлом, в состояние синхронного завершения ввода-вывода операционной системы. Подробности см. в документации 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 байт.

Например, следующая программа оставляет в файле только первые четыре байта:

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[]> Функция для фильтрации файлов и каталогов либо список шаблонов glob, которые следует исключить. Если указана функция, возвращает true, чтобы исключить элемент, и false, чтобы включить его. По умолчанию: undefined.
  • withFileTypes <boolean> true, если glob должен возвращать пути в виде Dirent, и 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);
});

fs.lchmod(path, mode, callback)

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

Изменяет разрешения символической ссылки. В callback завершения передаются только аргументы, необходимые для возможного исключения.

Этот метод реализован только в macOS.

Подробнее см. в документации POSIX для lchmod(2).

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

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

Назначает владельца символической ссылки. В callback завершения передаются только аргументы, необходимые для возможного исключения.

Подробнее см. в документации 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(), за исключением того, что если путь указывает на символическую ссылку, она не разыменовывается: вместо этого изменяются временные метки самой символической ссылки.

В callback завершения передаются только аргументы, необходимые для возможного исключения.

fs.link(existingPath, newPath, callback)

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

Создает новую ссылку от existingPath к newPath. Подробнее см. в документации POSIX для link(2). В callback завершения передаются только аргументы, необходимые для возможного исключения.

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> для символической ссылки, на которую указывает путь. Callback получает два аргумента (err, stats), где stats — объект <fs.Stats>. lstat() идентичен stat(), за исключением того, что если path является символической ссылкой, сведения получаются о самой ссылке, а не о файле, на который она указывает.

Подробнее см. в документации 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]). Значение path по-прежнему может быть undefined, когда recursive имеет значение true, если каталог не был создан (например, если он уже существовал).

Необязательный аргумент options может быть целым числом, задающим mode (права доступа и биты закрепления), или объектом со свойством mode и свойством recursive, указывающим, следует ли создавать родительские каталоги. Вызов fs.mkdir(), когда path — существующий каталог, приводит к ошибке только в том случае, если 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 для создания уникального временного каталога. Из-за различий между платформами не используйте завершающие символы X в prefix. Некоторые платформы, в частности BSD, могут возвращать более шести случайных символов и заменять завершающие символы X в prefix случайными символами.

Путь созданного каталога передается в виде строки во втором параметре обратного вызова.

Необязательный аргумент 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() добавляет шесть случайно выбранных символов непосредственно в конец строки 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().

Обратный вызов получает два аргумента (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> Необязательный MIME-тип для blob.
• Возвращает: <Promise> При успешном выполнении разрешается объектом <Blob>.

Возвращает объект <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();
})();

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.

Функции обратного вызова передаются три аргумента: (err, bytesRead, buffer).

Если файл не изменяется одновременно, конец файла достигается, когда количество прочитанных байтов равно нулю.

При вызове этого метода в виде версии с util.promisify() он возвращает промис для Object со свойствами bytesRead и buffer.

Метод fs.read() читает данные из файла, указанного дескриптором файла (fd). Аргумент length задает максимальное количество байтов, которое Node.js попытается прочитать из ядра. Однако по разным причинам фактическое количество прочитанных байтов (bytesRead) может быть меньше указанного значения length.

Например:

• Если файл короче указанного значения length, для bytesRead будет установлено фактическое количество прочитанных байтов.
• Если до заполнения буфера встретится EOF (конец файла), 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[]>

Считывает содержимое каталога. Функция обратного вызова получает два аргумента (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

Функции обратного вызова передаются два аргумента (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. Функция обратного вызова получает два аргумента (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, и записывает их в массив ArrayBufferView с помощью readv().

position — это смещение от начала файла, с которого следует читать данные. Если typeof position !== 'number', данные будут прочитаны с текущей позиции.

Обратному вызову будут переданы три аргумента: err, bytesRead и buffers. bytesRead — это количество байтов, прочитанных из файла.

При вызове этого метода в версии, преобразованной с помощью util.promisify(), он возвращает промис с объектом Object, содержащим свойства bytesRead и buffers.

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). Для разрешения относительных путей можно использовать process.cwd.

Поддерживаются только пути, которые можно преобразовать в строки UTF-8.

Необязательный аргумент 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).

Поддерживаются только пути, которые можно преобразовать в строки UTF-8.

Необязательный аргумент 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>
  • 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>

Асинхронный вызов rmdir(2). В callback завершения передаются только аргументы, необходимые для возможного исключения.

Использование fs.rmdir() для файла (не каталога) приводит к ошибке ENOENT в Windows и ошибке ENOTDIR в POSIX.

Чтобы получить поведение, аналогичное команде Unix rm -rf, используйте fs.rm() с параметрами { recursive: true, force: true }.

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). В callback завершения передаются только аргументы, необходимые для возможного исключения.

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). Callback получает два аргумента (err, stats), где stats — объект <fs.Stats>.

В случае ошибки err.code будет одной из распространенных системных ошибок.

fs.stat() следует по символическим ссылкам. Чтобы просмотреть сами ссылки, используйте fs.lstat().

Не рекомендуется использовать fs.stat() для проверки наличия файла перед вызовом fs.open(), fs.readFile() или fs.writeFile(). Вместо этого пользовательскому коду следует непосредственно открыть, прочитать или записать файл и обработать ошибку, возникающую, если файл недоступен.

Для проверки наличия файла без последующих манипуляций с ним рекомендуется использовать fs.access().

Например, задана следующая структура каталогов:

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

Следующая программа проверит статистику для указанных путей:

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. Callback получает два аргумента (err, stats), где stats — объект <fs.StatFs>.

В случае ошибки err.code будет одной из распространенных системных ошибок.

fs.symlink(target, path[, type], callback)

• target <string> | <Buffer> | <URL>
• path <string> | <Buffer> | <URL>
• type <string> | <null> По умолчанию: null
• callback <Function>
  • err <Error>

Создаёт ссылку с именем path, указывающую на target. В обработчик завершения передаются только возможные исключения, других аргументов нет.

Дополнительные сведения см. в документации POSIX для symlink(2).

Аргумент type доступен только в Windows и игнорируется на других платформах. Ему можно задать значение 'dir', 'file' или 'junction'. Если аргумент type имеет значение null, Node.js автоматически определяет тип target и использует 'file' или 'dir'. Если target не существует, будет использовано 'file'. Для точек соединения Windows путь назначения должен быть абсолютным. При использовании 'junction' аргумент target автоматически преобразуется в абсолютный путь. Точки соединения на томах NTFS могут указывать только на каталоги.

Относительные пути назначения отсчитываются от родительского каталога ссылки.

import { symlink } from 'node:fs';

symlink('./mew', './mewtwo', callback); copy

Приведённый выше пример создаёт символическую ссылку mewtwo, которая указывает на mew в том же каталоге:

$ tree .
.
├── mew
└── mewtwo -> ./mew copy

fs.truncate(path[, len], callback)

• path <string> | <Buffer> | <URL>
• len <integer> По умолчанию: 0
• callback <Function>
  • err <Error> | <AggregateError>

Усекает файл. В обработчик завершения передаются только возможные исключения, других аргументов нет. В качестве первого аргумента также можно передать дескриптор файла. В этом случае вызывается fs.ftruncate().

import { truncate } from 'node:fs';
// Assuming that 'path/file.txt' is a regular file.
truncate('path/file.txt', (err) => {
  if (err) throw err;
  console.log('path/file.txt was truncated');
});

const { truncate } = require('node:fs');
// Assuming that 'path/file.txt' is a regular file.
truncate('path/file.txt', (err) => {
  if (err) throw err;
  console.log('path/file.txt was truncated');
});

Передача дескриптора файла считается устаревшей и в будущем может привести к ошибке.

Дополнительные сведения см. в документации POSIX для truncate(2).

fs.unlink(path, callback)

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

Асинхронно удаляет файл или символическую ссылку. В обработчик завершения передаются только возможные исключения, других аргументов нет.

import { unlink } from 'node:fs';
// Assuming that 'path/file.txt' is a regular file.
unlink('path/file.txt', (err) => {
  if (err) throw err;
  console.log('path/file.txt was deleted');
}); copy

fs.unlink() не работает с каталогами, пустыми или нет. Чтобы удалить каталог, используйте fs.rmdir().

Дополнительные сведения см. в документации POSIX для unlink(2).

fs.unwatchFile(filename[, listener])

• filename <string> | <Buffer> | <URL>
• listener <Function> Необязательный аргумент: обработчик, ранее добавленный с помощью fs.watchFile()

Прекращает отслеживать изменения filename. Если указан listener, удаляется только этот обработчик. В противном случае удаляются все обработчики, и отслеживание filename фактически прекращается.

Вызов fs.unwatchFile() для имени файла, за которым не ведётся наблюдение, ничего не делает и не приводит к ошибке.

Использование fs.watch() эффективнее, чем fs.watchFile() и fs.unwatchFile(). По возможности вместо fs.watchFile() и fs.unwatchFile() следует использовать fs.watch().

fs.utimes(path, atime, mtime, callback)

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

Изменяет временные метки файловой системы объекта, на который ссылается path.

К аргументам atime и mtime применяются следующие правила:

• Значения могут быть числами, представляющими время в секундах с начала эпохи Unix, объектами Date или числовыми строками, например '123456789.0'.
• Если значение нельзя преобразовать в число или оно равно NaN, Infinity или -Infinity, будет вызвана ошибка Error.

fs.watch(filename[, options][, listener])

• filename <string> | <Buffer> | <URL>
• options <string> | <Object>
  • persistent <boolean> Указывает, должен ли процесс продолжать работу, пока за файлами ведётся наблюдение. По умолчанию: true.
  • recursive <boolean> Указывает, следует ли наблюдать за всеми подкаталогами или только за текущим каталогом. Применяется, если указан каталог, и только на поддерживаемых платформах (см. оговорки). По умолчанию: false.
  • encoding <string> Задаёт кодировку символов для имени файла, передаваемого обработчику. По умолчанию: 'utf8'.
  • signal <AbortSignal> позволяет закрыть наблюдатель с помощью AbortSignal.
  • ignore <string> | <RegExp> | <Function> | <Array> Шаблоны для игнорирования. Строки являются glob-шаблонами (с использованием minimatch), шаблоны RegExp проверяются на соответствие имени файла, а функции получают имя файла и возвращают true, чтобы игнорировать его. По умолчанию: undefined.
• listener <Function> | <undefined> По умолчанию: undefined
  • eventType <string>
  • filename <string> | <Buffer> | <null>
• Возвращает: <fs.FSWatcher>

Отслеживает изменения в filename, где filename — файл или каталог.

Второй аргумент необязателен. Если options передан в виде строки, он задаёт encoding. В противном случае options следует передать в виде объекта.

Функция обратного вызова обработчика получает два аргумента (eventType, filename). eventType — это либо 'rename', либо 'change', а filename — имя файла, вызвавшего событие.

На большинстве платформ событие 'rename' генерируется при появлении или исчезновении имени файла в каталоге.

Функция обратного вызова обработчика привязывается к событию 'change', генерируемому объектом <fs.FSWatcher>, но это не то же самое, что значение 'change' объекта eventType.

Если передан signal, прерывание соответствующего AbortController закроет возвращённый объект <fs.FSWatcher>.

import { watch } from 'node:fs';
watch('somedir', (eventType, filename) => {
  console.log(`event type is: ${eventType}`);
  if (filename) {
    console.log(`filename provided: ${filename}`);
  } else {
    console.log('filename not provided');
  }
}); copy

fs.watchFile(filename[, options], listener)

• filename <string> | <Buffer> | <URL>
• options <Object>
  • bigint <boolean> По умолчанию: false
  • persistent <boolean> По умолчанию: true
  • interval <integer> По умолчанию: 5007
• listener <Function>
  • current <fs.Stats>
  • previous <fs.Stats>
• Возвращает: <fs.StatWatcher>

Отслеживает изменения в filename. Функция обратного вызова listener вызывается каждый раз при обращении к файлу.

Аргумент options можно опустить. Если он указан, это должен быть объект. Объект options может содержать логическое свойство с именем persistent, указывающее, должен ли процесс продолжать работу, пока за файлами ведётся наблюдение. В объекте options можно указать свойство interval, задающее частоту опроса целевого объекта в миллисекундах.

Функция listener получает два аргумента: текущий объект stat и предыдущий объект stat:

import { watchFile } from 'node:fs';

watchFile('message.text', (curr, prev) => {
  console.log(`the current mtime is: ${curr.mtime}`);
  console.log(`the previous mtime was: ${prev.mtime}`);
}); copy

Эти объекты stat являются экземплярами fs.Stat. Если параметр bigint имеет значение true, числовые значения в этих объектах задаются как BigInt.

Чтобы получать уведомления об изменении файла, а не только о доступе к нему, необходимо сравнивать curr.mtimeMs и prev.mtimeMs.

Если операция fs.watchFile завершается ошибкой ENOENT, функция обработчика будет вызвана один раз, причём все поля будут обнулены (а для дат будет указана эпоха Unix). Если файл будет создан позднее, функция обработчика будет вызвана снова с последними объектами stat. Это изменение поведения появилось в версии v0.10.

Использование fs.watch() эффективнее, чем fs.watchFile и fs.unwatchFile. По возможности вместо fs.watchFile и fs.unwatchFile следует использовать fs.watch.

Если файл, за которым наблюдает fs.watchFile(), исчезает и появляется снова, содержимое previous во втором событии обратного вызова (повторное появление файла) будет таким же, как содержимое previous в первом событии обратного вызова (исчезновение файла).

Это происходит в следующих случаях:

• файл удалён, а затем восстановлен
• файл переименован, а затем переименован ещё раз, чтобы вернуть ему исходное имя

fs.write(fd, buffer, offset[, length[, position]], callback)

• fd <integer>
• buffer <Buffer> | <TypedArray> | <DataView>
• offset <integer> По умолчанию: 0
• length <integer> По умолчанию: buffer.byteLength - offset
• position <integer> | <null> По умолчанию: null
• callback <Function>
  • err <Error>
  • bytesWritten <integer>
  • buffer <Buffer> | <TypedArray> | <DataView>

Записывает buffer в файл, указанный в fd.

offset определяет часть буфера, которую необходимо записать, а length — целое число, задающее количество записываемых байтов.

position указывает смещение от начала файла, по которому следует записать эти данные. Если typeof position !== 'number', данные будут записаны в текущую позицию. См. pwrite(2).

Обратному вызову будут переданы три аргумента (err, bytesWritten, buffer), где bytesWritten указывает, сколько байтов было записано из buffer.

При вызове этого метода в виде его версии с util.promisify() он возвращает промис для Object со свойствами bytesWritten и buffer.

Небезопасно использовать fs.write() несколько раз для одного файла, не дожидаясь обратного вызова. В этом случае рекомендуется использовать fs.createWriteStream().

В Linux позиционная запись не работает, если файл открыт в режиме добавления. Ядро игнорирует аргумент позиции и всегда добавляет данные в конец файла.

fs.write(fd, buffer[, options], callback)

• fd <integer>
• buffer <Buffer> | <TypedArray> | <DataView>
• options <Object>
  • offset <integer> По умолчанию: 0
  • length <integer> По умолчанию: buffer.byteLength - offset
  • position <integer> | <null> По умолчанию: null
• callback <Function>
  • err <Error>
  • bytesWritten <integer>
  • buffer <Buffer> | <TypedArray> | <DataView>

Записывает buffer в файл, указанный в fd.

Подобно описанной выше функции fs.write, эта версия принимает необязательный объект options. Если объект options не указан, будут использоваться значения по умолчанию, приведённые выше.

fs.write(fd, string[, position[, encoding]], callback)

• fd <integer>
• string <string>
• position <integer> | <null> По умолчанию: null
• encoding <string> По умолчанию: 'utf8'
• callback <Function>
  • err <Error>
  • written <integer>
  • string <string>

Записывает string в файл, указанный в fd. Если string не является строкой, будет выброшено исключение.

position указывает смещение от начала файла, по которому следует записать эти данные. Если typeof position !== 'number', данные будут записаны в текущую позицию. См. pwrite(2).

encoding — ожидаемая кодировка строки.

Обратному вызову будут переданы аргументы (err, written, string), где written указывает, сколько байтов требуется для записи переданной строки. Количество записанных байтов не обязательно совпадает с количеством записанных символов строки. См. Buffer.byteLength.

Небезопасно использовать fs.write() несколько раз для одного файла, не дожидаясь обратного вызова. В этом случае рекомендуется использовать fs.createWriteStream().

В Linux позиционная запись не работает, если файл открыт в режиме добавления. Ядро игнорирует аргумент позиции и всегда добавляет данные в конец файла.

В Windows, если файловый дескриптор подключён к консоли (например, fd == 1 или stdout), строка, содержащая символы не из ASCII, по умолчанию будет отображаться некорректно независимо от используемой кодировки. Чтобы консоль корректно отображала UTF-8, можно изменить активную кодовую страницу с помощью команды chcp 65001. Подробнее см. в документации по chcp.

fs.writeFile(file, data[, options], callback)

• file <string> | <Buffer> | <URL> | <integer> имя файла или дескриптор файла
• data <string> | <Buffer> | <TypedArray> | <DataView>
• options <Object> | <string>
  • encoding <string> | <null> По умолчанию: 'utf8'
  • mode <integer> По умолчанию: 0o666
  • flag <string> См. поддерживаемые flags файловой системы. По умолчанию: 'w'.
  • flush <boolean> Если все данные успешно записаны в файл и flush имеет значение true, для сброса данных используется fs.fsync(). По умолчанию: false.
  • signal <AbortSignal> позволяет отменить выполняющуюся операцию writeFile
• callback <Function>
  • err <Error> | <AggregateError>

Если file — это имя файла, данные асинхронно записываются в файл, заменяя его, если он уже существует. data может быть строкой или буфером.

Если file — это дескриптор файла, поведение аналогично прямому вызову fs.write() (который рекомендуется использовать). См. примечания ниже об использовании дескриптора файла.

Параметр encoding игнорируется, если data — это буфер.

Параметр mode влияет только на вновь созданный файл. Подробнее см. в разделе fs.open().

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

const data = new Uint8Array(Buffer.from('Hello Node.js'));
writeFile('message.txt', data, (err) => {
  if (err) throw err;
  console.log('The file has been saved!');
}); copy

Если options — это строка, она задает кодировку:

import { writeFile } from 'node:fs';

writeFile('message.txt', 'Hello Node.js', 'utf8', callback); copy

Небезопасно использовать fs.writeFile() несколько раз для одного и того же файла, не дожидаясь callback. В этом случае рекомендуется использовать fs.createWriteStream().

Как и fs.readFile, fs.writeFile — это вспомогательный метод, который внутри выполняет несколько вызовов write для записи переданного ему буфера. Для кода, чувствительного к производительности, рекомендуется использовать fs.createWriteStream().

Для отмены fs.writeFile() можно использовать <AbortSignal>. Отмена выполняется «по возможности», и, вероятно, часть данных всё равно будет записана.

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

const controller = new AbortController();
const { signal } = controller;
const data = new Uint8Array(Buffer.from('Hello Node.js'));
writeFile('message.txt', data, { signal }, (err) => {
  // When a request is aborted - the callback is called with an AbortError
});
// When the request should be aborted
controller.abort(); copy

Отмена выполняющегося запроса не отменяет отдельные запросы операционной системы, а прекращает внутреннюю буферизацию, выполняемую fs.writeFile.

import { write } from 'node:fs';
import { Buffer } from 'node:buffer';

write(fd, Buffer.from(data, options.encoding), callback); copy

fs.writev(fd, buffers[, position], callback)

• fd <integer>
• buffers <ArrayBufferView[]>
• position <integer> | <null> По умолчанию: null
• callback <Function>
  • err <Error>
  • bytesWritten <integer>
  • buffers <ArrayBufferView[]>

Записывает массив ArrayBufferViews в файл, указанный в fd, используя writev().

position — это смещение от начала файла, по которому следует записать данные. Если значение равно typeof position !== 'number', данные будут записаны в текущую позицию.

В callback передаются три аргумента: err, bytesWritten и buffers. bytesWritten — количество байтов, записанных из buffers.

Если для этого метода вызвать util.promisify(), он вернет промис для Object со свойствами bytesWritten и buffers.

Небезопасно использовать fs.writev() несколько раз для одного и того же файла, не дожидаясь callback. В этом случае используйте fs.createWriteStream().

В Linux позиционная запись не работает, если файл открыт в режиме добавления. Ядро игнорирует аргумент позиции и всегда добавляет данные в конец файла.

fs.accessSync(path[, mode])

• path <string> | <Buffer> | <URL>
• mode <integer> По умолчанию: fs.constants.F_OK

Синхронно проверяет разрешения пользователя для файла или каталога, указанного в path. Аргумент mode — необязательное целое число, задающее проверки доступности, которые нужно выполнить. Значением mode должно быть либо fs.constants.F_OK, либо маска, состоящая из побитового ИЛИ любых значений из fs.constants.R_OK, fs.constants.W_OK и fs.constants.X_OK (например, fs.constants.W_OK | fs.constants.R_OK). Возможные значения mode см. в разделе Константы доступа к файлам.

Если какая-либо проверка доступности завершится неудачей, будет выброшена ошибка Error. В противном случае метод вернёт undefined.

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

try {
  accessSync('etc/passwd', constants.R_OK | constants.W_OK);
  console.log('can read/write');
} catch (err) {
  console.error('no access!');
} copy

fs.appendFileSync(path, data[, options])

• 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.

Синхронно добавляет данные в файл, создавая его, если он ещё не существует. Значение data может быть строкой или <Buffer>.

Параметр mode влияет только на вновь созданный файл. Подробнее см. в разделе fs.open().

import { appendFileSync } from 'node:fs';

try {
  appendFileSync('message.txt', 'data to append');
  console.log('The "data to append" was appended to file!');
} catch (err) {
  /* Handle the error */
} copy

Если options — строка, она задаёт кодировку:

import { appendFileSync } from 'node:fs';

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

В качестве path можно указать числовой файловый дескриптор, открытый для добавления данных (с помощью fs.open() или fs.openSync()). Файловый дескриптор не будет закрыт автоматически.

import { openSync, closeSync, appendFileSync } from 'node:fs';

let fd;

try {
  fd = openSync('message.txt', 'a');
  appendFileSync(fd, 'data to append', 'utf8');
} catch (err) {
  /* Handle the error */
} finally {
  if (fd !== undefined)
    closeSync(fd);
} copy

fs.chmodSync(path, mode)

• path <string> | <Buffer> | <URL>
• mode <string> | <integer>

Подробную информацию см. в документации асинхронной версии этого API: fs.chmod().

Дополнительные сведения см. в документации POSIX для chmod(2).

fs.chownSync(path, uid, gid)

• path <string> | <Buffer> | <URL>
• uid <integer>
• gid <integer>

Синхронно изменяет владельца и группу файла. Возвращает undefined. Это синхронная версия метода fs.chown().

Дополнительные сведения см. в документации POSIX для chown(2).

fs.closeSync(fd)

• fd <integer>

Закрывает файловый дескриптор. Возвращает undefined.

Вызов fs.closeSync() для любого файлового дескриптора (fd), который в данный момент используется другой операцией fs, может привести к неопределённому поведению.

Дополнительные сведения см. в документации POSIX для close(2).

fs.copyFileSync(src, dest[, mode])