Number.MAX_SAFE_INTEGER — Eigenschaft · JavaScript-Referenz

Signatur

Number.MAX_SAFE_INTEGER

Beschreibung

Number.MAX_SAFE_INTEGER ist eine statische, nicht beschreibbare Dateneigenschaft des Number-Konstruktors mit dem Wert 9007199254740991 (2**53 - 1). Sie ist die größte Ganzzahl, bei der JavaScript noch garantieren kann, dass sie exakt dargestellt wird und sich eindeutig von ihren Nachbarn unterscheiden lässt.

Der Grund liegt im Zahlenformat: JavaScript-Zahlen sind 64-Bit-Gleitkommazahlen nach IEEE 754 mit 52 Bit Mantisse (plus implizitem Bit). Oberhalb von 2**53 reicht die Genauigkeit nicht mehr, um jede Ganzzahl abzubilden – Werte werden gerundet, und z. B. 2**53 + 1 ergibt wieder 2**53.

Man nutzt die Konstante vor allem zur Validierung: bei IDs aus Datenbanken oder APIs, bei Zählern, Zeitstempeln in Nanosekunden oder beim Parsen großer Zahlen aus JSON. Werden größere Ganzzahlen benötigt, ist BigInt das passende Werkzeug. Das Gegenstück für die untere Grenze ist Number.MIN_SAFE_INTEGER (-(2**53 - 1)); zur Prüfung einzelner Werte dient Number.isSafeInteger().

Beispiele

Wert und Präzisionsverlust oberhalb der Grenze

const max = Number.MAX_SAFE_INTEGER;
console.log(max);            // 9007199254740991
console.log(max === 2 ** 53 - 1);

// Jenseits der Grenze kollidieren Werte
console.log(max + 1 === max + 2);
console.log(max + 2);

9007199254740991 true true 9007199254740992

IDs aus einer API validieren

const parseId = (raw) => {
  const id = Number(raw);
  if (!Number.isInteger(id) || id < 0 || id > Number.MAX_SAFE_INTEGER) {
    throw new RangeError(`Unsichere ID: ${raw} – bitte als String oder BigInt verarbeiten`);
  }
  return id;
};

console.log(parseId('4711'));
try {
  parseId('9007199254740993');
} catch (err) {
  console.log(err.message);
}

4711 Unsichere ID: 9007199254740993 – bitte als String oder BigInt verarbeiten

Zähler mit Überlaufschutz und Umstieg auf BigInt

let counter = Number.MAX_SAFE_INTEGER - 1;

const increment = (n) =>
  n >= Number.MAX_SAFE_INTEGER ? BigInt(n) + 1n : n + 1;

counter = increment(counter); // 9007199254740991 (number)
counter = increment(counter); // 9007199254740992n (bigint)
console.log(counter, typeof counter);

9007199254740992n bigint

Große Zahlen in JSON erkennen

const json = '{"orderId": 12345678901234567890}';
const { orderId } = JSON.parse(json);

console.log(orderId);
console.log(Number.isSafeInteger(orderId));
console.log(orderId > Number.MAX_SAFE_INTEGER);

12345678901234567000 false true

// Wichtig · Fallstricke

Nicht mit Number.MAX_VALUE verwechseln: MAX_VALUE (ca. 1.8e308) ist die größte darstellbare Zahl überhaupt, aber weit oberhalb der Grenze, bis zu der Ganzzahlen exakt sind.
Stiller Präzisionsverlust: Oberhalb der Grenze wirft JavaScript keinen Fehler, sondern rundet stillschweigend. Vergleiche wie a === b können dann trotz unterschiedlicher Eingaben true ergeben.
JSON und 64-Bit-IDs: JSON.parse() wandelt große Ganzzahlen (z. B. Twitter-/Snowflake-IDs, 64-Bit-Datenbankschlüssel) in ungenaue Zahlen um. Solche Werte sollten als String übertragen werden oder mit einem Reviver bzw. BigInt verarbeitet werden.
Bitoperatoren wie |, & oder << arbeiten nur mit 32-Bit-Ganzzahlen – dort liegt die Grenze viel niedriger (2**31 - 1).
Die Eigenschaft ist schreibgeschützt; Zuweisungen werden ignoriert bzw. werfen im Strict Mode einen TypeError.
Kompatibilität: Seit ES2015 in allen modernen Browsern und Node.js verfügbar; nicht im Internet Explorer (dort Ersatz: Math.pow(2, 53) - 1).

Siehe auch

Number.MIN_SAFE_INTEGER Number.MAX_VALUE Number.EPSILON BigInt Number