‏stream-json: پردازش فایل‌های JSON خیلی بزرگ با حافظهٔ کم

stream-json یه میکروکتابخونه برای پردازش فایل‌ها و استریم‌های JSON با کمترین مصرف حافظه‌ست. سازنده‌ش می‌گه می‌شه یه فایل خیلی بزرگ‌تر از RAM بهش داد و اون بدون مشکل از روش رد می‌شه. فقط بخش‌هایی که برات مهمه رو جدا می‌کنی و یکی‌یکی پردازششون می‌کنی، به جای اینکه کل فایل رو با JSON.parse لود کنی. حتی کلیدها، رشته‌ها و عددها هم می‌تونن تیکه‌تیکه استریم بشن.

هر جزء این کتابخونه یه مرحله از یه pipeline هست. parser متن رو به یه استریم از tokenها تبدیل می‌کنه (یعنی تیکه‌های ریز مثل «شروع آبجکت» یا «یه کلید»). بعد فیلترهایی مثل pick، ignore، replace و filter همون لحظه استریم رو کوچیک و مرتب می‌کنن و streamerها tokenهای باقی‌مونده رو دوباره به آبجکت جاوااسکریپت تبدیل می‌کنن. نکتهٔ مهم اینه که بایت‌هایی که رد می‌شن اصلاً تو حافظه ساخته نمی‌شن.

این مثال از خود مقاله، آرایهٔ data رو از یه فایل خیلی بزرگ بیرون می‌کشه و رکوردها رو یکی‌یکی می‌ده:

const pipeline = chain([
  fs.createReadStream('data.json'),
  parser(),
  pick({filter: 'data'}),
  streamArray()
]);

اتصال این مرحله‌ها به هم با کتابخونهٔ stream-chain انجام می‌شه که هیچ وابستگی‌ای نداره و backpressure (یعنی کند کردن خوندن وقتی مصرف‌کننده عقب افتاده) رو هم مدیریت می‌کنه. اگه pick چند تا زیرآبجکت رو پیدا کنه، با streamValues() می‌شه هر کدوم رو جدا به آبجکت تبدیل کرد. برای خوندن مستقیم از فایل هم parseFile() هست که فقط روی Node کار می‌کنه.

کتابخونه فقط ESM هست، تایپ‌های TypeScript داخلش هست و روی Node، Bun، Deno و مرورگر تست شده. پارسر JSON، JSONL و JSONC (یعنی JSON با کامنت) داره. نویسنده صریح می‌گه این ابزار برای داده‌ای ساخته شده که مال خودته یا بهش اعتماد داری، مثل dump دیتابیس و لاگ. برای JSON از اینترنت یا کاربر ناشناس طراحی نشده و اون داده اول باید جدا اعتبارسنجی بشه.

تو نسخه‌های اخیر، 3.7.0 گزینهٔ maxDepth رو به قوانین FlexAssembler اضافه کرد و فیلترهای رشته‌ای و RegExp رو خیلی سریع‌تر کرد. نسخهٔ 3.6.0 دو تا مشکل امنیتی رو درست کرد: یکی اینکه کلید proto دیگه prototype آبجکت ساخته‌شده رو عوض نمی‌کنه. نسخهٔ 3.0.0 هم کتابخونه رو به ESM و stream-chain 4.x برد.

نکات کلیدی:

• stream-json فایل JSON بزرگ‌تر از RAM رو با حافظهٔ ثابت پردازش می‌کنه.
• فیلترهای pick، ignore، replace و filter بخش‌های اضافه رو قبل از ساخته شدن تو حافظه دور می‌ریزن.
• فقط ESM، با تایپ‌های TypeScript، روی Node و Bun و Deno و مرورگر.
• از JSON، JSONL و JSONC پشتیبانی می‌کنه.
• برای ورودی غیرقابل اعتماد طراحی نشده.
• نسخهٔ 3.6.0 مشکل امنیتی مربوط به کلید proto رو درست کرد.