Base di conoscenzaCentro esami
ITItaliano
Scegli la lingua13

CKTIS / JavaScript

Riferimenti nei grafi JSON ed escape dei percorsi

Mantieni oggetti condivisi e cicli nel testo JSON usando marcatori `$ref` e percorsi che distinguono i caratteri delle chiavi dai separatori.

Versione: ECMAScript 2024 and the current web platform; runtime support varies

Sintassi

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 ~.

Il JSON ordinario rappresenta un albero di valori, non l’identità degli oggetti. Per impostazione predefinita, JSON.stringify() scrive separatamente ogni occorrenza di un oggetto condiviso non coinvolto in cicli. JSON.parse() crea oggetti distinti da quelle copie. Se la serializzazione incontra un ciclo, JSON.stringify() genera un TypeError.

In questa convenzione applicativa, una WeakMap memorizza il primo percorso di un oggetto prima di visitarne i figli. Ai successivi incontri con lo stesso oggetto, il codificatore emette {"$ref":"<path>"}. Questo oggetto con un unico campo di tipo stringa è riservato ai riferimenti; JSON.parse() non li risolve da solo.

In un percorso in stile JSON Pointer, "" indica la radice e / la sua proprietà con chiave vuota. Ogni segmento è una chiave di oggetto o un indice di array a partire da zero. Prima di unire i segmenti con /, sostituisci ~ con ~0 e poi / con ~1. Dalla chiave a/~1 si ottiene /a~1~01. In lettura, considera "" un percorso senza segmenti. Ogni percorso non vuoto deve iniziare con /: rimuovi solo questo primo / e separa il resto in corrispondenza di /, mantenendo i segmenti vuoti. Il percorso / contiene quindi un solo segmento vuoto. In ogni segmento, sostituisci ~1 con / e poi ~0 con ~. Questa operazione è distinta dall’escape delle stringhe JSON e dalla codifica percentuale degli URI.

Dopo il parsing, indicizza prima gli oggetti e gli array effettivi, poi sostituisci i marcatori con i relativi oggetti o array di destinazione. Funzionano così anche i riferimenti a elementi che compaiono più avanti. Per dati non attendibili, convalida il formato, limita dimensioni e profondità e rifiuta i percorsi non validi e le destinazioni mancanti. Non usare eval() né percorrere le catene dei prototipi.

Se serve una copia anziché del testo, structuredClone() mantiene cicli e condivisione per i valori supportati. È un’API della piattaforma web, non un metodo di JSON; la disponibilità dipende dall’ambiente di esecuzione.

Esempi

{
  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);
}

Risultato

{"a/~1":{"count":1},"alias":{"$ref":"/a~1~01"},"self":{"$ref":""}}
true
true

L’esempio usa dati attendibili: oggetti semplici, array senza buchi e valori primitivi rappresentabili in JSON. Il decodificatore confronta i percorsi completi già sottoposti a escape in una `Map`, quindi non deve decodificare i segmenti. I due risultati `true` confermano il ripristino della condivisione e del ciclo.

Lezioni correlate

  • JavaScript · Lezione 17 · Avanzato · Versione: 4

Fonti