re:re:actable
Урок 013 минуты чтения

fs и fs-promises - синхронные и асинхронные операции

На этой странице
Кратко

fs - встроенный модуль Node.js для работы с файловой системой: файлами, папками, правами, метаданными и потоками чтения/записи. fs/promises - promise-версия этого API, которую удобно использовать вместе с async/await.

Синхронные операции fs блокируют выполнение JavaScript до завершения работы с диском. Асинхронные операции отдают задачу Node.js и позволяют event loop продолжать обрабатывать другие события.

Вопрос

Что такое fs и fs/promises и чем синхронные операции отличаются от асинхронных?

Главное определение

В браузере JavaScript не имеет прямого доступа к диску пользователя. В Node.js такой доступ есть через модуль node:fs.

У fs есть несколько стилей API:

СтильПримерКогда использовать
Callback APIfs.readFile(path, cb)В старом коде и библиотеках
Promise APIawait fs.readFile(path) из node:fs/promisesВ современном приложении
Sync APIfs.readFileSync(path)В CLI, скриптах и при старте приложения
Stream APIfs.createReadStream(path)Для больших файлов

Пример чтения файла

import { readFile } from 'node:fs/promises';
 
const text = await readFile('notes.txt', 'utf8');
 
console.log(text);

Если не указать 'utf8', Node вернет Buffer, а не строку.

const data = await readFile('image.png');
 
console.log(Buffer.isBuffer(data)); // true

Почему лучше начинать с fs/promises?

fs/promises проще читать, легче комбинируется с try/catch и не создает вложенность callback-функций.

import { writeFile } from 'node:fs/promises';
 
try {
  await writeFile('result.txt', 'Готово', 'utf8');
  console.log('Файл записан');
} catch (error) {
  console.error('Не удалось записать файл:', error.message);
}

Sync и async: что блокирует event loop

В Node.js один основной поток выполняет JavaScript-код. Если вызвать синхронную операцию, этот поток будет ждать диск.

import { readFileSync } from 'node:fs';
 
const config = readFileSync('config.json', 'utf8');
console.log(config);

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

Асинхронная версия не блокирует основной поток:

import { readFile } from 'node:fs/promises';
 
const config = await readFile('config.json', 'utf8');
console.log(config);

await приостанавливает текущую async-функцию, но не весь Node.js-процесс.

Когда sync API допустим?

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

  • чтение конфига при запуске;
  • одноразовый скрипт миграции;
  • CLI-утилита;
  • генерация файлов в build step.

На HTTP-сервере в обработчике запроса sync API обычно считается плохой практикой.

import { readFileSync } from 'node:fs';
import http from 'node:http';
 
http.createServer((req, res) => {
  const page = readFileSync('index.html', 'utf8'); // блокирует все запросы
  res.end(page);
});

Собеседовательный нюанс

Асинхронность в fs не означает, что файл читается самим JavaScript. Node.js использует возможности ОС и libuv, а часть операций может выполняться через thread pool.

Что важно помнить

  • Sync-методы блокируют event loop — в обработчиках запросов их не используют.
  • readFile читает файл целиком в память; для больших файлов нужны streams.
  • Ошибки fs содержат code: ENOENT (нет файла), EACCES (нет прав), EEXIST.
  • mkdir(path, { recursive: true }) и rm(path, { recursive: true, force: true }) удобны для работы с папками.

Мини-шпаргалка

  • node:fs - базовый модуль файловой системы.
  • node:fs/promises - современный promise-интерфейс.
  • readFile читает файл целиком в память.
  • writeFile создает или перезаписывает файл.
  • Для больших файлов лучше использовать streams.
  • Sync API блокирует event loop.
  • Async API лучше для серверов.
  • Sync API допустим при старте приложения и в простых скриптах.
  • await не блокирует весь процесс.
  • В обработчиках HTTP-запросов избегай readFileSync.

Документация

Node.js: File system, Node.js: fs Promises API.

Дочитали до конца?
Отметьте урок — прогресс сохранится в браузере.

Поиск

Поиск по урокам