Node.js: fayl sistemi və axınlar

Node.js-də fayllarla işləmək: `fs/promises` ilə oxuma, yazma və qovluqlar, `node:path` ilə hər sistemdə düzgün yollar, `ENOENT` kimi xəta kodları və axınlar — `pipeline`, gzip və böyük log faylının `readline` ilə sətir-sətir oxunması.

  • İrəli
  • 25 dəq
  • 12 sual
  • 39 dərsdən 34-cüsü

Bu dərsdə öyrənəcəksən

  • fs/promises ilə faylları oxumaq, yazmaq, sonuna əlavə etmək, qovluqları idarə etmək və xətaları code sahəsinə görə emal etmək
  • Yolları sətirləri yapışdırmaqla deyil, node:path və import.meta.dirname ilə qurmaq
  • Axınların yaddaşa niyə qənaət etdiyini izah etmək və onları stream.pipeline ilə təhlükəsiz birləşdirmək
  • Böyük faylı readline ilə sətir-sətir emal edib log hesabatı hazırlamaq

Veb server hər sorğunu log faylına yazır. Bir aydan sonra fayl 2 GB olur. Onu readFile ilə açsanız, Node.js bütün 2 GB-ı birdən yaddaşa yerləşdirməyə çalışacaq — proqram ləngiyəcək və ya çökəcək. «Node.js əsasları» dərsində qeydləri readFile və writeFile ilə saxladıq; kiçik fayllar üçün bu düzgündür. Bu dərsdə bütün fs/promises alət dəstini, hər sistemdə işləyən yolları, xəta kodlarını və axınları öyrənəcəksiniz: axın məlumatı hissə-hissə emal edir, ona görə 2 GB-lıq fayl da eyni anda yaddaşda cəmi bir neçə on kilobayt tutur.

fs/promises: faylları oxumaq və yazmaq

node:fs/promises modulu fayl funksiyalarının Promise qaytaran versiyalarını verir, ona görə onları await ilə çağırırıq (bax: «Asinxron JavaScript: callback, Promise, async/await»). Ən çox lazım olan üçü: writeFile(yol, məlumat) faylı yaradır və ya məzmununu tamamilə əvəz edir, appendFile sonuna əlavə edir, readFile(yol, 'utf8') isə məzmunu sətir kimi qaytarır. Kodlaşdırma ('utf8') verilməsə, readFile Buffer — xam baytlar qaytarır.

BufferTərif

Node.js-in xam ikili məlumat tipi: sabit uzunluqlu baytlar (0–255) ardıcıllığı. Fayllar, şəbəkə paketləri və şəkillər Buffer kimi gəlir; buffer.toString('utf8') baytları mətnə, Buffer.from(mətn) isə mətni baytlara çevirir.

JavaScript
// files.mjs
import { writeFile, appendFile, readFile } from 'node:fs/promises';

await writeFile('greeting.txt', 'Salam, dünya!\n');
await appendFile('greeting.txt', 'Hello, world!\n');

const text = await readFile('greeting.txt', 'utf8');
console.log(JSON.stringify(text));
console.log('characters:', text.length);

const bytes = await readFile('greeting.txt');
console.log('bytes:', bytes.length);
console.log(bytes.subarray(0, 10));
console.log(bytes.subarray(0, 10).toString('utf8'));
console.log(bytes.subarray(0, 9).toString('utf8'));

Gözlənilən nəticə

"Salam, dünya!\nHello, world!\n"
characters: 28
bytes: 29
<Buffer 53 61 6c 61 6d 2c 20 64 c3 bc>
Salam, dü
Salam, d�
Boş qovluqda node files.mjs ilə işə salın. UTF-8-də ü hərfi 2 bayt tutur, ona görə faylda 28 simvol, amma 29 bayt var. Baytları 9-cudan sonra kəsəndə ü yarıya bölünür və qırıq bayt � kimi görünür.

Hər funksiyanın node:fs modulunda sinxron əkizi də var: readFileSync, writeFileSync. Onlar disk cavab verənə qədər hadisə dövrünü bloklayır. Qısa skriptdə və ya proqram başlayanda bu qorxulu deyil, serverdə isə bir yavaş oxuma bütün istifadəçiləri dondurur (bax: «Hadisə dövrü və paralel işlər»). Köhnə kodda callback üslubu da görəcəksiniz: fs.readFile(yol, (err, data) => …).

FunksiyaNə edirQeyd
readFile(p, 'utf8')bütün faylı oxuyurkodlaşdırmasız — Buffer
writeFile(p, data)yaradır və ya üzərinə yazır{ flag: 'wx' } — fayl varsa EEXIST
appendFile(p, data)sonuna əlavə edirfayl yoxdursa, yaradır
mkdir(p, { recursive: true })qovluğu bütün valideynləri ilə yaradırqovluq varsa, xəta yoxdur
readdir(p, { withFileTypes: true })qovluğun siyahısıisFile(), isDirectory() olan Dirent
stat(p)fayl haqqında məlumatsize, mtime, isFile()
rm(p, { recursive: true, force: true })faylı və ya bütün ağacı silirgeri qaytarmaq olmur!

Davamını oxumaq üçün pulsuz qeydiyyatdan keç

Dərsin qalan bölmələri, test və qeydlər Educora hesabı ilə açılır. Qeydiyyat bir dəqiqə çəkir; irəliləyişin bütün cihazlarında saxlanılır.

Qovluqlar, fayl məlumatı və xəta kodları

Fayl əməliyyatı alınmayanda Node.js qısa kodu olan xəta atır. Mesajı deyil, error.code sahəsini yoxlayın: mesaj dəyişə bilər, kod dəyişmir. Ən çox rast gəlinənlər: ENOENT — belə fayl və ya qovluq yoxdur; EEXIST — artıq mövcuddur; EACCES və EPERM — icazə yoxdur; EISDIR — fayl gözlənilən yerdə qovluq verilib; ENOTEMPTY — qovluq boş deyil.

JavaScript
// folders.mjs
import { mkdtemp, mkdir, writeFile, readdir, stat, readFile, rm } from 'node:fs/promises';
import path from 'node:path';
import os from 'node:os';

const root = await mkdtemp(path.join(os.tmpdir(), 'demo-'));
await mkdir(path.join(root, 'reports', '2026'), { recursive: true });
await writeFile(path.join(root, 'notes.txt'), 'buy bread');
await writeFile(path.join(root, 'reports', '2026', 'oct.csv'), 'day,sales\n1,40\n');

for (const entry of await readdir(root, { withFileTypes: true })) {
  const info = await stat(path.join(root, entry.name));
  console.log(info.isFile() ? `${entry.name} (${info.size} B)` : `${entry.name}/`);
}

try {
  await readFile(path.join(root, 'missing.txt'), 'utf8');
} catch (error) {
  console.log(error.code, error.syscall);
}
try {
  await mkdir(path.join(root, 'reports'));
} catch (error) {
  console.log(error.code, error.syscall);
}
await rm(root, { recursive: true, force: true });
await stat(root).catch((error) => console.log('after rm:', error.code));

Gözlənilən nəticə

notes.txt (9 B)
reports/
ENOENT open
EEXIST mkdir
after rm: ENOENT
mkdtemp sistemin müvəqqəti qovluğunda unikal qovluq yaradır (məsələn, demo-a1B2c3), ona görə nümunə sizin fayllarınıza toxunmur. { recursive: true } reports və 2026 qovluqlarını bir çağırışla yaratdı. Sonda rm bütün ağacı silir, stat isə bunu ENOENT ilə təsdiqləyir.

Yollar: node:path və import.meta.dirname

Windows qovluqları \ ilə, Linux və macOS isə / ilə ayırır. path.join düzgün ayırıcını qoyur, .. hissələrini və artıq ayırıcıları təmizləyir. basename, extname və dirname yolu hissələrə bölür, path.parse bütün hissələri birdən qaytarır, path.relative isə bir yoldan digərinə necə getməyi göstərir.

JavaScript
// paths.mjs
import path from 'node:path';

const file = path.join('data', 'logs', '..', 'reports', 'oct.csv');
console.log(file);
console.log(path.basename(file), path.extname(file), path.basename(file, '.csv'));
console.log(path.dirname(file));
console.log(path.parse('/srv/app/server.mjs'));
console.log(path.isAbsolute('data/oct.csv'), path.isAbsolute('/srv/app'));
console.log(path.relative('/srv/app', '/srv/app/public/index.html'));
console.log(import.meta.dirname === path.dirname(import.meta.filename));

Gözlənilən nəticə

data\reports\oct.csv
oct.csv .csv oct
data\reports
{
  root: '/',
  dir: '/srv/app',
  base: 'server.mjs',
  ext: '.mjs',
  name: 'server'
}
false true
public\index.html
true
Çıxış Windows-dadır. Linux və macOS-da birinci sətir data/reports/oct.csv, path.relative isə public/index.html olur. Son sətir: import.meta.dirname faylın öz qovluğudur.

Ən vacib məqam: 'data.json' kimi nisbi yol skriptin qovluğuna görə deyil, process.cwd()-yə — node-u işə saldığınız qovluğa görə açılır. Eyni skript bir qovluqdan işə salınanda faylı tapır, başqasından isə ENOENT verir. Skriptin yanındakı faylları onun öz qovluğundan qurun: path.join(import.meta.dirname, 'data.json'). import.meta.dirname və import.meta.filename ES modullarında Node.js 20.11-dən var; CommonJS-də onlar __dirname və __filename adlanır.

Necə işə salınıbprocess.cwd()path.resolve('data.json')path.join(import.meta.dirname, 'data.json')
cd app && node scripts/report.mjsappapp/data.jsonapp/scripts/data.json
cd app/scripts && node report.mjsapp/scriptsapp/scripts/data.jsonapp/scripts/data.json
app/scripts/report.mjs skripti iki fərqli qovluqdan işə salınıb (yollar qısaldılıb). Yalnız sonuncu sütun hər dəfə eynidir.

Axınlar: məlumat hissə-hissə

readFile hər şeyi birdən yükləyir. Axın (stream) isə məlumatı hissələrlə (chunk) verir: faylı oxuyan axın hər dəfə 64 KiB qaytarır, siz hissəni emal edib unudursunuz və faylın ölçüsü nə olursa olsun, yaddaş kiçik və sabit qalır. Node.js-də axınlar hər yerdədir: fayllar, HTTP sorğu və cavabları, process.stdin, sıxılma.

NövMənasıNümunələr
Readableondan oxuyursunuzfs.createReadStream, process.stdin, HTTP request
Writableona yazırsınızfs.createWriteStream, process.stdout, HTTP response
Transformkeçən məlumatı dəyişirzlib.createGzip()
Duplexhər iki istiqamətdəşəbəkə soketi

Oxunan axın hadisə yayıcısıdır (ətraflı: «Node.js: hadisələr, proses və komanda sətri alətləri»): hər hissə üçün data, məlumat bitəndə end, xəta olanda error hadisəsini yayır. Onu for await (const chunk of stream) ilə də oxumaq olar — çox vaxt bu daha sadədir.

JavaScript
// chunks.mjs
import { createReadStream } from 'node:fs';
import { writeFile } from 'node:fs/promises';

await writeFile('big.txt', 'x'.repeat(1_000_000));

const stream = createReadStream('big.txt');
console.log('chunk size limit:', stream.readableHighWaterMark);

let chunks = 0;
let bytes = 0;
stream.on('data', (chunk) => {
  chunks++;
  bytes += chunk.length;
});
stream.on('end', () => console.log(`end: ${chunks} chunks, ${bytes} bytes`));
stream.on('error', (error) => console.log('error:', error.code));

const missing = createReadStream('no-such-file.txt');
missing.on('error', (error) => console.log('error:', error.code));

Gözlənilən nəticə

chunk size limit: 65536
error: ENOENT
end: 16 chunks, 1000000 bytes
1 000 000 bayt = 65 536 baytlıq 15 tam hissə + 16 960 baytlıq bir hissə. Olmayan faylın error hadisəsi daha tez gəldi: iki axın eyni vaxtda işləyir, açmağın alınmaması isə 16 oxumadan tez bilinir. error dinləyicisi olmasaydı, bu xəta proqramı dayandırardı.

Yazmanın problemi əksinədir. write() məlumatı axının buferinə qoyur və bufer dolanda (fayllar üçün standart olaraq 16 KiB) false qaytarır — disk sizin dövrünüzdən yavaşdır. Buna baxmayaraq yazmağa davam etsəniz, yaddaş böyüyür; buna backpressure-ə (əks təzyiqə) məhəl qoymamaq deyilir. Həll: write() false qaytaranda drain hadisəsini gözləyin.

JavaScript
// write-log.mjs
import { createWriteStream } from 'node:fs';
import { once } from 'node:events';

const out = createWriteStream('access.log');
let waits = 0;
for (let i = 1; i <= 100_000; i++) {
  const level = i % 25 === 0 ? 'ERROR' : 'INFO';
  const ok = out.write(`2026-10-03 ${level} GET /api/items/${i % 40}\n`);
  if (!ok) {
    waits++;
    await once(out, 'drain');
  }
}
out.end();
await once(out, 'finish');
console.log('bytes written:', out.bytesWritten);
console.log('waited for drain:', waits, 'times');

Gözlənilən nəticə

bytes written: 3379000
waited for drain: 206 times
100 000 sətir, 3 379 000 bayt; dövr disk çatdırana qədər 206 dəfə dayandı. once(out, 'finish') bütün məlumat diskə yazılandan sonra yerinə yetirilir.

Axınları əl ilə birləşdirmək səhvlərə açıqdır: ortadakı axın xəta versə, qalanlarını da bağlamaq lazımdır. node:stream/promises modulundan pipeline istənilən sayda axını birləşdirir, backpressure-i özü idarə edir, xətada hamısını bağlayır və Promise qaytarır. Addım async function* generatoru da ola bilər: o, əvvəlki axını alır və hissələri yield edir — öz çevirmə (transform) addımınızı yazmağın ən sadə yolu.

JavaScript
// gzip.mjs
import { createReadStream, createWriteStream } from 'node:fs';
import { stat } from 'node:fs/promises';
import { pipeline } from 'node:stream/promises';
import { createGzip } from 'node:zlib';

let passed = 0;
async function* countBytes(source) {
  for await (const chunk of source) {
    passed += chunk.length;
    yield chunk;
  }
}

await pipeline(
  createReadStream('access.log'),
  countBytes,
  createGzip(),
  createWriteStream('access.log.gz'),
);
const { size } = await stat('access.log.gz');
console.log(`read ${passed} bytes, wrote ${size} bytes`);
console.log(`compressed to ${(size / passed * 100).toFixed(1)}%`);

await pipeline(createReadStream('missing.log'), createGzip(), createWriteStream('x.gz'))
  .catch((error) => console.log('pipeline failed:', error.code));

Gözlənilən nəticə

read 3379000 bytes, wrote 27272 bytes
compressed to 0.8%
pipeline failed: ENOENT
Təkrarlanan sözlərlə dolu log 1 %-dən də az yer tutdu. Mənbə fayl olmayanda pipeline ENOENT ilə rədd edilir və digər axınları bağlayır, amma createWriteStream boş x.gz faylını artıq yaradıb — real kodda yarımçıq faylı silin.

Böyük fayl sətir-sətir: log hesabatı layihəsi

Loglar, CSV ixracları və JSON Lines faylları sətir-sətir emal olunur. Hissələr sətirlərə fikir vermir: bir hissə sətrin ortasında bitə bilər. node:readline modulu parçaları toplayıb sizə tam sətirlər verir; for await ilə dövr növbəti sətri yalnız siz hazır olanda oxuyur. crlfDelay: Infinity Windows sətir sonlarını (\r\n) bir keçid kimi sayır.

  1. Müvəqqəti qovluq

    mkdtemp ilə unikal qovluq yaradın ki, layihə sizin fayllarınıza toxunmasın.

  2. Nümunə log

    Ora vaxt səviyyə metod yol status müddət formatında bir neçə sətir yazın.

  3. Sətir-sətir statistika

    readline ilə oxuyun və sayğacları yığın: sətir sayı, səviyyələr, orta müddət, ən yavaş sorğu, ən çox çağırılan yol.

  4. Hesabat və təmizlik

    Nəticəni JSON kimi saxlayın, qovluğu isə finally blokunda silin — hansısa addım xəta versə belə.

JavaScript
// summarize.mjs
import { createReadStream } from 'node:fs';
import { createInterface } from 'node:readline';

export async function summarize(file) {
  const lines = createInterface({ input: createReadStream(file), crlfDelay: Infinity });
  const levels = {};
  const paths = new Map();
  let total = 0;
  let totalMs = 0;
  let slowest = { ms: 0, request: '' };

  for await (const line of lines) {
    if (!line.trim()) continue;
    const [, level, method, url, , duration] = line.split(' ');
    const ms = parseInt(duration, 10);
    total++;
    totalMs += ms;
    levels[level] = (levels[level] ?? 0) + 1;
    paths.set(url, (paths.get(url) ?? 0) + 1);
    if (ms > slowest.ms) slowest = { ms, request: `${method} ${url}` };
  }
  const [topPath] = [...paths].sort((a, b) => b[1] - a[1]);
  return { total, levels, avgMs: Math.round(totalMs / total), slowest, topPath };
}
line.split(' ') [vaxt, səviyyə, metod, url, status, müddət] verir; destrukturlaşdırmadakı boş yerlər vaxtı və statusu ötürür. parseInt('35ms', 10) ədədi oxuyur və m hərfində dayanır. Yaddaşda yalnız bir sətir və sayğaclar saxlanılır — fayl gigabaytlarla ola bilər.
JavaScript
// report.mjs
import { mkdtemp, writeFile, readFile, rm } from 'node:fs/promises';
import path from 'node:path';
import os from 'node:os';
import { summarize } from './summarize.mjs';

const dir = await mkdtemp(path.join(os.tmpdir(), 'logs-'));
try {
  const logFile = path.join(dir, 'app.log');
  await writeFile(logFile, [
    '2026-10-03T09:00:01Z INFO GET /api/products 200 35ms',
    '2026-10-03T09:00:02Z INFO GET /api/products 200 41ms',
    '2026-10-03T09:00:04Z WARN POST /api/orders 400 12ms',
    '2026-10-03T09:00:05Z INFO GET /api/users/7 200 28ms',
    '2026-10-03T09:00:09Z ERROR POST /api/orders 500 1203ms',
    '2026-10-03T09:00:12Z INFO GET /api/products 200 37ms',
    '',
  ].join('\n'));

  const report = await summarize(logFile);
  await writeFile(path.join(dir, 'report.json'), JSON.stringify(report, null, 2));
  console.log(await readFile(path.join(dir, 'report.json'), 'utf8'));
} finally {
  await rm(dir, { recursive: true, force: true });
}

Gözlənilən nəticə

{
  "total": 6,
  "levels": {
    "INFO": 4,
    "WARN": 1,
    "ERROR": 1
  },
  "avgMs": 226,
  "slowest": {
    "ms": 1203,
    "request": "POST /api/orders"
  },
  "topPath": [
    "/api/products",
    3
  ]
}
Orta müddət: (35 + 41 + 12 + 28 + 1203 + 37) / 6 = 1356 / 6 = 226 ms. finally bloku summarize xəta atsa belə müvəqqəti qovluğu silir.

Tapşırıq

Axın mətni sətirlərə baxmadan hissələrə bölür. splitLines(chunks) generatorunu yazın: hissənin bitməmiş sonunu rest-də saxlasın, onu növbəti hissəyə yapışdırsın və yalnız tam sətirləri yield etsin; sonda qalan parça da verilsin. readline içəridə məhz bunu edir.

Tapşırıq · JavaScript
const chunks = ['INFO sta', 'rt\nERROR db do', 'wn\nINFO ok\nWA', 'RN slow disk'];

function* splitLines(chunks) {
  let rest = '';
  // glue rest + chunk, split by '\n', keep the last part in rest
}

let n = 0;
for (const line of splitLines(chunks)) {
  n++;
  console.log(`${n}: ${line}`);
}
Gözlənilən nəticə
1: INFO start
2: ERROR db down
3: INFO ok
4: WARN slow disk

Tapşırıq

Log hesabatının məntiqini fayl olmadan yoxlayaq. countLevels(lines) hər səviyyənin sayını obyekt kimi, slowRequests(lines, limitMs) isə müddəti limitMs-dən çox olan sorğuları METOD /yol sətirləri kimi qaytarsın. Boş sətirləri ötürün.

Tapşırıq · JavaScript
const log = [
  '09:00:01 INFO GET /api/products 35ms',
  '09:00:04 WARN POST /api/orders 12ms',
  '09:00:09 ERROR POST /api/orders 1203ms',
  '',
  '09:00:12 INFO GET /api/products 37ms',
];

function countLevels(lines) {
  // { INFO: 2, ... }
}

function slowRequests(lines, limitMs) {
  // ['POST /api/orders', ...]
}

console.log(JSON.stringify(countLevels(log)));
console.log(slowRequests(log, 100));
console.log(slowRequests(log, 30).length);
Gözlənilən nəticə
{"INFO":2,"WARN":1,"ERROR":1}
[ 'POST /api/orders' ]
3

Yadda saxla

  • fs/promises + await: readFile, writeFile (üzərinə yazır), appendFile, mkdir({ recursive: true }), readdir, stat, rm; kodlaşdırmasız readFile Buffer qaytarır.
  • Xətaları error.code ilə ayırın: ENOENT, EEXIST, EACCES, EISDIR. Əvvəlcə yoxlamayın — edin və tutun.
  • Yolları path.join və import.meta.dirname ilə qurun; nisbi yol process.cwd()-dən asılıdır.
  • Axın məlumatı hissələrlə verir (fayl oxuyanda 64 KiB), yaddaş kiçik qalır; write() false qaytarırsa, drain-i gözləyin.
  • Axınları pipeline ilə birləşdirin (xətalar və backpressure həll olunur), böyük mətn fayllarını isə readline + for await ilə sətir-sətir oxuyun.
Dərsdə səhv və ya qeyri-dəqiqlik gördün?

Özünü yoxla

12 sual. Hər düzgün cavab XP qazandırır.

Sual 1 / 12

Sual 1 / 12. const data = await readFile('photo.png'); — data nədir?