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
trueO 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
- 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