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

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

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

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

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

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

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

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

import { unlink } from 'node:fs';

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

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

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

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

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

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

import { unlinkSync } from 'node:fs';

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

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

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

API промисов

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

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

Класс: FileHandle

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

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

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

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

Событие: 'close'

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

filehandle.appendFile(data[, options])

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

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

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

filehandle.chmod(mode)

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

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

filehandle.chown(uid, gid)

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

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

filehandle.close()

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

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

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

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

filehandle.createReadStream([options])

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

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

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

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

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

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

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

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

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

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

filehandle.createWriteStream([options])

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

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

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

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

filehandle.datasync()

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

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

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

filehandle.fd

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

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

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

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

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

filehandle.read([options])

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

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

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

filehandle.read(buffer[, options])

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

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

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

filehandle.readableWebStream([options])

• options <Object>

  • type <string> | <undefined> Открывать обычный поток или поток 'bytes'. По умолчанию: undefined

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

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

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

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

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

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

await file.close();

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

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

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

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

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

filehandle.readFile(options)

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

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

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

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

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

filehandle.readLines([options])

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

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

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

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

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

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

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

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

filehandle.readv(buffers[, position])

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

Читает данные из файла и записывает их в массив объектов <ArrayBufferView>

filehandle.stat([options])

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

filehandle.sync()

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

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

filehandle.truncate(len)

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

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

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

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

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

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

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

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

filehandle.utimes(atime, mtime)

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

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

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

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

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

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

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

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

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

filehandle.write(buffer[, options])

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

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

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

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

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

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

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

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

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

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

filehandle.writeFile(data, options)

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

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

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

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

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

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

filehandle.writev(buffers[, position])

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

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

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

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

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

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

filehandle[Symbol.asyncDispose]()

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

fsPromises.access(path[, mode])

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

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

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

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

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

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

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

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

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

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

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

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

fsPromises.chmod(path, mode)

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

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

fsPromises.chown(path, uid, gid)

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

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

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

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

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

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

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

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

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

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

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

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

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

fsPromises.lchmod(path, mode)

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

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

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

fsPromises.lchown(path, uid, gid)

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

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

fsPromises.lutimes(path, atime, mtime)

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

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

fsPromises.link(existingPath, newPath)

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

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

fsPromises.lstat(path[, options])

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

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

fsPromises.mkdir(path[, options])

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

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

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

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

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

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

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

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

  console.log(dirCreation);
  return dirCreation;
}

makeDirectory().catch(console.error);

fsPromises.mkdtemp(prefix[, options])

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

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

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

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

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

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

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

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

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

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

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

fsPromises.opendir(path[, options])

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

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

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

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

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

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

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

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

fsPromises.readdir(path[, options])

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

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

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

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

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

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

fsPromises.readFile(path[, options])

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

fsPromises.readlink(path[, options])

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

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

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

fsPromises.realpath(path[, options])

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

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

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

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

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

fsPromises.rename(oldPath, newPath)

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

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

fsPromises.rmdir(path[, options])

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

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

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

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

fsPromises.rm(path[, options])

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

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

fsPromises.stat(path[, options])

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

fsPromises.statfs(path[, options])

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

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

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

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

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

fsPromises.truncate(path[, len])

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

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

fsPromises.unlink(path)

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

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

fsPromises.utimes(path, atime, mtime)

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

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

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

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

fsPromises.watch(filename[, options])

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

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

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

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

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

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

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

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

• file <string> | <Buffer> | <URL> имя файла или <FileHandle> FileHandle
• data <string> | <Buffer> | <TypedArray> | <DataView> | <AsyncIterable> | <Iterable> | <Stream>
• options <Object> | <string>
  • encoding <string> | <null> По умолчанию: 'utf8'
  • mode <integer> По умолчанию: 0o666
  • flag <string> См. поддерживаемые флаги файловой системы flags. По умолчанию: 'w'.
  • flush <boolean> Если все данные успешно записаны в файл и flush равно true, для сброса данных используется filehandle.sync(). По умолчанию: false.
  • signal <AbortSignal> позволяет отменить выполняющуюся запись файла
• Возвращает: <Promise> При успешном выполнении содержит undefined.

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

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

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

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

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

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

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

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

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

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

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

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

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

fsPromises.constants

• <Object>

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

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

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

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

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

• path <string> | <Buffer> | <URL>
• mode <integer> По умолчанию: fs.constants.F_OK
• callback <Function>
  • err <Error>

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

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

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

const file = 'package.json';

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

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

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

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

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

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

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

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

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

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

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

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

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

    throw err;
  }

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

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

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

    throw err;
  }

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

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

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

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

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

    throw err;
  }

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

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

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

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

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

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

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

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

import { appendFile } from 'node:fs';

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

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

import { appendFile } from 'node:fs';

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

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

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

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

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

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

fs.chmod(path, mode, callback)

• path <string> | <Buffer> | <URL>
• mode <string> | <integer>
• callback <Function>
  • err <Error>

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

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

import { chmod } from 'node:fs';

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

Режимы доступа к файлам

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

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

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

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

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

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

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

• path <string> | <Buffer> | <URL>
• uid <integer>
• gid <integer>
• callback <Function>
  • err <Error>

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

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

fs.close(fd[, callback])

• fd <integer>
• callback <Function>
  • err <Error>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

fs.createReadStream(path[, options])

• path <string> | <Buffer> | <URL>
• options <string> | <Object>
  • flags <string> См. поддерживаемые флаги файловой системы flags. По умолчанию: 'r'.
  • encoding <string> По умолчанию: null
  • fd <integer> | <FileHandle> По умолчанию: null
  • mode <integer> По умолчанию: 0o666
  • autoClose <boolean> По умолчанию: true
  • emitClose <boolean> По умолчанию: true
  • start <integer>
  • end <integer> По умолчанию: Infinity
  • highWaterMark <integer> По умолчанию: 64 * 1024
  • fs <Object> | <null> По умолчанию: null
  • signal <AbortSignal> | <null> По умолчанию: null
• Возвращает: <fs.ReadStream>

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

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

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

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

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

import { createReadStream } from 'node:fs';

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

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

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

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

import { createReadStream } from 'node:fs';

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

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

fs.createWriteStream(path[, options])

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

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

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

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

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

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

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

fs.exists(path, callback)

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

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

import { exists } from 'node:fs';

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

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

Если path является символической ссылкой, она прослеживается. Поэтому, если path существует, но указывает на несуществующий элемент, обратный вызов получит значение false.

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

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

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

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

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

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

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

    throw err;
  }

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

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

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

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

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

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

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

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

    throw err;
  }

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

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

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

fs.fchmod(fd, mode, callback)

• fd <integer>
• mode <string> | <integer>
• callback <Function>
  • err <Error>

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

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

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

• fd <integer>
• uid <integer>
• gid <integer>
• callback <Function>
  • err <Error>

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

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

fs.fdatasync(fd, callback)

• fd <integer>
• callback <Function>
  • err <Error>

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

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

• fd <integer>
• options <Object>
  • bigint <boolean> Должны ли числовые значения в возвращаемом объекте <fs.Stats> иметь тип bigint. По умолчанию: false.
• callback <Function>
  • err <Error>
  • stats <fs.Stats>

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

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

fs.fsync(fd, callback)

• fd <integer>
• callback <Function>
  • err <Error>

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

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

• fd <integer>
• len <integer> По умолчанию: 0
• callback <Function>
  • err <Error>

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

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

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

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

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

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

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

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

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

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

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

• fd <integer>
• atime <number> | <string> | <Date>
• mtime <number> | <string> | <Date>
• callback <Function>
  • err <Error>

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

fs.lchmod(path, mode, callback)

• path <string> | <Buffer> | <URL>
• mode <integer>
• callback <Function>
  • err <Error> | <AggregateError>

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

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

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

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

• path <string> | <Buffer> | <URL>
• uid <integer>
• gid <integer>
• callback <Function>
  • err <Error>

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

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

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

• path <string> | <Buffer> | <URL>
• atime <number> | <string> | <Date>
• mtime <number> | <string> | <Date>
• callback <Function>
  • err <Error>

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

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

fs.link(existingPath, newPath, callback)

• existingPath <string> | <Buffer> | <URL>
• newPath <string> | <Buffer> | <URL>
• callback <Function>
  • err <Error>

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

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

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

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

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

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

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

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

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

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

import { mkdir } from 'node:fs';

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

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

import { mkdir } from 'node:fs';

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

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

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

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

Создает уникальный временный каталог.

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

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

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

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

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

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

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

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

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

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

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

• path <string> | <Buffer> | <URL>
• flags <string> | <number> См. поддерживаемые флаги файловой системы flags. По умолчанию: 'r'.
• mode <string> | <integer> По умолчанию: 0o666 (чтение и запись)
• callback <Function>
  • err <Error>
  • fd <integer>

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

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

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

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

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

fs.openAsBlob(path[, options])

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

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

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

import { openAsBlob } from 'node:fs';

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Например:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

import { readFile } from 'node:fs';

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

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

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

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

import { readFile } from 'node:fs';

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

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

import { readFile } from 'node:fs';

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

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

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

import { readFile } from 'node:fs';

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

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

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

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

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

Особенности производительности

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Если путь не существует, возникает ошибка ENOENT. error.path — это абсолютный путь к файлу.

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

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

Асинхронная версия realpath(3).

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

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

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

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

fs.rename(oldPath, newPath, callback)

• oldPath <string> | <Buffer> | <URL>
• newPath <string> | <Buffer> | <URL>
• callback <Function>
  • err <Error>

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

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

import { rename } from 'node:fs';

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

import { stat } from 'node:fs';

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

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

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

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

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

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

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

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

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

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

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

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

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

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

import { symlink } from 'node:fs';

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

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

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

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

• path <string> | <Buffer> | <URL>
• len <integer> По умолчанию: 0
• callback <Function>
  • err <Error> | <AggregateError>

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

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

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

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

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

fs.unlink(path, callback)

• path <string> | <Buffer> | <URL>
• callback <Function>
  • err <Error>

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

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

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

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

fs.unwatchFile(filename[, listener])

• filename <string> | <Buffer> | <URL>
• listener <Function> Необязательный параметр: обработчик, ранее добавленный с помощью fs.watchFile()

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

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

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

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

• path <string> | <Buffer> | <URL>
• atime <number> | <string> | <Date>
• mtime <number> | <string> | <Date>
• callback <Function>
  • err <Error>

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

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

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

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

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

Наблюдает за изменениями в filename, где filename является файлом или каталогом.

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

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

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

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

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

Ограничения

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

В 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, однако этот метод медленнее и менее надежен.

Индексы inode

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

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

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

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

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

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

• filename <string> | <Buffer> | <URL>
• options <Object>
  • bigint <boolean> По умолчанию: false
  • persistent <boolean> По умолчанию: true
  • interval <integer> По умолчанию: 5007
• listener <Function>
  • current <fs.Stats>
  • previous <fs.Stats>
• Возвращает: <fs.StatWatcher>

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

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

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

import { watchFile } from 'node:fs';

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

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

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

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

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

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

Это происходит в следующих случаях:

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

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

• fd <integer>
• buffer <Buffer> | <TypedArray> | <DataView>
• offset <integer> По умолчанию: 0
• length <integer> По умолчанию: buffer.byteLength - offset
• position <integer> | <null> По умолчанию: null
• callback <Function>
  • err <Error>
  • bytesWritten <integer>
  • buffer <Buffer> | <TypedArray> | <DataView>

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

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

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

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

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

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

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

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

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

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

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

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

• fd <integer>
• string <string>
• position <integer> | <null> По умолчанию: null
• encoding <string> По умолчанию: 'utf8'
• callback <Function>
  • err <Error>
  • written <integer>
  • string <string>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

import { writeFile } from 'node:fs';

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Синхронный API

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

fs.accessSync(path[, mode])

• path <string> | <Buffer> | <URL>
• mode <integer> По умолчанию: fs.constants.F_OK

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

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

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

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

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

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

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

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

import { appendFileSync } from 'node:fs';

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

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

import { appendFileSync } from 'node:fs';

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

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

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

let fd;

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

fs.chmodSync(path, mode)

• path <string> | <Buffer> | <URL>
• mode <string> | <integer>

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

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

fs.chownSync(path, uid, gid)

• path <string> | <Buffer> | <URL>
• uid <integer>
• gid <integer>

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

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

fs.closeSync(fd)

• fd <integer>

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

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

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

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

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

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

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

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

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

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

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

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

fs.existsSync(path)

• path <string> | <Buffer> | <URL>
• Возвращает: <boolean>

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

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

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

import { existsSync } from 'node:fs';

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

fs.fchmodSync(fd, mode)

• fd <integer>
• mode <string> | <integer>

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

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

fs.fchownSync(fd, uid, gid)

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

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

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

fs.fdatasyncSync(fd)

• fd <integer>

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

fs.fstatSync(fd[, options])

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

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

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

fs.fsyncSync(fd)

• fd <integer>

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

fs.ftruncateSync(fd[, len])

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

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

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

fs.futimesSync(fd, atime, mtime)

• fd <integer>
• atime <number> | <string> | <Date>
• mtime <number> | <string> | <Date>

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

fs.lchmodSync(path, mode)

• path <string> | <Buffer> | <URL>
• mode <integer>

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

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

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

fs.lchownSync(path, uid, gid)

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

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

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

fs.lutimesSync(path, atime, mtime)

• path <string> | <Buffer> | <URL>
• atime <number> | <string> | <Date>
• mtime <number> | <string> | <Date>

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

fs.linkSync(existingPath, newPath)

• existingPath <string> | <Buffer> | <URL>
• newPath <string> | <Buffer> | <URL>

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

fs.lstatSync(path[, options])