JavaScript Temporal.Duration: Zeitintervall-Berechnungen meistern

Die Temporal-API von JavaScript führt eine moderne und leistungsstarke Methode zur Handhabung von Daten, Zeiten und Zeitintervallen ein. Das Temporal.Duration-Objekt repräsentiert eine Zeitdauer und bietet einen klaren und intuitiven Ansatz zur Durchführung von Berechnungen mit Zeitintervallen. Dieser Artikel befasst sich mit den Details von Temporal.Duration und zeigt, wie man Dauern für verschiedene Anwendungsfälle erstellt, bearbeitet und formatiert.

Was ist Temporal.Duration?

Temporal.Duration stellt eine Zeitspanne dar und drückt sie in Jahren, Monaten, Tagen, Stunden, Minuten, Sekunden und Sekundenbruchteilen (Millisekunden, Mikrosekunden, Nanosekunden) aus. Im Gegensatz zu Date-Objekten, die einen bestimmten Zeitpunkt repräsentieren, stellt Temporal.Duration eine Zeitmenge dar. Es hält sich an das ISO 8601-Dauerformat (z.B. steht P1Y2M10DT2H30M für 1 Jahr, 2 Monate, 10 Tage, 2 Stunden und 30 Minuten). Die Temporal-API ist so konzipiert, dass sie intuitiver und weniger fehleranfällig ist als das veraltete Date-Objekt.

Erstellen von Temporal.Duration-Objekten

Es gibt mehrere Möglichkeiten, Temporal.Duration-Objekte zu erstellen:

1. Aus einem einfachen Objekt

Sie können eine Dauer erstellen, indem Sie ein Objekt mit den gewünschten Eigenschaften übergeben:

const duration = new Temporal.Duration(1, 2, 10, 2, 30, 0, 0, 0);
console.log(duration.toString()); // Ausgabe: P1Y2M10DT2H30M

Dies erstellt eine Dauer von 1 Jahr, 2 Monaten, 10 Tagen, 2 Stunden und 30 Minuten. Beachten Sie, dass die Argumente der folgenden Reihenfolge entsprechen: Jahre, Monate, Wochen, Tage, Stunden, Minuten, Sekunden, Millisekunden, Mikrosekunden, Nanosekunden.

2. Aus einem ISO 8601-String

Sie können eine Dauer auch aus einem ISO 8601-Dauer-String mit Temporal.Duration.from() erstellen:

const duration = Temporal.Duration.from("P1Y2M10DT2H30M");
console.log(duration.toString()); // Ausgabe: P1Y2M10DT2H30M

Dies ist besonders nützlich, wenn Sie mit Dauern arbeiten, die im String-Format gespeichert sind oder von einer externen Quelle empfangen werden.

3. Verwendung der Methoden add() und subtract() mit Temporal.Instant, Temporal.ZonedDateTime usw.

Wenn Sie Temporal.Duration zu anderen Temporal-Typen (wie Temporal.Instant oder Temporal.ZonedDateTime) addieren oder subtrahieren, wird eine Temporal.Duration zurückgegeben, die die Differenz zwischen den beiden Zeitpunkten darstellt, wenn Sie diese anschließend voneinander abziehen. Zum Beispiel:

const now = Temporal.Now.zonedDateTimeISO();
const later = now.add({ hours: 5 });
const duration = later.since(now);
console.log(duration.toString()); // Ausgabe: PT5H

Zugriff auf die Komponenten einer Dauer

Sie können auf die einzelnen Komponenten eines Temporal.Duration-Objekts über dessen Eigenschaften zugreifen:

const duration = Temporal.Duration.from("P1Y2M10DT2H30M");
console.log(duration.years);      // Ausgabe: 1
console.log(duration.months);     // Ausgabe: 2
console.log(duration.days);       // Ausgabe: 10
console.log(duration.hours);      // Ausgabe: 2
console.log(duration.minutes);     // Ausgabe: 30
console.log(duration.seconds);     // Ausgabe: 0
console.log(duration.milliseconds); // Ausgabe: 0
console.log(duration.microseconds); // Ausgabe: 0
console.log(duration.nanoseconds);  // Ausgabe: 0

Durchführung von Arithmetik mit Dauern

Temporal.Duration-Objekte unterstützen Addition und Subtraktion mithilfe der Methoden add() und subtract(). Diese Methoden geben ein neues Temporal.Duration-Objekt zurück, das das Ergebnis der Operation darstellt.

const duration1 = Temporal.Duration.from("P1Y2M");
const duration2 = Temporal.Duration.from("P3M4D");

const addedDuration = duration1.add(duration2);
console.log(addedDuration.toString()); // Ausgabe: P1Y5M4D

const subtractedDuration = duration1.subtract(duration2);
console.log(subtractedDuration.toString()); // Ausgabe: P10M26D

Sie können diese Methoden auch für komplexere Berechnungen verketten:

const duration = Temporal.Duration.from("P1D").add({ hours: 12 }).subtract({ minutes: 30 });
console.log(duration.toString()); // Ausgabe: P1DT11H30M

Die negated()-Methode gibt ein neues Temporal.Duration-Objekt zurück, bei dem alle Komponenten negiert sind:

const duration = Temporal.Duration.from("P1Y2M10DT2H30M");
const negatedDuration = duration.negated();
console.log(negatedDuration.toString()); // Ausgabe: -P1Y2M10DT2H30M

Die abs()-Methode gibt ein neues Temporal.Duration-Objekt zurück, bei dem alle Komponenten positive Werte haben (absolute Werte):

const duration = Temporal.Duration.from("-P1Y2M10DT2H30M");
const absoluteDuration = duration.abs();
console.log(absoluteDuration.toString()); // Ausgabe: P1Y2M10DT2H30M

Die with()-Methode ermöglicht es Ihnen, eine neue Temporal.Duration-Instanz zu erstellen, bei der einige oder alle Eigenschaften auf neue Werte geändert werden. Wenn ein Wert im Argumentobjekt nicht angegeben wird, wird der ursprüngliche Wert der Dauer verwendet. Zum Beispiel:

const duration = Temporal.Duration.from("P1Y2M10DT2H30M");
const newDuration = duration.with({ years: 2, days: 5 });
console.log(newDuration.toString()); // Ausgabe: P2Y2M5DT2H30M

Normalisieren von Dauern

Dauern können manchmal in einer nicht normalisierten Form ausgedrückt werden (z.B. P1Y12M, was zu P2Y vereinfacht werden könnte). Die normalized()-Methode versucht, eine Dauer in ihre kompakteste Form zu vereinfachen. Sie erfordert jedoch ein Referenzdatum, um die Komplexität variierender Monatslängen zu bewältigen. Um korrekt zu normalisieren, benötigen Sie eine Temporal.PlainDate-, Temporal.ZonedDateTime- oder Temporal.Instant-Instanz.

Zum Beispiel erfordert die Normalisierung einer Dauer, die Monate und Tage umfasst, ein Referenzdatum:

const duration = Temporal.Duration.from("P1M32D");
const referenceDate = Temporal.PlainDate.from("2024-01-01");
const normalizedDuration = duration.normalized({ relativeTo: referenceDate });
console.log(normalizedDuration.toString()); // Ausgabe: P2M1D

In diesem Beispiel wird die Dauer P1M32D relativ zum 1. Januar 2024 normalisiert, was zu P2M1D führt, da der Januar 31 Tage hat.

Wenn Sie nur mit Zeitkomponenten (Stunden, Minuten, Sekunden usw.) arbeiten, können Sie ohne ein Referenzdatum normalisieren:

const duration = Temporal.Duration.from("PT25H61M");
const normalizedDuration = duration.normalized({ relativeTo: null }); //oder lassen Sie das relativeTo-Argument weg
console.log(normalizedDuration.toString()); // Ausgabe: P1DT2H1M

Vergleichen von Dauern

Sie können Dauern mit der compare()-Methode vergleichen. Diese Methode gibt zurück:

• -1, wenn die erste Dauer kürzer als die zweite Dauer ist.
• 0, wenn die Dauern gleich sind.
• 1, wenn die erste Dauer länger als die zweite Dauer ist.

const duration1 = Temporal.Duration.from("P1Y");
const duration2 = Temporal.Duration.from("P6M");

const comparisonResult = Temporal.Duration.compare(duration1, duration2);
console.log(comparisonResult); // Ausgabe: 1

Praktische Beispiele

1. Berechnung der Zeit bis zu einem Ereignis

Angenommen, Sie möchten die verbleibende Zeit bis zu einem bestimmten Ereignis berechnen. Verwenden Sie Temporal.Now.zonedDateTimeISO(), um die aktuelle Zeit zu erhalten, und subtrahieren Sie das Datum des Ereignisses. Wenn das Datum des Ereignisses bereits vergangen ist, wird die Ausgabe negativ sein.

const eventDate = Temporal.ZonedDateTime.from({ timeZone: 'America/Los_Angeles', year: 2024, month: 12, day: 25, hour: 9, minute: 0, second: 0 });
const now = Temporal.Now.zonedDateTimeISO('America/Los_Angeles');

const durationUntilEvent = eventDate.since(now);

console.log(durationUntilEvent.toString()); // Ausgabe: z.B. P262DT14H30M (abhängig vom aktuellen Datum und der aktuellen Uhrzeit)

2. Nachverfolgen der Dauer von Projektaufgaben

Im Projektmanagement können Sie Temporal.Duration verwenden, um die geschätzte oder tatsächliche Dauer von Aufgaben zu verfolgen.

const task1EstimatedDuration = Temporal.Duration.from("PT8H"); // 8 Stunden
const task2EstimatedDuration = Temporal.Duration.from("PT16H"); // 16 Stunden

const totalEstimatedDuration = task1EstimatedDuration.add(task2EstimatedDuration);
console.log(`Total estimated duration: ${totalEstimatedDuration.toString()}`); // Ausgabe: Total estimated duration: P1DT

3. Berechnung des Alters

Obwohl die genaue Berechnung des Alters die Berücksichtigung von Schaltjahren und Zeitzonen erfordert, kann Temporal.Duration eine vernünftige Schätzung liefern:

const birthDate = Temporal.PlainDate.from("1990-05-15");
const currentDate = Temporal.PlainDate.from("2024-01-20");

const ageDuration = currentDate.since(birthDate, { smallestUnit: 'years' });
console.log(`Estimated age: ${ageDuration.years} years`); // Ausgabe: Estimated age: 33 years

4. Anzeige von menschenlesbaren Dauern

Oftmals müssen Sie Dauern in einem menschenlesbaren Format anzeigen. Obwohl Temporal.Duration keine integrierten Formatierungsfunktionen hat, können Sie eine benutzerdefinierte Formatierungslogik erstellen:

function formatDuration(duration) {
  const parts = [];
  if (duration.years) parts.push(`${duration.years} year${duration.years > 1 ? 's' : ''}`);
  if (duration.months) parts.push(`${duration.months} month${duration.months > 1 ? 's' : ''}`);
  if (duration.days) parts.push(`${duration.days} day${duration.days > 1 ? 's' : ''}`);
  if (duration.hours) parts.push(`${duration.hours} hour${duration.hours > 1 ? 's' : ''}`);
  if (duration.minutes) parts.push(`${duration.minutes} minute${duration.minutes > 1 ? 's' : ''}`);
  if (duration.seconds) parts.push(`${duration.seconds} second${duration.seconds > 1 ? 's' : ''}`);

  return parts.join(', ');
}

const duration = Temporal.Duration.from("P1Y2M10DT2H30M");
const formattedDuration = formatDuration(duration);
console.log(formattedDuration); // Ausgabe: 1 year, 2 months, 10 days, 2 hours, 30 minutes

Erweiterte Nutzung und Überlegungen

1. Umgang mit Zeitzonen

Wenn Sie mit Zeitintervallen arbeiten, die Zeitzonengrenzen oder Sommerzeitübergänge überschreiten, ist es entscheidend, Temporal.ZonedDateTime zu verwenden, um genaue Berechnungen zu gewährleisten. Die Verwendung von Temporal.PlainDate und Temporal.PlainTime vermeidet jegliche Zeitzonenumrechnungen.

2. Kleinste Einheit und Rundung

Die `since()` und `until()` Methoden akzeptieren oft Optionen, um die kleinste Einheit für die resultierende Dauer zu definieren. Zum Beispiel die Berechnung der Zeit *bis* zu einem Ereignis und die Begrenzung der Ergebnisse auf Tage.

const eventDate = Temporal.PlainDate.from("2024-12-25");
const now = Temporal.PlainDate.from("2024-01-20");

const durationUntilEvent = now.until(eventDate, { smallestUnit: 'days' });

console.log(durationUntilEvent.toString()); //Beispielausgabe PT340D

3. Schaltsekunden

Temporal berücksichtigt Schaltsekunden nicht nativ. Wenn Sie extreme Präzision benötigen, müssen Sie Schaltsekunden separat behandeln.

4. IANA-Zeitzonen

Die Temporal-API stützt sich auf die Zeitzonendatenbank der IANA (Internet Assigned Numbers Authority). Stellen Sie sicher, dass Ihre Umgebung eine aktuelle Version der IANA-Datenbank hat, um Zeitzonenumrechnungen genau zu handhaben.

Bewährte Praktiken

• Verwenden Sie das ISO 8601-Format für Dauer-Strings: Dies gewährleistet Konsistenz und Interoperabilität.
• Wählen Sie den geeigneten Temporal-Typ: Verwenden Sie Temporal.PlainDate, Temporal.PlainTime, Temporal.ZonedDateTime oder Temporal.Instant, je nachdem, ob Sie Zeitzonenunterstützung benötigen oder nicht.
• Normalisieren Sie Dauern bei Bedarf: Die Normalisierung vereinfacht Dauern und erleichtert deren Vergleich.
• Gehen Sie sorgfältig mit Zeitzonen um: Zeitzonenumrechnungen können komplex sein, verwenden Sie daher Temporal.ZonedDateTime und achten Sie auf Sommerzeitübergänge.
• Berücksichtigen Sie die kleinste Einheit: Geben Sie bei der Berechnung von Dauern die kleinste Einheit an, um den gewünschten Genauigkeitsgrad zu erhalten.
• Schreiben Sie Unit-Tests: Testen Sie Ihren Code gründlich, um sicherzustellen, dass die Dauerberechnungen korrekt sind.

Häufige Fallstricke

• Ignorieren von Zeitzonen: Das Nichtberücksichtigen von Zeitzonen kann zu falschen Dauerberechnungen führen, insbesondere bei Ereignissen an verschiedenen Orten.
• Verwendung des veralteten Date-Objekts: Das veraltete Date-Objekt ist für seine Eigenheiten und Inkonsistenzen bekannt. Bevorzugen Sie die Temporal-API für eine zuverlässigere Datums- und Zeitbehandlung.
• Nicht-Normalisierung von Dauern: Das Nicht-Normalisieren von Dauern kann Vergleiche und Berechnungen komplexer machen.
• Falsches ISO 8601-Format: Die Verwendung eines ungültigen ISO 8601-Dauer-Strings kann zu Fehlern führen.

Anwendungsfälle aus der Praxis in verschiedenen Kulturen

Die Temporal-API kann besonders in globalen Anwendungen von Vorteil sein, in denen Zeitzonenunterschiede und kulturelle Nuancen von Bedeutung sind. Hier sind einige Beispiele:

• Globale Ereignisplanung: Genaue Planung von Ereignissen über mehrere Zeitzonen hinweg unter Berücksichtigung von Sommerzeitübergängen. Zum Beispiel die Planung eines Webinars, das um 9:00 Uhr PST beginnt, und die Anzeige der entsprechenden Startzeit in verschiedenen Zeitzonen wie CET, JST und AEDT.
• Internationale Reiseplanung: Berechnung von Reisedauern, einschließlich Zwischenstopps und Zeitzonenwechsel. Dies ist nützlich für die Erstellung von Reiserouten und die Verwaltung von Flugplänen. Zum Beispiel die Berechnung der Gesamtreisezeit von New York nach Tokio, einschließlich eines Zwischenstopps in London und der Anpassung an Zeitzonenunterschiede.
• Globaler E-Commerce: Anzeige der voraussichtlichen Lieferzeiten in der lokalen Zeitzone des Benutzers. Dies erfordert die Berücksichtigung der Ursprungszeitzone, der Versanddauer und der Zielzeitzone. Zum Beispiel ein Artikel, der von einem Lager in Deutschland an einen Kunden in Australien versendet wird, mit einer geschätzten Lieferzeit von 7 Tagen, die in der lokalen Zeit des Kunden angezeigt wird.
• Grenzüberschreitende Finanztransaktionen: Genaue Berechnung von Zinsabgrenzungen oder Zahlungsfristen in verschiedenen Regionen. Dies beinhaltet oft die Berücksichtigung unterschiedlicher Geschäftstage und Feiertage in jedem Land. Zum Beispiel die Berechnung der auf ein Darlehen in Singapur anfallenden Zinsen unter Berücksichtigung der singapurischen Feiertage.
• Multikulturelle Kalenderanwendungen: Unterstützung verschiedener Kalendersysteme, wie des islamischen oder hebräischen Kalenders, und genaue Berechnung von Ereignisdauern und Erinnerungen auf der Grundlage dieser Kalender.
• Globales Projektmanagement: Verfolgung von Projektaufgabendauern und -fristen in verteilten Teams unter Berücksichtigung unterschiedlicher Arbeitszeiten und Zeitzonen.

Fazit

Temporal.Duration bietet eine robuste und intuitive Möglichkeit, mit Zeitintervallen in JavaScript zu arbeiten. Indem Sie seine Funktionen und bewährten Praktiken verstehen, können Sie sicher genaue und zuverlässige Dauerberechnungen in Ihren Anwendungen durchführen. Die Einführung der Temporal-API führt zu saubererem, wartbarerem Code und reduziert das Risiko von Fehlern, die mit der veralteten Datums- und Zeitbehandlung verbunden sind.

Wenn Sie tiefer in die Temporal-API eintauchen, denken Sie daran, die offizielle Dokumentation zu konsultieren und mit verschiedenen Szenarien zu experimentieren, um ihre Fähigkeiten vollständig zu erfassen. Mit ihrem modernen Design und ihren umfassenden Funktionen wird Temporal die Art und Weise, wie wir mit Daten, Zeiten und Dauern in JavaScript umgehen, revolutionieren.