Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / JavaScript

Referências em grafos JSON e escape de caminhos

Preserva objetos partilhados e ciclos em texto JSON com marcadores `$ref` e caminhos que distinguem os caracteres das chaves dos separadores.

Versão: ECMAScript 2024 and the current web platform; runtime support varies

Sintaxe

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

O JSON simples representa uma árvore de valores, não a identidade dos objetos. Por predefinição, JSON.stringify() escreve um objeto partilhado sem ciclos separadamente em cada ocorrência. JSON.parse() cria objetos distintos a partir dessas cópias. Se a serialização encontrar um ciclo, JSON.stringify() lança um TypeError.

Nesta convenção da aplicação, um WeakMap guarda o primeiro caminho de um objeto antes de visitar os seus descendentes. Quando volta a encontrar o mesmo objeto, o codificador emite {"$ref":"<path>"}. Este objeto com um único campo do tipo cadeia de caracteres está reservado para referências; JSON.parse() não as resolve por si só.

Num caminho ao estilo JSON Pointer, "" indica a raiz e / indica a sua propriedade com chave vazia. Cada segmento é uma chave de objeto ou um índice de array com início em zero. Antes de unir os segmentos com /, substitui ~ por ~0 e depois / por ~1. A chave a/~1 dá /a~1~01. Ao ler, trata "" como um caminho sem segmentos. Qualquer caminho não vazio tem de começar por /: remove apenas esse primeiro / e divide o resto usando / como separador, mantendo os segmentos vazios. Assim, o caminho / tem um único segmento vazio. Em cada segmento, substitui ~1 por / e depois ~0 por ~. Isto é distinto do escape de cadeias JSON e da codificação percentual de URI.

Depois de analisar o JSON, indexa primeiro os objetos e arrays reais e só depois substitui os marcadores pelos respetivos alvos. Assim funcionam também as referências para alvos que aparecem mais à frente. Para dados não fiáveis, valida o formato, limita o tamanho e a profundidade e rejeita caminhos inválidos e alvos inexistentes. Não uses eval() nem percorras cadeias de protótipos.

Se precisares de uma cópia em vez de texto, structuredClone() preserva os ciclos e a partilha para os valores suportados. É uma API da plataforma web, não um método de JSON; a disponibilidade varia consoante o ambiente de execução.

Exemplos

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

Resultado

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

O exemplo usa dados fiáveis: objetos simples, arrays sem lacunas e valores primitivos representáveis em JSON. O descodificador compara os caminhos completos já sujeitos a escape num `Map`, pelo que não precisa de reverter o escape dos segmentos. Os dois resultados `true` confirmam que a partilha e o ciclo foram restaurados.

Lições relacionadas

  • JavaScript · Lição 17 · Avançado · Versão: 4

Fontes