JavaScript Temporal API: Moderne Datum- en Tijdbehandeling voor een Wereldwijd Publiek

Het JavaScript `Date`-object is al lang een bron van frustratie voor ontwikkelaars. De veranderlijkheid, inconsistente API en slechte ondersteuning voor tijdzones hebben geleid tot talloze bibliotheken zoals Moment.js en date-fns om de leemtes op te vullen. Nu, met de Temporal API, biedt JavaScript een moderne, ingebouwde oplossing voor het omgaan met datums en tijden met verbeterde duidelijkheid en precisie. Dit artikel geeft een uitgebreid overzicht van de Temporal API, met de nadruk op de functies, voordelen en het gebruik in diverse internationale contexten.

Wat is de Temporal API?

De Temporal API is een nieuw, globaal object in JavaScript dat is ontworpen om de tekortkomingen van het `Date`-object aan te pakken. Het biedt een schone, onveranderlijke (immutable) API voor het werken met datums, tijden, tijdzones en kalendersystemen. Cruciaal is dat het tot doel heeft datum- en tijdconcepten weer te geven op een manier die beter aansluit bij het gebruik en de verwachtingen in de praktijk, waardoor internationalisering veel eenvoudiger wordt.

Belangrijkste Kenmerken:

• Onveranderlijkheid (Immutability): Temporal-objecten zijn onveranderlijk, wat betekent dat bewerkingen zoals het toevoegen van dagen of maanden nieuwe objecten retourneren in plaats van het origineel te wijzigen. Dit elimineert een veelvoorkomende bron van bugs en maakt code beter te beredeneren.
• Duidelijke API: Temporal biedt een consistente en intuïtieve API voor veelvoorkomende datum- en tijdbewerkingen.
• Ondersteuning voor Tijdzones: Temporal bevat robuuste ondersteuning voor tijdzones, waardoor u met datums en tijden op verschillende locaties kunt werken zonder de complexiteit van het oude `Date`-object. Het maakt gebruik van de IANA-tijdzonedatabase, wat zorgt voor accurate en actuele informatie.
• Kalendersystemen: Naast de Gregoriaanse kalender ondersteunt Temporal alternatieve kalendersystemen, om te voldoen aan de behoeften van diverse culturen en regio's.
• Verbeterde Precisie: Temporal biedt precisie op nanosecondeniveau, wat de beperkingen van het op milliseconden gebaseerde `Date`-object aanpakt.

Basis Temporal Objecten

De Temporal API introduceert verschillende nieuwe objecttypes. Hier zijn enkele van de belangrijkste:

• `Temporal.PlainDate`: Vertegenwoordigt een datum (jaar, maand, dag) zonder tijdzone.
• `Temporal.PlainTime`: Vertegenwoordigt een tijd (uur, minuut, seconde, milliseconde, microseconde, nanoseconde) zonder datum of tijdzone.
• `Temporal.PlainDateTime`: Vertegenwoordigt een datum en tijd zonder tijdzone.
• `Temporal.ZonedDateTime`: Vertegenwoordigt een datum en tijd met een specifieke tijdzone.
• `Temporal.Instant`: Vertegenwoordigt een specifiek moment in de tijd, gemeten in nanoseconden sinds de Unix epoch (1 januari 1970 UTC).
• `Temporal.TimeZone`: Vertegenwoordigt een tijdzone.
• `Temporal.Duration`: Vertegenwoordigt een tijdsduur (bijv. 2 uur, 30 minuten).
• `Temporal.YearMonth`: Vertegenwoordigt een jaar en maand.
• `Temporal.MonthDay`: Vertegenwoordigt een maand en dag.

Werken met Datums

Een `Temporal.PlainDate` Creëren

Om een `Temporal.PlainDate` te creëren, kunt u de constructor gebruiken:

const plainDate = new Temporal.PlainDate(2024, 10, 27); // Jaar, Maand (1-12), Dag
console.log(plainDate.toString()); // Output: 2024-10-27

U kunt ook de `from`-methode gebruiken, die een string in ISO 8601-formaat accepteert:

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

Datumcomponenten Ophalen

U kunt individuele datumcomponenten benaderen via eigenschappen zoals `year`, `month` en `day`:

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

Datumrekenen

Om dagen, weken, maanden of jaren op te tellen of af te trekken, gebruikt u de `plus`- en `minus`-methoden. Deze methoden retourneren een nieuw `Temporal.PlainDate`-object:

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

Datums Vergelijken

U kunt datums vergelijken met de `compare`-methode:

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 is eerder dan date2)

Werken met Tijden

Een `Temporal.PlainTime` Creëren

Om een `Temporal.PlainTime` te creëren, gebruikt u de constructor:

const plainTime = new Temporal.PlainTime(10, 30, 0); // Uur, Minuut, Seconde
console.log(plainTime.toString()); // Output: 10:30:00

Of gebruik de `from`-methode met een ISO 8601-tijdstring:

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

Tijdcomponenten Ophalen

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

Tijdrekenen

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

Werken met Datum en Tijd Samen

Een `Temporal.PlainDateTime` Creëren

U kunt een `Temporal.PlainDateTime` direct creëren of door een `Temporal.PlainDate` en een `Temporal.PlainTime` te combineren:

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

Tijdzones

Het correct omgaan met tijdzones is cruciaal voor applicaties die te maken hebben met gebruikers op verschillende locaties. De Temporal API biedt robuuste ondersteuning voor tijdzones via de `Temporal.ZonedDateTime`- en `Temporal.TimeZone`-objecten.

Een `Temporal.ZonedDateTime` Creëren

Om een `Temporal.ZonedDateTime` te creëren, heeft u een `Temporal.PlainDateTime` en een tijdzone-ID nodig. Tijdzone-ID's zijn gebaseerd op de IANA-tijdzonedatabase (bijv. `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] (De offset is afhankelijk van de regels voor zomertijd)

U kunt ook een `Temporal.ZonedDateTime` creëren vanuit een `Instant`.

const instant = Temporal.Instant.fromEpochSeconds(1666866600); // Voorbeeld timestamp
const zonedDateTimeFromInstant = instant.toZonedDateTimeISO(timeZone); // Tijdzone zoals 'America/Los_Angeles'
console.log(zonedDateTimeFromInstant.toString());

Converteren Tussen Tijdzones

U kunt een `Temporal.ZonedDateTime` naar een andere tijdzone converteren met de `withTimeZone`-methode:

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

Werken met Tijdzone-offsets

De `getOffsetStringFor`-methode van het `Temporal.TimeZone`-object geeft de offset-string voor een gegeven `Temporal.Instant`:

const timeZoneObject = new Temporal.TimeZone(timeZone);
const offsetString = timeZoneObject.getOffsetStringFor(zonedDateTime.toInstant());
console.log(offsetString); // Output: -07:00 (Afhankelijk van de regels voor zomertijd)

Het is essentieel om de juiste IANA-tijdzone-ID's te gebruiken voor nauwkeurige berekeningen. Deze ID's worden regelmatig onderhouden en bijgewerkt om veranderingen in zomertijd en tijdzonegrenzen weer te geven.

Tijdsduren (Durations)

Het `Temporal.Duration`-object vertegenwoordigt een tijdsduur. Het kan worden gebruikt om tijd op te tellen bij of af te trekken van datums en tijden.

Een `Temporal.Duration` Creëren

U kunt een `Temporal.Duration` creëren met de constructor, waarbij u de jaren, maanden, dagen, uren, minuten, seconden, milliseconden, microseconden en nanoseconden specificeert:

const duration = new Temporal.Duration(1, 2, 3, 4, 5, 6, 7, 8, 9); // Jaren, Maanden, Dagen, Uren, Minuten, Seconden, Milliseconden, Microseconden, Nanoseconden
console.log(duration.toString()); // Output: P1Y2M3DT4H5M6.007008009S

Of door een ISO 8601-duurstring te gebruiken:

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

Tijdsduren Toevoegen aan Datums en Tijden

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

Let op dat het toevoegen van tijdsduren met maanden of jaren aan datums zorgvuldige overweging vereist, aangezien het aantal dagen in een maand of jaar kan variëren.

Kalendersystemen

De Temporal API ondersteunt verschillende kalendersystemen naast de Gregoriaanse kalender. Dit is cruciaal voor applicaties die datums in verschillende culturele contexten moeten verwerken. Hoewel de ondersteuning nog in ontwikkeling is, biedt het een basis voor toekomstige uitbreiding.

Alternatieve Kalenders Gebruiken

Om een specifieke kalender te gebruiken, kunt u deze specificeren bij het creëren van Temporal-objecten:

const hebrewDate = new Temporal.PlainDate(5785, 1, 1, { calendar: 'hebrew' });
console.log(hebrewDate.toString()); // De specifieke output kan variëren afhankelijk van de implementatie en formattering. Vereist een polyfill in veel omgevingen op het moment van schrijven.

Belangrijk: Ondersteuning voor niet-Gregoriaanse kalenders kan polyfills of specifieke browser-/omgevingsondersteuning vereisen. Controleer de documentatie van de Temporal API en de compatibiliteitstabellen van browsers voor de meest recente informatie.

Datums en Tijden Formatteren

Hoewel de Temporal API zich richt op de manipulatie van datum en tijd, wordt de formattering doorgaans afgehandeld door het `Intl.DateTimeFormat`-object, dat deel uitmaakt van de Internationalization API. Temporal-objecten werken naadloos samen met `Intl.DateTimeFormat`.

`Intl.DateTimeFormat` Gebruiken

Hier ziet u hoe u een `Temporal.PlainDate` formatteert met `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

U kunt de formatteringsopties aanpassen aan uw behoeften. Het eerste argument van `Intl.DateTimeFormat` is de 'locale', die de taal en regionale conventies bepaalt die voor de formattering worden gebruikt. Het gebruik van verschillende locales (bijv. 'en-US', 'de-DE', 'fr-FR', 'ja-JP') levert verschillende outputformaten op.

`Temporal.ZonedDateTime` Formatteren

Het formatteren van `Temporal.ZonedDateTime` is vergelijkbaar, maar u kunt ook tijdzone-informatie in de output opnemen:

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 (De afkorting van de tijdzone is afhankelijk van de regels voor zomertijd)

Best Practices voor Internationalisering

Houd bij het werken met datums en tijden in een wereldwijde context rekening met de volgende best practices:

• Gebruik IANA Tijdzone-ID's: Gebruik altijd IANA-tijdzone-ID's (bijv. `America/Los_Angeles`, `Europe/London`) voor een nauwkeurige afhandeling van tijdzones.
• Houd Rekening met Zomertijd: Zomertijd (Daylight Saving Time, DST) kan de tijdzone-offsets beïnvloeden. De Temporal API handelt DST-overgangen automatisch af.
• Gebruik `Intl.DateTimeFormat` voor Formattering: Gebruik het `Intl.DateTimeFormat`-object voor het formatteren van datums en tijden volgens de locale van de gebruiker.
• Overweeg Kalendersystemen: Als uw applicatie gebruikers in verschillende culturele contexten moet ondersteunen, overweeg dan het gebruik van alternatieve kalendersystemen.
• Sla Datums en Tijden op in UTC: Bij het opslaan van datums en tijden in een database is het de best practice om ze in UTC (Coordinated Universal Time) op te slaan om tijdzoneproblemen te voorkomen. Converteer ze vervolgens naar de lokale tijd voor weergavedoeleinden. Temporal biedt methoden voor het converteren van en naar UTC.
• Test Grondig: Test uw applicatie met verschillende tijdzones, locales en kalendersystemen om ervoor te zorgen dat deze voor alle gebruikers correct werkt.

Vergelijking van de Temporal API met het Verouderde Date Object

Hier is een tabel die de belangrijkste verschillen en voordelen van de Temporal API benadrukt in vergelijking met het verouderde `Date`-object:

Kenmerk	Verouderd `Date` Object	Temporal API
Veranderlijkheid	Veranderlijk (past het originele object aan)	Onveranderlijk (geeft nieuwe objecten terug)
Ondersteuning voor Tijdzones	Beperkt en vaak problematisch	Robuust en accuraat, gebaseerd op de IANA-tijdzonedatabase
API	Inconsistent en moeilijk te gebruiken	Duidelijk, consistent en intuïtief
Precisie	Milliseconde	Nanoseconde
Kalendersystemen	Beperkt tot Gregoriaans	Ondersteunt alternatieve kalendersystemen (met evoluerende ondersteuning)
Internationalisering	Vereist externe bibliotheken voor robuuste internationalisering	Ingebouwde ondersteuning en naadloze integratie met `Intl.DateTimeFormat`

Browserondersteuning en Polyfills

Als een relatief nieuwe API is de browserondersteuning voor de Temporal API nog in ontwikkeling. Controleer de nieuwste compatibiliteitstabellen van browsers (bijv. op MDN Web Docs) om te zien welke browsers en omgevingen dit native ondersteunen. Voor oudere browsers of omgevingen zonder native ondersteuning kunt u polyfills gebruiken om de functionaliteit van de Temporal API te bieden. Zoek op het web naar "Temporal API polyfill" om geschikte opties te vinden.

Conclusie

De JavaScript Temporal API vertegenwoordigt een aanzienlijke vooruitgang in het omgaan met datums en tijden in JavaScript. De onveranderlijkheid, duidelijke API, robuuste ondersteuning voor tijdzones en de mogelijkheden voor kalendersystemen maken het een krachtig hulpmiddel voor ontwikkelaars die applicaties bouwen die nauwkeurig en betrouwbaar met datums en tijden moeten werken in diverse internationale contexten. Hoewel de browserondersteuning nog in ontwikkeling is, maken de voordelen van de Temporal API het de moeite waard om te leren en te adopteren voor nieuwe projecten. Door de Temporal API te omarmen en de best practices voor internationalisering te volgen, kunt u applicaties creëren die een naadloze en nauwkeurige datum- en tijdervaring bieden aan gebruikers over de hele wereld.

Verder Leren

• Officiële Documentatie van de Temporal API
• MDN Web Docs over Temporal