Number.isSafeInteger() — Methode · JavaScript-Referenz

Signatur

Number.isSafeInteger(testValue)

Beschreibung

Number.isSafeInteger() gibt true zurück, wenn der übergebene Wert vom Typ number ist, eine ganze Zahl ist und im Bereich von Number.MIN_SAFE_INTEGER (−9.007.199.254.740.991) bis Number.MAX_SAFE_INTEGER (9.007.199.254.740.991) liegt, jeweils einschließlich.

Eine sichere Ganzzahl (safe integer) ist eine Ganzzahl, die sich exakt als IEEE-754-Gleitkommazahl mit doppelter Genauigkeit darstellen lässt und deren Darstellung nicht durch Rundung einer anderen Ganzzahl entstanden sein kann. So ist 2 ** 53 - 1 sicher, 2 ** 53 dagegen nicht: Es ist zwar exakt darstellbar, aber 2 ** 53 + 1 wird auf genau diesen Wert gerundet. Ab dieser Grenze sind Vergleiche und Arithmetik mit Ganzzahlen also nicht mehr zuverlässig.

In der Praxis nutzt man die Methode, um IDs, Zähler, Zeitstempel oder aus JSON bzw. Benutzereingaben gelesene Zahlen zu prüfen, bevor man mit ihnen rechnet. Liegt ein Wert außerhalb des sicheren Bereichs, sollte man auf BigInt oder eine Bibliothek für beliebige Genauigkeit ausweichen.

Im Unterschied zu vielen älteren Prüfungen findet keine Typumwandlung statt: Zeichenketten wie "42" ergeben false.

Parameter

Name	Typ	Default	Beschreibung
$testValue Pflicht	any		Der zu prüfende Wert. Wird nicht in eine Zahl umgewandelt; nur echte `number`-Werte können `true` ergeben.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn testValue eine Zahl, ganzzahlig und im Bereich Number.MIN_SAFE_INTEGER bis Number.MAX_SAFE_INTEGER ist; sonst false.

Beispiele

Grundlegende Prüfungen

console.log(Number.isSafeInteger(3));                       // true
console.log(Number.isSafeInteger(2 ** 53 - 1));            // true
console.log(Number.isSafeInteger(2 ** 53));                // false
console.log(Number.isSafeInteger(-(2 ** 53 - 1)));         // true
console.log(Number.isSafeInteger(3.0));                    // true
console.log(Number.isSafeInteger(3.1));                    // false
console.log(Number.isSafeInteger(NaN));                    // false
console.log(Number.isSafeInteger(Infinity));               // false
console.log(Number.isSafeInteger("3"));                    // false
console.log(Number.isSafeInteger(10n));                    // false

true true false true true false false false false false

Warum die Grenze wichtig ist

const max = Number.MAX_SAFE_INTEGER;

// Ab 2^53 werden verschiedene Ganzzahlen gleich
console.log(max + 1 === max + 2);
console.log(Number.isSafeInteger(max + 1));

// Mit BigInt bleibt die Genauigkeit erhalten
console.log(BigInt(max) + 1n === BigInt(max) + 2n);

true false false

IDs aus einer API-Antwort validieren

const parseId = (value) => {
  const num = typeof value === "string" ? Number(value) : value;
  if (!Number.isSafeInteger(num) || num <= 0) {
    throw new RangeError(`Ungültige oder zu große ID: ${value}`);
  }
  return num;
};

console.log(parseId("12345"));

try {
  parseId("9007199254740993"); // größer als MAX_SAFE_INTEGER
} catch (err) {
  console.log(err.message);
}

12345 Ungültige oder zu große ID: 9007199254740993

Sichere Addition mit Fallback auf BigInt

const safeAdd = (a, b) => {
  const sum = a + b;
  return Number.isSafeInteger(sum) ? sum : BigInt(a) + BigInt(b);
};

console.log(safeAdd(1, 2));
console.log(safeAdd(Number.MAX_SAFE_INTEGER, 2));

3 9007199254740993n

// Wichtig · Fallstricke

Keine Typumwandlung: Number.isSafeInteger("5") ergibt false. Wer Zeichenketten prüfen will, muss sie vorher mit Number() umwandeln. Es gibt keine globale Funktion isSafeInteger().
BigInt: BigInt-Werte wie 10n ergeben immer false, da sie nicht vom Typ number sind.
Bereits verlorene Genauigkeit wird nicht erkannt: Das Ergebnis einer Rechnung kann wieder im sicheren Bereich liegen, obwohl ein Zwischenergebnis ungenau war (z. B. (2 ** 53 + 1) - 2). Prüfe daher Operanden und Ergebnis.
JSON-Parsing: JSON.parse() rundet große Ganzzahlen (etwa 64-Bit-IDs aus Datenbanken) stillschweigend. Solche IDs sollten als Zeichenkette übertragen werden.
5.0 gilt als Ganzzahl, da JavaScript nicht zwischen 5 und 5.0 unterscheidet; -0 ergibt ebenfalls true.
Kompatibilität: Teil von ES2015, in allen modernen Browsern und Node.js unterstützt; nicht im Internet Explorer. Einfacher Polyfill: Number.isInteger(v) && Math.abs(v) <= Number.MAX_SAFE_INTEGER.

Siehe auch

Number.isInteger() Number.MAX_SAFE_INTEGER Number.MIN_SAFE_INTEGER Number.isFinite() Number.isNaN() BigInt Number