JSON Toolkit

Как парсить JSON до его полной доставки: потоковый предпросмотр и инкрементальное восстановление

Главное: LLM выдают JSON по токенам, а API доставляют большие ответы чанками, но JSON.parse отказывается работать, пока не придёт весь документ. В руководстве разделены три стиля реализации — полное восстановление, настоящий инкремент и частичный разбор — и показано, как маска Allow делает предпросмотр стабильным, с измерениями конвейера и готовым к продакшену кодом.

Средний~5 мин чтенияОпубликовано 2026-11-16Обновлено 2026-11-16
Схема частичного разбора и инкрементального восстановления по чанкам потокового JSON

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

Источники

Подходящие инструменты

Похожие статьи

Руководство по восстановлению JSON: как спасти сломанный вывод LLM и сохранить доверие

Вывод LLM, завёрнутый в markdown-ограждение, с завершающими запятыми и литералами Python, строгий парсер отвергает целиком — как и конфиги, отредактированные вручную без кавычек. Это руководство проводит настоящую границу между девятью классами ошибок, которые восстановитель исправляет, и четырьмя, которые не исправит никогда, объясняет, почему автомат состояний побеждает регулярные выражения, и даёт цепочку разбора, готовую к продакшену, с jsonrepair и json-repair.

Средний~6 мин чтенияОбновлено 2026-11-08

JSON от LLM обрезался: сначала посмотрите причину остановки, потом говорите о починке

Модель вернула JSON, оборвавшийся на середине значения, а парсер сообщает только номер столбца. Закрыть скобки — и разбор снова проходит, но каждый недостающий кусок теперь спрятан внутри данных. Статья проводит границу между тем, что починка обрезки может честно вернуть, и тем, что надо запрашивать заново: проверка stop_reason, расчёт лимита, порядок полей схемы.

Практика~5 мин чтенияОбновлено 2026-11-14

Практика работы с JSONL-файлами: открытие, конвертация и поиск повреждённых строк

Если весь .jsonl-файл отдать JSON.parse или json.load и получить ошибку — почти всегда виноват не файл, а способ чтения. В статье: стандартные паттерны проверки и построчного чтения, команды взаимного преобразования с JSON-массивом, таблица шести типов битых строк и корректное потребление NDJSON из потокового HTTP-ответа.

Средний~9 мин чтенияОбновлено 2026-11-06