JavaScript Temporal API: Cara Mengelola Tanggal dan Zona Waktu dengan Akurat

Tanggal dan waktu terlihat sederhana sampai aplikasi harus menangani pengguna dari beberapa negara, jadwal berulang, perubahan zona waktu, atau perbedaan panjang bulan. Kesalahan kecil bisa membuat pengingat bergeser, masa langganan dihitung keliru, atau laporan analitik masuk ke hari yang salah. Di JavaScript, objek Date masih berguna, tetapi modelnya sering membuat aturan tanggal dan waktu menjadi kurang eksplisit.

Temporal API dirancang untuk mengatasi sebagian masalah tersebut. API ini menyediakan tipe khusus untuk tanggal kalender, waktu lokal, titik waktu absolut, zona waktu, dan durasi. Dengan memilih tipe yang sesuai, kode menjadi lebih mudah dibaca dan lebih aman diuji.

Mengapa objek Date sering menyulitkan?

Date pada dasarnya merepresentasikan satu titik waktu dalam milidetik sejak epoch, lalu menyediakan metode untuk membaca atau mengubah komponennya. Namun, beberapa kebutuhan bisnis bukanlah titik waktu. Tanggal ulang tahun, misalnya, tidak otomatis memiliki zona waktu. Jam buka toko juga bisa berarti pukul 09.00 di lokasi toko, bukan pukul 09.00 di perangkat setiap pengunjung.

Selain itu, sejumlah metode Date mengubah objek yang sama, parsing string tertentu dapat bergantung pada format, dan operasi aritmetika kalender tidak selalu sesederhana menambahkan sejumlah milidetik. Perubahan waktu musiman di wilayah tertentu juga dapat membuat waktu lokal tidak ada atau terjadi dua kali. Menggunakan UTC untuk semua kebutuhan tanpa memahami maknanya justru bisa memindahkan tanggal kalender yang seharusnya tetap.

Apa itu Temporal API?

Temporal adalah kumpulan objek JavaScript untuk mengolah tanggal dan waktu dengan semantik yang lebih jelas. Objek Temporal bersifat immutable: operasi seperti penambahan hari menghasilkan nilai baru, bukan mengubah objek asal. API ini juga memungkinkan pengembang menyatakan zona waktu dan kalender secara eksplisit, sehingga maksud kode lebih mudah ditinjau.

Temporal bukan pengganti penyimpanan database atau sistem sinkronisasi waktu. Ia adalah alat untuk memodelkan, menghitung, membandingkan, dan memformat nilai tanggal-waktu di dalam aplikasi. Data yang dikirim melalui API tetap perlu memiliki format dan aturan yang disepakati oleh semua layanan.

Kenali tipe utama sebelum menulis kode

• Temporal.Instant mewakili satu titik absolut pada garis waktu, cocok untuk cap waktu kejadian yang perlu dibandingkan lintas zona.
• Temporal.PlainDate menyimpan tanggal kalender tanpa jam dan zona waktu, misalnya tanggal jatuh tempo yang ditetapkan berdasarkan kalender bisnis.
• Temporal.PlainTime menyimpan jam tanpa tanggal atau zona, seperti waktu toko mulai beroperasi.
• Temporal.PlainDateTime menyimpan tanggal dan jam lokal tanpa mengunci zona waktu.
• Temporal.ZonedDateTime menggabungkan tanggal, jam, kalender, dan zona waktu, berguna untuk rapat yang ditetapkan di kota tertentu.
• Temporal.Duration menyatakan rentang seperti dua jam atau tiga hari. Durasi kalender tidak selalu sama dengan jumlah milidetik tetap.

Pemilihan tipe adalah langkah terpenting. Jangan menyimpan semua nilai sebagai timestamp hanya karena format itu mudah dikirim. Pertama-tama tentukan apakah kebutuhan bisnis berbicara tentang suatu momen, tanggal kalender, jam lokal, atau jadwal yang terikat zona tertentu.

Contoh praktis penggunaan Temporal

Misalnya, aplikasi perlu menampilkan jadwal rapat pada pukul 09.30 waktu Kuala Lumpur. Zona waktu harus menjadi bagian dari aturan jadwal, bukan hanya diambil dari pengaturan laptop orang yang membuatnya.

const jadwal = Temporal.ZonedDateTime.from({
  timeZone: "Asia/Kuala_Lumpur",
  year: 2026,
  month: 10,
  day: 22,
  hour: 9,
  minute: 30
});

console.log(jadwal.toString());

Untuk tanggal kalender yang tidak memerlukan zona waktu, gunakan tipe yang lebih sederhana:

const tanggalJatuhTempo = Temporal.PlainDate.from("2026-10-22");
const pengingatBerikutnya = tanggalJatuhTempo.add({ days: 7 });

console.log(pengingatBerikutnya.toString());

Contoh tersebut menyatakan tanggal secara langsung dan menambahkan tujuh hari kalender. Tidak perlu mengubah tanggal menjadi milidetik, membagi angka dengan 86.400.000, lalu berharap hasilnya selalu cocok dengan aturan kalender.

Kapan Temporal paling bermanfaat?

Temporal layak dipertimbangkan untuk sistem pemesanan, jadwal rapat lintas negara, pengingat berulang, masa berlaku kontrak, penagihan, aplikasi kalender, serta analitik yang mengelompokkan peristiwa berdasarkan tanggal lokal. Tipe yang eksplisit membantu mencegah perbedaan tafsir antara frontend, backend, dan database.

Untuk log teknis, biasanya simpan waktu kejadian sebagai timestamp yang jelas—misalnya ISO 8601 dengan penanda UTC—agar urutan peristiwa dapat dibandingkan. Untuk acara berulang, simpan juga aturan lokal yang dibutuhkan, termasuk zona waktu IANA seperti Asia/Kuala_Lumpur. Menyimpan hanya offset +08:00 belum tentu cukup untuk jadwal di wilayah yang aturan waktunya dapat berubah.

Baca juga: Network Time Security: Mengamankan Sinkronisasi Waktu.

Referensi resmi: Spesifikasi proposal Temporal dari TC39.

Kesimpulan

Temporal menyediakan tipe yang lebih jelas untuk tanggal kalender, waktu lokal, titik waktu absolut, dan zona waktu. Pilih tipe sesuai makna data, simpan zona IANA untuk jadwal berbasis lokasi, serta uji kasus batas kalender dan kompatibilitas runtime sebelum menjadikannya fondasi aplikasi produksi.