Node.js/vm

VM (تنفيذ JavaScript)

مؤشر الاستقرار: 2 - مستقر.

توفر الوحدة vm واجهات تطبيقات لترجمة وتشغيل الشيفرات البرمجية ضمن سياقات آلآت V8 الافتراضية.

ويمكن ترجمة شيفرة JavaScript البرمجية وتشغيلها فورًا أو تجميعها وحفظها وتشغيلها لاحقًا.

من الاستخدامات الشائعة، تشغيل التعليمات البرمجية في بيئة تجريبية معزولة (sandbox environment). وتُستخدم شيفرة sandbox سياق V8 مختلف، مما يعني انه يحتوي علي كائن عام مختلف عن باقي الشيفرة البرمجية.

ويمكن توفير السياق عن طريق وضع كائن sandbox المعزول في السياق. وتعامل الشيفرةُ المعزولة أي خاصية في بيئة sandbox على أنها متغير عام. وتنعكس أية تغييرات علي المتغيرات العامة الحادثة بسبب الشيفرة المعزولة على كائن sandbox.

const vm = require('vm');

const x = 1;

const sandbox = { x: 2 };
vm.createContext(sandbox); // وضع الـ sandbox في السياق.

const code = 'x += 40; var y = 17;';
// x و y متغيرات عامة في بيئة معزولة.
// في البداية، تحتوي x على القيمة 2 لأن هذه هي قيمة sandbox.x.
vm.runInContext(code, sandbox);

console.log(sandbox.x); // 42
console.log(sandbox.y); // 17

console.log(x); // 1; y غير مُعرَّف.

ولا تُعد الوحدة vm آلية أمان. ولا يجب استخدامها لتشغيل شيفرة برمجية غير موثوق بها.

الصنف: vm.SourceTextModule

أضيفت مع الإصدار: v9.6.0.

مؤشر الاستقرار: 1 - تجريبي.

تتوفر هذه الميزة فقط عند تفعيل راية الأمر ‎--experimental-vm-modules.

ويوفر الصنف vm.SourceTextModule واجهة منخفضة المستوى لاستخدام وحدات ECMAScript في سياقات VM. وهو نظير للصنف vm.Script الذي يعكس سجلات وحدة نَّص المصدر (Source Text Module Records) كما هو محدد في مواصفات ECMAScript.

ومع ذلك، علي عكس vm.Script يرتبط كل كائن vm.SourceTextModule إلى سياق من إنشائه. وتكون العمليات على كائنات vm.SourceTextModule في جوهرها غير متزامنة، في تناقض مع الطبيعة المتزامنة لكائنات vm.Script بيد أن التلاعب بكائنات vm.SourceTextModule يكون واضحا إلى حد ما بمساعدة الدوال المتزامنة.

يتطلب استخدام كائن vm.SourceTextModule أربع خطوات: إنشاء/تحليل, ربط، عمل مثيل، والتقييم. هذه الخطوات الأربع موضحة في المثال التالي.

يكمن هذا التنفيذ في مستوى أقل من مُحمِـل وحدة ECMAScript. كما لا يوجد حاليا أي وسيلة للتفاعل مع المُحمِّـل، على الرغم من التخطيط لدعمه.

const vm = require('vm');

const contextifiedSandbox = vm.createContext({ secret: 42 });

(async () => {
// الخطوة 1

//

// إنشاء وحدة عن طريق بناء كائن `vm.SourceTextModule` جديد.

// يحلل هذا نص المصدر المعطى ويطلق `SyntaxError` إذا حدث أي خطأ.

// بشكل افتراضي، تُنشأ وحدة في أعلى السياق. ولكن هنا،

// نُحدد `contextifiedSandbox` كسياق تنتمي له هذه الوحدة.

//

// هنا نحاول الحصول على التصدير الافتراضي من وحدة "foo"،

// ووضعه في "secret" الربط المحلية.

 const bar = new vm.SourceTextModule(`
    import s from 'foo';
    s;

// الخطوة 2

//

// "ربط" التبعيات المستوردة لهذه الوحدة بها.

//

// تقبل دالةُ رد الاتصال المُعطاة ("الرابطة") وسيطين:

// الوحدة الأصل ('bar' في هذه الحالة) والسلسلة التي تحدد

// الوحدة المستوردة. ومن المتوقع أن تعيد دالة رد الاتصال الوحدة التي

// تتوافق مع المحدد المعطى، مع بعض المتطلبات الموثقة

// في `module.link()‎`.

//

// إذا لم يبدأ الربط للوحدة المُعادة، ستُستدعى نفس دالة رد الاتصال الرابطة

// على الوحدة المُعادة.

//

// ويجب ربط حتى الوحدات ذات المستوي الأعلى الخالية من التبعيات بشكل صريح. 
// وعلى الرغم من ذلك، لن تستدعى دالة رد الاتصال المعطاة.

//

ويعيد التابع link()‎ الوعد (Promise) والذي سيُحل عندما

تُحل جميع الوعود Promises المُعادة بواسطة الرابط.

//

// ملاحظة: هذا المثال مُعَد كمثال على أن دالة الرابط تُنشئ

// وحدة "foo" جديدة في كل مرة تستدعى فيها. في نظام وحدة متكامل،

// قد تستخدم ذاكرة التخزين المؤقت على الأرجح لتجنب تكرار الوحدات.

  async function linker(specifier, referencingModule) {
    if (specifier === 'foo') {
      return new vm.SourceTextModule(`
// يشير المتغير "secret" إلى المتغير العام الذي أضفناه إلى

// "contextifiedSandbox" عند إنشاء السياق.

        export default secret;
      `, { context: referencingModule.context });


// استخدام `contextifiedSandbox` بدلا من `referencingModule.context`

// هنا سوف يعمل أيضًا.
 }
    throw new Error(`Unable to resolve dependency: ${specifier}`);
  }
  await bar.link(linker);


// الخطوة 3

//

// إنشاء مثيل الوحدة في المستوي الأعلى.

//

// فقط الوحدة في المستوي الأعلى تحتاج إلى إنشاء مثيل بشكل صريح؛

// وستُنشأ مثيلات لتبعياتها بشكل متكرر من قِبَل instantiate()‎.

  bar.instantiate();

// الخطوة 4

//

// تقييم الوحدة. يُعيد التابع evaluate()‎ وعد Promise مع

// خاصية "result" منفردة والتي تحتوي علي نتيجة آخر عبارة

// نُفِذَّت في الوحدة. في حالة `bar`، يكون حرف `s` هو الذي يشير إلى

// التصدير الافتراضي للوحدة 'foo'، و 'secret' الذي ضُبِط

// في بداية بالقيمة 42.

 const { result } = await bar.evaluate();

  console.log(result);
  // طباعة 42.
})();

المُنشئ: new vm.SourceTextModule(code[, options])‎

• code من النوع <string> وهو شيفرة وحدة JavaScript المراد تحليلها
• options
  • url من النوع <string> وهو URL المستخدم في حل الوحدة وتتبعات المكدس. القيمة الافتراضية: 'vm:module(i)' حيث i مؤشر تصاعدي خاص بالسياق.
  • context من النوع <Object> وهو الكائن الموضوع في السياق كما أُعيد من قبل التابع vm.createContext()‎، لترجمته وتقييمه داخل Module.
  • lineoffset من النوع <integer> وهو يحدد إزاحة رقم السطر المعروض في تتبعات المكدس التي تنتجها الوحدة Module.
  • columnoffset من النوع <integer> وهو يحدد إزاحة رقم العمود المعروض في تتبعات المكدس التي تنتجها الوحدة Module
  • initalizeImportMeta من النوع <Function> تًستدعى خلال تقييم هذه الوحدة Module لإعادة تهيئة import.meta. لدى هذه الدالة التوقيع  (meta, module) مع كون meta كائن import.meta في Module، و module كائن vm.SourceTextModule.

إنشاء كائن ES Module جديد.

قد تسمح الخصائص المعينة لكائن import.meta التي هي كائنات للوحدة Module للوصول إلى المعلومات خارج context المحدد، إذا أنشئ الكائن في سياق المستوي الأعلى. استخدام vm.runincontext()‎‎ لإنشاء كائنات في سياق معين.

// ملاحظة: أنشئ هذا الكائن في السياق الأعلى. وعلى هذا النحو،

// يشير الكائن Object.getPrototypeOf(import.meta.prop) إلى

// Object.prototype في أعلى السياق بدلا من ذلك الذي في

// الـ sandbox.

// وبما أن ليس للوحدة تبعيات، فلن تُستدعى دالة الرابط أبدًا.

// يساوي Object.prototype.secret الآن 42.

//

// لإصلاح هذه المشكلة، يستبدل

// meta.prop = {};

// أعلاه مع،

// meta.prop = vm.runInContext('{}', contextifiedSandbox);

module.dependencySpecifiers

• من النوع <string[]>

محددات كافة تبعيات هذه الوحدة. تُجمَّد المصفوفة المُعادة لمنع حدوث أي تغييرات عليه.

يتوافق مع الحقل [[RequestedModules]] في سجلات وحدة نص المصدر في مواصفات ECMAScript.

module.error

• من أي نوع من الأنواع <any>.

إذا كانت الحالة module.status بالقيمة 'errored'، تحتوي هذه الخاصية علي الاستثناء الذي أُجريَ بواسطة الوحدة أثناء التقييم. إذا كانت الحالة أي شيء آخر، سيؤدي الوصول إلى هذه الخاصية إلى إجراء استثناء.

لا يمكن استخدام القيمة undefined للحالات حيث لا يوجد إجراء استثناء بسبب الغموض المحتمل حولthrow undefined;.

يتوافق مع الحقل [[EvaluationError]] في سجلات وحدة نص المصدر في مواصفات ECMAScript.

وحدة نمطية.تقييم([خيارات])

• options من النوع  <Object>.
  • timeout من النوع <number> وهو يحدد عدد المللي ثانية اللازمة للتقييم قبل إنهاء التنفيذ. إذا تمت مقاطعة التنفيذ، سينطلق Error.
  • breakOnSigint من النوع <boolean>، إذا كان true، سينتهي التنفيذ عند تلقي SIGINT (أو Ctrl + C). ستُعَّطل المعالجات الموجودة للحدث الذي أُرفِق بواسطة process.on('SIGINT') أثناء تنفيذ السكريبت، ولكنها سوف تستمر في العمل بعد ذلك. إذا تمت مقاطعة التنفيذ، سينطلق Error.
• القيمة المُعادة: من النوع <Promise>.

تقييم الوحدة.

يجب استدعاءه بعد إنشاء مثيل الوحدة؛ وإلا فانه سيُطلق خطأ. ويمكن استدعاؤه أيضًا عند تقييم الوحدة بالفعل، وفي هذه الحالة سيقوم بأحد الأمرين التاليين:

• إعادة undefined إذا انتهى التقييم الأولي بنجاح (module.status تكون 'evaluated').
• أعادة إجراء الاستثناء نفسه الذي أجراه التقييم الأولي إذا أُنهيَ التقييم الأولي في خطأ (module.status تكون 'errored').

لا يمكن استدعاء هذا التابع أثناء تقييم الوحدة (module.status تكون 'evaluating') لمنع لانهائية العودية.

يتوافق مع حقل التابع Evaluate()‎ المتماسك من سجلات وحدة نص المصدر في مواصفات ECMAScript.

module.instantiate()‎

إنشاء مثيل للوحدة. يجب استدعاءه بعد إنهاء الربط (linkingStatus تكون 'linked').؛ وإلا فانه سيُطلق خطأ. كما يجوز إجراء استثناء إذا لم يوفر أحد التبعيات التصدير الذي تتطلبه الوحدة الأصل.

ومع ذلك، إذا نجحت هذه الدالة، ستكون الاستدعاءات اللاحقة لهذه الدالة بعد الإنشاء الأولي لمثيل هو no-ops، لتكون متناسقة مع مواصفات ECMAScript.

علي عكس التوابع الأخرى التي تعمل علي Module، تكمل هذه الدالة بشكل متزامن ولا تقوم بإعادة أي شيء.

يتوافق مع حقل التابع Instantiate()‎ المتماسك من سجلات وحدة نص المصدر في مواصفات ECMAScript.

module.link (linker)

• linker من النوع <Function>.
• القيمة المُعادة: من النوع <Promise>.

ربط تبعيات الوحدة. يجب استدعاء هذا التابع قبل إنشاء مثيل، ويمكن استدعاؤه مره واحدهة فقط لكل وحدة.

سيمرر معاملين إلى الدالة linker:

• specifier وهو محدد الوحدة المطلوبة:

// ^^^^^ محدد الوحدة

• referencingModule وهو كائن Module الذي يستدعى عليه التابع link()‎.

والمتوقع من الدالةإعادة كائن Module أو Promise والذي يحل إلى كائن Module في نهاية المطاف. يجب أن يلبي الكائن Module المُعاد الثابتين التالييَن:

• ويجب أن ينتمي إلى نفس سياق كائن Module الأصل.
• ولا يجب أن تصبح linkingStatus الخاصة بها 'errored'.

إذا كانت linkingStatus المُعادة والخاصة بالكائن Module هي 'unlinked'، سيستدعى هذا التابع بشكل متكرر علي Module المُعاد مع نفس الدالة linker المُعطاة.

يعيد link()‎ الوعد Promise والذي سيُحل عندما تحل كافة مثيلات الربط إلى Module صالح، أو يرفض إذا أجرت دالة الربط استثناءً أو أعادت Module غير صالح.

تتوافق دالة الربط بشكل تقريبي مع عملية HostResolveImportedModule المجردة والمعرفة من قِبَل التطبيق في مواصفة ECMAScript مع بعض الاختلافات الرئيسية:

• يُسمح لدالة رابط أن تكون غير متزامنة في حين أن HostResolveImportedModule متزامن.
• تُنفَّذ دالة الربط أثناء الربط، وهي أحد مراحل Node.js hgohwm قبل إنشاء المثيل، في حين يُستدعى HostResolveImportedModule خلال إنشاء المثيل.

يُعيد تطبيق HostResolveImportedModule الفعلي المستخدم أثناء إنشاء مثيل الوحدة الوحدات المرتبطة أثناء الربط. لأن في هذه النقطة، تكون جميع الوحدات قد رُبطت بالكامل بالفعل، ويكون تطبيق HostResolveImportedModule متزامنًا تمامًا كما في المواصفات.

module.linkingStatus

• من النوع <string>.

حاله الربط الحالية للوحدة module. وستكون إحدي القيم التالية:

• 'unlinked': لم يُستدعى module.link()‎ بعد.
• 'linking': أُستدعيَ module.link()‎، ولكن لم تُحل كل Promises المُعادة من قِبَل دالة الربط بعد.
• 'linked': أُستدعيَ module.link()‎، ورُبطت جميع التبعيات بنجاح.
• 'errored': أُستدعيَ module.link()‎، ولكن أحد تبعياته علي الأقل فشل في الارتباط، إما لان دالة رد الاتصال أعادت Promise مرفوض، أو لأن Module الذي أعادته دالة رد الاتصال غير صالحة.

module.namespace

• من النوع <Object>.

كائن مجال الأسماء للوحدة. وهو مناح فقط بعد اكتمال إنشاء المثيل (module.instantiate()‎).

يتوافق مع عملية GetModuleNamespace المجردة في مواصفة ECMAScript.

module.status

• من النوع <string>.

الحالة الحالية للوحدة. سوف تكون واحدة من:

• 'uninstantiated': لم يُنشأ مثيل للوحدة. قد يكون بسبب أيٍ من الأسباب التالية:
  • إنشاء الوحدة للتو.
  • استدعاء module.instantiate()‎ علي هذه الوحدة ولكن فشل لسبب ما.

لا ينقل هذا الوضع أيَّة معلومات تتعلق بإذا كان التابع module.link()‎ قد أستُدعيَ. راجع module.linkingstatus.

• 'instantiating': يُنشأ حاليًا مثيل الوحدة من خلال استدعاء module.instantiate()‎ علي نفسه أو على وحدة أصل.
• 'instantiated': نجح إنشاء مثيل للوحدة، ولكن لم يستدعى التابع module.evaluate()‎ حتى الآن.
• 'evaluating': يُقيَّم مثيل الوحدة من خلال استدعاء module.evaluate()‎ علي نفسه أو على وحدة أصل.
• 'evaluated': نجح تقييم الوحدة.
• 'errored': قُيّمت وحدة، ولكن أُجريَ استثناء.

بخلاف 'errored'، تتوافق سلسلة هذه الحالة مواصفات حقل سجل وحدة نَص المصدر [[Status]]. ويتوافق 'errored' مع 'evaluated' من حيث المواصفات، لكن يُضبط مع [[EvaluationError]] بقيمة غير undefined.

module.url

• من النوع <string>.

عنوان URL الخاص بالوحدة الحالية، كما هو محدد في المُنشِئ.

الصنف: vm.Script

أضيف مع الإصدار: v0.3.1.

تحتوي مثيلات  الصنف vm.Script علي سكريبتات مترجمة مسبقا والتي يمكن تنفيذها في بيئات معزولة (sandboxes) (أو "سياقات") معينة.

new vm.Script(code, options)

• code من النوع <string> وهو شيفرة JavaScript المراد ترجمتها.
• options
  • filename من النوع <string> وهو يحدد اسم الملف المستخدم في تتبعات المكدس المُنتَجة بواسطة هذا السكريبت.
  • lineOffset من النوع <number> وهو يحدد إزاحة رقم السطر المعروض في تتبعات المكدس التي ينتجها هذا السكريبت.
  • columnOffset من النوع <number> وهو يحدد إزاحة رقم العمود المعروض في تتبعات المكدس التي ينتجها هذا السكريبت.
  • cachedData من النوع <Buffer> وهو يوفرBuffer اختياري مع بيانات مؤقتة لشيفرة V8 للمصدر المُعطى. عند توفيرها، ستُضبط قيمة cacheddatarejected على true أو false اعتمادًا علي قبول البيانات بواسطة V8.
  • produceCachedData من النوع <boolean>. عندما يكون true ولا يوجد cachedData، سيحاول V8 إنتاج بيانات مؤقتة لشيفرة code. عند النجاح، سينتَج Buffer مع بيانات مؤقتة لشيفرة V8 ويُخزَّن في الخاصية cacheddata من مثيل vm.Script المُعاد. ستُضبط قيمة cacheddataproduced على true أو false استنادا إلى ما إذا البيانات المؤقتة للشيفرة قد أُنتجت بنجاح أم لا. تم إهمال هذا الخيار لصالح script.createCachedData()‎.

إنشاء كائن vm.Script جديد يُترجم code ولكن لا يُنفذها. يمكن تنفيذ vm.Script المُترجَم لاحقًا عدة مرات. لا يرتبط code إلى أي كائن عام، ولكن بدلا من ذلك، فانه يرتبط قبل كل تشغيل، فقط لهذا التشغيل.

script.createCachedData()‎

أضيف مع الإصدار: v10.6.0.

• القيمة المُعادة: من النوع <Buffer>.

إنشاء تخزين مؤقت للشيفرة البرمجية التي يمكن استخدامها مع خيار سكريبت المُنشِئ cachedData. يُعيد مخزن مؤقت. قد يستدعى هذا التابع في أي وقت ولأي عدد من المرات.

script.runInContext(contextifiedSandbox[, options]) [المصدر]

• contextifiedSandbox من النوع <object>، وهو الكائن الموضوع في السياق كما أُعيد من قبل التابع vm.createContext()‎.
• options من النوع  <Object>.
  • filename من النوع <string> وهو يحدد اسم الملف المستخدم في تتبعات المكدس المُنتَجة بواسطة هذا السكريبت.
  • lineOffset من النوع <number> وهو يحدد إزاحة رقم السطر المعروض في تتبعات المكدس التي ينتجها هذا السكريبت.
  • columnOffset من النوع <number> وهو يحدد إزاحة رقم العمود المعروض في تتبعات المكدس التي ينتجها هذا السكريبت.
  • displayErrors من النوع <boolean>، عندما يكون true، إذا حدث خطأ Error أثناء ترجمة code، يُرفق السطر من الشيفرة البرمجية الذي يسبب الخطأ إلى تتبع المكدس.
  • timeout من النوع <number> وهو يحدد عدد المللي ثانية اللازمة لتنفيذ code قبل إنهاء التنفيذ. إذا أنهي التنفيذ، سينطلقError.
  • breakOnSigint من النوع <boolean>، إذا كان true، سينتهي التنفيذ عند تلقي SIGINT (أو Ctrl + C). ستُعَّطل المعالجات الموجودة للحدث الذي أُرفِق بواسطة process.on('SIGINT') أثناء تنفيذ السكريبت، ولكنها سوف تستمر في العمل بعد ذلك. إذا أنهي التنفيذ، سينطلقError.

تشغيل التعليمات البرمجية المترجمة الوردة في كائن vm.Script داخل contextifiedSandbox المعطى وإعادة النتيجة. ليس لدى الشيفرة الجاري تشغيلها الحق في الوصول إلى النطاق المحلي.

يُترجم المثال التالي الشيفرة البرمجية التي تُزيد متغير عام، ويضبط قيمة متغير عام آخر، ثم يُنفذ التعليمات البرمجية عده مرات. المتغيرات العامة مضمنة في الكائن sandbox.

سيؤدي استخدام الخيارات timeout أو breakOnSigint إلى حلقات حدث جديد وبدء الخيوط المقابلة، والتي يكون لها عبء أداء (performance overhead) غير صفري.

script.runInNewContext([sandbox[, options]]) [المصدر]

• sandbox من النوع <Object> وهو الكائن المراد وضعه في السياق. إذا كان undefined ، سينشأ كائن جديد.
• options من النوع  <Object>.
  • filename من النوع <string> وهو يحدد اسم الملف المستخدم في تتبعات المكدس المُنتَجة بواسطة هذا السكريبت.
  • lineOffset من النوع <number> وهو يحدد إزاحة رقم السطر المعروض في تتبعات المكدس التي ينتجها هذا السكريبت.
  • columnOffset من النوع <number> وهو يحدد إزاحة رقم العمود المعروض في تتبعات المكدس التي ينتجها هذا السكريبت.
  • displayErrors من النوع <boolean>، عندما يكون true، إذا حدث خطأ Error أثناء ترجمة code، يُرفق السطر من الشيفرة البرمجية الذي يسبب الخطأ إلى تتبع المكدس.
  • timeout من النوع <number> وهو يحدد عدد المللي ثانية اللازمة لتنفيذ code قبل إنهاء التنفيذ. إذا أنهي التنفيذ، سينطلقError.
  • contextName من النوع <string> وهو اسم قابل للقراءة للسياق المُنشَأ حديثًا. القيمة الافتراضية: 'VM Context i'، حيث i هو مؤشر تصاعدي عددي للسياق المُنشَأ.
  • contextOrigin من النوع <string> وهو الأصل المقابل للسياق المُنشَأ حديثًا لأغراض العرض. يجب ان يكون تنسيق الأصل مثل URL، ولكن فقط مع المخطَط، والمضيف ، والمنفذ (إذا لزم الأمر) ، مثل قيمة الخاصية url.originلكائن URL. والاهم من ذلك، يجب حذف الشرطة المائلة اللاحقة، إذ إنها تشير إلى مسار. القيمة الافتراضية: ''.
  • contextCodeGenerationالقيمة المُعادة <Object>.
    • strings من النوع <boolean> إذا ضُبط على false سيُطلِق أي استدعاء إلى eval أو لمنشئات الدالة (Function و GeneratorFunction ، الخ) خطأ EvalError. القيمة الافتراضية: true.
    • wasm من نوع <boolean> إذا ضُبط على false ستُطلِق أي محاولة لترجمة وحدة WebAssembly الخطأ WebAssembly.CompileError. القيمة الافتراضية: true.

يضع أولا sandbox المعطى في السياق، ثم ينفذ الشيفرة البرمجية المترجمة الواردة في كائن vm.Script الوارد في sandbox المُنشَأ، وإعادة النتيجة. ليس لدى الشيفرة الجاري تشغيلها الحق في الوصول إلى النطاق المحلي.

يُترجم المثال التالي الشيفرة البرمجية التي تضبط قيمة متغير عام، ثم يُنفذ التعليمات البرمجية عده مرات في عدة سياقات. تُضبط المتغيرات العامة وترِد ضمن كل sandbox فردي.

script.runInThisContext([options]) [المصدر]

أضيف مع الإصدار: v0.3.1.

• options من النوع  <Object>.
  • filename من النوع <string> وهو يحدد اسم الملف المستخدم في تتبعات المكدس المُنتَجة بواسطة هذا السكريبت.
  • lineOffset من النوع <number> وهو يحدد إزاحة رقم السطر المعروض في تتبعات المكدس التي ينتجها هذا السكريبت.
  • columnOffset من النوع <number> وهو يحدد إزاحة رقم العمود المعروض في تتبعات المكدس التي ينتجها هذا السكريبت.
  • displayErrors من النوع <boolean>، عندما يكون true، إذا حدث خطأ Error أثناء ترجمة code، يُرفق السطر من الشيفرة البرمجية الذي يسبب الخطأ إلى تتبع المكدس.
  • timeout من النوع <number> وهو يحدد عدد المللي ثانية اللازمة لتنفيذ code قبل إنهاء التنفيذ. إذا أنهي التنفيذ، سينطلقError.

تشغيل الشيفرة البرمجية المترجمة المضمنة في vm.Script ضمن سياق الكائن global الحالي. ليس لدى الشيفرة الجاري تنفيذها الحق في الوصول إلى النطاق المحلي ولكن لديه حق الوصول إلى الكائن global الحالي.

يُترجم المثال التالي الشيفرة البرمجية التي تُزيد متغير global، ثم يُنفذ التعليمات البرمجية عده مرات.

vm.compileFunction(code[, params[, options]]) [المصدر]

أُضيف مع الإصدار: v10.10.0.

• code من النوع <string> وهو متن الدالة المراد ترجمتها.
• params من النوع <string[]> وهو مصفوفة من السلاسل النصية التي تحتوي على جميع المعاملات للدالة.
• options من النوع  <Object>.
  • filename من النوع <string> وهو يحدد اسم الملف المستخدم في تتبعات المكدس المُنتَجة بواسطة هذا السكريبت. القيمة الافتراضية: ''.
  • lineOffset من النوع <number> وهو يحدد إزاحة رقم السطر المعروض في تتبعات المكدس التي ينتجها هذا السكريبت. القيمة الافترضية: 0.
  • columnOffset من النوع <number> وهو يحدد إزاحة رقم العمود المعروض في تتبعات المكدس التي ينتجها هذا السكريبت. القيمة الافتراضية: 0.
  • cachedData من النوع <Buffer> وهو يوفرBuffer اختياري مع بيانات مؤقتة لشيفرة V8 للمصدر المُعطى.
  • producecacheddata من النوع <boolean>، وهو يحدد ما إذا كان ستُنتَج بيانات مؤقتة جديدة. القيمة الافتراضية: false.
  • parsingContext من النوع <Object> وهو sandbox/السياق الذي يجب ترجمة الدالة المعنية فيه.
  • contextExtensions من النوع < Object [] > وهو مصفوفة تحتوي علي مجموعة من ملحقات السياق (كائنات تلتف حول النطاق الحالي) لتطبيقها أثناء الترجمة. القيمة الافتراضية: [].

ترجمة الشيفرة البرمجية المعطاة إلى السياق/sanbox المتوفر (إذا لم يتوفر أي سياق ، يستخدم السياق الحالي) ، ويقوم بإرجاعها ملفوفَا داخل دالة مع params المعطي.

vm.createContext([sandbox[, options]]) [المصدر]

• sandbox من النوع <Object>.
• options من النوع  <Object>.
  • name من النوع <string> وهو اسم قابل للقراءة للسياق المُنشَأ حديثًا. القيمة الافتراضية: 'VM Context i'، حيث i هو مؤشر تصاعدي عددي للسياق المُنشَأ.
  • origin من النوع <string> وهو الأصل المقابل للسياق المُنشَأ حديثًا لأغراض العرض. يجب ان يكون تنسيق الأصل مثل URL، ولكن فقط مع المخطَط، والمضيف ، والمنفذ (إذا لزم الأمر) ، مثل قيمة الخاصية url.originلكائن URL. والاهم من ذلك، يجب حذف الشرطة المائلة اللاحقة، إذ إنها تشير إلى مسار. القيمة الافتراضية: ''.
  • codeGeneration من النوع <Object>
    • strings من النوع <boolean> إذا ضُبط على false سيُطلِق أي استدعاء إلى eval أو لمنشئات الدالة (Function و GeneratorFunction ، الخ) خطأ EvalError. القيمة الافتراضية: true.
    • wasm من نوع <boolean> إذا ضُبط على false ستُطلِق أي محاولة لترجمة وحدة WebAssembly الخطأ WebAssembly.CompileError. القيمة الافتراضية: true.

إذا أُعطي كائن sandbox، سيُحضِـر التابع vm.createContext()‎ كائن sandbox هذا بحيث يمكن استخدامه في استدعاء vm.runInContext()‎ أو script.runInContext()‎. داخل مثل هذه السكريبتات، سيكون كائن sandbox هو الكائن العام، محتفظًا بكافة خصائصه الموجودة ولكنه يمتلك أيضا الكائنات المضمنة والدوال التي يمتلكها أي كائن عام قياسي. فيما عدا السكريبتات التي تُنفَّذ بواسطة الوحدة vm، ستبقي المتغيرات العامة دون تغيير.

إذا حذف sandbox (أو مُرِر بشكل صريح كـ undefined)، سيعاد كائن sandbox جديد فارغ موضوع في السياق.

ويفيد التابع vm.createContext()‎ في المقام الأول في إنشاء sandbox منفرد والذي يمكن استخدامه لتشغيل عدة سكريبتات. علي سبيل المثال، في حالة محاكاة متصفح ويب، يمكن استخدام التابع لإنشاء sandbox منفرد يمثل كائن عام للإطار ، ثم لتشغيل كافة وسوم <script> معا ضمن سياق هذا ال sandbox.

ويُجعَل name و origin السياق المتوفرَين مرئيـيَن من خلال مفتش API.

vm.isContext(sandbox) [المصدر]

أضيف مع الإصدار: v 0.11.7.

• sandbox من النوع <Object>.
• القيمة المُعادة: من النوع <boolean>.

يُعيد true إذا وُضِع كائن sandbox المُعطي في السياق باستخدام vm. createcontext()‎‎.

vm.runInContext(رمز ، contextifiedSandbox [خيارات]) [المصدر]

• code من النوع <string> وهو شيفرة JavaScript المراد ترجمتها وتنفيذها.
• contextifiedSandbox من النوع <Object>، وهو الكائن الموضوع في السياق المستخدام كمتغير global عند ترجمة code وتشغيله.
• options من النوع <Object> | <string>.
  • filename من النوع <string> وهو يحدد اسم الملف المستخدم في تتبعات المكدس المُنتَجة بواسطة هذا السكريبت.
  • lineOffset من النوع <number> وهو يحدد إزاحة رقم السطر المعروض في تتبعات المكدس التي ينتجها هذا السكريبت.
  • columnOffset من النوع <number> وهو يحدد إزاحة رقم العمود المعروض في تتبعات المكدس التي ينتجها هذا السكريبت.
  • displayErrors من النوع <boolean>، عندما يكون true، إذا حدث خطأ Error أثناء ترجمة code، يُرفق السطر من الشيفرة البرمجية الذي يسبب الخطأ إلى تتبع المكدس.
  • timeout من النوع <number> وهو يحدد عدد المللي ثانية اللازمة لتنفيذ code قبل إنهاء التنفيذ. إذا أنهي التنفيذ، سينطلقError.

يترجم التابع vm.runInContext()‎ الشيفرة code، وينفذها ضمن سياقvm contextifiedSandbox ، ثم يعيد النتيجة. ليس لدى الشيفرة الجاري تنفيذها الحق في الوصول إلى النطاق المحلي. يجب أن يكون كائن contextifiedSandbox موضوعا مسبقا في السياق باستخدام التابع vm.createcontext()‎‎.

إذا كانت قيمة options سلسلة نصية، ثم تحدد اسم الملف.

يُترجم المثال التالي سكريبتات مختلفة وينفذها باستخدام كائن منفرد موضوع في السياق.

vm.runInNewContext(code[, sandbox[, options]]) [المصدر]

أضيف مع الإصدار: v0.3.1.

• code من النوع <string> وهو شيفرة JavaScript المراد ترجمتها وتنفيذها.
• sandbox من النوع <Object> وهو الكائن المراد وضعه في السياق. إذا كان undefined ، سينشأ كائن جديد.
• options من النوع <Object> | <string>.
  • filename من النوع <string> وهو يحدد اسم الملف المستخدم في تتبعات المكدس المُنتَجة بواسطة هذا السكريبت.
  • lineOffset من النوع <number> وهو يحدد إزاحة رقم السطر المعروض في تتبعات المكدس التي ينتجها هذا السكريبت.
  • columnOffset من النوع <number> وهو يحدد إزاحة رقم العمود المعروض في تتبعات المكدس التي ينتجها هذا السكريبت.
  • displayErrors من النوع <boolean>، عندما يكون true، إذا حدث خطأ Error أثناء ترجمة code، يُرفق السطر من الشيفرة البرمجية الذي يسبب الخطأ إلى تتبع المكدس.
  • timeout من النوع <number> وهو يحدد عدد المللي ثانية اللازمة لتنفيذ code قبل إنهاء التنفيذ. إذا أنهي التنفيذ، سينطلقError.
  • contextName من النوع <string> وهو اسم قابل للقراءة للسياق المُنشَأ حديثًا. القيمة الافتراضية: 'VM Context i'، حيث i هو مؤشر تصاعدي عددي للسياق المُنشَأ.
  • contextOrigin من النوع <string> وهو الأصل المقابل للسياق المُنشَأ حديثًا لأغراض العرض. يجب ان يكون تنسيق الأصل مثل URL، ولكن فقط مع المخطَط، والمضيف ، والمنفذ (إذا لزم الأمر) ، مثل قيمة الخاصية url.originلكائن URL. والاهم من ذلك، يجب حذف الشرطة المائلة اللاحقة، إذ إنها تشير إلى مسار. القيمة الافتراضية: ''.

يضع التابع Vm.runInNewContext()‎ أولا كائنَ sandbox المُعطى في السياق (أو ينشئ sandbox جديد إذا مُرر ك undefined) ، ويترجم code، وينفذه ضمن سياق السياق المُنشَأ، ثم يعيد النتيجة. ليس لدى الشيفرة الجاري تنفيذها الحق في الوصول إلى النطاق المحلي.

إذا كانت قيمة options سلسلة نصية، ثم تحدد اسم الملف.

يُترجم المثال التالي شيفرة وينفذها والتي تُزيد متغيرًا عامًا وتضبط واحدًا جديدًا. المتغيرات العامة مضمنة في الكائن sandbox.

vm.runInThisContext(code[, options]) [المصدر]

أضيف مع الإصدار: v0.3.1.

• code من النوع <string> وهو شيفرة JavaScript المراد ترجمتها وتنفيذها.
• options من النوع <Object> | <string>.
  • filename من النوع <string> وهو يحدد اسم الملف المستخدم في تتبعات المكدس المُنتَجة بواسطة هذا السكريبت.
  • lineOffset من النوع <number> وهو يحدد إزاحة رقم السطر المعروض في تتبعات المكدس التي ينتجها هذا السكريبت.
  • columnOffset من النوع <number> وهو يحدد إزاحة رقم العمود المعروض في تتبعات المكدس التي ينتجها هذا السكريبت.
  • displayErrors من النوع <boolean>، عندما يكون true، إذا حدث خطأ Error أثناء ترجمة code، يُرفق السطر من الشيفرة البرمجية الذي يسبب الخطأ إلى تتبع المكدس.
  • timeout من النوع <number> وهو يحدد عدد المللي ثانية اللازمة لتنفيذ code قبل إنهاء التنفيذ. إذا أنهي التنفيذ، سينطلقError.

يترجم التابع vm.runInThisContext()‎ الشيفرة code، وينفذها ضمن سياق global الحالي، ثم يعيد النتيجة. ليس لدى الشيفرة الجاري تنفيذها الحق في الوصول إلى النطاق المحلي ولكن لديه حق الوصول إلى الكائن global الحالي.

إذا كانت قيمة options سلسلة نصية، ثم تحدد اسم الملف.

يوضح المثال التالي استخدام كل من vm.runInThisContext()‎ ودالة JavaScript eval()‎ لتنفيذ نفس الشيفرة:

لا تتغير localVar، لأنه ليس لدى vm.runInThisContext()‎ الحق في الوصول إلى النطاق المحلي. في المقابل، eval()‎‎ لديه حق الوصول إلى النطاق المحلي، فتتغير قيمة localvar. بهذه الطريقة يصبح التابع vm.runinthiscontext()‎‎ مشابه إلى حد كبير بالاستدعاء غير المباشر للدالة eval()‎ ، علي سبيل المثال، (0,eval)('code').

أمثلة: تشغيل خادم HTTP ضمن VM.

عند استخدام إما script.runInThisContext()‎ أو vm.runInThisContext()‎‎ ، تُنفـَذ الشيفرة البرمجية داخل سياق V8 العام الحالي. سيكون للشيفرة البرمجية الممررة إلى سياق VM نطاقها المعزول الخاص.

من أجل تشغيل خادم ويب بسيط باستخدام وحدة http، يجب أن تستدعي الشيفرةُ البرمجية التي مُرِرت إلى السياقِ التابعَ require('http') على نفسه، أو أن يكون له مرجع إلى الوحدة http يمرر إليه. على سبيل المثال:

يشارك التابع require()‎ في الحالة السابقة الحالة مع السياق الذي مُرِر منه. وهذا قد يفرض المخاطر عند تنفيذ شيفرة برمجية غير موثوق بها، علي سبيل المثال تغيير الكائنات في السياق بطرق غير مرغوب فيها.

ماذا يعني أن يوضع كائن في السياق؟

جميع شيفرات JavaScript المنفذة داخل Node.js تعمل ضمن نطاق "السياق". فوفقا لدليل V8 Embedder:

في V8، يكون السياق هو بيئة تنفيذ والتي تسمح لتطبيقات JavaScript منفصلة، غير مترابطة أن تعمل في مثيل واحد من V8. يجب تحديد السياق المراد تشغيل أي شيفرات JavaScript فيه بشكل صريح.

عند استدعاء التابع vm.createcontext()‎، يقترن كائن sandbox الذي مُرِر فيه (أو كائن مُنشَأ حديثًا إذا كان sandbox قيمته undefined) داخليا مع مثيل جديد من سياق V8. يوفر سياق V8 هذا تشغيل code باستخدام توابع الوحدة vm مع بيئة عامة معزولة والتي يمكن أن تعمل فيها. عملية إنشاء سياق V8 واقترانه مع الكائن sandbox هو ما تشير إليه هذه الوثيقة بأنه "الوضع في السياق" لكائن sandbox.