راهنمای جامع ماژول V8 در Node.js (ماژول node:v8)

1. معرفی ماژول V8

ماژول node:v8 APIهایی ارائه می‌دهد که مستقیماً با موتور V8 تعامل دارند. این APIها برای ابزارسازی، پروفایلینگ، تحلیل حافظه و بررسی رفتار داخلی V8 استفاده می‌شوند.

2. دسترسی به ماژول

const v8 = require('node:v8');

3. نسخه و سازگاری Cached Data

3.1 v8.cachedDataVersionTag()

برمی‌گرداند که آیا دادهٔ کش‌شدهٔ vm.Script با نسخهٔ فعلی V8 سازگار است یا نه.

console.log(v8.cachedDataVersionTag());

4. آمارهای Heap و حافظه

4.1 v8.getHeapCodeStatistics()

آمار مربوط به کد و متادیتای موجود در Heap.

4.2 v8.getHeapSpaceStatistics()

آمار فضاهای مختلف Heap مانند new_space، old_space، code_space و ...

4.3 v8.getHeapStatistics()

آمار کامل Heap شامل:

• total_heap_size
• used_heap_size
• heap_size_limit
• malloced_memory
• native_contexts
• detached_contexts
• external_memory

4.4 v8.getCppHeapStatistics()

آمار Heap مربوط به C++ (CppHeap) با دو سطح:

• brief: آمار کلی
• detailed: آمار کامل صفحات، freelist و histogram

5. Heap Snapshot

5.1 v8.getHeapSnapshot()

یک Stream از Snapshot Heap تولید می‌کند (فرمت JSON سازگار با DevTools).

v8.getHeapSnapshot().pipe(process.stdout);

5.2 v8.writeHeapSnapshot()

Snapshot را در فایل ذخیره می‌کند.

const filename = v8.writeHeapSnapshot();

نکات مهم:

• Snapshot دو برابر اندازهٔ Heap حافظه نیاز دارد.
• عملیات کاملاً synchronous و مسدودکننده است.
• Snapshot فقط مربوط به یک Isolate است (Workerها جدا هستند).

6. مدیریت Coverage

6.1 v8.takeCoverage()

نوشتن گزارش پوشش کد در مسیر NODE_V8_COVERAGE.

6.2 v8.stopCoverage()

توقف جمع‌آوری پوشش کد.

7. تنظیم فلگ‌های V8

7.1 v8.setFlagsFromString()

تنظیم فلگ‌های V8 به‌صورت برنامه‌نویسی.

v8.setFlagsFromString('--trace_gc');

8. جستجوی اشیا در Heap

8.1 v8.queryObjects()

جستجوی اشیایی که سازندهٔ مشخصی در Prototype Chain دارند.

class A {}
console.log(v8.queryObjects(A)); // تعداد اشیا

9. API سریال‌سازی

9.1 v8.serialize()

سریال‌سازی سازگار با Structured Clone.

const buf = v8.serialize({ a: 1 });

9.2 v8.deserialize()

بازگردانی دادهٔ سریال‌شده.

const obj = v8.deserialize(buf);

9.3 کلاس Serializer / Deserializer

برای کنترل کامل فرایند سریال‌سازی.

10. Promise Hooks

ردیابی چرخهٔ عمر Promiseها:

• init
• before
• after
• settled

const { promiseHooks } = require('node:v8');
promiseHooks.onInit((promise, parent) => {});

11. کاربردهای مهم ماژول V8

• تحلیل Memory Leak
• پروفایلینگ Heap و CppHeap
• ساخت ابزارهای DevTools
• جمع‌آوری Coverage در CI/CD
• سریال‌سازی داده‌ها برای ذخیره‌سازی یا انتقال
• ردیابی رفتار Promiseها

نتیجه‌گیری

ماژول node:v8 یکی از قدرتمندترین ابزارهای سطح پایین برای تحلیل عملکرد، حافظه و رفتار داخلی موتور V8 است. این ماژول برای توسعه‌دهندگان حرفه‌ای، ابزارسازها، متخصصان Performance و کسانی که نیاز به کنترل دقیق رفتار Node.js دارند، ضروری است. با استفادهٔ درست از این APIها می‌توان Memory Leakها را شناسایی کرد، Snapshotهای دقیق گرفت، پوشش کد را مدیریت کرد و حتی داده‌ها را با فرمت Structured Clone سریال‌سازی کرد.