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

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

Модули 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 <string> | <Buffer> | <TypedArray> | <DataView> | <AsyncIterable> | <Iterable> | <Stream>
• options <Object> | <string>
  • encoding <string> | <null> По умолчанию: 'utf8'
  • flush <boolean> Если true, внутренний дескриптор файла будет сброшен перед закрытием. По умолчанию: false.
• Возвращает: <Promise> При успехе возвращает undefined.

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

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

filehandle.chmod(mode)

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

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

filehandle.chown(uid, gid)

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

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

filehandle.close()

• Возвращает: <Promise> При успехе возвращает undefined.

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

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

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

filehandle.createReadStream([options])

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

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

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

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

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

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

const fd = await open('/dev/input/event0');
// Create a stream from some character device.
const stream = fd.createReadStream();
setTimeout(() => {
  stream.close(); // This may not close the stream.
  // Artificially marking end-of-stream, as if the underlying resource had
  // indicated end-of-file by itself, allows the stream to close.
  // This does not cancel pending read operations, and if there is such an
  // operation, the process may still not be able to exit successfully
  // until it finishes.
  stream.push(null);
  stream.read(0);
}, 100); 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 <целое число>
  • highWaterMark <число> По умолчанию: 16384
  • flush <логическое> Если true, то базовый дескриптор файла будет сброшен перед закрытием. По умолчанию: false.
• Возвращает: <fs.Поток записи>

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

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

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

filehandle.datasync()

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

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

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

filehandle.fd

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

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

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

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

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

filehandle.read([options])

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

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

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

filehandle.read(buffer[, options])

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

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

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

filehandle.readableWebStream([options])

• options <Object>

  • type <string> | <undefined> Выбор открытия обычного или 'bytes' потока. По умолчанию: undefined

• Возвращает: <ReadableStream>

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

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

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

filehandle.read() должен поддерживать чтение.

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

filehandle.readLines([options])

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

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

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

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

filehandle.stat([options])

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

filehandle.sync()

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

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

filehandle.truncate(len)

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

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

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

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

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

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

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

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

filehandle.utimes(atime, mtime)

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

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

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

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

Записать 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
• Возвращает: <Promise>

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

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

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

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

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

Записывает массив <Представлений массивов буферов> в файл.

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

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

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

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

filehandle[Symbol.asyncDispose]()

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

fsPromises.access(path[, mode])

• path <строка> | <Буфер> | <URL>
• mode <целое> По умолчанию: fs.constants.F_OK
• Возвращает: <Обещание> Выполняется с 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'.
  • flush <логическое> Если true, базовый дескриптор файла сбрасывается перед его закрытием. По умолчанию: false.
• Возвращает: <Обещание> Выполняется с undefined при успехе.

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

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

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

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

fsPromises.chmod(path, mode)

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

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

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

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

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

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

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

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

fsPromises.lutimes(path, atime, mtime)

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

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

fsPromises.link(existingPath, newPath)

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

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

fsPromises.lstat(path[, options])

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

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

fsPromises.mkdir(path[, options])

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

Асинхронно создаёт директорию.

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

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

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

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

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

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

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

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

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

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

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

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

fsPromises.opendir(path[, options])

• path <строка> | <Буфер> | <URL>
• options <Объект>
  • encoding <строка> | <null> По умолчанию: 'utf8'
  • bufferSize <число> Количество записей каталога, которые буферизуются во время чтения из каталога. Более высокие значения приводят к лучшей производительности, но и к большему потреблению памяти. По умолчанию: 32
  • recursive <логическое> Результатом 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 <строка> | <Буфер> | <URL>
• options <Объект>
  • encoding <строка> По умолчанию: 'utf8'
  • withFileTypes <логическое> По умолчанию: false
  • recursive <логическое> Если true, читает содержимое каталога рекурсивно. В рекурсивном режиме он выведет все файлы, подфайлы и каталоги. По умолчанию: false.
• Возвращает: <Promise> Выполняется с массивом имён файлов в каталоге, исключая '.' и '..'.

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

Необязательный параметр options может быть строкой, определяющей кодировку, или объектом с свойством encoding, определяющим кодировку символов для имён файлов. Если encoding установлено в '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 <строка> | <Буфер> | <URL> | <FileHandle> имя файла или FileHandle
• options <Объект> | <строка>
  • encoding <строка> | <null> По умолчанию: null
  • flag <строка> См. поддержку флагов файловой системы flags. По умолчанию: 'r'.
  • signal <AbortSignal> позволяет отменить запрос readFile.
• Возвращает: <Promise> Выполняется с содержимым файла.

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

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

Если 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> | <Объект>
  • encoding <string> По умолчанию: 'utf8'
• Возвращает: <Promise> Выполняется с linkString при успехе.

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

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

fsPromises.realpath(path[, options])

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

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

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

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

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

fsPromises.rename(oldPath, newPath)

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

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

fsPromises.rmdir(path[, options])

• path <string> | <Buffer> | <URL>
• options <Объект>
  • 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.

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

fsPromises.rm(path[, options])

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

fsPromises.statfs(path[, options])

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

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

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

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

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

fsPromises.truncate(path[, len])

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

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

fsPromises.unlink(path)

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

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

fsPromises.utimes(path, atime, mtime)

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

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

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

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

fsPromises.watch(filename[, options])

• filename <строка> | <Буфер> | <URL>
• options <строка> | <Объект>
  • persistent <логическое> Указывает, следует ли продолжать процесс, пока отслеживаются файлы. По умолчанию: true.
  • recursive <логическое> Указывает, следует ли отслеживать все подкаталоги или только текущий каталог. Это относится к случаю, когда указан каталог, и только на поддерживаемых платформах (см. примечания). По умолчанию: false.
  • encoding <строка> Указывает кодировку символов, которая должна использоваться для имени файла, переданного обработчику. По умолчанию: 'utf8'.
  • signal <AbortSignal> <AbortSignal>, используемый для сигнализации о необходимости остановки наблюдателя.
• Возвращает: <Асинхронный итератор> объектов со свойствами:
  • eventType <строка> Тип изменения
  • filename <строка> | <Буфер> | <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 <строка> | <Буфер> | <URL> | <Дескриптор файла> имя файла или FileHandle
• data <строка> | <Буфер> | <Массив типов> | <DataView> | <Асинхронно-итерируемый> | <Итерируемый> | <Поток>
• options <Объект> | <строка>
  • encoding <строка> | <null> По умолчанию: 'utf8'
  • mode <целое> По умолчанию: 0o666
  • flag <строка> Смотрите поддержку флагов файловой системы flags. По умолчанию: 'w'.
  • flush <логическое> Если все данные успешно записаны в файл, а flush равно true, используется filehandle.sync() для записи данных. По умолчанию: false.
  • signal <AbortSignal> позволяет прервать текущую запись файла
• Возвращает: <Promise> Выполняется с undefined при успехе.

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

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

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

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

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

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

Аналогично 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 <строка> | <Buffer> | <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 <строка> | <Buffer> | <URL> | <число> имя файла или дескриптор файла
• data <строка> | <Buffer>
• options <Объект> | <строка>
  • encoding <строка> | <null> По умолчанию: 'utf8'
  • mode <целое число> По умолчанию: 0o666
  • flag <строка> См. поддержку флагов файловой системы flags. По умолчанию: 'a'.
  • flush <логическое значение> Если true, дескриптор файла предварительно сбрасывается перед закрытием. По умолчанию: false.
• callback <Функция>
  • err <Ошибка>

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

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

import { appendFile } from 'node:fs';

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

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

import { appendFile } from 'node:fs';

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

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

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

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

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

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

fs.chmod(path, mode, callback)

• path <строка> | <Buffer> | <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>

В отличие от стандартного значения highWaterMark 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
  • highWaterMark <число> По умолчанию: 16384
  • flush <логическое значение> Если true, базовый дескриптор файла сбрасывается перед закрытием. По умолчанию: false.
• Возвращает: <fs.WriteStream>

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

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

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

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

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

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

fs.exists(path, callback)

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

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

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

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

Асинхронно создаёт директорию.

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

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

import { mkdir } from 'node:fs';

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

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

import { mkdir } from 'node:fs';

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

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

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

• prefix <строка> | <Буфер> | <URL>
• 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, то 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 устанавливает режим файла (разрешения и биты "sticky"), но только если файл был создан. В Windows можно манипулировать только правами на запись; см. fs.chmod().

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

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

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

fs.openAsBlob(path[, options])

• path <строка> | <Буфер> | <URL>
• options <Объект>
  • type <строка> Необязательный тип MIME для blob.
• Возвращает: <Promise> Выполняется с <Blob> при успехе.

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

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

Модули MJS

import { openAsBlob } from 'node:fs';

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

Модули CJS

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

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

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

• path <строка> | <Буфер> | <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 <целое> | <bigint> | <null> Указывает, с какой позиции начать чтение из файла. Если position имеет значение null или -1 , данные будут читаться с текущей позиции в файле, а позиция файла будет обновлена. Если position — целое число, позиция файла останется неизменной.
• callback <Функция>
  • err <Ошибка>
  • bytesRead <целое>
  • buffer <Буфер>

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

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

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

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

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

Например:

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

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

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

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

• fd <целое>
• options <Объект>
  • buffer <Буфер> | <Массив с плавающей запятой> | <DataView> По умолчанию: 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 <Буфер> | <Массив с плавающей запятой> | <DataView> Буфер, в который будут записаны данные.
• 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 <булево> Если true, считывает содержимое каталога рекурсивно. В рекурсивном режиме он будет перечислять все файлы, подкаталоги и директории. По умолчанию: 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 <строка> | <Буфер> | <URL> | <целое число> имя файла или дескриптор файла
• options <Объект> | <строка>
  • encoding <строка> | <null> По умолчанию: null
  • flag <строка> См. поддержку флагов файловой системы flags. По умолчанию: 'r'.
  • signal <AbortSignal> позволяет прервать запрос readFile
• callback <Функция>
  • err <Ошибка> | <AggregateError>
  • data <строка> | <Буфер>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

import { stat } from 'node:fs';

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Файлы 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.Stats>
  • previous <fs.Stats>
• Возвращает: <fs.StatWatcher>

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

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

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

import { watchFile } from 'node:fs';

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

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

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

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

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

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

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

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

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

• fd <целое число>
• buffer <Buffer> | <TypedArray> | <DataView>
• offset <целое число> По умолчанию: 0
• length <целое число> По умолчанию: buffer.byteLength - offset
• position <целое число> | <null> По умолчанию: null
• callback <Функция>
  • err <Ошибка>
  • bytesWritten <целое число>
  • buffer <Buffer> | <TypedArray> | <DataView>

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

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

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

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

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

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

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

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

• fd <целое число>
• buffer <Buffer> | <TypedArray> | <DataView>
• options <Объект>
  • offset <целое число> По умолчанию: 0
  • length <целое число> По умолчанию: buffer.byteLength - offset
  • position <целое число> По умолчанию: null
• callback <Функция>
  • err <Ошибка>
  • bytesWritten <целое число>
  • buffer <Buffer> | <TypedArray> | <DataView>

Записать 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 не является строкой, возникает исключение.

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'.
  • flush <логическое значение> Если все данные успешно записаны в файл, и flush равно true, fs.fsync() используется для сброса данных. По умолчанию: false.
  • 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()ся, он возвращает промис для Object с свойствами bytesWritten и buffers.

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

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

Синхронный API

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

fs.accessSync(path[, mode])

• path <строка> | <Buffer> | <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 <строка> | <Buffer> | <URL> | <число> имя файла или дескриптор файла
• data <строка> | <Buffer>
• options <Объект> | <строка>
  • encoding <строка> | <null> По умолчанию: 'utf8'
  • mode <целое> По умолчанию: 0o666
  • flag <строка> Смотрите поддержку флагов файловой системы flags. По умолчанию: 'a'.
  • flush <булево> Если true, буферизованный дескриптор файла сбрасывается перед закрытием. По умолчанию: false.

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

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

import { appendFileSync } from 'node:fs';

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

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

import { appendFileSync } from 'node:fs';

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

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

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

let fd;

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

fs.chmodSync(path, mode)

• path <строка> | <Buffer> | <URL>
• mode <строка> | <целое>

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

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

fs.chownSync(path, uid, gid)

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

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 <логическое значение> когда true метки времени из src будут сохранены. По умолчанию: false.
  • recursive <логическое значение> рекурсивное копирование каталогов. По умолчанию: false
  • verbatimSymlinks <логическое значение> При значении true разрешение пути для символических ссылок будет пропущено. По умолчанию: false

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

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