CKTIS / JavaScript
Références de graphe JSON et échappement des chemins
Conservez les objets partagés et les cycles dans un texte JSON grâce à des marqueurs `$ref` et à des chemins qui distinguent les caractères des clés des séparateurs.
Version : ECMAScript 2024 and the current web platform; runtime support varies
Syntaxe
Application-defined JSON graph marker: {"$ref":"<path>"}
Root path: "". Child path: parentPath + "/" + escapeToken(keyOrIndex).
escapeToken(token): replace ~ with ~0, then / with ~1.
To read a path as segments, treat "" as zero segments. For any other path, require a leading /, remove exactly that first /, then split the remainder at /, keeping empty segments. The path / has one empty segment. In each segment, replace ~1 with /, then ~0 with ~.Le JSON ordinaire décrit un arbre de valeurs, pas l’identité des objets. Par défaut, JSON.stringify() écrit séparément chaque occurrence d’un objet partagé hors cycle. JSON.parse() crée des objets distincts à partir de ces copies. Si la sérialisation rencontre un cycle, JSON.stringify() lève une TypeError.
Dans cette convention applicative, une WeakMap mémorise le premier chemin d’un objet avant d’en visiter les enfants. À chaque nouvelle rencontre du même objet, l’encodeur émet {"$ref":"<path>"}. Cet objet à champ unique de type chaîne est réservé aux références ; JSON.parse() ne les résout pas seul.
Dans un chemin de style JSON Pointer, "" désigne la racine et / sa propriété dont la clé est vide. Chaque segment est une clé d’objet ou un indice de tableau commençant à zéro. Avant de joindre les segments avec /, remplacez ~ par ~0, puis / par ~1. La clé a/~1 donne /a~1~01. À la lecture, "" ne contient aucun segment. Tout chemin non vide doit commencer par / : retirez uniquement ce premier /, puis découpez le reste aux / en conservant les segments vides. Le chemin / contient donc un seul segment vide. Dans chaque segment, remplacez ~1 par /, puis ~0 par ~. Cet échappement est distinct de celui des chaînes JSON et de l’encodage URI en pourcentage.
Après l’analyse du JSON, indexez d’abord les objets et tableaux réels, puis remplacez les marqueurs par leurs cibles. Cela permet aussi les références vers des cibles qui apparaissent plus loin. Pour les données non fiables, validez le format, limitez la taille et la profondeur, et rejetez les chemins invalides et les cibles absentes. N’utilisez pas eval() et ne parcourez pas les chaînes de prototypes.
Si vous avez besoin d’une copie plutôt que de texte, structuredClone() préserve les cycles et le partage pour les valeurs prises en charge. C’est une API de la plateforme web, pas une méthode de JSON ; sa disponibilité varie selon l’environnement d’exécution.
Exemples
{
const childPath = (path, key) =>
path + '/' + String(key).replace(/~/g, '~0').replace(/\//g, '~1');
const shared = { count: 1 };
const graph = { 'a/~1': shared, alias: shared };
graph.self = graph;
const seen = new WeakMap();
function encode(value, path = '') {
if (value === null || typeof value !== 'object') return value;
if (seen.has(value)) return { $ref: seen.get(value) };
seen.set(value, path);
if (Array.isArray(value)) {
return value.map((item, index) => encode(item, childPath(path, index)));
}
return Object.fromEntries(Object.entries(value).map(([key, item]) =>
[key, encode(item, childPath(path, key))]));
}
const text = JSON.stringify(encode(graph));
const restored = JSON.parse(text);
const nodes = new Map();
const links = [];
function index(node, path = '') {
nodes.set(path, node);
for (const [key, item] of Object.entries(node)) {
if (item === null || typeof item !== 'object') continue;
const keys = Object.keys(item);
if (!Array.isArray(item) && keys.length === 1 && keys[0] === '$ref' &&
typeof item.$ref === 'string') {
links.push([node, key, item.$ref]);
} else {
index(item, childPath(path, key));
}
}
}
index(restored);
for (const [owner, key, path] of links) {
if (!nodes.has(path)) throw new Error('Invalid reference path');
owner[key] = nodes.get(path);
}
console.log(text);
console.log(restored.alias === restored['a/~1']);
console.log(restored.self === restored);
}Résultat
{"a/~1":{"count":1},"alias":{"$ref":"/a~1~01"},"self":{"$ref":""}}
true
trueL’exemple utilise des données fiables : objets simples, tableaux sans trous et valeurs primitives représentables en JSON. Le décodeur compare les chemins échappés complets dans une `Map`, sans déséchapper les segments. Les deux résultats `true` confirment que le partage et le cycle ont été rétablis.
Leçons associées
- JavaScript · Leçon 17 · Avancé · Version : 4
Sources
- ECMAScript 2024 Language Specification — JSON.stringify
- ECMAScript 2024 Language Specification — JSON.parse
- ECMAScript 2024 Language Specification — WeakMap Objects
- ECMAScript 2024 Language Specification — Object.fromEntries
- HTML Standard — StructuredDeserialize
- HTML Standard — Structured cloning API
- RFC 6901 — JavaScript Object Notation (JSON) Pointer