Пример с обещаниями

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

Модули MJS

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

Модули CJS

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.

Модули MJS

import { unlink } from 'node:fs';

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

Модули CJS

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, или может быть допущено до подъёма по стеку вызовов.

Модули MJS

import { unlinkSync } from 'node:fs';

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

Модули CJS

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 <строка> | <Буфер> | <Массив типов> | <DataView> | <Асинхронный итерируемый объект> | <Итерируемый объект> | <Поток>
• options <Объект> | <строка>
  • encoding <строка> | <null> По умолчанию: 'utf8'
• Возвращает: <Обещание> Выполняется с undefined при успехе.

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

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

filehandle.chmod(mode)

• mode <целое число> маска битов режима файла.
• Возвращает: <Обещание> Выполняется с undefined при успехе.

Изменяет разрешения файла. См. chmod(2).

filehandle.chown(uid, gid)

• uid <целое число> Новый идентификатор пользователя владельца файла.
• gid <целое число> Новый идентификатор группы владельца файла.
• Возвращает: <Обещание> Выполняется с undefined при успехе.

Изменяет владение файлом. Оболочка для chown(2).

filehandle.close()

• Возвращает: <Обещание> Выполняется с undefined при успехе.

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

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

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

filehandle.createReadStream([options])

• options <Объект>
  • encoding <строка> По умолчанию: null
  • autoClose <логическое значение> По умолчанию: true
  • emitClose <логическое значение> По умолчанию: true
  • start <целое число>
  • end <целое число> По умолчанию: Infinity
  • highWaterMark <целое число> По умолчанию: 64 * 1024
• Возвращает: <fs.ReadStream>

В отличие от 16 Кбайт по умолчанию highWaterMark для <stream.Readable>, поток, возвращаемый этим методом, имеет значение по умолчанию highWaterMark в 64 Кбайта.

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

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

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

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

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

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

filehandle.createWriteStream([options])

• options <Объект>
  • encoding <строка> По умолчанию: 'utf8'
  • autoClose <логическое значение> По умолчанию: true
  • emitClose <логическое значение> По умолчанию: true
  • start <целое число>
• Возвращает: <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

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

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

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

Читает данные из файла и записывает их в указанный буфер.

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

filehandle.read([options])

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

Читает данные из файла и записывает их в указанный буфер.

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

filehandle.read(buffer[, options])

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

Читает данные из файла и записывает их в указанный буфер.

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

filehandle.readableWebStream(options)

• options <Объект>

  • type <строка> | <неопределено> Нужно ли открыть обычный или 'bytes' поток. По умолчанию: undefined

• Возвращает: <Поток чтения>

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

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

Модули MJS

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

Модули CJS

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

filehandle.readFile(options)

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

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

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

У <Дескриптор файла> должна быть возможность чтения.

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

filehandle.readLines([options])

• options <Объект>
  • encoding <строка> По умолчанию: null
  • autoClose <логическое значение> По умолчанию: true
  • emitClose <логическое значение> По умолчанию: true
  • start <целое число>
  • end <целое число> По умолчанию: Infinity
  • highWaterMark <целое число> По умолчанию: 64 * 1024
• Возвращает: <Конструктор интерфейса readline>

Удобный метод для создания интерфейса readline и потока над файлом. Смотрите filehandle.createReadStream() для параметров.

Модули MJS

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

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

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

Модули CJS

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 <Массив буферов> | <Массив типов данных> | <DataView>
• position <целое число> | <null> Смещение от начала файла, откуда должны быть считаны данные. Если position не является number, данные будут считаны с текущей позиции. По умолчанию: null
• Возвращает: <Обещание> При успехе выполняет объект с двумя свойствами:
  • bytesRead <целое число> число прочитанных байтов
  • buffers <Массив буферов> | <Массив типов данных> | <DataView> свойство, содержащее ссылку на buffers ввод.

Чтение из файла и запись в массив <ArrayBufferView>

filehandle.stat([options])

• options <Объект>
  • bigint <логическое значение> Нужно ли числовые значения в возвращаемом объекте <fs.Stats> быть bigint. По умолчанию: false.
• Возвращает: <Обещание> Возвращает <fs.Stats> для файла.

filehandle.sync()

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

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

filehandle.truncate(len)

• len <целое число> По умолчанию: 0
• Возвращает: <Обещание> Выполняется со значением 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();
} copy

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

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

filehandle.utimes(atime, mtime)

• atime <число> | <строка> | <Дата>
• mtime <число> | <строка> | <Дата>
• Возвращает: <Обещание>

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

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

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

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

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

• bytesWritten <целое число> количество записанных байтов
• buffer <Буфер> | <Массив с типом> | <DataView> ссылка на записанный buffer.

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

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

filehandle.write(buffer[, options])

• buffer <Буфер> | <Массив с типом> | <DataView>
• options <Объект>
  • offset <целое число> По умолчанию: 0
  • length <целое число> По умолчанию: buffer.byteLength - offset
  • position <целое число> По умолчанию: null
• Возвращает: <Обещание>

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

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

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

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

Записать string в файл. Если string не является строкой, обещание отклоняется с ошибкой.

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

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

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

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

filehandle.writeFile(data, options)

• data <строка> | <Буфер> | <Массив с типом> | <DataView> | <Асинхронно-итерируемый объект> | <Итерируемый объект> | <Поток>
• options <Объект> | <строка>
  • encoding <строка> | <null> Ожидаемая кодировка символов, когда data является строкой. По умолчанию: 'utf8'
• Возвращает: <Обещание>

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

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

У <Дескриптор файла> должна поддерживаться запись.

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

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

filehandle.writev(buffers[, position])

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

Записывает массив <ArrayBufferView> в файл.

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

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

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

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

filehandle[Symbol.asyncDispose]()

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

fsPromises.access(path[, mode])

• path <строка> | <Буфер> | <URL>
• mode <целое> По умолчанию: 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.

Если проверка доступности успешна, обещание выполняется без значения. Если какая-либо из проверок доступности завершится ошибкой, обещание отклоняется с объектом <Ошибка>. В следующем примере проверяется, может ли файл /etc/passwd читаться и записываться текущим процессом.

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

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

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

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

• path <строка> | <Буфер> | <URL> | <Дескриптор файла> имя файла или <Дескриптор файла>
• data <строка> | <Буфер>
• options <Объект> | <строка>
  • encoding <строка> | <null> По умолчанию: 'utf8'
  • mode <целое> По умолчанию: 0o666
  • flag <строка> Смотрите поддержку флагов файловой системы flags. По умолчанию: 'a'.
• Возвращает: <Promise> Выполняется с undefined при успехе.

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

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

Опция mode влияет только на только что созданный файл. См. fs.open() для получения дополнительных сведений.

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

fsPromises.chmod(path, mode)

• path <строка> | <Буфер> | <URL>
• mode <строка> | <целое>
• Возвращает: <Promise> Выполняется с undefined при успехе.

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

fsPromises.chown(path, uid, gid)

• path <строка> | <Буфер> | <URL>
• uid <целое>
• gid <целое>
• Возвращает: <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: Операция копирования попытается создать ссылку с копированием при изменении. Если платформа не поддерживает копирование при изменении, используется резервный механизм копирования.
  • fs.constants.COPYFILE_FICLONE_FORCE: Операция копирования попытается создать ссылку с копированием при изменении. Если платформа не поддерживает копирование при изменении, операция завершится ошибкой.
• Возвращает: <Promise> При успешном выполнении возвращает undefined.

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

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

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

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

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

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

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

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

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

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 — ложь.

Модули MJS

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

Модули CJS

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

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

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

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

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

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

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

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

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

Для получения более подробной информации, обратитесь к документации POSIX open(2).

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

fsPromises.opendir(path[, options])

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

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

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

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

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

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

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

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

fsPromises.readdir(path[, options])

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

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

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

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

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

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

fsPromises.readFile(path[, options])

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

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

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

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

Если path является каталогом, поведение fsPromises.readFile() зависит от платформы. На macOS, Linux и Windows обещание будет отклонено с ошибкой. На FreeBSD будет возвращена информация о содержимом каталога.

Пример чтения файла package.json, расположенного в том же каталоге, что и исполняемый код:

MJS модули

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

CJS модули

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

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

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

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

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

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

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

Любой указанный <FileHandle> должен поддерживать чтение.

fsPromises.readlink(path[, options])

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

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

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

fsPromises.realpath(path[, options])

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

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

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

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

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

fsPromises.rename(oldPath, newPath)

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

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

fsPromises.rmdir(path[, options])

• path <строка> | <Buffer> | <URL>
• options <Объект>
  • maxRetries <целое число> Если возникает ошибка EBUSY, EMFILE, ENFILE, ENOTEMPTY, или EPERM, Node.js повторит операцию с линейной задержкой ожидания retryDelay миллисекунд больше на каждой попытке. Эта опция представляет количество повторений. Эта опция игнорируется, если опция recursive не равна true. По умолчанию: 0.
  • recursive <булево значение> Если true, выполняется рекурсивное удаление каталога. В рекурсивном режиме операции повторяются при ошибке. По умолчанию: false. Устарело.
  • retryDelay <целое число> Время в миллисекундах, которое нужно ждать между повторными попытками. Эта опция игнорируется, если опция recursive не равна true. По умолчанию: 100.
• Возвращает: <Promise> При успехе выполняет undefined.

Удаляет каталог, идентифицированный по path.

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

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

fsPromises.rm(path[, options])

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

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

fsPromises.stat(path[, options])

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

fsPromises.statfs(path[, options])

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

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

• target <строка> | <Buffer> | <URL>
• path <строка> | <Buffer> | <URL>
• type <строка> По умолчанию: 'file'
• Возвращает: <Promise> Выполняется с undefined при успехе.

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

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

fsPromises.truncate(path[, len])

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

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

fsPromises.unlink(path)

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

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

fsPromises.utimes(path, atime, mtime)

• path <строка> | <Buffer> | <URL>
• atime <число> | <строка> | <Дата>
• mtime <число> | <строка> | <Дата>
• Возвращает: <Promise> Выполняется с undefined при успехе.

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

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

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

fsPromises.watch(filename[, options])

• filename <строка> | <Buffer> | <URL>
• options <строка> | <Объект>
  • persistent <логическое значение> Указывает, должен ли процесс продолжать работу, пока отслеживаются файлы. По умолчанию: true.
  • recursive <логическое значение> Указывает, должны ли отслеживаться все подкаталоги или только текущий каталог. Это применяется при указании каталога и только на поддерживаемых платформах (см. ограничения). По умолчанию: false.
  • encoding <строка> Указывает кодировку символов, которая должна использоваться для имени файла, передаваемого слушателю. По умолчанию: 'utf8'.
  • signal <AbortSignal> <Объект отмены> используемый для сигнализации о том, когда наблюдатель должен остановиться.
• Возвращает: <Асинхронный итератор> объектов со свойствами:
  • eventType <строка> Тип изменения
  • filename <строка> | <Buffer> | <null> Имя изменённого файла.

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

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

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

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

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

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

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

• file <строка> | <Buffer> | <URL> | <FileHandle> имя файла или FileHandle
• data <строка> | <Buffer> | <TypedArray> | <DataView> | <AsyncIterable> | <Iterable> | <Поток>
• options <Объект> | <строка>
  • encoding <строка> | <null> По умолчанию: 'utf8'
  • mode <целое число> По умолчанию: 0o666
  • flag <строка> См. поддержку флагов файловой системы flags. По умолчанию: 'w'.
  • 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().

Можно использовать <AbortSignal> для отмены fsPromises.writeFile(). Отмена выполняется с наилучшими результатами, и возможно, некоторое количество данных всё ещё будет записано.

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

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

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

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

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

fsPromises.constants

• <Объект>

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

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

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

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

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

• path <строка> | <Буфер> | <URL>
• mode <целое число> По умолчанию: fs.constants.F_OK
• callback <Функция>
  • err <Ошибка>

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

Окончательный аргумент, callback, — это функция обратного вызова, которая вызывается с возможным аргументом ошибки. Если какая-либо из проверок доступности завершается неудачей, аргумент ошибки будет объектом Error. Примеры ниже проверяют, существует ли package.json, и является ли он читаемым или записываемым.

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

const file = 'package.json';

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

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

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

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

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

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

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

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

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

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

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

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

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

    throw err;
  }

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

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

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

    throw err;
  }

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

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

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

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

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

    throw err;
  }

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

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

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

В Windows политики управления доступом (ACL) к каталогу могут ограничивать доступ к файлу или каталогу. Однако функция fs.access() не проверяет ACL и, следовательно, может сообщать, что путь доступен, даже если ACL запрещает пользователю чтение или запись в него.

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

• path <строка> | <Буфер> | <URL> | <число> имя файла или дескриптор файла
• data <строка> | <Буфер>
• options <Объект> | <строка>
  • encoding <строка> | <null> По умолчанию: 'utf8'
  • mode <целое число> По умолчанию: 0o666
  • flag <строка> См. поддержку флагов файловой системы flags. По умолчанию: 'a'.
• callback <Функция>
  • err <Ошибка>

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

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

import { appendFile } from 'node:fs';

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

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

import { appendFile } from 'node:fs';

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

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

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

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

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

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

fs.chmod(path, mode, callback)

• path <строка> | <Буфер> | <URL>
• mode <строка> | <целое число>
• callback <Функция>
  • err <Ошибка>

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

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

import { chmod } from 'node:fs';

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

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

Аргумент 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 <строка> | <Буфер> | <URL>
• uid <целое число>
• gid <целое число>
• callback <Функция>
  • err <Ошибка>

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

См. документацию POSIX chown(2) для получения более подробной информации.

fs.close(fd[, callback])

• fd <целое число>
• callback <Функция>
  • err <Ошибка>

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

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

См. документацию POSIX close(2) для получения более подробной информации.

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

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

Асинхронно копирует 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: операция копирования попытается создать ссылку с копированием при изменении. Если платформа не поддерживает копирование при изменении, используется резервный механизм копирования.
• fs.constants.COPYFILE_FICLONE_FORCE: операция копирования попытается создать ссылку с копированием при изменении. Если платформа не поддерживает копирование при изменении, операция завершится ошибкой.

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

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

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

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

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

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

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

При копировании каталога в другой каталог шаблоны (globs) не поддерживаются, и поведение аналогично 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>

В отличие от значения по умолчанию в 16 КБ для <stream.Readable>, поток, возвращаемый этим методом, имеет значение по умолчанию highWaterMark в 64 КБ.

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

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

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

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

Предоставление параметра fs позволяет переопределить соответствующие реализации fs для open, read, и close. При предоставлении параметра fs требуется переопределение для read. Если параметр fd не предоставлен, также требуется переопределение для open. Если autoClose равно true, также требуется переопределение для close.

import { createReadStream } from 'node:fs';

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

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

mode задаёт режим файла (разрешения и биты «sticky»), но только если файл был создан.

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

import { createReadStream } from 'node:fs';

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

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

fs.createWriteStream(path[, options])

• path <строка> | <Буфер> | <URL>
• options <строка> | <объект>
  • flags <строка> См. поддержку флагов файловой системы flags. По умолчанию: 'w'.
  • encoding <строка> По умолчанию: 'utf8'
  • fd <целое число> | <FileHandle> По умолчанию: null
  • mode <целое число> По умолчанию: 0o666
  • autoClose <логическое значение> По умолчанию: true
  • emitClose <логическое значение> По умолчанию: true
  • start <целое число>
  • fs <объект> | <null> По умолчанию: null
  • signal <AbortSignal> | <null> По умолчанию: null
• Возвращает: <fs.WriteStream>

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

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

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

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

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

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

fs.exists(path, callback)

• path <строка> | <Буфер> | <URL>
• callback <Функция>
  • exists <логическое значение>

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

import { exists } from 'node:fs';

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

Параметры для этого обратного вызова не согласованы с другими обратными вызовами Node.js. Обычно первым параметром обратного вызова Node.js является параметр err, за которым могут следовать другие параметры. Обратный вызов fs.exists() имеет только один логический параметр. Это одна из причин, по которой рекомендуется использовать fs.access() вместо fs.exists().

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

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

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

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

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

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

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

    throw err;
  }

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

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

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

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

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

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

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

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

    throw err;
  }

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

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

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

fs.fchmod(fd, mode, callback)

• fd <целое>
• mode <строка> | <целое>
• callback <Функция>
  • err <Ошибка>

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

См. документацию POSIX fchmod(2) для более подробной информации.

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

• fd <целое>
• uid <целое>
• gid <целое>
• callback <Функция>
  • err <Ошибка>

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

См. документацию POSIX fchown(2) для более подробной информации.

fs.fdatasync(fd, callback)

• fd <целое>
• callback <Функция>
  • err <Ошибка>

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

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

• fd <целое>
• options <Объект>
  • bigint <логическое> Указывает, должны ли числовые значения в возвращаемом объекте <fs.Stats> быть bigint. По умолчанию: false.
• callback <Функция>
  • err <Ошибка>
  • stats <fs.Stats>

Вызывает обратный вызов с объектом <fs.Stats> для дескриптора файла.

См. документацию POSIX fstat(2) для более подробной информации.

fs.fsync(fd, callback)

• fd <целое>
• callback <Функция>
  • err <Ошибка>

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

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

• fd <целое>
• len <целое> По умолчанию: 0
• callback <Функция>
  • err <Ошибка>

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

Для получения более подробной информации см. документацию POSIX ftruncate(2).

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

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

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

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

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

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

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

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

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

• fd <целое>
• atime <число> | <строка> | <Дата>
• mtime <число> | <строка> | <Дата>
• callback <Функция>
  • err <Ошибка>

Изменяет системные метки времени доступа и изменения объекта, на который указывает предоставленный дескриптор файла. См. fs.utimes().

fs.lchmod(path, mode, callback)

• path <строка> | <Буфер> | <URL>
• mode <целое>
• callback <Функция>
  • err <Ошибка> | <Собранная ошибка>

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

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

Для получения более подробной информации см. документацию POSIX lchmod(2).

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

• path <строка> | <Буфер> | <URL>
• uid <целое>
• gid <целое>
• callback <Функция>
  • err <Ошибка>

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

Для получения более подробной информации см. документацию POSIX lchown(2).

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

• path <строка> | <Буфер> | <URL>
• atime <число> | <строка> | <Дата>
• mtime <число> | <строка> | <Дата>
• callback <Функция>
  • err <Ошибка>

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

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

fs.link(existingPath, newPath, callback)

• existingPath <строка> | <Буфер> | <URL>
• newPath <строка> | <Буфер> | <URL>
• callback <Функция>
  • err <Ошибка>

Создаёт новую ссылку из existingPath на newPath. Для получения подробной информации см. документацию POSIX link(2). Никаких аргументов, кроме возможного исключения, не передаётся в обратный вызов.

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

• path <строка> | <Буфер> | <URL>
• options <Объект>
  • bigint <логическое> Должны ли числовые значения в возвращаемом объекте <fs.Stats> быть bigint. По умолчанию: false.
• callback <Функция>
  • err <Ошибка>
  • stats <fs.Stats>

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

Для получения дополнительной информации см. документацию POSIX lstat(2).

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

• path <строка> | <Буфер> | <URL>
• options <Объект> | <целое>
  • recursive <логическое> По умолчанию: false
  • mode <строка> | <целое> Не поддерживается в Windows. По умолчанию: 0o777.
• callback <Функция>
  • err <Ошибка>
  • path <строка> | <неопределён> Присутствует только если каталог был создан с recursive установленным в true.

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

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

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

import { mkdir } from 'node:fs';

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

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

import { mkdir } from 'node:fs';

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

Для получения дополнительной информации см. документацию POSIX mkdir(2).

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

• prefix <строка>
• options <строка> | <объект>
  • encoding <строка> По умолчанию: 'utf8'
• callback <Функция>
  • err <Ошибка>
  • directory <строка>

Создаёт уникальную временную директорию.

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

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

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

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

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

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

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

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

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

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

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

• path <строка> | <Буфер> | <URL>
• flags <строка> | <число> См. поддержку флагов файловой системы flags. По умолчанию: 'r'.
• mode <строка> | <целое> По умолчанию: 0o666 (чтение и запись)
• callback <Функция>
  • err <Ошибка>
  • fd <целое>

Асинхронное открытие файла. См. документацию POSIX open(2) для более подробной информации.

mode задаёт режим файла (разрешения и биты "stickiness"), но только если файл был создан. В Windows можно манипулировать только правом записи; см. fs.chmod().

Обратный вызов получает два аргумента (err, fd).

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

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

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

• path <строка> | <Буфер> | <URL>
• options <Объект>
  • encoding <строка> | <null> По умолчанию: 'utf8'
  • bufferSize <число> Число записей каталога, буферизованных внутри при чтении из каталога. Более высокие значения приводят к лучшей производительности, но и большему потреблению памяти. По умолчанию: 32
  • recursive <булево> По умолчанию: false
• callback <Функция>
  • err <Ошибка>
  • dir <fs.Dir>

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

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

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

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

• fd <целое>
• buffer <Буфер> | <Тип массива> | <DataView> Буфер, в который будут записаны данные.
• offset <целое> Позиция в buffer для записи данных.
• length <целое> Количество байтов для чтения.
• position <целое> | <null> Указывает, с какой позиции начать чтение в файле. Если position имеет значение null или -1 , данные будут считаны с текущей позиции файла, и позиция файла будет обновлена. Если position — целое число, позиция файла останется неизменной.
• callback <Функция>
  • err <Ошибка>
  • bytesRead <целое>
  • buffer <Буфер>

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

Обратный вызов получает три аргумента (err, bytesRead, buffer).

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

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

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

• fd <целое>
• options <Объект>
  • buffer <Буфер> | <Массив типов> | <Представление данных> По умолчанию: Buffer.alloc(16384)
  • offset <целое> По умолчанию: 0
  • length <целое> По умолчанию: buffer.byteLength - offset
  • position <целое> | <bigint> | <null> По умолчанию: null
• callback <Функция>
  • err <Ошибка>
  • bytesRead <целое>
  • buffer <Буфер>

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

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

• fd <целое>
• buffer <Буфер> | <Массив типов> | <Представление данных> Буфер, в который будут записаны данные.
• options <Объект>
  • offset <целое> По умолчанию: 0
  • length <целое> По умолчанию: buffer.byteLength - offset
  • position <целое> | <bigint> По умолчанию: null
• callback <Функция>
  • err <Ошибка>
  • bytesRead <целое>
  • buffer <Буфер>

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

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

• path <строка> | <Буфер> | <URL>
• options <строка> | <Объект>
  • encoding <строка> По умолчанию: 'utf8'
  • withFileTypes <логическое> По умолчанию: false
  • recursive <логическое> По умолчанию: false
• callback <Функция>
  • err <Ошибка>
  • files <массив строк> | <массив буферов> | <массив fs.Dirent>

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

См. документацию POSIX readdir(3) для более подробной информации.

Необязательный аргумент options может быть строкой, задающей кодировку, или объектом с свойством encoding, определяющим кодировку символов для имён файлов, переданных в функцию обратного вызова. Если encoding установлено в '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> позволяет прервать текущее чтение файла
• callback <Function>
  • err <Error> | <AggregateError>
  • data <string> | <Buffer>

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

import { readFile } from 'node:fs';

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

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

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

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

import { readFile } from 'node:fs';

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

Когда путь указывает на директорию, поведение fs.readFile() и fs.readFileSync() зависит от платформы. На macOS, Linux и Windows возвращается ошибка. На FreeBSD — представление содержимого директории.

import { readFile } from 'node:fs';

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

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

Можно прервать текущий запрос с помощью AbortSignal. Если запрос прерван, обработчик вызывается с AbortError.

import { readFile } from 'node:fs';

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

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

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

Дескрипторы файлов

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

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

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

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

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

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

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

• path <string> | <Buffer> | <URL>
• options <Object> | <string>
  • 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 <строка> | <Buffer> | <URL>
• options <строка> | <Объект>
  • encoding <строка> По умолчанию: 'utf8'
• callback <Функция>
  • err <Ошибка>
  • resolvedPath <строка> | <Buffer>

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

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

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

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

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

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

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

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

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

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

• path <строка> | <Buffer> | <URL>
• options <строка> | <Объект>
  • encoding <строка> По умолчанию: 'utf8'
• callback <Функция>
  • err <Ошибка>
  • resolvedPath <строка> | <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 <строка> | <Buffer> | <URL>
• newPath <строка> | <Buffer> | <URL>
• callback <Функция>
  • err <Ошибка>

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

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

import { rename } from 'node:fs';

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

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

• path <строка> | <Буфер> | <URL>
• options <Объект>
  • maxRetries <целое число> Если обнаружена ошибка EBUSY, EMFILE, ENFILE, ENOTEMPTY, или EPERM, Node.js повторит операцию с линейным отложенным ожиданием на retryDelay миллисекунд больше при каждой попытке. Эта опция представляет количество повторов. Эта опция игнорируется, если опция recursive не true . Значение по умолчанию: 0.
  • recursive <логическое значение> Если true, выполняется рекурсивное удаление каталога. В рекурсивном режиме операции повторяются при ошибках. Значение по умолчанию: false. Устаревшее.
  • retryDelay <целое число> Количество миллисекунд, ожидаемых между повторами. Эта опция игнорируется, если опция recursive не true . Значение по умолчанию: 100.
• callback <Функция>
  • err <Ошибка>

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

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

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

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

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

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

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

• path <строка> | <Буфер> | <URL>
• options <Объект>
  • bigint <логическое значение> Определяет, должны ли числовые значения в возвращаемом объекте <fs.Stats> быть bigint. Значение по умолчанию: false.
• callback <Функция>
  • err <Ошибка>
  • stats <fs.Stats>

Асинхронная stat(2). Обратному вызову передаются два аргумента (err, stats), где stats — это объект <fs.Stats>.

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

fs.stat() следует символьных ссылкам. Используйте fs.lstat() для просмотра самих ссылок.

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

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

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

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

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

import { stat } from 'node:fs';

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

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

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

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

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

• path <строка> | <Буфер> | <URL>
• options <Объект>
  • bigint <логическое значение> Нужно ли преобразовать числовые значения в возвращаемом объекте <fs.StatFs> в bigint. По умолчанию: false.
• callback <Функция>
  • err <Ошибка>
  • stats <fs.StatFs>

Асинхронная функция statfs(2). Возвращает информацию о смонтированной файловой системе, содержащей path. Обратный вызов получает два аргумента (err, stats), где stats является объектом <fs.StatFs>.

В случае ошибки, аргумент err.code будет одним из Общих системных ошибок.

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

• target <строка> | <Буфер> | <URL>
• path <строка> | <Буфер> | <URL>
• type <строка> | <null> По умолчанию: null
• callback <Функция>
  • err <Ошибка>

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

См. документацию POSIX symlink(2) для получения более подробной информации.

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

Относительные цели относятся к родительскому каталогу ссылки.

import { symlink } from 'node:fs';

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

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

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

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

• path <строка> | <Буфер> | <URL>
• len <целое число> По умолчанию: 0
• callback <Функция>
  • err <Ошибка> | <Суммарная ошибка>

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

MJS модули

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

CJS модули

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 <строка> | <Буфер> | <URL>
• callback <Функция>
  • err <Ошибка>

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

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

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

См. документацию POSIX unlink(2) для получения более подробной информации.

fs.unwatchFile(filename[, listener])

• filename <строка> | <Буфер> | <URL>
• listener <Функция> Необязательно, слушатель, ранее прикрепленный с помощью fs.watchFile()

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

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

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

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

• path <строка> | <Буфер> | <URL>
• atime <число> | <строка> | <Дата>
• mtime <число> | <строка> | <Дата>
• callback <Функция>
  • err <Ошибка>

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

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

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

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

• filename <строка> | <Буфер> | <URL>
• options <строка> | <объект>
  • persistent <логическое значение> Указывает, должен ли процесс продолжать работу до тех пор, пока файлы отслеживаются. По умолчанию: true.
  • recursive <логическое значение> Указывает, должны ли отслеживаться все подкаталоги или только текущий каталог. Применяется, когда указан каталог, и только на поддерживаемых платформах (см. примечания). По умолчанию: false.
  • encoding <строка> Указывает кодировку символов для имени файла, передаваемого обработчику. По умолчанию: 'utf8'.
  • signal <AbortSignal> позволяет закрыть наблюдатель с помощью AbortSignal.
• listener <Функция> | <неопределено> По умолчанию: undefined
  • eventType <строка>
  • filename <строка> | <Буфер> | <null>
• Возвращает: <fs.FSWatcher>

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

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

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

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

Обратный вызов обработчика прикреплён к событию 'change', генерируемому <fs.FSWatcher>, но это не то же самое, что значение 'change' из eventType.

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

Ограничения

API fs.watch не является на 100% согласованным на всех платформах и недоступен в некоторых ситуациях.

Рекурсивный вариант поддерживается только на macOS и Windows. Исключение ERR_FEATURE_UNAVAILABLE_ON_PLATFORM будет выброшено, если этот вариант используется на платформе, которая его не поддерживает.

В Windows не будут генерироваться события, если отслеживаемый каталог перемещается или переименовывается. Ошибка EPERM сообщает об удалении отслеживаемого каталога.

Доступность

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

• В системах Linux используется inotify(7).
• В системах BSD используется kqueue(2).
• В macOS используется kqueue(2) для файлов и FSEvents для каталогов.
• В системах SunOS (включая Solaris и SmartOS) используется event ports.
• В системах Windows эта функция зависит от ReadDirectoryChangesW.
• В системах AIX эта функция зависит от AHAFS, которая должна быть включена.
• В системах IBM i эта функция не поддерживается.

Если основная функциональность недоступна по какой-либо причине, то fs.watch() не сможет работать и может выбросить исключение. Например, отслеживание файлов или каталогов может быть ненадежным и в некоторых случаях невозможным на сетевых файловых системах (NFS, SMB и т.д.) или на файловых системах хоста при использовании программ виртуализации, таких как Vagrant или Docker.

По-прежнему можно использовать fs.watchFile(), который использует опросный метод stat, но этот метод медленнее и менее надёжен.

Индексы узлов

В системах Linux и macOS fs.watch() определяет путь к индексу узла inode и отслеживает этот индекс узла. Если отслеживаемый путь удаляется и воссоздаётся, ему назначается новый индекс узла. Наблюдатель сгенерирует событие об удалении, но продолжит отслеживать исходный индекс узла. События для нового индекса узла не будут сгенерированы. Это ожидаемое поведение.

В системах AIX файлы сохраняют тот же индекс узла в течение всего срока службы файла. Сохранение и закрытие отслеживаемого файла в AIX приведёт к двум уведомлениям (одно — о добавлении нового содержимого, второе — о усечении).

Аргумент имени файла

Предоставление аргумента filename в обратном вызове поддерживается только в Linux, macOS, Windows и AIX. Даже на поддерживаемых платформах, filename не всегда гарантируется. Поэтому не следует полагаться на то, что аргумент filename всегда будет доступен в обратном вызове, и необходимо иметь резервный вариант, если аргумент null.

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

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

• filename <строка> | <Буфер> | <URL>
• options <Объект>
  • bigint <булево> По умолчанию: false
  • persistent <булево> По умолчанию: true
  • interval <целое> По умолчанию: 5007
• listener <Функция>
  • current <fs.Статистика>
  • previous <fs.Статистика>
• Возвращает: <fs.Наблюдатель за состоянием>

Наблюдает за изменениями в filename. Обратный вызов listener будет вызываться каждый раз при доступе к файлу.

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

Обратный вызов listener получает два аргумента: текущий объект статистики и предыдущий объект статистики:

import { watchFile } from 'node:fs';

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

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

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

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

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

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

Это происходит, когда:

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

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

• fd <целое>
• buffer <Буфер> | <Массив типа> | <Представление данных>
• offset <целое> По умолчанию: 0
• length <целое> По умолчанию: buffer.byteLength - offset
• position <целое> | <null> По умолчанию: null
• callback <Функция>
  • err <Ошибка>
  • bytesWritten <целое>
  • buffer <Буфер> | <Массив типа> | <Представление данных>

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

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

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

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

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

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

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

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

• fd <целое>
• buffer <Буфер> | <Массив типа> | <Представление данных>
• options <Объект>
  • offset <целое> По умолчанию: 0
  • length <целое> По умолчанию: buffer.byteLength - offset
  • position <целое> По умолчанию: null
• callback <Функция>
  • err <Ошибка>
  • bytesWritten <целое>
  • buffer <Буфер> | <Массив типа> | <Представление данных>

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

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

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

• fd <целое число>
• string <строка> | <объект>
• position <целое число> | <null> По умолчанию: null
• encoding <строка> По умолчанию: 'utf8'
• callback <функция>
  • err <ошибка>
  • written <целое число>
  • string <строка>

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

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

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

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

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

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

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

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

• file <строка> | <Буфер> | <URL> | <целое число> имя файла или дескриптор файла
• data <строка> | <Буфер> | <TypedArray> | <DataView> | <объект>
• options <объект> | <строка>
  • encoding <строка> | <null> По умолчанию: 'utf8'
  • mode <целое число> По умолчанию: 0o666
  • flag <строка> См. поддержку flags системных флагов. По умолчанию: 'w'.
  • signal <AbortSignal> позволяет прервать запрос writeFile
• callback <функция>
  • err <ошибка> | <AggregateError>

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

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

Опция encoding игнорируется, если data является буфером.

Опция mode влияет только на только что созданный файл. См. fs.open() для получения дополнительных сведений.

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

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

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

import { writeFile } from 'node:fs';

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

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

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

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

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

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

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

Использование fs.writeFile() с дескрипторами файлов

Когда file является дескриптором файла, поведение почти идентично прямому вызову fs.write():

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

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

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

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

Например, если fs.writeFile() вызывается дважды подряд, сначала для записи строки 'Hello', а затем для записи строки ', World', файл будет содержать 'Hello, World', и может содержать часть исходных данных файла (в зависимости от размера исходного файла и позиции дескриптора файла). Если бы вместо дескриптора использовалось имя файла, файл гарантированно содержал бы только ', World'.

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

• fd <целое>
• buffers <ArrayBufferView[]>
• position <целое> | <null> По умолчанию: null
• callback <Функция>
  • err <Ошибка>
  • bytesWritten <целое>
  • buffers <ArrayBufferView[]>

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

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

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

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

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

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

Синхронный API

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

fs.accessSync(path[, mode])

• path <строка> | <Буфер> | <URL>
• mode <целое число> По умолчанию: fs.constants.F_OK

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

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

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

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

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

• path <строка> | <Буфер> | <URL> | <число> имя файла или дескриптор файла
• data <строка> | <Буфер>
• options <Объект> | <строка>
  • encoding <строка> | <null> По умолчанию: 'utf8'
  • mode <целое число> По умолчанию: 0o666
  • flag <строка> См. поддержку флагов файловой системы flags. По умолчанию: 'a'.

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

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

import { appendFileSync } from 'node:fs';

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

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

import { appendFileSync } from 'node:fs';

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

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

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

let fd;

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

fs.chmodSync(path, mode)

• path <строка> | <Буфер> | <URL>
• mode <строка> | <целое число>

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

См. документацию POSIX chmod(2) для более подробной информации.

fs.chownSync(path, uid, gid)

• path <строка> | <Буфер> | <URL>
• uid <целое число>
• gid <целое число>

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

См. документацию POSIX chown(2) для более подробной информации.

fs.closeSync(fd)

• fd <целое число>

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

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

См. документацию POSIX close(2) для более подробной информации.

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

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

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

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

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

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

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

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

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

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

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

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

fs.existsSync(path)

• path <строка> | <Буфер> | <URL>
• Возвращает: <логическое>

Возвращает true, если путь существует, false в противном случае.

Для получения подробной информации см. документацию асинхронной версии этого API: fs.exists().

fs.exists() устарело, но fs.existsSync() нет. Параметр callback для fs.exists() принимает параметры, несовместимые с другими обратными вызовами Node.js. fs.existsSync() не использует обратный вызов.

import { existsSync } from 'node:fs';

if (existsSync('/etc/passwd'))
  console.log('The path exists.'); copy

fs.fchmodSync(fd, mode)

• fd <целое число>
• mode <строка> | <целое число>

Устанавливает разрешения на файл. Возвращает undefined.

См. документацию POSIX fchmod(2) для более подробной информации.

fs.fchownSync(fd, uid, gid)

• fd <целое число>
• uid <целое число> новый идентификатор пользователя владельца файла.
• gid <целое число> новый идентификатор группы группы файла.

Устанавливает владельца файла. Возвращает undefined.

См. документацию POSIX fchown(2) для более подробной информации.

fs.fdatasyncSync(fd)

• fd <целое число>

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

fs.fstatSync(fd[, options])

• fd <целое число>
• options <Объект>
  • bigint <логическое> Числовые значения в возвращаемом объекте <fs.Stats> должны быть bigint. По умолчанию: false.
• Возвращает: <fs.Stats>

Получает <fs.Stats> для дескриптора файла.

См. документацию POSIX fstat(2) для более подробной информации.

fs.fsyncSync(fd)

• fd <целое число>

Запрос о том, что все данные для открытого дескриптора файла должны быть выгружены на устройство хранения. Конкретная реализация зависит от операционной системы и устройства. Обратитесь к документации POSIX fsync(2) для более подробной информации. Возвращает undefined.

fs.ftruncateSync(fd[, len])

• fd <целое число>
• len <целое число> По умолчанию: 0

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

Для получения подробной информации см. документацию асинхронной версии этого API: fs.ftruncate().

fs.futimesSync(fd, atime, mtime)

• fd <целое число>
• atime <число> | <строка> | <Дата>
• mtime <число> | <строка> | <Дата>

Синхронная версия fs.futimes(). Возвращает undefined.

fs.lchmodSync(path, mode)

• path <строка> | <Буфер> | <URL>
• mode <целое число>

Изменяет разрешения на символическую ссылку. Возвращает undefined.

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

См. документацию POSIX lchmod(2) для получения более подробной информации.

fs.lchownSync(path, uid, gid)

• path <строка> | <Буфер> | <URL>
• uid <целое число> Новый идентификатор пользователя владельца файла.
• gid <целое число> Новый идентификатор группы группы файла.

Устанавливает владельца для пути. Возвращает undefined.

См. документацию POSIX lchown(2) для более подробной информации.

fs.lutimesSync(path, atime, mtime)

• path <строка> | <Буфер> | <URL>
• atime <число> | <строка> | <Дата>
• mtime <число> | <строка> | <Дата>

Изменяет временные метки файловой системы символической ссылки, на которую ссылается path. Возвращает undefined, или выбрасывает исключение при некорректных параметрах или неудачном выполнении операции. Это синхронная версия fs.lutimes().

fs.linkSync(existingPath, newPath)

• existingPath <строка> | <Буфер> | <URL>
• newPath <строка> | <Буфер> | <URL>

Создаёт новую ссылку от existingPath к newPath. См. документацию POSIX link(2) для получения более подробной информации. Возвращает undefined.

fs.lstatSync(path[, options])

• path <строка> | <Буфер> | <URL>
• options <Объект>
  • bigint <булево> Следует ли числовые значения в возвращаемом объекте <fs.Stats> представлять тип bigint. По умолчанию: false.
  • throwIfNoEntry <булево> Следует ли бросать исключение, если записи файловой системы не существует, вместо возврата undefined. По умолчанию: true.
• Возвращает: <fs.Stats>

Получает <fs.Stats> для символической ссылки, на которую ссылается path.

См. документацию POSIX lstat(2) для получения более подробной информации.

fs.mkdirSync(path[, options])

• path <строка> | <Буфер> | <URL>
• options <Объект> | <целое число>
  • recursive <булево> По умолчанию: false
  • mode <строка> | <целое число> Не поддерживается в Windows. По умолчанию: 0o777.
• Возвращает: <строка> | <неопределено>

Синхронно создаёт директорию. Возвращает undefined, или, если recursive равно true, первый созданный путь к директории. Это синхронная версия fs.mkdir().

См. документацию POSIX mkdir(2) для получения более подробной информации.

fs.mkdtempSync(prefix[, options])

• prefix <строка>
• options <строка> | <объект>
  • encoding <строка> По умолчанию: 'utf8'
• Возвращает: <строка>

Возвращает путь созданного каталога.

Для получения подробной информации см. документацию асинхронной версии этого API: fs.mkdtemp().

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

fs.opendirSync(path[, options])

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

Синхронное открытие каталога. См. opendir(3).

Создаёт <fs.Дир>, который содержит все дальнейшие функции для чтения из каталога и очистки.

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

fs.openSync(path[, flags[, mode]])

• path <строка> | <Буфер> | <URL>
• flags <строка> | <число> По умолчанию: 'r'. См. поддержку системных флагов flags.
• mode <строка> | <целое число> По умолчанию: 0o666
• Возвращает: <число>

Возвращает целое число, представляющее дескриптор файла.

Для получения подробной информации см. документацию асинхронной версии этого API: fs.open().

fs.readdirSync(path[, options])