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

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

const fs = require('fs');

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

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

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

const fs = require('fs');

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

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

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

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

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

Порядок операций с обратными вызовами и обещаниями

Гарантированный порядок выполнения при использовании методов с обратными вызовами или на основе обещаний отсутствует. Например, следующее подвержено ошибке, так как операция fs.stat() может завершиться до операции fs.rename().

fs.rename('/tmp/hello', '/tmp/world', (err) => {
  if (err) throw err;
  console.log('renamed complete');
});
fs.stat('/tmp/world', (err, stats) => {
  if (err) throw err;
  console.log(`stats: ${JSON.stringify(stats)}`);
});

Чтобы правильно упорядочить операции, перенесите вызов fs.stat() в обратный вызов операции fs.rename().

fs.rename('/tmp/hello', '/tmp/world', (err) => {
  if (err) throw err;
  fs.stat('/tmp/world', (err, stats) => {
    if (err) throw err;
    console.log(`stats: ${JSON.stringify(stats)}`);
  });
});

Или используйте API на основе обещаний:

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

(async function(from, to) {
  try {
    await fs.rename(from, to);
    const stats = await fs.stat(to);
    console.log(`stats: ${JSON.stringify(stats)}`);
  } catch (error) {
    console.error('there was an error:', error.message);
  }
})('/tmp/hello', '/tmp/world');

Пути к файлам

Большинство fs операций принимают пути к файлам, которые могут быть заданы в виде строки, Buffer или объекта URL с использованием протокола file:.

Пути в строковом формате интерпретируются как последовательности UTF-8 символов, определяющих абсолютный или относительный путь к файлу. Относительные пути будут разрешаться относительно текущего каталога, определяемого вызовом process.cwd().

Пример использования абсолютного пути на POSIX:

const fs = require('fs');

fs.open('/open/some/file.txt', 'r', (err, fd) => {
  if (err) throw err;
  fs.close(fd, (err) => {
    if (err) throw err;
  });
});

Пример использования относительного пути на POSIX (относительно process.cwd()):

fs.open('file.txt', 'r', (err, fd) => {
  if (err) throw err;
  fs.close(fd, (err) => {
    if (err) throw err;
  });
});

Пути, заданные с помощью Buffer, полезны в основном на определённых операционных системах POSIX, которые обрабатывают пути к файлам как непрозрачные последовательности байтов. На таких системах один путь к файлу может содержать подпоследовательности, использующие несколько кодировок символов. Как и строковые пути, пути Buffer могут быть относительными или абсолютными:

Пример использования абсолютного пути на POSIX:

fs.open(Buffer.from('/open/some/file.txt'), 'r', (err, fd) => {
  if (err) throw err;
  fs.close(fd, (err) => {
    if (err) throw err;
  });
});

В Windows Node.js использует понятие текущего каталога для каждого диска. Это поведение можно наблюдать при использовании пути к диску без обратного слеша. Например, fs.readdirSync('C:\\') может потенциально вернуть другой результат, чем fs.readdirSync('C:'). Для получения более подробной информации см. эту страницу MSDN.

Поддержка объектов URL

Для большинства функций модуля fs, аргумент path или filename может быть передан в виде объекта WHATWG URL. Поддерживаются только объекты URL с использованием протокола file:.

const fs = require('fs');
const fileUrl = new URL('file:///tmp/hello');

fs.readFileSync(fileUrl);

file: URL всегда являются абсолютными путями.

Использование объектов WHATWG URL может привести к платформоспецифическому поведению.

В Windows file: URL с именем хоста преобразуются в UNC-пути, а file: URL с буквами диска преобразуются в локальные абсолютные пути. file: URL без имени хоста и буквы диска приведут к ошибке:

// On Windows :

// - WHATWG file URLs with hostname convert to UNC path
// file://hostname/p/a/t/h/file => \\hostname\p\a\t\h\file
fs.readFileSync(new URL('file://hostname/p/a/t/h/file'));

// - WHATWG file URLs with drive letters convert to absolute path
// file:///C:/tmp/hello => C:\tmp\hello
fs.readFileSync(new URL('file:///C:/tmp/hello'));

// - WHATWG file URLs without hostname must have a drive letters
fs.readFileSync(new URL('file:///notdriveletter/p/a/t/h/file'));
fs.readFileSync(new URL('file:///c/p/a/t/h/file'));
// TypeError [ERR_INVALID_FILE_URL_PATH]: File URL path must be absolute

file: URL с буквами диска должны использовать : в качестве разделителя сразу после буквы диска. Использование другого разделителя приведет к ошибке.

На всех других платформах file: URL с именем хоста не поддерживаются и приведут к ошибке:

// On other platforms:

// - WHATWG file URLs with hostname are unsupported
// file://hostname/p/a/t/h/file => throw!
fs.readFileSync(new URL('file://hostname/p/a/t/h/file'));
// TypeError [ERR_INVALID_FILE_URL_PATH]: must be absolute

// - WHATWG file URLs convert to absolute path
// file:///tmp/hello => /tmp/hello
fs.readFileSync(new URL('file:///tmp/hello'));

file: URL с закодированными слешами приведут к ошибке на всех платформах:

// On Windows
fs.readFileSync(new URL('file:///C:/p/a/t/h/%2F'));
fs.readFileSync(new URL('file:///C:/p/a/t/h/%2f'));
/* TypeError [ERR_INVALID_FILE_URL_PATH]: File URL path must not include encoded
\ or / characters */

// On POSIX
fs.readFileSync(new URL('file:///p/a/t/h/%2F'));
fs.readFileSync(new URL('file:///p/a/t/h/%2f'));
/* TypeError [ERR_INVALID_FILE_URL_PATH]: File URL path must not include encoded
/ characters */

В Windows file: URL с закодированными обратными слешами приведут к ошибке:

// On Windows
fs.readFileSync(new URL('file:///C:/path/%5C'));
fs.readFileSync(new URL('file:///C:/path/%5c'));
/* TypeError [ERR_INVALID_FILE_URL_PATH]: File URL path must not include encoded
\ or / characters */

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

В системах POSIX для каждого процесса ядро поддерживает таблицу открытых файлов и ресурсов. Каждый открытый файл получает простой числовой идентификатор, называемый дескриптором файла. На уровне системы все операции с файловой системой используют эти дескрипторы для идентификации и отслеживания каждого конкретного файла. Системы Windows используют другой, но концептуально подобный механизм для отслеживания ресурсов. Для упрощения для пользователей Node.js абстрагирует специфические различия между операционными системами и присваивает всем открытым файлам числовой дескриптор.

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

fs.open('/open/some/file.txt', 'r', (err, fd) => {
  if (err) throw err;
  fs.fstat(fd, (err, stat) => {
    if (err) throw err;
    // use stat

    // always close the file descriptor!
    fs.close(fd, (err) => {
      if (err) throw err;
    });
  });
});

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

Использование потокового пула

Все API файловой системы, кроме fs.FSWatcher() и явно синхронных, используют пул потоков libuv, что может иметь неожиданные и негативные последствия для производительности некоторых приложений. См. документацию UV_THREADPOOL_SIZE для получения дополнительной информации.

Класс: fs.Dir

Класс, представляющий поток каталога.

Создан с помощью fs.opendir(), fs.opendirSync() или fsPromises.opendir().

const fs = require('fs');

async function print(path) {
  const dir = await fs.promises.opendir(path);
  for await (const dirent of dir) {
    console.log(dirent.name);
  }
}
print('./').catch(console.error);

dir.close()

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

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

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

dir.close(callback)

• callback <Функция>
  • err <Ошибка>

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

callback будет вызван после закрытия дескриптора ресурса.

dir.closeSync()

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

dir.path

• <строка>

Путь только для чтения этого каталога, как был предоставлен в fs.opendir(), fs.opendirSync() или fsPromises.opendir().

dir.read()

• Возвращает: <Promise> содержащее <fs.Dirent> | <null>

Асинхронно считывает следующую запись каталога с помощью readdir(3) как fs.Dirent.

После завершения чтения возвращается Promise, который будет выполнен с fs.Dirent или null, если больше записей каталога нет для чтения.

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

dir.read(callback)

• callback <Функция>
  • err <Ошибка>
  • dirent <fs.Dirent> | <null>

Асинхронно считывает следующую запись каталога с помощью readdir(3) как fs.Dirent.

После завершения чтения callback будет вызван с fs.Dirent, или null, если больше записей каталога нет для чтения.

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

dir.readSync()

• Возвращает: <fs.Dirent> | <null>

Синхронно считывает следующую запись каталога с помощью readdir(3) как fs.Dirent.

Если больше записей каталога нет для чтения, возвращается null.

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

dir[Symbol.asyncIterator]()

• Возвращает: <ИтераторAsync> объектов <fs.Dirent>

Асинхронно перебирает каталог с помощью readdir(3) до тех пор, пока все записи не будут считаны.

Записи, возвращаемые асинхронным итератором, всегда являются fs.Dirent. Случай null из dir.read() обрабатывается внутри.

См. пример в fs.Dir.

Записи каталога, возвращаемые этим итератором, не упорядочены, как предоставляет основная система операционной системы. Записи, добавленные или удалённые при итерации по каталогу, могут отсутствовать в результатах итерации.

Класс: fs.Dirent

Представление записи каталога, которая может быть файлом или подкаталогом в каталоге, возвращаемой при чтении из fs.Dir. Запись каталога — это сочетание пары имя файла — тип файла.

Кроме того, когда fs.readdir() или fs.readdirSync() вызывается с параметром withFileTypes установленным в true, результирующий массив заполняется объектами fs.Dirent, а не строками или Buffers.

dirent.isBlockDevice()

• Возвращает: <булево>

Возвращает true, если объект fs.Dirent описывает блок-устройство.

dirent.isCharacterDevice()

• Возвращает: <булево>

Возвращает true, если объект fs.Dirent описывает символьное устройство.

dirent.isDirectory()

• Возвращает: <булево>

Возвращает true, если объект fs.Dirent описывает директорию файловой системы.

dirent.isFIFO()

• Возвращает: <булево>

Возвращает true, если объект fs.Dirent описывает пайп FIFO (First-In, First-Out).

dirent.isFile()

• Возвращает: <булево>

Возвращает true, если объект fs.Dirent описывает обычный файл.

dirent.isSocket()

• Возвращает: <булево>

Возвращает true, если объект fs.Dirent описывает сокет.

dirent.isSymbolicLink()

• Возвращает: <булево>

Возвращает true, если объект fs.Dirent описывает символическую ссылку.

dirent.name

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

Имя файла, на который ссылается этот объект fs.Dirent. Тип этого значения определяется параметром options.encoding, переданным в fs.readdir() или fs.readdirSync().

Класс: fs.FSWatcher

• Расширяет <EventEmitter>

Успешное выполнение метода fs.watch() вернёт новый объект fs.FSWatcher.

Все объекты fs.FSWatcher излучают событие 'change' всякий раз, когда изменяется отслеживаемый файл.

Событие: 'change'

• eventType <строка> Тип события изменения
• filename <строка> | <Буфер> Имя файла, который изменился (если применимо/доступно)

Издаётся, когда что-то изменяется в отслеживаемом каталоге или файле. Более подробная информация в fs.watch().

Аргумент filename может отсутствовать в зависимости от поддержки операционной системы. Если filename предоставлен, он будет предоставлен как Buffer, если fs.watch() был вызван с опцией encoding установленной в 'buffer', в противном случае filename будет строкой UTF-8.

// Example when handled through fs.watch() listener
fs.watch('./tmp', { encoding: 'buffer' }, (eventType, filename) => {
  if (filename) {
    console.log(filename);
    // Prints: <Buffer ...>
  }
});

Событие: 'close'

Издаётся, когда мониторинг изменений прекращается. Закрытый объект fs.FSWatcher больше не может быть использован в обработчике событий.

Событие: 'error'

• error <Ошибка>

Издаётся, когда при отслеживании файла возникает ошибка. Объект fs.FSWatcher, породивший ошибку, больше не может быть использован в обработчике событий.

watcher.close()

Прекращение отслеживания изменений в заданном fs.FSWatcher. После остановки объект fs.FSWatcher больше не может использоваться.

watcher.ref()

• Возвращает: <fs.FSWatcher>

При вызове запрашивает, чтобы цикл событий Node.js не завершался, пока активен FSWatcher. Вызов watcher.ref() несколько раз не повлияет на результат.

По умолчанию все объекты FSWatcher "ссылаются", поэтому обычно не нужно вызывать watcher.ref(), если watcher.unref() ранее не был вызван.

watcher.unref()

• Возвращает: <fs.FSWatcher>

При вызове активный объект FSWatcher не требует, чтобы цикл событий Node.js оставался активным. Если нет других активностей, поддерживающих работу цикла событий, процесс может завершиться до вызова обратного вызова объекта FSWatcher. Вызов watcher.unref() несколько раз не повлияет на результат.

Класс: fs.StatWatcher

• Расширяет <EventEmitter>

Успешное выполнение метода fs.watchFile() вернёт новый объект fs.StatWatcher.

watcher.ref()

• Возвращает: <fs.StatWatcher>

При вызове запрашивает, чтобы цикл событий Node.js не завершался, пока активен StatWatcher. Вызов watcher.ref() несколько раз не повлияет на результат.

По умолчанию все объекты StatWatcher "ссылаются", поэтому обычно не нужно вызывать watcher.ref(), если watcher.unref() ранее не был вызван.

watcher.unref()

• Возвращает: <fs.StatWatcher>

При вызове активный объект StatWatcher не требует, чтобы цикл событий Node.js оставался активным. Если нет других активностей, поддерживающих работу цикла событий, процесс может завершиться до вызова обратного вызова объекта StatWatcher. Вызов watcher.unref() несколько раз не повлияет на результат.

Класс: fs.ReadStream

• Расширяет: <stream.Readable>

Экземпляры fs.ReadStream создаются и возвращаются с помощью функции fs.createReadStream().

Событие: 'close'

Издаётся, когда базовый дескриптор файла fs.ReadStream закрыт.

Событие: 'open'

• fd <целое число> Целое число, дескриптор файла, используемый ReadStream.

Издаётся, когда дескриптор файла fs.ReadStream открыт.

Событие: 'ready'

Издаётся, когда fs.ReadStream готов к использованию.

Срабатывает сразу после 'open'.

readStream.bytesRead

• <число>

Количество прочитанных байтов.

readStream.path

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

Путь к файлу, из которого читает поток, как указано в первом аргументе к fs.createReadStream(). Если path передан как строка, то readStream.path будет строкой. Если path передан как Buffer, то readStream.path будет Buffer.

readStream.pending

• <логическое значение>

Это свойство true, если базовый файл ещё не открыт, т.е. до срабатывания события 'ready'.

Класс: fs.Stats

Объект fs.Stats содержит информацию о файле.

Объекты, возвращаемые методами fs.stat(), fs.lstat() и fs.fstat(), а также их синхронными аналогами, имеют этот тип. Если bigint в options параметрах, переданных в эти методы, имеет значение true, числовые значения будут bigint вместо number, и объект будет содержать дополнительные свойства с наносекундной точностью, оканчивающиеся на Ns.

Stats {
  dev: 2114,
  ino: 48064969,
  mode: 33188,
  nlink: 1,
  uid: 85,
  gid: 100,
  rdev: 0,
  size: 527,
  blksize: 4096,
  blocks: 8,
  atimeMs: 1318289051000.1,
  mtimeMs: 1318289051000.1,
  ctimeMs: 1318289051000.1,
  birthtimeMs: 1318289051000.1,
  atime: Mon, 10 Oct 2011 23:24:11 GMT,
  mtime: Mon, 10 Oct 2011 23:24:11 GMT,
  ctime: Mon, 10 Oct 2011 23:24:11 GMT,
  birthtime: Mon, 10 Oct 2011 23:24:11 GMT }

bigint версия:

BigIntStats {
  dev: 2114n,
  ino: 48064969n,
  mode: 33188n,
  nlink: 1n,
  uid: 85n,
  gid: 100n,
  rdev: 0n,
  size: 527n,
  blksize: 4096n,
  blocks: 8n,
  atimeMs: 1318289051000n,
  mtimeMs: 1318289051000n,
  ctimeMs: 1318289051000n,
  birthtimeMs: 1318289051000n,
  atimeNs: 1318289051000000000n,
  mtimeNs: 1318289051000000000n,
  ctimeNs: 1318289051000000000n,
  birthtimeNs: 1318289051000000000n,
  atime: Mon, 10 Oct 2011 23:24:11 GMT,
  mtime: Mon, 10 Oct 2011 23:24:11 GMT,
  ctime: Mon, 10 Oct 2011 23:24:11 GMT,
  birthtime: Mon, 10 Oct 2011 23:24:11 GMT }

stats.isBlockDevice()

• Возвращает: <логическое значение>

Возвращает true , если объект fs.Stats описывает блок-устройство.

stats.isCharacterDevice()

• Возвращает: <логическое значение>

Возвращает true , если объект fs.Stats описывает символьное устройство.

stats.isDirectory()

• Возвращает: <логическое значение>

Возвращает true , если объект fs.Stats описывает директорию файловой системы.

Если объект fs.Stats был получен из fs.lstat(), этот метод всегда вернёт false. Это потому, что fs.lstat() возвращает информацию о символической ссылке, а не о пути, к которому она указывает.

stats.isFIFO()

• Возвращает: <логическое значение>

Возвращает true , если объект fs.Stats описывает канал FIFO.

stats.isFile()

• Возвращает: <логическое значение>

Возвращает true , если объект fs.Stats описывает обычный файл.

stats.isSocket()

• Возвращает: <логическое значение>

Возвращает true , если объект fs.Stats описывает сокет.

stats.isSymbolicLink()

• Возвращает: <логическое значение>

Возвращает true , если объект fs.Stats описывает символическую ссылку.

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

stats.dev

• <число> | <bigint>

Числовой идентификатор устройства, содержащего файл.

stats.ino

• <число> | <bigint>

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

stats.mode

• <число> | <bigint>

Битовое поле, описывающее тип и режим файла.

stats.nlink

• <число> | <bigint>

Количество жёстких ссылок на файл.

stats.uid

• <число> | <bigint>

Числовой идентификатор пользователя, владеющего файлом (POSIX).

stats.gid

• <число> | <bigint>

Числовой идентификатор группы, владеющей файлом (POSIX).

stats.rdev

• <число> | <bigint>

Числовой идентификатор устройства, если файл представляет собой устройство.

stats.size

• <число> | <bigint>

Размер файла в байтах.

stats.blksize

• <число> | <bigint>

Размер блока файловой системы для операций ввода-вывода.

stats.blocks

• <число> | <bigint>

Количество блоков, выделенных для этого файла.

stats.atimeMs

• <число> | <bigint>

Отметка времени последнего доступа к файлу в миллисекундах с эпохи POSIX.

stats.mtimeMs

• <число> | <bigint>

Отметка времени последнего изменения файла в миллисекундах с эпохи POSIX.

stats.ctimeMs

• <число> | <bigint>

Отметка времени последнего изменения статуса файла в миллисекундах с эпохи POSIX.

stats.birthtimeMs

• <число> | <bigint>

Отметка времени создания файла в миллисекундах с эпохи POSIX.

stats.atimeNs

• <bigint>

Присутствует только при передаче bigint: true в метод, создающий объект. Отметка времени последнего доступа к файлу в наносекундах с эпохи POSIX.

stats.mtimeNs

• <bigint>

Присутствует только при передаче bigint: true в метод, создающий объект. Отметка времени последнего изменения файла в наносекундах с эпохи POSIX.

stats.ctimeNs

• <bigint>

Присутствует только при передаче bigint: true в метод, создающий объект. Отметка времени последнего изменения статуса файла в наносекундах с эпохи POSIX.

stats.birthtimeNs

• <bigint>

Присутствует только тогда, когда bigint: true передается в метод, генерирующий объект. Отметка времени, указывающая время создания этого файла в наносекундах с момента эпохи POSIX.

stats.atime

• <Дата>

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

stats.mtime

• <Дата>

Отметка времени, указывающая последний раз, когда этот файл был изменён.

stats.ctime

• <Дата>

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

stats.birthtime

• <Дата>

Отметка времени, указывающая время создания этого файла.

Значения времени stat

Свойства atimeMs, mtimeMs, ctimeMs, birthtimeMs — числовые значения, хранящие соответствующие временные метки в миллисекундах. Их точность зависит от платформы. Когда bigint: true передаётся в метод, генерирующий объект, свойства будут bigintami, в противном случае они будут числами.

Свойства atimeNs, mtimeNs, ctimeNs, birthtimeNs — bigint, хранящие соответствующие временные метки в наносекундах. Они присутствуют только тогда, когда bigint: true передаётся в метод, генерирующий объект. Их точность зависит от платформы.

atime, mtime, ctime, и birthtime являются Date объекта — альтернативные представления различных временных меток. Значения Date и числовые значения не связаны. Присвоение нового числового значения или изменение значения Date не отразится в соответствующем альтернативном представлении.

Временные метки в объекте stat имеют следующие значения:

• atime "Время доступа": Время, когда данные файла были в последний раз обработаны. Изменяется системными вызовами mknod(2), utimes(2) и read(2).
• mtime "Время изменения": Время, когда данные файла были в последний раз изменены. Изменяется системными вызовами mknod(2), utimes(2) и write(2).
• ctime "Время изменения статуса": Время последнего изменения статуса файла (изменения данных индексного узла). Изменяется системными вызовами chmod(2), chown(2), link(2), mknod(2), rename(2), unlink(2), utimes(2), read(2) и write(2).
• birthtime "Время создания": Время создания файла. Устанавливается один раз при создании файла. В файловых системах, где время создания недоступно, это поле может содержать либо ctime, либо 1970-01-01T00:00Z (т.е. отметка времени эпохи Unix 0). В этом случае это значение может быть больше, чем atime или mtime. В системах Darwin и других вариантах FreeBSD, также устанавливается, если atime явно устанавливается в более раннее значение, чем текущее значение birthtime с помощью системного вызова utimes(2).

До Node.js 0.12, ctime содержал birthtime в системах Windows. Начиная с 0.12, ctime не является "временем создания", и в системах Unix им никогда не был.

Класс: fs.WriteStream

• Расширяет <stream.Writable>

Экземпляры fs.WriteStream создаются и возвращаются с помощью функции fs.createWriteStream().

Событие: 'close'

Вызывается, когда дескриптор файла, лежащий в основе WriteStream, был закрыт.

Событие: 'open'

• fd <целое> Целое число — дескриптор файла, используемый WriteStream.

Вызывается, когда файл WriteStream открыт.

Событие: 'ready'

Вызывается, когда fs.WriteStream готов к использованию.

Вызывается сразу после 'open'.

writeStream.bytesWritten

Количество байтов, записанных до сих пор. Не включает данные, которые всё ещё находятся в очереди на запись.

writeStream.path

Путь к файлу, в который записывается поток, как указано в первом аргументе функции fs.createWriteStream(). Если path передаётся как строка, то writeStream.path будет строкой. Если path передаётся как Buffer, то writeStream.path будет Buffer.

writeStream.pending

• <логическое значение>

Это свойство имеет значение true, если базовый файл ещё не открыт, то есть до вызова события 'ready'.

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

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

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

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

Следующие примеры проверяют, существует ли package.json, и если оно читабельно или записываемо.

const file = 'package.json';

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

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

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

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

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

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

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

  fs.open('myfile', 'wx', (err, fd) => {
    if (err) throw err;
    writeMyData(fd);
  });
});

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

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

    throw err;
  }

  writeMyData(fd);
});

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

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

    throw err;
  }

  fs.open('myfile', 'r', (err, fd) => {
    if (err) throw err;
    readMyData(fd);
  });
});

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

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

    throw err;
  }

  readMyData(fd);
});

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

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

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

fs.accessSync(path[, mode])

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

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

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

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

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

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

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

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

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

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

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

fs.open('message.txt', 'a', (err, fd) => {
  if (err) throw err;
  fs.appendFile(fd, 'data to append', 'utf8', (err) => {
    fs.close(fd, (err) => {
      if (err) throw err;
    });
    if (err) throw err;
  });
});

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

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

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

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

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

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

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

let fd;

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

fs.chmod(path, mode, callback)

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

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

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

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

Режим файла

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

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

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

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

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

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

fs.chmodSync(path, mode)

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

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

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

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

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

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

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

fs.chownSync(path, uid, gid)

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

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

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

fs.close(fd[, callback])

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

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

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

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

fs.closeSync(fd)

• fd <integer>

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

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

fs.constants

• <Object>

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

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

const fs = require('fs');
const { COPYFILE_EXCL } = fs.constants;

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.
fs.copyFile('source.txt', 'destination.txt', callback);

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

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

const fs = require('fs');
const { COPYFILE_EXCL } = fs.constants;

// destination.txt will be created or overwritten by default.
fs.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.
fs.copyFileSync('source.txt', 'destination.txt', COPYFILE_EXCL);

fs.createReadStream(path[, options])

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

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

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

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

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

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

Предоставление параметра fs позволяет переопределить соответствующие реализации fs для open, read, и close. При предоставлении параметра fs требуются переопределения для open, read, и close.

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

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

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

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

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

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

fs.createWriteStream(path[, options])

• path <строка> | <Буфер> | <URL>
• options <строка> | <Объект>
  • flags <строка> См. поддержку флагов файловой системы flags. По умолчанию: 'w'.
  • encoding <строка> По умолчанию: 'utf8'
  • fd <целое> По умолчанию: null
  • mode <целое> По умолчанию: 0o666
  • autoClose <логическое> По умолчанию: true
  • emitClose <логическое> По умолчанию: false
  • start <целое>
  • fs <Объект> | <null> По умолчанию: null
• Возвращает: <fs.WriteStream> См. Поток Writable.

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

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

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

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

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

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

fs.exists(path, callback)

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

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

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

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

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

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

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

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

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

    throw err;
  }

  writeMyData(fd);
});

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

fs.exists('myfile', (exists) => {
  if (exists) {
    fs.open('myfile', 'r', (err, fd) => {
      if (err) throw err;
      readMyData(fd);
    });
  } else {
    console.error('myfile does not exist');
  }
});

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

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

    throw err;
  }

  readMyData(fd);
});

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

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

fs.existsSync(path)

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

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

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

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

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

fs.fchmod(fd, mode, callback)

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

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

fs.fchmodSync(fd, mode)

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

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

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

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

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

fs.fchownSync(fd, uid, gid)

• fd <целое>
• uid <целое>
• gid <целое>

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

fs.fdatasync(fd, callback)

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

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

fs.fdatasyncSync(fd)

• fd <целое>

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

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

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

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

fs.fstatSync(fd[, options])

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

Синхронная fstat(2).

fs.fsync(fd, callback)

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

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

fs.fsyncSync(fd)

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

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

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

• fd <целое число>
• len <целое число> По умолчанию: 0
• callback <Функция>
  • err <Ошибка>

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

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

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

console.log(fs.readFileSync('temp.txt', 'utf8'));
// Prints: Node.js

// get the file descriptor of the file to be truncated
const fd = fs.openSync('temp.txt', 'r+');

// Truncate the file to first four bytes
fs.ftruncate(fd, 4, (err) => {
  assert.ifError(err);
  console.log(fs.readFileSync('temp.txt', 'utf8'));
});
// Prints: Node

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

console.log(fs.readFileSync('temp.txt', 'utf8'));
// Prints: Node.js

// get the file descriptor of the file to be truncated
const fd = fs.openSync('temp.txt', 'r+');

// Truncate the file to 10 bytes, whereas the actual size is 7 bytes
fs.ftruncate(fd, 10, (err) => {
  assert.ifError(err);
  console.log(fs.readFileSync('temp.txt'));
});
// Prints: <Buffer 4e 6f 64 65 2e 6a 73 00 00 00>
// ('Node.js\0\0\0' in UTF8)

Последние три байта — нулевые байты ('\0'), чтобы компенсировать переполнение при обрезке.

fs.ftruncateSync(fd[, len])

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

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

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

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

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

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

Эта функция не работает на версиях AIX до 7.1, она вернёт ошибку UV_ENOSYS.

fs.futimesSync(fd, atime, mtime)

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

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

fs.lchmod(path, mode, callback)

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

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

Доступно только на macOS.

fs.lchmodSync(path, mode)

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

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

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

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

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

fs.lchownSync(path, uid, gid)

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

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

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

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

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

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

fs.lutimesSync(path, atime, mtime)

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

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

fs.link(existingPath, newPath, callback)

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

Асинхронная link(2). В обратном вызове передаются только возможные ошибки.

fs.linkSync(existingPath, newPath)

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

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

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

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

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

fs.lstatSync(path[, options])

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

Синхронная операция lstat(2).

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

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

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

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

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

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

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

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

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

fs.mkdirSync(path[, options])

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

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

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

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

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

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

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

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

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

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

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

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

// This method is *INCORRECT*:
fs.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*:
const { sep } = require('path');
fs.mkdtemp(`${tmpDir}${sep}`, (err, directory) => {
  if (err) throw err;
  console.log(directory);
  // Will print something similar to `/tmp/abc123`.
  // A new temporary directory is created within
  // the /tmp directory.
});

fs.mkdtempSync(prefix[, options])

• prefix <string>
• options <string> | <Object>
  • encoding <string> По умолчанию: 'utf8'
• Возвращает: <string>

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

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

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

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

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

Асинхронное открытие файла. См. open(2).

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

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

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

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

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

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

Асинхронно открыть каталог. См. opendir(3).

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

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

fs.opendirSync(path[, options])

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

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

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

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

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

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

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

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

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

• fd <целое>
• buffer <Buffer> | <TypedArray> | <DataView>
• offset <целое>
• length <целое>
• position <целое>
• callback <Функция>
  • err <Ошибка>
  • bytesRead <целое>
  • buffer <Buffer>

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

buffer — это буфер, в который будут записаны данные (считанные из fd).

offset — это смещение в буфере, с которого начнется запись.

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

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

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

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

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

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

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

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

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

• path <строка> | <Buffer> | <URL>
• options <строка> | <Объект>
  • encoding <строка> По умолчанию: 'utf8'
  • withFileTypes <логическое> По умолчанию: false
• callback <Функция>
  • err <Ошибка>
  • files <массив строк> | <массив буферов> | <массив fs.Dirent>

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

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

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

fs.readdirSync(path[, options])

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

Синхронное использование readdir(3).

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

fs.readFileSync(path[, options])

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

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

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

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

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

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

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

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

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

Асинхронная readlink(2). Функция обратного вызова получает два аргумента (err, linkString).

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

fs.readlinkSync(path[, options])

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

Синхронная readlink(2). Возвращает строковое значение символьной ссылки.

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

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

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

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

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

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

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

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

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

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

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

• fd <целое>
• buffers <ArrayBufferView[]>
• position <целое>
• callback <Функция>
  • err <Ошибка>
  • bytesRead <целое>
  • buffers <ArrayBufferView[]>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

fs.realpathSync(path[, options])

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

Возвращает разрешённое имя пути.

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

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

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

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

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

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

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

fs.rename(oldPath, newPath, callback)

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

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

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

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

fs.renameSync(oldPath, newPath)

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

Синхронная операция rename(2). Возвращает undefined.

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

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

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

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

Установка recursive в true приводит к поведению, аналогичному команде Unix rm -rf: ошибка не будет поднята для путей, которые не существуют, а пути, представляющие файлы, будут удалены. Позволительное поведение опции recursive устарело, ENOTDIR и ENOENT будут вызваны в будущем.

fs.rmdirSync(path[, options])

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

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

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

Установка recursive в true приводит к поведению, аналогичному команде Unix rm -rf: ошибка не будет поднята для путей, которые не существуют, а пути, представляющие файлы, будут удалены. Позволительное поведение опции recursive устарело, ENOTDIR и ENOENT будут вызваны в будущем.

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

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

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

fs.rmSync(path[, options])

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

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

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

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

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

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

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

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

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

- txtDir
-- file.txt
- app.js

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

const fs = require('fs');

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

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

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

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

fs.statSync(path[, options])

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

Синхронная функция stat(2).

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

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

Асинхронная symlink(2), которая создаёт ссылку под названием path, указывающую на target. В обратный вызов при завершении передаются только возможные исключения.

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

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

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

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

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

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

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

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

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

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

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

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

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

fs.truncateSync(path[, len])

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

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

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

fs.unlink(path, callback)

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

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

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

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

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

fs.unlinkSync(path)

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

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

fs.unwatchFile(filename[, listener])

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

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

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

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

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

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

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

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

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

fs.utimesSync(path, atime, mtime)

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

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

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

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

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

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

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

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

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

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

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

Примечания

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

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

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

Доступность

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

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

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

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

Иноды

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• fd <целое>
• buffer <Буфер> | <Массив типов> | <DataView> | <строка> | <объект>
• offset <целое>
• length <целое>
• position <целое>
• callback <Функция>
  • err <Ошибка>
  • bytesWritten <целое>
  • buffer <Буфер> | <Массив типов> | <DataView>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Опция encoding игнорируется, если data — буфер. Если data — обычный объект, он должен иметь собственное свойство функции toString.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• fd <целое>
• string <строка> | <Объект>
• position <целое>
• encoding <строка>
• Возвращает: <число> Количество записанных байтов.

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

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

• fd <целое>
• buffers <ArrayBufferView[]>
• position <целое>
• callback <Функция>
  • err <Ошибка>
  • bytesWritten <целое>
  • buffers <ArrayBufferView[]>

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

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

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

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

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

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

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

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

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

fs API для работы с обещаниями

API fs.promises предоставляет альтернативный набор асинхронных методов для работы с файловой системой, возвращающие объекты Promise, а не использующие обратные вызовы. К API можно получить доступ через require('fs').promises или require('fs/promises').

Класс: FileHandle

Объект FileHandle является оболочкой для числового дескриптора файла. Экземпляры FileHandle отличаются от числовых дескрипторов файлов тем, что предоставляют ориентированный на объекты API для работы с файлами.

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

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

В отличие от API на основе обратных вызовов (fs.fstat(), fs.fchown(), fs.fchmod(), и т. д.), числовой дескриптор файла не используется в API на основе обещаний. Вместо этого, API на основе обещаний использует класс FileHandle, чтобы избежать случайной утечки незакрытых дескрипторов файлов после выполнения или отклонения обещания Promise.

filehandle.appendFile(data, options)

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

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

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

filehandle.chmod(mode)

• mode <целое число>
• Возвращает: <Обещание>

Изменяет разрешения файла. Обещание Promise выполняется без аргументов при успехе.

filehandle.chown(uid, gid)

• uid <целое число>
• gid <целое число>
• Возвращает: <Обещание>

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

filehandle.close()

• Возвращает: <Обещание> Обещание, которое будет выполнено после закрытия базового дескриптора файла, или отклонено, если при закрытии произошла ошибка.

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

const fsPromises = require('fs').promises;
async function openAndClose() {
  let filehandle;
  try {
    filehandle = await fsPromises.open('thefile.txt', 'r');
  } finally {
    if (filehandle !== undefined)
      await filehandle.close();
  }
}

filehandle.datasync()

• Возвращает: <Обещание>

Асинхронный метод fdatasync(2). Обещание Promise выполняется без аргументов при успехе.

filehandle.fd

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

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

• buffer <Буфер> | <Uint8Array>
• offset <целое число>
• length <целое число>
• position <целое число>
• Возвращает: <Обещание>

Чтение данных из файла.

buffer — это буфер, в который будут записаны данные.

offset — это смещение в буфере, с которого начнётся запись.

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

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

После успешного чтения обещание Promise выполняется с объектом, содержащим свойство bytesRead, определяющее количество прочитанных байтов, и свойство buffer, которое является ссылкой на переданный аргумент buffer.

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

filehandle.read(options)

• options <Объект>
  • buffer <Буфер> | <Uint8Array> По умолчанию: Buffer.alloc(16384)
  • offset <целое число> По умолчанию: 0
  • length <целое число> По умолчанию: buffer.length
  • position <целое число> По умолчанию: null
• Возвращает: <Обещание>

filehandle.readFile(options)

• options <Объект> | <строка>
  • encoding <строка> | <null> По умолчанию: null
  • signal <AbortSignal> позволяет прервать текущее чтение файла
• Возвращает: <Обещание>

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

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

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

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

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

filehandle.readv(buffers[, position])

• buffers <ArrayBufferView[]>
• position <целое число>
• Возвращает: <Обещание>

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

Обещание Promise выполняется с объектом, содержащим свойство bytesRead, определяющее количество прочитанных байтов, и свойство buffers, содержащее ссылку на входной массив buffers.

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

filehandle.stat([options])

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

Получает fs.Stats для файла.

filehandle.sync()

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

Асинхронная операция fsync(2). Promise Promise выполняется без аргументов при успешном завершении.

filehandle.truncate(len)

• len <целое> По умолчанию: 0
• Возвращает: <Promise>

Усекает файл и выполняет Promise без аргументов при успешном завершении.

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

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

const fs = require('fs');
const fsPromises = fs.promises;

console.log(fs.readFileSync('temp.txt', 'utf8'));
// Prints: Node.js

async function doTruncate() {
  let filehandle = null;
  try {
    filehandle = await fsPromises.open('temp.txt', 'r+');
    await filehandle.truncate(4);
  } finally {
    if (filehandle) {
      // Close the file if it is opened.
      await filehandle.close();
    }
  }
  console.log(fs.readFileSync('temp.txt', 'utf8'));  // Prints: Node
}

doTruncate().catch(console.error);

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

const fs = require('fs');
const fsPromises = fs.promises;

console.log(fs.readFileSync('temp.txt', 'utf8'));
// Prints: Node.js

async function doTruncate() {
  let filehandle = null;
  try {
    filehandle = await fsPromises.open('temp.txt', 'r+');
    await filehandle.truncate(10);
  } finally {
    if (filehandle) {
      // Close the file if it is opened.
      await filehandle.close();
    }
  }
  console.log(fs.readFileSync('temp.txt', 'utf8'));  // Prints Node.js\0\0\0
}

doTruncate().catch(console.error);

Последние три байта — нули ('\0'), чтобы компенсировать усечение.

filehandle.utimes(atime, mtime)

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

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

Эта функция не работает на версиях AIX до 7.1, она отклонит Promise с ошибкой, используя код UV_ENOSYS.

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

• buffer <Буфер> | <Uint8Массив> | <строка> | <Объект>
• offset <целое>
• length <целое>
• position <целое>
• Возвращает: <Promise>

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

Promise Promise выполняется с объектом, содержащим свойство bytesWritten, идентифицирующее количество записанных байт, и свойство buffer, содержащее ссылку на записанный buffer.

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

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

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

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

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

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

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

Promise Promise выполняется с объектом, содержащим свойство bytesWritten, идентифицирующее количество записанных байт, и свойство buffer, содержащее ссылку на записанный string.

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

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

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

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

filehandle.writeFile(data, options)

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

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

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

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

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

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

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

filehandle.writev(buffers[, position])

• buffers <ArrayBufferView[]>
• position <целое число>
• Возвращает: <Promise>

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

Promise выполняется с объектом, содержащим свойство bytesWritten, определяющее количество записанных байтов, и свойство buffers, содержащее ссылку на входной buffers.

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

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

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

fsPromises.access(path[, mode])

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

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

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

const fs = require('fs');
const fsPromises = fs.promises;

fsPromises.access('/etc/passwd', fs.constants.R_OK | fs.constants.W_OK)
  .then(() => console.log('can access'))
  .catch(() => console.error('cannot access'));

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

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

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

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

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

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

fsPromises.chmod(path, mode)

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

Изменяет разрешения файла и выполняет Promise без аргументов при успехе.

fsPromises.chown(path, uid, gid)

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

Изменяет владельца файла и выполняет Promise без аргументов при успехе.

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

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

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

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). Если платформа не поддерживает копирование с разделяемой записью, операция завершится ошибкой.

const {
  promises: fsPromises,
  constants: {
    COPYFILE_EXCL
  }
} = require('fs');

// destination.txt will be created or overwritten by default.
fsPromises.copyFile('source.txt', 'destination.txt')
  .then(() => console.log('source.txt was copied to destination.txt'))
  .catch(() => console.log('The file could not be copied'));

// By using COPYFILE_EXCL, the operation will fail if destination.txt exists.
fsPromises.copyFile('source.txt', 'destination.txt', COPYFILE_EXCL)
  .then(() => console.log('source.txt was copied to destination.txt'))
  .catch(() => console.log('The file could not be copied'));

fsPromises.lchmod(path, mode)

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

Изменяет разрешения на символическую ссылку, а затем выполняет Promise без аргументов при успешном выполнении. Этот метод реализован только на macOS.

fsPromises.lchown(path, uid, gid)

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

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

fsPromises.lutimes(path, atime, mtime)

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

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

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

fsPromises.link(existingPath, newPath)

• existingPath <строка> | <Буфер> | <URL>
• newPath <строка> | <Буфер> | <URL>
• Возвращает: <Promise>

Асинхронная link(2). Promise выполняется без аргументов при успешном выполнении.

fsPromises.lstat(path[, options])

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

Асинхронная lstat(2). Promise выполняется с объектом fs.Stats для заданной символической ссылки path.

fsPromises.mkdir(path[, options])

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

Асинхронно создает директорию, а затем выполняет Promise либо без аргументов, либо с первым созданным путем к директории, если recursive имеет значение true.

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

fsPromises.mkdtemp(prefix[, options])

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

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

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

fsPromises.mkdtemp(path.join(os.tmpdir(), 'foo-'))
  .catch(console.error);

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

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

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

Асинхронное открытие файла, которое возвращает Promise, который, при выполнении, возвращает объект FileHandle. См. open(2).

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

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

fsPromises.opendir(path[, options])

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

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

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

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

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

const fs = require('fs');

async function print(path) {
  const dir = await fs.promises.opendir(path);
  for await (const dirent of dir) {
    console.log(dirent.name);
  }
}
print('./').catch(console.error);

fsPromises.readdir(path[, options])

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

Считывает содержимое каталога, а затем выполняет Promise с массивом имён файлов в каталоге, исключая '.' и '..'.

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

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

const fs = require('fs');

async function print(path) {
  const files = await fs.promises.readdir(path);
  for (const file of files) {
    console.log(file);
  }
}
print('./').catch(console.error);

fsPromises.readFile(path[, options])

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

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

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

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

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

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

const controller = new AbortController();
const signal = controller.signal;
readFile(fileName, { signal }).then((file) => { /* ... */ });
// Abort the request
controller.abort();

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

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

fsPromises.readlink(path[, options])

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

Асинхронная readlink(2). Promise выполняется с linkString при успехе.

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

fsPromises.realpath(path[, options])

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

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