# JavaScript Temporal API: Pengganti Modern untuk Date

> Mengapa objek Date bermasalah dan bagaimana Temporal memperbaikinya dengan tipe imutabel, zona waktu kelas satu, dan aritmetika aman DST — plus status browser terkini.

URL: https://www.matthewswong.com/id/blog/javascript-temporal-api-guide/

- Author: Matthews Wong (https://www.matthewswong.com/id/about/)
- Published: 2026-08-01
- Updated: 2026-08-01
- Category: Web Dev

> **Key takeaway:** JavaScript Temporal API adalah pengganti modern dan imutabel untuk objek Date yang bermasalah. API ini menyediakan tipe khusus seperti PlainDate, ZonedDateTime, Instant, dan Duration, plus zona waktu kelas satu dan aritmetika aman DST. Temporal telah mencapai TC39 Stage 4 dan kini hadir di Firefox serta Chrome, dengan polyfill js-temporal menutupi mesin lama.

Bekerja dengan tanggal di JavaScript selalu terasa seperti melawan bahasanya sendiri. Objek Date bawaan diporting hampir persis dari Java awal, dan telah membawa kesalahan desain yang sama selama tiga dekade. Temporal adalah jawaban jalur standar — objek global baru yang dibangun agar penanganan tanggal dan waktu menjadi dapat diprediksi, bukan berbahaya.

Dalam panduan ini saya membahas mengapa Date bermasalah, tipe Temporal baru yang akan benar-benar Anda pakai, bagaimana imutabilitas dan zona waktu kelas satu mengubah cara Anda menalar waktu, dan tepatnya di mana posisi Temporal saat ini di browser maupun di standar bahasa.

## Mengapa objek Date bermasalah

Date mencoba menjadi terlalu banyak hal sekaligus. Satu instance Date sekaligus merupakan timestamp yang diukur dalam milidetik sejak epoch Unix dan sekumpulan field kalender, sehingga API-nya membingungkan dan mudah disalahgunakan. Sifat terburuknya bersifat struktural, bukan kosmetik:

- Mutabilitas — setter seperti setMonth dan setDate mengubah objek di tempat, sehingga mengoper Date berarti fungsi mana pun bisa merusaknya diam-diam.
- Zona waktu lemah — Date hanya memahami UTC dan zona lokal mesin. Tidak ada cara merepresentasikan waktu jam-dinding di zona IANA sembarang seperti Asia/Jakarta.
- Parsing rapuh — memasukkan string ke konstruktor Date memberi hasil yang secara historis berbeda antar browser, sehingga mem-parse apa pun selain input ISO ketat tidak dapat diandalkan.
- Hanya satu kalender — Date mendukung kalender Gregorian secara eksklusif, mengabaikan sistem Ibrani, Tionghoa, Jepang, dan lain-lain yang dipakai miliaran orang.

Ini bukan kasus tepi. Kebingungan zona waktu dan mutasi tak sengaja adalah dua sumber bug tanggal paling umum di JavaScript produksi, dan tidak ada pustaka pembungkus yang benar-benar menyembunyikannya.

## Mengenal Temporal: imutabel sejak desain

Temporal menggantikan Date tunggal yang kelebihan beban dengan keluarga kecil tipe imutabel yang dibangun untuk tujuan khusus. Setiap metode yang tampak mengubah nilai — add, subtract, with, round — malah mengembalikan objek yang benar-benar baru dan membiarkan aslinya tak tersentuh. Aturan tunggal itu menghapus satu kelas bug aliasing sepenuhnya.

Perhatikan bagaimana setiap nilai pada contoh di atas menyatakan dengan tepat apa dirinya. PlainDate tidak punya zona waktu, sehingga tidak bisa tak sengaja menggeser hari saat server berjalan di wilayah berbeda. ZonedDateTime membawa zona IANA-nya, sehingga aritmetika melintasi batas daylight-saving tetap benar. Tidak ada ambiguitas tentang makna sebuah nilai.

> Pilih tipe paling spesifik yang diizinkan kasus Anda. Simpan tanggal lahir sebagai PlainDate, alarm harian sebagai PlainTime, dan acara terjadwal nyata sebagai ZonedDateTime. Memakai ZonedDateTime di mana-mana justru mengembalikan ambiguitas yang ingin dihilangkan Temporal.

## Tipe Temporal yang akan Anda pakai

Temporal mengekspos beberapa tipe di bawah satu namespace global, masing-masing memodelkan satu konsep yang jelas. Sebagian besar kode aplikasi hanya menyentuh tiga atau empat yang pertama:

- Temporal.Instant — titik tetap pada garis waktu global dengan presisi nanodetik, disimpan sebagai nanodetik dari epoch Unix, tanpa kalender atau zona.
- Temporal.ZonedDateTime — tanggal dan waktu yang tertambat pada zona waktu IANA dan kalender tertentu; tipe untuk acara dunia nyata seperti rapat atau penerbangan.
- Temporal.PlainDate — tanggal kalender berupa tahun, bulan, dan hari tanpa waktu dan tanpa zona; ideal untuk tanggal lahir, faktur, dan acara sepanjang hari.
- Temporal.PlainTime — waktu jam-dinding berupa jam, menit, dan detik tanpa tanggal atau zona; bayangkan alarm 09:00 yang berulang.
- Temporal.PlainDateTime — tanggal plus waktu jam-dinding tetapi tetap tanpa zona; berguna saat zona diberikan terpisah kemudian.
- Temporal.PlainYearMonth dan Temporal.PlainMonthDay — tahun-dan-bulan seperti periode penagihan, serta bulan-dan-hari seperti hari peringatan tahunan.
- Temporal.Duration — rentang waktu yang dinyatakan dari tahun hingga nanodetik, dikembalikan oleh perbandingan dan dikonsumsi oleh add serta subtract.
- Temporal.Now — namespace untuk membaca instant, zoned date-time, atau plain date saat ini dari jam sistem.

## Zona waktu kelas satu dan aritmetika aman DST

Fitur yang paling dirindukan pengembang dari Date adalah dukungan zona waktu yang jujur. Temporal memperlakukan zona IANA sebagai input kelas satu: Anda dapat membuat ZonedDateTime di Asia/Jakarta atau America/New_York secara langsung, mengonversi antar zona tanpa kehilangan informasi, dan membandingkan instant di seluruh dunia dengan aman.

Aritmetikanya sadar daylight-saving. Pada contoh kode, menambah satu hari kalender ke rapat New York tetap mempertahankan waktu jam-dinding 12:00 meski hari spring-forward hanya berdurasi 23 jam — offset bergeser dari minus lima ke minus empat secara otomatis. Dengan Date Anda harus menangani kasus itu sendiri, dan kebanyakan kode tidak pernah melakukannya.

> Temporal bukan sekadar penggantian nama Date. Metode, nama properti, dan perilaku pembulatannya sengaja berbeda. Sisihkan waktu untuk mempelajari modelnya alih-alih mengganti panggilan Date secara massal, dan pisahkan Instant untuk timestamp mesin dari tipe plain yang dipakai untuk nilai kalender yang dihadapi manusia.

## Date versus Temporal sekilas

Tabel di bawah merangkum mengapa tim bermigrasi. Setiap baris adalah titik masalah konkret yang dihilangkan Temporal lewat desain, bukan lewat konvensi.

| Aspek | Date lama | Temporal |
| --- | --- | --- |
| Mutabilitas | Setter mengubah objek di tempat | Imutabel — setiap operasi mengembalikan nilai baru |
| Zona waktu | Hanya UTC atau mesin lokal | Zona waktu IANA apa pun, kelas satu |
| Tipe | Satu objek mewakili segalanya | Tipe berbeda untuk date, time, instant, dan duration |
| Kalender | Hanya kalender Gregorian | Mendukung banyak sistem kalender |
| Parsing | Tidak konsisten antar mesin | Parsing ISO 8601 yang ketat dan dapat diprediksi |

## Standardisasi dan status browser

Temporal telah menuntaskan proses TC39. API ini mencapai Stage 4 — tahap akhir, yang berarti sudah menjadi tambahan yang diterima pada standar ECMAScript — setelah hampir satu dekade kerja desain. Spesifikasinya sedang digabung ke ECMA-262 dan ECMA-402, sehingga permukaan API-nya kini stabil.

Peluncuran di mesin sudah berjalan baik. Firefox yang pertama, mengaktifkan Temporal secara default di Firefox 139 pada 27 Mei 2025. Chrome menyusul di Chrome 144 pada 13 Januari 2026, dan Node.js menambahkannya di Node 26 pada 5 Mei 2026. Dukungan Safari masih dalam pengembangan, sehingga Temporal belum menjadi fitur Baseline yang bisa diasumsikan ada di mana-mana.

## Haruskah Anda memakai Temporal sekarang?

Ya, dengan hati-hati. Di Firefox, Chrome, dan Node terbaru Anda dapat memanggil Temporal secara native. Untuk selebihnya, pasang paket polyfill js-temporal resmi dari para champion proposal, yang mengekspos API yang sama persis sehingga kode Anda tetap kompatibel ke depan. Tulis dengan Temporal sekarang, pertahankan polyfill sampai Safari merilisnya, lalu lepas nanti tanpa perubahan kode.

## Sources

- MDN Web Docs — referensi Temporal
- Dokumentasi TC39 proposal-temporal
- Repositori dan status tc39/proposal-temporal
- SpiderMonkey — Shipping Temporal di Firefox

## Source links

- https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal
- https://tc39.es/proposal-temporal/docs/
- https://github.com/tc39/proposal-temporal
- https://spidermonkey.dev/blog/2025/04/11/shipping-temporal.html

## FAQ

### Apa itu JavaScript Temporal API?

Temporal adalah objek global bawaan JavaScript baru yang menggantikan objek Date yang bermasalah. Ia menyediakan tipe imutabel khusus seperti PlainDate, ZonedDateTime, Instant, dan Duration, plus dukungan zona waktu IANA kelas satu dan aritmetika aman DST. Temporal telah mencapai TC39 Stage 4, menjadi bagian resmi standar ECMAScript.

### Mengapa objek Date JavaScript dianggap bermasalah?

Date menjejalkan timestamp dan field kalender ke satu objek, setter-nya mengubah nilai di tempat, dan ia hanya memahami UTC serta zona lokal. Perilaku parsing secara historis berbeda antar browser dan hanya mendukung kalender Gregorian. Cacat struktural ini membuat bug zona waktu dan mutasi umum terjadi di kode produksi.

### Apa saja tipe utama Temporal?

Tipe intinya adalah Temporal.Instant untuk timestamp mesin, Temporal.ZonedDateTime untuk acara berzona nyata, Temporal.PlainDate, Temporal.PlainTime, dan Temporal.PlainDateTime untuk nilai tanpa zona, Temporal.PlainYearMonth dan Temporal.PlainMonthDay untuk tanggal parsial, serta Temporal.Duration untuk rentang waktu. Temporal.Now membaca waktu saat ini.

### Browser mana yang mendukung Temporal API?

Firefox merilis Temporal secara default di Firefox 139 pada 27 Mei 2025, Chrome menambahkannya di Chrome 144 pada 13 Januari 2026, dan Node.js di Node 26. Dukungan Safari masih dalam pengembangan, sehingga Temporal belum menjadi fitur Baseline yang bisa diasumsikan tersedia di mana-mana.

### Apakah saya bisa memakai Temporal di produksi sekarang?

Ya, dengan hati-hati. Anda dapat memanggil Temporal secara native di Firefox, Chrome, dan Node terbaru. Untuk mesin yang belum mendukungnya, pasang paket resmi @js-temporal/polyfill yang mengekspos API sama. Tulis dengan Temporal sekarang lalu lepas polyfill setelah Safari merilisnya, tanpa perubahan kode.

---

- HTML version: https://www.matthewswong.com/id/blog/javascript-temporal-api-guide/
- English: https://www.matthewswong.com/en/blog/javascript-temporal-api-guide/
- Site index for agents: https://www.matthewswong.com/llms.txt
- Sitemap: https://www.matthewswong.com/sitemap.xml
- API description (OpenAPI): https://www.matthewswong.com/openapi.json