Metadata Berkas

Kadang kita tidak butuh isi berkas, melainkan keterangan tentang berkas itu sendiri: berapa ukurannya untuk memvalidasi unggahan, apakah sebuah path adalah berkas atau direktori sebelum diproses, kapan terakhir diubah untuk keperluan sinkronisasi. Keterangan semacam ini disebut metadata, dan stat dari node:fs/promises adalah pintu utamanya. Pada chapter ini kita membaca metadata beserta cara mengendalikannya agar hasil program tetap dapat diprediksi, termasuk perbedaan penting antara stat dan lstat ketika berhadapan dengan symbolic link.

Membaca Informasi Berkas dengan stat #

stat menerima satu path dan mengembalikan object Stats: kumpulan informasi yang dicatat sistem operasi tentang berkas tersebut. Contoh berikut menyiapkan berkas uji sendiri, membekukan waktunya, lalu membaca metadatanya.

import { writeFile, utimes, stat, rm } from "node:fs/promises";

// Siapkan berkas uji dengan isi yang selalu sama
await writeFile("berkas-uji.txt", "isi berkas uji");

// Setel waktu berkas ke tanggal tetap agar hasil stat bisa diprediksi
const waktuBeku = new Date("2026-01-15T08:00:00Z");
await utimes("berkas-uji.txt", waktuBeku, waktuBeku);

const info = await stat("berkas-uji.txt");
console.log(`ukuran      : ${info.size} byte`);
console.log(`berkas?     : ${info.isFile()}`);
console.log(`direktori?  : ${info.isDirectory()}`);
console.log(`diubah      : ${info.mtime.toISOString()}`);

await rm("berkas-uji.txt");
console.log("berkas-uji.txt dihapus");

Output yang Dihasilkan:

ukuran      : 14 byte
berkas?     : true
direktori?  : false
diubah      : 2026-01-15T08:00:00.000Z
berkas-uji.txt dihapus

Mari kita telaah baris-baris kode di atas:

1. Baris 4 (writeFile): berkas uji dibuat dengan isi yang selalu sama, sehingga size pada output pasti identik di setiap eksekusi.
2. Baris 7-8 (utimes): waktu akses dan waktu modifikasi berkas disetel ke satu tanggal tetap — 15 Januari 2026 pukul 08:00 UTC. Langkah ini membuat mtime yang dicetak dapat diprediksi; tanpa ini, waktunya adalah momen eksekusi yang berbeda setiap detik. Dalam program nyata, utimes dipakai misalnya untuk menjaga stempel waktu saat memindahkan berkas antar sistem.
3. Baris 10 (stat): object Stats menyimpan seluruh metadata; di sini kita mencetak size dalam satuan byte.
4. Baris 12-13 (isFile/isDirectory): pemeriksaan jenis dikembalikan sebagai boolean — cara paling andal membedakan berkas dari direktori, jauh lebih tepercaya daripada menebak dari ekstensi nama.
5. Baris 14 (mtime.toISOString()): mtime berupa object Date. Method toISOString() selalu mencetak dalam UTC dengan format tetap, sehingga aman untuk log dan perbandingan antar mesin.
6. Baris 16-17 (rm): berkas uji dibersihkan di akhir agar contoh dapat dijalankan berulang dengan hasil yang sama.

stat versus lstat pada Symbolic Link #

Symbolic link adalah berkas khusus yang isinya berupa path menuju berkas lain — semacam jalan pintas. Kehadirannya menciptakan dua pertanyaan berbeda: “informasi apa yang dimiliki tautan ini?” dan “informasi apa yang dimiliki targetnya?” stat menjawab pertanyaan kedua karena mengikuti tautan sampai ke tujuan; lstat menjawab pertanyaan pertama karena memeriksa tautan apa adanya.

import { writeFile, symlink, stat, lstat, rm } from "node:fs/promises";

await writeFile("berkas-asli.txt", "isi berkas asli");

// Buat symbolic link yang menunjuk ke berkas asli
await rm("tautan.txt", { force: true });
await symlink("berkas-asli.txt", "tautan.txt");

// stat mengikuti tautan sampai ke berkas target
const viaStat = await stat("tautan.txt");
console.log(`stat   : isFile=${viaStat.isFile()} isSymbolicLink=${viaStat.isSymbolicLink()}`);

// lstat memeriksa tautan itu sendiri, tanpa mengikuti
const viaLstat = await lstat("tautan.txt");
console.log(`lstat  : isFile=${viaLstat.isFile()} isSymbolicLink=${viaLstat.isSymbolicLink()}`);

await rm("tautan.txt");
await rm("berkas-asli.txt");
console.log("berkas uji dibersihkan");

Output yang Dihasilkan:

stat   : isFile=true isSymbolicLink=false
lstat  : isFile=false isSymbolicLink=true
berkas uji dibersihkan

Hasilnya kontras tegas: stat melaporkan tautan.txt sebagai berkas biasa (karena yang diperiksanya adalah berkas-asli.txt di ujung tautan), sedangkan lstat melaporkannya sebagai symbolic link. Baris 6 memakai rm dengan force: true sebelum symlink agar eksekusi berulang tetap mulus — rm pada symbolic link hanya melepaskan tautan, tidak menyentuh berkas aslinya. Perbedaan ini penting saat menulis program yang menelusuri folder: memakai stat saja membuat tautan diikuti diam-diam, yang bisa berujung pada memproses berkas yang sama dua kali atau terjebak pada tautan melingkar.

Isi Object Stats Lainnya #

Object Stats memuat lebih banyak bidang daripada yang kita cetak di atas. Tabel berikut merangkum yang paling relevan sehari-hari; rujukan lengkapnya ada di dokumentasi class fs.Stats .

Metadata memberi kita potret kondisi berkas pada satu momen. Chapter berikutnya bergerak lebih jauh: bereaksi saat berkas berubah, tanpa harus memeriksa berulang kali sendiri.