JSON Toolkit

Analyser du JSON avant la fin de la réception : aperçu en flux et réparation incrémentale

L’essentiel : Les LLM émettent du JSON token par token et les API livrent leurs réponses par fragments, mais JSON.parse refuse de travailler tant que le document complet n'est pas là. Ce guide distingue trois styles d'implémentation — réparation complète, incrément réel et analyse partielle — et montre comment un masque Allow stabilise l'aperçu, avec des mesures de pipeline et du code prêt pour la production.

Intermédiaire~5 min de lecturePublié le 2026-11-16Mis à jour le 2026-11-16
Schéma de l'analyse partielle et de la réparation incrémentale sur des fragments JSON en flux

JSON.parse promet « je ne démarre qu'une fois le document entier arrivé », tandis que le flux promet « je te livre les données fragment par fragment ». Le conflit ne porte pas sur la vitesse mais sur la sémantique de complétude : un document inachevé n'a pas encore de résultat d'analyse correct.

Le symptôme : trois scénarios qui ne peuvent pas attendre le texte entier

Premier scénario, les applications LLM. Le modèle émet le JSON token par token ; une sortie structurée de 8 Ko peut mettre des dizaines de secondes à arriver pendant que l'utilisateur fixe un panneau vide — alors que les premiers champs étaient affichables dès la première seconde. Deuxième scénario, les passerelles et proxys : l'amont pousse une réponse de dizaines de mégaoctets en fragments HTTP, et un proxy qui veut filtrer des champs avant de transmettre multiplie son pic mémoire s'il bufferise tout via res.json(). Troisième scénario, les files de messages et les pipelines de journaux : les enregistrements NDJSON arrivent les uns après les autres et le consommateur préfère ne pas accumuler.

Le point commun est clair : les données arrivent progressivement alors que l'analyseur standard n'accepte qu'un document complet. JSON.parse lance Unexpected end of JSON input au fragment 1, lance la même erreur au fragment 65 et ne renvoie un résultat qu'au tout dernier. Attendre n'est pas la seule option — mais il faut d'abord décider ce que signifie « analyser » un document inachevé.

La sémantique de l'analyse par préfixe : chaque fragment est-il valide ?

Prenez un tableau de commandes de 7847 octets, découpez-le en fragments de 120 caractères pour simuler une arrivée en flux (Node v22.13.1, jsonrepair 3.15.0, partial-json 0.1.7), puis exécutez trois analyseurs sur chaque préfixe :

Approche Réussites sur 66 préfixes Temps cumulé Sémantique
JSON.parse 1 (seul le dernier fragment) 2,1 ms tout ou rien
partial-json (Allow.ALL) 66 (dès le fragment 1) 14,3 ms renvoie toujours « ce qui est connu à ce stade »
jsonrepair réexécuté sur chaque préfixe 66 23,8 ms analysable après complétion des accolades, recalculé de zéro à chaque fois

Deux conclusions comptent. D'abord, l'échec de JSON.parse ne porte aucune information : la position signalée est toujours la fin, on ne sait ni combien il manque ni si la partie reçue est cohérente. Ensuite, réexécuter la réparation complète sur chaque préfixe fonctionne mais coûte : la longueur moyenne par appel croît linéairement, le coût cumulé grimpe en O(n²). 23,8 ms paraît anodin ; à l'échelle du mégaoctet, le même facteur devient des secondes de CPU gaspillées.

Notez aussi que « analysable par préfixe » ne veut pas dire « complet ». Le dernier nombre d'un préfixe complété peut être prolongé par le fragment suivant, et la dernière chaîne peut être coupée au milieu d'une séquence d'échappement — c'est la racine de tous les problèmes de stabilité d'aperçu.

Trois styles d'implémentation et leur place

Les bibliothèques de flux se répartissent en trois postures, et se tromper de posture coûte plus cher que se tromper de bibliothèque :

Bibliothèque Posture À utiliser quand À éviter quand
jsonrepair (3.15.0) réparation complète + flux Transform l'entrée deviendra un document complet et il faut une sortie sans perte on veut juste un aperçu (la réparation émet du texte, pas des objets)
partial-json (0.1.7) analyse partielle, peut abandonner les fins inachevées aperçus UI : chaque préfixe doit donner un objet exploitable persistance (l'aperçu peut manquer des champs et vaciller sur les nombres)
jsonmend (0.1.3) réparation réellement incrémentale, corpus de conformité ouvert pipelines qui produisent une version par fragment sans re-scanner document terminé (une analyse complète est plus rapide)

Ce ne sont pas des concurrents. Le sous-chemin ./stream de jsonrepair exporte jsonrepairTransform, un flux Transform standard : les fragments entrent à gauche, du JSON réparé sort à droite, et la concaténation est garantie égale à l'analyse du texte complet — la promesse decode(encode(x)) === x est tenue. partial-json tient une autre promesse : chaque préfixe donne immédiatement un objet, au prix d'abandonner « le résultat ne changera plus ». jsonmend contraint une troisième voie avec un corpus de conformité public : incrément réel, sémantique alignée, base de régression partagée entre implémentations.

Le masque Allow : quels champs osent apparaître dans l'aperçu

Le cœur de partial-json n'est pas « analyser des entrées aussi cassées soient-elles » mais l'appelant déclare quelle incomplétude il accepte. Le masque combine des bits par type (STR, NUM, ARR, OBJ, ...) ; retirer un bit retire de l'aperçu les valeurs inachevées de ce type :

import { parse, Allow } from 'partial-json';

parse('{"price": 12', Allow.ALL);
// → { price: 12 }        12 est « lu jusqu'ici »
parse('{"price": 1234.5', Allow.ALL);
// → { price: 1234.5 }    même champ, nouvelle valeur : l'aperçu vacille
parse('{"price": 12', Allow.ALL & ~Allow.NUM);
// → {}                   sans le bit NUM, les nombres inachevés restent cachés

C'est la trouvaille la plus utile du test : les nombres destinés à être prolongés — prix, compteurs — peuvent changer à chaque image affichée, tandis que Allow.ALL & ~Allow.NUM les fait patienter jusqu'à leur achèvement. Même logique pour les chaînes : une chaîne coupée au milieu d'un échappement Unicode est abandonnée sans risque par partial-json 0.1.7 plutôt que devinée. La stabilité de l'aperçu n'est pas un cadeau de l'analyseur ; l'appelant la paie avec le masque.

Ce que coûte une réparation en flux : tampon de rétrospection et copies quadratiques

Un pipeline en flux n'est pas une boucle for autour de l'API complète. Sur le même échantillon de 66 fragments, le pipeline jsonrepairTransform a pris 6,7 ms au total contre 23,8 ms cumulées pour la réparation complète réexécutée par préfixe — l'écart de 3,5× vit dans l'implémentation : la voie en flux ne rétrospective que dans la fenêtre nécessaire et ajoute la sortie de façon incrémentale au lieu de recopier le texte précédent.

Le portage du cœur en flux de jsonrepair vers ArkTS sur HarmonyOS documente trois coûts concrets : la voie streaming amont accumule un tampon de rétrospection, ce qui fait paradoxalement attendre les petits documents jusqu'au flush — l'auteur a donc écrit un IncrementalRepairer séparé pour prévisualiser les textes courts pendant la réception ; la voie régulière amont recopie la sortie entière de façon quadratique, corrigé dans le portage avec un OutputBuilder ; et un piège de caractère frontière — après le remplacement du test de fin text[i] === undefined par charAt, ''.includes('') toujours vrai trompe les tests d'appartenance de caractères, il faut donc bloquer d'abord la lecture hors bornes par une garde de chaîne vide. Ces détails expliquent pourquoi la réparation en flux mérite sa propre case : sa complexité d'ingénierie est d'un autre ordre que la réparation ponctuelle.

Une limite connue mérite d'être notée : l'issue #214 de jsonrepair signale que la réparation en flux refuse un préfixe légal où manque une virgule avant une valeur préfixée par une barre oblique — dans un flux, « le caractère suivant n'est pas encore arrivé » et « l'entrée est invalide » sont difficiles à distinguer lexicalement, et la fenêtre de rétrospection est le prix de cette ambiguïté.

Mise en œuvre : aperçu et persistance suivent deux chemins

Réunissez la sémantique en un pipeline avec une règle unique : analyse partielle pour l'aperçu, analyse stricte pour la persistance.

import { jsonrepairTransform } from 'jsonrepair/stream';
import { parse as partialParse, Allow } from 'partial-json';

// Voie 1 : pipeline sans perte. Fragments en entrée, JSON réparé en sortie, contrôle strict à la fin
const tr = jsonrepairTransform();
tr.pipe(finalSink);                 // finalSink exécute JSON.parse plus la validation métier
chunkStream.pipe(tr);

// Voie 2 : pipeline d'aperçu. Une image par préfixe ; nombres et chaînes inachevés masqués
function onChunk(buffer) {
  const preview = partialParse(buffer, Allow.ALL & ~Allow.NUM & ~Allow.STR);
  render(preview);                  // ne dessiner que les champs stables
}

Les deux voies ont des contrats différents et ne se remplacent pas : les images d'aperçu peuvent manquer des champs, pas les images persistées ; une image persistée doit attendre la fin du flux et passer un JSON.parse complet plus la validation métier, et une image d'aperçu n'est jamais persistée. Quand l'amont est un LLM, la persistance exige aussi de juger la troncature par le motif d'arrêt — ce flux « examiner stop_reason avant de réparer » est développé dans Réparation du JSON tronqué du LLM.

Quand ne pas passer en flux

Trois conditions de veto ; si l'une s'applique, analysez simplement tout : fichiers petits — sous 22 Mo environ un JSON.parse ordinaire finit en moins d'une seconde et le flux n'ajoute que de la complexité ; statistiques ponctuelles — pour l'agrégation, jq --stream ou le NDJSON ligne à ligne est plus simple, voir le guide des fichiers JSONL ; l'aval n'accepte pas de données partielles — les totaux sont le cas classique : une valeur intermédiaire d'aperçu multipliée par erreur est un bug financier, l'aperçu en flux ne vaut alors rien de plus qu'une barre de progression.

Le flux résout « on ne peut pas attendre », pas « on veut plus vite ». À texte égal, l'analyse complète dépense toujours moins de CPU total que n'importe quel schéma en flux ; ce qu'on achète, c'est le délai jusqu'au premier fragment exploitable, un niveau de mémoire constant et la capacité de traiter en recevant. Décidez ce compromis explicitement et le choix de la bibliothèque cessera de vaciller.

FAQ

Peut-on persister directement un objet d'aperçu ?

Non. Un aperçu est un instantané de « ce qui est connu à ce stade » : les nombres peuvent être prolongés par le fragment suivant, les chaînes coupées, les champs provisoirement absents. Avant persistance, attendez la fin du flux, exécutez un JSON.parse strict sur le texte complet puis la validation métier. L'aperçu n'appartient qu'à la couche UI.

partial-json ou jsonrepair ?

Tout dépend de ce que vous voulez : du texte ou des objets. Pour du texte réparé sans perte qu'un composant aval analysera à nouveau, prenez jsonrepair — sa sortie en flux est garantie égale à l'analyse du texte complet. Pour un objet à chaque préfixe afin d'alimenter un aperçu UI, prenez partial-json et configurez le masque Allow champ par champ.

Le flux réduit-il le temps total ?

Non. En temps CPU total, l'analyse complète reste toujours la plus rapide ; le flux paie en plus la maintenance d'état. Ce qu'il achète, ce sont trois choses : le délai jusqu'au premier fragment exploitable, un niveau de mémoire qui ne croît pas avec la taille du document, et la capacité de transmettre, filtrer ou afficher en recevant.

Les éléments d'un tableau arrivent un par un et je veux les traiter un par un ?

C'est une autre voie : le streamArray de stream-json émet {key, value} à la fermeture de chaque élément et, associé à for await, produit naturellement une contre-pression — adapté aux imports en lot « analyser puis insérer », une granularité différente de l'aperçu documentaire décrit ici.

Références

Outils associés

Articles liés

Guide de réparation JSON : sauver les sorties LLM cassées sans perdre la confiance

Les sorties LLM enveloppées de balises markdown, truffées de virgules finales et de littéraux Python, sont rejetées par tout parseur strict — tout comme les configs éditées à la main sans guillemets. Ce guide trace la vraie frontière entre neuf classes d'erreurs réparables et quatre irréparables, explique pourquoi une machine à états bat les regex, et fournit une chaîne d'analyse prête pour la production avec jsonrepair et json-repair.

Intermédiaire~6 min de lectureMis à jour le 2026-11-08

Le JSON d'un LLM est tronqué : regardez d'abord la raison d'arrêt, ensuite la réparation

Le modèle renvoie un JSON coupé au milieu, et le parseur ne vous donne qu'un numéro de colonne. Refermer les accolades le rend de nouveau analysable, mais chaque champ manquant disparaît dans les données. Cet article trace la frontière entre ce qu'une réparation de troncature peut honnêtement récupérer et ce qui doit être relancé : filtrage par stop_reason, dimensionnement du plafond, ordre des champs du schéma.

Pratique~5 min de lectureMis à jour le 2026-11-14

JSONL en pratique : ouvrir, convertir et déboguer les lignes invalides

Passer un fichier .jsonl entier à JSON.parse et obtenir une erreur signifie presque toujours que la stratégie de lecture est fausse, pas que le fichier est cassé. Ce guide couvre les façons standard d'inspecter et de lire un JSONL ligne par ligne, les commandes de conversion vers et depuis un tableau JSON, un tableau de six types de lignes invalides, et la bonne façon de consommer du NDJSON depuis une réponse HTTP en flux.

Intermédiaire~9 min de lectureMis à jour le 2026-11-06