Durée JavaScript Temporal : Maîtriser l'arithmétique des intervalles de temps

L'API JavaScript Temporal révolutionne la manière dont nous gérons les dates et les heures. En son cœur se trouve l'objet Temporal.Duration, un outil puissant pour représenter et manipuler les intervalles de temps. Ce guide complet explorera les subtilités de Temporal.Duration, vous dotant des connaissances nécessaires pour effectuer des calculs arithmétiques temporels complexes avec facilité et précision.

Qu'est-ce que Temporal.Duration ?

Temporal.Duration représente un laps de temps, exprimé en années, mois, jours, heures, minutes, secondes et nanosecondes. Contrairement à Date, qui représente un point spécifique dans le temps, Duration décrit une quantité de temps relative. Cela le rend idéal pour les calculs impliquant des différences de temps, des décalages et des événements récurrents.

Pensez-y comme une recette pour le temps. Il vous indique quelle quantité de chaque unité de temps ajouter ou soustraire à partir d'un point de départ donné. Par exemple, une durée de "1 an, 2 mois et 3 jours" peut être utilisée pour calculer la date 1 an, 2 mois et 3 jours après une date spécifique.

Créer des objets Temporal.Duration

Il existe plusieurs façons de créer un objet Temporal.Duration :

1. À partir d'un objet littéral

L'approche la plus simple consiste à utiliser un objet littéral avec des propriétés pour chaque unité de temps :

            const duration = new Temporal.Duration(1, 2, 3, 4, 5, 6, 7); // 1 an, 2 mois, 3 jours, 4 heures, 5 minutes, 6 secondes, 7 nanosecondes
console.log(duration.toString()); // 'P1Y2M3DT4H5M6.000000007S'
            

              
                Copy
              
            
          

Vous pouvez omettre les propriétés qui sont nulles. Par exemple :

            const duration = new Temporal.Duration(0, 0, 7); // 7 jours
console.log(duration.toString()); // 'P7D'
            

              
                Copy
              
            
          

2. À partir d'une chaîne ISO 8601

Temporal.Duration peut également être créé à partir d'une chaîne de durée ISO 8601 :

            const duration = Temporal.Duration.from('P1Y2M3DT4H5M6S'); // 1 an, 2 mois, 3 jours, 4 heures, 5 minutes, 6 secondes
console.log(duration.toString()); // 'P1Y2M3DT4H5M6S'

const duration2 = Temporal.Duration.from('PT30M'); // 30 minutes
console.log(duration2.toString()); // 'PT30M'
            

              
                Copy
              
            
          

Cette méthode est particulièrement utile lorsque l'on traite des données provenant de sources externes qui utilisent le format ISO 8601. Le format de la chaîne suit le modèle P[années]Y[mois]M[jours]D[T[heures]H[minutes]M[secondes]S].

3. À partir d'autres types Temporal

Vous pouvez calculer la durée entre deux objets Temporal.Instant, Temporal.ZonedDateTime, Temporal.PlainDate, ou Temporal.PlainTime en utilisant la méthode until(). Ceci est particulièrement utile pour déterminer le temps écoulé entre deux événements.

            const start = Temporal.PlainDate.from('2023-01-01');
const end = Temporal.PlainDate.from('2023-03-15');
const duration = start.until(end);
console.log(duration.toString()); // 'P2M14D'
            

              
                Copy
              
            
          

Accéder aux propriétés de Duration

Une fois que vous avez un objet Temporal.Duration, vous pouvez accéder à ses propriétés pour récupérer les composantes temporelles individuelles :

            const duration = new Temporal.Duration(1, 2, 3, 4, 5, 6, 7);

console.log(duration.years); // 1
console.log(duration.months); // 2
console.log(duration.days); // 3
console.log(duration.hours); // 4
console.log(duration.minutes); // 5
console.log(duration.seconds); // 6
console.log(duration.nanoseconds); // 7
            

              
                Copy
              
            
          

Ces propriétés sont en lecture seule, garantissant que l'objet Duration reste immuable.

Arithmétique avec Temporal.Duration

L'une des principales forces de Temporal.Duration est sa capacité à effectuer des opérations arithmétiques. Vous pouvez additionner, soustraire, multiplier et diviser des durées, ce qui facilite considérablement les calculs temporels complexes.

1. Additionner des durées

Utilisez la méthode add() pour additionner deux durées :

            const duration1 = new Temporal.Duration(1, 2, 3);
const duration2 = new Temporal.Duration(0, 0, 7);
const sum = duration1.add(duration2);
console.log(sum.toString()); // 'P1Y2M10D'
            

              
                Copy
              
            
          

2. Soustraire des durées

Utilisez la méthode subtract() pour soustraire une durée d'une autre :

            const duration1 = new Temporal.Duration(1, 2, 3);
const duration2 = new Temporal.Duration(0, 0, 7);
const difference = duration1.subtract(duration2);
console.log(difference.toString()); // 'P1Y2M-4D'
            

              
                Copy
              
            
          

Notez que la soustraction d'une durée plus grande d'une plus petite peut entraîner des valeurs négatives pour certaines propriétés.

3. Multiplier des durées

Utilisez la méthode multiply() pour multiplier une durée par une valeur scalaire :

            const duration = new Temporal.Duration(1, 0, 0);
const doubled = duration.multiply(2);
console.log(doubled.toString()); // 'P2Y'
            

              
                Copy
              
            
          

Ceci est utile pour mettre à l'échelle des durées afin de représenter, par exemple, le double de la longueur d'un événement particulier.

4. Négation et valeur absolue

Utilisez la méthode negated() ou abs() pour modifier une durée :

            const duration = new Temporal.Duration(1, 0, 0);
const negated = duration.negated();
console.log(negated.toString()); // 'P-1Y'

const durationNegative = new Temporal.Duration(-1, 0, 0);
const absoluteValue = durationNegative.abs();
console.log(absoluteValue.toString()); // 'P1Y'

            

              
                Copy
              
            
          

Normaliser les durées

Les durées peuvent parfois être dans un état non normalisé, ce qui signifie qu'elles contiennent des composantes qui pourraient être exprimées en unités plus grandes. Par exemple, une durée de "1 an et 12 mois" pourrait être normalisée en "2 ans".

Pour normaliser une durée, vous pouvez utiliser les méthodes toPlainDays(), toPlainHours(), toPlainMinutes(), toPlainSeconds(), ou toPlainNanoseconds() en conjonction avec un autre type Temporal tel que Temporal.PlainDate. La normalisation nécessite un contexte pour tenir compte correctement des mois de longueur variable et des années bissextiles.

            const plainDate = Temporal.PlainDate.from('2024-01-01'); // Date de début d'exemple
const duration = new Temporal.Duration(0, 13, 0); // 13 mois

// Normalisation dans un contexte de date
const normalizedDate = plainDate.add(duration);

// Calcul de la durée entre la date initiale et la date normalisée
const normalizedDuration = plainDate.until(normalizedDate);
console.log(normalizedDuration.toString()); // Sortie : 'P1Y1M'
            

              
                Copy
              
            
          

Dans cet exemple, l'ajout d'une durée de 13 mois au 1er janvier 2024 donne le 1er février 2025. La méthode until() calcule ensuite la durée entre la date initiale et la date résultante, nous donnant la durée normalisée de 1 an et 1 mois.

Travailler avec différents types Temporal

Temporal.Duration est conçu pour fonctionner de manière transparente avec d'autres types Temporal, tels que Temporal.Instant, Temporal.ZonedDateTime, Temporal.PlainDate, et Temporal.PlainTime. Cela vous permet d'effectuer des calculs temporels complexes impliquant des points spécifiques dans le temps et des dates.

1. Ajouter des durées à Temporal.PlainDate

Vous pouvez ajouter une Duration à un Temporal.PlainDate pour calculer une date future :

            const startDate = Temporal.PlainDate.from('2023-01-01');
const duration = new Temporal.Duration(1, 0, 0); // 1 an
const futureDate = startDate.add(duration);
console.log(futureDate.toString()); // '2024-01-01'
            

              
                Copy
              
            
          

2. Soustraire des durées de Temporal.ZonedDateTime

De même, vous pouvez soustraire une Duration d'un Temporal.ZonedDateTime pour calculer une date et une heure passées :

            const startDateTime = Temporal.ZonedDateTime.from('2023-01-01T12:00:00+00:00[UTC]');
const duration = new Temporal.Duration(0, 0, 0, 6); // 6 heures
const pastDateTime = startDateTime.subtract(duration);
console.log(pastDateTime.toString()); // '2023-01-01T06:00:00+00:00[UTC]'
            

              
                Copy
              
            
          

Exemples pratiques et cas d'utilisation

Temporal.Duration est un outil polyvalent avec de nombreuses applications pratiques. Voici quelques exemples :

1. Calculer l'âge

Vous pouvez utiliser Temporal.Duration pour calculer l'âge d'une personne en fonction de sa date de naissance :

            const birthDate = Temporal.PlainDate.from('1990-05-15');
const today = Temporal.Now.plainDateISO();
const ageDuration = birthDate.until(today);

console.log(`Âge : ${ageDuration.years} ans, ${ageDuration.months} mois, ${ageDuration.days} jours`);
            

              
                Copy
              
            
          

2. Planifier des événements récurrents

Temporal.Duration est idéal pour planifier des événements récurrents, tels que des réunions hebdomadaires ou des rapports mensuels. Vous pouvez l'utiliser pour calculer la prochaine occurrence d'un événement en fonction de son intervalle de récurrence.

3. Calculer les décalages horaires pour la planification de voyages

Lors de la planification de voyages internationaux, vous pouvez utiliser Temporal.Duration pour calculer le décalage horaire entre deux lieux :

            const departureTime = Temporal.ZonedDateTime.from('2023-03-01T10:00:00+01:00[Europe/Paris]');
const arrivalTime = Temporal.ZonedDateTime.from('2023-03-01T14:00:00-08:00[America/Los_Angeles]');
const flightDuration = departureTime.until(arrivalTime);

console.log(`Durée du vol : ${flightDuration.hours} heures, ${flightDuration.minutes} minutes`);
            

              
                Copy
              
            
          

4. Implémenter des comptes à rebours

Créez des comptes à rebours pour des événements spéciaux, des lancements de produits ou des dates limites, en affichant dynamiquement le temps restant.

5. Mesurer les métriques de performance

Enregistrez la durée des sections d'exécution de code critiques pour identifier les goulots d'étranglement de performance et optimiser le code.

Considérations sur l'internationalisation

Lorsque vous travaillez avec des dates et des heures dans un contexte mondial, il est crucial de prendre en compte l'internationalisation. L'API Temporal fournit plusieurs fonctionnalités pour vous aider à gérer différents fuseaux horaires, calendriers et locales.

1. Fuseaux horaires

Utilisez Temporal.ZonedDateTime pour travailler avec des dates et des heures dans des fuseaux horaires spécifiques. Cela garantit que vos calculs sont précis, quel que soit l'emplacement de l'utilisateur.

2. Calendriers

L'API Temporal prend en charge différents calendriers, tels que le calendrier grégorien, le calendrier islamique et le calendrier japonais. Vous pouvez spécifier le calendrier lors de la création d'un objet Temporal.PlainDate ou Temporal.ZonedDateTime.

3. Locales

Utilisez la méthode toLocaleString() pour formater les dates et les heures en fonction de la locale de l'utilisateur. Cela garantit que les dates et les heures sont affichées d'une manière culturellement appropriée.

            const date = Temporal.PlainDate.from('2023-03-15');

console.log(date.toLocaleString('en-US')); // '3/15/2023'
console.log(date.toLocaleString('fr-FR')); // '15/03/2023'
console.log(date.toLocaleString('ja-JP')); // '2023/03/15'
            

              
                Copy
              
            
          

Bonnes pratiques pour travailler avec Temporal.Duration

Pour garantir que votre code est robuste et maintenable, suivez ces bonnes pratiques lorsque vous travaillez avec Temporal.Duration :

• Utilisez l'API Temporal de manière cohérente : Évitez de mélanger l'API Temporal avec l'ancien objet Date, car cela peut entraîner des incohérences et des erreurs.
• Gérez les fuseaux horaires avec soin : Spécifiez toujours le fuseau horaire lorsque vous travaillez avec des dates et des heures pertinentes pour un emplacement spécifique.
• Validez les entrées utilisateur : Validez les entrées utilisateur pour vous assurer qu'elles sont au bon format et dans la plage attendue.
• Testez votre code de manière approfondie : Testez votre code avec différents fuseaux horaires, calendriers et locales pour vous assurer qu'il fonctionne correctement dans tous les scénarios.
• Documentez votre code : Documentez votre code de manière claire et concise, en expliquant le but de chaque fonction et les hypothèses qu'elle formule.

Pièges courants et comment les éviter

Bien que l'API Temporal simplifie la gestion des dates et des heures, certains pièges peuvent entraîner des résultats inattendus. Être conscient de ces problèmes courants et savoir comment les éviter est crucial pour écrire du code fiable.

1. Format de chaîne de durée incorrect

Assurez-vous que la chaîne de durée est strictement conforme au format ISO 8601. Même un petit écart peut provoquer des erreurs d'analyse ou des calculs incorrects.

            // Incorrect : 'T' manquant pour les composantes de temps
// Temporal.Duration.from('P1D2H3M'); // Cela pourrait lever une erreur ou produire des résultats inattendus

// Correct : Format ISO 8601 approprié
const duration = Temporal.Duration.from('P1DT2H3M');
console.log(duration.toString()); // Sortie : 'P1DT2H3M'
            

              
                Copy
              
            
          

2. Ignorer les années bissextiles et l'heure d'été

Les années bissextiles et l'heure d'été (DST) peuvent avoir un impact significatif sur les calculs de durée, en particulier lorsqu'il s'agit de longs intervalles de temps. Utilisez toujours les types et méthodes Temporal appropriés pour tenir compte de ces anomalies.

            // Exemple avec l'heure d'été
const plainDateTime = Temporal.PlainDate.from('2023-03-12'); // Jour du changement d'heure d'été aux États-Unis
const duration1Day = Temporal.Duration.from('P1D');
const nextDay = plainDateTime.add(duration1Day);

console.log(nextDay.toString()); // La date changera correctement, en tenant compte du changement d'heure dû au DST
            

              
                Copy
              
            
          

3. Mélanger incorrectement les types Temporal

Assurez-vous d'utiliser les types Temporal corrects pour vos calculs. Par exemple, évitez d'utiliser Temporal.PlainDate pour les opérations qui nécessitent une connaissance du fuseau horaire.

4. Hypothèses de normalisation incorrectes

Normalisez toujours les durées dans un contexte spécifique (par exemple, par rapport à un Temporal.PlainDate) pour gérer avec précision les unités ambiguës comme les mois ou les années.

            // Incorrect : Supposer qu'un mois dure toujours 30 jours
const duration = new Temporal.Duration(0, 1, 0); // 1 mois
// const daysInMonth = duration.months * 30; // Ce n'est pas précis

// Correct : Utiliser Temporal.PlainDate pour déterminer le nombre de jours dans un mois spécifique
const startDate = Temporal.PlainDate.from('2023-02-01');
const endDate = startDate.add({ months: 1 });
const daysInMonth = startDate.until(endDate, { unit: 'days' }).days;
console.log(daysInMonth); // Sortie : 28 (pour février 2023)
            

              
                Copy
              
            
          

Conclusion

Temporal.Duration est un outil puissant pour travailler avec les intervalles de temps en JavaScript. En comprenant ses propriétés, ses méthodes et ses bonnes pratiques, vous pouvez effectuer des calculs arithmétiques temporels complexes avec facilité et précision. À mesure que l'API Temporal est plus largement adoptée, la maîtrise de Temporal.Duration deviendra une compétence essentielle pour tout développeur JavaScript. Que vous calculiez des âges, planifiez des événements ou organisiez des voyages internationaux, Temporal.Duration offre une solution robuste et fiable pour tous vos besoins liés au temps. Adoptez l'API Temporal et débloquez un nouveau niveau de précision et de clarté dans votre code JavaScript.

Ce guide a couvert les aspects fondamentaux de Temporal.Duration. En approfondissant l'API Temporal, explorez ses fonctionnalités avancées, telles que les calendriers personnalisés et la gestion des fuseaux horaires, pour améliorer encore vos compétences en programmation temporelle. N'oubliez pas de consulter la documentation officielle ECMAScript Temporal pour obtenir les informations et les spécifications les plus à jour.

Bon codage !