Файловая система

Модуль node:fs позволяет взаимодействовать с файловой системой способом, основанным на стандартных функциях POSIX.

Чтобы использовать API на основе промисов:

import * as fs from 'node:fs/promises';

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

Чтобы использовать API с колбэками и синхронный API:

import * as fs from 'node:fs';

const fs = require('node:fs');

Все операции с файловой системой имеют синхронные формы, формы с колбэками и формы на основе промисов и доступны как с использованием синтаксиса CommonJS, так и модулей ES6 (ESM).

Пример с промисами

Операции на основе промисов возвращают промис, который выполняется после завершения асинхронной операции.

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

try {
  await unlink('/tmp/hello');
  console.log('successfully deleted /tmp/hello');
} catch (error) {
  console.error('there was an error:', error.message);
}

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

(async function(path) {
  try {
    await unlink(path);
    console.log(`successfully deleted ${path}`);
  } catch (error) {
    console.error('there was an error:', error.message);
  }
})('/tmp/hello');

Пример с колбэком

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

import { unlink } from 'node:fs';

unlink('/tmp/hello', (err) => {
  if (err) throw err;
  console.log('successfully deleted /tmp/hello');
});

const { unlink } = require('node:fs');

unlink('/tmp/hello', (err) => {
  if (err) throw err;
  console.log('successfully deleted /tmp/hello');
});

Версии API модуля node:fs на основе колбэков предпочтительнее API на основе промисов, если требуется максимальная производительность (как с точки зрения времени выполнения, так и выделения памяти).

Синхронный пример

Синхронный API блокирует цикл событий Node.js и дальнейшее выполнение JavaScript до завершения операции. Исключения выбрасываются немедленно, и их можно обработать с помощью try…catch или позволить им распространиться выше по стеку вызовов.

import { unlinkSync } from 'node:fs';

try {
  unlinkSync('/tmp/hello');
  console.log('successfully deleted /tmp/hello');
} catch (err) {
  // handle the error
}

const { unlinkSync } = require('node:fs');

try {
  unlinkSync('/tmp/hello');
  console.log('successfully deleted /tmp/hello');
} catch (err) {
  // handle the error
}

API промисов

API fs/promises предоставляет асинхронные методы файловой системы, возвращающие промисы.

API промисов использует базовый пул потоков Node.js для выполнения операций с файловой системой вне потока цикла событий. Эти операции не синхронизированы и не являются потокобезопасными. При выполнении нескольких одновременных изменений одного файла следует соблюдать осторожность, иначе данные могут быть повреждены.

Класс: FileHandle

Объект <FileHandle> является оберткой для числового дескриптора файла.

Экземпляры объекта <FileHandle> создаются методом fsPromises.open().

Все объекты <FileHandle> являются объектами <EventEmitter>.

Если объект <FileHandle> не закрыт с помощью метода filehandle.close(), он попытается автоматически закрыть дескриптор файла и выдать предупреждение процесса, помогая предотвратить утечки памяти. Пожалуйста, не полагайтесь на это поведение, поскольку оно может быть ненадежным, а файл может остаться открытым. Вместо этого всегда явно закрывайте объекты <FileHandle>. В будущем Node.js может изменить это поведение.

Событие: 'close'

Событие 'close' генерируется после закрытия объекта <FileHandle>, когда его больше нельзя использовать.

filehandle.appendFile(data[, options])

• data <string> | <Buffer> | <TypedArray> | <DataView> | <AsyncIterable> | <Stream>
• options <Object> | <string>
  • encoding <string> | <null> По умолчанию: 'utf8'
  • signal <AbortSignal> | <undefined> позволяет прервать выполняющуюся операцию writeFile. По умолчанию: undefined
• Возвращает: <Promise> В случае успеха выполняется с undefined.

Псевдоним для filehandle.writeFile().

При работе с дескрипторами файлов режим нельзя изменить по сравнению с тем, который был задан с помощью fsPromises.open(). Поэтому это эквивалентно filehandle.writeFile().

filehandle.chmod(mode)

• mode <integer> битовая маска режима файла.
• Возвращает: <Promise> При успешном выполнении выполняется с undefined.

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

filehandle.chown(uid, gid)

• uid <integer> идентификатор пользователя нового владельца файла.
• gid <integer> идентификатор группы новой группы файла.
• Возвращает: <Promise> При успешном выполнении выполняется с undefined.

Изменяет владельца файла. Обертка для chown(2).

filehandle.close()

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

Закрывает файловый дескриптор после завершения всех ожидающих операций с ним.

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

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

filehandle.createReadStream([options])

• options <Object>
  • encoding <string> По умолчанию: null
  • autoClose <boolean> По умолчанию: true
  • emitClose <boolean> По умолчанию: true
  • start <integer>
  • end <integer> По умолчанию: Infinity
  • highWaterMark <integer> По умолчанию: 64 * 1024
  • signal <AbortSignal> | <undefined> По умолчанию: undefined
• Возвращает: <fs.ReadStream>

options может содержать значения start и end, чтобы прочитать диапазон байтов из файла, а не весь файл целиком. И start, и end включаются в диапазон; отсчет начинается с 0, допустимые значения находятся в диапазоне [0, Number.MAX_SAFE_INTEGER]. Если start не указано или равно undefined, filehandle.createReadStream() выполняет последовательное чтение с текущей позиции в файле. encoding может иметь любое из значений, принимаемых <Buffer>.

Если FileHandle указывает на символьное устройство, поддерживающее только блокирующее чтение (например, клавиатуру или звуковую карту), операции чтения не завершаются до появления данных. Это может помешать завершению процесса и естественному закрытию потока.

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

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);
mjscopy

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

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

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

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

filehandle.createWriteStream([options])

• options <Object>
  • encoding <string> По умолчанию: 'utf8'
  • autoClose <boolean> По умолчанию: true
  • emitClose <boolean> По умолчанию: true
  • start <integer>
  • highWaterMark <number> По умолчанию: 16384
  • flush <boolean> Если true, перед закрытием выполняется сброс буферов файлового дескриптора. По умолчанию: false.
• Возвращает: <fs.WriteStream>

options также может включать параметр start, позволяющий записывать данные с некоторой позиции после начала файла; допустимые значения находятся в диапазоне [0, Number.MAX_SAFE_INTEGER]. Для изменения файла вместо его замены может потребоваться установить параметр flags open в значение r+ вместо значения по умолчанию r. Значение encoding может быть любым из значений, принимаемых <Buffer>.

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

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

filehandle.datasync()

• Возвращает: <Promise> Выполняется с результатом undefined в случае успеха.

Принудительно переводит все поставленные в очередь операции ввода-вывода, связанные с файлом, в состояние завершения синхронизированного ввода-вывода операционной системы. Подробности см. в документации POSIX для fdatasync(2).

В отличие от filehandle.sync, этот метод не сбрасывает изменённые метаданные.

filehandle.fd

• Тип: <number> Числовой файловый дескриптор, управляемый объектом <FileHandle>.

filehandle.pull([...transforms][, options])

• ...transforms <Function> | <Object> Необязательные преобразования, применяемые через stream/iter pull().
• options <Object>
  • signal <AbortSignal>
  • autoClose <boolean> Закрыть файловый дескриптор при завершении потока. По умолчанию: false.
  • start <number> Смещение в байтах, с которого начинается чтение. Если указано, для чтения используется явное позиционирование (семантика pread). По умолчанию: текущая позиция в файле.
  • limit <number> Максимальное количество байтов для чтения до завершения итератора. Чтение прекращается, когда передано limit байтов или достигнут EOF — в зависимости от того, что наступит раньше. По умолчанию: чтение до EOF.
  • chunkSize <number> Размер в байтах буфера, выделяемого для каждой операции чтения. По умолчанию: 131072 (128 КБ).
• Возвращает: {AsyncIterable<Uint8Array[]>}

Возвращает содержимое файла в виде асинхронного итерируемого объекта, используя pull-модель node:stream/iter. Чтение выполняется блоками по chunkSize байт (по умолчанию — 128 КБ). Если указаны преобразования, они применяются через stream/iter pull().

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

Эта функция доступна только при включённом флаге --experimental-stream-iter.

import { open } from 'node:fs/promises';
import { text } from 'node:stream/iter';
import { compressGzip } from 'node:zlib/iter';

const fh = await open('input.txt', 'r');

// Read as text
console.log(await text(fh.pull({ autoClose: true })));

// Read 1 KB starting at byte 100
const fh2 = await open('input.txt', 'r');
console.log(await text(fh2.pull({ start: 100, limit: 1024, autoClose: true })));

// Read with compression
const fh3 = await open('input.txt', 'r');
const compressed = fh3.pull(compressGzip(), { autoClose: true });

const { open } = require('node:fs/promises');
const { text } = require('node:stream/iter');
const { compressGzip } = require('node:zlib/iter');

async function run() {
  const fh = await open('input.txt', 'r');

  // Read as text
  console.log(await text(fh.pull({ autoClose: true })));

  // Read 1 KB starting at byte 100
  const fh2 = await open('input.txt', 'r');
  console.log(await text(fh2.pull({ start: 100, limit: 1024, autoClose: true })));

  // Read with compression
  const fh3 = await open('input.txt', 'r');
  const compressed = fh3.pull(compressGzip(), { autoClose: true });
}

run().catch(console.error);

filehandle.pullSync([...transforms][, options])

• ...transforms <Function> | <Object> Необязательные преобразования, применяемые через stream/iter pullSync().
• options <Object>
  • autoClose <boolean> Закрывать файловый дескриптор по завершении потока. По умолчанию: false.
  • start <number> Смещение в байтах, с которого начинается чтение. Если указано, для чтения используется явное позиционирование. По умолчанию: текущая позиция в файле.
  • limit <number> Максимальное количество байтов для чтения до завершения итератора. По умолчанию: чтение до конца файла.
  • chunkSize <number> Размер в байтах буфера, выделяемого для каждой операции чтения. По умолчанию: 131072 (128 КБ).
• Возвращает: {Iterable<Uint8Array[]>}

Синхронный аналог filehandle.pull(). Возвращает синхронный итерируемый объект, который считывает файл с помощью синхронного ввода-вывода в основном потоке. Данные считываются блоками по chunkSize байт (по умолчанию — 128 КБ).

Файловый дескриптор заблокирован на время обхода итерируемого объекта. В отличие от асинхронного pull(), этот метод не поддерживает AbortSignal, поскольку все операции выполняются синхронно.

Эта функция доступна только при включенном флаге --experimental-stream-iter.

import { open } from 'node:fs/promises';
import { textSync, pipeToSync } from 'node:stream/iter';
import { compressGzipSync, decompressGzipSync } from 'node:zlib/iter';

const fh = await open('input.txt', 'r');

// Read as text (sync)
console.log(textSync(fh.pullSync({ autoClose: true })));

// Sync compress pipeline: file -> gzip -> file
const src = await open('input.txt', 'r');
const dst = await open('output.gz', 'w');
pipeToSync(src.pullSync(compressGzipSync(), { autoClose: true }), dst.writer({ autoClose: true }));

const { open } = require('node:fs/promises');
const { textSync, pipeToSync } = require('node:stream/iter');
const { compressGzipSync, decompressGzipSync } = require('node:zlib/iter');

async function run() {
  const fh = await open('input.txt', 'r');

  // Read as text (sync)
  console.log(textSync(fh.pullSync({ autoClose: true })));

  // Sync compress pipeline: file -> gzip -> file
  const src = await open('input.txt', 'r');
  const dst = await open('output.gz', 'w');
  pipeToSync(
    src.pullSync(compressGzipSync(), { autoClose: true }),
    dst.writer({ autoClose: true }),
  );
}

run().catch(console.error);

filehandle.read(buffer, offset, length, position)

• buffer <Buffer> | <TypedArray> | <DataView> Буфер, который будет заполнен считанными данными файла.
• offset <integer> Позиция в буфере, с которой начинается запись данных. По умолчанию: 0
• length <integer> Количество байтов для чтения. По умолчанию: buffer.byteLength - offset
• position <integer> | <bigint> | <null> Позиция, с которой начинается чтение данных из файла. Если null или -1, данные будут считываться с текущей позиции в файле, а позиция будет обновлена. Если position — неотрицательное целое число, текущая позиция в файле останется без изменений. По умолчанию: null
• Возвращает: <Promise> При успешном выполнении возвращает объект с двумя свойствами:
  • bytesRead <integer> Количество считанных байтов
  • buffer <Buffer> | <TypedArray> | <DataView> Ссылка на переданный аргумент buffer.

Считывает данные из файла и сохраняет их в указанном буфере.

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

filehandle.read([options])

• options <Object>
  • buffer <Buffer> | <TypedArray> | <DataView> Буфер, который будет заполнен считанными данными файла. По умолчанию: Buffer.alloc(16384)
  • offset <integer> Позиция в буфере, с которой начнётся заполнение. По умолчанию: 0
  • length <integer> Количество байтов для чтения. По умолчанию: buffer.byteLength - offset
  • position <integer> | <bigint> | <null> Позиция, с которой следует начать чтение данных из файла. Если null или -1, данные будут считываться с текущей позиции в файле, и эта позиция будет обновлена. Если position — неотрицательное целое число, текущая позиция в файле останется неизменной. По умолчанию:: null
• Возвращает: <Promise> При успешном выполнении возвращает объект с двумя свойствами:
  • bytesRead <integer> Количество прочитанных байтов
  • buffer <Buffer> | <TypedArray> | <DataView> Ссылка на переданный аргумент buffer.

Считывает данные из файла и сохраняет их в указанном буфере.

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

filehandle.read(buffer[, options])

• buffer <Buffer> | <TypedArray> | <DataView> Буфер, который будет заполнен считанными данными файла.
• options <Object>
  • offset <integer> Позиция в буфере, с которой начнётся заполнение. По умолчанию: 0
  • length <integer> Количество байтов для чтения. По умолчанию: buffer.byteLength - offset
  • position <integer> | <bigint> | <null> Позиция, с которой следует начать чтение данных из файла. Если null или -1, данные будут считываться с текущей позиции в файле, и эта позиция будет обновлена. Если position — неотрицательное целое число, текущая позиция в файле останется неизменной. По умолчанию:: null
• Возвращает: <Promise> При успешном выполнении возвращает объект с двумя свойствами:
  • bytesRead <integer> Количество прочитанных байтов
  • buffer <Buffer> | <TypedArray> | <DataView> Ссылка на переданный аргумент buffer.

Считывает данные из файла и сохраняет их в указанном буфере.

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

filehandle.readableWebStream([options])

• options <Object>
  • autoClose <boolean> Если значение равно true, <FileHandle> закрывается при закрытии потока. По умолчанию: false
• Возвращает: <ReadableStream>

Возвращает ориентированный на байты ReadableStream, который можно использовать для чтения содержимого файла.

Будет вызвана ошибка, если этот метод вызывается более одного раза или после закрытия либо начала закрытия FileHandle.

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

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

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

await file.close();

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

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

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

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

Хотя ReadableStream прочитает файл целиком, он не закроет FileHandle автоматически. Пользовательский код по-прежнему должен вызывать метод fileHandle.close(), если только для параметра autoClose не задано значение true.

filehandle.readFile(options)

• options <Object> | <string>
  • encoding <string> | <null> По умолчанию: null
  • signal <AbortSignal> позволяет прервать выполняющееся чтение файла
• Возвращает: <Promise> Выполняется при успешном чтении и содержит содержимое файла. Если кодировка не указана (с помощью options.encoding), данные возвращаются как объект <Buffer>. В противном случае данные будут строкой.

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

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

<FileHandle> должен поддерживать чтение.

Если для файлового дескриптора выполняется один или несколько вызовов filehandle.read(), а затем вызывается filehandle.readFile(), данные будут прочитаны с текущей позиции до конца файла. Чтение не всегда начинается с начала файла.

filehandle.readLines([options])

• options <Object>
  • encoding <string> По умолчанию: null
  • autoClose <boolean> По умолчанию: true
  • emitClose <boolean> По умолчанию: true
  • start <integer>
  • end <integer> По умолчанию: Infinity
  • highWaterMark <integer> По умолчанию: 64 * 1024
• Возвращает: <readline.InterfaceConstructor>

Вспомогательный метод для создания интерфейса readline и потока для чтения файла. Параметры см. в разделе filehandle.createReadStream().

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

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

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

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

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

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

filehandle.readv(buffers[, position])

• buffers <Buffer[]> | <TypedArray[]> | <DataView[]>
• position <integer> | <null> Смещение от начала файла, с которого следует считывать данные. Если position не является значением number, данные будут считываться с текущей позиции. По умолчанию: null
• Возвращает: <Promise> При успешном выполнении возвращает объект с двумя свойствами:
  • bytesRead <integer> количество прочитанных байтов
  • buffers <Buffer[]> | <TypedArray[]> | <DataView[]> свойство, содержащее ссылку на исходный buffers.

Читает данные из файла и записывает их в массив {ArrayBufferView}.

filehandle.stat([options])

• options <Object>
  • bigint <boolean> Следует ли числовым значениям в возвращаемом объекте <fs.Stats> иметь тип bigint. По умолчанию: false.
  • signal <AbortSignal> AbortSignal для отмены операции. По умолчанию: undefined.
• Возвращает: <Promise> В случае выполнения содержит объект <fs.Stats> для файла.

filehandle.sync()

• Возвращает: <Promise> В случае успешного выполнения содержит undefined.

Запрашивает сброс всех данных для открытого дескриптора файла на устройство хранения. Конкретная реализация зависит от операционной системы и устройства. Подробнее см. в документации POSIX fsync(2).

filehandle.truncate(len)

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

Усекает файл.

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

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

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

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

Если исходный размер файла был меньше len байт, файл увеличивается, а добавленная часть заполняется нулевыми байтами ('\0'):

Если len отрицательно, будет использоваться 0.

filehandle.utimes(atime, mtime)

• atime <number> | <string> | <Date>
• mtime <number> | <string> | <Date>
• Возвращает: <Promise>

Изменяет временные метки файловой системы объекта, на который ссылается <FileHandle>, после чего в случае успеха промис выполняется без аргументов.

filehandle.write(buffer, offset[, length[, position]])

• buffer <Buffer> | <TypedArray> | <DataView>
• offset <integer> Начальная позиция данных для записи внутри buffer.
• length <integer> Количество байтов, записываемых из buffer. По умолчанию: buffer.byteLength - offset
• position <integer> | <null> Смещение от начала файла, по которому следует записать данные из buffer. Если position не является значением number, данные будут записаны в текущую позицию. Подробнее см. в документации POSIX pwrite(2). По умолчанию: null
• Возвращает: <Promise>

Записывает buffer в файл.

Промис выполняется с объектом, содержащим два свойства:

• bytesWritten <integer> количество записанных байтов
• buffer <Buffer> | <TypedArray> | <DataView> ссылка на записанный buffer.

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

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

filehandle.write(buffer[, options])

• buffer <Buffer> | <TypedArray> | <DataView>
• options <Object>
  • offset <integer> По умолчанию: 0
  • length <integer> По умолчанию: buffer.byteLength - offset
  • position <integer> | <null> По умолчанию: null
• Возвращает: <Promise>

Записывает buffer в файл.

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

filehandle.write(string[, position[, encoding]])

• string <string>
• position <integer> | <null> Смещение от начала файла, по которому должны быть записаны данные из string. Если position не является значением number, данные будут записаны в текущую позицию. Подробнее см. документацию POSIX по функции pwrite(2). По умолчанию: null
• encoding <string> Ожидаемая кодировка строки. По умолчанию: 'utf8'
• Возвращает: <Promise>

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

Промис будет выполнен с объектом, содержащим два свойства:

• bytesWritten <integer> количество записанных байтов
• buffer <string> ссылка на записанное значение string.

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

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

filehandle.writeFile(data, options)

• data <string> | <Buffer> | <TypedArray> | <DataView> | <AsyncIterable> | <Stream>
• options <Object> | <string>
  • encoding <string> | <null> Ожидаемая кодировка символов, если data является строкой. По умолчанию: 'utf8'
  • signal <AbortSignal> | <undefined> позволяет прервать выполняющуюся операцию writeFile. По умолчанию: undefined
• Возвращает: <Promise>

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

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

<FileHandle> должен поддерживать запись.

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

Если для файлового дескриптора выполняется один или несколько вызовов filehandle.write(), а затем вызов filehandle.writeFile(), данные будут записаны с текущей позиции до конца файла. Запись не всегда начинается с начала файла.

filehandle.writev(buffers[, position])

• buffers <Buffer[]> | <TypedArray[]> | <DataView[]>
• position <integer> | <null> Смещение от начала файла, по которому должны быть записаны данные из buffers. Если position не является number, данные будут записаны в текущую позицию. По умолчанию: null
• Возвращает: <Promise>

Записывает массив объектов {ArrayBufferView} в файл.

Промис разрешается объектом, содержащим два свойства:

• bytesWritten <integer> количество записанных байтов
• buffers <Buffer[]> | <TypedArray[]> | <DataView[]> ссылка на входные данные buffers.

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

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

filehandle.writer([options])

• options <Object>
  • autoClose <boolean> Закрывать файловый дескриптор после завершения работы средства записи или при ошибке. По умолчанию: false.
  • start <number> Смещение в байтах, с которого начинается запись. Если указано, запись выполняется с явным позиционированием. По умолчанию: текущая позиция в файле.
  • limit <number> Максимальное количество байтов, принимаемое средством записи. Асинхронные операции записи (write(), writev()), превышающие лимит, отклоняются с ERR_OUT_OF_RANGE. Синхронные операции записи (writeSync(), writevSync()) возвращают false. По умолчанию: без ограничений.
  • chunkSize <number> Максимальный размер блока в байтах для синхронных операций записи. Запись данных, превышающих этот порог, выполняется асинхронно. Для оптимальной производительности pipeTo() установите это значение равным chunkSize средства чтения. По умолчанию: 131072 (128 КБ).

• Возвращает: <Object>
  • write(chunk[, options]) <Function> Возвращает <Promise>. Принимает Uint8Array, Buffer или строку (в кодировке UTF-8).
    • chunk <Buffer> | <TypedArray> | <DataView> | <string>
    • options <Object>
      • signal <AbortSignal> Если сигнал уже прерван, запись завершается отказом с AbortError без выполнения операций ввода-вывода.
  • writev(chunks[, options]) <Function> Возвращает <Promise>. Использует scatter/gather-ввод-вывод посредством одного системного вызова writev(). Принимает массивы, содержащие как Uint8Array, так и строки.
    • chunks <Buffer[]> | <TypedArray[]> | <DataView[]> | <string[]>
    • options <Object>
      • signal <AbortSignal> Если сигнал уже прерван, запись завершается отказом с AbortError без выполнения операций ввода-вывода.
  • writeSync(chunk) <Function> Возвращает <boolean>. Пытается выполнить синхронную запись. Возвращает true, если запись выполнена успешно, и false, если вызывающему коду следует перейти к асинхронной записи write(). Возвращает false, если: запись закрыта или находится в состоянии ошибки; выполняется асинхронная операция; размер фрагмента превышает chunkSize или запись превысит limit.
    • chunk <Buffer> | <TypedArray> | <DataView> | <string>
  • writevSync(chunks) <Function> Возвращает <boolean>. Синхронная пакетная запись. Семантика перехода к резервному варианту такая же, как у writeSync().
    • chunks <Buffer[]> | <TypedArray[]> | <DataView[]> | <string[]>
  • end([options]) <Function> Возвращает <Promise>, который выполняется с общим числом записанных байтов. Идемпотентен: возвращает totalBytesWritten, если запись уже закрыта, и возвращает ожидающий промис, если запись уже закрывается. Отклоняется, если запись находится в состоянии ошибки.
    • options <Object>
      • signal <AbortSignal> Если сигнал уже прерван, end() отклоняется с AbortError, а запись остается открытой.
  • endSync() <Function> Возвращает <number> | <number> — общее число записанных байтов при успехе; -1, если запись находится в состоянии ошибки или выполняется асинхронная операция. Идемпотентен, если запись уже закрыта.
  • fail(reason) <Function> Переводит запись в конечное состояние ошибки. Выполняется синхронно. Если запись уже закрыта или находится в состоянии ошибки, ничего не делает. Если autoClose имеет значение true, синхронно закрывает файловый дескриптор.

Возвращает записывающий поток node:stream/iter, использующий этот файловый дескриптор.

Запись поддерживает как Symbol.asyncDispose, так и Symbol.dispose:

• await using w = fh.writer() — если запись все еще открыта (вызов end() еще не выполнен), asyncDispose вызывает fail(). Если end() ожидает завершения, он дожидается этого.
• using w = fh.writer() — безусловно вызывает fail().

Методы writeSync() и writevSync() обеспечивают быстрый путь try-sync, используемый в stream/iter pipeTo(). Если размер фрагмента читателя совпадает с chunkSize записывающего потока, все операции записи в конвейере pipeTo() завершаются синхронно, без затрат на промисы.

Эта функция доступна только при включенном флаге --experimental-stream-iter.

import { open } from 'node:fs/promises';
import { from, pipeTo } from 'node:stream/iter';
import { compressGzip } from 'node:zlib/iter';

// Async pipeline
const fh = await open('output.gz', 'w');
await pipeTo(from('Hello!'), compressGzip(), fh.writer({ autoClose: true }));

// Sync pipeline with limit
const src = await open('input.txt', 'r');
const dst = await open('output.txt', 'w');
const w = dst.writer({ limit: 1024 * 1024 }); // Max 1 MB
await pipeTo(src.pull({ autoClose: true }), w);
await w.end();
await dst.close();

const { open } = require('node:fs/promises');
const { from, pipeTo } = require('node:stream/iter');
const { compressGzip } = require('node:zlib/iter');

async function run() {
  // Async pipeline
  const fh = await open('output.gz', 'w');
  await pipeTo(from('Hello!'), compressGzip(), fh.writer({ autoClose: true }));

  // Sync pipeline with limit
  const src = await open('input.txt', 'r');
  const dst = await open('output.txt', 'w');
  const w = dst.writer({ limit: 1024 * 1024 }); // Max 1 MB
  await pipeTo(src.pull({ autoClose: true }), w);
  await w.end();
  await dst.close();
}

run().catch(console.error);

filehandle[Symbol.asyncDispose]()

Вызывает filehandle.close() и возвращает промис, который выполняется после закрытия дескриптора файла.

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');
}
mjscopy

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

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

• path <string> | <Buffer> | <URL> | <FileHandle> имя файла или <FileHandle>
• data <string> | <Buffer>
• options <Object> | <string>
  • encoding <string> | <null> По умолчанию: 'utf8'
  • mode <integer> По умолчанию: 0o666
  • flag <string> См. поддерживаемые флаги файловой системы flags. По умолчанию: 'a'.
  • flush <boolean> Если true, базовый файловый дескриптор сбрасывается перед закрытием. По умолчанию: false.
• Возвращает: <Promise> При успешном выполнении возвращает undefined.

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

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

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

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

fsPromises.chmod(path, mode)

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

Изменяет разрешения файла.

fsPromises.chown(path, uid, gid)

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

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

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

• src <string> | <Buffer> | <URL> имя исходного файла для копирования
• dest <string> | <Buffer> | <URL> имя файла назначения для операции копирования
• mode <integer> Необязательные модификаторы, задающие поведение операции копирования. Можно создать маску, объединив побитовой операцией ИЛИ два или более значений (например, fs.constants.COPYFILE_EXCL | fs.constants.COPYFILE_FICLONE) По умолчанию: 0.
  • fs.constants.COPYFILE_EXCL: операция копирования завершится ошибкой, если dest уже существует.
  • fs.constants.COPYFILE_FICLONE: при выполнении операции копирования будет предпринята попытка создать reflink с копированием при записи. Если платформа не поддерживает копирование при записи, будет использован резервный механизм копирования.
  • fs.constants.COPYFILE_FICLONE_FORCE: при выполнении операции копирования будет предпринята попытка создать reflink с копированием при записи. Если платформа не поддерживает копирование при записи, операция завершится ошибкой.
• Возвращает: <Promise> При успешном выполнении возвращает undefined.

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

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

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

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

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

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') не поддерживаются.
  • followSymlinks <boolean> Если true, при раскрытии шаблонов ** выполняется переход по символьным ссылкам на каталоги. По умолчанию: false.
  • withFileTypes <boolean> true, если glob должен возвращать пути в виде Dirent, и false в противном случае. По умолчанию: false.
• Возвращает: <AsyncIterator> AsyncIterator, выдающий пути к файлам, соответствующим шаблону.

Если включен followSymlinks, обнаруженные циклы символьных ссылок не обходятся рекурсивно.

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

for await (const entry of glob('**/*.js'))
  console.log(entry);

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

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

fsPromises.lchmod(path, mode)

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

Изменяет разрешения символьной ссылки.

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

fsPromises.lchown(path, uid, gid)

• path <string> | <Buffer> | <URL>
• uid <integer>
• gid <integer>
• Возвращает: <Promise> В случае успеха выполняется с результатом undefined.

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

fsPromises.lutimes(path, atime, mtime)

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

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

fsPromises.link(existingPath, newPath)

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

Создаёт новую ссылку из existingPath на newPath. Подробнее см. документацию POSIX link(2).

fsPromises.lstat(path[, options])

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

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

fsPromises.mkdir(path[, options])

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

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

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

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

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

  console.log(`created ${createDir}`);
} catch (err) {
  console.error(err.message);
}

const { mkdir } = require('node:fs/promises');
const { join } = require('node:path');

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

  console.log(dirCreation);
  return dirCreation;
}

makeDirectory().catch(console.error);

fsPromises.mkdtemp(prefix[, options])

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

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

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

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

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

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

fsPromises.mkdtempDisposable(prefix[, options])

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

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

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

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

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

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

• path <string> | <Buffer> | <URL>
• flags <string> | <number> См. сведения о поддержке flags файловой системой. По умолчанию: 'r'.
• mode <string> | <integer> Задает режим файла (права доступа и биты sticky), если файл создается. Подробнее см. в разделе Режимы файлов. По умолчанию: 0o666 (доступен для чтения и записи)
• Возвращает: <Promise> Выполняется с объектом <FileHandle>.

Открывает <FileHandle>.

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

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

fsPromises.opendir(path[, options])

• path <string> | <Buffer> | <URL>
• options <Object>
  • encoding <string> | <null> По умолчанию: 'utf8'
  • bufferSize <number> Количество записей каталога, которые буферизуются во внутренней памяти при чтении каталога. Более высокие значения повышают производительность, но увеличивают потребление памяти. По умолчанию: 32
  • recursive <boolean> Разрешенный Dir будет объектом <AsyncIterable>, содержащим все вложенные файлы и каталоги. По умолчанию: false
• Возвращает: <Promise> Выполняется с объектом <fs.Dir>.

Асинхронно открывает каталог для итеративного сканирования. Подробнее см. документацию POSIX для opendir(3).

Создает объект <fs.Dir>, содержащий все необходимые функции для чтения каталога и его очистки.

Параметр encoding задает кодировку для path при открытии каталога и последующих операциях чтения.

Пример использования асинхронной итерации:

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

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

При использовании асинхронного итератора объект <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);
}
mjscopy

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);
}
mjscopy

Отмена выполняющегося запроса не отменяет отдельные запросы операционной системы, а лишь внутреннюю буферизацию, выполняемую 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> В настоящее время параметры не предоставляются. Ранее существовали параметры для recursive, maxBusyTries и emfileWait, но они были объявлены устаревшими и удалены. Аргумент options по-прежнему принимается для обратной совместимости, но не используется.
• Возвращает: <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.
  • throwIfNoEntry <boolean> Следует ли выбрасывать исключение, если запись файловой системы не существует, вместо возврата undefined. По умолчанию: true.
• Возвращает: <Promise> В случае успеха выполняется с объектом <fs.Stats> для указанного path.

fsPromises.statfs(path[, options])

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

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

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

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

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

fsPromises.truncate(path[, len])

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

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

fsPromises.unlink(path)

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

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

fsPromises.utimes(path, atime, mtime)

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

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

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

• Значениями могут быть числа, представляющие время эпохи Unix, объекты 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'.
  • ignore <string> | <RegExp> | <Function> | <Array> Шаблоны, которые нужно игнорировать. Строки являются шаблонами glob (с использованием minimatch), шаблоны RegExp проверяются на соответствие имени файла, а функции получают имя файла и возвращают true, если его нужно игнорировать. По умолчанию: undefined.
• Возвращает: <AsyncIterator> объектов со свойствами:
  • eventType <string> Тип изменения
  • filename <string> | <Buffer> | <null> Имя изменённого файла.

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

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

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

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

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

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

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

• file <string> | <Buffer> | <URL> | <FileHandle> имя файла или FileHandle
• data <string> | <Buffer> | <TypedArray> | <DataView> | <AsyncIterable> | <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);
}
mjscopy

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

fsPromises.constants

• Тип: <Object>

Возвращает объект, содержащий часто используемые константы для операций с файловой системой. Этот объект совпадает с fs.constants. Подробнее см. в разделе Константы FS.

API обратных вызовов

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

API обратных вызовов используют внутренний пул потоков Node.js для выполнения операций с файловой системой вне потока цикла событий. Эти операции не синхронизированы и не являются потокобезопасными. При одновременном изменении одного и того же файла необходимо соблюдать осторожность, иначе может произойти повреждение данных.

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`);
});
mjscopy

Не используйте 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;
      });
    }
  });
});
mjscopy

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

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;
    });
  }
});
mjscopy

чтение (НЕ РЕКОМЕНДУЕТСЯ)

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;
      });
    }
  });
});
mjscopy

чтение (РЕКОМЕНДУЕТСЯ)

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;
    });
  }
});
mjscopy

Приведённые выше примеры с пометкой «не рекомендуется» проверяют доступность файла, а затем используют его; примеры с пометкой «рекомендуется» лучше, поскольку они используют файл напрямую и обрабатывают возможную ошибку.

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

В 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!');
});
mjscopy

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

import { appendFile } from 'node:fs';

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

В качестве 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;
  }
});
mjscopy

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!');
});
mjscopy

Режимы файлов

Аргумент mode, используемый в методах fs.chmod() и fs.chmodSync(), представляет собой числовую битовую маску, созданную с помощью логического ИЛИ следующих констант:

Более простой способ задать mode — использовать последовательность из трёх восьмеричных цифр (например, 765). Крайняя левая цифра (7 в примере) задаёт разрешения владельца файла. Средняя цифра (6 в примере) задаёт разрешения группы. Крайняя правая цифра (5 в примере) задаёт разрешения для остальных.

Например, восьмеричное значение 0o765 означает:

• Владелец может читать, записывать и выполнять файл.
• Группа может читать и записывать файл.
• Остальные могут читать и выполнять файл.

При использовании обычных чисел там, где ожидаются режимы файлов, любое значение больше 0o777 может привести к зависящему от платформы поведению, для которого не гарантируется единообразная работа. Поэтому такие константы, как S_ISVTX, S_ISGID или S_ISUID, не предоставляются в fs.constants.

Ограничения: в Windows можно изменить только разрешение на запись, а различия между разрешениями для группы, владельца и остальных не реализованы.

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);
mjscopy

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);
mjscopy

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

mode задаёт режим файла (права доступа и бит закрепления), но только если файл был создан.

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

import { createReadStream } from 'node:fs';

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

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

fs.createWriteStream(path[, options])

• path <string> | <Buffer> | <URL>
• options <string> | <Object>
  • flags <string> См. поддерживаемые флаги файловой системы flags. По умолчанию: 'w'.
  • encoding <string> По умолчанию: 'utf8'
  • fd <integer> | <FileHandle> По умолчанию: null
  • mode <integer> По умолчанию: 0o666
  • autoClose <boolean> По умолчанию: true
  • emitClose <boolean> По умолчанию: true
  • start <integer>
  • fs <Object> | <null> По умолчанию: null
  • signal <AbortSignal> | <null> По умолчанию: null
  • highWaterMark <number> По умолчанию: 16384
  • flush <boolean> Если true, базовый файловый дескриптор сбрасывается перед его закрытием. По умолчанию: false.
• Возвращает: <fs.WriteStream>

options может также включать параметр start, позволяющий записывать данные в позицию, расположенную после начала файла; допустимые значения находятся в диапазоне [0, Number.MAX_SAFE_INTEGER]. Для изменения файла, а не его замены, может потребоваться установить параметр flags в значение r+ вместо значения w по умолчанию. encoding может принимать любое из значений, допустимых для <Buffer>.

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

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

С помощью параметра fs можно переопределить соответствующие реализации fs для open, write, writev и close. Переопределение write() без writev() может снизить производительность, поскольку некоторые оптимизации (_writev()) будут отключены. При указании параметра fs требуется переопределить как минимум один из write и writev. Если параметр fd не задан, также требуется переопределение open. Если autoClose равен true, также требуется переопределение close.

Как и <fs.ReadStream>, если указан fd, <fs.WriteStream> проигнорирует аргумент path и будет использовать указанный файловый дескриптор. Это означает, что событие 'open' генерироваться не будет. fd должен быть блокирующим; неблокирующие fd следует передавать в <net.Socket>.

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

fs.exists(path, callback)

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

Проверяет существование элемента по указанному адресу path с помощью файловой системы. Затем вызывает аргумент callback, передавая ему true или false:

import { exists } from 'node:fs';

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

Параметры этого обратного вызова отличаются от параметров других обратных вызовов 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;
        });
      }
    });
  }
});
mjscopy

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

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;
    });
  }
});
mjscopy

чтение (НЕ РЕКОМЕНДУЕТСЯ)

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');
  }
});
mjscopy

чтение (РЕКОМЕНДУЕТСЯ)

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;
    });
  }
});
mjscopy

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

Как правило, проверяйте существование файла, только если он не будет использоваться напрямую, например, когда его наличие служит сигналом от другого процесса.

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;
  }
});
mjscopy

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

• callback <Function>

  • err <Error>

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

Если включен followSymlinks, обнаруженные циклы символических ссылок не обходятся рекурсивно.

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

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

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

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

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

Callback получает возможное исключение и, если 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;
});
mjscopy

В Windows использование fs.mkdir() для корневого каталога даже с рекурсивным созданием приведет к ошибке:

import { mkdir } from 'node:fs';

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

Дополнительные сведения см. в документации 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 случайными символами.

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

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

Метод 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.
});
mjscopy

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().

Callback получает два аргумента (err, fd).

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

Функции, основанные на fs.open(), также ведут себя таким образом: fs.writeFile(), fs.readFile() и т. д.

fs.openAsBlob(path[, options])

• path <string> | <Buffer> | <URL>
• options <Object>
  • type <string> Необязательный MIME-тип для blob.
• Возвращает: <Promise> При успешном выполнении возвращает <Blob>.

Возвращает <Blob>, данные которого хранятся в указанном файле.

После создания <Blob> файл нельзя изменять. Любые изменения приведут к тому, что чтение данных <Blob> завершится ошибкой DOMException. Для обнаружения изменений данных файла на диске при создании Blob и перед каждым чтением выполняются синхронные операции stat.

import { openAsBlob } from 'node:fs';

const blob = await openAsBlob('the.file.txt');
const ab = await blob.arrayBuffer();
blob.stream();

const { openAsBlob } = require('node:fs');

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

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

• path <string> | <Buffer> | <URL>
• options <Object>
  • encoding <string> | <null> По умолчанию: 'utf8'
  • bufferSize <number> Количество записей каталога, которые буферизуются во внутренней памяти при чтении каталога. Более высокие значения повышают производительность, но увеличивают потребление памяти. По умолчанию: 32
  • recursive <boolean> По умолчанию: false
• callback <Function>
  • err <Error>
  • dir <fs.Dir>

Асинхронно открывает каталог. Дополнительные сведения см. в документации POSIX для opendir(3).

Создаёт <fs.Dir>, содержащий все последующие функции для чтения содержимого каталога и очистки ресурсов.

Опция encoding задаёт кодировку для path при открытии каталога и последующих операциях чтения.

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

• fd <integer>
• buffer <Buffer> | <TypedArray> | <DataView> Буфер, в который будут записаны данные.
• offset <integer> Позиция в buffer, в которую следует записать данные.
• length <integer> Количество байтов для чтения.
• position <integer> | <bigint> | <null> Указывает, с какого места в файле начать чтение. Если position равно null или -1 , данные будут прочитаны с текущей позиции в файле, а позиция в файле будет обновлена. Если position — неотрицательное целое число, позиция в файле останется неизменной.
• callback <Function>
  • err <Error>
  • bytesRead <integer>
  • buffer <Buffer>

Читает данные из файла, указанного в fd.

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

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

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

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

Например:

• Если файл короче указанного значения length, для bytesRead будет установлено фактическое число прочитанных байтов.
• Если в файле встретится EOF (конец файла) до заполнения буфера, Node.js прочитает все доступные байты до EOF, а параметр bytesRead в обратном вызове будет содержать фактическое число прочитанных байтов, которое может быть меньше указанного значения length.
• Если файл находится в медленной сетевой filesystem или во время чтения возникнет другая проблема, значение bytesRead может быть меньше указанного значения length.

Поэтому при использовании fs.read() важно проверять значение bytesRead, чтобы определить, сколько байтов действительно было прочитано из файла. В зависимости от логики приложения может потребоваться обработать случаи, когда bytesRead меньше указанного значения length, например обернуть вызов чтения в цикл, если требуется прочитать не меньше определённого количества байтов.

Это поведение аналогично функции POSIX preadv2.

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

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

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

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

• fd <integer>
• buffer <Buffer> | <TypedArray> | <DataView> Буфер, в который будут записаны данные.
• options <Object>
  • offset <integer> По умолчанию: 0
  • length <integer> По умолчанию: buffer.byteLength - offset
  • position <integer> | <bigint> По умолчанию: null
• callback <Function>
  • err <Error>
  • bytesRead <integer>
  • buffer <Buffer>

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

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

• path <string> | <Buffer> | <URL>
• options <string> | <Object>
  • encoding <string> По умолчанию: 'utf8'
  • withFileTypes <boolean> По умолчанию: false
  • recursive <boolean> Если true, содержимое каталога считывается рекурсивно. В рекурсивном режиме будут перечислены все файлы, вложенные файлы и каталоги. По умолчанию: false.
• callback <Function>
  • err <Error>
  • files <string[]> | <Buffer[]> | <fs.Dirent[]>

Считывает содержимое каталога. Обратный вызов получает два аргумента (err, files), где files — это массив имен файлов в каталоге, за исключением '.' и '..'.

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

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

Если для options.withFileTypes задано значение true, массив files будет содержать объекты <fs.Dirent>.

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

• path <string> | <Buffer> | <URL> | <integer> имя файла или файловый дескриптор
• options <Object> | <string>
  • encoding <string> | <null> По умолчанию: null
  • flag <string> См. поддерживаемые флаги файловой системы flags. По умолчанию: 'r'.
  • signal <AbortSignal> позволяет прервать выполняющуюся операцию readFile
• callback <Function>
  • err <Error> | <AggregateError>
  • data <string> | <Buffer>

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

import { readFile } from 'node:fs';

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

Callback получает два аргумента (err, data), где data — это содержимое файла.

Если кодировка не указана, возвращается исходный буфер.

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

import { readFile } from 'node:fs';

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

Если путь указывает на каталог, поведение 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>
});
mjscopy

Выполняющийся запрос можно прервать с помощью AbortSignal. При прерывании запроса callback вызывается с 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();
mjscopy

Функция fs.readFile() буферизует весь файл целиком. Чтобы сократить затраты памяти, по возможности используйте потоковую передачу через fs.createReadStream().

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

Файловые дескрипторы

1. Указанный файловый дескриптор должен поддерживать чтение.
2. Если в качестве path указан файловый дескриптор, он не будет закрыт автоматически.
3. Чтение начнётся с текущей позиции. Например, если файл уже содержал 'Hello World' и с помощью файлового дескриптора было прочитано шесть байтов, вызов fs.readFile() с тем же файловым дескриптором вернёт 'World', а не 'Hello World'.

Соображения производительности

Метод fs.readFile() асинхронно считывает содержимое файла в память по одному фрагменту за раз, позволяя циклу событий работать между чтениями фрагментов. Благодаря этому операция чтения меньше влияет на другие задачи, которые могут использовать пул потоков libuv, однако полное считывание файла в память занимает больше времени.

Дополнительные накладные расходы на чтение могут значительно различаться в разных системах и зависят от типа считываемого файла. Если файл не является обычным файлом (например, это канал) и Node.js не может определить его фактический размер, каждая операция чтения загрузит 64 KiB данных. Для обычных файлов при каждом чтении обрабатывается 512 KiB данных.

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

В задаче Node.js на GitHub #25741 приведены дополнительные сведения и подробный анализ производительности fs.readFile() для файлов разных размеров в различных версиях Node.js.

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

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

Читает содержимое символической ссылки, на которую указывает path. Колбэк получает два аргумента (err, linkString).

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

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

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

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

Читает данные из файла, указанного в fd, и записывает их в массив ArrayBufferView с помощью readv().

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

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

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

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

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

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

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

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

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

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

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

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

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

import { rename } from 'node:fs';

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

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

• path <string> | <Buffer> | <URL>
• options <Object> В настоящее время нет доступных параметров. Ранее существовали параметры recursive, maxBusyTries и emfileWait, но они устарели и были удалены. Аргумент options по-прежнему принимается для обратной совместимости, но не используется.
• callback <Function>
  • err <Error>

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

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

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

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

• path <string> | <Buffer> | <URL>
• options <Object>
  • force <boolean> Если true, исключения будут игнорироваться, если path не существует. По умолчанию: false.
  • maxRetries <integer> При возникновении ошибки EBUSY, EMFILE, ENFILE, ENOTEMPTY или EPERM Node.js повторит операцию, увеличивая время ожидания при линейном экспоненциальном откате на retryDelay миллисекунд с каждой попыткой. Эта опция задаёт количество повторных попыток. Опция игнорируется, если опция recursive не равна true. По умолчанию: 0.
  • recursive <boolean> Если true, выполняется рекурсивное удаление. В рекурсивном режиме при сбое операции повторяются. По умолчанию: false.
  • retryDelay <integer> Время ожидания между повторными попытками в миллисекундах. Опция игнорируется, если опция recursive не равна true. По умолчанию: 100.
• callback <Function>
  • err <Error>

Асинхронно удаляет файлы и каталоги (работа основана на стандартной утилите POSIX rm). Функция обратного вызова завершения получает аргументы только в случае возможного исключения.

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

• path <string> | <Buffer> | <URL>
• options <Object>
  • bigint <boolean> Должны ли числовые значения в возвращаемом объекте <fs.Stats> иметь тип bigint. По умолчанию: false.
  • throwIfNoEntry <boolean> Следует ли выбрасывать исключение, если запись в файловой системе отсутствует, вместо возврата undefined. По умолчанию: true.
• 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
textcopy

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

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);
  });
}
mjscopy

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

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,
  atimeInstant: 2019-06-22T03:37:33.071963Z,
  mtimeInstant: 2019-06-22T03:36:54.5833518Z,
  ctimeInstant: 2019-06-22T03:37:06.6235366Z,
  birthtimeInstant: 2019-06-22T03:28:46.9372893Z
}
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,
  atimeInstant: 2019-06-22T03:36:56.6188555Z,
  mtimeInstant: 2019-06-22T03:36:54.584Z,
  ctimeInstant: 2019-06-22T03:36:54.5838145Z,
  birthtimeInstant: 2019-06-22T03:26:47.7107478Z
}
consolecopy

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

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

import { symlink } from 'node:fs';

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

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

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

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');
});
mjscopy

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])