Файловая система¶

v18.x.x

Модуль node:fs позволяет взаимодействовать с файловой системой по образцу стандартных функций POSIX.

Чтобы использовать API, основанные на обещаниях:

1

import * as fs from 'node:fs/promises';

1

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

Чтобы использовать API обратного вызова и синхронизации:

1

import * as fs from 'node:fs';

1

const fs = require('node:fs');

Все операции с файловой системой имеют синхронную, обратную и основанную на обещаниях формы, и доступны как с помощью синтаксиса CommonJS, так и с помощью модулей ES6 (ESM).

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

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

1
2
3
4
5
6
7
8

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

try {
    await unlink('/tmp/hello');
    console.log('successfully deleted /tmp/hello');
} catch (error) {
    console.error('произошла ошибка:', error.message);
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

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

(async function (path) {
    try {
        await unlink(path);
        console.log(`successfully deleted ${path}`);
    } catch (error) {
        console.error('произошла ошибка:', error.message);
    }
})('/tmp/hello');

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

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

1
2
3
4
5
6

import { unlink } from 'node:fs';

unlink('/tmp/hello', (err) => {
    if (err) throw err;
    console.log('успешно удалено /tmp/hello');
});

1
2
3
4
5
6

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

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

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

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

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

1
2
3
4
5
6
7
8

import { unlinkSync } from 'node:fs';

try {
    unlinkSync('/tmp/hello');
    console.log('successfully deleted /tmp/hello');
} catch (err) {
    // обрабатываем ошибку
}

1
2
3
4
5
6
7
8

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

try {
    unlinkSync('/tmp/hello');
    console.log('successfully deleted /tmp/hello');
} catch (err) {
    // обрабатываем ошибку
}

Promises API¶

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

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

FileHandle¶

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

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

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

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

Событие: 'close'¶

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

filehandle.appendFile¶

1

filehandle.appendFile(data[, options])

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

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

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

filehandle.chmod¶

1

filehandle.chmod(mode);

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

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

filehandle.chown¶

1

filehandle.chown(uid, gid);

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

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

filehandle.close¶

1

filehandle.close();

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

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

1
2
3
4
5
6
7
8

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

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

filehandle.createReadStream¶

1

filehandle.createReadStream([options]);

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

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

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

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

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

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

const fd = await open('/dev/input/event0');
// Создаем поток из некоторого символьного устройства.
const stream = fd.createReadStream();
setTimeout(() => {
    stream.close(); // Это может не закрыть поток.
    // Искусственное обозначение конца потока, как если бы базовый ресурс сам по себе
    // сам по себе указал конец файла, позволяет потоку закрыться.
    // Это не отменяет ожидающие операции чтения, и если такая операция есть, то процесс может не закрыть поток.
    // операция, процесс все равно не сможет успешно завершиться.
    // пока она не завершится.
    stream.push(null);
    stream.read(0);
}, 100);

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

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

1
2
3
4

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

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

filehandle.createWriteStream¶

1

filehandle.createWriteStream([options]);

• options <Object>
  • encoding <string> По умолчанию: 'utf8'.
  • autoClose <boolean> По умолчанию: true
  • emitClose <boolean> По умолчанию: true
  • start <integer>
• Возвращает: <fs.WriteStream>

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

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

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

filehandle.datasync¶

1

filehandle.datasync();

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

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

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

filehandle.fd¶

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

filehandle.read¶

1

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

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

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

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

1

filehandle.read([options]);

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

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

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

1

filehandle.read(buffer[, options])

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

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

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

filehandle.readableWebStream¶

1

filehandle.readableWebStream();

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

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

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

1
2
3
4
5
6
7
8

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

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¶

1

filehandle.readFile(options);

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

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

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

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

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

filehandle.readLines¶

1

filehandle.readLines([options]);

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

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

1
2
3
4
5
6
7

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

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

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

1
2
3
4
5
6
7
8
9

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¶

1

filehandle.readv(buffers[, position])

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

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

filehandle.stat¶

1

filehandle.stat([options]);

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

filehandle.sync¶

1

filehandle.sync();

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

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

filehandle.truncate¶

1

filehandle.truncate(len);

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

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

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

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

1
2
3
4
5
6
7
8
9

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

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

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

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

filehandle.utimes¶

1

filehandle.utimes(atime, mtime);

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

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

filehandle.write¶

1

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

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

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

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

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

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

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

1

filehandle.write(buffer[, options])

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

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

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

1

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

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

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

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

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

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

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

filehandle.writeFile¶

1

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 - строка, то она определяет кодировку.

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

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

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

filehandle.writev¶

1

filehandle.writev(buffers[, position])

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

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

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

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

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

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

fsPromises.access¶

1

fsPromises.access(path[, mode])

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

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

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

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('невозможно получить доступ');
}

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

fsPromises.appendFile¶

1

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

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

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

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

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

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

fsPromises.chmod¶

1

fsPromises.chmod(path, mode);

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

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

fsPromises.chown¶

1

fsPromises.chown(path, uid, gid);

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

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

fsPromises.copyFile¶

1

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

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

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

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

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

try {
    await copyFile('source.txt', 'destination.txt');
    console.log(
        'source.txt был скопирован в destination.txt'
    );
} catch {
    console.error('Файл не удалось скопировать');
}

// При использовании COPYFILE_EXCL операция завершится неудачей, если файл destination.txt существует.
try {
    await copyFile(
        'source.txt',
        'destination.txt',
        constants.COPYFILE_EXCL
    );
    console.log(
        'source.txt был скопирован в destination.txt'
    );
} catch {
    console.error('Файл не удалось скопировать');
}

fsPromises.cp¶

1

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

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

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

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

fsPromises.lchmod¶

1

fsPromises.lchmod(path, mode);

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

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

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

fsPromises.lchown¶

1

fsPromises.lchown(path, uid, gid);

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

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

fsPromises.lutimes¶

1

fsPromises.lutimes(path, atime, mtime);

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

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

fsPromises.link¶

1

fsPromises.link(existingPath, newPath);

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

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

fsPromises.lstat¶

1

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¶

1

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

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¶

1

fsPromises.mkdtemp(prefix[, options])

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

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

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

1
2
3
4
5
6
7
8
9

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

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

fsPromises.open¶

1

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

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

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

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

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

fsPromises.opendir¶

1

fsPromises.opendir(path[, options])

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

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

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

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

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

1
2
3
4
5
6
7
8
9

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

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

fsPromises.readdir¶

1

fsPromises.readdir(path[, options])

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

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

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

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

1
2
3
4
5
6
7
8

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

fsPromises.readFile¶

1

fsPromises.readFile(path[, options])

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

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

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

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

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

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

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

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

    // Прервать запрос до того, как обещание исполнится.
    controller.abort();

    await promise;
} catch (err) {
    // Когда запрос прерывается - err является AbortError
    console.error(err);
}

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

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

fsPromises.readlink¶

1

fsPromises.readlink(path[, options])

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

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

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

fsPromises.realpath¶

1

fsPromises.realpath(path[, options])

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

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

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

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

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

fsPromises.rename¶

1

fsPromises.rename(oldPath, newPath);

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

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

fsPromises.rmdir¶

1

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¶

1

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¶

1

fsPromises.stat(path[, options])

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

fsPromises.statfs¶

1

fsPromises.statfs(path[, options])

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

fsPromises.symlink¶

1

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

fsPromises.truncate¶

1

fsPromises.truncate(path[, len])

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

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

fsPromises.unlink¶

1

fsPromises.unlink(path);

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

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

fsPromises.utimes¶

1

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, будет выдана ошибка.

fsPromises.watch¶

1

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> Имя измененного файла.

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

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

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

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

fsPromises.writeFile¶

1

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
  • флаг <string> По умолчанию: 'w'.
  • 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().

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

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

    // Прервите запрос до того, как обещание установится.
    controller.abort();

    await promise;
} catch (err) {
    // Когда запрос прерывается - err является AbortError
    console.error(err);
}

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

fsPromises.constants¶

• <Object>

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

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

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

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

fs.access¶

1

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, либо маской, состоящей из побитового OR любого из fs.constants.R_OK, fs.constants.W_OK и fs.constants.X_OK (например, fs.constants.W_OK | fs.constants.R_OK). Возможные значения mode смотрите в File access constants.

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

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

const file = 'package.json';

// Проверяем, существует ли файл в текущем каталоге.
access(file, constants.F_OK, (err) => {
    console.log(
        `${файл} ${err ? 'не существует' : 'существует'}`
    );
});

// Проверяем, доступен ли файл для чтения.
access(file, constants.R_OK, (err) => {
    console.log(
        `${file} ${err ? 'is not readable' : 'is readable'}`
    );
});

// Проверьте, доступен ли файл для записи.
access(file, constants.W_OK, (err) => {
    console.log(
        `${file} ${err ? 'is not writable' : 'is writable'}`
    );
});

// Проверьте, доступен ли файл для чтения и записи.
access(file, constants.R_OK | constants.W_OK, (err) => {
    console.log(
        `${file} ${
            err ? 'is not' : 'is'
        } readable and writable`
    );
});

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

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

access('myfile', (err) => {
    if (!err) {
        console.error('myfile уже существует');
        return;
    }

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

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

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

open('myfile', 'wx', (err, fd) => {
    if (err) {
        if (err.code === 'EEXIST') {
            console.error('myfile уже существует');
            return;
        }

        throw err;
    }

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

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

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

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

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

fs.appendFile¶

1

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

• path <string> | <Buffer> | <URL> | <number> имя файла или дескриптор файла
• data <string> | <Buffer>
• options <Object> | <string>
  • encoding <string> | <null> По умолчанию: `'utf8''
  • mode <integer> По умолчанию: 0o666
  • флаг <string> По умолчанию: 'a'.
• callback <Function>
  • err <Error>

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

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

import { appendFile } from 'node:fs';

appendFile(
    'message.txt',
    'данные для добавления',
    (err) => {
        if (err) throw err;
        console.log(
            'Данные "data to append" были добавлены в файл!'
        );
    }
);

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

1
2
3
4
5
6
7
8

import { appendFile } from 'node:fs';

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

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

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,
            'данные для добавления',
            'utf8',
            (err) => {
                closeFd(fd);
                if (err) throw err;
            }
        );
    } catch (err) {
        closeFd(fd);
        throw err;
    }
});

fs.chmod¶

1

fs.chmod(path, mode, callback);

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

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

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

1
2
3
4
5
6
7
8

import { chmod } from 'node:fs';

chmod('my_file.txt', 0o775, (err) => {
    if (err) throw err;
    console.log(
        'Разрешения для файла "my_file.txt" были изменены!'
    );
});

Файловые режимы

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

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

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

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

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

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

fs.chown¶

1

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

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

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

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

fs.close¶

1

fs.close(fd[, callback])

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

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

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

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

fs.copyFile¶

1

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

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

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

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

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

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

function callback(err) {
    if (err) throw err;
    console.log(
        'source.txt был скопирован в destination.txt'
    );
}

// destination.txt будет создан или перезаписан по умолчанию.
copyFile('source.txt', 'destination.txt', callback);

// При использовании COPYFILE_EXCL операция завершится неудачно, если файл destination.txt существует.
copyFile(
    'source.txt',
    'destination.txt',
    constants.COPYFILE_EXCL,
    callback
);

fs.cp¶

1

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

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

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

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

fs.createReadStream¶

1

fs.createReadStream(path[, options])

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

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

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