fs/promises

Проверяет разрешения пользователя для файла или каталога, указанного в 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 см. в File access constants.

Если проверка доступности выполнена успешно, промис выполняется без значения. Если какая-либо из проверок доступности завершается неудачей, промис отклоняется с объектом 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');
}

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

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

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

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

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

Изменяет права доступа к файлу.

Изменяет владельца файла.

Асинхронно копирует 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');
}

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

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

Возвращает файлы, соответствующие указанному шаблону.

Изменяет владельца символической ссылки.

Создаёт новую ссылку с existingPath на newPath. Дополнительные сведения см. в документации POSIX link(2).

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

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

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

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

Асинхронный mkdir(2) — создание каталога.

Асинхронный mkdir(2) — создание каталога.

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

Метод fsPromises.mkdtemp() добавит шесть случайно выбранных символов непосредственно к строке prefix. Например, если задан каталог /tmp, а временный каталог требуется создать внутри /tmp, строка prefix должна оканчиваться разделителем пути, специфичным для платформы (import { sep } from 'node:path').

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

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

Открывает FileHandle.

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

Некоторые символы (< > : " / \ | ? *) зарезервированы в Windows, как описано в разделе Имена файлов, пути и пространства имен. В NTFS, если имя файла содержит двоеточие, Node.js откроет файловый поток, как описано на этой странице MSDN.

Асинхронно открывает каталог для последовательного просмотра. Подробнее см. документацию 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);
}

При использовании асинхронного итератора объект fs.Dir будет автоматически закрыт после завершения итератора.

Читает содержимое каталога.

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

Асинхронный readdir(3) — чтение каталога.

Асинхронный readdir(3) — чтение каталога.

Асинхронный readdir(3) — чтение каталога.

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

Если кодировка не указана (с помощью 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);
}

Текущий запрос 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);
}

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

Указанный FileHandle должен поддерживать чтение.

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

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

Читает содержимое символической ссылки, на которую указывает path. Подробнее см. в документации POSIX по readlink(2). При успешном выполнении промис возвращает linkString.

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

Асинхронный readlink(2) — чтение значения символической ссылки.

Асинхронный readlink(2) — чтение значения символической ссылки.

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

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

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

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

Асинхронный realpath(3) — возврат канонического абсолютного пути.

Асинхронный realpath(3) — возврат канонического абсолютного пути.

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

Удаляет файлы и каталоги (по образцу стандартной утилиты POSIX rm).

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

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

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

Создаёт символическую ссылку.

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

Укорачивает или увеличивает длину содержимого в path до len байт.

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

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

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

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

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

import { watch } from '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;
  }
})();

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

Для fsPromises.watch() также применяются все caveats для fs.watch().

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

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

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

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

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

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

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

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

Подобно 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);
}

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

Изменяет права доступа символической ссылки.

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