Как парсить 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 — годится для батч-импорта «разобрать и вставить», гранулярность иная, чем документный предпросмотр из этой статьи.