Temporal.Instant.prototype.subtract() — Methode · JavaScript-Referenz

Signatur

Temporal.Instant.prototype.subtract(duration)

Beschreibung

subtract() zieht eine feste Zeitspanne von einem exakten Zeitpunkt auf der Zeitachse ab (Nanosekunden seit der Unix-Epoche) und gibt das Ergebnis als neues Temporal.Instant zurück. Wie alle Temporal-Objekte ist Temporal.Instant unveränderlich: Das Original bleibt gleich.

Als Dauer geht eine Temporal.Duration, ein ISO-8601-Dauer-String (z. B. "PT1H30M") oder ein Objekt wie { hours: 2, minutes: 15 }. Intern wird der Wert mit Temporal.Duration.from() umgewandelt. Der Aufruf entspricht instant.add(duration.negated()).

Ein Instant hat weder Zeitzone noch Kalender. Deshalb sind nur exakte Einheiten erlaubt: hours, minutes, seconds, milliseconds, microseconds und nanoseconds. Kalendereinheiten wie Jahre, Monate, Wochen oder Tage sind nicht immer gleich lang (Schaltjahre, Sommerzeit). Wer sie braucht, wandelt den Zeitpunkt vorher in ein Temporal.ZonedDateTime um.

Typische Anwendungen sind Zeitfenster für Logs, Ablaufzeiten für Caches oder Tokens und die Frage „Was war vor 15 Minuten?“. Dabei geht es immer um absolute Zeit und nicht um die Uhrzeit, die jemand vor Ort sieht.

Parameter

Name	Typ	Default	Beschreibung
$duration Pflicht	Temporal.Duration \| string \| object		Die Dauer, die abgezogen wird: eine `Temporal.Duration`, ein ISO-8601-Dauer-String wie `"PT45M"` oder ein Objekt mit Dauer-Feldern wie `{ minutes: 45 }`. Erlaubt sind nur Stunden und kleinere Einheiten. Negative Dauern verschieben den Zeitpunkt in die Zukunft.

Rückgabewert

Typ

Temporal.Instant

Beschreibung

Ein neues Temporal.Instant, das um duration früher liegt als der ursprüngliche Zeitpunkt.

Beispiele

Stunden und Minuten abziehen

const start = Temporal.Instant.from("2024-03-10T12:00:00Z");
const earlier = start.subtract({ hours: 5, minutes: 30 });

console.log(earlier.toString());
console.log(start.toString()); // Original bleibt unverändert

2024-03-10T06:30:00Z 2024-03-10T12:00:00Z

ISO-8601-Dauer-String und Duration-Objekt

const instant = Temporal.Instant.from("2024-03-10T12:00:00Z");

console.log(instant.subtract("PT90M").toString());

const timeout = Temporal.Duration.from({ seconds: 30, milliseconds: 500 });
console.log(instant.subtract(timeout).toString());

2024-03-10T10:30:00Z 2024-03-10T11:59:29.5Z

Log-Einträge der letzten 15 Minuten filtern

const now = Temporal.Instant.from("2024-05-01T10:00:00Z");
const threshold = now.subtract({ minutes: 15 });

const logs = [
  { msg: "Login", at: "2024-05-01T09:40:00Z" },
  { msg: "Upload", at: "2024-05-01T09:50:00Z" },
  { msg: "Logout", at: "2024-05-01T09:58:30Z" }
];

const recent = logs.filter(
  ({ at }) => Temporal.Instant.compare(Temporal.Instant.from(at), threshold) >= 0
);

console.log(recent.map((l) => l.msg));

[ 'Upload', 'Logout' ]

Tage abziehen: RangeError und korrekter Weg über ZonedDateTime

const instant = Temporal.Instant.from("2024-03-31T12:00:00Z");

try {
  instant.subtract({ days: 1 });
} catch (err) {
  console.log(err.name); // Tage sind bei Instant nicht erlaubt
}

// Genau 24 Stunden zurück
console.log(instant.subtract({ hours: 24 }).toString());

// Einen Kalendertag zurück in Berlin (Zeitumstellung am 31.03.2024)
const berlin = instant.toZonedDateTimeISO("Europe/Berlin");
console.log(berlin.subtract({ days: 1 }).toInstant().toString());

RangeError 2024-03-30T12:00:00Z 2024-03-30T13:00:00Z

// Wichtig · Fallstricke

Keine Kalendereinheiten: Enthält die Dauer years, months, weeks oder days (auch als String wie "P1D"), wirft die Methode einen RangeError. Nutze stattdessen { hours: 24 }, wenn du genau 24 Stunden meinst, oder toZonedDateTimeISO(zone).subtract({ days: 1 }) für einen Kalendertag. Bei einer Zeitumstellung ist das nicht dasselbe.
Wertebereich: Liegt das Ergebnis außerhalb des darstellbaren Bereichs von ±10⁸ Tagen um die Unix-Epoche, gibt es einen RangeError.
Ungültige Eingaben: Ein fehlerhafter Dauer-String oder ein Objekt ohne gültige Dauer-Felder führt zu einem RangeError bzw. TypeError.
Unveränderlichkeit: Die Methode verändert den ursprünglichen Zeitpunkt nicht. Du musst den Rückgabewert speichern.
Vergleiche: < und > funktionieren bei Temporal-Objekten nicht, weil valueOf() einen TypeError wirft. Nutze Temporal.Instant.compare() oder equals().
Browser-Unterstützung: Temporal ist neu. Nach meinem Kenntnisstand gibt es es ab Firefox 139 und ab Chrome 144 (bitte bei Bedarf in einer aktuellen Kompatibilitätstabelle prüfen). Für ältere Browser und Node.js gibt es den Polyfill @js-temporal/polyfill.

Siehe auch

Temporal.Instant.prototype.add() Temporal.Instant.prototype.since() Temporal.Instant.prototype.until() Temporal.Instant.compare() Temporal.Duration.from() Temporal.ZonedDateTime.prototype.subtract() Temporal.Instant