JavaScript Temporal API: Pengganti Modern untuk Date

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.

import { Temporal } from '@js-temporal/polyfill';

// A calendar date — no time, no time zone attached
const releaseDay = Temporal.PlainDate.from('2026-08-01');

// Immutable: add() returns a NEW instance, the original is untouched
const nextRelease = releaseDay.add({ months: 1 });
releaseDay.toString();  // '2026-08-01'  (unchanged)
nextRelease.toString(); // '2026-09-01'

// A real event carries its IANA time zone
const meeting = Temporal.ZonedDateTime.from(
  '2026-03-07T12:00[America/New_York]'
);

// DST-safe arithmetic: adding one calendar day keeps 12:00 wall-clock,
// even though 8 Mar 2026 is only 23 hours long (spring-forward)
meeting.add({ days: 1 }).toString();
// '2026-03-08T12:00:00-04:00[America/New_York]'

// A timestamp on the global timeline: nanosecond precision, no calendar
const now = Temporal.Now.instant();

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.

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.

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.

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.