JSON : mthode statique parse()

Exemple interactif

const json = '{"result":true, "count":42}';
const obj = JSON.parse(json);

console.log(obj.count);
// Rsultat attendu : 42

console.log(obj.result);
// Rsultat attendu : true

Syntaxe

JSON.parse(text)
JSON.parse(text, reviver)

Paramtres

text

La chane de caractres analyser comme du JSON. Voir l'objet JSON pour une description de la syntaxe JSON.

reviver Facultatif

Si c'est une fonction, elle dfinit comment chaque valeur produite par l'analyse est transforme avant d'tre retourne. Les valeurs non appelables sont ignores. La fonction est appele avec les arguments suivants :

key

La cl associe la valeur.

value

La valeur produite par l'analyse.

context Facultatif

Un objet contexte qui contient l'tat pertinent pour l'expression en cours de restauration. C'est un nouvel objet chaque appel de la fonction reviver. Il n'est transmis que lors de la restauration de valeurs primitives, mais pas lorsque value est un objet ou un tableau. Il contient la proprit suivante :

source

La chane de caractres JSON d'origine reprsentant cette valeur.

Valeur de retour

L'objet (Object), le tableau (Array), la chane de caractres, le nombre, le boolen ou la valeur null correspondant au text JSON fourni.

Exceptions

SyntaxError

Leve si la chane de caractres analyser ne contient pas du JSON valide.

Description

JSON.parse() analyse une chane de caractres JSON selon la grammaire JSON, puis value la chane comme s'il s'agissait d'une expression JavaScript. La seule situation o un texte JSON reprsente une valeur diffrente de la mme expression JavaScript concerne la cl "__proto__" voir Syntaxe des littraux d'objet et JSON.

Le paramtre reviver

Si un reviver est dfini, la valeur obtenue par l'analyse est transforme avant d'tre retourne. Plus prcisment, la valeur calcule et toutes ses proprits (selon un parcours en profondeur (angl.), en commenant par les proprits les plus imbriques et en remontant jusqu' la valeur d'origine) sont passes individuellement au reviver.

Le reviver est appel avec l'objet contenant la proprit en cours de traitement comme valeur de this (sauf si vous dfinissez le reviver comme une fonction flche, auquel cas il n'y a pas de liaison distincte de this) et deux arguments : key et value, reprsentant respectivement le nom de la proprit sous forme de chane de caractres (mme pour les tableaux) et la valeur de la proprit. Pour les valeurs primitives, un paramtre supplmentaire context est transmis, qui contient le texte source de cette valeur. Si la fonction reviver retourne undefined (ou ne retourne aucune valeur par exemple si l'excution s'arrte la fin de la fonction), la proprit est supprime de l'objet. Sinon, la proprit est redfinie avec la valeur retourne. Si le reviver ne transforme que certaines valeurs et pas d'autres, assurez-vous de retourner toutes les valeurs non transformes telles quelles sinon, elles seront supprimes de l'objet obtenu.

De faon similaire au paramtre replacer de JSON.stringify(), pour les tableaux et objets, reviver sera appel en dernier sur la valeur racine avec une chane de caractres vide comme key et l'objet racine comme value. Pour les autres valeurs JSON valides, reviver fonctionne de faon similaire et est appel une fois avec une chane de caractres vide comme key et la valeur elle-mme comme value.

Si vous retournez une autre valeur depuis reviver, cette valeur remplacera compltement la valeur analyse l'origine. Cela s'applique mme la valeur racine. Par exemple :

const transformedObj = JSON.parse('[1,5,{"s":1}]', (key, value) =>
  typeof value === "object" ? undefined : value,
);

console.log(transformedObj); // undefined

Il n'existe aucun moyen de contourner cela de faon gnrique. Vous ne pouvez pas traiter spcifiquement le cas o key est une chane de caractres vide, car les objets JSON peuvent aussi contenir des cls qui sont des chanes de caractres vides. Vous devez savoir trs prcisment quel type de transformation est ncessaire pour chaque cl lors de l'implmentation du reviver.

Notez que reviver est excut aprs l'analyse de la valeur. Par exemple, les nombres dans le texte JSON auront dj t convertis en nombres JavaScript, et peuvent perdre en prcision lors du processus. Une faon de transfrer de grands nombres sans perte de prcision est de les srialiser en tant que chanes de caractres, puis de les restaurer en des BigInt, ou dans d'autres formats prcision arbitraire appropris.

Vous pouvez galement utiliser la proprit context.source pour accder au texte source JSON d'origine reprsentant la valeur, comme illustr ci-dessous :

const bigJSON = '{"gross_gdp": 12345678901234567890}';
const bigObj = JSON.parse(bigJSON, (key, value, context) => {
  if (key === "gross_gdp") {
    // Ignorer la valeur car elle a dj perdu en prcision
    return BigInt(context.source);
  }
  return value;
});

Exemples

Utiliser la mthode parse()

JSON.parse("{}"); // {}
JSON.parse("true"); // true
JSON.parse('"foo"'); // "foo"
JSON.parse('[1, 5, "false"]'); // [1, 5, "false"]
JSON.parse("null"); // null

Utiliser le paramtre reviver

JSON.parse(
  '{"p": 5}',
  (key, value) =>
    typeof value === "number"
      ? value * 2 // retourner value * 2 pour les nombres
      : value, // retourner tout le reste inchang
);
// { p: 10 }

JSON.parse('{"1": 1, "2": 2, "3": {"4": 4, "5": {"6": 6}}}', (key, value) => {
  console.log(key);
  return value;
});
// 1
// 2
// 4
// 6
// 5
// 3
// ""

Utiliser reviver avec le replacer de JSON.stringify()

Pour qu'une valeur puisse tre correctement srialise puis dsrialise (c'est--dire qu'elle soit dsrialise en le mme objet d'origine), le processus de srialisation doit prserver les informations de type. Par exemple, vous pouvez utiliser le paramtre replacer de JSON.stringify() cet effet :

// Les Map sont normalement srialises comme des objets sans proprits.
// Nous pouvons utiliser le paramtre replacer pour dfinir les entres  srialiser.
const map = new Map([
  [1, "un"],
  [2, "deux"],
  [3, "trois"],
]);

const jsonText = JSON.stringify(map, (key, value) =>
  value instanceof Map ? Array.from(value.entries()) : value,
);

console.log(jsonText);
// [[1,"un"],[2,"deux"],[3,"trois"]]

const map2 = JSON.parse(jsonText, (key, value) =>
  Array.isArray(value) && value.every(Array.isArray) ? new Map(value) : value,
);

console.log(map2);
// Map { 1 => "un", 2 => "deux", 3 => "trois" }

Comme JSON ne possde pas de syntaxe permettant d'annoter les mtadonnes de type, pour restaurer des valeurs qui ne sont pas de simples objets, vous devez envisager l'une des solutions suivantes :

• Srialiser l'objet entier en une chane de caractres et le prfixer avec une tiquette de type.
•  Deviner  en fonction de la structure des donnes (par exemple, un tableau de tableaux deux lments)
• Si la structure de la charge utile est fixe, se baser sur le nom de la proprit (par exemple, toutes les proprits nommes registry contiennent des objets Map).

JSON illgal

Lorsque JSON.parse reoit une chane de caractres qui ne respecte pas la grammaire JSON, il lve une exception SyntaxError.

Les tableaux et objets ne peuvent pas avoir de virgules finales en JSON :

JSON.parse("[1, 2, 3, 4, ]");
// SyntaxError: Unexpected token ] in JSON at position 13

JSON.parse('{"foo": 1, }');
// SyntaxError: Unexpected token } in JSON at position 12

Les chanes de caractres JSON doivent tre dlimites par des guillemets doubles (et pas simples) :

JSON.parse("{'foo': 1}");
// SyntaxError: Unexpected token ' in JSON at position 1

JSON.parse("'string'");
// SyntaxError: Unexpected token ' in JSON at position 0

Si vous crivez du JSON l'intrieur d'une chane de caractres littrale JavaScript, vous devez soit utiliser des guillemets simples pour dlimiter la chane de caractres JavaScript, soit chapper les guillemets doubles qui dlimitent la chane de caractres JSON :

JSON.parse('{"foo": 1}'); // OK
JSON.parse("{\"foo\": 1}"); // OK

Spcifications

Compatibilit des navigateurs

Voir aussi

• La mthode JSON.stringify()