File Deklarasi (.d.ts): Tipe untuk Kode Tanpa Tipe

Kamu memasang sebuah paket, menulis satu baris kode yang memakainya, dan TypeScript langsung tahu bentuk dari semua yang dikembalikan paket itu. Nama-nama metodenya muncul otomatis di editor. Kamu langsung diperingatkan kalau salah mengoper angka padahal yang dibutuhkan teks. Rasanya seperti sihir, apalagi kalau paketnya sendiri ditulis dalam JavaScript biasa tanpa tipe sama sekali. Lalu dari mana semua informasi tipe itu datang?

Jawabannya ada di satu jenis file kecil yang namanya agak aneh: file deklarasi, yang berakhiran .d.ts. File ini salah satu bagian terpenting dalam dunia TypeScript, tapi anehnya banyak developer bertahun-tahun tidak pernah menulisnya secara manual. Di artikel ini kita akan membongkar apa sebenarnya file ini, konsep deklarasi “ambient”, kata kunci declare, dan sebuah proyek komunitas besar yang menyediakan tipe untuk ribuan pustaka JavaScript. Begitu selesai membaca, sihir tadi akan terasa jauh lebih masuk akal.

Masalah yang dipecahkan file deklarasi

TypeScript dan JavaScript punya hubungan yang unik. JavaScript adalah bahasa yang benar-benar dijalankan di browser dan server. TypeScript adalah lapisan di atasnya yang menambahkan informasi tipe, dan informasi itu diperiksa saat kamu menulis kode lalu dihapus sebelum kode dijalankan. Browser tidak pernah melihat satu tipe pun.

Di sinilah muncul celahnya. Sangat banyak kode di dunia ini ditulis dalam JavaScript biasa. Pustaka lama, skrip internal, paket yang dirilis sebelum TypeScript populer: semuanya tidak membawa informasi tipe. Ketika kamu memakai kode seperti itu dari proyek TypeScript, TypeScript sama sekali tidak tahu isinya apa. Ia tidak tahu bahwa sebuah fungsi butuh dua argumen, atau bahwa sebuah objek punya properti name. Bagi pemeriksa tipe, kode itu cuma kotak hitam.

File deklarasi adalah cara menjelaskan kotak hitam itu dari luar. Ini file yang isinya hanya informasi tipe tanpa logika yang bisa dijalankan. Tugasnya cuma satu: memberi tahu TypeScript, “ini lho bentuk dari kode JavaScript tersebut” supaya pemeriksa tipe bisa bekerja.

Hanya tipe, bukan perilaku

File .d.ts tidak pernah berisi implementasi nyata dari apa pun. Isinya tanda tangan tipe, bentuk interface, dan deklarasi fungsi. Anggap saja seperti label pada kotak yang tersegel: label itu memberi tahu apa isi di dalam tanpa menjadi isinya.

Apa arti “ambient”

Saat membaca soal file deklarasi, kamu akan sering bertemu kata ambient. Kedengarannya teknis, tapi idenya sebenarnya sederhana.

Biasanya di TypeScript, sebuah tipe ada karena kamu menulis kode yang membuatnya. Kamu mendefinisikan sebuah fungsi, lalu TypeScript menyimpulkan tipenya dari isi fungsi itu. Tipe dan nilai aslinya hidup berdampingan.

Deklarasi ambient berbeda. Ia menjelaskan sebuah nilai atau tipe yang ada di tempat lain, di kode yang tidak bisa dilihat atau diperiksa TypeScript. Kamu tidak sedang membuat apa pun; kamu hanya mengumumkan bahwa sesuatu memang sudah ada di lingkungan sekitarnya. Kata “ambient” pas untuk itu, mirip menjelaskan suhu sebuah ruangan tempat kamu berdiri tapi bukan kamu yang membangunnya.

Contoh klasiknya adalah variabel global yang dimuat ke halaman lewat tag skrip. Variabel itu betul-betul ada saat program berjalan, tapi tidak ada kode TypeScript yang menghasilkannya. Jadi kamu menulis deklarasi ambient untuk memberi tahu compiler tentang variabel itu.

Kata kunci `declare`

Alat yang dipakai untuk menulis deklarasi ambient adalah kata kunci declare. Ini semacam janji kepada TypeScript: “percaya saja, benda ini ada saat program berjalan, walaupun kamu tidak bisa melihat kode yang membuatnya.”

Bayangkan sebuah skrip analitik pihak ketiga menambahkan fungsi global bernama trackEvent ke halaman. Di kode TypeScript kamu ingin memanggilnya tanpa error. Kamu bisa mendeklarasikannya:

// analytics.d.ts
declare function trackEvent(name: string, value: number): void;

Sekarang di mana pun dalam proyekmu kamu bisa memanggil trackEvent("signup", 1) dan TypeScript akan memeriksa argumennya terhadap tanda tangan tadi, walaupun fungsi aslinya ada di skrip eksternal. Perhatikan, tidak ada isi fungsi di situ. Kata kunci declare berarti kamu hanya menjelaskan bentuknya, bukan menyediakan kodenya.

Yang bisa dideklarasikan bukan cuma fungsi. Variabel, kelas, sampai modul utuh semuanya bisa:

// globals.d.ts
declare const APP_VERSION: string;

declare namespace AppConfig {
  const apiUrl: string;
  const timeout: number;
}

Janji yang harus kamu tepati

declare menyuruh TypeScript menganggap sesuatu itu ada, tapi tidak membuatnya benar-benar ada. Kalau kamu mendeklarasikan fungsi yang sebenarnya tidak hadir saat program berjalan, kodemu akan lolos kompilasi dengan mulus lalu error saat dijalankan. Deklarasi itu sebuah deskripsi, bukan jaminan. Pastikan yang kamu deklarasikan memang benar-benar termuat.

Menjelaskan satu modul utuh

Banyak pustaka JavaScript bukan variabel global, melainkan modul yang kamu impor. Untuk menjelaskan modul seperti itu, kamu memakai pola yang sedikit lebih besar bernama deklarasi modul.

Misalkan ada paket JavaScript biasa bernama simple-logger yang tidak punya tipe. Kamu mengimpornya begini:

import { log } from "simple-logger";

Tanpa tipe, TypeScript akan protes karena tidak menemukan modulnya. Kamu bisa menulis file deklarasi yang menjelaskan permukaan publiknya:

// simple-logger.d.ts
declare module "simple-logger" {
  export function log(message: string): void;
  export function warn(message: string): void;
  export const version: string;
}

Sekarang TypeScript memperlakukan simple-logger seolah-olah bertipe lengkap. Kamu dapat autocomplete pada log dan warn, plus garis merah kalau memanggilnya dengan salah. Kode JavaScript di dalam paket itu sama sekali tidak berubah; kamu cuma menjelaskannya dari luar.

Inilah model berpikir inti yang layak kamu pegang:

  Pustaka JavaScript biasa          File deklarasi (.d.ts)
  ┌──────────────────────┐          ┌──────────────────────┐
  │ kode asli yang jalan │  ◄────►  │ tipe yang menjelaskan │
  │ (tanpa info tipe)    │          │ kode itu (tanpa jalan)│
  └──────────────────────┘          └──────────────────────┘
            │                                  │
            └──────────► TypeScript ◄──────────┘
                  melihat perilaku saat jalan
                  DAN memahami tipenya

DefinitelyTyped dan @types

Bagian inilah yang menjelaskan sihir sehari-hari tadi. Kalau file deklarasi menjelaskan pustaka tanpa tipe, lalu siapa yang menulis deklarasi untuk ribuan paket JavaScript populer di luar sana? Kamu bisa saja menulisnya sendiri satu per satu, tapi itu pekerjaan yang luar biasa banyak dan berulang.

Komunitas memecahkan ini lewat satu proyek terbuka yang sangat besar bernama DefinitelyTyped. Ini sebuah repositori publik tempat para relawan menyumbang file deklarasi berkualitas untuk pustaka JavaScript populer yang tidak menyertakan tipenya sendiri. Begitu seseorang menuliskan deklarasi untuk sebuah pustaka, semua orang ikut menikmati hasilnya.

Deklarasi-deklarasi ini diterbitkan ke registry npm di bawah lingkup khusus bernama @types. Pola penamaannya sederhana. Kalau sebuah pustaka bernama lodash, tipe yang dikelola komunitas untuknya ada di paket bernama @types/lodash. Kalau namanya express, tipenya ada di @types/express.

npm install lodash
npm install --save-dev @types/lodash

Baris pertama memasang pustaka aslinya, kode yang dijalankan. Baris kedua memasang file deklarasi yang cocok, yaitu tipe yang menjelaskannya. TypeScript otomatis melihat ke dalam paket @types dan memakainya. Kamu mengimpor lodash seperti biasa, lalu tiba-tiba semuanya bertipe, padahal lodash sendiri ditulis dalam JavaScript biasa.

Cek dulu apakah tipenya sudah ikut

Banyak pustaka modern sekarang sudah menyertakan file .d.ts-nya sendiri di dalam paket, jadi kamu tidak perlu memasang @types terpisah sama sekali. Kebiasaan yang baik: coba impor dulu pustakanya. Kalau TypeScript sudah langsung paham, berarti tipenya memang sudah ikut. Baru cari @types/... kalau editor mengeluh tidak menemukan deklarasi.

Kenapa lebih sering memakai daripada menulis

Setelah semua bagian disatukan, muncul satu kenyataan yang melegakan: sebagai developer yang bekerja sehari-hari, kamu akan membaca dan mengandalkan file deklarasi terus-menerus, tapi menulisnya jarang sekali.

Setiap kali kamu memasang pustaka yang bertipe, kamu sedang memakai file deklarasi. Setiap saran autocomplete, setiap error tipe pada fungsi pustaka, setiap tooltip yang muncul saat hover dan menunjukkan tanda tangan fungsi, semuanya berasal dari file .d.ts yang sudah ditulis orang lain, entah penulis pustakanya atau kontributor DefinitelyTyped.

Situasi di mana kamu benar-benar menulis sendiri itu sempit:

Situasi	Perlu menulis .d.ts?
Memakai pustaka yang sudah bertipe	Tidak, tipenya sudah ikut
Memakai pustaka yang dicakup @types	Tidak, cukup pasang @types
Variabel global dari tag skrip	Kadang, deklarasi kecil saja
Pustaka JS internal lama yang tak bertipe	Sesekali, kalau memang perlu
Mengimpor aset non-kode (gambar, dll.)	Kadang, deklarasi modul mungil

Untuk kebanyakan proyek, satu-satunya deklarasi yang ditulis tangan cuma beberapa baris untuk memberi tahu TypeScript soal sebuah global atau impor yang tidak biasa. Pekerjaan beratnya sudah diselesaikan untukmu.

TypeScript modern menulisnya untukmu

Saat kamu membangun pustaka TypeScript sendiri lalu mengompilasinya, compiler bisa otomatis menghasilkan file .d.ts dari kode sumbermu. Kodemu sudah punya tipe, jadi TypeScript tinggal mengeluarkannya menjadi file deklarasi untuk para penggunamu. Beginilah paket TypeScript yang diterbitkan dengan rapi mengirim tipenya: tidak ada yang menulis deklarasinya secara manual, compiler-lah yang melakukannya.

Sedikit catatan jujur soal akurasi

Ada satu peringatan jujur yang layak disampaikan. File deklarasi hanya seakurat orang yang menulisnya. Karena ia deskripsi terpisah dari kode yang hidup di tempat lain, keduanya bisa mulai tidak sinkron. Sebuah pustaka mungkin menambahkan opsi baru yang belum disebut di deklarasinya, atau sebuah tipe komunitas mungkin menjelaskan versi yang lebih lama.

Kalau itu terjadi, TypeScript tetap percaya pada deklarasinya, karena cuma itu acuan yang ia punya. Kodenya bisa saja lolos pemeriksaan tipe tapi tetap berperilaku salah. Hal ini jarang terjadi pada pustaka populer, yang tipenya diawasi banyak mata, tapi inilah alasan deklarasi disebut deskripsi dan bukan jaminan. Anggap error tipe yang mengejutkan terhadap sebuah pustaka sebagai petunjuk untuk mengecek apakah tipenya cocok dengan versi yang kamu pasang.

Rangkuman

File deklarasi, yang berakhiran .d.ts, ada untuk memberi TypeScript kosakata terhadap kode yang tidak bisa ia lihat: JavaScript biasa yang tidak membawa informasi tipe sama sekali. Isinya hanya tipe dan tidak ada yang bisa dijalankan.

Gagasan-gagasan utamanya menyatu dengan rapi. Deklarasi ambient menjelaskan sesuatu yang sudah ada di lingkungan sekitar, bukan membuatnya. Kata kunci declare adalah cara menulis deskripsi itu, baik untuk fungsi global, variabel, maupun satu modul utuh. Dan proyek DefinitelyTyped, yang diterbitkan sebagai paket @types di npm, menyediakan deklarasi siap pakai untuk ribuan pustaka tanpa tipe, itulah sebabnya memasang @types/lodash membuat lodash langsung terasa bertipe lengkap.

Kesimpulan praktisnya melegakan: kamu tidak perlu mahir menulis file deklarasi untuk bisa memakai TypeScript dengan baik. Kamu akan memakainya setiap hari lewat pustaka yang kamu pasang, dan hanya sesekali menulis beberapa baris untuk menjelaskan sebuah global atau impor yang ganjil. Memahami apa itu file .d.ts dan dari mana tipenya datang sudah cukup untuk membuat seluruh sistem terasa jelas, bukan lagi seperti sihir.