Як парсити JSON до повної доставки: потоковий попередній перегляд і інкрементне відновлення
Головне: LLM видають JSON по токенах, а API доставляють великі відповіді чанками, але JSON.parse відмовляється працювати, доки не прийде весь документ. У посібнику розділено три стилі реалізації — повне відновлення, справжній інкремент і частковий розбір — і показано, як маска Allow робить попередній перегляд стабільним, з вимірами конвеєра та кодом, готовим до продакшену.

Контракт
JSON.parse— «я почну, коли прийде весь документ», а контракт потокової обробки — «приходить чанк — обробляю чанк». Конфлікт не у швидкості, а в семантиці повноти: у недописаного документа ще немає коректного результату розбору.
Симптом: три сценарії, які не можуть зачекати весь текст
Перший сценарій — LLM-застосунки. Модель видає JSON по токенах; структурований вивід на 8 КБ може надходити десятки секунд, поки користувач дивиться на порожню панель — хоча перші поля були доступні вже за секунду. Другий сценарій — шлюзи та проксі: upstream штовхає відповідь на десятки мегабайт HTTP-чанками, і проксі, який хоче відфільтрувати поля перед пересиланням, множить свій пік пам'яті, якщо буферизує все через res.json(). Третій сценарій — черги повідомлень та лог-конвеєри: записи NDJSON приходять один за одним, і споживачеві не хочеться накопичувати батчі.
Спільне в усіх одне: дані приходять поступово, а стандартний парсер приймає лише повний документ. JSON.parse кидає Unexpected end of JSON input на першому чанку, кидає ту саму помилку на 65-му і повертає результат лише на самому останньому. Чекати — не єдиний варіант, але спершу треба вирішити, що взагалі означає «розібрати» недописаний документ.
Семантика розбору за префіксами: чи є кожен чанк валідним
Візьмемо масив замовлень на 7847 байт, поріжемо його на чанки по 120 символів, імітуючи потокову доставку (Node v22.13.1, jsonrepair 3.15.0, partial-json 0.1.7), і прогонимо три парсери на кожному префіксі:
| Підхід | Успіхів на 66 префіксах | Сумарний час | Семантика |
|---|---|---|---|
JSON.parse |
1 (лише останній чанк) | 2,1 мс | усе або нічого |
partial-json (Allow.ALL) |
66 (з першого чанка) | 14,3 мс | завжди повертає «що відомо на даний момент» |
jsonrepair з повним перезапуском на кожному префіксі |
66 | 23,8 мс | розбирається після доповнення дужок, але щоразу рахує з нуля |
Важливі два висновки. Перший: збій JSON.parse не несе жодної інформації — позиція помилки завжди в кінці, і невідомо ані скільки бракує, ані чи узгоджена отримана частина. Другий: повний перезапуск відновлення на кожному префіксі працює, але невигідно: середня довжина тексту за виклик зростає лінійно, сумарні витрати зростають як O(n²). 23,8 мс виглядає нешкідливо; на мегабайтах той самий коефіцієнт перетворюється на секунди витраченої CPU.
Зауважте також: «розбирається за префіксами» не означає «дані повні». Останнє число доповненого префікса може бути продовжене наступним чанком, а останній рядок може обрізатися посеред escape-послідовності — це корінь усіх проблем стабільності попереднього перегляду.
Три стилі реалізації та їхнє місце
Потокові бібліотеки поділяються на три «пози», і помилитися в пози дорожче, ніж помилитися в бібліотеці:
| Бібліотека | Позиція | Коли використовувати | Коли уникати |
|---|---|---|---|
jsonrepair (3.15.0) |
повне відновлення + Transform-потік | вхід стане повним документом, потрібен вихід без втрат | потрібен лише перегляд (відновлення видає текст, а не об'єкти даних) |
partial-json (0.1.7) |
частковий розбір, може відкидувати незавершені хвости | UI-перегляд: кожен префікс має давати придатний об'єкт | збереження в БД (у перегляді можуть бути відсутні поля й «плавати» числа) |
jsonmend (0.1.3) |
справжнє інкрементне відновлення, відкритий корпус відповідності | конвеєри, що видають версію на кожен скормлений чанк без повторного скану | завершений документ (прямий повний розбір швидший) |
Вони не конкуренти. Підшлях ./stream у jsonrepair експортує jsonrepairTransform — стандартний Transform-потік: чанки входять зліва, справа виходить полагоджений JSON-текст, і конкатенація гарантовано дорівнює розбору всього тексту за один прохід — обіцянку decode(encode(x)) === x воно тримає. partial-json тримає іншу обіцянку: кожен префікс одразу дає об'єкт ціною відмови від «результат більше не зміниться». jsonmend прив'язує третій шлях до відкритого корпусу відповідності: справжній інкремент, вивірена семантика, спільна регресійна база для незалежних реалізацій.
Маска Allow: які поля наважуються з'явитися в перегляді
Ядро partial-json — не «розібрати вхід, яким би битим він не був», а той, хто викликає, оголошує, яку неповноту він приймає. Маска комбінує біти за типами JSON (STR, NUM, ARR, OBJ, ...); зняття біта прибирає з перегляду незавершені значення цього типу:
import { parse, Allow } from 'partial-json';
parse('{"price": 12', Allow.ALL);
// → { price: 12 } 12 — це «прочитане на даний момент»
parse('{"price": 1234.5', Allow.ALL);
// → { price: 1234.5 } те саме поле, нове значення: перегляд плаває
parse('{"price": 12', Allow.ALL & ~Allow.NUM);
// → {} без біта NUM незавершені числа лишаються прихованими
Це найінженернішо цінна знахідка тесту: числа, які будуть дописані — ціни, лічильники — можуть змінюватися в кожному кадрі, де з'являються, а Allow.ALL & ~Allow.NUM тримає їх у тиші до завершення. З рядками так само: рядок, обрізаний посеред Unicode-escape, безпечно відкидається partial-json 0.1.7 замість вгадування. Стабільність перегляду — не подарунок парсера; той, хто викликає, платить за неї маскою.
У що обходиться потокове відновлення: буфер зворотного погляду і квадратичні копії
Потоковий конвеєр — це не for-цикл навколо повного API. На тій самій вибірці з 66 чанків конвеєр jsonrepairTransform витратив сумарно 6,7 мс, а повне відновлення з перезапуском на кожному префіксі накопичило 23,8 мс — розрив у 3,5 раза живе в реалізації: потоковий шлях оглядається назад лише в необхідному вікні і додає вихід інкрементально, не перекопіюючи попередній текст.
Перенесення ядра потокового jsonrepair на ArkTS у HarmonyOS документує три конкретні витрати: streaming-шлях upstream копить «буфер зворотного погляду», через що малі документи парадоксально чекають flush — автор написав окремий IncrementalRepairer для коротких текстів із переглядом на льоту; регулярний шлях upstream перекопіює весь вивід квадратично, у переносі це усунено OutputBuilder-ом; і пастка граничного символу — після заміни перевірки кінця text[i] === undefined на charAt ''.includes(''), завжди істинне, обманює перевірки належності символів, тому читання за межею спершу блокується перевіркою на порожній рядок. Ці деталі пояснюють, чому потокове відновлення заслуговує власної категорії: його інженерна складність на порядок вища за разове відновлення.
Відому межу теж варто записати: issue #214 jsonrepair повідомляє, що потокове відновлення відхиляє легальний префікс із пропущеною комою перед значенням із ведучим слешем — у потоці «наступний символ ще не прийшов» і «вхід недопустимий» лексично важко розрізнити, і вікно зворотного погляду — ціна, сплачена за цю неоднозначність.
Впровадження: перегляд і збереження йдуть різними шляхами
Зберіть семантику в один конвеєр з єдиним правилом: частковий розбір для перегляду, строгий розбір для збереження.
import { jsonrepairTransform } from 'jsonrepair/stream';
import { parse as partialParse, Allow } from 'partial-json';
// Шлях 1: конвеєр без втрат. Чанки на вході, полагоджений JSON на виході, строга перевірка в кінці
const tr = jsonrepairTransform();
tr.pipe(finalSink); // finalSink робить JSON.parse плюс бізнес-валідацію
chunkStream.pipe(tr);
// Шлях 2: конвеєр перегляду. Кадр на кожен префікс; незавершені числа та рядки приховані маскою
function onChunk(buffer) {
const preview = partialParse(buffer, Allow.ALL & ~Allow.NUM & ~Allow.STR);
render(preview); // малюємо лише стабільні поля
}
У двох шляхів різні контракти, вони не взаємозамінні: кадри перегляду можуть пропускати поля, кадри збереження — ні; кадр збереження має дочекатися кінця потоку і пройти повний JSON.parse плюс бізнес-валідацію, а кадр перегляду ніколи не зберігається. Якщо вхід — вивід LLM, перед збереженням ще треба судити про обрив за причиною зупинки — той процес «спершу stop_reason, потім відновлення» розібрано у Відновлення обрізаного JSON з LLM.
Коли не варто потоково
Три вето-умови; якщо спрацювало будь-яке, просто розберіть усе ціликом: файли малі — нижче приблизно 22 МБ звичайний JSON.parse закінчується менш ніж за секунду, потік лише додає складності коду; разова статистика — для агрегації jq --stream або постиковий NDJSON простіший, див. посібник із файлами JSONL; споживач нижче по ланцюжку не приймає часткові дані — підсумкові суми класичний випадок: проміжне значення перегляду, помножене помилково, — це грошовий баг, і потоковий перегляд коштує тоді не більше за прогрес-бар.
Потоковий розбір розв'язує проблему «не можна чекати», а не «хочеться швидше». На тому самому обсязі тексту повний розбір завжди витрачає менше сумарного CPU, ніж будь-який потоковий варіант; купуються час до першого придатного чанка, сталий рівень пам'яті та можливість обробляти на льоту. Проясніть цей вибір — і підбір бібліотеки перестане хитатися.
FAQ
Чи можна зберегти об'єкт перегляду просто в базу?
Не можна. Перегляд — знімок «що відомо на даний момент»: числа можуть бути дописані наступним чанком, рядки обрізані, поля тимчасово відсутні. Перед збереженням дочекайтеся кінця потоку, прогоніть строгий JSON.parse по повному тексту та пройдіть бізнес-валідацію. Перегляд живе лише в шарі UI.
partial-json чи jsonrepair?
Залежить від того, що потрібно: текст чи об'єкти. Для безвтратного полагодженого тексту, який наступний компонент розбере знову, беріть jsonrepair — його потоковий вивід гарантовано дорівнює розбору повного тексту. Для об'єкта на кожному префіксі під UI-перегляд беріть partial-json і налаштовуйте маску Allow за кожним полем.
Чи знижує потоковий розбір загальний час?
Ні. За сумарним CPU повний розбір завжди швидший; потоковий додатково платить за підтримання стану. Купуються три речі: час до першого придатного чанка, рівень пам'яті, що не зростає з розміром документа, і можливість пересилати, фільтрувати та показувати на льоту.
Елементи масиву приходять по одному, і я хочу обробляти їх по одному
Це інший шлях: streamArray зі stream-json видає {key, value} при закритті кожного елемента і у зв'язці з for await дає природний backpressure — годиться для батч-імпорту «розібрати і вставити», гранулярність інша, ніж документний перегляд із цієї статті.