JSON.rawJSON() — Methode · JavaScript-Referenz

Signatur

JSON.rawJSON(string)

Beschreibung

JSON.rawJSON() packt einen primitiven JSON-Text (Zahl, String, true, false oder null) in ein spezielles Objekt. Trifft JSON.stringify() beim Serialisieren auf so ein Objekt, schreibt es den enthaltenen Text wörtlich in die Ausgabe. Der Text wird dabei nicht in einen JavaScript-Wert umgewandelt und danach wieder zurückübersetzt.

Das hilft vor allem dann, wenn JavaScript-Werte sich nicht verlustfrei als JSON darstellen lassen. Typische Fälle:

BigInt-Werte als echte JSON-Zahlen ausgeben statt als String. Normalerweise wirft JSON.stringify() bei BigInt einen TypeError.
Zahlen mit mehr als 53 Bit Genauigkeit, etwa IDs oder Beträge, die mit einem Number ungenau würden.
Dezimalzahlen mit fester Schreibweise wie 19.90, die sonst zu 19.9 gekürzt würden.

Das zurückgegebene Objekt hat den Prototyp null, ist mit Object.freeze() eingefroren und besitzt genau eine Eigenschaft rawJSON mit dem ursprünglichen Text. Ob ein Wert so ein Objekt ist, prüft man mit JSON.isRawJSON(). Das Gegenstück beim Einlesen ist der dritte Parameter context der Reviver-Funktion von JSON.parse(). Über context.source erhält man dort den ursprünglichen Quelltext eines primitiven Werts.

Parameter

Name	Typ	Default	Beschreibung
$string Pflicht	string		Der JSON-Text. Andere Werte werden vorher in einen String umgewandelt. Der Text muss gültiges JSON für einen primitiven Wert sein (Zahl, String in doppelten Anführungszeichen, `true`, `false`, `null`). Leerzeichen am Anfang oder Ende sind nicht erlaubt.

Rückgabewert

Typ

Object

Beschreibung

Ein eingefrorenes Objekt mit dem Prototyp null und der Eigenschaft rawJSON, die den übergebenen Text enthält. Ist der Text ungültig, wirft die Methode einen SyntaxError.

Beispiele

BigInt verlustfrei als JSON-Zahl serialisieren

const bestellung = { id: 12345678901234567890n, menge: 3 };

const json = JSON.stringify(bestellung, (key, value) =>
  typeof value === 'bigint' ? JSON.rawJSON(value.toString()) : value
);

console.log(json);

{"id":12345678901234567890,"menge":3}

Round-Trip zusammen mit JSON.parse und context.source

const eingang = '{"kontoId": 9007199254740993, "name": "Max"}';

// Beim Einlesen: große Zahl als BigInt aus dem Quelltext übernehmen
const daten = JSON.parse(eingang, (key, value, context) =>
  key === 'kontoId' ? BigInt(context.source) : value
);
console.log(daten.kontoId); // exakt, ohne Rundung

// Beim Ausgeben: BigInt wieder als rohe Zahl schreiben
const ausgabe = JSON.stringify(daten, (key, value) =>
  typeof value === 'bigint' ? JSON.rawJSON(String(value)) : value
);
console.log(ausgabe);

9007199254740993n {"kontoId":9007199254740993,"name":"Max"}

Feste Dezimalschreibweise für Preise beibehalten

const artikel = {
  name: 'Kaffee',
  preisNormal: 19.90,
  preisRoh: JSON.rawJSON('19.90')
};

console.log(JSON.stringify(artikel));

{"name":"Kaffee","preisNormal":19.9,"preisRoh":19.90}

Eigenschaften des Objekts und ungültige Eingaben

const roh = JSON.rawJSON('"hallo"');
console.log(roh.rawJSON);                  // '"hallo"'
console.log(JSON.isRawJSON(roh));          // true
console.log(Object.isFrozen(roh));         // true
console.log(Object.getPrototypeOf(roh));   // null

for (const text of ['{"a":1}', '[1,2]', ' 42', 'hallo']) {
  try {
    JSON.rawJSON(text);
  } catch (err) {
    console.log(`${text} -> ${err.name}`);
  }
}

"hallo" true true null {"a":1} -> SyntaxError [1,2] -> SyntaxError 42 -> SyntaxError hallo -> SyntaxError

// Wichtig · Fallstricke

Nur primitive Werte: Objekte und Arrays ({…}, […]) sind nicht erlaubt und lösen einen SyntaxError aus. Dasselbe gilt für Leerzeichen am Anfang oder Ende und für Strings ohne doppelte Anführungszeichen. So kann man über rawJSON keine beliebigen Strukturen in die Ausgabe schmuggeln.
Kein normaler Wert in JavaScript: Das Objekt ist nur für JSON.stringify() etwas Besonderes. Rechnen oder Vergleichen damit funktioniert nicht, dafür braucht man den Inhalt von .rawJSON oder einen BigInt.
Genauigkeit beim Empfänger: Die ausgegebene Zahl ist zwar exakt, aber viele JSON-Parser, auch ein normales JSON.parse() ohne Reviver, runden große Zahlen trotzdem auf Number. Prüfen Sie, ob die Gegenseite damit umgehen kann.
Kompatibilität: Die Methode stammt aus dem Stage-3-Proposal „JSON.parse source text access“ und gehört noch nicht zum fertigen ECMAScript-Standard. Sie läuft in Chromium ab 114, Firefox ab 135, Safari ab 18.4 und Node.js ab 21. Vor dem Einsatz mit typeof JSON.rawJSON === 'function' prüfen und bei Bedarf ein Polyfill nutzen oder BigInt als String ausgeben.

Siehe auch

JSON.isRawJSON() JSON.stringify() JSON.parse() JSON BigInt Object.freeze() new URIError()