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

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

Модули MJS

import { unlink } from '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('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 'fs';

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

Модули CJS

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

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

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

Пример синхронной операции

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

Модули MJS

import { unlinkSync } from 'fs';

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

Модули CJS

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

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

API обещаний

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

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

Класс: FileHandle

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

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

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

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

Событие: 'close'

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

filehandle.appendFile(data[, options])

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

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

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

filehandle.chmod(mode)

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

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

filehandle.chown(uid, gid)

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

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

filehandle.close()

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

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

import { open } from 'fs/promises';

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

filehandle.createReadStream([options])

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

В отличие от значения по умолчанию 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 '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);

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

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

import { open } from 'fs/promises';

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

filehandle.createWriteStream([options])

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

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

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

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

filehandle.datasync()

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

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

В отличие от filehandle.sync, этот метод не очищает изменённые метаданные.

filehandle.fd

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

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

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

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

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

filehandle.read([options])

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

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

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

filehandle.readFile(options)

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

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

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

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

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

filehandle.readv(buffers[, position])

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

Считывает данные из файла и записывает их в массив <ArrayBufferView>.

filehandle.stat([options])

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

filehandle.sync()

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

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

filehandle.truncate(len)

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

Усечение файла.

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

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

import { open } from 'fs/promises';

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

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

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

filehandle.utimes(atime, mtime)

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

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

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

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

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

Если buffer — обычный объект, он должен иметь собственную (не унаследованную) функцию toString.

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

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

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

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

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

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

Запись string в файл. Если string — не строка или объект с собственной функцией toString, промис отклоняется с ошибкой.

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

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

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

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

filehandle.writeFile(data, options)

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

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

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

У <FileHandle> должна быть поддержка записи.

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

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

filehandle.writev(buffers[, position])

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

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

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

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

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

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

fsPromises.access(path[, mode])

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

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

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

import { access } from 'fs/promises';
import { constants } from 'fs';

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

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

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

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

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

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

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

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

fsPromises.chmod(path, mode)

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

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

fsPromises.chown(path, uid, gid)

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

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

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

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

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

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

import { constants } from 'fs';
import { copyFile } from 'fs/promises';

try {
  await copyFile('source.txt', 'destination.txt');
  console.log('source.txt was copied to destination.txt');
} catch {
  console.log('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.log('The file could not be copied');
}

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

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

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

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

fsPromises.lchmod(path, mode)

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

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

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

fsPromises.lchown(path, uid, gid)

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

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

fsPromises.lutimes(path, atime, mtime)

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

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

fsPromises.link(existingPath, newPath)

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

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

fsPromises.lstat(path[, options])

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

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

fsPromises.mkdir(path[, options])

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

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

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

fsPromises.mkdtemp(prefix[, options])

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

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

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

import { mkdtemp } from 'fs/promises';

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

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

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

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

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

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

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

fsPromises.opendir(path[, options])

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

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

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

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

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

import { opendir } from 'fs/promises';

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

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

fsPromises.readdir(path[, options])

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

Считывает содержимое каталога.

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

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

import { readdir } from 'fs/promises';

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

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 будет возвращено представление содержимого каталога.

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

import { readFile } from 'fs/promises';

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

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

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

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

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

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

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

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

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

fsPromises.rm(path[, options])

• path <строка> | <Буфер> | <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.symlink(target, path[, type])

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

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

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

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

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

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

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

fsPromises.watch(filename[, options])

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

import { access, constants } from '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 exists in the current directory, and if it is writable.
access(file, constants.F_OK | constants.W_OK, (err) => {
  if (err) {
    console.error(
      `${file} ${err.code === 'ENOENT' ? 'does not exist' : 'is read-only'}`);
  } else {
    console.log(`${file} exists, and it is writable`);
  }
});

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

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

import { access, open, close } from '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;
      });
    }
  });
});

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

import { open, close } from '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;
    });
  }
});

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

import { access, open, close } from '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;
      });
    }
  });
});

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

import { open, close } from '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;
    });
  }
});

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

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

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

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

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

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

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

import { appendFile } from 'fs';

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

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

import { appendFile } from 'fs';

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

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

import { open, close, appendFile } from '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;
  }
});

fs.chmod(path, mode, callback)

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

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

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

import { chmod } from 'fs';

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

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

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

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

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

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

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

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

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

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

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

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

fs.close(fd[, callback])

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

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

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

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

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

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

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

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

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

import { copyFile, constants } from '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);

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

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

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

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

fs.createReadStream(path[, options])

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

В отличие от значения по умолчанию 16 КБ для <stream.Readable>, поток, возвращаемый этим методом, имеет значение по умолчанию 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 '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);

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

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

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

import { createReadStream } from 'fs';

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

Если 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
• Возвращает: <fs.Поток записи>

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

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

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

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

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

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

fs.exists(path, callback)

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

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

import { exists } from 'fs';

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

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

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

import { open, close } from '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;
    });
  }
});

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

import { open, close, exists } from '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');
  }
});

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

import { open, close } from '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;
    });
  }
});

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

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

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

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

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

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

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

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

fs.lchmod(path, mode, callback)

• path <string> | <Buffer> | <URL>
• mode <целое число>
• callback <Функция>
  • err <Ошибка> | <AggregateError>

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

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

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

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

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

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

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

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

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

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

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

fs.link(existingPath, newPath, callback)

• existingPath <string> | <Buffer> | <URL>
• newPath <string> | <Buffer> | <URL>
• callback <Функция>
  • err <Ошибка>

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

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

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

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

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

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

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

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

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

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

import { mkdir } from 'fs';

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

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

import { mkdir } from 'fs';

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

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

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

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

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

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

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

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

import { mkdtemp } from 'fs';

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

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

import { tmpdir } from 'os';
import { mkdtemp } from '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 '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.
});

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, как документировано в Именование файлов, путей и имён. В NTFS, если имя файла содержит двоеточие, Node.js откроет поток файловой системы, как описано на странице MSDN здесь.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• path <строка> | <Буфер> | <URL>
• options <строка> | <Объект>
  • encoding <строка> По умолчанию: 'utf8'
  • withFileTypes <логическое значение> По умолчанию: false
• callback <Функция>
  • err <Ошибка>
  • files <Массив строк> | <Массив буферов> | <Массив 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> позволяет прервать выполняемое чтение файла
• callback <Function>
  • err <Error> | <AggregateError>
  • data <string> | <Buffer>

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

import { readFile } from 'fs';

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

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

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

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

import { readFile } from 'fs';

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• fd <integer>
• buffers <ArrayBufferView[]>
• position <integer>
• callback <Function>
  • err <Error>
  • bytesRead <integer>
  • buffers <ArrayBufferView[]>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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 'fs';

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

- txtDir
-- file.txt
- app.js

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

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

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

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
}

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

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

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

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

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

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

import { symlink } from 'fs';

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

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

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

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

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

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

Модули MJS

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

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

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

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

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

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

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

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

Примечания

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

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

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

Доступность

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

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

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

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

Иноды

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

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

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

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

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

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

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

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

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

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

import { watchFile } from 'fs';

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

Эти объекты stat являются экземплярами fs.Stat.

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

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

Когда операция fs.watchFile приводит к ошибке ENOENT, она вызовет обработчик один раз, со всеми полями, обнуленными (или, для дат, с эпохой Unix). Если файл создается позже, обработчик будет вызван снова с последними объектами stat. Это изменение функциональности с версии 0.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 <Буфер> | <Массив типов> | <DataView> | <строка> | <объект>
• offset <целое число>
• length <целое число>
• position <целое число>
• callback <Функция>
  • err <Ошибка>
  • bytesWritten <целое число>
  • buffer <Буфер> | <Массив типов> | <DataView>

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

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, string[, position[, encoding]], callback)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Если data является простым объектом, у него должна быть собственная (не унаследованная) функция toString.

import { writeFile } from 'fs';
import { Buffer } from '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!');
});

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

import { writeFile } from 'fs';

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• fd <integer>
• buffers <ArrayBufferView[]>
• position <integer>
• callback <Function>
  • err <Error>
  • bytesWritten <integer>
  • buffers <ArrayBufferView[]>

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

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

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

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

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

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

Синхронный API

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

fs.accessSync(path[, mode])

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

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

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

import { accessSync, constants } from 'fs';

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

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

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

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

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

import { appendFileSync } from 'fs';

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

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

import { appendFileSync } from 'fs';

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

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

import { openSync, closeSync, appendFileSync } from '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);
}

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

import { copyFileSync, constants } from '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);

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

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

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

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

fs.existsSync(path)

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

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

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

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

import { existsSync } from 'fs';

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

fs.fchmodSync(fd, mode)

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

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

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

fs.fchownSync(fd, uid, gid)

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

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

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

fs.fdatasyncSync(fd)

• fd <целое>

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

fs.fstatSync(fd[, options])

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

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

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

fs.fsyncSync(fd)

• fd <целое>

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

fs.ftruncateSync(fd[, len])

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

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

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

fs.futimesSync(fd, atime, mtime)

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

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

fs.lchmodSync(path, mode)

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

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

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

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

fs.lchownSync(path, uid, gid)

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

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

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

fs.lutimesSync(path, atime, mtime)

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

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

fs.linkSync(existingPath, newPath)

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

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

fs.lstatSync(path[, options])

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

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

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

fs.mkdirSync(path[, options])

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

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

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

fs.mkdtempSync(prefix[, options])

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

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

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

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

fs.opendirSync(path[, options])

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

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

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

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

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

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

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

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

fs.readdirSync(path[, options])

• path <строка> | <Буфер> | <URL>
• options <строка> | <Объект>
  • encoding <строка> По умолчанию: 'utf8'
  • withFileTypes <логическое> По умолчанию: false
• Возвращает: <массив строк> | <массив буферов> | <fs.Dirent[]>

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

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

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

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

fs.readFileSync(path[, options])

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

Возвращает содержимое path.

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

Если задан параметр encoding, эта функция возвращает строку. В противном случае она возвращает буфер.

Аналогично fs.readFile(), когда путь указывает на каталог, поведение fs.readFileSync() зависит от платформы.

import { readFileSync } from 'fs';

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

//  FreeBSD
readFileSync('<directory>'); // => <data>

fs.readlinkSync(path[, options])

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

Возвращает строковое значение символьной ссылки.

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

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

fs.readSync(fd, buffer, offset, length, position)

• fd <целое>
• buffer <Буфер> | <Массив типов> | <DataView>
• offset <целое>
• length <целое>
• position <целое> | <bigint>
• Возвращает: <число>

Возвращает количество bytesRead.

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

fs.readSync(fd, buffer[, options])

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

Возвращает количество bytesRead.

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

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

fs.readvSync(fd, buffers[, position])

• fd <целое>
• buffers <ArrayBufferView[]>
• position <целое>
• Возвращает: <число> Количество считанных байт.

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

fs.realpathSync(path[, options])

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

Возвращает решенный путь.

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

fs.realpathSync.native(path[, options])

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

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

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

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

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

fs.renameSync(oldPath, newPath)

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

Переименовывает файл из oldPath в newPath. Возвращает undefined.

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

fs.rmdirSync(path[, options])

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

Синхронное rmdir(2). Возвращает undefined.

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

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

fs.rmSync(path[, options])

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

Синхронно удаляет файлы и каталоги (по образцу стандартной утилиты POSIX rm). Возвращает undefined.

fs.statSync(path[, options])

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

Получает <fs.Stats> для пути.

fs.symlinkSync(target, path[, type])

• target <строка> | <Buffer> | <URL>
• path <строка> | <Buffer> | <URL>
• type <строка>

Возвращает undefined.

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

fs.truncateSync(path[, len])

• path <строка> | <Buffer> | <URL>
• len <целое число> Значение по умолчанию: 0

Усекает файл. Возвращает undefined. Дескриптор файла также можно передать в качестве первого аргумента. В этом случае вызывается fs.ftruncateSync().

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

fs.unlinkSync(path)

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

Синхронная функция unlink(2). Возвращает undefined.

fs.utimesSync(path, atime, mtime)

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

Возвращает undefined.

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

fs.writeFileSync(file, data[, options])

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

Возвращает undefined.

Если data — обычный объект, он должен иметь собственное (не унаследованное) свойство функции toString.

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

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

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

• fd <целое>
• buffer <Буфер> | <Массив_типов> | <DataView> | <строка> | <Объект>
• offset <целое>
• length <целое>
• position <целое>
• Возвращает: <число> Количество записанных байтов.

Если buffer — обычный объект, он должен иметь собственное (не унаследованное) свойство функции toString.

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

fs.writeSync(fd, string[, position[, encoding]])