jsonchunk: LLM 스트리밍 출력을 위한 타입 안전한 초경량 부분 JSON 파서

섹션별 상세

LLM 스트리밍 환경에서 발생하는 불완전한 JSON 구조 문제를 해결한다. 기존 JSON.parse는 중괄호가 닫히지 않거나 키-값 쌍이 완성되지 않으면 예외를 던지지만, jsonchunk는 현재까지 도착한 데이터만으로 유효한 객체를 구성하여 반환한다.

다양한 데이터 유형의 부분적 상태를 지능적으로 처리한다. 따옴표가 닫히지 않은 문자열, 값이 없는 키, 완성되지 않은 배열, 소수점이나 지수 표기법 도중의 숫자 등을 감지하여 안전하게 처리하며, true/false/null 같은 키워드도 첫 글자만으로 미리 예측하여 파싱 결과에 반영한다.

javascript

import { parseStream } from 'jsonchunk';

type User = { name: string; age: number; hobbies: string[] };
const response = await fetch('/api/user', { /* streaming */ });
const stream = response.body!.pipeThrough(new TextDecoderStream());

for await (const partial of parseStream(stream)) {
  console.log(partial.name); // 토큰이 도착함에 따라 실시간 업데이트
  console.log(partial.hobbies); // 배열 내용이 점진적으로 추가됨
}

ReadableStream을 통해 들어오는 LLM 응답을 실시간으로 파싱하여 부분 객체를 반환하는 예시

javascript

import { createParser } from 'jsonchunk';

const parser = createParser();
parser.push('{"name": "Ali');
console.log(parser.value); // { name: "Ali" }

parser.push('ce", "age": 30}');
console.log(parser.value); // { name: "Alice", age: 30 }

상태를 유지하는 파서를 생성하여 수동으로 데이터 조각을 추가하고 현재까지의 파싱 결과를 확인하는 방식

네 가지 주요 API를 통해 유연한 통합을 지원한다. 단순 문자열 파싱을 위한 parse, 상태를 유지하며 조각을 추가하는 createParser, ReadableStream과 연동되는 parseStream, 그리고 TransformStream 어댑터인 createStream을 제공하여 다양한 런타임 환경에 대응한다.

성능과 경량화를 최우선으로 설계되었다. 외부 의존성이 전혀 없는 Zero-dependency 라이브러리이며 번들 크기는 약 5KB에 불과하다. 매번 전체 문자열을 다시 파싱하는 단순한 구조를 채택했음에도 LLM 페이로드 수준의 데이터 크기에서는 충분히 빠른 성능을 보장한다.

TypeScript 사용자들을 위해 DeepPartial 타입을 제공한다. 파싱 결과물의 모든 필드가 재귀적으로 선택적(optional)임을 명시하여, 개발자가 런타임에 존재하지 않을 수 있는 데이터에 안전하게 접근하도록 강제하고 런타임 에러를 방지한다.

용어 해설

부분 JSON 파싱(Partial JSON Parsing): — 완성되지 않은 불완전한 JSON 문자열에서 유효한 데이터만을 추출하여 객체 형태로 변환하는 기술이다. LLM의 스트리밍 출력처럼 데이터가 실시간으로 생성되는 환경에서 전체 응답이 완료되기 전에 사용자에게 정보를 보여주기 위해 필수적이다.
스트리밍 응답(Streaming Response): — 서버가 전체 데이터를 한꺼번에 보내지 않고 생성되는 대로 조각(chunk) 단위로 클라이언트에 전송하는 방식이다. LLM 서비스에서 텍스트가 한 글자씩 나타나는 효과를 구현할 때 사용되며 응답 대기 시간을 시각적으로 줄여주는 효과가 있다.
재귀적 부분 타입(DeepPartial): — 객체의 모든 계층에 있는 필드들을 선택적(optional)인 상태로 만드는 TypeScript 타입 정의 방식이다. 중첩된 구조를 가진 JSON 데이터가 스트리밍되는 도중 특정 필드가 아직 도착하지 않았더라도 타입 오류 없이 안전하게 접근할 수 있도록 돕는다.

기술

JavaScript
TypeScript
npm
ReadableStream

활용 사례

실시간 LLM 챗봇 UI 업데이트
스트리밍 방식의 구조화된 데이터 추출
진행 상황을 보여주는 AI 에이전트 대시보드

언급된 리소스

GitHubjsonchunk GitHub Repository