핵심 요약
LLM은 토큰 단위로 응답을 생성하므로 JSON 구조가 완성되기 전까지는 일반적인 JSON.parse를 사용할 수 없다. jsonchunk는 스트리밍 중인 불완전한 JSON 문자열에서 유효한 정보를 최대한 추출하여 실시간으로 UI를 업데이트할 수 있게 돕는다. 이 라이브러리는 의존성이 없고 5KB 미만의 가벼운 크기로 설계되었으며 TypeScript의 DeepPartial을 통해 타입 안전성을 제공한다. 결과적으로 개발자는 정규표현식이나 복잡한 복구 로직 없이도 매끄러운 스트리밍 사용자 경험을 구현할 수 있다.
배경
JavaScript/TypeScript, LLM Streaming API (OpenAI/Claude 등), Web Streams API 이해
대상 독자
LLM 기반 웹 애플리케이션을 개발하는 프론트엔드 및 풀스택 개발자
의미 / 영향
LLM 응답 속도가 사용자 경험의 핵심인 상황에서 이 도구는 대기 시간을 획기적으로 줄여주는 표준적인 유틸리티가 될 수 있다. 특히 복잡한 구조의 JSON을 생성하는 에이전트나 대시보드 서비스에서 실시간성을 확보하는 데 기여할 것으로 보인다.
섹션별 상세
LLM의 스트리밍 응답은 토큰별로 전달되므로 전체 응답이 올 때까지 기다려야 하는 기존 방식은 사용자 경험을 저해한다. jsonchunk는 '{"name": "Ali'와 같이 끊긴 문자열에서도 { name: "Ali" }라는 유효한 객체를 추출해낸다. 이를 통해 개발자는 응답이 완료되기 전에도 화면에 데이터를 즉시 렌더링할 수 있다.
라이브러리는 다양한 환경에 맞춘 API를 제공한다. 단순 문자열 파싱을 위한 parse, 상태를 유지하며 청크를 추가하는 createParser, 그리고 ReadableStream과 직접 연동되는 parseStream 등이 포함된다. 특히 createStream은 TransformStream 어댑터 역할을 하여 파이프라인 구성을 용이하게 한다.
불완전한 문자열, 객체, 배열뿐만 아니라 숫자(3. → 3)나 키워드(tru → true) 등 까다로운 중간 상태를 모두 처리한다. 이스케이프 문자(\n, \uXXXX)가 청크 경계에서 잘리는 경우도 올바르게 처리하도록 설계되었다. 키가 없는 값이나 값이 없는 키는 무시하며 현재 시점에서 구축 가능한 가장 큰 유효 객체를 반환한다.
외부 의존성이 전혀 없으며 번들 크기가 약 5KB에 불과해 프론트엔드 환경에 적합하다. 매 청크마다 전체 문자열을 다시 파싱하는 방식을 채택하여 구현의 단순함과 정확성을 확보했다. 스키마 검증 기능은 포함하지 않으므로 최종 결과물에 대한 검증이 필요한 경우 Zod와 같은 라이브러리와 병행 사용을 권장한다.
실무 Takeaway
- LLM 스트리밍 UI 구현 시 JSON.parse 에러 처리를 위한 복잡한 정규표현식 로직을 대체할 수 있다.
- TypeScript의 DeepPartial 타입을 활용하여 스트리밍 중인 데이터의 불확실성을 코드 레벨에서 안전하게 관리할 수 있다.
- parseStream API를 사용하면 fetch 응답의 body를 직접 연결하여 실시간 데이터 흐름을 간결하게 처리할 수 있다.
언급된 리소스
AI 분석 전체 내용 보기
AI 요약 · 북마크 · 개인 피드 설정 — 무료