פענוח JSON שעוד לא הגיע במלואו: תצוגה מקדימה בסטרימינג ותיקון מצטבר
שורה תחתונה: מודלי LLM משחררים JSON טוקן אחר טוקן ו-API מחזירות תשובות גדולות במקטעים, אבל JSON.parse מסרב להתחיל לעבוד עד שהמסמך המלא מגיע. המאמר מפריד שלושה סגנונות מימוש — תיקון מלא, מצטבר אמיתי ופענוח חלקי — ומסביר כיצד מסכת Allow שומרת על תצוגה מקדימה יציבה, עם מדידות צינור וקוד מוכן לפרודקשן.

החוזה של
JSON.parseהוא «לא מתחיל עד שהמסמך המלא מגיע», והחוזה של הסטרימינג הוא «מוסר נתונים חתיכה אחר חתיכה» — הסתירה ביניהם איננה במהירות אלא בסמנטיקה של השלמות: למסמך שלא נכתב עד סופו עדיין אין «תוצאת פענוח נכונה» שניתן לבחון.
התסמין: שלושה תרחישים שאינם יכולים לחכות לטקסט המלא
התרחיש הראשון הוא יישומי LLM. המודל משחרר JSON טוקן אחר טוקן; פלט מובנה בגודל 8KB עשוי להימשך עשרות שניות עד להשלמתו בזמן שהמשתמש מביט בחלונית ריקה — למרות שהשדות הראשונים היו זמינים לתצוגה כבר בשנייה הראשונה. התרחיש השני הוא שערים ופרוקסים: ה-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 ms | הכול או כלום |
partial-json (Allow.ALL) |
66 (מהחתיכה הראשונה) | 14.3 ms | תמיד מחזיר «הידוע עד כה» |
jsonrepair עם הרצת תיקון מלא מחדש לכל קידומת |
66 | 23.8 ms | ניתן לפענוח לאחר השלמת סוגריים, אך מחושב מחדש מההתחלה בכל פעם |
שתי מסקנות קריטיות. הראשונה: כישלון JSON.parse אינו נושא עמו שום מידע — המיקום המדווח תמיד בסוף, ואינך יודע כמה עוד חסר ואף אם החלק שהתקבל עקבי עם עצמו. השנייה: הרצת תיקון מלא מחדש בכל קידומת אפשרית אך לא משתלמת: אורך הטקסט הממוצע לקריאה צומח ליניארית והעלות המצטברת צומחת ריבועית, O(n²). 23.8 ms נראה תמים; כשהטקסט מגיע לסדר גודל של מגהבייטים, אותו מכפיל הופך לשניות CPU מבוזבזות.
ושימו לב גם לזה: «ניתן לפענוח לפי קידומות» איננו «נתונים שלמים». המספר האחרון בקידומת שהושלמו סוגרייה עשוי להימשך על ידי החתיכה הבאה, והמחרוזת האחרונה עשויה להיחתך באמצע רצף escape — שם נמצאת השורש של כל אי-היציבות בתצוגה המקדימה בסטרימינג.
שלושה סגנונות מימוש וחלוקת התפקידים ביניהם
ספריות בצד הסטרימינג מתחלקות לשלוש עמדות, ובחירה שגויה בעמדה מזיקה יותר מבחירה שגויה בספרייה:
| ספרייה | עמדה | מתאים | לא מתאים |
|---|---|---|---|
jsonrepair (3.15.0) |
תיקון מלא + Transform stream | קיבלת «מסמך שיושלם בסוף» ורוצה תוצאה ללא אובדן | רק תצוגה מקדימה (הפלט הוא כל הטקסט המתוקן, לא אובייקט נתונים) |
partial-json (0.1.7) |
פענוח חלקי, מתיר להשליך זנב שלא הושלם | תצוגה מקדימה ב-UI: לכל קידומת יש מיד אובייקט שמיש | כתיבה לבסיס נתונים (בתצוגה עלולים להיעדר שדות, מספרים אינם יציבים) |
jsonmend (0.1.3) |
מצטבר אמיתי, קורפוס עקביות ציבורי | צינור בסגנון «נכנס חתיכה — יוצאת גרסה» בלי לסרוק שוב את העבר | מסמך שהסתיים (פענוח מלא מהיר יותר) |
השלושה אינם מתחרים. jsonrepair מייצא את jsonrepairTransform דרך תתי-נתיב ./stream, Transform stream תקני: חתיכות נכנסות משמאל, מימין יוצאות בלוקים של טקסט 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, המספר שלא הושלם לא יוצג
זו התובנה בעלת הערך ההנדסי הגבוה ביותר מהמדידה: מספרים כמו מחיר ומונה שעשויים להימשך על ידי החתיכה הבאה משתנים ב-UI עם כל פריים; ואילו Allow.ALL & ~Allow.NUM מורה להם לחכות בשקט עד שייכתבו במלואם ורק אז להופיע. מחרוזות באותה מידה — מחרוזת שנחתכה באמצע רצף escape יוניקוד, partial-json 0.1.7 משליך אותה בבטחה במקום לנחש. יציבות התצוגה אינה מתנה מהפרסר; הקורא קונה אותה במסכה.
עלות המימוש של תיקון בסטרימינג: מאגר מבט-לאחור והעתקה ריבועית
צינור סטרימינג איננו לעטוף את ה-API המלא בלולאת for. על אותו דגימה של 66 חתיכות, צינור עם jsonrepairTransform לקח סה"כ 6.7ms, בעוד שהרצת תיקון מלא מחדש לכל קידומת הצטברה ל-23.8ms — פער של 3.5 מגיע משכבת המימוש: מימוש הסטרימינג מביט לאחור רק בחלון הנחוץ, פלט נוסף באמצעות מאגר מצטבר, ואינו מעתיק שוב ושוב את הטקסט הקודם.
העברת ליבת הסטרימינג של jsonrepair ל-HarmonyOS ArkTS (ניסיון התאמת ספריות צד שלישי ב-openHarmony) חשפה שלוש עלויות ספציפיות: נתיב ה-streaming במעלה הזרם צריך לצבור «מאגר מבט-לאחור», ולכן במסמכים קטנים התוצאה ממתינה עד flush — הכותב כתב לכן IncrementalRepairer נפרד לטקסטים קצרים; נתיב ה-regular במעלה הזרם מעתיק את הפלט במלואו שוב ושוב, מה שריבועי בטבעו, ובזמן ההעברה OutputBuilder הסיר זאת; ועוד נותרה מלכודת תו גבול — תנאי text[i] === undefined כבדיקה «הגעתי לסוף» כשהוא מועבר ל-charAt יכול להטעות, מכיוון ש-''.includes('') תמיד true, ולכן חריגת גבול חייבת קודם להיחסם במחרוזת ריקה. הפרטים האלה מסבירים מדוע «תיקון בסטרימינג» ראוי למקום קטגוריה משלו: מורכבותו ההנדסית והתיקון החד-פעמי אינם באותה מדרגה.
שווה לרשום גם את הגבול המוכר: issue #214 ב-jsonrepair מדווח שתיקון הסטרימינג דוחה קידומת תקפה שחסרה בה פסיק לפני ערך עם קידומת slash — במצב סטרימינג קשה להבחין לקסיקלית בין «התו הבא עוד לא הגיע» לבין «הקלט אינו תקין»; חלון המבט-לאחור הוא המחיר שמשלמים עבור אי-הוודאות הזו.
איך להעביר לפועל: תצוגה מקדימה ואחסון הולכים בנתיבים נפרדים
שזרו את הסמנטיקה שלמעלה לצינור אחד; העיקרון נכנס במשפט אחד: תצוגה מקדימה בפענוח חלקי, אחסון בפענוח מחמיר.
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: צינור תצוגה מקדימה. כל קידומת נותנת פריים UI; מספרים ומחרוזות שלא הושלמו נעצרים במסכה
function onChunk(buffer) {
const preview = partialParse(buffer, Allow.ALL & ~Allow.NUM & ~Allow.STR);
render(preview); // צייר רק שדות יציבים; שדות משתנים במהירות ימתינו
}
החוזה של שני הנתיבים שונה ואינם מחליפים זה את זה: פריים תצוגה מקדימה רשאי להיעדר שדות, פריים אחסון לא; פריים אחסון חייב לחכות לסיום הסטרים ולעבור JSON.parse מלא עם בדיקה עסקית, בעוד פריים תצוגה מקדימה לעולם אינו נשמר בשום מקום. אם המעלה הוא פלט LLM, לפני אחסון צריך להעריך על פי stop_reason אם נחתך — הזרימה «הבט ב-stop_reason קודם ורק אז דבר על תיקון» מפורטת במאמר תיקון JSON חתוך מ-LLM, לא חוזר כאן.
מתי לא לעשות סטרימינג
שלושה תנאי וטו; מספיק שאחד מתקיים והשתמשו כנה בפענוח מלא: קובץ קטן — JSON.parse רגיל קורא עד ~22MB בפעם אחת בדרך כלל בפחות משנייה, סטרימינג רק מוסיף קוד; סטטיסטיקה חד-פעמית בלבד — אגרגציה קלה יותר עם jq --stream או NDJSON שורה-שורה, ראו המדריך המעשי ל-JSONL; הצרכן במורד הזרם אינו מקבל נתונים חלקיים — למשל סכום כסף, ערך ביניים אחד שהוכפל שגוי מהתצוגה הוא הפסד אמיתי; אז לתצוגה המקדימה בסטרימינג נותר ערך של «מד התקדמות» בלבד.
מה שפענוח בסטרימינג פותר תמיד הוא «אין אפשרות לחכות», לא «מהיר יותר». באותו נפח טקסט, זמן ה-CPU הכולל של פענוח מלא תמיד קטן מכל אפשרות סטרימינג; אתם מחליפים זמן עד לבייט הראשון שניתן לשימוש ומפלס זיכרון קבוע. הבינו את העסקה הזו בבהירות, ובחירת הטכנולוגיה לא תתנדנד.
שאלות נפוצות
אפשר לשמור אובייקט תצוגה מקדימה ישירות בבסיס נתונים?
לא. תצוגה מקדימה היא תמונה של «הידוע עד כה»: מספר עשוי להימשך על ידי החתיכה הבאה, מחרוזת עשויה להיחתך, שדות עשויים להיעדר זמנית. לפני אחסון צריך לחכות לסיום הסטרים, להריץ סבב אחד של JSON.parse מחמיר על הטקסט המלא ואז לעבור בדיקה עסקית. תצוגה מקדימה שייכת רק לשכבת ה-UI.
partial-json או jsonrepair?
תלוי מה אתם רוצים: טקסט או אובייקט. טקסט מתוקן ללא אובדן (להעביר לפענוח במורד) — jsonrepair; הפלט המסטרימינג שלו מבטיח התאמה לפענוח המלא. אובייקט לכל קידומת להצגה מיידית ב-UI — partial-json, עם מסכת Allow מכוונת לפי רמת אי-היציבות שאתם מוכנים לשאת.
האם פענוח בסטרימינג מקצר את הזמן הכולל?
לא. זמן ה-CPU הכולל של פענוח מלא תמיד הקטן ביותר, ואפשרות הסטרימינג עוד משלמת עלות תחזוקת מצב. הסטרימינג מחליף שלושה דברים: זמן עד החתיכה הראשונה ששימושית, זיכרון שאינו צומח עם אורך המלוא, והיכולת לעבד תוך כדי קבלה (העברה, סינון, תצוגה).
איברי המערך מגיעים אחד-אחד ואני רוצה לעבד אחד-אחד — מה לעשות?
זה נתיב אחר: stream-json עם streamArray זורק {key, value} ברגע שהאיבר נסגר, ועם for await נוצר לחץ-חזרה טבעי — מתאים לייבוא בכמות גדולה בסגנון «פענח וכתוב»; המאמר הזה מדבר על תצוגה מקדימה בקנה מידה של מסמך שלם.