API JavaScript Temporal : Manipulation moderne des dates et heures

L'objet Date de JavaScript a longtemps été une source de frustration pour les développeurs. Sa mutabilité, son manque de support natif des fuseaux horaires et son API maladroite ont conduit à d'innombrables bibliothèques et solutions de contournement. Heureusement, l'API Temporal vise à remédier à ces lacunes, en fournissant une solution moderne, intuitive et consciente des fuseaux horaires pour la manipulation des dates et heures en JavaScript.

Qu'est-ce que l'API Temporal ?

L'API Temporal est un nouvel objet global, Temporal, qui offre une manière moderne et standardisée de travailler avec les dates et heures en JavaScript. Elle est conçue pour remplacer l'ancien objet Date, offrant des améliorations significatives en termes de conception d'API, d'immutabilité, de support des fuseaux horaires et d'utilisabilité générale. Elle fait partie de la proposition ECMAScript et est implémentée dans les principaux moteurs JavaScript.

Avantages clés de l'API Temporal :

• Immutabilité : Les objets Temporal sont immuables, ce qui signifie que les opérations sur eux retournent de nouveaux objets au lieu de modifier l'original. Cela permet d'éviter les effets secondaires imprévus et rend le code plus facile à raisonner.
• API claire : L'API est conçue pour être plus intuitive et cohérente que l'ancien objet Date.
• Support des fuseaux horaires : Temporal offre un support robuste des fuseaux horaires, vous permettant de travailler avec des dates et heures dans différentes régions du monde.
• Support des calendriers : Au-delà du calendrier grégorien, l'API permet d'utiliser d'autres systèmes de calendrier, facilitant les applications mondiales.
• Gestion des secondes intercalaires : L'API Temporal prend en compte les secondes intercalaires, fournissant des calculs d'heure plus précis.

Premiers pas avec Temporal

Bien que l'API Temporal soit encore en développement et pas encore entièrement prise en charge dans tous les navigateurs et environnements Node.js, vous pouvez utiliser un polyfill pour commencer à l'expérimenter dès aujourd'hui. Vous pouvez installer le polyfill via npm :

            npm install @js-temporal/polyfill
            

              
                Copy
              
            
          

Ensuite, importez le polyfill dans votre code JavaScript :

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

              
                Copy
              
            
          

Une fois le polyfill installé, vous pouvez commencer à utiliser l'objet Temporal et ses différentes classes.

Classes Temporal principales

L'API Temporal fournit plusieurs classes clés pour travailler avec les dates et heures :

• Temporal.PlainDate : Représente une date calendaire (année, mois et jour) sans aucune information de fuseau horaire ou d'heure.
• Temporal.PlainTime : Représente une heure de la journée (heure, minute, seconde et fraction de seconde) sans aucune information de date ou de fuseau horaire.
• Temporal.PlainDateTime : Représente une date et une heure sans aucune information de fuseau horaire.
• Temporal.ZonedDateTime : Représente une date et une heure avec un fuseau horaire spécifique.
• Temporal.Instant : Représente un point spécifique dans le temps, mesuré en nanosecondes depuis l'époque Unix (1er janvier 1970, à 00:00:00 Temps Universel Coordonné (UTC)).
• Temporal.TimeZone : Représente un fuseau horaire.
• Temporal.Duration : Représente une durée de temps, telle que des heures, des minutes ou des secondes.
• Temporal.Now : Fournit l'accès à la date et à l'heure actuelles.

Travailler avec PlainDate

La classe Temporal.PlainDate représente une date sans aucune information de fuseau horaire ou d'heure. Elle est utile pour représenter des anniversaires ou d'autres événements basés sur la date.

Créer un PlainDate :

            const plainDate = Temporal.PlainDate.from({ year: 2024, month: 10, day: 26 });
console.log(plainDate.toString()); // Sortie : 2024-10-26
            

              
                Copy
              
            
          

Vous pouvez également créer un PlainDate à partir d'une chaîne au format ISO 8601 :

            const plainDateFromString = Temporal.PlainDate.from('2024-12-25');
console.log(plainDateFromString.toString()); // Sortie : 2024-12-25
            

              
                Copy
              
            
          

Accéder aux composants de la date :

            const year = plainDate.year; // 2024
const month = plainDate.month; // 10
const day = plainDate.day;   // 26
const dayOfWeek = plainDate.dayOfWeek; // Jour de la semaine (1-7, Lundi-Dimanche)
const dayOfYear = plainDate.dayOfYear; // Jour de l'année (1-366)
const daysInMonth = plainDate.daysInMonth; // Nombre de jours dans le mois
const isLeapYear = plainDate.isLeapYear;   // Booléen indiquant si l'année est bissextile
            

              
                Copy
              
            
          

Ajouter et soustraire des jours :

            const nextDay = plainDate.add({ days: 1 });
console.log(nextDay.toString()); // Sortie : 2024-10-27

const previousWeek = plainDate.subtract({ weeks: 1 });
console.log(previousWeek.toString()); // Sortie : 2024-10-19
            

              
                Copy
              
            
          

Comparer des dates :

            const anotherDate = Temporal.PlainDate.from({ year: 2024, month: 11, day: 15 });

if (plainDate.equals(anotherDate)) {
  console.log('Les dates sont égales');
} else if (plainDate.lessThan(anotherDate)) {
  console.log('plainDate est antérieure à anotherDate');
} else {
  console.log('plainDate est postérieure à anotherDate');
}
// Sortie : plainDate est antérieure à anotherDate
            

              
                Copy
              
            
          

Travailler avec PlainTime

La classe Temporal.PlainTime représente une heure de la journée sans aucune information de date ou de fuseau horaire. Elle est utile pour représenter les heures d'ouverture, les heures de réunion ou d'autres événements basés sur l'heure.

Créer un PlainTime :

            const plainTime = Temporal.PlainTime.from({ hour: 14, minute: 30, second: 0 });
console.log(plainTime.toString()); // Sortie : 14:30:00
            

              
                Copy
              
            
          

Vous pouvez également créer un PlainTime à partir d'une chaîne au format ISO 8601 :

            const plainTimeFromString = Temporal.PlainTime.from('09:00:00');
console.log(plainTimeFromString.toString()); // Sortie : 09:00:00
            

              
                Copy
              
            
          

Accéder aux composants de l'heure :

            const hour = plainTime.hour;   // 14
const minute = plainTime.minute; // 30
const second = plainTime.second; // 0
const millisecond = plainTime.millisecond; // 0
const microsecond = plainTime.microsecond; // 0
const nanosecond = plainTime.nanosecond;   // 0
            

              
                Copy
              
            
          

Ajouter et soustraire du temps :

            const laterTime = plainTime.add({ minutes: 15 });
console.log(laterTime.toString()); // Sortie : 14:45:00

const earlierTime = plainTime.subtract({ hours: 1 });
console.log(earlierTime.toString()); // Sortie : 13:30:00
            

              
                Copy
              
            
          

Comparer des heures :

            const anotherTime = Temporal.PlainTime.from({ hour: 15, minute: 0, second: 0 });

if (plainTime.equals(anotherTime)) {
  console.log('Les heures sont égales');
} else if (plainTime.lessThan(anotherTime)) {
  console.log('plainTime est antérieure à anotherTime');
} else {
  console.log('plainTime est postérieure à anotherTime');
}
// Sortie : plainTime est antérieure à anotherTime
            

              
                Copy
              
            
          

Travailler avec PlainDateTime

La classe Temporal.PlainDateTime représente une date et une heure sans aucune information de fuseau horaire. Elle combine les fonctionnalités de PlainDate et PlainTime.

Créer un PlainDateTime :

            const plainDateTime = Temporal.PlainDateTime.from({ year: 2024, month: 10, day: 26, hour: 14, minute: 30, second: 0 });
console.log(plainDateTime.toString()); // Sortie : 2024-10-26T14:30:00
            

              
                Copy
              
            
          

Vous pouvez également créer un PlainDateTime à partir d'une chaîne au format ISO 8601 :

            const plainDateTimeFromString = Temporal.PlainDateTime.from('2024-12-25T09:00:00');
console.log(plainDateTimeFromString.toString()); // Sortie : 2024-12-25T09:00:00
            

              
                Copy
              
            
          

Accéder aux composants de date et d'heure :

            const year = plainDateTime.year;   // 2024
const month = plainDateTime.month; // 10
const day = plainDateTime.day;     // 26
const hour = plainDateTime.hour;   // 14
const minute = plainDateTime.minute; // 30
const second = plainDateTime.second; // 0
            

              
                Copy
              
            
          

Ajouter et soustraire des dates et heures :

            const nextDayAndTime = plainDateTime.add({ days: 1, hours: 2 });
console.log(nextDayAndTime.toString()); // Sortie : 2024-10-27T16:30:00

const previousWeekAndTime = plainDateTime.subtract({ weeks: 1, minutes: 30 });
console.log(previousWeekAndTime.toString()); // Sortie : 2024-10-19T14:00:00
            

              
                Copy
              
            
          

Convertir en PlainDate et PlainTime :

            const plainDateFromDateTime = plainDateTime.toPlainDate();
console.log(plainDateFromDateTime.toString()); // Sortie : 2024-10-26

const plainTimeFromDateTime = plainDateTime.toPlainTime();
console.log(plainTimeFromDateTime.toString()); // Sortie : 14:30:00
            

              
                Copy
              
            
          

Travailler avec ZonedDateTime

La classe Temporal.ZonedDateTime représente une date et une heure avec un fuseau horaire spécifique. Ceci est crucial pour les applications qui doivent gérer des dates et heures dans différentes régions du monde. Contrairement à l'objet Date obsolète, Temporal fournit un support natif des fuseaux horaires.

Créer un ZonedDateTime :

            const zonedDateTime = Temporal.ZonedDateTime.from({ year: 2024, month: 10, day: 26, hour: 14, minute: 30, second: 0, timeZone: 'America/Los_Angeles' });
console.log(zonedDateTime.toString()); // Sortie : 2024-10-26T14:30:00-07:00[America/Los_Angeles]
            

              
                Copy
              
            
          

Vous pouvez également créer un ZonedDateTime à partir d'un Instant et d'un fuseau horaire :

            const instant = Temporal.Instant.fromEpochSeconds(1666785000); // Horodatage exemple
const zonedDateTimeFromInstant = instant.toZonedDateTimeISO('Europe/London');
console.log(zonedDateTimeFromInstant.toString()); // La sortie variera en fonction de l'instant mais reflétera la date/heure en Europe/Londres
            

              
                Copy
              
            
          

Accéder aux composants de date et d'heure :

            const year = zonedDateTime.year;   // 2024
const month = zonedDateTime.month; // 10
const day = zonedDateTime.day;     // 26
const hour = zonedDateTime.hour;   // 14
const minute = zonedDateTime.minute; // 30
const second = zonedDateTime.second; // 0
const timeZone = zonedDateTime.timeZone; // Objet Temporal.TimeZone
            

              
                Copy
              
            
          

Convertir entre les fuseaux horaires :

            const newYorkDateTime = zonedDateTime.withTimeZone('America/New_York');
console.log(newYorkDateTime.toString()); // Sortie : 2024-10-26T17:30:00-04:00[America/New_York]
            

              
                Copy
              
            
          

Gérer l'heure d'été (DST) :

Temporal gère automatiquement les transitions de l'heure d'été. Lors de l'ajout ou de la soustraction de temps, il prend en compte l'heure d'été, garantissant des résultats précis. Par exemple, considérons une réunion prévue lors de la transition de l'heure d'été en Allemagne :

            const meetingStart = Temporal.ZonedDateTime.from({ year: 2024, month: 3, day: 31, hour: 2, minute: 30, timeZone: 'Europe/Berlin' });
const meetingEnd = meetingStart.add({ hours: 1 }); // Ajout de 1 heure
console.log(meetingEnd.toString()); // Sortie : 2024-03-31T03:30:00+02:00[Europe/Berlin]. Notez que le décalage change en raison de l'heure d'été.
            

              
                Copy
              
            
          

Travailler avec Instant

La classe Temporal.Instant représente un point spécifique dans le temps, mesuré en nanosecondes depuis l'époque Unix. Elle est utile pour stocker et comparer des moments exacts.

Créer un Instant :

            const instant = Temporal.Instant.fromEpochSeconds(1666785000); // Horodatage Unix en secondes (exemple)
console.log(instant.toString()); // La sortie sera une représentation sous forme de chaîne ISO de cet instant
            

              
                Copy
              
            
          

Convertir en ZonedDateTime :

            const zonedDateTimeFromInstant = instant.toZonedDateTimeISO('America/Los_Angeles');
console.log(zonedDateTimeFromInstant.toString()); // Sortie : Date et heure en America/Los_Angeles correspondant à l'instant
            

              
                Copy
              
            
          

Comparer des Instants :

            const anotherInstant = Temporal.Instant.fromEpochSeconds(1666790000);

if (instant.equals(anotherInstant)) {
  console.log('Les Instants sont égaux');
} else if (instant.lessThan(anotherInstant)) {
  console.log('instant est antérieur à anotherInstant');
} else {
  console.log('instant est postérieur à anotherInstant');
}
// Sortie : instant est antérieur à anotherInstant
            

              
                Copy
              
            
          

Travailler avec Duration

La classe Temporal.Duration représente une durée de temps, telle que des heures, des minutes ou des secondes. Elle est utile pour calculer la différence entre deux dates ou heures.

Créer une Duration :

            const duration = Temporal.Duration.from({ hours: 2, minutes: 30 });
console.log(duration.toString()); // Sortie : PT2H30M
            

              
                Copy
              
            
          

Calculer la différence entre des dates/heures :

            const startDate = Temporal.PlainDateTime.from({ year: 2024, month: 1, day: 1, hour: 0, minute: 0, second: 0 });
const endDate = Temporal.PlainDateTime.from({ year: 2024, month: 1, day: 3, hour: 12, minute: 30, second: 0 });
const difference = endDate.since(startDate);
console.log(difference.toString()); // Sortie : P2DT12H30M

// Accéder aux composants de la durée
console.log(difference.days);    // 2
console.log(difference.hours);   // 12
console.log(difference.minutes); // 30
            

              
                Copy
              
            
          

Ajouter une Durée à des dates/heures :

            const newDate = startDate.add(duration);
console.log(newDate.toString()); // Sortie : 2024-01-03T02:30:00
            

              
                Copy
              
            
          

Travailler avec les Calendriers

L'API Temporal prend en charge différents systèmes de calendrier au-delà du calendrier grégorien. Bien que pas encore entièrement implémentée dans tous les polyfills et moteurs, l'intention est de permettre aux applications de gérer les dates selon des calendriers spécifiques à diverses cultures. Par exemple, pour utiliser le calendrier japonais (hypothétiquement, car l'implémentation est toujours en évolution) :

            // Ceci est un exemple conceptuel car le support des calendriers est toujours en cours de développement
// const japaneseDate = Temporal.PlainDate.from({ year: 2024, month: 10, day: 26, calendar: 'japanese' });
// console.log(japaneseDate.toString()); // Attendu : Sortie formatée selon le calendrier japonais

            

              
                Copy
              
            
          

Note : Le support des calendriers est une fonctionnalité évolutive de l'API Temporal, et la pleine fonctionnalité n'est pas encore universellement disponible.

Exemples pratiques et cas d'utilisation

L'API Temporal offre un large éventail de possibilités pour gérer les dates et heures en JavaScript. Voici quelques exemples pratiques et cas d'utilisation :

• Planification de rendez-vous : Créez une application de planification qui permet aux utilisateurs de réserver des rendez-vous dans leur fuseau horaire local. Temporal.ZonedDateTime facilite la conversion entre les fuseaux horaires et la gestion des transitions de l'heure d'été. Pour une clinique à Berlin qui planifie des rendez-vous dans le monde entier :

            const appointmentTimeBerlin = Temporal.ZonedDateTime.from({ year: 2024, month: 11, day: 5, hour: 10, minute: 0, timeZone: 'Europe/Berlin' });
const appointmentTimeLA = appointmentTimeBerlin.withTimeZone('America/Los_Angeles');
console.log(`Heure du rendez-vous à Berlin : ${appointmentTimeBerlin.toString()}`);
console.log(`Heure du rendez-vous à Los Angeles : ${appointmentTimeLA.toString()}`);
            

              
                Copy
              
            
          

• Calcul de l'âge : Déterminez l'âge d'un utilisateur en fonction de sa date de naissance. PlainDate vous permet de représenter la date de naissance sans aucune information de fuseau horaire.

            const birthDate = Temporal.PlainDate.from({ year: 1990, month: 5, day: 15 });
const today = Temporal.Now.plainDateISO();
const age = today.year - birthDate.year - (today.month < birthDate.month || (today.month === birthDate.month && today.day < birthDate.day) ? 1 : 0);
console.log(`Âge : ${age}`);
            

              
                Copy
              
            
          

• Affichage des dates et heures dans différents formats : Formatez les dates et heures selon la locale de l'utilisateur. Bien que les fonctionnalités d'internationalisation (Intl) soient séparées, les objets Temporal peuvent être facilement formatés à l'aide de toLocaleString() ou de méthodes similaires lorsqu'ils sont combinés avec les fonctionnalités de l'API Intl.

            const zonedDateTimeNow = Temporal.Now.zonedDateTimeISO('en-GB');
console.log(zonedDateTimeNow.toLocaleString('en-GB'));
console.log(zonedDateTimeNow.toLocaleString('de-DE'));
            

              
                Copy
              
            
          

• Suivi des durées d'événements : Calculez la durée d'un événement et affichez-la dans un format lisible par l'homme. Duration vous permet de représenter la différence de temps entre deux dates ou heures.

            const eventStart = Temporal.Instant.fromEpochSeconds(1700000000); // Horodatage de début exemple
const eventEnd = Temporal.Instant.fromEpochSeconds(1700005000);   // Horodatage de fin exemple
const durationOfEvent = eventEnd.since(eventStart);
console.log(`Durée de l'événement : ${durationOfEvent.minutes} minutes`);
            

              
                Copy
              
            
          

Meilleures pratiques pour l'utilisation de l'API Temporal

Voici quelques meilleures pratiques à garder à l'esprit lors de l'utilisation de l'API Temporal :

• Utilisez l'immutabilité : Adoptez l'immutabilité des objets Temporal. Évitez de modifier directement les objets. Créez plutôt de nouveaux objets en utilisant des méthodes telles que add, subtract et with.
• Gérez les fuseaux horaires avec soin : Soyez attentif aux fuseaux horaires lorsque vous travaillez avec des dates et heures. Utilisez ZonedDateTime lorsque vous avez besoin de représenter des dates et heures dans un fuseau horaire spécifique.
• Utilisez des noms de variables clairs : Utilisez des noms de variables descriptifs qui indiquent clairement le type d'objet Temporal utilisé (par exemple, plainDate, zonedDateTime, duration).
• Considérez les polyfills : Puisque Temporal est encore relativement nouveau, assurez un support suffisant en utilisant une bibliothèque de polyfill si nécessaire.
• Validez les entrées : Validez toujours les entrées de l'utilisateur pour vous assurer que les dates et heures sont dans le bon format.

Migration depuis la Date obsolète

La migration depuis l'ancien objet Date peut être un processus graduel. Considérez ces stratégies :

• Adoption incrémentielle : Commencez par utiliser Temporal dans le nouveau code tout en conservant Date dans les parties existantes de votre application.
• Fonctions enveloppantes : Créez des fonctions enveloppantes qui convertissent entre les objets Date et Temporal pour faciliter l'interopérabilité pendant la migration.
• Tests approfondis : Testez la migration de manière approfondie pour vous assurer que tous les calculs de date et d'heure sont précis.

API Temporal vs Moment.js

Moment.js était une bibliothèque populaire pour la manipulation des dates et heures en JavaScript, mais elle est maintenant considérée comme un projet obsolète et est en mode maintenance. L'API Temporal offre une solution plus moderne et standardisée qui corrige bon nombre des lacunes de Moment.js. Moment.js est mutable et manque de support natif des fuseaux horaires. L'API Temporal est immuable et possède un support natif des fuseaux horaires.

Conclusion

L'API JavaScript Temporal représente une amélioration significative par rapport à l'ancien objet Date. Son immutabilité, son API claire, son support des fuseaux horaires et de ses calendriers en font un outil puissant pour gérer les dates et heures dans les applications JavaScript modernes. Bien que l'adoption soit encore en croissance, l'utilisation d'un polyfill vous permet de commencer à bénéficier de ses avantages dès aujourd'hui. À mesure que l'API deviendra plus largement prise en charge, elle devrait devenir la manière standard de travailler avec les dates et heures en JavaScript.

Adoptez l'API Temporal et débloquez une manière plus efficace et fiable de gérer les dates et heures dans vos projets, en garantissant que votre application gère avec précision les fuseaux horaires et les calculs mondiaux.