Membaca Referensi API

Halaman referensi API Node.js terasa padat pada kunjungan pertama: judul penuh tanda kurung, tabel kecil bertumpuk, dan kata Stability yang muncul di mana-mana. Padatnya bukan tanpa alasan — satu entri harus memuat kontrak lengkap sebuah API supaya pembaca tidak perlu menebak perilakunya. Begitu anatomi satu entri dikuasai, seluruh halaman referensi lain terbaca dengan pola yang sama, karena formatnya seragam dari fs sampai http. Chapter ini membedah satu entri nyata — fsPromises.readFile — bagian demi bagian, lalu melengkapi kita dengan indeks stabilitas dan tabel History sebagai alat baca cepat.

Anatomi Sebuah Entri API #

Kita pakai entri fsPromises.readFile(path[, options]) pada dokumentasi garis 24 sebagai contoh. Entri tersebut menyimpan seluruh kontrak function ini, dan tiap bagiannya punya peran tetap:

Judul entri sekaligus adalah tautan: arahkan kursor ke judulnya, lalu simbol # akan muncul di sisinya dengan alamat seperti fs.html#fspromisesreadfilepath-options. Alamat berpagar itulah yang bisa kita bagikan atau simpan sebagai penanda menuju entri yang persis — jauh lebih presisi daripada membagikan halaman fs.html utuh yang memuat ratusan entri lain.

Notasi pada Signature #

Signature memakai tiga notasi ringkas yang perlu dikenali sekali saja:

Notasi ini menjelaskan mengapa demo pada Section Filesystem kerap memanggil readFile dalam dua bentuk: readFile(path) saat isi berkas cukup dikonsumsi sebagai Buffer, dan readFile(path, { encoding: "utf8" }) saat hasilnya perlu langsung berupa string. Keduanya sah menurut signature yang sama.

Dari Dokumentasi ke Kode #

Membaca entri akan makin melekat jika langsung diuji. Berkas baca-tugas.mjs berikut menjalankan fsPromises.readFile sesuai kontraknya — sekali pada jalur sukses dengan options berisi encoding, sekali pada jalur gagal karena path salah ketik:

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

// Skenario sukses: path valid, options berisi encoding "utf8"
const isi = await readFile("catatan.txt", { encoding: "utf8" });
console.log(`isi catatan : ${isi.trim()}`);

// Skenario gagal: path salah ketik sehingga berkas tidak ditemukan
try {
  await readFile("catata.txt", { encoding: "utf8" });
} catch (e) {
  console.log(`kode error  : ${e.code}`);
}

Output yang Dihasilkan:

isi catatan : Belajar membaca dokumentasi API resmi.
kode error  : ENOENT

Mari kita telaah baris-baris kode di atas:

1. Baris 1 (import): readFile diimpor dari node:fs/promises — entri yang kita baca memang berada pada bagian Promises API halaman fs, berbeda dengan varian callback-nya yang berada di bagian Callback API.
2. Baris 4 (options sebagai object): pemanggilan mengikuti signature readFile(path[, options]); opsi encoding: "utf8" membuat promise terpenuhi dengan string alih-alih Buffer.
3. Baris 8-11 (try...catch): jalur gagal tetap ditangani eksplisit, dan yang dicetak hanya e.code — kode ENOENT inilah yang bisa dicari langsung di halaman errors dokumentasi ketika maknanya belum jelas.

Indeks Stabilitas #

Sebagian entri memuat baris seperti Stability: 2 - Stable atau Stability: 1.1 - Active development. Indeks ini menandakan seberapa kokoh komitmen API tersebut untuk tidak berubah. Makna tiap angkatannya tercantum pada indeks stabilitas resmi :

Tabel History sebagai Alat Kompatibilitas #

Tabel History pada tiap entri mencatat kapan sebuah perilaku ditambahkan atau diubah, disusun dari yang terbaru. Entri fsPromises.readFile pada dokumentasi garis 24, misalnya, mencatat bahwa opsi buffer baru hadir di v24.19.0 dan signal sejak v15.2.0 — dua angka yang langsung memberi tahu versi minimum bila kita ingin memakai opsi tersebut. Karena itu tabel ini adalah alat bantu utama saat menulis kode yang harus berjalan pada beberapa versi Node.js sekaligus; matriks ringkasnya untuk seluruh fitur Course ini kita susun di Chapter Referensi Kompatibilitas.

Anatomi entri API kini bukan lagi halaman yang asing: signature, tipe, opsi, nilai balik, stabilitas, dan riwayatnya masing-masing punya tempat yang jelas. Sisa kendala saat membaca dokumentasi biasanya bukan strukturnya, melainkan istilah yang bertaburan di dalamnya — dari event loop sampai middleware — dan daftar lengkapnya sudah kita kumpulkan di Chapter Glosarium.