new BigInt() — Methode · JavaScript-Referenz

Signatur

BigInt(value)

Beschreibung

BigInt() erzeugt aus einer Zahl, einer Zeichenkette, einem Wahrheitswert oder einem Objekt einen primitiven Wert vom Typ bigint. Mit BigInt lassen sich ganze Zahlen beliebiger Größe exakt darstellen, also auch jenseits von Number.MAX_SAFE_INTEGER (2⁵³ − 1). Typische Einsatzfälle sind große Datenbank-IDs (z. B. Snowflake-IDs), Kryptografie, exakte Zeitstempel in Nanosekunden oder Finanzberechnungen in kleinsten Einheiten.

Wichtig: Anders als bei Number oder String ist BigInt kein Konstruktor im klassischen Sinn. new BigInt(1) löst einen TypeError aus. Man ruft BigInt() daher immer als normale Funktion auf oder verwendet direkt ein Literal mit dem Suffix n, z. B. 123n.

Die Umwandlungsregeln sind streng:

Zahlen müssen ganzzahlig sein. BigInt(1.5), BigInt(NaN) und BigInt(Infinity) lösen einen RangeError aus.
Zeichenketten werden als ganze Zahl gelesen, auch mit den Präfixen 0x, 0o und 0b. Leerraum am Anfang und Ende wird entfernt, und eine leere Zeichenkette ergibt 0n. Dezimalpunkte, Exponenten oder das Suffix n führen zu einem SyntaxError.
Wahrheitswerte: true wird zu 1n, false zu 0n.
undefined, null und Symbol-Werte lösen einen TypeError aus.
Objekte werden zuerst über valueOf() bzw. toString() in einen primitiven Wert umgewandelt.

Parameter

Name	Typ	Default	Beschreibung
$value Pflicht	number \| string \| boolean \| bigint \| object		Der umzuwandelnde Wert. Zahlen müssen ganzzahlig sein. Zeichenketten müssen eine gültige ganze Zahl darstellen (dezimal, `0x`, `0o` oder `0b`).

Rückgabewert

Typ

bigint

Beschreibung

Ein primitiver BigInt-Wert. typeof liefert dafür "bigint", nicht "object".

Beispiele

Grundlegende Umwandlungen

console.log(BigInt(42));         // aus Number
console.log(BigInt('12345678901234567890')); // aus String
console.log(BigInt('0xff'));     // Hexadezimal
console.log(BigInt('  7  '));    // Leerraum wird entfernt
console.log(BigInt(true));       // aus Boolean
console.log(typeof BigInt(1));

42n 12345678901234567890n 255n 7n 1n bigint

new BigInt() ist nicht erlaubt

try {
  const x = new BigInt(10);
} catch (err) {
  console.log(err.constructor.name, '-', err.message);
}

// Richtig: als Funktion aufrufen oder ein Literal verwenden
const a = BigInt(10);
const b = 10n;
console.log(a === b);

TypeError - BigInt is not a constructor true

Große IDs aus einer API exakt verarbeiten

// IDs als String übertragen, sonst geht beim JSON.parse Genauigkeit verloren
const payload = '{"id":"1234567890123456789"}';
const { id } = JSON.parse(payload);

const userId = BigInt(id);
const nextId = userId + 1n;
console.log(nextId.toString());

// Zum Vergleich: der Weg über Number verliert Stellen
console.log(BigInt(Number(id)).toString());

1234567890123456790 1234567890123456768

Sichere Umwandlung mit Fehlerbehandlung

const toBigIntSafe = (value) => {
  try {
    return BigInt(value);
  } catch (err) {
    console.log(`${String(value)} -> ${err.name}`);
    return null;
  }
};

toBigIntSafe(1.5);        // Nachkommastellen
toBigIntSafe('1.5');      // ungültiger String
toBigIntSafe(undefined);  // nicht umwandelbar
console.log(toBigIntSafe(Math.trunc(1.5)));

1.5 -> RangeError 1.5 -> SyntaxError undefined -> TypeError 1n

// Wichtig · Fallstricke

Kein new: new BigInt() löst immer einen TypeError aus. Ein Wrapper-Objekt erhält man bei Bedarf nur mit Object(1n), was in der Praxis aber kaum gebraucht wird.
Genauigkeitsverlust vor der Umwandlung: BigInt(9007199254740993) ergibt 9007199254740992n, weil die Zahl schon als Number-Literal gerundet wird. Große Werte deshalb als String übergeben oder direkt als Literal 9007199254740993n schreiben.
Kein Mischen der Typen: 1n + 1 löst einen TypeError aus. Vorher ausdrücklich mit BigInt() oder Number() umwandeln. Vergleiche wie 1n == 1 oder 2n > 1 funktionieren dagegen.
Division: Das Ergebnis wird Richtung null abgeschnitten, 7n / 2n ergibt also 3n.
JSON: JSON.stringify({ a: 1n }) löst einen TypeError aus. Abhilfe schafft eine Replacer-Funktion oder BigInt.prototype.toJSON.
Math-Methoden nehmen keine BigInt-Werte an. Auch der unäre Operator +1n löst einen TypeError aus.
Kompatibilität: Unterstützt ab Chrome 67, Firefox 68, Safari 14 und Node.js 10.4. BigInt lässt sich nicht per Polyfill nachrüsten, weil die Literal-Syntax transpiliert werden müsste.
Sicherheit: Operationen mit BigInt laufen nicht in konstanter Zeit. Für kryptografische Geheimnisse sind sie daher anfällig für Timing-Angriffe.

Siehe auch

BigInt BigInt.asIntN() BigInt.asUintN() BigInt.prototype.toString() BigInt.prototype.toLocaleString() Number Number.MAX_SAFE_INTEGER typeof