Menguasai JavaScript Temporal ZonedDateTime: Panduan Anda untuk Perhitungan Sadar Zona Waktu yang Sempurna

Di dunia kita yang semakin terhubung, aplikasi jarang beroperasi dalam batas satu zona waktu. Mulai dari menjadwalkan pertemuan tim internasional dan mengelola acara global hingga mencatat transaksi keuangan lintas benua, menangani tanggal dan waktu secara akurat dan tidak ambigu adalah tantangan yang persisten dan seringkali kompleks bagi para pengembang. Objek Date JavaScript tradisional, meskipun fungsional untuk operasi waktu lokal sederhana, terkenal kesulitan dengan seluk-beluk zona waktu, perubahan daylight saving time (DST), dan sistem kalender yang berbeda. Hal ini sering menyebabkan bug halus yang dapat memiliki implikasi signifikan bagi pengalaman pengguna, integritas data, dan logika bisnis.

Memperkenalkan API Temporal JavaScript, solusi modern, kuat, dan sangat dinanti yang dirancang untuk menggantikan objek Date lawas. Di antara primitif barunya yang kuat, Temporal.ZonedDateTime menonjol sebagai landasan untuk perhitungan yang benar-benar sadar zona waktu. Ini mewakili momen waktu yang spesifik dan tidak ambigu, terikat pada zona waktu tertentu, membuatnya sangat diperlukan untuk aplikasi apa pun yang melayani audiens global. Panduan komprehensif ini akan mendalami ZonedDateTime, menjelajahi fitur-fiturnya, menunjukkan aplikasi praktisnya, dan menguraikan praktik terbaik untuk mengintegrasikannya ke dalam alur kerja pengembangan global Anda.

Tantangan Waktu Global: Mengapa Tanggal dan Waktu Itu Rumit

Sebelum kita merangkul solusi yang ditawarkan oleh Temporal, mari kita bongkar mengapa manajemen tanggal dan waktu telah menjadi sumber pusing yang terus-menerus di JavaScript dan lingkungan pemrograman lainnya. Masalah intinya berasal dari ambiguitas yang melekat dalam merepresentasikan 'titik waktu' tanpa kerangka acuan yang jelas.

Keterbatasan Objek Date Lama

Objek Date asli JavaScript secara fundamental cacat untuk aplikasi global karena ia mencoba menjadi dua hal sekaligus: momen waktu tertentu (seperti stempel waktu UTC) dan representasi lokal dari momen itu. Sifat ganda ini sering menyebabkan kebingungan dan kesalahan:

• Asumsi Zona Waktu Implisit: Saat Anda membuat new Date() tanpa argumen, ia akan default ke zona waktu lokal sistem. Saat Anda mengurai string seperti "2023-10-27T10:00:00", seringkali diinterpretasikan sebagai waktu lokal, tetapi tanpa informasi zona waktu eksplisit, ini adalah instruksi yang ambigu.
• Objek yang Dapat Diubah (Mutable): Objek Date bersifat mutable, artinya operasi seperti setHours() secara langsung memodifikasi objek asli. Ini membuat pelacakan perubahan menjadi sulit dan dapat menyebabkan efek samping yang tidak diinginkan, terutama dalam aplikasi kompleks di mana tanggal sering dilewatkan.
• Perhitungan yang Sulit: Melakukan perhitungan seperti menambahkan 'tiga jam' atau 'dua hari' tanpa memperhitungkan pergeseran zona waktu atau perubahan DST dengan benar rentan terhadap kesalahan. Menangani transisi DST secara manual, yang terjadi pada waktu dan tanggal yang berbeda secara global, adalah tugas yang monumental.
• Parsing yang Tidak Konsisten: Parsing string terkenal tidak dapat diandalkan di berbagai browser dan mesin JavaScript, yang mengarah pada perilaku yang tidak terstandarisasi saat menafsirkan string tanggal.
• Tidak Ada Pembedaan yang Jelas: Tidak ada cara yang jelas untuk merepresentasikan tanggal tertentu tanpa waktu, atau waktu tanpa tanggal, atau durasi, atau instan tanpa zona waktu.

Dampak Kesalahan Zona Waktu di Dunia Nyata

Pertimbangkan skenario ini di mana penanganan tanggal/waktu yang tidak memadai dapat menyebabkan masalah signifikan:

• Rapat yang Terlewat: Sebuah tim di London menjadwalkan rapat pada "jam 3 sore" dengan rekan kerja di New York. Tanpa konversi zona waktu yang tepat, tim New York mungkin menafsirkannya sebagai jam 3 sore waktu lokal mereka, bukan jam 3 sore waktu London (yang akan menjadi jam 10 pagi di New York selama waktu standar).
• Waktu Acara yang Salah: Konferensi online yang diiklankan mulai pukul "9:00 pagi PST" dapat disalahartikan oleh peserta di wilayah lain jika tampilan lokal mereka tidak mengonversi dengan benar.
• Transaksi Keuangan yang Cacat: Bank atau bursa saham yang beroperasi lintas negara memerlukan stempel waktu yang presisi dan tidak ambigu untuk setiap transaksi guna menjaga jejak audit dan memastikan kepatuhan terhadap peraturan. Satu jam yang salah tempat bisa menyebabkan kerugian jutaan dolar atau sengketa hukum.
• Masalah Analisis Log: Log server yang diberi stempel waktu lokal dari server berbeda di wilayah geografis yang berbeda menjadi tidak mungkin untuk dikorelasikan dan dianalisis secara akurat tanpa normalisasi.
• Keterlambatan Logistik dan Pengiriman: Menjadwalkan pengiriman "besok jam 10 pagi" lintas benua memerlukan pertimbangan zona waktu penerima, bukan hanya pengirim.

Tantangan-tantangan ini menyoroti kebutuhan kritis akan API yang kuat, eksplisit, dan tidak ambigu untuk menangani tanggal dan waktu. Inilah tepatnya yang ingin disampaikan oleh JavaScript Temporal.

Memasuki JavaScript Temporal: Pendekatan Modern untuk Tanggal dan Waktu

API Temporal adalah objek global baru yang menyediakan API yang intuitif dan andal untuk bekerja dengan tanggal dan waktu. Ini mengatasi kekurangan objek Date lawas dengan memperkenalkan serangkaian tipe yang tidak dapat diubah (immutable) dan berbeda yang secara jelas memisahkan urusan:

• Temporal.Instant: Mewakili titik waktu yang spesifik dan tidak ambigu, independen dari kalender atau zona waktu apa pun. Ini pada dasarnya adalah stempel waktu UTC presisi tinggi. Ideal untuk mencatat dan menyimpan momen yang presisi.
• Temporal.PlainDate: Mewakili tanggal kalender (tahun, bulan, hari) tanpa informasi waktu atau zona waktu. Berguna untuk ulang tahun atau hari libur.
• Temporal.PlainTime: Mewakili waktu jam dinding (jam, menit, detik, pecahan detik) tanpa informasi tanggal atau zona waktu. Berguna untuk rutinitas harian.
• Temporal.PlainDateTime: Menggabungkan PlainDate dan PlainTime. Ini adalah tanggal dan waktu spesifik pada kalender, tetapi masih tanpa zona waktu. Sering disebut "tanggal-waktu lokal" atau "tanggal-waktu jam dinding".
• Temporal.ZonedDateTime: Bintang dari panduan ini. Ini adalah PlainDateTime yang terkait dengan Temporal.TimeZone tertentu. Ini adalah tipe yang secara akurat mewakili momen spesifik di zona waktu tertentu, menangani DST dan offset dengan benar.
• Temporal.Duration: Mewakili rentang waktu, seperti "3 jam 30 menit" atau "5 hari". Digunakan untuk melakukan aritmatika dengan tipe Temporal lainnya.
• Temporal.TimeZone: Mewakili zona waktu tertentu, diidentifikasi oleh string zona waktu IANA (misalnya, "Europe/London", "America/New_York", "Asia/Tokyo").
• Temporal.Calendar: Mewakili sistem kalender, seperti Gregorian, ISO 8601, Jepang, atau Cina.

Prinsip utama di balik Temporal adalah kejelasan (explicitness). Anda selalu tahu persis jenis informasi tanggal/waktu apa yang sedang Anda kerjakan, dan operasi mengharuskan Anda untuk berhati-hati tentang zona waktu, durasi, dan kalender. Ini menghilangkan asumsi tersembunyi dan ambiguitas yang mengganggu objek Date lawas.

Memahami Komponen Inti ZonedDateTime

Pada intinya, Temporal.ZonedDateTime menggabungkan tiga informasi penting untuk secara tidak ambigu mewakili momen waktu relatif terhadap suatu wilayah geografis:

1. Sebuah Temporal.PlainDateTime: Komponen ini menyediakan komponen tahun, bulan, hari, jam, menit, detik, dan sub-detik dari tanggal dan waktu. Yang terpenting, ini adalah waktu "jam dinding", artinya inilah yang akan Anda lihat di jam atau kalender di lokasi tertentu, *tanpa* mempertimbangkan aturan zona waktu apa pun. Misalnya, "2023-10-27 pukul 10:00:00".
2. Sebuah Temporal.TimeZone: Ini adalah seperangkat aturan (misalnya, offset dari UTC, tanggal mulai/berakhir DST) yang menentukan bagaimana waktu dijaga di wilayah geografis tertentu. Temporal menggunakan pengidentifikasi IANA Time Zone Database (misalnya, "America/Los_Angeles", "Europe/Berlin", "Asia/Dubai"). Komponen ini menyediakan konteks yang diperlukan untuk menafsirkan PlainDateTime.
3. Sebuah offset (diturunkan secara implisit): Meskipun tidak secara eksplisit menjadi bagian dari parameter konstruktor dalam banyak kasus, ZonedDateTime secara internal mengetahui offset UTC yang tepat pada saat itu. Offset ini memperhitungkan offset standar zona waktu dan setiap daylight saving time yang aktif. Ini memastikan bahwa komponen PlainDateTime dipetakan dengan benar ke Temporal.Instant yang tepat (waktu UTC).

Ketika Anda memiliki ketiga elemen ini, Anda dapat menentukan momen spesifik yang tidak ambigu pada garis waktu, terlepas dari di mana aplikasi Anda berjalan atau apa zona waktu lokal pengguna. Ini membuat ZonedDateTime ideal untuk setiap operasi tanggal dan waktu yang perlu disajikan atau dihitung relatif terhadap zona waktu tertentu.

Membuat Objek ZonedDateTime: Contoh Praktis

Ada beberapa cara untuk membuat instance objek Temporal.ZonedDateTime, tergantung pada data awal Anda. Mari kita jelajahi metode paling umum dengan contoh global.

1. Dari Waktu Saat Ini

Untuk mendapatkan tanggal dan waktu saat ini di zona waktu tertentu, Anda menggunakan Temporal.ZonedDateTime.now(). Anda dapat secara opsional meneruskan pengidentifikasi zona waktu.

            
// Dapatkan ZonedDateTime saat ini di zona waktu default sistem
const nowInSystemTimeZone = Temporal.ZonedDateTime.now();
console.log(`Waktu saat ini (sistem): ${nowInSystemTimeZone.toString()}`);
// Contoh output: 2023-10-27T14:30:45.123456789+02:00[Europe/Berlin]

// Dapatkan ZonedDateTime saat ini secara eksplisit untuk 'Europe/London'
const nowInLondon = Temporal.ZonedDateTime.now('Europe/London');
console.log(`Waktu saat ini (London): ${nowInLondon.toString()}`);
// Contoh output: 2023-10-27T13:30:45.123456789+01:00[Europe/London]

// Dapatkan ZonedDateTime saat ini secara eksplisit untuk 'Asia/Tokyo'
const nowInTokyo = Temporal.ZonedDateTime.now('Asia/Tokyo');
console.log(`Waktu saat ini (Tokyo): ${nowInTokyo.toString()}`);
// Contoh output: 2023-10-27T21:30:45.123456789+09:00[Asia/Tokyo]

            

              
                Copy
              
            
          

Perhatikan bagaimana now() memberi Anda instan saat ini, tetapi memformatnya sesuai dengan zona waktu yang ditentukan, termasuk offset yang benar pada saat itu.

2. Dari Komponen Spesifik

Anda dapat membuat ZonedDateTime dengan menyediakan komponen tanggal dan waktu individualnya, bersama dengan zona waktu yang diinginkan. Ini sering dilakukan menggunakan metode statis from().

            
// Tentukan PlainDateTime untuk acara tertentu
const plainDateTime = Temporal.PlainDateTime.from({ year: 2024, month: 3, day: 15, hour: 9, minute: 0 });

// Buat ZonedDateTime untuk acara ini di New York
const eventInNewYork = Temporal.ZonedDateTime.from({
  plainDateTime: plainDateTime,
  timeZone: 'America/New_York',
});
console.log(`Acara di New York: ${eventInNewYork.toString()}`);
// Output yang diharapkan: 2024-03-15T09:00:00-04:00[America/New_York] (dengan asumsi DST aktif di bulan Maret)

// Buat acara yang sama di Mumbai, India
const eventInMumbai = Temporal.ZonedDateTime.from({
  year: 2024, month: 3, day: 15, hour: 9, minute: 0,
  timeZone: 'Asia/Kolkata' // ID IANA untuk Mumbai/India
});
console.log(`Acara di Mumbai: ${eventInMumbai.toString()}`);
// Output yang diharapkan: 2024-03-15T09:00:00+05:30[Asia/Kolkata]

            

              
                Copy
              
            
          

Metode ini secara eksplisit menyatakan waktu jam dinding dan zona waktu tempatnya, menghilangkan semua ambiguitas.

3. Dari PlainDateTime dan TimeZone

Jika Anda sudah memiliki Temporal.PlainDateTime (tanggal dan waktu tanpa zona waktu), Anda dapat dengan mudah mengubahnya menjadi ZonedDateTime dengan menentukan zona waktu.

            
// PlainDateTime yang mewakili jam 5 sore pada 1 November 2024
const fivePMMarch1st = Temporal.PlainDateTime.from('2024-11-01T17:00:00');

// Ubah ini menjadi ZonedDateTime di Sydney, Australia
const sydneyTime = fivePMMarch1st.toZonedDateTime('Australia/Sydney');
console.log(`Waktu Sydney: ${sydneyTime.toString()}`);
// Output yang diharapkan: 2024-11-01T17:00:00+11:00[Australia/Sydney] (Sydney seharusnya menggunakan DST pada bulan November)

// Ubah PlainDateTime yang sama menjadi ZonedDateTime di Sao Paulo, Brazil
const saoPauloTime = fivePMMarch1st.toZonedDateTime('America/Sao_Paulo');
console.log(`Waktu Sao Paulo: ${saoPauloTime.toString()}`);
// Output yang diharapkan: 2024-11-01T17:00:00-03:00[America/Sao_Paulo] (Sao Paulo seharusnya menggunakan waktu standar pada bulan November)

            

              
                Copy
              
            
          

Objek PlainDateTime tidak berubah; sebaliknya, ia diinterpretasikan dalam konteks zona waktu baru.

4. Dari Instant dan TimeZone

Instant mewakili titik waktu global dan universal. Anda dapat mengonversi Instant menjadi ZonedDateTime dengan menyediakan zona waktu target, yang secara efektif mengatakan, "Jam dan tanggal berapa di zona waktu ini pada instan universal itu?"

            
// Instan waktu tertentu (misalnya, acara yang dicatat secara global)
const globalInstant = Temporal.Instant.from('2023-10-27T12:00:00Z'); // 12 siang UTC

// Tampilkan instan ini di Berlin
const berlinTime = globalInstant.toZonedDateTime('Europe/Berlin');
console.log(`Waktu Berlin: ${berlinTime.toString()}`);
// Output yang diharapkan: 2023-10-27T14:00:00+02:00[Europe/Berlin]

// Tampilkan instan yang sama di Mexico City
const mexicoCityTime = globalInstant.toZonedDateTime('America/Mexico_City');
console.log(`Waktu Mexico City: ${mexicoCityTime.toString()}`);
// Output yang diharapkan: 2023-10-27T06:00:00-06:00[America/Mexico_City]

            

              
                Copy
              
            
          

Ini penting untuk menampilkan acara yang disimpan dalam UTC kepada pengguna dalam konteks lokal mereka.

5. Parsing String

Temporal.ZonedDateTime juga dapat mengurai format string tertentu, terutama format ISO 8601 yang diperluas yang mencakup informasi zona waktu.

            
// String dengan zona waktu dan offset eksplisit
const parisMeeting = Temporal.ZonedDateTime.from('2023-12-25T09:30:00+01:00[Europe/Paris]');
console.log(`Rapat Paris: ${parisMeeting.toString()}`);
// Output yang diharapkan: 2023-12-25T09:30:00+01:00[Europe/Paris]

// String hanya dengan zona waktu, Temporal akan menentukan offset yang benar
const dubaiLaunch = Temporal.ZonedDateTime.from('2024-01-15T14:00:00[Asia/Dubai]');
console.log(`Peluncuran Dubai: ${dubaiLaunch.toString()}`);
// Output yang diharapkan: 2024-01-15T14:00:00+04:00[Asia/Dubai]

            

              
                Copy
              
            
          

Parsing ini kuat dan terstandarisasi, tidak seperti objek Date lawas, membuatnya andal untuk menyerap data tanggal/waktu dari berbagai sumber.

Melakukan Perhitungan Sadar Zona Waktu

Kekuatan sejati ZonedDateTime bersinar saat melakukan perhitungan. Sifat immutable Temporal dan penanganan eksplisit zona waktu berarti bahwa operasi dapat diprediksi dan akurat, bahkan di seluruh skenario kompleks seperti transisi DST.

1. Menambah dan Mengurangi Durasi

Anda dapat menambah atau mengurangi objek Temporal.Duration ke ZonedDateTime. Perhitungan akan dengan benar mematuhi aturan zona waktu terkait, termasuk DST.

            
// Waktu mulai: 9 Maret 2024, jam 10 pagi di New York (sebelum DST maju)
const startTimeNY = Temporal.ZonedDateTime.from('2024-03-09T10:00:00[America/New_York]');
console.log(`Waktu Mulai (NY): ${startTimeNY.toString()}`); // 2024-03-09T10:00:00-05:00[America/New_York]

// Tambahkan 2 hari dan 5 jam. DST di NY biasanya maju pada awal Maret.
const durationToAdd = Temporal.Duration.from({ days: 2, hours: 5 });
const endTimeNY = startTimeNY.add(durationToAdd);
console.log(`Waktu Selesai (NY): ${endTimeNY.toString()}`);
// Output yang diharapkan: 2024-03-11T16:00:00-04:00[America/New_York]
// Penjelasan: 10 Maret adalah transisi DST. Menambahkan 2 hari + 5 jam, jam melompat ke depan.
// Perhitungan dengan benar memperhitungkan jam yang hilang selama transisi DST.

// Contoh di zona waktu yang tidak menerapkan DST (misalnya, Asia/Shanghai)
const startTimeShanghai = Temporal.ZonedDateTime.from('2024-03-09T10:00:00[Asia/Shanghai]');
console.log(`Waktu Mulai (Shanghai): ${startTimeShanghai.toString()}`); // 2024-03-09T10:00:00+08:00[Asia/Shanghai]
const endTimeShanghai = startTimeShanghai.add(durationToAdd);
console.log(`Waktu Selesai (Shanghai): ${endTimeShanghai.toString()}`);
// Output yang diharapkan: 2024-03-11T15:00:00+08:00[Asia/Shanghai] (Tidak perlu penyesuaian DST)

            

              
                Copy
              
            
          

Penanganan DST otomatis ini adalah pengubah permainan, menghilangkan sumber utama bug.

2. Mengubah Zona Waktu (Konversi Waktu)

Salah satu operasi global yang paling sering adalah mengonversi momen tertentu di satu zona waktu ke zona waktu lain. ZonedDateTime membuat ini mudah dengan metode withTimeZone().

            
// Rapat dijadwalkan pukul 9:00 pagi di Paris pada 10 Desember 2023
const meetingInParis = Temporal.ZonedDateTime.from('2023-12-10T09:00:00[Europe/Paris]');
console.log(`Rapat di Paris: ${meetingInParis.toString()}`);
// Output: 2023-12-10T09:00:00+01:00[Europe/Paris]

// Jam berapa rapat ini untuk rekan kerja di Tokyo?
const meetingInTokyo = meetingInParis.withTimeZone('Asia/Tokyo');
console.log(`Rapat di Tokyo: ${meetingInTokyo.toString()}`);
// Output: 2023-12-10T17:00:00+09:00[Asia/Tokyo] (9 pagi Paris + perbedaan 8 jam = 5 sore Tokyo)

// Dan untuk rekan kerja di Mexico City?
const meetingInMexicoCity = meetingInParis.withTimeZone('America/Mexico_City');
console.log(`Rapat di Mexico City: ${meetingInMexicoCity.toString()}`);
// Output: 2023-12-10T02:00:00-06:00[America/Mexico_City] (9 pagi Paris - perbedaan 7 jam = 2 pagi Mexico City)

            

              
                Copy
              
            
          

Instan yang mendasarinya (titik waktu universal) tetap sama; hanya representasinya (tanggal, waktu, dan offset) yang berubah untuk mencerminkan aturan zona waktu baru.

3. Membandingkan Objek ZonedDateTime

Membandingkan dua objek ZonedDateTime sangat mudah karena keduanya mewakili momen waktu yang tidak ambigu. Anda dapat menggunakan metode seperti equals(), before(), after(), dan Temporal.ZonedDateTime.compare() statis.

            
const eventA = Temporal.ZonedDateTime.from('2023-11-05T10:00:00[Europe/London]');
const eventB = Temporal.ZonedDateTime.from('2023-11-05T09:00:00[America/New_York]');

// Acara A (London) adalah 10:00 pagi (+00:00 atau +01:00 tergantung DST, mari asumsikan +00:00 untuk Nov)
// Acara B (New York) adalah 09:00 pagi (-04:00 atau -05:00 tergantung DST, mari asumsikan -05:00 untuk Nov)
// Jika London adalah GMT, maka Acara A secara efektif adalah 10:00 UTC.
// Jika New York adalah EST, maka Acara B secara efektif adalah 14:00 UTC (9 pagi + 5 jam).
// Jadi Acara A *sebelum* Acara B.

console.log(`Apakah acara sama? ${eventA.equals(eventB)}`); // false
console.log(`Apakah Acara A sebelum Acara B? ${eventA.before(eventB)}`); // true
console.log(`Apakah Acara A setelah Acara B? ${eventA.after(eventB)}`);   // false

const comparisonResult = Temporal.ZonedDateTime.compare(eventA, eventB);
console.log(`Hasil perbandingan (A vs B): ${comparisonResult}`); // -1 (A sebelum B)

            

              
                Copy
              
            
          

Ini menunjukkan bahwa perbandingan didasarkan pada instan universal yang sebenarnya, bukan hanya waktu jam dinding di zona waktu yang berpotensi berbeda.

4. Menangani Transisi Waktu Musim Panas (DST)

Salah satu aspek paling kompleks dari penanganan waktu adalah DST. ZonedDateTime secara inheren memahami dan menerapkan aturan DST untuk zona waktu yang ditentukan. Saat melakukan penambahan atau konversi, ia secara otomatis menyesuaikan offset.

Maju Cepat (Jam Melompat ke Depan)

            
// 10 Maret 2024, di New York, 1:30 pagi (30 menit sebelum DST dimulai)
const beforeSpringForward = Temporal.ZonedDateTime.from('2024-03-10T01:30:00[America/New_York]');
console.log(`Sebelum DST: ${beforeSpringForward.toString()}`); // 2024-03-10T01:30:00-05:00[America/New_York]

// Tambahkan 1 jam. Ini melewati batas DST (2:00 pagi menjadi 3:00 pagi).
const afterSpringForward = beforeSpringForward.add({ hours: 1 });
console.log(`Setelah DST (tambah 1 jam): ${afterSpringForward.toString()}`);
// Diharapkan: 2024-03-10T03:30:00-04:00[America/New_York]
// Jam secara efektif melompat dari 1:59:59 ke 3:00:00, jadi menambahkan satu jam ke 1:30 pagi akan menjadi 3:30 pagi.

            

              
                Copy
              
            
          

Mundur (Jam Melompat ke Belakang)

            
// 3 November 2024, di New York, 1:30 pagi (30 menit sebelum DST berakhir)
const beforeFallBack = Temporal.ZonedDateTime.from('2024-11-03T01:30:00[America/New_York]');
console.log(`Sebelum Mundur DST: ${beforeFallBack.toString()}`); // 2024-11-03T01:30:00-04:00[America/New_York]

// Tambahkan 1 jam. Ini melewati batas DST (2:00 pagi muncul dua kali).
const afterFallBack = beforeFallBack.add({ hours: 1 });
console.log(`Setelah DST (tambah 1 jam): ${afterFallBack.toString()}`);
// Diharapkan: 2024-11-03T01:30:00-05:00[America/New_York]
// Jam secara efektif beralih dari 1:59:59-04:00 ke 1:00:00-05:00. Jadi menambahkan 1 jam ke 1:30 pagi-04:00 menghasilkan 1:30 pagi-05:00.

            

              
                Copy
              
            
          

Temporal dengan benar menangani transisi kompleks ini, yang merupakan sumber utama bug pada objek Date lawas.

Disambiguasi untuk Waktu yang Ambigu/Tidak Ada

Selama transisi DST, waktu jam dinding bisa tidak ada (maju cepat) atau ambigu (mundur, di mana waktu tertentu terjadi dua kali). Temporal menyediakan opsi disambiguation saat mengonversi PlainDateTime ke ZonedDateTime:

• 'compatible' (default): Bertujuan untuk pemetaan yang paling alami. Untuk waktu yang tidak ada, ia 'maju' ke waktu valid berikutnya. Untuk waktu yang ambigu, ia memilih offset yang lebih awal.
• 'earlier': Selalu memilih waktu/offset valid yang lebih awal.
• 'later': Selalu memilih waktu/offset valid yang lebih lambat.
• 'reject': Melemparkan kesalahan jika waktunya tidak ada atau ambigu.

            
const ambiguousTime = Temporal.PlainDateTime.from('2024-11-03T01:30:00'); // 1:30 pagi selama Mundur
const timeZoneNY = 'America/New_York';

// Default (compatible) akan memilih offset yang lebih awal
const zdtCompatible = ambiguousTime.toZonedDateTime(timeZoneNY, { disambiguation: 'compatible' });
console.log(`Kompatibel (offset lebih awal): ${zdtCompatible.toString()}`); // 2024-11-03T01:30:00-04:00[America/New_York]

// Secara eksplisit memilih offset yang lebih lambat
const zdtLater = ambiguousTime.toZonedDateTime(timeZoneNY, { disambiguation: 'later' });
console.log(`Offset lebih lambat: ${zdtLater.toString()}`); // 2024-11-03T01:30:00-05:00[America/New_York]

// Tolak waktu yang ambigu
try {
  ambiguousTime.toZonedDateTime(timeZoneNY, { disambiguation: 'reject' });
} catch (e) {
  console.error(`Waktu ambigu ditolak: ${e.message}`); // Akan melempar jika waktu ambigu
}

            

              
                Copy
              
            
          

Tingkat kontrol ini penting untuk aplikasi yang memerlukan kepatuhan waktu yang ketat, seperti sistem keuangan.

5. Mengekstrak Komponen dan Memformat

Anda dapat dengan mudah mengekstrak komponen individual (tahun, bulan, hari, jam, dll.) dari ZonedDateTime. Saat menampilkan kepada pengguna, Anda biasanya ingin memformatnya menjadi string yang dapat dibaca manusia.

            
const exampleZDT = Temporal.ZonedDateTime.from('2024-07-20T14:30:00[Europe/Berlin]');

console.log(`Tahun: ${exampleZDT.year}`);      // 2024
console.log(`Bulan: ${exampleZDT.month}`);     // 7
console.log(`Hari: ${exampleZDT.day}`);         // 20
console.log(`Jam: ${exampleZDT.hour}`);       // 14
console.log(`Offset: ${exampleZDT.offset}`);   // +02:00
console.log(`ID Zona Waktu: ${exampleZDT.timeZoneId}`); // Europe/Berlin

// Untuk output yang dapat dibaca manusia, gunakan toLocaleString() (yang sadar lokal)
console.log(`Diformat (lokal default): ${exampleZDT.toLocaleString()}`);
// Contoh: 20.07.2024, 14:30:00 MESZ

// Atau dengan opsi spesifik untuk audiens global
console.log(exampleZDT.toLocaleString('en-US', { dateStyle: 'full', timeStyle: 'long' }));
// Contoh: Saturday, July 20, 2024 at 2:30:00 PM Central European Summer Time

// Atau untuk output yang lebih dapat dibaca mesin dan presisi, gunakan toString()
console.log(`String ISO: ${exampleZDT.toString()}`);
// Output: 2024-07-20T14:30:00+02:00[Europe/Berlin]

            

              
                Copy
              
            
          

toLocaleString() sangat kuat untuk mengadaptasi tampilan tanggal dan waktu ke berbagai konvensi budaya, memanfaatkan API Intl browser.

Skenario Global Umum dan Solusinya dengan ZonedDateTime

Mari kita lihat bagaimana ZonedDateTime memberikan solusi elegan untuk tantangan pengembangan global sehari-hari.

1. Menjadwalkan Rapat Lintas Benua

Tantangan klasik: mengoordinasikan rapat antara tim yang tersebar di seluruh dunia.

Masalah:

Seorang manajer proyek di Paris perlu menjadwalkan pembaruan status 30 menit dengan anggota tim di New York, Beijing, dan Sydney. Dia ingin memulainya pada jam 10:00 pagi waktu Paris pada hari Senin. Jam berapa itu untuk orang lain?

Solusi:

Tentukan waktu mulai rapat dalam waktu Paris menggunakan ZonedDateTime, lalu konversikan ke zona waktu anggota tim lainnya. Ini memastikan semua orang melihat waktu mulai lokal mereka yang benar.

            
const meetingDate = Temporal.PlainDate.from('2024-04-15'); // Hari Senin
const meetingTime = Temporal.PlainTime.from('10:00:00'); // 10:00 pagi

// 1. Tentukan waktu mulai rapat di Paris
const meetingStartParis = Temporal.ZonedDateTime.from({
  plainDateTime: Temporal.PlainDateTime.from({ year: 2024, month: 4, day: 15, hour: 10, minute: 0 }),
  timeZone: 'Europe/Paris'
});
console.log(`Rapat dimulai untuk Paris: ${meetingStartParis.toLocaleString('en-US', { timeStyle: 'short', dateStyle: 'medium', timeZoneName: 'short' })}`);
// Output: 4/15/2024, 10:00 AM CEST

// 2. Konversi untuk New York (America/New_York)
const meetingStartNY = meetingStartParis.withTimeZone('America/New_York');
console.log(`Rapat dimulai untuk New York: ${meetingStartNY.toLocaleString('en-US', { timeStyle: 'short', dateStyle: 'medium', timeZoneName: 'short' })}`);
// Output: 4/15/2024, 4:00 AM EDT (10 pagi Paris - perbedaan 6 jam = 4 pagi NY)

// 3. Konversi untuk Beijing (Asia/Shanghai dekat, digunakan sebagai zona waktu Tiongkok tipikal)
const meetingStartBeijing = meetingStartParis.withTimeZone('Asia/Shanghai');
console.log(`Rapat dimulai untuk Beijing: ${meetingStartBeijing.toLocaleString('en-US', { timeStyle: 'short', dateStyle: 'medium', timeZoneName: 'short' })}`);
// Output: 4/15/2024, 4:00 PM CST (10 pagi Paris + perbedaan 6 jam = 4 sore Beijing)

// 4. Konversi untuk Sydney (Australia/Sydney)
const meetingStartSydney = meetingStartParis.withTimeZone('Australia/Sydney');
console.log(`Rapat dimulai untuk Sydney: ${meetingStartSydney.toLocaleString('en-US', { timeStyle: 'short', dateStyle: 'medium', timeZoneName: 'short' })}`);
// Output: 4/16/2024, 12:00 AM AEST (10 pagi Paris + perbedaan 14 jam = 12 pagi hari berikutnya Sydney)

// Untuk menunjukkan waktu akhir rapat untuk Paris
const meetingEndParis = meetingStartParis.add({ minutes: 30 });
console.log(`Rapat berakhir untuk Paris: ${meetingEndParis.toLocaleString('en-US', { timeStyle: 'short', dateStyle: 'medium', timeZoneName: 'short' })}`);
// Output: 4/15/2024, 10:30 AM CEST

            

              
                Copy
              
            
          

Pendekatan ini menghilangkan semua tebakan, memberikan setiap peserta waktu rapat lokal mereka yang tepat.

2. Manajemen Acara dan Tiket

Menyelenggarakan acara online global, konser, atau webinar memerlukan waktu mulai yang jelas dan tidak ambigu bagi peserta di seluruh dunia.

Masalah:

Festival musik global online diiklankan akan dimulai pada "jam 8:00 malam pada 1 Agustus 2024" di London (Europe/London). Bagaimana Anda menampilkannya dengan benar kepada pengguna yang menjelajah dari Tokyo, Jepang, atau Rio de Janeiro, Brasil?

Solusi:

Simpan waktu mulai acara sebagai ZonedDateTime di zona waktu resminya. Saat pengguna melihat acara tersebut, konversikan ke zona waktu lokal browser mereka atau zona waktu yang telah mereka pilih secara eksplisit.

            
// Waktu mulai resmi festival di London
const festivalStartLondon = Temporal.ZonedDateTime.from('2024-08-01T20:00:00[Europe/London]');
console.log(`Mulai Festival Resmi (London): ${festivalStartLondon.toLocaleString('en-US', { dateStyle: 'full', timeStyle: 'long', timeZoneName: 'long' })}`);
// Output: Thursday, August 1, 2024 at 8:00:00 PM British Summer Time

// Dengan asumsi pengguna di Tokyo
const userTimeZoneTokyo = 'Asia/Tokyo';
const festivalStartTokyo = festivalStartLondon.withTimeZone(userTimeZoneTokyo);
console.log(`Untuk pengguna di Tokyo: ${festivalStartTokyo.toLocaleString('en-US', { dateStyle: 'full', timeStyle: 'long', timeZoneName: 'long' })}`);
// Output: Friday, August 2, 2024 at 4:00:00 AM Japan Standard Time

// Dengan asumsi pengguna di Rio de Janeiro
const userTimeZoneRio = 'America/Sao_Paulo'; // ID IANA untuk Rio/Brasil
const festivalStartRio = festivalStartLondon.withTimeZone(userTimeZoneRio);
console.log(`Untuk pengguna di Rio de Janeiro: ${festivalStartRio.toLocaleString('en-US', { dateStyle: 'full', timeStyle: 'long', timeZoneName: 'long' })}`);
// Output: Thursday, August 1, 2024 at 4:00:00 PM Brasilia Standard Time

            

              
                Copy
              
            
          

Ini memastikan bahwa pengguna selalu melihat waktu acara dilokalkan dengan benar ke konteks mereka, mencegah kebingungan dan acara yang terlewat.

3. Mencatat dan Mengaudit Transaksi Global

Untuk sistem yang memerlukan presisi kronologis absolut, seperti platform perdagangan keuangan atau aplikasi blockchain, setiap peristiwa harus diberi stempel waktu secara tidak ambigu.

Masalah:

Transaksi berasal dari berbagai pusat data regional, masing-masing dengan waktu server lokalnya sendiri. Bagaimana Anda memastikan jejak audit universal yang tidak ambigu?

Solusi:

Simpan waktu kanonis peristiwa sebagai Temporal.Instant (UTC). Saat menampilkan atau memproses log ini dalam konteks regional, konversikan Instant ke ZonedDateTime untuk zona waktu yang relevan.

            
// Sebuah transaksi terjadi pada momen universal tertentu
const transactionInstant = Temporal.Instant.from('2023-10-27T15:30:45.123456789Z');
console.log(`Instan Transaksi Universal: ${transactionInstant.toString()}`);
// Output: 2023-10-27T15:30:45.123456789Z

// Nanti, pengguna di Frankfurt perlu melihat kapan ini terjadi dalam waktu lokal mereka
const frankfurtTime = transactionInstant.toZonedDateTime('Europe/Berlin');
console.log(`Transaksi di Frankfurt: ${frankfurtTime.toLocaleString('en-US', { dateStyle: 'full', timeStyle: 'long', timeZoneName: 'long' })}`);
// Output: Friday, October 27, 2023 at 5:30:45 PM Central European Summer Time

// Pengguna di Singapura perlu melihatnya dalam waktu lokal mereka
const singaporeTime = transactionInstant.toZonedDateTime('Asia/Singapore');
console.log(`Transaksi di Singapura: ${singaporeTime.toLocaleString('en-US', { dateStyle: 'full', timeStyle: 'long', timeZoneName: 'long' })}`);
// Output: Friday, October 27, 2023 at 11:30:45 PM Singapore Standard Time

            

              
                Copy
              
            
          

Pola ini menyediakan kebenaran global (Instant) dan perspektif yang dilokalkan (ZonedDateTime), penting untuk audit dan pelaporan yang kuat.

4. Batas Waktu Pesanan E-commerce

Menetapkan batas waktu untuk promosi, pengiriman hari yang sama, atau penawaran khusus untuk basis pelanggan global.

Masalah:

Situs e-commerce menawarkan "Pesan sebelum jam 5:00 sore hari ini untuk pengiriman hari berikutnya." Batas waktu ini perlu dilokalkan untuk pelanggan di berbagai wilayah.

Solusi:

Tentukan batas waktu kanonis dalam zona waktu bisnis tertentu. Untuk setiap pelanggan, konversikan batas waktu ini ke zona waktu lokal mereka dan hitung waktu yang tersisa.

            
// Tentukan waktu batas harian di zona waktu pusat pemenuhan (misalnya, Waktu Timur AS)
const cutoffTimePlain = Temporal.PlainTime.from('17:00:00'); // 5 sore
const todayInFulfillment = Temporal.ZonedDateTime.now('America/New_York');
const todayDate = todayInFulfillment.toPlainDate();

const dailyCutoffNY = Temporal.ZonedDateTime.from({
  plainDate: todayDate,
  plainTime: cutoffTimePlain,
  timeZone: 'America/New_York'
});
console.log(`Batas harian (New York): ${dailyCutoffNY.toLocaleString('en-US', { timeStyle: 'short', dateStyle: 'medium', timeZoneName: 'short' })}`);

// Untuk pelanggan di Los Angeles (America/Los_Angeles)
const customerLA = dailyCutoffNY.withTimeZone('America/Los_Angeles');
console.log(`Pelanggan di Los Angeles: Pesan sebelum ${customerLA.toLocaleString('en-US', { timeStyle: 'short', dateStyle: 'medium', timeZoneName: 'short' })}`);
// Output akan menunjukkan 2:00 PM untuk pelanggan LA untuk instan batas waktu yang sama.

// Untuk pelanggan di London (Europe/London)
const customerLondon = dailyCutoffNY.withTimeZone('Europe/London');
console.log(`Pelanggan di London: Pesan sebelum ${customerLondon.toLocaleString('en-US', { timeStyle: 'short', dateStyle: 'medium', timeZoneName: 'short' })}`);
// Output akan menunjukkan 10:00 PM untuk pelanggan London untuk instan batas waktu yang sama.

// Hitung waktu yang tersisa hingga batas waktu untuk pengguna di zona waktu lokal mereka (misalnya, Los Angeles)
const nowInLA = Temporal.ZonedDateTime.now('America/Los_Angeles');
const timeRemaining = nowInLA.until(customerLA);
console.log(`Waktu tersisa untuk pelanggan LA: ${timeRemaining.toString()}`);

            

              
                Copy
              
            
          

Skenario ini menyoroti bagaimana ZonedDateTime memungkinkan Anda untuk mendefinisikan satu aturan bisnis yang konsisten dan kemudian menyajikannya secara akurat dalam berbagai konteks lokal.

Praktik Terbaik Menggunakan ZonedDateTime dalam Aplikasi Global

Untuk memaksimalkan manfaat Temporal.ZonedDateTime dan memastikan aplikasi Anda benar-benar siap untuk global, pertimbangkan praktik terbaik ini:

• Simpan Momen Waktu-Agnostik sebagai Temporal.Instant (UTC): Untuk setiap peristiwa yang mewakili satu titik waktu universal, selalu simpan sebagai Temporal.Instant (yang secara intrinsik adalah UTC). Ini adalah "sumber kebenaran" Anda. Hanya konversi ke ZonedDateTime saat Anda perlu melakukan perhitungan sadar zona waktu atau menampilkannya dalam konteks spesifik pengguna.

              
  // Simpan di database
  const eventTimestamp = Temporal.Instant.now(); // Selalu UTC
  // Ambil dari database
  const retrievedInstant = Temporal.Instant.from('2023-10-27T15:30:45.123456789Z');
      
              
  
                
                  Copy
                
              
            

• Gunakan ZonedDateTime untuk Tampilan yang Menghadap Pengguna dan Logika Spesifik Zona Waktu: Saat Anda perlu menunjukkan tanggal dan waktu kepada pengguna, atau saat logika bisnis bergantung pada waktu jam dinding tertentu (misalnya, "buka jam 9 pagi waktu lokal"), ZonedDateTime adalah pilihan yang tepat. Konversikan Instant (sumber kebenaran Anda) ke zona waktu yang disukai pengguna menggunakan instant.toZonedDateTime(userTimeZone).

              
  const userTimeZone = Temporal.TimeZone.from('America/New_York');
  const displayTime = retrievedInstant.toZonedDateTime(userTimeZone);
  console.log(displayTime.toLocaleString('en-US', { dateStyle: 'medium', timeStyle: 'short' }));
      
              
  
                
                  Copy
                
              
            

• Definisikan Zona Waktu Secara Eksplisit: Jangan pernah mengandalkan default sistem untuk operasi kritis. Selalu berikan pengidentifikasi zona waktu IANA (misalnya, "Europe/London", "Asia/Shanghai") saat membuat atau mengonversi objek ZonedDateTime. Jika menampilkan kepada pengguna, tentukan zona waktu mereka baik dari API browser (Intl.DateTimeFormat().resolvedOptions().timeZone) atau dari pengaturan preferensi pengguna.

              
  // Baik: zona waktu eksplisit
  const specificZDT = Temporal.ZonedDateTime.from('2023-11-01T10:00:00[Europe/Berlin]');
  
  // Berpotensi bermasalah jika tidak diinginkan secara sengaja (tergantung pada konfigurasi sistem)
  // const implicitZDT = Temporal.ZonedDateTime.now();
      
              
  
                
                  Copy
                
              
            

• Waspadai Perubahan DST (Tapi Biarkan Temporal Menanganinya): Meskipun Temporal menangani DST secara otomatis, penting untuk memahami bagaimana hal itu memengaruhi durasi dan konversi waktu. Misalnya, menambahkan 24 jam selama "maju cepat" DST mungkin tidak menghasilkan waktu jam dinding yang sama pada hari berikutnya. Ini adalah perilaku yang benar, tetapi bisa mengejutkan jika tidak dipahami.
• Edukasi Tim Anda: Pastikan semua pengembang yang mengerjakan aplikasi global memahami berbagai tipe Temporal dan kapan harus menggunakan masing-masing. Kesalahpahaman dapat menyebabkan bug baru, bahkan dengan API yang unggul.
• Uji Secara Menyeluruh, Terutama di Sekitar Transisi DST: Buat kasus uji spesifik untuk waktu tepat sebelum, selama, dan setelah perubahan DST di berbagai zona waktu yang relevan dengan basis pengguna Anda. Uji konversi antara zona waktu yang berbeda secara signifikan.
• Pertimbangkan Preferensi Pengguna untuk Tampilan Zona Waktu: Meskipun Temporal.ZonedDateTime.now() dan Intl.DateTimeFormat().resolvedOptions().timeZone dapat memberi Anda zona waktu sistem pengguna, mengizinkan pengguna untuk secara eksplisit memilih zona waktu pilihan mereka dapat meningkatkan pengalaman mereka, terutama bagi mereka yang bepergian atau yang zona waktu sistemnya mungkin tidak mencerminkan preferensi aktual mereka.
• Manfaatkan Temporal.Calendar untuk Kalender Non-Gregorian (jika berlaku): Jika aplikasi Anda perlu melayani budaya yang menggunakan kalender non-Gregorian (misalnya, kalender Jepang, Islam, Buddha Thailand), ZonedDateTime juga dapat dibuat dengan kalender tertentu, memastikan representasi tanggal yang benar dalam sistem tersebut. Ini lebih lanjut meningkatkan inklusivitas global.

              
  const japaneseNewYear = Temporal.ZonedDateTime.from({
    year: 2024, month: 1, day: 1, hour: 0, minute: 0,
    timeZone: 'Asia/Tokyo', calendar: 'japanese'
  });
  console.log(japaneseNewYear.toLocaleString('ja-JP', { dateStyle: 'full', timeStyle: 'full', calendar: 'japanese' }));
      
              
  
                
                  Copy
                
              
            

Dukungan Browser dan Polyfill

Pada akhir 2023 / awal 2024, API Temporal berada di Tahap 3 dari proses TC39, yang berarti spesifikasinya sebagian besar stabil tetapi belum diimplementasikan secara universal di semua mesin browser secara default. Ini adalah area yang berkembang pesat, jadi penting untuk memeriksa tabel kompatibilitas terbaru.

Untuk penggunaan segera di lingkungan produksi, terutama untuk aplikasi global yang sangat penting, polyfill sangat disarankan. Polyfill Temporal resmi memungkinkan Anda untuk mulai menggunakan API hari ini di berbagai versi browser dan Node.js, memberikan perilaku yang konsisten hingga dukungan asli ada di mana-mana.

Anda dapat menemukan polyfill resmi dan informasi lebih lanjut tentang penggunaannya melalui npm:

            
npm install @js-temporal/polyfill

            

              
                Copy
              
            
          

Kemudian, biasanya di titik masuk aplikasi Anda:

            
import '@js-temporal/polyfill/global';
// Sekarang Anda bisa menggunakan Temporal secara langsung
const now = Temporal.ZonedDateTime.now('Europe/London');

            

              
                Copy
              
            
          

Selalu merujuk ke dokumentasi Temporal resmi dan repositori GitHub polyfill untuk instruksi instalasi dan penggunaan yang paling mutakhir.

Kesimpulan: Merangkul Temporal untuk Pengalaman Waktu Global yang Harmonis

Tantangan dalam menangani tanggal dan waktu dalam konteks global telah lama menjadi titik sakit bagi pengembang JavaScript. Objek Date lawas, dengan ambiguitas dan sifatnya yang dapat diubah, seringkali menyebabkan bug yang halus namun signifikan. Dengan munculnya API Temporal JavaScript, dan secara khusus Temporal.ZonedDateTime, kita sekarang memiliki alat yang kuat, eksplisit, dan andal untuk menaklukkan kompleksitas ini.

Dengan memahami komponen intinya dan memanfaatkan objeknya yang tidak dapat diubah, pengembang dapat dengan percaya diri melakukan perhitungan sadar zona waktu, mengonversi waktu lintas benua, menangani transisi Daylight Saving Time secara akurat, dan menyajikan informasi tanggal dan waktu secara tidak ambigu kepada pengguna di seluruh dunia. Baik Anda membangun platform e-commerce global, dasbor analitik waktu nyata, atau aplikasi penjadwalan kolaboratif, ZonedDateTime adalah aset yang sangat diperlukan untuk menciptakan perangkat lunak yang benar-benar terinternasionalisasi dan kuat.

Perjalanan menuju API tanggal/waktu yang lebih presisi dan intuitif di JavaScript sedang berjalan dengan baik. Mulailah menjelajahi Temporal hari ini, integrasikan ke dalam proyek Anda dengan bantuan polyfill, dan tingkatkan aplikasi Anda untuk memberikan pengalaman waktu yang harmonis dan sempurna bagi setiap pengguna, di mana pun.