M

MLOG

Bahasa Indonesia

Panduan mendalam tentang API Temporal JavaScript, solusi modern untuk menangani tanggal dan waktu secara efektif di berbagai konteks internasional.

API Temporal JavaScript: Penanganan Tanggal dan Waktu Modern untuk Audiens Global

Objek `Date` JavaScript telah lama menjadi sumber frustrasi bagi para pengembang. Sifatnya yang dapat diubah (mutable), API yang tidak konsisten, dan dukungan zona waktu yang buruk telah menyebabkan munculnya banyak pustaka seperti Moment.js dan date-fns untuk mengisi kekosongan tersebut. Sekarang, dengan API Temporal, JavaScript menawarkan solusi modern bawaan untuk menangani tanggal dan waktu dengan kejelasan dan presisi yang lebih baik. Artikel ini memberikan gambaran komprehensif tentang API Temporal, dengan fokus pada fitur, manfaat, dan penggunaannya dalam berbagai konteks internasional.

Apa itu API Temporal?

API Temporal adalah objek global baru di JavaScript yang dirancang untuk mengatasi kekurangan objek `Date`. API ini menyediakan API yang bersih dan tidak dapat diubah (immutable) untuk bekerja dengan tanggal, waktu, zona waktu, dan sistem kalender. Yang terpenting, API ini bertujuan untuk merepresentasikan konsep tanggal dan waktu dengan cara yang lebih selaras dengan penggunaan dan ekspektasi dunia nyata, membuat internasionalisasi menjadi jauh lebih mudah.

Fitur Utama:

Objek Dasar Temporal

API Temporal memperkenalkan beberapa jenis objek baru. Berikut adalah beberapa yang utama:

Bekerja dengan Tanggal

Membuat `Temporal.PlainDate`

Untuk membuat `Temporal.PlainDate`, Anda dapat menggunakan konstruktor:

const plainDate = new Temporal.PlainDate(2024, 10, 27); // Tahun, Bulan (1-12), Hari
console.log(plainDate.toString()); // Output: 2024-10-27

Anda juga dapat menggunakan metode `from`, yang menerima string dalam format ISO 8601:

const plainDateFromString = Temporal.PlainDate.from('2024-10-27');
console.log(plainDateFromString.toString()); // Output: 2024-10-27

Mendapatkan Komponen Tanggal

Anda dapat mengakses komponen tanggal individual menggunakan properti seperti `year`, `month`, dan `day`:

console.log(plainDate.year); // Output: 2024
console.log(plainDate.month); // Output: 10
console.log(plainDate.day); // Output: 27

Aritmetika Tanggal

Untuk menambah atau mengurangi hari, minggu, bulan, atau tahun, gunakan metode `plus` dan `minus`. Metode ini mengembalikan objek `Temporal.PlainDate` baru:

const nextWeek = plainDate.plus({ days: 7 });
console.log(nextWeek.toString()); // Output: 2024-11-03

const lastMonth = plainDate.minus({ months: 1 });
console.log(lastMonth.toString()); // Output: 2024-09-27

Membandingkan Tanggal

Anda dapat membandingkan tanggal menggunakan metode `compare`:

const date1 = new Temporal.PlainDate(2024, 10, 27);
const date2 = new Temporal.PlainDate(2024, 11, 15);

console.log(Temporal.PlainDate.compare(date1, date2)); // Output: -1 (date1 lebih awal dari date2)

Bekerja dengan Waktu

Membuat `Temporal.PlainTime`

Untuk membuat `Temporal.PlainTime`, gunakan konstruktor:

const plainTime = new Temporal.PlainTime(10, 30, 0); // Jam, Menit, Detik
console.log(plainTime.toString()); // Output: 10:30:00

Atau gunakan metode `from` dengan string waktu ISO 8601:

const plainTimeFromString = Temporal.PlainTime.from('10:30:00');
console.log(plainTimeFromString.toString()); // Output: 10:30:00

Mendapatkan Komponen Waktu

console.log(plainTime.hour); // Output: 10
console.log(plainTime.minute); // Output: 30
console.log(plainTime.second); // Output: 0

Aritmetika Waktu

const later = plainTime.plus({ minutes: 15 });
console.log(later.toString()); // Output: 10:45:00

Bekerja dengan Tanggal dan Waktu Bersamaan

Membuat `Temporal.PlainDateTime`

Anda dapat membuat `Temporal.PlainDateTime` secara langsung atau dengan menggabungkan `Temporal.PlainDate` dan `Temporal.PlainTime`:

const plainDateTime = new Temporal.PlainDateTime(2024, 10, 27, 10, 30, 0);
console.log(plainDateTime.toString()); // Output: 2024-10-27T10:30:00

const date = new Temporal.PlainDate(2024, 10, 27);
const time = new Temporal.PlainTime(10, 30, 0);
const combinedDateTime = date.toPlainDateTime(time);
console.log(combinedDateTime.toString()); // Output: 2024-10-27T10:30:00

Zona Waktu

Menangani zona waktu dengan benar sangat penting для aplikasi yang berurusan dengan pengguna di lokasi yang berbeda. API Temporal menyediakan dukungan zona waktu yang kuat melalui objek `Temporal.ZonedDateTime` dan `Temporal.TimeZone`.

Membuat `Temporal.ZonedDateTime`

Untuk membuat `Temporal.ZonedDateTime`, Anda memerlukan `Temporal.PlainDateTime` dan pengidentifikasi zona waktu. Pengidentifikasi zona waktu didasarkan pada basis data zona waktu IANA (misalnya, `America/Los_Angeles`, `Europe/London`, `Asia/Tokyo`).

const plainDateTime = new Temporal.PlainDateTime(2024, 10, 27, 10, 30, 0);
const timeZone = 'America/Los_Angeles';
const zonedDateTime = plainDateTime.toZonedDateTime(timeZone);
console.log(zonedDateTime.toString()); // Output: 2024-10-27T10:30:00-07:00[America/Los_Angeles] (Offset akan bergantung pada aturan DST)

Sebagai alternatif, buat `Temporal.ZonedDateTime` dari sebuah `Instant`.

const instant = Temporal.Instant.fromEpochSeconds(1666866600); // Contoh stempel waktu
const zonedDateTimeFromInstant = instant.toZonedDateTimeISO(timeZone); // Zona waktu seperti 'America/Los_Angeles'
console.log(zonedDateTimeFromInstant.toString());

Mengonversi Antar Zona Waktu

Anda dapat mengonversi `Temporal.ZonedDateTime` ke zona waktu yang berbeda menggunakan metode `withTimeZone`:

const newTimeZone = 'Europe/London';
const zonedDateTimeInLondon = zonedDateTime.withTimeZone(newTimeZone);
console.log(zonedDateTimeInLondon.toString()); // Output: 2024-10-27T18:30:00+01:00[Europe/London]

Bekerja dengan Offset Zona Waktu

Metode `getOffsetStringFor` dari objek `Temporal.TimeZone` menyediakan string offset untuk `Temporal.Instant` yang diberikan:

const timeZoneObject = new Temporal.TimeZone(timeZone);
const offsetString = timeZoneObject.getOffsetStringFor(zonedDateTime.toInstant());
console.log(offsetString); // Output: -07:00 (Tergantung pada aturan DST)

Sangat penting untuk menggunakan pengidentifikasi zona waktu IANA yang benar untuk perhitungan yang akurat. Pengidentifikasi ini dipelihara dan diperbarui secara berkala untuk mencerminkan perubahan waktu musim panas (daylight saving time) dan batas zona waktu.

Durasi

Objek `Temporal.Duration` merepresentasikan rentang waktu. Objek ini dapat digunakan untuk menambah atau mengurangi dari tanggal dan waktu.

Membuat `Temporal.Duration`

Anda dapat membuat `Temporal.Duration` menggunakan konstruktor, dengan menentukan tahun, bulan, hari, jam, menit, detik, milidetik, mikrodetik, dan nanodetik:

const duration = new Temporal.Duration(1, 2, 3, 4, 5, 6, 7, 8, 9); // Tahun, Bulan, Hari, Jam, Menit, Detik, Milidetik, Mikrodetik, Nanodetik
console.log(duration.toString()); // Output: P1Y2M3DT4H5M6.007008009S

Atau dengan menggunakan string durasi ISO 8601:

const durationFromString = Temporal.Duration.from('P1Y2M3DT4H5M6S');
console.log(durationFromString.toString()); // Output: P1Y2M3DT4H5M6S

Menambahkan Durasi ke Tanggal dan Waktu

const plainDate = new Temporal.PlainDate(2024, 10, 27);
const duration = new Temporal.Duration(0, 0, 7); // 7 hari
const newDate = plainDate.plus(duration);
console.log(newDate.toString()); // Output: 2024-11-03

Perhatikan bahwa menambahkan durasi yang melibatkan bulan atau tahun ke tanggal memerlukan pertimbangan yang cermat, karena jumlah hari dalam sebulan atau setahun dapat bervariasi.

Sistem Kalender

API Temporal mendukung sistem kalender yang berbeda selain kalender Gregorian. Ini sangat penting untuk aplikasi yang perlu menangani tanggal dalam berbagai konteks budaya. Meskipun dukungan masih berkembang, ini memberikan dasar untuk ekspansi di masa depan.

Menggunakan Kalender Alternatif

Untuk menggunakan kalender tertentu, Anda dapat menentukannya saat membuat objek Temporal:

const hebrewDate = new Temporal.PlainDate(5785, 1, 1, { calendar: 'hebrew' });
console.log(hebrewDate.toString()); // Output spesifik mungkin bervariasi tergantung pada implementasi dan pemformatan. Memerlukan polyfill di banyak lingkungan saat tulisan ini dibuat.

Penting: Dukungan untuk kalender non-Gregorian mungkin memerlukan polyfill atau dukungan browser/lingkungan tertentu. Periksa dokumentasi API Temporal dan tabel kompatibilitas browser untuk informasi terbaru.

Memformat Tanggal dan Waktu

Meskipun API Temporal berfokus pada manipulasi tanggal dan waktu, pemformatan biasanya ditangani oleh objek `Intl.DateTimeFormat`, yang merupakan bagian dari API Internasionalisasi. Objek temporal bekerja dengan lancar dengan `Intl.DateTimeFormat`.

Menggunakan `Intl.DateTimeFormat`

Berikut cara memformat `Temporal.PlainDate` menggunakan `Intl.DateTimeFormat`:

const plainDate = new Temporal.PlainDate(2024, 10, 27);
const formatter = new Intl.DateTimeFormat('en-US', { year: 'numeric', month: 'long', day: 'numeric' });
console.log(formatter.format(plainDate)); // Output: October 27, 2024

const formatterGerman = new Intl.DateTimeFormat('de-DE', { year: 'numeric', month: 'long', day: 'numeric' });
console.log(formatterGerman.format(plainDate)); // Output: 27. Oktober 2024

Anda dapat menyesuaikan opsi format sesuai kebutuhan Anda. Argumen pertama untuk `Intl.DateTimeFormat` adalah lokal, yang menentukan bahasa dan konvensi regional yang digunakan untuk pemformatan. Menggunakan lokal yang berbeda (misalnya, 'en-US', 'de-DE', 'fr-FR', 'ja-JP') menghasilkan format output yang berbeda.

Memformat `Temporal.ZonedDateTime`

Memformat `Temporal.ZonedDateTime` serupa, tetapi Anda juga dapat menyertakan informasi zona waktu dalam output:

const plainDateTime = new Temporal.PlainDateTime(2024, 10, 27, 10, 30, 0);
const timeZone = 'America/Los_Angeles';
const zonedDateTime = plainDateTime.toZonedDateTime(timeZone);

const formatter = new Intl.DateTimeFormat('en-US', { year: 'numeric', month: 'long', day: 'numeric', hour: 'numeric', minute: 'numeric', timeZoneName: 'short' });
console.log(formatter.format(zonedDateTime)); // Output: October 27, 2024, 10:30 AM PDT (Singkatan zona waktu tergantung pada aturan DST)

Praktik Terbaik Internasionalisasi

Saat bekerja dengan tanggal dan waktu dalam konteks global, perhatikan praktik terbaik berikut:

Perbandingan API Temporal dengan Objek Date Lama

Berikut adalah tabel yang menyoroti perbedaan utama dan keuntungan API Temporal dibandingkan dengan objek `Date` yang lama:

Fitur Objek `Date` Lama API Temporal
Mutabilitas Dapat diubah (memodifikasi objek asli) Tidak dapat diubah (mengembalikan objek baru)
Dukungan Zona Waktu Terbatas dan sering bermasalah Kuat dan akurat, berdasarkan basis data zona waktu IANA
API Tidak konsisten dan sulit digunakan Jelas, konsisten, dan intuitif
Presisi Milidetik Nanodetik
Sistem Kalender Terbatas pada Gregorian Mendukung sistem kalender alternatif (dengan dukungan yang terus berkembang)
Internasionalisasi Membutuhkan pustaka eksternal untuk internasionalisasi yang kuat Dukungan bawaan dan integrasi yang lancar dengan `Intl.DateTimeFormat`

Dukungan Browser dan Polyfill

Sebagai API yang relatif baru, dukungan browser untuk API Temporal masih terus berkembang. Periksa tabel kompatibilitas browser terbaru (misalnya, di MDN Web Docs) untuk melihat browser dan lingkungan mana yang mendukungnya secara native. Untuk browser atau lingkungan yang lebih lama tanpa dukungan native, Anda dapat menggunakan polyfill untuk menyediakan fungsionalitas API Temporal. Cari "Temporal API polyfill" di web untuk menemukan opsi yang sesuai.

Kesimpulan

API Temporal JavaScript merupakan langkah maju yang signifikan dalam menangani tanggal dan waktu di JavaScript. Sifatnya yang immutable, API yang jelas, dukungan zona waktu yang kuat, dan kemampuan sistem kalender menjadikannya alat yang ampuh bagi pengembang yang membangun aplikasi yang perlu bekerja dengan tanggal dan waktu secara akurat dan andal dalam berbagai konteks internasional. Meskipun dukungan browser masih berkembang, manfaat dari API Temporal membuatnya layak dipelajari dan diadopsi untuk proyek-proyek baru. Dengan merangkul API Temporal dan mengikuti praktik terbaik internasionalisasi, Anda dapat membuat aplikasi yang memberikan pengalaman tanggal dan waktu yang lancar dan akurat bagi pengguna di seluruh dunia.

Pembelajaran Lebih Lanjut