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

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

Модули MJS

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

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

Модули CJS

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

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

Пример с обратным вызовом

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

Модули MJS

import { unlink } from 'node:fs';

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

Модули CJS

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

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

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

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

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

Модули MJS

import { unlinkSync } from 'node:fs';

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

Модули CJS

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

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

API обещаний

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

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

Класс: FileHandle

Объект <FileHandle> — это обертка над числовым дескриптором файла.

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

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

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

Событие: 'close'

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

filehandle.appendFile(data[, options])

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

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

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

filehandle.chmod(mode)

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

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

filehandle.chown(uid, gid)

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

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

filehandle.close()

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

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

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

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

filehandle.createReadStream([options])

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

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

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

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

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

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

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

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

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

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

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

filehandle.createWriteStream([options])

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

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

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

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

filehandle.datasync()

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

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

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

filehandle.fd

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

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

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

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

filehandle.read(buffer[, options])

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

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

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

filehandle.readableWebStream([options])

• options <Object>

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

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

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

У <FileHandle> должна быть возможность чтения.

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

filehandle.readLines([options])

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

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

filehandle.stat([options])

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

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

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

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

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

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

filehandle.write(buffer[, options])

• buffer <Буфер> | <TypedArray> | <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 <строка> | <Buffer> | <TypedArray> | <DataView> | <AsyncIterable> | <Iterable> | <Поток>
• options <Объект> | <строка>
  • encoding <строка> | <null> Ожидаемая кодировка символов, когда data является строкой. По умолчанию: 'utf8'
• Возвращает: <Promise>

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

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

У <FileHandle> должна быть возможность записи.

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

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

filehandle.writev(buffers[, position])

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

Запись массива <ArrayBufferView> в файл.

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

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

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

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

filehandle[Symbol.asyncDispose]()

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

fsPromises.access(path[, mode])

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

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

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

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

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

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

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

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

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

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

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

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

fsPromises.chmod(path, mode)

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

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

fsPromises.chown(path, uid, gid)

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

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

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

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

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

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

fsPromises.glob(pattern[, options])

• pattern <строка> | <массив строк>
• options <Объект>
  • cwd <строка> текущая рабочая директория. По умолчанию: process.cwd()
  • exclude <Функция> Функция для фильтрации файлов/директорий. Возвращает true для исключения элемента, false для включения. По умолчанию: undefined.
  • withFileTypes <логическое значение> true если glob должен возвращать пути в виде Dirents, false в противном случае. По умолчанию: false.
• Возвращает: <Асинхронный итератор> Асинхронный итератор, который возвращает пути файлов, соответствующие шаблону.

MJS модули

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

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

CJS модули

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

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

fsPromises.lchmod(path, mode)

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

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

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

fsPromises.lchown(path, uid, gid)

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

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

fsPromises.lutimes(path, atime, mtime)

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

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

fsPromises.link(existingPath, newPath)

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

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

fsPromises.lstat(path[, options])

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

Эквивалентно fsPromises.stat(), если path не ссылается на символическую ссылку, в противном случае, информация о самой ссылке, а не о файле, на который она ссылается, выводится с помощью stat.

fsPromises.mkdir(path[, options])

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

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

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

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

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

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

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

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

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

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

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

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

fsPromises.opendir(path[, options])

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

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

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

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

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

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

fsPromises.readFile(path[, options])

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

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

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

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

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

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

MJS модули

import { readFile } from 'node:fs/promises';
try {
  const filePath = new URL('./package.json', import.meta.url);
  const contents = await readFile(filePath, { encoding: 'utf8' });
  console.log(contents);
} catch (err) {
  console.error(err.message);
}

CJS модули

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

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

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

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

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

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

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

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

fsPromises.readlink(path[, options])

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

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

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

fsPromises.realpath(path[, options])

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

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

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

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

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

fsPromises.rename(oldPath, newPath)

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

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

fsPromises.rmdir(path[, options])

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

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

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

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

fsPromises.rm(path[, options])

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

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

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

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

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

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

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

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

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

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

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

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

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

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

fsPromises.constants

• <Объект>

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

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

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

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

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

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

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

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

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

const file = 'package.json';

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

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

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

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

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

write (НЕ РЕКОМЕНДУЕТСЯ)

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

write (РЕКОМЕНДУЕТСЯ)

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

read (НЕ РЕКОМЕНДУЕТСЯ)

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

read (РЕКОМЕНДУЕТСЯ)

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

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

    throw err;
  }

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

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

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

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

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

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

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

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

import { appendFile } from 'node:fs';

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

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

import { appendFile } from 'node:fs';

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

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

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

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

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

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

fs.chmod(path, mode, callback)

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

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

Более подробную информацию см. в документации POSIX chmod(2).

import { chmod } from 'node:fs';

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

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

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

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

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

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

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

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

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

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

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

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

fs.close(fd[, callback])

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

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

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

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

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

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

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

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

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

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

fs.createReadStream(path[, options])

• path <строка> | <Буфер> | <URL>
• options <строка> | <Объект>
  • flags <строка> См. поддержку файловой системы flags. По умолчанию: 'r'.
  • encoding <строка> По умолчанию: null
  • fd <целое число> | <Дескриптор файла> По умолчанию: null
  • mode <целое число> По умолчанию: 0o666
  • autoClose <boolean> По умолчанию: true
  • emitClose <boolean> По умолчанию: true
  • start <целое число>
  • end <целое число> По умолчанию: Infinity
  • highWaterMark <целое число> По умолчанию: 64 * 1024
  • fs <Объект> | <null> По умолчанию: null
  • signal <Сигнал прерывания> | <null> По умолчанию: null
• Возвращает: <fs.Поток чтения>

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

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

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

Если 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 ложно, то дескриптор файла не будет закрыт, даже если произошла ошибка. Приложением необходимо закрыть его и убедиться, что нет утечки дескрипторов файлов. Если autoClose установлено в истинное значение (по умолчанию), при 'error' или 'end' дескриптор файла будет закрыт автоматически.

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

Пример чтения последних 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 <целое число> | <Дескриптор файла> По умолчанию: null
  • mode <целое число> По умолчанию: 0o666
  • autoClose <булево> По умолчанию: true
  • emitClose <булево> По умолчанию: true
  • start <целое число>
  • fs <Объект> | <null> По умолчанию: null
  • signal <AbortSignal> | <null> По умолчанию: null
  • highWaterMark <число> По умолчанию: 16384
  • flush <булево> Если true, базовый дескриптор файла будет сброшен перед закрытием. По умолчанию: false.
• Возвращает: <fs.Поток записи>

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

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

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

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

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

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

fs.exists(path, callback)

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

Проверьте существование заданного пути, проверив его с файловой системой. Затем вызовите аргумент callback со значением истина или ложь:

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

write (НЕ РЕКОМЕНДУЕТСЯ)

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

write (РЕКОМЕНДУЕТСЯ)

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

read (НЕ РЕКОМЕНДУЕТСЯ)

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

read (РЕКОМЕНДУЕТСЯ)

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.glob(pattern[, options], callback)

• pattern <строка> | <массив_строк>

• options <Объект>

  • cwd <строка> текущий рабочий каталог. По умолчанию: process.cwd()
  • exclude <Функция> Функция для фильтрации файлов/каталогов. Возврат true для исключения элемента, false для включения его. По умолчанию: undefined.
  • withFileTypes <логическое> true если glob должен возвращать пути как Dirents, false в противном случае. По умолчанию: false.

• callback <Функция>

  • err <Ошибка>

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

Модули MJS

import { glob } from 'node:fs';

glob('**/*.js', (err, matches) => {
  if (err) throw err;
  console.log(matches);
});

Модули CJS

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

glob('**/*.js', (err, matches) => {
  if (err) throw err;
  console.log(matches);
});

fs.lchmod(path, mode, callback)

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

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

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

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

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

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

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

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

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

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

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

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

fs.link(existingPath, newPath, callback)

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

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

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

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

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

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

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

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

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

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

Дополнительный аргумент options может быть целым числом, определяющим mode (разрешения и биты «липкости»), или объектом со свойством 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 устанавливает режим файла (разрешения и биты «липкости»), но только если файл был создан. В Windows можно манипулировать только правом записи; см. fs.chmod().

Функция получает два аргумента (err, fd).

Некоторые символы (< > : " / \ | ? *) зарезервированы в Windows, как описано в Naming Files, Paths, and Namespaces. В 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. Синхронные операции stat на файле во время создания 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 <string> | <Buffer> | <URL>
• options <Object>
  • encoding <string> | <null> По умолчанию: 'utf8'
  • bufferSize <number> Количество записей каталога, кэшируемых при чтении из каталога. Большие значения ведут к лучшему быстродействию, но увеличивают использование памяти. По умолчанию: 32
  • recursive <boolean> По умолчанию: false
• callback <Function>
  • err <Error>
  • dir <fs.Dir>

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

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

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

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

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

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

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

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

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

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

Например:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

import { readFile } from 'node:fs';

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

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

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

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

import { readFile } from 'node:fs';

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

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

import { readFile } from 'node:fs';

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

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

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

import { readFile } from 'node:fs';

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

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

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

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

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

Учёт производительности

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

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

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

В вопросе на GitHub Node.js #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 <строка> | <Буфер>

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

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

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

Асинхронная функция realpath(3).

Функция callback получает два аргумента (err, resolvedPath).

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

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

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

fs.rename(oldPath, newPath, callback)

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

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

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

import { rename } from 'node:fs';

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Например, данная структура каталогов:

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

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

import { stat } from 'node:fs';

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

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

Результат будет похож на:

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

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

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

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

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

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

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

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

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

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

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

import { symlink } from 'node:fs';

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

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

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

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

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

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

Модули MJS

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

Модули CJS

const { truncate } = require('node:fs');
// Assuming that 'path/file.txt' is a regular file.
truncate('path/file.txt', (err) => {
  if (err) throw err;
  console.log('path/file.txt was truncated');
});

Передача дескриптора файла устарела и может привести к ошибке в будущем.

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

fs.unlink(path, callback)

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

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

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

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

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

fs.unwatchFile(filename[, listener])

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Примечания

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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> позволяет прервать текущую запись файла
• callback <Функция>
  • err <Ошибка> | <Сводная ошибка>

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

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

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

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

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

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

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

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

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

import { appendFileSync } from 'node:fs';

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

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

import { appendFileSync } from 'node:fs';

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

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

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

let fd;

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

fs.chmodSync(path, mode)

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

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

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

fs.chownSync(path, uid, gid)

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

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

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

fs.closeSync(fd)

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

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

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

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

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

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

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

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

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

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

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

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

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

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