Node.js/process

يكون الكائن process عامًا (global) والذي يزود معلومات عن عملية Node.js الحالية ورقابةً عليها، كونه كائنًا عامًا فهو متوافر دومًا لتطبيقات Node.js دون استخدام ()require.

أحداث Process

الكائن process هو نسخة من EventEmitter.

الحدث 'beforeExit'

أُضيف في الإصدار: 0.11.12.

يُطلَق الحدث 'beforeExit' عندما تفرغ Node.js من حلقة الأحداث (event loop) ولا يوجد عمل إضافي لجدولته. بشكل طبيعي، عملية Node.js سوف تنتهي عندما لا يكون هناك عمل مجدولٌ، لكن المُنصِت المسجِّل لحدث 'beforeExit' يمكن أن يعمل استدعاءات غير متزامنة، وبذلك يسبب استمرار عملية Node.js .

تُستدعى دالة رد نداء المنصت مع قيمة process.exitCode المُمررة كوسيط وحيد.

لا يُطلَق الحدث 'beforeExit' لأجل حالات تسبب إنهاء صريح، مثل استدعاء ()process.exit أو استثناءات غير مُلتقطة.

لا ينبغي أن يُستخدم 'beforeExit' كبديل للحدث 'exit' إلّا إذا كان القصد هو جدولة عمل إضافي.

الحدث 'disconnect'

أُضيف في الإصدار: 0.7.7.

إذا وُلِّدت عملية Node.js عبر قناة الاتصالات ما بين العمليات IPC (انظر توثيق Child Process و Cluster)، سوف يُطلَق الحدث 'disconnect' عندما تُغلق قناة IPC.

الحدث 'exit'

أُضيف في الإصدار: 0.1.7.

• code‏ ‎<integer>‎

يُطلَق الحدث 'exit' عندما تكون عملية Node.js على وشك الخروج كنتيجة لأحد أمرين:

• استدعاء التابع ()process.exit بشكل صريح؛
• لم تعد تحوي حلقة أحداث Node.js أي عمل إضافي ليُنجز.

لا توجد طريقة لمنع خروج حلقة الأحداث في هذه النقطة، وحالما ينتهي تنفيذ كل مُنصتات 'exit' سوف تنتهي عملية Node.js.

تُستدعى دالة رد النداء مع حالة الخروج؛ إمّا بخاصية process.exitCode أو بوسيط exitCode المُمرر للتابع process.exit(‎)‎.

process.on('exit', (code) => {
  console.log(`About to exit with code: ${code}`);
});

دوال المُنصت يجب أن تُنجِز عمليات متزامنة فقط. سوف تنتهي عملية Node.js مباشرةً بعد استدعاء مُنصتات الحدث 'exit' متسببًة بتجاهل أي عمل إضافي بقي في طابور حلقة الأحداث. في المثال التالي لن يُنفَّذ ما ضمن الدالة setTimeout:

process.on('exit', (code) => {
  setTimeout(() => {
    console.log('This will not run');
  }, 0);
});

الحدث 'message'

أُضيف في الإصدار: 0.5.10.

• message‏ ‎<Object> | <boolean> | <number> | <string> | <null>‎: كائن JASON مُحلل نحويًا أو قيمة أولية متسلسلة (serializable primitive value).

• sendHandle‏ <net.Server> | <net.Socket>: كائن net.Server أو net.Socket أو undefined.

إذا وُلِّدت عملية Node.js عبر قناة الاتصالات ما بين العمليات IPC (انظر توثيق Child Process و Cluster)، يُطلِق الحدث 'message' حالما تُستقبل الرسالة المُرسلة بواسطة العملية الأب باستخدام ()childprocess.send من قبل العملية الابن.

تمر الرسالة عبر مراحل التسلسل والتحليل النحوي، لذا قد لا تكون الرسالة الناتجة مثل الأصل الذي أُرسِل.

الحدث 'rejectionHandled'

أُضيف في الإصدار: 1.4.1.

• promise‏ ‏<Promise>: الوعد المُعالج المتأخر.

يُطلَق الحدث 'rejectionHandled' كلما رُفض الوعد Promise وأُرفق بمُعالج الأخطاء (على سبيل المثال، باستخدام ()promise.catch) متأخرةً عن حلقة أحداث Node.js بدور واحد.

سيكون الكائن Promise مُطلَقًا سابقًا في الحدث 'unhandledRejection'، لكن خلال دورة المعالجة حصل على مُعالِج الرفض.

لا يوجد دليل على مستوى عالي لأجل سلسلة Promise التي ستُعالج فيها المرفوضات دائمًا، كونها أصلاً غير متزامنة بطبيعتها، فيمكن أن يُعالج رفض Promise في نقطة مستقبلية في الزمن- ربما (المُعالجة) متأخرةً بكثير عن دور حلقة الأحداث الذي يأخذه حدث 'unhandledRejection' ليُطلق.

طريقة ثانية للتعبير عن ذلك، غير شبيهة بالشيفرة المتزامنة و حيث يوجد لائحة متزايدة دومًا من الاستثناءات غير المُعالجة، في الوعود Promises يمكن أن يكون هناك لائحة متزايدة-و-متناقصة من الرفض غير المُعَالج.

في الشيفرة المتزامنة، يُطلَق الحدث 'uncaughtException' عندما تزداد لائحة الاستثناءات غير المعالجة.

في الشيفرة غير المتزامنة يُطلَق الحدث 'unhandledRejection' عندما تزداد لائحة المرفوضات غير المُعالجة، ويُطلَق الحدث 'rejectionHandled' عندما تتناقص لائحة المرفوضات غير المُعالجة.

const unhandledRejections = new Map();
process.on('unhandledRejection', (reason, promise) => {
  unhandledRejections.set(promise, reason);
});
process.on('rejectionHandled', (promise) => {
  unhandledRejections.delete(promise);
});

في هذا المثال، سوف تزداد Map (خريطة) unhandledRejections وتتناقص بمرور الوقت، عاكسةً المرفوضات التي بدأت غير مُعالجة ثم أصبحت مُعالجة، من الممكن تسجيل مثل هذه الأخطاء في سجل أخطاء، إمّا دوريًا (والذي يبدو الأفضل من أجل التطبيقات طويلة التشغيل)أو عند خروج العملية (والذي يبدو الأنسب للبرامج النصية scripts).

الحدث 'uncaughtException'

أُضيف في الإصدار: 0.1.18.

يُطلق الحدث 'uncaughtException'  عندما تصعد استثناءات JavaScript غير المُلتقطة إلى حلقة الأحداث (event loop) في Node.js. بشكل افتراضي، تعالج Node.js مثل هذه الاستثناءات بطباعة التتبع التكديسي (stack trace) إلى مجرى الخطأ القياسي، stderr والخروج من العملية مع حالة الخروج 1. متجاوزةً أي تهيئة سابقة للخاصية process.exitCode. إضافة معالج للحدث 'uncaughtException' يعيد تعريف سلوكه الافتراضي. قد تُغيِّر أنت أيضًا الخاصية process.exitCode في معالج 'uncaughtException' مما سيؤدي إلى إنهاء العملية مع حالة الخروج المُحدَّدة، وإذا لم يوجد مثل هذا المعالج فسوف تخرج العملية مع حالة الخروج 0.

يُستدعى تابع المنصت مع الكائن Error المُمرر كوسيط وحيد.

process.on('uncaughtException', (err) => {
  fs.writeSync(1, `Caught exception: ${err}\n`);
});

setTimeout(() => {
  console.log('This will still run.');
}, 500);

// تسبب استثناء عمداَ ولكن لا تُمسكه
nonexistentFunc();
console.log('This will not run.');

تحذير: استخدام 'uncaughtException' بشكل صحيح

لاحظ أنّ 'uncaughtException' هو آلية خام لمعالجة الاستثناء ويُعتمد استخدامها فقط كحل أخير. لا ينبغي أن يستخدم هذا الحدث كبديل لآلية On Error Resume Next. الاستثناءات غير المعالجة الموروثة تعني أن التطبيق في حالة غير مُعرّفة. السعي لاستئناف شيفرة التطبيق بدون الاستعادة الصحيحة من الاستثناء قد تسبب أمور إضافية طارئة ولا يمكن التنبؤ بها.

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

محاولة الاستئناف الطبيعي بعد الاستثناء غير المُلتقط يمكن أن تكون شبيهة بسحب كبل الطاقة عند تحديث الحاسوب- تسعة مرات من عشرة لن يحصل شيء- لكن في المرة العاشرة، سيصبح النظام تالفًا.

الاستخدام الصحيح للحدث 'uncaughtException' هو إجراء تنظيف متزامن للموارد المحجوزة (على سبيل المثال، واصفات الملفات، المُعالجات/المقابض، ...إلخ.) قبل إيقاف تشغيل العملية. ليس من الآمن استئناف عملية عادية بعد 'uncaughtException'.

لإعادة تشغيل تطبيق معطّل بطريقة أكثر موثوقيةً، سواءً كان 'uncaughtException' مُطلقًا أو لا، ينبغي توظيف مراقب خارجي في عملية منفصلة لكشف فشل التطبيق والاستعادة أو إعادة التشغيل حسب الحاجة.

الحدث: 'unhandledRejection'

سجل التغييرات

الإصدار	التغييرات
7.0.0.	أُهمِلَت مرفوضات Promise غير المُعالجة.
6.6.0.	مرفوضات Promise غير المُعالجة سوف تبعث الآن تحذير process warning.
1.4.1.	أُضيف في الإصدار 1.4.1.

يُبعث الحدث 'unhandledRejection' كلّما رُفض وعد  Promise ولم يرفق معالج أخطاء بالوعد خلال دور من حلقة الأحداث. عند البرمجة مع الوعود، تُغلّف الاستثناءات "ك وعود مرفوضة". المرفوضات يمكن أن تُلتقط وتُعالج باستخدام ()promise.catch وتُنشر خلال سلسلة Promise. الحدث 'unhandledRejection' مفيد من أجل كشف و حفظ مسار الوعود التي رُفضت والتي لم تُعالَج مرفوضاتها بعد.

تُستدعى دالة المُنصت مع الوسائط التالية:

• reason‏ <Error> | <any>: الكائن الذي رُفض الوعد معه (عادةً ما يكون كائن Error)

• p :الوعد Promise الذي رُفِض

process.on('unhandledRejection', (reason, p) => {
  console.log('Unhandled Rejection at:', p, 'reason:', reason);
//تسجيل دخول محدد التطبيق ، راميًا خطأ أو منطق برمجي آخر هنا
});

somePromise.then((res) => {
  return reportToUser(JSON.pasre(res)); // (`pasre`) لاحظ الخطأ المطبعي
}); // `.catch()` أو `.then()`لا يوجد

ستؤدي الشيفرة الآتية إلى إطلاق الحدث 'unhandledRejection':

function SomeResource() {
// مبدئيًا يضبط الحالة المُحمّلة إلى وعد مرفوض
  this.loaded = Promise.reject(new Error('Resource not yet loaded!'));
}

const resource = new SomeResource();
//لدور واحد على الأقل resource.loaded‎ على catch أو .then ‎لايوجد

في حالة هذا المثال، يمكن تتبع الرفض كخطأ مطوِّر(developer error) كما تكون الحالة النموذجية لأحداث 'unhandledRejection' الأخرى. لعنونة مثل هذا الفشل، يمكن أن يُرفق معالج ‎‏‎‎‎‏‎.‎catch‎(() => { }‎)‎‎‎‎‎‎‎ غير العملياتي

(non-operational ‎.‎catch‎(() => { }‎)‎‎‎‎‎‎‎‎) ب resource.loaded ، والذي سيمنع الحدث 'unhandledRejection' من الإطلاق. بدلًا من ذلك، يمكن أن يُستخدم الحدث 'rejectionHandled'.

الحدث 'warning'

أُضيف في الإصدار: 6.0.0.

• warning‏ <Error>

الخصائص الرئيسة/المفتاحية للتحذير warning هي:

• name‏ <string>: اسم التحذير. القيمة الافتراضية: 'Warning'.

• message‏ <string>: توصيف مزوّد من قبل النظام عن التحذير.

• stack‏ <string>: المسار المُكدَّس/التتبع التكديسي للمكان في الشيفرة حيث أُصدر التحذير.

يُطلق الحدث 'warning' كلّما أطلق Node.js تحذير عملية (process warning).

تحذير العملية (process warning) شبيهٌ بالخطأ في أنّه يوصّف ظروفًا استثنائيةً والتي تسترعي انتباه المستخدم. لكن التحذيرات ليست جزءًا من تدفق معالجة الأخطاء الطبيعي في Node.js و JavaScript. تستطيع Node.js إطلاق تحذيرات كلّما كشفت عن ممارسات شيفرة سيئة يمكن أن تقود إلى أداء تطبيق دون المستوى الأمثل، أو أخطاء، أو ثغرات أمنية.

process.on('warning', (warning) => {
  console.warn(warning.name);  //يطبع اسم التحذير
  console.warn(warning.message);   //يطبع رسالة التحذير
  console.warn(warning.stack);  //التتبع التكديسي‎ يطبع
});

افتراضيًا، سوف تطبع Node.js تحذيرات عمليات (process warning) إلى مجرى الخطأ القياسي stderr. يمكن أن يُستخدم خيار سطر الأوامر ‎-‎‎-‎no-‎warnings‎ لكتم مخرجات console (وحدة التحكم) الافتراضية لكن الحدث سيبقى مُطلقًا من قبل الكائن process. يوضّح المثال التالي التحذير الذي يُطبع إلى مجرى الخطأ القياسي stderr عندما تُضاف الكثير من المُنصتات إلى حدث ما:

$ node
> events.defaultMaxListeners = 1;
> process.on('foo', () => {});
> process.on('foo', () => {});
> (node:38638) MaxListenersExceededWarning: Possible EventEmitter memory leak
detected. 2 foo listeners added. Use emitter.setMaxListeners() to increase limit

بالمقابل، يطفئ المثال التالي خرج التحذير الافتراضي ويضيف مُعالج مخصص لحدث 'warning':

$ node --no-warnings
> const p = process.on('warning', (warning) => console.warn('Do not do that!'));
> events.defaultMaxListeners = 1;
> process.on('foo', () => {});
> process.on('foo', () => {});
> Do not do that!

يمكن أن يُستخدم خيار سطر الأوامر ‎-‎-‎trace-‎warnings‎ للحصول على خرج وحدة التحكم console الافتراضي للتحذيرات متضمنًا المسار المكدَّس/التتبع التكديسي الكامل للتحذير.

تشغيل Node.js باستخدام خيار سطر الأوامر ‎-‎-‎throw-‎deprecation‎ سوف يسبب إلقاء تحذيرات مُهملة/منخفضة الأهمية مخصصة (custom deprecation warnings) كاستثناءات.

سيسبب استخدام خيار سطر الأوامر ‎-‎-‎trace-‎deprecation‎ طباعة التحذيرات المُهملة المخصصة إلى مجرى الخطأ القياسي stderr مع المسار المكدَّس/التتبع التكديسي.

سوف يكتم استخدام خيار سطر الأوامر ‎-‎-‎no-‎deprecation‎ كل التقارير عن التحذيرات المُهملة المخصصة.

ستؤثر خيارات سطر الأوامر ‎*‎-‎deprecation‎ فقط على التحذيرات التي تستخدم الاسم 'DeprecationWarning'

إصدار تحذيرات مخصصة

انظر التابع process.emitWarnin‎g()‎ لإصدار تحذيرات مُخصصة أو خاصة بالتطبيق.

أحداث الإشارات (Signal Events)

سوف تُطلق أحداث الإشارة عندما تستقبل عملية Node.js إشارةً، رجاءً راجع signal(7)‎ من أجل لائحة أسماء إشارات POSIX (واجهة نظام التشغيل المحمولة لأنظمة يونكس) القياسية مثل 'SIGINT' و 'SIGHUP'  ...إلخ.

سوف يستقبل مُعالج الإشارة اسم الاشارة ('SIGINT' أو 'SIGTERM' أو ...إلخ.) كأول وسيط.

سيكون اسم كل حدث هو الاسم الشائع للحدث وبحالة الأحرف الكبيرة (مثال 'SIGINT' من أجل إشارات SIGINT).

// لذلك لن تنتهي العملية stdin بدء القراءة من مجرى الدخل القياسي
process.stdin.resume();

process.on('SIGINT', () => {
  console.log('Received SIGINT. Press Control-D to exit.');
});

//استخدام دالة وحيدة لمعالجة إشارات متعددة
function handle(signal) {
  console.log(`Received ${signal}`);
}

process.on('SIGINT', handle);
process.on('SIGTERM', handle);

• 'SIGUSR1': محجوزة من قبل Node.js من أجل بدء المُنقّح (debugger)، من الممكن تنصيب مُنصت ولكن فعل ذلك قد يؤدي إلى تداخل مع المُنقّح.
• 'SIGTERM' و 'SIGINT': تملك مُعالجات افتراضية على منصات غير ويندوز (أنظمة تشغيل مختلفة عن ويندوز) والتي ستعيد ضبط حالة الطرفية إلى حالتها الافتراضية قبل الخروج (العودة من الصدفة) بحالة خروج تساوي 128 + رقم الإشارة

‎(‎128‎ +‎ signal‎ number‎)‎‎. إذا كانت إحدى هذه الإشارات تمتلك مُنصتًا مُنصّبًا(موجودًا لتغيير آلية معالجة الإشارة)، سوف يُزال سلوكها الافتراضي (ولن تنتهي عملية Node.js حينئذٍ).

• 'SIGPIPE': مُهملة افتراضيًا، يمكن أن تملك مُنصتًا مُنصبًا (موجوداً لمعالجة الإشارة بآلية خاصة).
• 'SIGHUP': تُولّد في ويندوز عندما تُغلق نافذة الطرفية/وحدة التحكم console، وعلى المنصات الأخرى تحت ظروف شتى مشابهة، انظر signal(7)‎. يمكن أن تملك مُنصتًا منصبًا، ولكن Node.js سوف تُنهى بشكل غير مشروط من قبل ويندوز بعد حوالي 10 ثواني. على منصات غير ويندوز، السلوك الافتراضي للحدث SIGHUP هو إنهاء Node.js، لكن حالما يُنصّب المنصت سوف يُزال سلوكه الافتراضي.
• 'SIGTERM': ليست مدعومةً في ويندوز، يمكن الانصات عليها.
• 'SIGINT': مدعومة من قبل الطرفية على جميع المنصات، ويمكن توليدها عادة ب ‎<‎Ctrl>‎+‎C‎ (بالرغم أن ذلك قد يكون قابلًا للضبط)، لا تُولّد عندما يكون النمط الخام للطرفية مفعلاً.
• 'SIGBREAK': تُرسل في ويندوز عندما يُضغط <Ctrl>+<Break>، على منصات غير ويندوز يمكن الاستماع لها، ولكن لا يوجد طريقة لإرسالها أو توليدها.
• 'SIGWINCH': تُرسل عندما يُغيّر حجم الطرفية/وحدة التحكم console في الويندوز، سوف يحصل هذا فقط في الكتابة على وحدة التحكم عندما يُحرّك المؤشر، أو عندما تكون tty (الطرفية الوهمية التي ينشئها نظام التشغيل) القابلة للقراءة مُستخدمة في الوضع الخام.
• 'SIGKILL': لا يمكن أن تمتلك مُنصتًا مُنصّبًا (لمعالجة الإشارة بآلية خاصة)، سوف تُنهي Node.js بشكل غير مشروط على جميع المنصات.
• 'SIGSTOP': لا يمكن أن تمتلك مُنصتًا مُنصّبًا (لمعالجة الإشارة بآلية خاصة).
• 'SIGBUS 'و 'SIGFPE' و'SIGSEGV' و 'SIGILL': عندما لا تُثار صناعيًا باستخدام kill(‎2‎‎)‎، تترك العملية بشكل متأصل في حالة ليس آمنًا منها محاولة استدعاء مُنصتات JS، القيام بذلك قد يقود إلى تعليق العملية في حلقة لا نهائية، بما أن المُنصتات المرفقة باستخدام process.on(‎)‎ تُستدعى بشكل غير متزامن فهي غير قادرة على تصحيح المشكلة الأساسية.

لا يدعم ويندوز إرسال الإشارات، لكن Node.js توفر بعض المحاكاة مع التوابع process.kill(‎)‎ و subprocess.kill(‎)‎. إرسال الإشارة 0 يمكن أن يُستخدم لاختبار وجود العملية. إرسال SIGINT و SIGTERM و SIGKILL يسبب انهاءً غير مشروطٍ للعملية الهدف.

process.abort(‎)‎

أُضيف في الإصدار: 0.7.0.

يسبب التابع process.abort(‎‎)‎ خروج عملية Node.js مباشرة وتوليد ملف نواة (core file).

هذه الميزة ليست متوفرة في خيوط Worker.

Process.arch

أُضيفت في الإصدار: 0.5.0.

• <string>

تعيد الخاصية process.arch سلسلة نصية مُعرِّفةً البنية المعمارية لوحدة المعالجة المركزية CPU لنظام التشغيل والذي بُنيت فيه Node.js الثنائية.

القيم الحالية الممكنة هي:

'arm'، و'arm64'، و'ia32'، و'mips'، و'mipsel'، و'ppc'، و'ppc64'، و's390'، و's390x'، و'x32'، و'x64'.

console.log(`This processor architecture is ${process.arch}`);

process.argv

أُضيفت في الإصدار: 0.1.27.

• <string[]‎>

تعيد الخاصية process.argv مصفوفةً متضمنةً على وسطاء سطر الأوامر المُمررة عندما شُغّلت عملية Node.js. سيكون العنصر الأول process.execPath. انظر process.argv0 إذا كان هناك حاجة للوصول إلى القيمة الأصلية للوسيط argv[‎0‎]‎. سوف يكون العنصر الثاني مسار إلى ملف JavaScript قيد التنفيذ. العناصر المتبقية ستكون أي وسطاء إضافية لسطر الأوامر.

على سبيل المثال، بافتراض السكربت التالي باسم process-args.js:

//يطبع process.argv
process.argv.forEach((val, index) => {
  console.log(`${index}: ${val}`);
});

تشغيل عملية Node.js مثلَ:

$ node process-args.js one two=three four

سيولّد الناتج الآتي:

0: /usr/local/bin/node
1: /Users/mjr/work/node/process-args.js
2: one
3: two=three
4: four

process.argv0

أُضيفت في الإصدار: 6.4.0.

• <string>

تُخزِّن الخاصية process.argv0 نسخة قابلة للقراءة فقط من القيم الأصلية للوسيط argv[‎0‎]‎ مُمررةً عندما تبدأ Node.js.

$ bash -c 'exec -a customArgv0 ./node'
> process.argv[0]
'/Volumes/code/external/node/out/Release/node'
> process.argv0
'customArgv0'

Process.channel

أُضيفت في الإصدار: 7.1.0.

• <Object>

إذا وُلِّدت عملية Node.js عبر قناة الاتصالات ما بين العمليات IPC (انظر توثيق العملية الابن Child Process) تكون الخاصية process.channel مرجعًا لقناة الاتصال ما بين العمليات IPC. إذا لم توجد قناة IPC، تكون هذه الخاصية غير معرّفة undefined.

process.chdir(directory‎)‎

أُضيف في الإصدار: 0.1.17.  

• directory <string>‎

يغير التابع process.chdir‎(‎)‎ مجلد العمل الحالي لعملية Node.js أو يرمي استثناءً إذا فشل ذلك (على سبيل المثال، إذا كان directory المحدد غير موجود).

console.log(`Starting directory: ${process.cwd()}`);
try {
  process.chdir('/tmp');
  console.log(`New directory: ${process.cwd()}`);
} catch (err) {
  console.error(`chdir: ${err}`);
}

هذه الميزة غير متوافرة في خيوط Worker‏‎.‏‎‎

process.config

أُضيفت في الإصدار: 0.7.7.

• <Object>

تعيد الخاصية process.config كائن Object حاوي على تمثيل JavaScript لخيارات التهيئة المستخدمة لبناء الملف التنفيدي لبرمجية Node.js الحالية القابلة للتنفيذ. وهذا مثل ملف config.gypi الذي يُنتج عند تشغيل سكربت الضبط (أي السكربت ‎/‎‎configure‎.).

يبدو مثال عن المخرجات المحتملة مثل:

{
  target_defaults:
   { cflags: [],
     default_configuration: 'Release',
     defines: [],
     include_dirs: [],
     libraries: [] },
  variables:
   {
     host_arch: 'x64',
     node_install_npm: 'true',
     node_prefix: '',
     node_shared_cares: 'false',
     node_shared_http_parser: 'false',
     node_shared_libuv: 'false',
     node_shared_zlib: 'false',
     node_use_dtrace: 'false',
     node_use_openssl: 'true',
     node_shared_openssl: 'false',
     strict_aliasing: 'true',
     target_arch: 'x64',
     v8_use_snapshot: 'true'
   }
}

الخاصية process.config ليست للقراءة فقط وهناك وحدات موجودة في في النظام الذي توفره Node.js تُعرَّف للتوسّع أو التعديل أو تبديل كلي لقيمة process.config.

process.connected

أُضيفت في الإصدار: 0.7.2.

• <boolean>

إذا وُلِّدت عملية Node.js عبر قناة الاتصالات ما بين العمليات IPC (انظر توثيق Child Process وCluster) سوف تعيد الخاصية process.connected القيمة true طالما كانت قناة IPC متصلة وستعيد القيمة false بعد أن يُستدعى التابع process.disconnect(‎)‎.

حالما تصبح قيمة process.connected خطأ (false)، لا يعود من الممكن إرسال رسائل عبر قناة IPC باستخدام التابع process.send(‎)‎.

process.cpuUsage([previousValue‎]‎)‎

أُضيف في الإصدار: 6.1.0.

• previousValue‏ ‎:<Object>‎ قيمة سابقة مُعادة من استدعاء التابع process.cpuUsage(‎)‎.
• القيمة المعادة: <Object>
  • user‏ ‎<integer>‎
  • system‏ ‎<integer>‎

يعيد التابع process.cpuUsage(‎)‎ وقت المُستخدِم ووقت نظام وحدة المعالجة المركزية CPU المُستخدم في العملية الحالية، في كائن مع الخاصيتين user و system، حيث قيمهما هي قيم بالميكرو ثانية (مليون من الثانية). تقيس هذه القيم الوقت المُنفق في شيفرة المستخدم والنظام على الترتيب، وقد تنتهي بكونه (الوقت) أكبر من الوقت الفعلي المنقضي إذا كانت وحدة معالجة مركزية متعددة النوى تنجز العمل لهذه العملية.

يمكن أن تُمرر نتيجة استدعاء سابق للتابع process.cpuUsage(‎)‎ كوسيط للدالة، للحصول على قراءة مختلفة.

const startUsage = process.cpuUsage();
// { user: 38579, system: 6986 }
//{ المستخدم: 38579, النظام: 6986 }


//جعل المعالج يدور ل 500 ميلي ثانية
const now = Date.now();
while (Date.now() - now < 500);

console.log(process.cpuUsage(startUsage));
// { user: 514883, system: 11226 }
// { المستخدم: 514883, النظام: 11226 }

process.cwd(‎)‎

أُضيف في الإصدار: 0.1.8.

• القيمة المعادة: <string>

يعيد التابع process.cwd(‎)‎ مجلد العمل الحالي لعملية Node.js.

console.log(`Current directory: ${process.cwd()}`);

process.debugPort

أُضيفت في الإصدار: 0.7.2.

• <number>

المَنفذ المستخدم من قبل المُنقّح (debugger) الخاص ب Node.js عندما يُفعّل.

process.debugPort = 5858;

process.disconnect(‎)‎

أُضيف في الإصدار: 0.7.2.

إذا وُلِّدت عملية Node.js عبر قناة الاتصالات ما بين العمليات IPC (انظر توثيق Child Process و Cluster)، سيُغلِق التابع process.disconnect(‎)‎ قناة IPC للعملية الأب، سامحةً للعملية الابن بالانتهاء بأمان حالما لا تتواجد أي اتصالات أخرى تبقيها حية.

تأثير استدعاء process.disconnect‎(‎‎)‎‎ هو مثل استدعاء العملية الأب للتابع ChildProcess.disconnect(‎)‎.

إذا كانت عملية Node.js غير مُولَّدة بقناة الاتصال ما بين العمليات IPC، سيكون process.disconnect‎(‎‎)‎‎ غير معرّف undefined.

‎process.dlopen(module, filename[, flags‎]‎)‎

سجل التغييرات

الإصدار	التغييرات
9.0.0.	إضافة الدعم للوسيط  flags.
0.1.16.	أُضيف في الإصدار 0.1.16.

• module‏ ‎<Object>‎
• filename‏ <string>
• flags‏ ‎<os.constants.dlopen>‎، القيمة الإفتراضية: os.constants.dlopen.RTLD_LAZY.

يسمح التابع process.dlopen(‎)‎ بتحميل الكائنات المُشتركة المحلية ديناميكيًا. إنّه يُستخدم في الأصل من خلال require(‎)‎ من أجل تحميل إضافات ++C، ولا ينبغي أن يُستخدم مباشرة، إلّا في حالات خاصة. بعبارة أخرى، ينبغي تفضيل require(‎)‎ على process.dlopen(‎)‎، مالم تكن هناك أسباب محددة.

الوسيط flags هو عدد صحيح يسمح بتحديد سلوك dlopen. انظر توثيق os.constants.dlopen للتفاصيل.

إذا كان هناك أسباب محددة لاستخدام process.dlopen(‎)‎ (على سبيل المثال، لضبط رايات dlopen)، فمن المفيد غالبًا استخدام require.resolve(‎)‎ للبحث عن مسار الوحدة.

هنالك عائق مهم عند استدعاء process.dlopen(‎)‎ هو أن نسخة من الكائن/الصنف module يجب أن تُمرر. سيكون الوصول إلى التوابع المُصدّرة من قبل إضافات C+‎+‎ ممكنًا عبر module.exports.

يعرض المثال في الأسفل كيفية تحميل إضافة C+‎+‎. مسماة binding، وتُصدّر كدالة foo. سوف تُحمّل كل الرموز قبل عودة الاستدعاء، عبر تمرير الثابت RTLD_NOW. يُفترَض في هذا المثال أن يكون الثابت RTLD_NOW متوافرًا:

const os = require('os');
process.dlopen(module, require.resolve('binding'),
               os.constants.dlopen.RTLD_NOW);
module.exports.foo();

process.emitWarning(warning[, options]‎)‎

أُضيف في الإصدار: 8.0.0.

• warning‏ ‎<string> | <Error>‎‎: التحذير الذي سيُطلق

• options‏ ‎<Object>‎
  • type‏ ‎<string>‎: عندما يكون التحذير warning هو سلسلة نصية String، يكون النوع type هو الاسم المُستخدم لنوع التحذير الذي يُطلق. القيمة الافتراضية: 'Warning'.
  • code‏ ‎<string>‎: مُعرِّف فريد لنسخة التحذير التي ستُطلق.
  • ctor‏ ‎<Function>‎: عندما يكون warning هو سلسلة نصية، يكون ctor تابع اختياري يُستخدم للحد من المسار التتبع التكديسي المتولد. القيمة الإفتراضية :process.emitWarning.
  • detail‏ ‎<string>‎: نص إضافي ليدرج مع الخطأ.

يمكن أن يُستخدم التابع process.emitWarning(‎)‎ لإطلاق تحذيرات عمليات (process warnings) مُحددة التطبيق أو مخصصة. يمكن الإنصات إليها بإضافة معالج إلى حدث 'warning'.

// إطلاق تحذير مع رمز وتفاصيل أخرى
process.emitWarning('Something happened!', {
  code: 'MY_WARNING',
  detail: 'This is some additional information'
});
//تطلق:‏
// (node:56338) [MY_WARNING] Warning: Something happened!
// This is some additional information هذه بعض المعلومات الإضافية
في هذا المثال، وُلِّد كائن خطأ Error داخليًا من قبل التابع process.emitWarning(‎)‎ و مُرر إلى معالج 'warning'
process.on('warning', (warning) => {
  console.warn(warning.name);    // 'Warning'
  console.warn(warning.message); // 'Something happened!'
  console.warn(warning.code);    // 'MY_WARNING'
  console.warn(warning.stack);  //التتبع التكديسي‎
  console.warn(warning.detail);  // 'This is some additional information'
});

إذا مُرر التحذير warning ككائن Error ، يُهمل الوسيط options.

process.emitWarning(warning[, type[, code]][, ctor‎]‎)‎

أُضيف في الإصدار: 6.0.0.

• warning‏‎<string> | <Error> ‎‎: التحذير الذي سيُطلق.
• type‏ ‎<string>‎: عندما يكون التحذير warning سلسلة نصية، يكون type هو الاسم المُستخدم لنوع التحذير الذي يُطلق. القيمة الإفتراضية: 'Warning'
• code‏ ‎<string>‎: مُعرِّف فريد لنسخة التحذير الذي يُطلق.

• ctor‏ ‎<Function>‎: عندما يكون التحذير warning سلسلة نصية، يُستخدمctor كتابع اختياري للحد من التتبع التكديسي المتولّد. القيمة الإفتراضية: process.emitWarning.

يمكن أن يُستخدم التابع process.emitWarning(‎)‎ لإطلاق تحذيرات عمليات (process warnings) محددة التطبيق أو مخصصة. يمكن الإنصات إليها بإضافة معالج إلى حدث 'warning'.

//إطلاق تحذير باستخدام سلسلة
process.emitWarning('Something happened!');
// Emits: (node: 56338) Warning: Something happened!
// تطلق :(node: 56338) التحذير: Something happened!
// .تطلق تحذير باستخدام سلسلة ونوع
process.emitWarning('Something Happened!', 'CustomWarning');
// Emits: (node:56338) CustomWarning: Something Happened!
//تطلق:(node:56338) CustomWarning:Something Happened!
process.emitWarning('Something happened!', 'CustomWarning', 'WARN001');
// Emits: (node:56338) [WARN001] CustomWarning: Something happened!
// تطلق: (node:56338) [WARN001] CustomWarning: Something happened!

في كل من الأمثلة السابقة، يُولّد كائن Error داخليًا من قبل التابع process.emitWarning(‎)‎ ويُمرر عبرها إلى معالج 'warning'.

process.on('warning', (warning) => {
  console.warn(warning.name);
  console.warn(warning.message);
  console.warn(warning.code);
  console.warn(warning.stack);
});

إذا مُرر التحذير warning ككائن Error، سوف يُمرر عبر معالج الحدث 'warning' غير معدلٍ (وسوف تُهمل الوسطاء الإختيارية type و code و ctor):

// Error إطلاق تحذير باستخدام كائن 
const myWarning = new Error('Something happened!');
//  لتحديد اسم النوع Error استخدام خاصية اسم الكائن
myWarning.name = 'CustomWarning';
myWarning.code = 'WARN001';

process.emitWarning(myWarning);
// Emits: (node:56338) [WARN001] CustomWarning: Something happened!
//تطلق: (node:56338) [WARN001] CustomWarning: Something happened!

يرمى خطأ مطبعي TypeError إذا كان التحذير warning هو أي شيء غير السلسلة النصية أو كائن Error.

لاحظ أنّه بينما تستخدم تحذيرات العمليات (process warning) كائنات Error، آلية تحذير العمليات ليست بديلة لآلية معالجة الأخطاء العادية.

تُنفذ المعالجة الإضافية التالية إذا كان نوع (type) التحذير هو 'DeprecationWarning':

• إذا استُخدِم خيار سطر الأوامر ‎-‎-‎throw‎-‎deprecation‎، سيُلقى التحذير المُهمل كاستثناء بدلًا من إطلاقه كحدث.
• إذا استُخدِم خيار سطر الأوامر ‎-‎-‎no‎-‎deprecation‎، سيُكبت التحذير المُهمل.
• إذا استُخدم خيار سطر الأوامر ‎-‎-‎trace‎-‎deprecation‎ ، سيُطبَع التحذير المُهمل إلى مجرى الخطأ القياسي stderr مع التتبع التكديسي الكامل.

تجنب التحذيرات المُكرّرة (Avoiding duplicate warnings)

من المستحسن أن تُطلق التحذيرات مرة فقط لكل العملية. لفعل ذلك، يُنصح بوضع التابع emitWarning(‎)‎ بعد اختبارٍ منطقيٍ بسيط كما هو موضح في المثال أدناه:

function emitMyWarning() {
  if (!emitMyWarning.warned) {
    emitMyWarning.warned = true;
    process.emitWarning('Only warn once!');
  }
}
emitMyWarning();
// Emits: (node: 56339) Warning: Only warn once!
//تطلق: (node: 56339) Warning: Only warn once!
emitMyWarning();
// Emits nothing
// تطلق لاشيء

process.env

سجل التغييرات

الإصدار	التغييرات
10.0.0.	أُهمل التحويل الضمني لقيمة المتحول إلى سلسلة نصية
0.1.27.	أُضيفت في الإصدار 0.1.27

• <Object>

ستعيد الخاصية process.env كائنًا حاويًا على بيئة المستخدم. انظر environ(‎7‎)‎ .

يبدو مثالٌ عن الكائن شبيهًا بالكائن الآتي:

{
  TERM: 'xterm-256color',
  SHELL: '/usr/local/bin/bash',
  USER: 'maciej',
  PATH: '~/.bin/:/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin',
  PWD: '/Users/maciej',
  EDITOR: 'vim',
  SHLVL: '1',
  HOME: '/Users/maciej',
  LOGNAME: 'maciej',
  _: '/usr/local/bin/node'
}

يمكن تعديل هذا الكائن، ولكن مثل هذه التعديلات لن تنعكس خارج عملية Node.js . بعبارة أخرى، المثال التالي لن يعمل:

$ node -e 'process.env.foo = "bar"' && echo $foo

بينما سيعمل المثال التالي:

process.env.foo = 'bar';
console.log(process.env.foo);

إسناد الخاصية process.env سوف يحول القيمة ضمنيًا إلى سلسلة نصية، أُهمل هذا السلوك. سترمي النسخ المستقبلية من Node.js خطأً عندما لا تكون القيمة سلسلة نصية أو عدد أو قيمة منطقية. مثال:

process.env.test = null;
console.log(process.env.test);
// => 'null'
process.env.test = undefined;
console.log(process.env.test);
// => 'undefined'

استخدم المعامل delete لحذف خاصية من process.env. مثال:

process.env.TEST = 1;
delete process.env.TEST;
console.log(process.env.TEST);
// => undefined
//=> غير معرّف

في نظام التشغيل ويندوز، تكون متغيرات البيئة غير حساسة لحالة الأحرف. مثال:

process.env.TEST = 1;
console.log(process.env.test);
// => 1

الخاصية process.env قابلة للقراءة فقط في خيوط Worker.

process.execArgv

أُضيفت في الإصدار: 0.7.7.

• ‎<‎string‎[‎]‎>‎‎‎

تعيد الخاصية process.execArgv مجموعة من خيارات سطر الأوامر الخاصة ببيئة Node.js والمُمرَّرة عندما تُشغّل عملية Node.js. لا تظهر هذه الخيارات في المصفوفة المُعادة من قبل الخاصية process.argv، ولا تتضمن هذه المصفوفة اسم الملف التنفيذي لبيئة Node.js، ولا اسم السكربت المُشغَّل، ولا أيّ خيارات تلي اسم السكربت. هذه الخيارات مفيدة من أجل توليد عملية ابن بنفس بيئة التنفيذ للعملية الأب.

$ node --harmony script.js --version

يُنتِج ما سبق القيمة الآتية المخزّنة في الخاصية process.execArgv:

['--harmony']

وفي process.argv:

['/usr/local/bin/node', 'script.js', '--version']

process.execPath

أُضيفت في الإصدار: 0.1.100.

• <string>

تعيد الخاصية process.execPath المسار المطلق للملف التنفيذي الذي يبدأ عملية Node.js:

'/usr/local/bin/node'

process.exit([code‎]‎)‎

أُضيف في الإصدار: 0.1.13.

• ‎<integer>‎ code: حالة الخروج. القيمة الإفتراضية :0

التابع process.exit(‎)‎ يأمر Node.js إنهاء العملية بشكل متزامن مع حالة الخروج code. إذا حُذف code، يستخدم الخروج إمّا حالة النجاح '‎‎success‎‎' وقيمته 0 أو قيمة الخاصية process.exitCode إذا ضُبطت. لن تنتهي Node.js حتى تُستدعى جميع مُنصتات الحدث 'exit'.

للانهاء مع حالة الفشل 'failure' :

process.exit(1);

ينبغي أن ترى الصدفة التي نفّذت Node.js حالة الخروج ‎.‎1

استدعاء process.exit(‎)‎ سيجبر العملية على الانتهاء بأقصى سرعة ممكنة حتى لو بقيت هناك عمليات (operations) غير متزامنة معلّقة ولم تنته بالكامل بعد. متضمنةً عمليات الدخل والخرج I/O إلى process.stdout و process.stderr.

في معظم الحالات، ليس من الضروري فعليًا الاستدعاء الصريح للتابع process.exit(‎)‎. سوف تنتهي عملية Node.js من تلقاء نفسها إذا لم يوجد أي عمل إضافي مُعلّق في حلقة الأحداث. يمكن أن تُضبط الخاصية process.exitCode لتُعلِم العملية أي حالة خروج عليها أن تُستخدَم عندما تنتهي العملية بأمان.

على سبيل المثال، يوضّح المثال التالي سوء استخدام للطريقة process.exit(‎)‎ والذي يمكن أن يقود إلى تقطيع وضياع البيانات المطبوعة إلى مجرى الخرج القياسي stdout.

// :هذا مثال على ما *لا* يجب فعله
if (someConditionNotMet()) {
  printUsageToStdout();
  process.exit(1);
}

الدافع إلى هذه الإشكالية هو بسبب أنّ الكتابة إلى process.stdout في Node.js تكون أحيانًا غير متزامنة ويمكن أن تحدث خلال عدة وحدات لحلقة أحداث Node.js. لكن استدعاء process.exit(‎)‎ يجبر العملية على الانتهاء قبل أن تُنجز تلك الكتابة الإضافية إلى مجرى الخرج القياسي stdout. بدلًا من استدعاء process.exit(‎)‎ مباشرةً، ينبغي ضبط رمز process.exitCode والسماح للعملية بإنهاء طبيعي من خلال تجنب جدولة أي عمل إضافي لحلقة الأحداث.

// كيف تُجهِّز حالة الخروج/الانتهاء بشكل صحيح بينما تسمح للعملية بالانتهاء بسلام
if (someConditionNotMet()) {
  printUsageToStdout();
  process.exitCode = 1;
}

إذا كان من الضروري إنهاء عملية Node.js بسبب حالة خطأ، فإنّ إلقاء خطأ غير مُلتقط والسماح للعملية بالإنهاء وفق ذلك هو أكثر أمانًا من استدعاء process.exit(‎)‎.

في خيوط Worker، توقف هذه الدالة الخيط الحالي بدلًا من العملية الحالية.

process.exitCode

أُضيفت في الإصدار: 0.11.8.

• <integer>

الرقم الذي سيكون حالة الخروج للعملية، إمّا عندما تنتهي العملية بسلام أو تُنهى بواسطة التابع process.exit(‎)‎ بدون تحديد حالة خروج.

تعيين حالة خروج للتابع process.exit(‎code‎)‎ سوف يتجاوز أي إعدادٍ سابق للخاصية process.exitCode.

process.getegid(‎)‎

أُضيف في الإصدار: 2.0.0.

يُعيد التابع process.getegid(‎)‎ المُعرِّف الرقمي للمجموعة الفعالة لعمليةNode.js ‎ (انظر ‎getegid(2‎)‎‎)

if (process.getegid) {
  console.log(`Current gid: ${process.getegid()}`);
}

تتوافر هذه الدالة فقط على منصات POSIX ( أي ليست ويندوز أو أندرويد).

process.geteuid(‎)‎

أُضيف هذا التابع في الإصدار: 2.0.0.

• القيمة المعادة: <Object>

يعيد التابع process.geteuid(‎)‎ المُعرِّف الرقمي للمستخدم الفعّال للعملية. ‎‎(انظر ‎ (geteuid‎(‎2‎‎‎‎)‎‎

if (process.geteuid) {
  console.log(`Current uid: ${process.geteuid()}`);
}

تتوافر هذه الدالة فقط على منصات POSIX (أي ليست ويندوز أو أندرويد).

process.getgid(‎)‎

أُضيف في الإصدار: 0.1.31.

• القيمة المعادة: <Object>.

يعيد التابع process.getgid(‎)‎ المُعرِّف الرقمي للمجموعة المالكة لعملية‎ .‎Node.js‎ ‎(انظر ‎(getgid‎(‎‎2‎‎)‎.

if (process.getgid) {
  console.log(`Current gid: ${process.getgid()}`);
}

تتوافر هذه الدالة فقط على منصات POSIX (أي ليست ويندوز أو أندرويد).

process.getgroups(‎)‎

أُضيف في الإصدار: 0.9.4.

القيمة المعادة: <[]integer>.

يعيد التابع process.getgroups(‎)‎ مصفوفةً مع المُعرِّف الرقمي للمجموعة المساعدة. تتركها POSIX غير محددة إذا كان معرّف المجموعة الفعّالة مُضمّنًا ولكن Node.js تضمن ذلك دائمًا.

تتوافر هذه الدالة فقط على منصات POSIX ( أي ليست ويندوز أو أندرويد).

process.getuid(‎)‎

أُضيف في الإصدار: 0.1.28.

القيمة المعادة: <integer>.

يعيد التابع process.getuid(‎)‎ المعرّف الرقمي لمستخدم العملية. (انظر(getuid(2).

if (process.getuid) {
  console.log(`Current uid: ${process.getuid()}`);
}

تتوافر هذه الدالة فقط على منصات POSIX ( أي ليست ويندوز أو أندرويد).

process.hasUncaughtExceptionCaptureCallback‎(‎)‎

أُضيف في الإصدار: 9.3.0.

• القيمة المعادة: <boolean>.

يحدد فيما إذا ضُبطت دالة رد النداء باستخدام process.setUncaughtExceptionCaptureCallback(‎)‎.

process.hrtime([time‎]‎)‎

أُضيف في الإصدار: 0.7.6.

• ‎‎<‎integer[]‎>‎‎ time: نتيجة الاستدعاء السابق للتابع process.hrtime(‎)‎.
• القيمة المعادة: <integer‎[‎]‎>.

هذا هو الإصدار القديم من ‎process.hrtime.bigint(‎)‎ قبل أن تُدخل bigint في JavaScript.

يعيد التابع process.hrtime(‎)‎ الزمن الحقيقي الحالي عالي الدقة على شكل مصفوفة بالصيغة [seconds, nanoseconds]، إذ إنَّ nanoseconds هو الجزء المتبقي من الزمن الحقيقي والذي لا يمكن تمثيله بدِقة الثواني.

time هو معامل اختياري والذي يجب أن يكون نتيجة الاستدعاء السابق للتابع process.hrtime(‎)‎ ليختلف عن الزمن الحالي. إذا لم يكن المعامل المُمرر مصفوفة غير قابلة للتعديل Array، سوف يُلقى خطأ مطبعي (TypeError). التمرير في مصفوفة معرّفة من قبل المستخدم بدلًا من نتيجة الاستدعاء السابق للتابع process.hrtime(‎)‎ سوف يقود إلى سلوك غير معرّف.

هذا الزمن هو نسبي إلى زمن اعتباطي في الماضي، وليس مرتبطًا بزمن اليوم ولذلك لا يخضع لحركة الساعة. الاستخدام الأساسي هو قياس الأداء بين الفترات:

const NS_PER_SEC = 1e9;
const time = process.hrtime();
// [ 1800216, 25 ]

setTimeout(() => {
  const diff = process.hrtime(time);
  // [ 1, 552 ]

  console.log(`Benchmark took ${diff[0] * NS_PER_SEC + diff[1]} nanoseconds`);
  // benchmark took 1000000552 nanoseconds //أخذ قياس الأداء 1000000552 نانو ثانية
}‎,‎ 1000‎)‎;‎