Класс: 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 равно 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> Необязательные модификаторы, задающие поведение операции копирования. Можно создать маску, объединив два или более значения побитовой операцией OR (например, fs.constants.COPYFILE_EXCL | fs.constants.COPYFILE_FICLONE) По умолчанию: 0.
  • fs.constants.COPYFILE_EXCL: операция копирования завершится ошибкой, если dest уже существует.
  • fs.constants.COPYFILE_FICLONE: операция копирования попытается создать reflink с копированием при записи. Если платформа не поддерживает копирование при записи, будет использован резервный механизм копирования.
  • fs.constants.COPYFILE_FICLONE_FORCE: операция копирования попытается создать reflink с копированием при записи. Если платформа не поддерживает копирование при записи, операция завершится ошибкой.
• Возвращает: <Promise> В случае успеха выполняется с undefined.

Асинхронно копирует src в dest. По умолчанию dest перезаписывается, если уже существует.

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

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

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

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

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

• src <string> | <URL> исходный путь для копирования.
• dest <string> | <URL> путь назначения для копирования.
• options <Object>
  • dereference <boolean> разыменовывать символические ссылки. По умолчанию: false.
  • errorOnExist <boolean> если force имеет значение false и место назначения существует, выбрасывать ошибку. По умолчанию: false.
  • filter <Function> Функция для фильтрации копируемых файлов и каталогов. Возвращает true, чтобы скопировать элемент, или false, чтобы пропустить его. При пропуске каталога пропускается и всё его содержимое. Также может вернуть 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> 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 не указывает на символическую ссылку; в этом случае stat выполняется для самой ссылки, а не для файла, на который она указывает. Подробнее см. документацию 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.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().

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

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

В Linux, если Node.js связан с musl libc, для работы этой функции файловая система procfs должна быть смонтирована в /proc. Для glibc такого ограничения нет.

fsPromises.rename(oldPath, newPath)

• oldPath <string> | <Buffer> | <URL>
• newPath <string> | <Buffer> | <URL>
• Возвращает: <Promise> В случае успеха выполняется с undefined.

Переименовывает oldPath в newPath.

fsPromises.rmdir(path[, options])

• path <string> | <Buffer> | <URL>
• options <Object>
  • 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 не является строкой, Node.js автоматически определит тип target и использует 'file' или 'dir'. Если target не существует, будет использовано 'file'. Для точек соединения Windows путь назначения должен быть абсолютным. При использовании 'junction' аргумент target будет автоматически преобразован в абсолютный путь. Точки соединения на томах NTFS могут указывать только на каталоги.

fsPromises.truncate(path[, len])

• path <string> | <Buffer> | <URL>
• len <integer> По умолчанию: 0
• Возвращает: <Promise> При успешном выполнении разрешается значением undefined.

Обрезает (укорачивает или увеличивает длину) содержимое файла по адресу path до len байт.

fsPromises.unlink(path)

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

Если path указывает на символическую ссылку, ссылка удаляется, не затрагивая файл или каталог, на который она указывает. Если path указывает на путь к файлу, который не является символической ссылкой, файл удаляется. Дополнительные сведения см. в документации POSIX для unlink(2).

fsPromises.utimes(path, atime, mtime)

• path <string> | <Buffer> | <URL>
• atime <number> | <string> | <Date>
• mtime <number> | <string> | <Date>
• Возвращает: <Promise> При успешном выполнении разрешается значением undefined.

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

Аргументы atime и mtime должны соответствовать следующим правилам:

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

fsPromises.watch(filename[, options])

• filename <string> | <Buffer> | <URL>
• options <string> | <Object>
  • persistent <boolean> Указывает, следует ли процессу продолжать работу, пока отслеживаются файлы. По умолчанию: true.
  • recursive <boolean> Указывает, следует ли отслеживать все подкаталоги или только текущий каталог. Применяется, если указан каталог, и только на поддерживаемых платформах (см. предостережения). По умолчанию: false.
  • encoding <string> Задает кодировку символов, используемую для имени файла, передаваемого обработчику. По умолчанию: 'utf8'.
  • signal <AbortSignal> <AbortSignal>, используемый для указания момента остановки наблюдателя.
  • maxQueue <number> Задает количество событий, помещаемых в очередь между итерациями возвращаемого <AsyncIterator>. По умолчанию: 2048.
  • overflow <string> Либо 'ignore', либо 'throw', если в очереди находится больше событий, чем допускает maxQueue. 'ignore' означает, что события переполнения отбрасываются и выдается предупреждение, а 'throw' означает выброс исключения. По умолчанию: 'ignore'.
• Возвращает: <AsyncIterator> объектов со свойствами:
  • eventType <string> Тип изменения
  • filename <string> | <Buffer> | <null> Имя измененного файла.

Возвращает асинхронный итератор, отслеживающий изменения в filename, где filename является файлом или каталогом.

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

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

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

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

Все предостережения, относящиеся к fs.watch(), также применимы к fsPromises.watch().

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

• file <string> | <Buffer> | <URL> | <FileHandle> имя файла или FileHandle
• data <string> | <Buffer> | <TypedArray> | <DataView> | <AsyncIterable> | <Iterable> | <Stream>
• options <Object> | <string>
  • encoding <string> | <null> По умолчанию: 'utf8'
  • mode <integer> По умолчанию: 0o666
  • flag <string> См. поддерживаемые флаги файловой системы flags. По умолчанию: 'w'.
  • flush <boolean> Если все данные успешно записаны в файл и flush имеет значение true, для сброса данных используется filehandle.sync(). По умолчанию: false.
  • signal <AbortSignal> позволяет отменить выполняющуюся операцию writeFile
• Возвращает: <Promise> при успешном выполнении разрешается со значением undefined.

Асинхронно записывает данные в файл, заменяя его, если он уже существует. data может быть строкой, буфером, объектом <AsyncIterable> или <Iterable>.

Параметр 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>.

Если для autoClose установлено значение true (поведение по умолчанию) в 'error' или 'finish', файловый дескриптор будет закрыт автоматически. Если для 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.exists() рекомендуется использовать fs.access().

Если 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>

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

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

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

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

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

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

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

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

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

Изменяет время доступа и модификации файла так же, как fs.utimes(), но если путь указывает на символическую ссылку, она не разыменовывается: вместо этого изменяются временные метки самой символической ссылки.

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

fs.link(existingPath, newPath, callback)

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

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

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

• path <string> | <Buffer> | <URL>
• options <Object>
  • bigint <boolean> Определяет, должны ли числовые значения в возвращаемом объекте <fs.Stats> иметь тип bigint. По умолчанию: false.
• callback <Function>
  • err <Error>
  • stats <fs.Stats>

Получает объект <fs.Stats> для символической ссылки, на которую указывает путь. Функция обратного вызова получает два аргумента (err, stats), где stats — это объект <fs.Stats>. lstat() идентичен stat(), за исключением того, что если path является символической ссылкой, то stat выполняется для самой ссылки, а не для файла, на который она указывает.

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

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

• path <string> | <Buffer> | <URL>
• options <Object> | <integer>
  • recursive <boolean> По умолчанию: false
  • mode <string> | <integer> Не поддерживается в Windows. По умолчанию: 0o777.
• callback <Function>
  • err <Error>
  • path <string> | <undefined> Присутствует, только если каталог создан с параметром recursive, установленным в значение true.

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

Функция обратного вызова получает возможную ошибку и, если recursive равно true, путь к первому созданному каталогу, (err[, path]). path может оставаться равным undefined, если recursive равно true, когда каталог не был создан (например, если он уже был создан ранее).

Необязательный аргумент options может быть целым числом, задающим mode (права доступа и sticky-биты), или объектом со свойством 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 задает режим файла (права доступа и sticky-биты), но только если файл был создан. В 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> файл нельзя изменять. Любые изменения приведут к ошибке DOMException при чтении данных <Blob>. При создании 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>

Асинхронно вычисляет канонический путь, разрешая ., .. и символические ссылки.

Канонический путь не обязательно уникален. Жесткие ссылки и точки монтирования bind позволяют обращаться к объекту файловой системы по множеству путей.

Эта функция работает как realpath(3), за некоторыми исключениями:

1. В файловых системах без учета регистра преобразование регистра не выполняется.

2. Максимальное количество символических ссылок не зависит от платформы и, как правило, (намного) превышает поддерживаемое собственной реализацией realpath(3).

В callback передаются два аргумента: (err, resolvedPath). Для разрешения относительных путей можно использовать process.cwd.

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

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

Если path разрешается в сокет или канал, функция вернет зависящее от системы имя этого объекта.

Если путь не существует, возникает ошибка ENOENT. error.path — это абсолютный путь к файлу.

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

• path <string> | <Buffer> | <URL>
• options <string> | <Object>
  • encoding <string> По умолчанию: 'utf8'
• callback <Function>
  • err <Error>
  • resolvedPath <string> | <Buffer>

Асинхронный вариант realpath(3).

В callback передаются два аргумента: (err, resolvedPath).

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

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

В Linux, если Node.js скомпонован с musl libc, для работы этой функции файловая система procfs должна быть смонтирована в /proc. Для glibc такого ограничения нет.

fs.rename(oldPath, newPath, callback)

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

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

См. также: rename(2).

import { rename } from 'node:fs';

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

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

• path <string> | <Buffer> | <URL>
• options <Object>
  • 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). В функцию обратного вызова завершения передаются только аргументы, относящиеся к возможному исключению.

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

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

• path <string> | <Buffer> | <URL>
• options <Object>
  • bigint <boolean> Должны ли числовые значения в возвращаемом объекте <fs.Stats> иметь тип bigint. По умолчанию: false.
• callback <Function>
  • err <Error>
  • stats <fs.Stats>

Асинхронный вызов stat(2). Функция обратного вызова получает два аргумента (err, stats), где 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. Функция обратного вызова получает два аргумента (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 не является строкой, 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.
• 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() несколько раз для одного и того же файла, не дожидаясь функции обратного вызова. В этом случае рекомендуется использовать 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[]>

Записывает массив объектов ArrayBufferView в файл, указанный параметром fd, с помощью writev().

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

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

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

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

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

fs.accessSync(path[, mode])

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

Синхронно проверяет разрешения пользователя для файла или каталога, указанного в path. Аргумент mode — необязательное целое число, задающее проверки доступности, которые необходимо выполнить. Значение mode должно быть либо fs.constants.F_OK, либо маской, состоящей из побитового OR любых значений из 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])

• src <string> | <Buffer> | <URL> имя исходного файла для копирования
• dest <string> | <Buffer> | <URL> имя файла назначения для операции копирования
• mode <integer> модификаторы операции копирования. По умолчанию: 0.

Синхронно копирует src в dest. По умолчанию файл dest перезаписывается, если он уже существует. Возвращает undefined. Node.js не гарантирует атомарность операции копирования. Если ошибка возникает после открытия файла назначения для записи, Node.js попытается удалить файл назначения.

mode — необязательное целое число, задающее поведение операции копирования. Можно создать маску из побитового OR двух или более значений (например, fs.constants.COPYFILE_EXCL | fs.constants.COPYFILE_FICLONE).

• fs.constants.COPYFILE_EXCL: операция копирования завершится ошибкой, если dest уже существует.
• fs.constants.COPYFILE_FICLONE: операция копирования попытается создать reflink с копированием при записи. Если платформа не поддерживает копирование при записи, будет использован резервный механизм копирования.
• fs.constants.COPYFILE_FICLONE_FORCE: операция копирования попытается создать reflink с копированием при записи. Если платформа не поддерживает копирование при записи, операция завершится ошибкой.

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

// destination.txt will be created or overwritten by default.
copyFileSync('source.txt', 'destination.txt');
console.log('source.txt was copied to destination.txt');

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

fs.cpSync(src, dest[, options])

• src <string> | <URL> исходный путь для копирования.
• dest <string> | <URL> путь назначения, куда следует скопировать.
• options <Object>
  • dereference <boolean> разыменовывать символические ссылки. По умолчанию: false.
  • errorOnExist <boolean> если force имеет значение false и место назначения существует, выбрасывать ошибку. По умолчанию: false.
  • filter <Function> Функция для фильтрации копируемых файлов и каталогов. Возвращает true, чтобы скопировать элемент, или false, чтобы пропустить его. При пропуске каталога всё его содержимое также будет пропущено. По умолчанию: undefined
    • src <string> исходный путь для копирования.
    • dest <string> путь назначения, куда следует скопировать.
    • Возвращает: <boolean> Любое значение, отличное от Promise, которое можно привести к boolean.
  • force <boolean> перезаписывать существующий файл или каталог. Если установить значение false и место назначения существует, операция копирования будет игнорировать ошибки. Используйте параметр errorOnExist, чтобы изменить это поведение. По умолчанию: true.
  • mode <integer> модификаторы операции копирования. По умолчанию: 0. См. флаг mode функции fs.copyFileSync().
  • preserveTimestamps <boolean> Если true, временные метки из src будут сохранены. По умолчанию: false.
  • recursive <boolean> рекурсивно копировать каталоги. По умолчанию: false
  • verbatimSymlinks <boolean> Если true, разрешение путей для символических ссылок будет пропущено. По умолчанию: false