Temporal.ZonedDateTime.prototype.nanosecond — Eigenschaft · JavaScript-Referenz

Signatur

get Temporal.ZonedDateTime.prototype.nanosecond

Beschreibung

Die Zugriffseigenschaft nanosecond liefert den Nanosekunden-Anteil (10^-9 Sekunde) der Uhrzeit eines Temporal.ZonedDateTime. Der Wert ist eine ganze Zahl von 0 bis 999. Gemeint sind nur die letzten drei Stellen des Sekundenbruchteils: Bei 12:34:56.123456789 ist millisecond gleich 123, microsecond gleich 456 und nanosecond gleich 789.

Es handelt sich um eine reine Getter-Eigenschaft ohne Setter. Da Temporal-Objekte unveränderlich sind, erzeugt man einen Wert mit anderer Nanosekunde über with({ nanosecond }), round() oder durch Rechnen mit add()/subtract().

Brauchbar ist die Eigenschaft überall, wo es um Zeitstempel mit hoher Genauigkeit geht, z. B. bei Mess- und Log-Daten, beim Abgleich mit Systemen, die Nanosekunden liefern (Datenbanken, Tracing), oder um beim Formatieren zu prüfen, ob noch Stellen unterhalb der Mikrosekunde vorhanden sind.

Rückgabewert

Typ

number

Beschreibung

Ganze Zahl von 0 bis 999: der Nanosekunden-Anteil innerhalb der aktuellen Mikrosekunde der Wanduhrzeit.

Beispiele

Sekundenbruchteil in seine Teile zerlegen

const zdt = Temporal.ZonedDateTime.from(
  "2021-07-01T12:34:56.123456789+02:00[Europe/Berlin]"
);

console.log(zdt.millisecond); // Millisekunden
console.log(zdt.microsecond); // Mikrosekunden
console.log(zdt.nanosecond);  // Nanosekunden

123 456 789

Nanosekunden entfernen: with() und round()

const zdt = Temporal.ZonedDateTime.from(
  "2021-07-01T12:34:56.123456789+02:00[Europe/Berlin]"
);

// Abschneiden: neues Objekt, das Original bleibt unverändert
const ohneNs = zdt.with({ nanosecond: 0 });
console.log(ohneNs.toString());

// Kaufmännisch auf Mikrosekunden runden
const gerundet = zdt.round({ smallestUnit: "microsecond" });
console.log(gerundet.microsecond, gerundet.nanosecond);

console.log(zdt.nanosecond); // Original unverändert

2021-07-01T12:34:56.123456+02:00[Europe/Berlin] 457 0 789

Zeitstempel aus Date haben nie Nanosekunden

const ausDate = Temporal.Instant
  .fromEpochMilliseconds(Date.now())
  .toZonedDateTimeISO("Europe/Berlin");

// Date arbeitet nur mit Millisekunden
console.log(ausDate.microsecond, ausDate.nanosecond);

// Nur mit höherer Genauigkeit gibt es Nanosekunden
const praezise = ausDate.add({ nanoseconds: 42 });
console.log(praezise.nanosecond);

0 0 42

Prüfen, ob eine Formatierung Stellen verliert

const hatSubMikrosekunden = (zdt) => zdt.nanosecond !== 0;

const messung = Temporal.ZonedDateTime.from(
  "2024-03-10T08:00:00.000000042+01:00[Europe/Berlin]"
);

if (hatSubMikrosekunden(messung)) {
  console.log("Volle Genauigkeit:", messung.toString({ fractionalSecondDigits: 9 }));
}

Volle Genauigkeit: 2024-03-10T08:00:00.000000042+01:00[Europe/Berlin]

// Wichtig · Fallstricke

Nur Teilwert, nicht Gesamtwert: nanosecond liefert nur die Stellen 7–9 des Sekundenbruchteils (0–999), nicht die Nanosekunden seit Sekundenbeginn. Den ganzen Bruchteil erhält man mit millisecond * 1e6 + microsecond * 1e3 + nanosecond, die absolute Zeit mit epochNanoseconds (ein BigInt).
Vorsicht mit Modulo: zdt.epochNanoseconds % 1000n ergibt bei Zeitpunkten vor 1970 einen negativen Wert, nanosecond dagegen ist immer 0–999.
Nur lesbar: Es gibt keinen Setter. Eine Zuweisung wie zdt.nanosecond = 5 wird ohne Strict Mode stillschweigend ignoriert und löst im Strict Mode (und in Modulen) einen TypeError aus. Stattdessen with({ nanosecond: 5 }) verwenden.
Werte außerhalb des Bereichs: with({ nanosecond: 1000 }) wird mit der Standardeinstellung overflow: \"constrain\" auf 999 begrenzt. Mit overflow: \"reject\" gibt es einen RangeError.
Kompatibilität: Temporal gibt es in Firefox 139+ und Chrome/Edge 144+, in Safari noch nicht. Für den produktiven Einsatz den Polyfill @js-temporal/polyfill oder temporal-polyfill einbinden. Date und performance.now() liefern in der Praxis keine echte Nanosekunden-Genauigkeit.

Siehe auch

Temporal.ZonedDateTime.prototype.microsecond Temporal.ZonedDateTime.prototype.millisecond Temporal.ZonedDateTime.prototype.second Temporal.ZonedDateTime.prototype.epochNanoseconds Temporal.ZonedDateTime.prototype.with() Temporal.ZonedDateTime.prototype.round() Temporal.PlainTime.prototype.nanosecond Temporal.ZonedDateTime