fs.watch în Node.js

import { watch } from "node:fs/promises";
for await (const { eventType, filename } of watch(cale, { recursive, signal })) { ... }

Ce face fs.watch

watch din node:fs/promises întoarce un iterator asincron: îl parcurgi cu for await și primești câte un obiect pentru fiecare schimbare, cu eventType ("rename" sau "change") și filename (numele fișierului afectat). "rename" apare când un fișier apare sau dispare, "change" când i se modifică conținutul.

Bucla nu se termină singură. O oprești cu un AbortController: dai signal în opțiuni și apelezi abort(); iteratorul aruncă atunci o eroare cu name === "AbortError", pe care o tratezi.

Comportamentul depinde de sistemul de operare: același salvat dintr-un editor poate produce unul sau mai multe evenimente, iar filename poate lipsi pe unele sisteme. Pentru repornirea automată a unui script folosește direct node --watch.

Parametri

Parametru	Descriere
cale	Fișierul sau directorul urmărit.
recursive	Urmărește și subdirectoarele (macOS, Windows, Linux). Implicit false.
signal	Un AbortSignal care oprește urmărirea.
persistent	Dacă procesul rămâne pornit cât timp urmărește. Implicit true.
encoding	Codificarea pentru filename. Implicit "utf8".

Ce returnează

Un iterator asincron de obiecte { eventType, filename }.

Exemple

Exemplul 1: Primul fișier nou dintr-un director

Urmărirea pornește, apoi după 100 ms se creează un fișier. La primul eveniment bucla se oprește prin abort().

import { watch, writeFile } from "node:fs/promises";

const control = new AbortController();
const urmarire = watch(".", { signal: control.signal });

setTimeout(() => writeFile("comenzi.csv", "id,client\n1,Ana\n"), 100);

try {
  for await (const eveniment of urmarire) {
    console.log("Fișier nou sau modificat:", eveniment.filename);
    control.abort();
  }
} catch (eroare) {
  if (eroare.name !== "AbortError") throw eroare;
  console.log("Urmărire oprită");
}

Rezultat

Fișier nou sau modificat: comenzi.csv
Urmărire oprită

Exemplul 2: Reîncărcarea configurării la fiecare salvare

Tipar folosit în aplicații: când se schimbă config.json, îl citești din nou. Scriptul rulează până la Ctrl+C; ieșirea de mai jos apare după două salvări din editor.

import { watch, readFile } from "node:fs/promises";

async function citesteConfig() {
  return JSON.parse(await readFile("config.json", "utf8"));
}

let config = await citesteConfig();
console.log("Pornit cu tema:", config.tema);

for await (const { eventType } of watch("config.json")) {
  if (eventType !== "change") continue;
  try {
    config = await citesteConfig();
    console.log("Configurare reîncărcată, tema:", config.tema);
  } catch {
    console.log("config.json incomplet, aștept următoarea salvare");
  }
}

Ieșire în terminal

Pornit cu tema: luminoasă
Configurare reîncărcată, tema: întunecată
Configurare reîncărcată, tema: întunecată
Configurare reîncărcată, tema: albastră

Greșeli frecvente

• Te aștepți la exact un eveniment pentru o salvare. Editoarele scriu adesea fișierul în mai mulți pași, așa că primești două sau trei evenimente: grupează-le (de exemplu, reacționează o singură dată la 100 ms) sau verifică dacă s-a schimbat conținutul.
• Nu tratezi AbortError după abort() și programul se termină cu eroare.
• Urmărești un fișier pe care editorul îl înlocuiește (salvare prin fișier temporar + redenumire): după prima salvare urmărirea poate rămâne pe fișierul vechi. Urmărește directorul și filtrează după filename.

Comenzi înrudite

• node --watch: Repornește automat scriptul când salvezi fișierul sau unul dintre modulele importate, fără nodemon.
• fs.readFile: Citește tot conținutul unui fișier: ca text dacă dai codificarea („utf8”), altfel ca Buffer cu octeții bruți.
• fs.stat / fs.access / existsSync: Află informații despre un fișier (tip, mărime, date), verifică dacă există și dacă poate fi citit sau scris.
• EventEmitter (node:events): Clasa pentru evenimente din Node.js: înregistrezi ascultători cu on și îi declanșezi cu emit. Baza pentru stream-uri și servere.