JSDoc adalah TypeScript

 (culi.bearblog.dev)
1 poin oleh GN⁺ 2025-12-16 | 1 komentar | Bagikan ke WhatsApp
  • Pada 2023, PR refaktor di repositori Svelte yang beralih ke kode berbasis JSDoc menarik perhatian para skeptis TypeScript
  • Pihak Svelte menjelaskan bahwa ini bukan sikap anti-TypeScript, melainkan bagian dari ketergantungan berkelanjutan pada TypeScript
  • Artikel ini menekankan bahwa JSDoc dan TypeScript bukanlah dua hal yang berseberangan, melainkan JSDoc itu sendiri merupakan bagian dari TypeScript
  • TypeScript berperan sebagai mesin IntelliSense, yang menangani interpretasi komentar JSDoc sekaligus fitur autocompletion kode
  • Tanpa tahap build, JSDoc menyediakan kemampuan analisis statis yang sama, dan dalam proyek JS modern pada praktiknya menjalankan peran yang sama dengan TypeScript

PR Svelte dan latar belakang kontroversi

  • Pada Mei 2023, PR refaktor internal di repositori Svelte naik ke halaman depan Hacker News
    • PR ini mengubah deklarasi tipe di file .ts menjadi komentar JSDoc di file .js
    • Sebagian orang menafsirkan ini sebagai penolakan terhadap manfaat TypeScript
  • Pendiri Svelte, Rich Harris, menjelaskan langsung di HN bahwa “ini bukan anti-TypeScript”
    • Ia menyebut komitmen Svelte terhadap TypeScript tetap sangat kuat
  • Setelah kejadian ini, bermunculan banyak tulisan perbandingan “TypeScript vs JSDoc”, dan pandangan yang menilai JSDoc sebagai “TypeScript tanpa tahap build” pun semakin meluas

Asal-usul dan hakikat TypeScript

  • Pada akhir 2000-an hingga awal 2010-an, JavaScript dipandang sebagai bahasa yang kurang memiliki autocompletion dan keamanan tipe
    • Pengembang Microsoft merespons dengan menggunakan ScriptSharp untuk mengubah kode C# menjadi JS
    Iklan
  • Dalam latar belakang seperti itu, TypeScript lahir, dan pada dasarnya berawal sebagai alat build untuk meningkatkan pengembangan JS

TypeScript adalah IntelliSense

  • TypeScript bukan sekadar bahasa, tetapi juga berperan sebagai mesin IntelliSense
    • Bahkan tanpa memakai file .ts, fitur seperti autocompletion kode, informasi parameter, dan penelusuran simbol disediakan oleh language service TypeScript
    • Di sebagian besar editor, saat menulis kode JS pun layanan TypeScript berjalan di backend

TypeScript adalah JSDoc

  • Language service TypeScript juga digunakan untuk menafsirkan komentar JSDoc
    • CHANGELOG TypeScript sering memuat penambahan fitur yang berkaitan dengan JSDoc
    • Proyek berbasis JSDoc juga bisa dikonfigurasi dengan tsconfig.json, dan pemeriksaan tipe dapat dijalankan dengan perintah tsc
  • Karena itu, pengembang yang memakai JSDoc pada dasarnya juga sudah menggunakan TypeScript
Iklan

Pengalaman dengan proyek berbasis JSDoc

  • Penulis membagikan pengalaman menulis ulang frontend proyek lama dengan komentar tipe berbasis JSDoc
    • Selain fitur runtime seperti enum, sebagian besar ekspresi TypeScript dapat diwujudkan dengan JSDoc
    • Generic memang punya sintaks yang agak rumit, tetapi justru mendorong pemanfaatan inferensi tipe secara lebih aktif
  • Dalam proyek JSDoc, saat mengklik fungsi, pengembang bisa langsung berpindah ke kode sebenarnya, sehingga pengalaman pengembangan meningkat
  • Ekosistem alat TypeScript juga bisa digunakan ulang dalam proyek JSDoc
    • Contoh: library yang menghasilkan tipe dari skema OpenAPI atau GraphQL juga dapat menghasilkan tipe dalam bentuk komentar JSDoc

Kesimpulan dan contoh tambahan

  • JSDoc bukan alternatif bagi TypeScript, melainkan berbagi sistem analisis statis yang sama
    • Dengan melewati tahap build, JSDoc tetap memberikan stabilitas tipe yang setara
  • Sebagai tambahan, disebut pula contoh proyek webpack yang dimigrasikan ke JSDoc
  • Sebagai pakar TypeScript, penulis dengan tegas menyatakan posisi bahwa “JSDoc adalah TypeScript”

Bacaan terkait

1 komentar

 
GN⁺ 2025-12-16
Komentar Hacker News

  • Selama beberapa tahun mengembangkan dan memelihara perangkat lunak web dan robotika dengan Python/JavaScript, saya merangkum pelajaran yang saya dapat
    Tipe tetap ada meskipun tidak ditulis secara eksplisit, dan jika tidak dituliskan pada akhirnya tipe itu hanya ada di dalam kepala
    Namun kepala sangat mudah lupa dan sulit diakses orang lain
    Karena itu, pengetikan tipe adalah sarana dokumentasi yang sangat baik
    JSDoc dan TypeScript adalah format standar untuk mengekspresikan tipe, dan keduanya punya kelebihan serta kekurangan
    Yang penting adalah mendefinisikan tipe secara konsisten dan bisa diprediksi
    Type checker adalah cara komputer mengatakan, “kalau begitu buktikan”
    Tidak semua program memerlukan tingkat pembuktian yang sama, dan pembuktian yang berlebihan bisa menjadi pemborosan
    Karena itu saya lebih menyukai bahasa yang bisa “membuktikan” seperlunya

    • Saya sangat setuju dengan kalimat “informasi yang hanya ada di dalam kepala itu mudah menguap”
      Saat bekerja saya benar-benar belajar bahwa “orang lain” itu juga mencakup diri saya sendiri di masa depan
    • Rust dikenal sebagai representasi filosofi “prove it”, tetapi saya rasa kenyataannya tidak sesederhana itu
      Rust bisa melonggarkan batasan lewat unsafe, Arc, clone, tetapi sebagai gantinya kita harus secara jelas memilih batasan mana yang belum dibuktikan
      Sebaliknya, pada bahasa yang “tidak perlu membuktikan”, sulit mengetahui pendekatan apa yang sebenarnya diambil secara internal
      Pendekatan Rust bisa terasa longgar seperti Python di awal, tetapi kemudian jauh lebih unggul dalam hal keterbacaan dan skalabilitas
    • Saya setuju bahwa JSDoc dan TypeScript memiliki tujuan yang sama
      Maksudnya bukan membela alat tertentu, hanya ingin menekankan bahwa keduanya sama-sama cara mengekspresikan sistem tipe
    • Saya sudah mempelajari pelajaran ini 25 tahun lalu saat kuliah
      Bahasa dengan static typing jauh lebih mudah ditangani dalam proyek tim, dan sampai sekarang saya tetap lebih memilih static type kalau memungkinkan
    • Saya setuju dengan pernyataan “tipe selalu ada”, tetapi bahasa seperti C# yang mewajibkan penulisan tipe jelas membutuhkan jauh lebih banyak kerja dibanding Ruby
      Jika melihat definisi tipe TypeScript yang ditambahkan belakangan ke library JS lama, kompleksitasnya luar biasa
      Satu tipe yang salah saja bisa merusak seluruh kompilasi
      Pada akhirnya, bahasa dinamis harus digunakan dengan pendekatan ‘tanggung sendiri’

  • Saya suka semua hal yang bisa dibuat dengan JavaScript tanpa build step
    Kombinasi HTML/CSS modern, Web Components, dan JSDoc masih diremehkan
    Memang tidak cocok untuk semua orang, tetapi menurut saya itu kandidat stack frontend yang cukup modern

    • Mulai Node 24, TypeScript juga bisa dijalankan tanpa build step
    • Saya paham daya tarik pendekatan tanpa build step, tetapi dalam praktiknya pengelolaan dependensi jadi lebih rumit
      Berkat fitur seperti HMR, biaya build step juga sudah jauh berkurang
    • Dalam 10 tahun terakhir saya belum pernah menulis kode JS yang benar-benar langsung dideploy
      Selalu lewat Vite atau Webpack, jadi saya tidak terlalu merasakan keuntungan JS tanpa build
    • Web Components cukup menyakitkan untuk dibuat
      Saya berharap ada cara yang lebih mudah untuk membuat komponen yang kompleks
    • Kelebihan kombinasi HTML+CSS+JSDoc adalah integrasi alaminya dengan browser developer tools
      Melacak request jaringan, lompat langsung ke source code, memasang breakpoint, dan sebagainya membuat debugging jauh lebih intuitif
      Semakin besar skalanya, lingkungan seperti ini semakin membantu

  • Saat SPA sedang populer, JSDoc adalah penyelamat pengelolaan tipe
    Setelah itu Google Closure Compiler muncul dan memberikan type safety berbasis JSDoc, lalu TypeScript mendukung (TS)JSDoc bersama sintaksnya sendiri
    Komunitas akhirnya memilih TypeScript dan Closure Compiler pun menghilang
    Karena itu, (TS)JSDoc tersisa sebagai artefak dari masa ketika MS bersaing dengan Google
    Sekarang TS menawarkan jauh lebih banyak fitur seperti generics, enum, utility type, pengujian tipe Vitest, type guard, dan lain-lain
    Saya memakai TS dan JSDoc bersama — TS untuk kode, JSDoc untuk dokumentasi (@link, @see, @deprecated, @example, dll.)

    • Sebenarnya JSDoc modern menggunakan TypeScript language service
      Generics, utility type, type guard, parsing regex, dan sebagian besar fitur TS bisa dimanfaatkan juga di JSDoc
      Di proyek pribadi saya bahkan pernah mengimplementasikan semuanya dengan JSDoc, termasuk generics
    • Klaim di atas tidak benar
      Menyebut (TS)JSDoc sebagai artefak masa lalu adalah informasi yang keliru, jadi sebaiknya jangan menyebarkannya tanpa verifikasi
    • Tulisan ini sendiri adalah sanggahan langsung terhadap klaim itu

  • Banyak yang bilang ada banyak tipe yang tidak bisa diekspresikan dengan JSDoc, tetapi andai pendekatan seluruh bahasa seperti Flow bisa diterapkan, itu mungkin bagus
    TypeScript juga sebenarnya bisa melakukan itu, jadi saya tidak tahu kenapa tidak dilakukan

    • Saya ingin mendengar contoh yang spesifik
      Dulu saya juga berpikir begitu, tetapi berubah pikiran setelah merombak proyek menjadi JSDoc
      Di JSDoc kita juga bisa mendefinisikan slot generic dengan @template
      Contoh: 
      /** @type {ReturnType<typeof useState<Book[]>>} */
const [books, setBooks] = useState();
    • Sekarang hampir semua fitur sistem tipe juga sudah ditambahkan ke sintaks JSDoc
    • Sistem tipe TypeScript itu Turing complete sehingga pada praktiknya punya daya ekspresi yang nyaris tak terbatas
      Tautan terkait

  • Paket yang ditulis dengan JSDoc memberikan pengalaman developer yang baik karena klik CMD/CTRL bisa langsung menuju ke kode asli

    • Ini juga bisa dikustomisasi lewat pengaturan editor
    • Sebenarnya di TypeScript pun perilakunya sama

  • Lima tahun lalu di sebuah meetup, ada pembicara yang mengatakan “kalau tidak suka TypeScript, JSDoc adalah alternatifnya”
    Saya menjelaskan bahwa pada akhirnya keduanya sama-sama TypeScript, tetapi atasan saya tidak percaya

    • Menurut saya bedanya hanya soal tingkat kompresi sintaks (syntax compression)
    • Kalimat “JSDoc pada akhirnya adalah TypeScript juga” itu hanya setengah benar
      JSDoc dan TS sama-sama mengekspresikan tipe secara eksplisit, tetapi sintaks TS jauh lebih kuat
      Meski begitu, bagi orang yang ingin tetap memakai lingkungan JS sambil mendapatkan manfaat alat tipe, JSDoc adalah pilihan yang bagus

  • Sebagai sanggahan, JSDoc bukan TypeScript
    Tipe yang didefinisikan dengan @typedef akan diekspor secara otomatis, dan tidak ada cara untuk mengendalikan itu
    Isu terkait
    Karena hal ini, saat mengembangkan library IntelliSense jadi tampil berantakan dan terasa merepotkan

    • Untuk Web Components, JSDoc cukup cocok
      File “my-component.js” bisa langsung disalin apa adanya dan tetap berjalan tanpa build
      Tetapi untuk proyek besar, saya lebih suka sintaks TS
    • Secara teknis itu memang poin yang benar, tetapi mengatur @import biasanya bisa menyelesaikan sebagian besar masalah

  • Saya setuju dengan klaim bahwa “JSDoc bukan alternatif TypeScript”
    JSDoc juga memberikan analisis statis tetapi tanpa build step
    Lihat dokumentasi resmi Node

    • Secara internal, build step itu sebenarnya masih ada
      Tetapi TS berbasis JSDoc juga berjalan di browser
      Secara pribadi saya lebih menyukai keterbacaan sintaks TS, dan kecepatan penghapusan tipe dengan alat seperti swc juga sudah cukup cepat
    • Namun fitur ini terbatas pada lingkungan Node dan tidak berjalan di browser

  • Alasan TypeScript menang atas alternatif lain adalah karena ia tetap menjadi type checker, bukan bahasa baru
    Di awal arahnya sempat agak goyah, tetapi lalu diperbaiki dengan tepat, dan sekarang bahkan enum pun jarang dipakai di sebagian besar kode

  • Di VSCode, jika mengaktifkan pengaturan “TypeScript: Prefer Go To Source Definition”, kita bisa pindah ke source yang sebenarnya
    Selain itu, jika menambahkan declarationMap: true ke tsconfig, hasilnya akan bekerja lebih akurat
    Saya hampir selalu lebih suka melihat source saat cmd+click