Node.js/util

صُمِّمَت الوحدة util بشكل أساسي لتلبية احتياجات واجهات Node.js البرمجيّة الداخليّة. هذا لا يمنَع كون الأدوات، التي توفرها الوحدة، مفُيدةً للتطبيقات ولمطوري الوحدات البرمجيّة. يمكنك استيراد الوحدة والبدء باستخدامها عبر تنفيذ:

const util = require('util');

util.callbackify(original)‎

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

• original‎:‏ <Function> دالة async‎ غير متزامنة.
• القيم المُعادة: <Function> دالةً من نمط دوال رد النداء (callback function).

يأخُذ التابِع الدالة async (أو دالة تُعيد كاِئنًا من النوع Promise) ويعيد دالةً تتبع نمط دالة رد النداء «الخطأ أولًا» (error-first callback)، مثل أخذ رد النداء ‎(err, value) => …‎ كآخر وسيط. في دالة رد النداء، الوسيط الأول سيعبِّر عن سبب الرفض (أو القيمة null‎ إن قُبِل الكائن Promise‎)، والوسيط الثاني سيكون القيمة المقبولة.

const util = require('util');

async function fn() {
  return 'hello world';
}
const callbackFunction = util.callbackify(fn);

callbackFunction((err, ret) => {
  if (err) throw err;
  console.log(ret);
});

ستطبع هذه الشيفرة عند تنفيذها الناتج التالي:

hello world

تنفَّذ دالة رد النداء بشكل غير متزامن، وستملك آنذاك تعقُّبَ مكدسٍ محدودٍ. إن رمت دالة رد النداء خطأً، فستُطلِق العملية الحدث 'uncaughtException'، وستخرج العملية إن لم يعالج. بما أنَّ القيمة null‎ لها معنًى خاص في كونها قيمةً للوسيط الأول في دالة رد النداء، فإن رفضَت دالةٌ محاطَةٌ (wrapped function) الكائن Project‎ مع قيمة خطأ (falsy value) بوصفها سببًا، فستُغلَّف القيمة بالخطأ Error‎ مع القيمة الأصلية المخزَّنة في حقلٍ يدعى reason‎.

function fn() {
  return Promise.reject(null);
}
const callbackFunction = util.callbackify(fn);

callbackFunction((err, ret) => {
  // Error غُلِّفت مع الخطأ ،'null' مع القيمة Promise عندما رُفِض الكائن
  // 'reason' وخُزِّنت القيمة الأصلية في
  err && err.hasOwnProperty('reason') && err.reason === null;  // true
});

util.debuglog(section)‎

أضيف في الإصدار: v0.11.3.

• section‎:‏ <string> سلسلة نصية تحدِّد الجزء الذي يجري إنشاء الدالة debuglog‎ من أجله في التطبيق.
• القيم المعادة: <Function> دالة تسجيل (logging function).

يستعمَل التابع util.debuglog()‎ لإنشاء دالةٍ تكتب رسائل خطأٍ بشكل شرطي في مجرى الخطأ القياسي (stderr) اعتمادًا على وجود متغير البيئة NODE_DEBUG‎. إن ظهر الاسم section‎ في قيمة متغير البيئة، فستعمل الدالة المعادة بشكل مشابه للتابع console.error()‎. أمَّا إن لم يظهر، فستنفِّذ الدالة المعادة حينئذٍ العمليَّة no-op (عمليَّة فارغة [no operation]).

const util = require('util');
const debuglog = util.debuglog('foo');

debuglog('hello from foo [%d]', 123);

إن شُغِّل هذا التطبيق مع ضبط متغير البيئة NODE_DEBUG‎ بالشكل NODE_DEBUG=foo‎، فسيُظهِر شيئًا شبيهًا بالناتج التالي:

FOO 3245: hello from foo [123]

يمثِّل العدد 3245‎ معرِّف العملية. وإن شُغِّل دون ضبط متغير البيئة، فلن يُطبَع آنذاك أي ناتج. يدعم الاسم section‎ محارف الصدفة الخاصَّة (wildcard ويشار إليها meta characters) أيضًا:

const util = require('util');
const debuglog = util.debuglog('foo-bar');

debuglog('hi there, it\'s foo-bar [%d]', 2333);

إن شُغِّل هذا التطبيق مع ضبط متغير البيئة بالشكل NODE_DEBUG=foo*‎، فسيطبع شيئًا شبيهًا بالناتج التالي:

FOO-BAR 3257: hi there, it's foo-bar [2333]

قد تُستعمَل عدة أسماء مفصولة بفاصلة مع setion‎ في متغير البيئة NODE_DEBUG‎ مثل NODE_DEBUG=fs,net,tls.

util.deprecate(fn, msg[, code])‎

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

الإصدار	التغييرات
v10.0.0	أصبحت تحذيرات الإهمال تُطلَق مرةً واحدةً فقط لكل شيفرة.
v0.8.0	أضيف هذا التابع.

• fn‎:‏ <Function> الدالة التي يجري إهمالها.
• msg:‏ <string> رسالة التحذير المراد إظهارها عندما تستدعى الدالة المهملة.
• code:‏ <string> الشيفرة المهملة.
• القيم المعادة: <Function> الدالة المهملة بعد تغليفها لإطلاق تحذير.

يغلف التابع util.deprecate()‎ الدالة (أو الصنف) fn‎ بطريقة تبدو فيها وكأنَّها مهملةٌ.

const util = require('util');

exports.obsoleteFunction = util.deprecate(() => {
  // افعل شيئًا هنا.
}, 'obsoleteFunction() is deprecated. Use newShinyFunction() instead.');

عندما تنفَّذ هذه الشيفرة ويستدعى التابع util.deprecate()‎، ستعيد دالةً تطلق التحذير DeprecationWarning‎ باستعمال الحدث 'warning'. سيُطلَق التحذير وسيُطبع على مجرى الخطأ القياسي (stderr) أول مرة تستدعى فيها الدالة المعادة. بعد أن يُطلَق التحذير، تُستدعَى الدالة المُغلَّفَة دون إطلاق تحذير. إن أعطيت الشيفرة code‎ الاختيارية نفسها في عدة استدعاءات إلى التابع util.deprecate()‎، فستُطلَق الاستدعاءات مرةً واحدةً فقط للشيفرة code‎ تلك.

const util = require('util');

const fn1 = util.deprecate(someFunction, someMessage, 'DEP0001');
const fn2 = util.deprecate(someOtherFunction, someOtherMessage, 'DEP0001');
fn1(); // DEP0001 إطلاق تحذير إهمال مع الرمز
fn2(); // لا يطلق هنا أي تحذير إهمال لأن هذه الدالة تملك الشيفرة نفسها للدالة السابقة

إن استعملت إمَّا الراية ‎--no-deprecation‎ أو الراية ‎--no-warnings‎ أو ضبطت الخاصية process.noDeprecation‎ إلى القيمة true‎ قبل إطلاق أول تحذير إهمال، فلن يفعل التابع util.deprecate()‎ أي شيء.

إن استعملت إمَّا الراية ‎--trace-deprecation‎ أو الراية ‎--trace-warnings‎ أو ضبطت الخاصية process.traceDeprecation إلى القيمة true‎، فستُطبَع التحذيرات وتعقبات المكدس (stack trace) على مجرى الخطأ القياسي (stderr) في المرة الأولى التي تستدعى فيها الدالة المهملة

إن استعملت الراية ‎--throw-deprecation‎ أو ضُبطَت الخاصية process.throwDeprecation‎ إلى القيمة true‎، فسيُرمَى استثناءٌ عندما تستدعَى الدالة المهملة.

إنَّ للراية ‎--throw-deprecation‎ والخاصية process.throwDeprecation‎ أولويةٌ على الراية ‎--trace-deprecation‎ والخاصية process.traceDeprecation‎.

util.format(format[, ...args])‎

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

الإصدار	التغييرات
v8.4.0	أصبح المحدِّدان ‎%‎o‎ و ‎%O‎ مدعومين الآن.
v0.5.3	أضيف هذا التابع.

• format‎:‏ <string> سلسلة تنسيق نصية تشبه التنسيق المستعمل في printf‎.

يعيد التابع util.format()‎ سلسلةً نصيةً منسَّقة باستعمال الوسيط الأول على أنَّه تنسيقٌ شبيهٌ بالتنسيق printf‎.

الوسيط الأول هو سلسلة نصية تحوي رموزًا نائبةً (placeholder tokens). يُستبدَل بكل رمز نائب القيمة المحوَّلة من الوسيط المقابل. الرموز النائبة المدعومة هي:

• ‎%s‎: سلسلة نصية.
• ‎%d: عددٌ صحيح أو عشري.
• ‎%i‎: عدد صحيح.
• ‎%f‎: عدد عشري.
• ‎%j‎: صيغة JSON. يستبدل بها السلسلة النصية '[Circular]' إن احتوى الوسيط على مراجع دائرية (circular references).
• ‎%o‎: كائنٌ. سلسلةٌ نصيةٌ ممثلةٌ لكائنٍ مع تنسيق الكائن العام في JavaScript. هذا يشبه التابع util.inspect()‎ مع الخيارات { showHidden: true, showProxy: true }‎. سيُظهر ذلك الكائن كاملًا من ضمنها الخاصيات والوسطاء (proxies) الغير قابلة للإحصاء (non-enumerable).
• ‎%O‎: كائنٌ. سلسلةٌ نصيةٌ ممثلةٌ لكائنٍ مع تنسيق الكائن العام في JavaScript. هذا يشبه التابع util.inspect()‎ دون خيارات. سيُظهر ذلك الكائن كاملًا باستثناء الخاصيات والوسطاء (proxies) الغير قابلة للإحصاء (non-enumerable).
• %%‎: إشارة مئوية واحدة ('%'). هذا لا يستهلك وسيطًا.
• القيم المعادة: <string> السلسلة النصية بعد تنسيقها.

إن لم يكن هنالك وسيطٌ مقابلٌ للرمز النائب المعطى، فسيُطبَع الرمز النائب دون استبدال.

util.format('%s:%s', 'foo');
// 'foo:%s' :سيُعاد

وإن كانت الوسائط المُمرَّرة إلى التابع util.format()‎ أكثرَ عددًا من الرموز النائبة، فستُحوَّل هذه الوسائط إلى سلاسل نصية ثمَّ تضاف إلى السلسلة النصية المعادة، إذ يُفصَل كل وسيط بفراغ. الوسائط الزائدة التي من النوع (أي يعطي استعمال typeof‎ معها) 'object' أو 'symbol' (باستثناء null‎) ستُحوَّل باستعمال التابع util.inspect()‎.

util.format('%s:%s', 'foo', 'bar', 'baz'); // 'foo:bar baz'

إن لم يكن الوسيط الأول سلسلةً نصيةً، فسيعيد التابع util.format()‎ حينئذٍ سلسلة نصية ناتجة عن جمع جميع الوسائط مع بعضها عبر فصل كلٍّ منها بفراغ، إذ يحوَّل آنذاك الوسيط إلى سلسلة نصية عبر التابع util.inspect()‎.

util.format(1, 2, 3); // '1 2 3'

إن مُرِّر وسيطٌ واحدٌ فقط إلى التابع util.format()‎، فسيُعاد الوسيط نفسه دون أي تنسيق.

util.format('%% %s'); // '%% %s'

انتبه إلى أنَّ التابع util.format()‎ هو تابعٌ متزامنٌ يستعمل بشكل أساسي كأداةٍ لتنقيح الأخطاء. يمكن أن تسبِّب بعض قيم المدخلات حملًا زائدًا كبيرًا على الأداء قد يحجب حلقة الأحداث (event loop)، لذا استعمل هذا التابع بحذر ولا تستعمله في مسارات الشيفرة التنفيذية (code execution paths وتدعى أيضًا hot code path).

util.formatWithOptions(inspectOptions, format[, ...args])‎

أضيف في الإصدار: v10.0.0.

• inspectOptions‎:‏ <Object>
• format:‏ <string>

هذا التابع ممائل تمامًا للتابع util.format()‎ باستثناء أنَّه يأخذ الوسيط inspectOptions‎ الذي يحدِّد الخيارات التي تُمرَّر إلى التابع util.inspect()‎.

util.formatWithOptions({ colors: true }, 'See object %O', { foo: 42 });
// إذ يلوَّن العدد '42' كعدد 'See object { foo: 42 }' ستعاد السلسلة
// عند طباعته على الطرفية

util.getSystemErrorName(err)‎

أضيف في الإصدار: v9.7.0.

• err‎:‏ <number>
• القيم المعادة: <string>

يعيد هذا التابع سلسلةً نصيةً تمثِّل اسم الخطأ ذا الرمز err‎ الناتج عن إحدى واجهات Node.js البرمجية. تعتمد عملية الربط بين رموز الأخطاء وأسمائها على المنصة المستعملة. اطلع على أسماء الأخطاء الشائعة في القسم «أخطاء النظام الشائعة».

fs.access('file/that/does/not/exist', (err) => {
  const name = util.getSystemErrorName(err.errno);
  console.error(name);  // ENOENT
});

util.inherits(constructor, superConstructor)‎

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

الإصدار	التغييرات
v5.0.0	أصبح بإمكان المعامل constructor أن يشير إلى الصنف ES6 الآن.
v0.3.0	أضيف هذا التابع.

• constructor‎:‏ <Function>
• superConstructor:‏ <Function>

استعمال التابع util.inherits()‎ غير موثوق. استعمل رجاءً الكلمات المفتاحية ES6 class‎ و extends‎ للحصول على دعمٍ للوراثة على مستوى اللغة. لاحظ أيضًا أن النمطين غير متوافقان دلاليًّا.

يورث هذا التابع التوابع prototype‎ من باني (constructor) لآخر. سيُضبَط prototype‎‎ للباني constructor‎ إلى الكائن الجديد المنشأ من الباني superConstructor‎.

للسهولة، سيكون الباني superConstructor‎ قابلًا للوصول عبر الخاصية constructor.super_‎.

const util = require('util');
const EventEmitter = require('events');

function MyStream() {
  EventEmitter.call(this);
}

util.inherits(MyStream, EventEmitter);

MyStream.prototype.write = function(data) {
  this.emit('data', data);
};

const stream = new MyStream();

console.log(stream instanceof EventEmitter); // true
console.log(MyStream.super_ === EventEmitter); // true

stream.on('data', (data) => {
  console.log(`Received data: "${data}"`);
});
stream.write('It works!'); // "It works!" :البيانات المستلمة

المثال التالي هو عن ES6 وكيفية استعمال الكلمتين المفتاحيتين class‎ و extends‎:

const EventEmitter = require('events');

class MyStream extends EventEmitter {
  write(data) {
    this.emit('data', data);
  }
}

const stream = new MyStream();

stream.on('data', (data) => {
  console.log(`Received data: "${data}"`);
});
stream.write('With ES6');

util.inspect(object[,options])‎ و util.inspect(object[, showHidden[, depth[, colors]]])‎

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

الإصدار	التغييرات
v10.6.0	أصبح فحص القوائم المرتبطة (linked lists) والكائنات المشابهة متاحًا الآن حتى حجم مكدِّس الاستدعاء الأقصى.
v10.0.0	يمكن الآن فحص المدخلتين WeakMap‎ و WeakSet‎.
v9.9.0	أصبح الخيار compact‎ مدعومًا الآن.
v6.6.0	تستطيع دوال الفحص المخصصة (custom inspection functions) الآن إعادة this‎.
v6.3.0	أصبح الخيار breakLength‎ مدعومًا الآن.
v6.1.0	أصبح الخيار maxArrayLength مدعومًا الآن. بعبارة أخرى، ستُقتطع الآن المصفوفات الطويلة بشكل افتراضي.
v6.1.0	أصبح الخيار showProxy مدعومًا الآن.
v0.3.0	أضيف هذا التابع.

• object:‏ <any> أي نوع أساسي من أنواع JavaScript أو كائن من النوع Object‎.
• options:‏ <Object>
  • showHidden:‏ <boolean> قيمة منطقية إن كانت true‎، فستُضمَّن رموز وخاصيات الكائن object‎ غير القابلة للإحصاء (non-enumerable) في السلسلة النصية المنسقة الناتجة بالإضافة إلى المدخلات WeakMap‎ و WeakSet‎. القيمة الافتراضية هي: false‎.
  • depth:‏ <number> يحدِّد عدد مرات التكرار (recurse) أثناء تنسيق الكائن object‎. هذا الخيار مفيدٌ مع الكائنات الكبيرة المعقدة. إن أردت أن تصل عمليات التكرار إلى حجم مكدس الاستدعاء الأقصى، فمرِّر القيمة Infinity‎ أو القيمة null‎ لهذا الخيار. القيمة الافتراضية هي: 2.
  • colors:‏ <boolean> قيمة منطقية إن كانت true‎، فستُنسَّق المخرجات بحسب معيار ANSI للألوان. اطلع على القسم «تخصيص الألوان» لمزيد من المعلومات حول تخصيص الألوان في التابع util.inspect. القيمة الافتراضية هي: false.
  • customInspect:‏ <boolean> قيمة منطقية إن كانت false، فلن تستدعى الدوال inspect(depth, opts)‎ المخصصة آنذاك. القيمة الافتراضية هي: true‎.
  • showProxy:‏ <boolean> قيمة منطقية إن كانت false‎، فستُفحَص (introspected) حينئذٍ الكائنات والدوال التي هي كائناتٌ من النوع Proxy‎ لإظهار الكائنات target‎ والكائنات handler‎ الخاصة بهم. القيمة الافتراضية هي: false‎.
  • maxArrayLength:‏ <number> يحدِّد عدد العناصر الأقصى للكائنات Array‎، و TypedArray‎، و WeakMap‎، و WeakSet‎ التي ستُشمَل في عملية التنسيق. إن أردت إظهار جميع العناصر، فاضبط هذا الخيار إلى القيمة null‎ أو القيمة Infinity‎. إن ضبط هذا الخيار إلى القيمة 0 أو أية قيمة سالبة، فلن يُظهَر أي عنصر. القيمة الافتراضية هي: 100.
  • breakLength:‏ <number> الطول الذي ستُجزَّأ عنده مفاتيح الكائن إلى عدة أسطر. إن ضبط هذا الخيار إلى القيمة Infinity‎، فسيُنسَّق الكائن على أنَّه سطرٌ واحدٌ. القيمة الافتراضية هي: 60 من أجل التوافقية الإرثية (legacy compatibility).
  • compact:‏ <boolean> يؤدي ضبط هذا الخيار إلى القيمة false‎ إلى تغيير القيمة الافتراضية للبادئة الفارغة المراد استعمالها لفصل الأسطر لكل مفتاح كائن عوضًا عن وضع عدة خاصيات في سطر واحد. سيُفصَل أيضًا النص الذي يزيد عن الحجم breakLength‎ إلى أجزاء أصغر وأفضل للقراءة بالإضافة إلى إزاحة الكائنات بشكل مماثل تمامًا للمصفوفات. انتبه إلى أنَّ أي جزء من النص لن يقل عن 16 محرف بغض النظر عن القيمة breakLength‎‎. لمزيد من المعلومات، تفحَّص المثال في الأسفل. القيمة الافتراضية هي: true‎.

• القيم المعادة: <string> سلسلة نصية تمثِّل الكائن المعطى.

يعيد التابع util.inspect()‎ سلسلةً نصيةً تمثِّل الوسيط object المعطى الذي يراد تنقيحه من الأخطاء (debugging). قد تتغيَّر مخرجات التابع util.inspect‎ في أي وقت ولا يجب الاعتماد عليها برمجيًا. قد تمرَّر الخيارات option‎ لضبط كيفية تنسيق السلسلة النصية من نواحٍ محدَّدة. سيستعمل التابع util.inspect()‎ اسم الباني و/أو ‎@@toStringTag‎ لإنشاء وسمٍ قابل للتعريف (identifiable tag) للقيمة الناتجة.

class Foo {
  get [Symbol.toStringTag]() {
    return 'bar';
  }
}

class Bar {}

const baz = Object.create(null, { [Symbol.toStringTag]: { value: 'foo' } });

util.inspect(new Foo()); // 'Foo [bar] {}'
util.inspect(new Bar()); // 'Bar {}'
util.inspect(baz);       // '[foo] {}'

يتفحَّص المثال التالي جميع خاصيات الكائن utile‎:

const util = require('util');

console.log(util.inspect(util, { showHidden: true, depth: null }));

قد تعطي القيم الدوال inspect(depth, opts)‎ المخصَّصة الخاصة بها، إذ يُمرَّر إليها عند استدعائها الخيار depth‎ في التفحُّص التكراري (recursive inspection) بالإضافة إلى الخيار options‎ الذي مُرِّر إلى التابع util.inspect()‎. يسلط المثال التالي الضوء على الخيار compact‎:

const util = require('util');

const o = {
  a: [1, 2, [[
    'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do ' +
      'eiusmod tempor incididunt ut labore et dolore magna aliqua.',
    'test',
    'foo']], 4],
  b: new Map([['za', 1], ['zb', 'test']])
};
console.log(util.inspect(o, { compact: true, depth: 5, breakLength: 80 }));

// { a:
//   [ 1,
//     2,
//     [ [ 'Lorem ipsum dolor sit amet, consectetur [...]', // A long line
//           'test',
//           'foo' ] ],
//     4 ],
//   b: Map { 'za' => 1, 'zb' => 'test' } }

// إلى تغيير المخرجات لتصبح أكثر قابلية للقراءة false إلى القيمة `compact` يؤدي ضبط الخيار
console.log(util.inspect(o, { compact: false, depth: 5, breakLength: 80 }));

// {
//   a: [
//     1,
//     2,
//     [
//       [
//         'Lorem ipsum dolor sit amet, consectetur ' +
//           'adipiscing elit, sed do eiusmod tempor ' +
//           'incididunt ut labore et dolore magna ' +
//           'aliqua.,
//         'test',
//         'foo'
//       ]
//     ],
//     4
//   ],
//   b: Map {
//     'za' => 1,
//     'zb' => 'test'
//   }
// }

// "Lorem ipsum" إلى قيمة مثل 150 سيؤدي إلى طباعة النص `breakLength` ضبط الخيار
// في سطر واحد
// إلى قطع أصغر "Lorem ipsum" سيتسبَّب في تقطيع النص `breakLength` تقليل قيمة الخيار

يسمح استعمال الخيار showHidden‎ بفحص المدخلات WeakMap‎ و WeakSet‎. إن كان هنالك مدخلات تزيد عن القيمة maxArrayLength‎، فلا يمكن معرفة أية مدخلات ستظهر. هذا يعني أنَّ استدعاء التابع util.inspect()‎ لجلب نفس مدخلات الكائن WeakSet‎ مرتين قد لا يعطي نفس النتيجة المتوقعة بل قد يعطي ناتجًا مختلفًا. أضف إلى ذلك أنَّ أي عنصر قد ينتقل إلى المهملات عبر مجمِّع المهملات (garbage collector) في أي لحظة من الزمن إن لم يبقى هنالك مرجعًا قويًا لذلك الكائن. بناءً على ذلك، ليس هنالك أي ضمان للحصول على نفس الناتج في كل مرة.

const { inspect } = require('util');

const obj = { a: 1 };
const obj2 = { b: 2 };
const weakSet = new WeakSet([obj, obj2]);

console.log(inspect(weakSet, { showHidden: true }));
// WeakSet { { a: 1 }, { b: 2 } }

انتبه إلى أنَّ التابع util.inspect()‎ هو تابعٌ متزامنٌ يُستعمَل بشكل أساسي كأداة لتنقيح الأخطاء. يمكن أن تسبِّب بعض قيم المدخلات حملًا زائدًا كبيرًا على الأداء قد يحجب حلقة الأحداث (event loop)، لذا استعمل هذا التابع بحذر ولا تستعمله في مسارات الشيفرة التنفيذية (code execution paths وتدعى أيضًا hot code path).

تخصيص الألوان في التابع util.inspect‎

يمكن تخصيص ألوان المخرجات (إن كانت مفعلة) في التابع util.inspect‎ على الصعيد العام (globally) عبر الخاصيتين util.inspect.styles‎ و util.inspect.colors‎.

الخاصية util.inspect.styles‎ هي خريطة (map) تربط اسم النمط (style name) باللون في الخاصية util.inspect.colors‎. الألوان الافتراضية المرتبطة بالأنماط هي:

• yellow‎ - number‎
• yellow‎ - boolean‎
• green‎ - string‎
• magenta‎ - date‎
• red‎ - ‎regexp
• ‎bold - null‎
• gray‎ - undefined‎
• ‎cyan - special‎ (لا تطبق على الدوال في الوقت الحالي.)
• name‎ - (لا يوجد لون)

رموز الألوان المعرَّفة مسبقًا هي: white‎، و gray، و black، و blue، و cyan، و green، و magenta، و red، و yellow. هنالك أيضًا الرموز bold‎، و italic، و underline، و inverse.

يستعمل نمط الألوان رموز تحكم ANSI التي قد لا تكون مدعومةً في جميع الطرفيات.

تخصيص دوال الفحص في الكائنات (Custom inspection functions on Objects)

قد تُعرِّف الكائنات دالةً من الشكل [util.inspect.custom](depth, opts)‎ (أو الدالة inspect(depth, opts)‎ المكافئة إلا أنَّها أصبحت مهملة) خاصة بها سيستدعيها التابع util.inspect()‎ ويستعمل الناتج الذي تعيده عند تفحُّص الكائن:

const util = require('util');

class Box {
  constructor(value) {
    this.value = value;
  }

  [util.inspect.custom](depth, options) {
    if (depth < 0) {
      return options.stylize('[Box]', 'special');
    }

    const newOptions = Object.assign({}, options, {
      depth: options.depth === null ? null : options.depth - 1
    });

    // "Box< " استعمال حاشية بمقدار خمسة فراغات لأن هذا هو حجم
    const padding = ' '.repeat(5);
    const inner = util.inspect(this.value, newOptions)
                      .replace(/\n/g, `\n${padding}`);
    return `${options.stylize('Box', 'special')}< ${inner} >`;
  }
}

const box = new Box(true);

util.inspect(box);
// "Box< true >" :سيُعاد

تعيد الدوال [util.inspect.custom](depth, opts)‎ المخصَّصة عادةً سلسلةً نصيةً ولكن قد تعيد قيمة ذات نوع آخر ستُنسَّق وفقًا لذك عبر التابع util.inspect()‎.

const util = require('util');

const obj = { foo: 'this will not show up in the inspect() output' };
obj[util.inspect.custom] = (depth) => {
  return { bar: 'baz' };
};

util.inspect(obj);
// "{ bar: 'baz' }" :سيُعاد

الخاصية util.inspect.custom‎

أضيفت في الإصدار: v6.6.0. تمثِّل هذه الخاصية قيمةً من النوع symbol‎ يمكن استعمالها للتصريح عن دوال فحص مخصَّصة. اطلع على القسم «تخصيص دوال الفحص في الكائنات» في الأعلى.

الخاصية util.inspect.defaultOptions

أضيفت في الإصدار: v6.4.0. تسمح القيمة defaultOptions‎ بتخصيص القيم الافتراضية للخيارات التي يستعملها التابع util.inspect‎. هذه الخاصية مفيدةٌ جدًا لتوابع مثل console.log‎ أو util.format‎ والتي تستدعي التابع util.inspect‎ ضمنيًّا. يجب أن تُضبَط إلى كائنٍ يحوي خيارًا واحدًا أو أكثر من خيارات التابع util.inspect()‎. يمكن أيضًا ضبط خاصيات الكائن options‎ مباشرةً.

const util = require('util');
const arr = Array(101).fill(0);

console.log(arr); // logs the truncated array
util.inspect.defaultOptions.maxArrayLength = null;
console.log(arr); // logs the full array

util.isDeepStrictEqual(val1, val2)‎

أضيف في الإصدار: v9.0.0.

• val1:‏ <any>
• val2:‏ <any>

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

يعيد هذا التابع القيمة true‎ إن كان الوسيطان val1‎ و val2‎ متساويين بالعمق وبشكل صارم. خلا ذلك، سيُعيِد القيمة false‎.

اطلع على توثيق التابع assert.deepStrictEqual()‎ لمزيد من المعلومات حول التساوي بالعمق وبشكل صارم.

util.promisify(original)‎

أضيف في الإصدار: v8.0.0.

• original:‏ <Function>
• القيم المعادة: <Function>

يأخذ هذا التابع دالةً تتبع نمط رد النداء «الخطأ أولًا» (error-first callback)، مثل أن تأخذ رد النداء ‎(err, value) => …‎ كآخر وسيط، ثم يعيد النسخة التي تعيد وعودًا (promises) من تلك الدالة.

const util = require('util');
const fs = require('fs');

const stat = util.promisify(fs.stat);
stat('.').then((stats) => {
  // `stats` افعل شيئًا مع
}).catch((error) => {
  // عالج الخطأ
});

أو يمكن بشكل مكافئ استعمال async function‎:

const util = require('util');
const fs = require('fs');

const stat = util.promisify(fs.stat);

async function callStat() {
  const stats = await stat('.');
  console.log(`This directory is owned by ${stats.uid}`);
}

إن كانت الخاصية original[util.promisify.custom]‎ موجودةً، فسيعيد التابع promisify‎ قيمتها. اطلع على الفقرة «دوال الوعود المخصصة» في الأسفل. يفترض التابع promisify()‎ أنَّ الوسيط original‎ هو دالةٌ يمرَّر رد نداءٍ كآخر وسيط إليها في جميع الحالات. إن لم يكن الوسيط original‎ دالةً، فسيرمي التابع promisify()‎ خطأً. أمَّا إن كان الوسيط original‎ دالةً ولكن لم يكن آخر وسيط فيه رد النداء «الخطأ أولًا»، فإنَّه لا يزال بالإمكان تمرير رد النداء «الخطأ أولًا» كآخر وسيط لها.

دوال الوعود المخصصة

استعمال الخاصية util.promisify.custom‎ يؤدي إلى استبدال القيمة المعادة للتابع util.promisify():

const util = require('util');

function doSomething(foo, callback) {
  // ...
}

doSomething[util.promisify.custom] = (foo) => {
  return getPromiseSomehow();
};

const promisified = util.promisify(doSomething);
console.log(promisified === doSomething[util.promisify.custom]);
// 'true' :سيُطبَع

يمكن أن يكون ذلك مفيدٌ في الحالات التي لا تتبع فيها الدالة الأصلية الصيغة القياسية لأخذ رد النداء «الخطأ أولًا» كآخر وسيط. على سبيل المثال، مع دالة تأخذ الوسائط (foo, onSuccessCallback, onErrorCallback)‎:

doSomething[util.promisify.custom] = (foo) => {
  return new Promise((resolve, reject) => {
    doSomething(foo, resolve, reject);
  });
};

إن عُرَّفت الخاصية promisify.custom‎ ولم تكن دالةً، فسيرمي التابع promisify()‎ خطأً.

الخاصية util.promisify.custom‎

أضيف في الإصدار: v8.0.0.

• <symbol>

تمثِّل هذه الخاصية رمزًا (symbol) يمكن استعماله للتصريح عن متغيرات الوعود المخصصة (custom promisified variants) للدوال.

الصنف util.TextDecoder‎

أضيف في الإصدار: v8.3.0.

يعدُّ هذا الصنف تنفيذًا للواجهة TextDecoder البرمجية للترميز القياسي المتوافق مع المعيار WHATWG.

const decoder = new TextDecoder('shift_jis');
let string = '';
let buffer;
while (buffer = getNextChunkSomehow()) {
  string += decoder.decode(buffer, { stream: true });
}
string += decoder.decode(); // نهاية المجرى

الترميزات المدعومة المتوافقة مع WHATWG

وفقًا للترميز القياسي المتوافق مع WHATWG، الترميزات المدعومة من قِبَل الواجهة TextDecoder‎ البرمجية مدرجةٌ في الجدوال الآتي. قد يُستعمَل اسمٌ بديلٌ واحدٌ أو أكثر لكل ترميز من هذه الترميزات.

تدعم إعدادات بُنيَات Node.js المختلفة مجموعات مختلفة للترميزات. لمَّا كانت المجموعة الأساسية للترميزات مدعومةً حتى في بنيات Node.js التي تُبنَى دون تفعيل ICU، فإنَّه يتوافر دعمٌ لبعض الترميزات عندما تبنَى Node.js مع تفعيل ICU واستعمال بيانات ICU الكاملة فقط (اطلع على هذه الصفحة لمزيد من المعلومات).

الترميزات المدعومة دون تفعيل ICU

الترميز	الأسماء البديلة
'utf-8'	'Unicode-1-1-utf-8'، و 'utf8'
'utf-16le'	'utf-16'

الترميزات المدعومة بشكل افتراضي (مع تفعيل ICU)

الترميز	الأسماء البديلة
'utf-8'	'unicode-1-1-utf-8'، و 'utf8'
'utf-16le'	'utf-16'
'utf-16be'

الترميزات التي تتطلب بيانات ICU الكاملة

الترميز	الأسماء البديلة
'ibm866'	'866'، و 'cp866'، و 'csibm866'
'iso-8859-2'	'csisolatin2'، و 'iso-ir-101'، و 'iso8859-2'، و 'iso88592'، و 'iso_8859-2'، و 'iso_8859-2:1987'، و 'l2'، و 'latin2'
'iso-8859-3'	'csisolatin3'، و 'iso-ir-109'، و 'iso8859-3'، و 'iso88593'، و 'iso_8859-3'، و 'iso_8859-3:1988'، و 'l3'، و 'latin3'
'iso-8859-4'	'csisolatin4'، و 'iso-ir-110'، و 'iso8859-4'، و 'iso88594'، و 'iso_8859-4'، و 'iso_8859-4:1988'، و 'l4'، و 'latin4'
'iso-8859-5'	'csisolatincyrillic'، و 'cyrillic'، و 'iso-ir-144'، و 'iso8859-5'، و 'iso88595'، و 'iso_8859-5'، و 'iso_8859-5:1988'
'iso-8859-6'	'arabic'، و 'asmo-708'، و 'csiso88596e'، و 'csiso88596i'، و 'csisolatinarabic'، و 'ecma-114'، و 'iso-8859-6-e'، و 'iso-8859-6-i'، و 'iso-ir-127'، و 'iso8859-6'، و 'iso88596'، و 'iso_8859-6'، و 'iso_8859-6:1987'
'iso-8859-7'	'csisolatingreek'، و 'ecma-118'، و 'elot_928'، و 'greek'، و 'greek8'، و 'iso-ir-126'، و 'iso8859-7'، و 'iso88597'، و 'iso_8859-7'، و 'iso_8859-7:1987'، و 'sun_eu_greek'
'iso-8859-8'	'csiso88598e'، و 'csisolatinhebrew'، و 'hebrew'، و 'iso-8859-8-e'، و 'iso-ir-138'، و 'iso8859-8'، و 'iso88598'، و 'iso_8859-8'، و 'iso_8859-8:1988'، و 'visual'
'iso-8859-8-i'	'csiso88598i'، و 'logical'
'iso-8859-10'	'csisolatin6'، و 'iso-ir-157'، و 'iso8859-10'، و 'iso885910'، و 'l6'، و 'latin6'
'iso-8859-13'	'iso8859-13'، و 'iso885913'
'iso-8859-14'	'iso8859-14'، و 'iso885914'
'iso-8859-15'	'csisolatin9'، و 'iso8859-15'، و 'iso885915'، و 'iso_8859-15'، و 'l9'
'koi8-r'	'cskoi8r'، و 'koi'، و 'koi8'، و 'koi8_r'
'koi8-u'	'koi8-ru'
'macintosh'	'csmacintosh'، و 'mac'، و 'x-mac-roman'
'windows-874'	'dos-874'، و 'iso-8859-11'، و 'iso8859-11'، و 'iso885911'، و 'tis-620'
'windows-1250'	'cp1250'، و 'x-cp1250'
'windows-1251'	'cp1251'، و 'x-cp1251'
'windows-1252'	'ansi_x3.4-1968'، و 'ascii'، و 'cp1252'، و 'cp819'، و 'csisolatin1'، و 'ibm819'، و 'iso-8859-1'، و 'iso-ir-100'، و 'iso8859-1'، و 'iso88591'، و 'iso_8859-1'، و 'iso_8859-1:1987'، و 'l1'، و 'latin1'، و 'us-ascii'، و 'x-cp1252'
'windows-1253'	'cp1253'، و 'x-cp1253'
'windows-1254'	'cp1254'، و 'csisolatin5'، و 'iso-8859-9'، و 'iso-ir-148'، و 'iso8859-9'، و 'iso88599'، و 'iso_8859-9'، و 'iso_8859-9:1989'، و 'l5'، و 'latin5'، و 'x-cp1254'
'windows-1255'	'cp1255'، و 'x-cp1255'
'windows-1256'	'cp1256'، و 'x-cp1256'
'windows-1257'	'cp1257'، و 'x-cp1257'
'windows-1258'	'cp1258'، و 'x-cp1258'
'x-mac-cyrillic'	'x-mac-ukrainian'
'gbk'	'chinese'، و 'csgb2312'، و 'csiso58gb231280'، و 'gb2312'، و 'gb_2312'، و 'gb_2312-80'، و 'iso-ir-58'، و 'x-gbk'
'gb18030'
'big5'	'big5-hkscs'، و 'cn-big5'، و 'csbig5'، و 'x-x-big5'
'euc-jp'	'cseucpkdfmtjapanese'، و 'x-euc-jp'
'iso-2022-jp'	'csiso2022jp'
'shift_jis'	'csshiftjis'، و 'ms932'، و 'ms_kanji'، و 'shift-jis'، و 'sjis'، و 'windows-31j'، و 'x-sjis'
'euc-kr'	'cseuckr'، و 'csksc56011987'، و 'iso-ir-149'، و 'korean'، و 'ks_c_5601-1987'، و 'ks_c_5601-1989'، و 'ksc5601'، و 'ksc_5601'، و 'windows-949'

الترميز 'iso-8859-16' المدرج في الترميز القياسي المتوافق مع WHATWG غير مدعوم.

new TextDecoder([encoding[, options]])‎

• encoding:‏ <string> يعرِّف الترميز الذي تدعمه النسخة TextDecoder‎. القيمة الافتراضية هي: 'utf-8'.
• options:‏ <Object>
  • fatal:‏ <boolean> قيمة منطقية تكون true‎ إذا كان فشل عملية فك الترميز فادحًا وخطيرًا (fatal). هذا الخيار مدعومٌ عندما يكون ICU مفعلًا فقط (اطلع على هذه الصفحة لمزيد من المعلومات). القيمة الافتراضية هي: false‎.
  • ignoreBOM:‏ <boolean> قيمة منطقية إن كانت true‎، سيتضمَّن الكائن TextDecoder‎ علامة ترتيب البايت (byte order mark) في البيانات الناتجة عن فك الترميز. أمَّا عندما تكون قيمة هذا الخيار false‎، ستُحذَف علامة ترتيب البايت من المخرجات. يستعمَل هذا الخيار عندما يكون الوسيط encoding‎ هو إمَّا 'utf-8'، أو 'utf-16be'، أو 'utf-16le'. القيمة الافتراضية هي: false‎.

تنشئ هذه الدالة نسخةً جديدةً من الصنف TextDecoder‎. قد يحدِّد الوسيط encoding‎ أحد الترميزات المدعومة أو الأسماء البديلة لها.

textDecoder.decode([input[, options]])‎

• input:‏ <ArrayBuffer‎> | <DataView> | <TypedArray> نسخةٌ من ArrayBuffer‎، أو DataView‎، أو TypedArray‎ تحوي البيانات المرمَّزة.
• options:‏ <Object>
  • stream:‏ <boolean> قيمة منطقية تكون true‎ إن كان يتوقع وجود أجزاء إضافية من البيانات. القيمة الافتراضية هي: false‎.
• القيم المعادة: <string>

يفك هذا التابع البيانات المعطاة في الترميز input‎ ثمَّ يعيدها في سلسلة نصية. إن كانت قيمة الخيار options.stream‎ هي true‎، فستُخزَّن أية سلسلة غير مكتملة من البايتات توجد في نهاية المدخلات input‎ داخليًّا ثم تُصدَر بعد الاستدعاء التالي للتابع textDecoder.decode()‎. إن كانت قيمة الخيار textDecoder.fatal‎ هي true‎، فسيؤدي حصول أي خطأ أثناء عملية فك الترميز إلى رمي الخطأ TypeError‎.

‎textDecoder.encoding

• <string>

تمثِّل هذه الخاصية الترميز الذي تدعمه النسخة TextDecoder‎.

‎textDecoder.fatal

• <boolean>

ستكون قيمة هذه الخاصية true‎ إن تمَّ رمي الخطأ TypeError‎ الناتج عن حصول أخطاء فادحة أثناء عملية فك الترميز.

‎textDecoder.ignoreBOM

• <boolean>

ستكون قيمة هذه الخاصية هي true‎ إن كان ناتج عملية فك الترميز سيتضمَّن علامة ترتيب البايت (byte order mark).

الصنف util.TextEncoder

أضيف في الإصدار: v8.3.0.

يعدُّ هذا الصنف تنفيذًا للواجهة TextEncoder البرمجية للترميز القياسي المتوافق مع المعيار WHATWG.

const encoder = new TextEncoder();
const uint8array = encoder.encode('this is some data');

textEncoder.encode([input])‎

• input‎:‏ النص المراد ترميزه. القيمة الافتراضية هي: سلسلة نصية فارغة.
• القيم المعادة: <Uint8Array>

يرمِّز هذا التابع البيانات المعطاة في الوسيط input‎ بالترميز UTF-8 ثم يعيد كائنًا من النوع Uint8Array‎ يحوي البايتات المرمَّزة.

textEncoder.encoding‎

• <string>

تمثِّل هذه الخاصية الترميز الذي تدعمه النسخة TextEncoder. تُضبَط إلى القيمة 'utf-8'.

util.types‎

أضيف في الإصدار: v10.0.0. يوفِّر util.types‎ عددًا من تحققات الأنواع (type checks) لمختلف أنواع الكائنات المضمَّنة (built-in objects) في اللغة. لا تفحص هذه التحققات، بشكل مخالف للمعامل instanceof‎ أو Object.prototype.toString.call(value)‎، خاصيات الكائن القابلة للوصول من طرف JavaScript (مثل فحص الخاصية prototype‎)، بل تجري عادةً استدعاءات زائدة داخل ++C. عمومًا، لا يقدِّم الناتج أي ضمانات عن ماهية نوع الخاصيات أو السلوك المتوقع لقيمةٍ ما في JavaScript. أكثر من يستفيد من هذه التحقُّقات هم مطورو الإضافات الذين يفضلون إجراء التحقق من النوع في JavaScript.

util.types.isArgumentsObject(value)‎

أضيف في الإصدار: v10.0.0.

• value‎:‏ <any>
• القيم المعادة: <boolean>

يعيد هذا التابع القيمة true‎ المنطقية إن كانت القيمة value‎ كائنًا من النوع arguments‎.

function foo() {
  util.types.isArgumentsObject(arguments);  // Returns true
}

util.types.isArrayBuffer(value)‎

أضيف في الإصدار: v10.0.0.

• value‎:‏ <any>
• القيم المعادة: <boolean>

يعيد هذا التابع القيمة true‎ المنطقية إن كانت القيمة value‎ نسخةً مضمَّنةً من النوع ArrayBuffer‎. هذا لا يتضمن النسخ SharedArrayBuffer‎. يفضَّل عادةً فحص كلاهما. انظر إلى الدالة util.types.isAnyArrayBuffer()‎ من أجل ذلك.

util.types.isArrayBuffer(new ArrayBuffer());  // true
util.types.isArrayBuffer(new SharedArrayBuffer());  // false

util.types.isAsyncFunction(value)‎

أضيف في الإصدار: v10.0.0.

• value‎:‏ <any>
• القيم المعادة: <boolean>

يعيد هذا التابع القيمة true‎ المنطقية إن كانت القيمة value‎ دالةً غير متزامنةً (async function). انتبه إلى أنَّ ناتج هذا التابع يعكس ما يراه محرِّك JavaScript؛ على وجه التحديد، قد لا تطابق القيمة المعادة الشيفرة المصدرية الأصلية إن استُعملَت الأداة transpilation.

util.types.isAsyncFunction(function foo() {});  // false
util.types.isAsyncFunction(async function foo() {});  // true

util.types.isBigInt64Array(value)‎

أضيف في الإصدار: v10.0.0.

• value‎:‏ <any>
• القيم المعادة: <boolean>

يعيد هذا التابع القيمة true‎ المنطقية إن كانت القيمة value‎ نسخةً من النوع BigInt64Array‎.

util.types.isBigInt64Array(new BigInt64Array()); // true util.types.isBigInt64Array(new BigUint64Array()); // false

util.types.isBigUint64Array(value)‎

أضيف في الإصدار: v10.0.0.

• value‎:‏ <any>
• القيم المعادة: <boolean>

يعيد هذا التابع القيمة true‎ المنطقية إن كانت القيمة value‎ نسخةً من النوع BigUint64Array‎.

util.types.isBigUint64Array(new BigInt64Array());   // false
util.types.isBigUint64Array(new BigUint64Array());  // true

util.types.isBooleanObject(value)‎

أضيف في الإصدار: v10.0.0.

• value‎:‏ <any>
• القيم المعادة: <boolean>

يعيد هذا التابع القيمة true‎ المنطقية إن كانت القيمة value‎ كائنًا من النوع boolean‎ (أنشئ عبر new Boolean()‎).

util.types.isBooleanObject(false);  // Returns false
util.types.isBooleanObject(true);   // false
util.types.isBooleanObject(new Boolean(false)); // true
util.types.isBooleanObject(new Boolean(true));  // true
util.types.isBooleanObject(Boolean(false)); // false
util.types.isBooleanObject(Boolean(true));  // false

util.types.isBoxedPrimitive(value)‎

أضيف في الإصدار: v10.0.0.

• value‎:‏ <any>
• القيم المعادة: <boolean>

يعيد هذا التابع القيمة true‎ المنطقية إن كانت القيمة value‎ أيًّا من الكائنات الأساسية المغلفة (boxed primitive object)، مثل تلك التي أنشأت باستعمال new Boolean()‎، أو new String()‎، أو Object(Symbol())‎. تفحَّص المثال التالي:

util.types.isBoxedPrimitive(false); // false
util.types.isBoxedPrimitive(new Boolean(false)); // true
util.types.isBoxedPrimitive(Symbol('foo')); // false
util.types.isBoxedPrimitive(Object(Symbol('foo'))); // true
util.types.isBoxedPrimitive(Object(BigInt(5))); // true

util.types.isDataView(value)‎

أضيف في الإصدار: v10.0.0.

• value‎:‏ <any>
• القيم المعادة: <boolean>

يعيد هذا التابع القيمة true‎ المنطقية إن كانت القيمة value‎ نسخةً مضمَّنةً من الصنف DataView‎.

const ab = new ArrayBuffer(20);
util.types.isDataView(new DataView(ab));  // true
util.types.isDataView(new Float64Array());  // false

انظر أيضًا التابع ArrayBuffer.isView()‎.

util.types.isDate(value)‎

أضيف في الإصدار: v10.0.0.

• value‎:‏ <any>
• القيم المعادة: <boolean>

يعيد هذا التابع القيمة true‎ المنطقية إن كانت القيمة value‎ نسخةً مضمَّنة من الصنف date‎.

util.types.isDate(new Date());  // true

util.types.isExternal(value)‎

أضيف في الإصدار: v10.0.0.

• value‎:‏ <any>
• القيم المعادة: <boolean>

يعيد هذا التابع القيمة true‎ المنطقية إن كانت القيمة value‎ قيمةً أساسيَّةً من النوع External‎.

util.types.isFloat32Array(value)‎

أضيف في الإصدار: v10.0.0.

• value‎:‏ <any>
• القيم المعادة: <boolean>

يعيد هذا التابع القيمة true‎ المنطقية إن كانت القيمة value‎ نسخةً مضمَّنة من الصنف Float32Array‎.

util.types.isFloat32Array(new ArrayBuffer());  // false
util.types.isFloat32Array(new Float32Array());  // true
util.types.isFloat32Array(new Float64Array());  // false

util.types.isFloat64Array(value)‎

أضيف في الإصدار: v10.0.0.

• value‎:‏ <any>
• القيم المعادة: <boolean>

يعيد هذا التابع القيمة true‎ المنطقية إن كانت القيمة value‎ نسخةً مضمَّنةً من الصنف Float64Array‎.

util.types.isFloat64Array(new ArrayBuffer());  // false
util.types.isFloat64Array(new Uint8Array());  // false
util.types.isFloat64Array(new Float64Array());  // true

util.types.isGeneratorFunction(value)‎

أضيف في الإصدار: v10.0.0.

• value‎:‏ <any>
• القيم المعادة: <boolean>

يعيد هذا التابع القيمة true‎ المنطقية إن كانت القيمة value‎ دالةً مولدةً (generator function). انتبه إلى أنَّ ناتج هذا التابع يعكس ما يراه محرِّك JavaScript. على وجهة التحديد، قد لا تطابق القيمة المعادة الشيفرة المصدرية الأصلية إن استُعملَت الأداة transpilation.

util.types.isGeneratorFunction(function foo() {});  // false
util.types.isGeneratorFunction(function* foo() {});  // true

‎util.types.isGeneratorObject(value)‎

أضيف في الإصدار: v10.0.0.

• value‎:‏ <any>
• القيم المعادة: <boolean>

يعيد هذا التابع القيمة true‎ المنطقية إن كانت القيمة value‎ كائنًا مولدًا (generator object) أعيد من دالة مولِّدة مضمَّنة. انتبه إلى أنَّ ناتج هذا التابع يعكس ما يراه محرِّك JavaScript. على وجهة التحديد، قد لا تطابق القيمة المعادة الشيفرة المصدرية الأصلية إن استُعملَت الأداة transpilation.

function* foo() {}
const generator = foo();
util.types.isGeneratorObject(generator);  // true

util.types.isInt8Array(value)‎

أضيف في الإصدار: v10.0.0.

• value‎:‏ <any>
• القيم المعادة: <boolean>

يعيد هذا التابع القيمة true‎ المنطقية إن كانت القيمة value‎ نسخةً مضمَّنةً من الصنف Int8Array‎.

util.types.isInt8Array(new ArrayBuffer());  // false
util.types.isInt8Array(new Int8Array());  // true
util.types.isInt8Array(new Float64Array());  // false

‎util.types.isInt16Array(value)‎

أضيف في الإصدار: v10.0.0.

• value‎:‏ <any>
• القيم المعادة: <boolean>

يعيد هذا التابع القيمة true‎ المنطقية إن كانت القيمة value‎ نسخةً مضمَّنةً من الصنف Int16Array‎.

util.types.isInt16Array(new ArrayBuffer());  // Returns false
util.types.isInt16Array(new Int16Array());  // Returns true
util.types.isInt16Array(new Float64Array());  // Returns false

util.types.isInt32Array(value)‎

أضيف في الإصدار: v10.0.0.

• value‎:‏ <any>
• القيم المعادة: <boolean>

يعيد هذا التابع القيمة true‎ المنطقية إن كانت القيمة value‎ نسخةً مضمَّنةً من الصنف Int32Array‎.

util.types.isInt32Array(new ArrayBuffer());  // false
util.types.isInt32Array(new Int32Array());  // true
util.types.isInt32Array(new Float64Array());  // false

util.types.isMap(value)‎

أضيف في الإصدار: v10.0.0.

• value‎:‏ <any>
• القيم المعادة: <boolean>

يعيد هذا التابع القيمة true‎ المنطقية إن كانت القيمة value‎ نسخةً مضمَّنةً من الصنف Map‎.

util.types.isMap(new Map());  // true

‎util.types.isMapIterator(value)‎

أضيف في الإصدار: v10.0.0.

• value‎:‏ <any>
• القيم المعادة: <boolean>

يعيد هذا التابع القيمة true‎ المنطقية إن كانت القيمة value‎ مكرِّرًا (iterator) أعيد من نسخةٍ مضمَّنةٍ من الكائن Map‎.

const map = new Map();
util.types.isMapIterator(map.keys());  // true
util.types.isMapIterator(map.values());  // true
util.types.isMapIterator(map.entries());  // true
util.types.isMapIterator(map[Symbol.iterator]());  // true

util.types.isModuleNamespaceObject(value)‎

أضيف في الإصدار: v10.0.0.

• value‎:‏ <any>
• القيم المعادة: <boolean>

يعيد هذا التابع القيمة true‎ المنطقية إن كانت القيمة value‎ نسخةً من كائن وحدة مجال الأسماء (Module Namespace).

import * as ns from './a.js';

util.types.isModuleNamespaceObject(ns);  // true

util.types.isNativeError(value)‎

أضيف في الإصدار: v10.0.0.

• value‎:‏ <any>
• القيم المعادة: <boolean>

يعيد هذا التابع القيمة true‎ المنطقية إن كانت القيمة value‎ نسخةً مضمَّنةً من الصنف Error‎.

util.types.isNativeError(new Error());  // true
util.types.isNativeError(new TypeError());  // true
util.types.isNativeError(new RangeError());  // true

util.types.isNumberObject(value)‎

أضيف في الإصدار: v10.0.0.

• value‎:‏ <any>
• القيم المعادة: <boolean>

يعيد هذا التابع القيمة true‎ المنطقية إن كانت القيمة value‎ كائنًا من النوع Number‎ (أنشيء باستعمال new Number()‎).

util.types.isNumberObject(0);  // false
util.types.isNumberObject(new Number(0));   // true

util.types.isPromise(value)‎

أضيف في الإصدار: v10.0.0.

• value‎:‏ <any>
• القيم المعادة: <boolean>

يعيد هذا التابع القيمة true‎ المنطقية إن كانت القيمة value‎ كائنًا من النوع Promise‎.

util.types.isPromise(Promise.resolve(42));  // true

util.types.isProxy(value)‎

أضيف في الإصدار: v10.0.0.

• value‎:‏ <any>
• القيم المعادة: <boolean>

يعيد هذا التابع القيمة true‎ المنطقية إن كانت القيمة value‎ نسخةً من الصنف Proxy‎.

const target = {};
const proxy = new Proxy(target, {});
util.types.isProxy(target);  // false
util.types.isProxy(proxy);  // true

‎util.types.isRegExp(value)‎

أضيف في الإصدار: v10.0.0.

• value‎:‏ <any>
• القيم المعادة: <boolean>

يعيد هذا التابع القيمة true‎ المنطقية إن كانت القيمة value‎ كائنًا من النوع RegExp‎.

util.types.isRegExp(/abc/);  // true
util.types.isRegExp(new RegExp('abc'));  // true

util.types.isSet(value)‎

أضيف في الإصدار: v10.0.0.

• value‎:‏ <any>
• القيم المعادة: <boolean>

يعيد هذا التابع القيمة true‎ المنطقية إن كانت القيمة value‎ نسخةً مضمَّنةً من الصنف Set‎.

util.types.isSet(new Set());  // true

util.types.isSetIterator(value)‎

أضيف في الإصدار: v10.0.0.

• value‎:‏ <any>
• القيم المعادة: <boolean>

يعيد هذا التابع القيمة true‎ المنطقية إن كانت القيمة value‎ مكرِّرًا أعيد من النسخة Set‎ المضمَّنة.

const set = new Set();
util.types.isSetIterator(set.keys());  // true
util.types.isSetIterator(set.values());  // true
util.types.isSetIterator(set.entries());  // true
util.types.isSetIterator(set[Symbol.iterator]());  // true

util.types.isSharedArrayBuffer(value)‎

أضيف في الإصدار: v10.0.0.

• value‎:‏ <any>
• القيم المعادة: <boolean>

يعيد هذا التابع القيمة true‎ المنطقية إن كانت القيمة value‎ نسخةً مضمَّنةً من الصنف SharedArrayBuffer‎. هذا لا يتضمَّن النُسَخ ArrayBuffer‎، لذا يفضَّل عادةً التحقق من كلاهما. اطلع على توثيق التابع util.types.isAnyArrayBuffer()‎ من أجل ذلك.

util.types.isSharedArrayBuffer(new ArrayBuffer());  // false
util.types.isSharedArrayBuffer(new SharedArrayBuffer());  // true

util.types.isStringObject(value)‎

أضيف في الإصدار: v10.0.0.

• value‎:‏ <any>
• القيم المعادة: <boolean>

يعيد هذا التابع القيمة true‎ المنطقية إن كانت القيمة value‎ كائنًا من النوع string‎ (أنشئ مثلًا عبر new String()‎).

util.types.isStringObject('foo');  // false
util.types.isStringObject(new String('foo'));   // true

‎util.types.isSymbolObject(value)‎

أضيف في الإصدار: v10.0.0.

• value‎:‏ <any>
• القيم المعادة: <boolean>

يعيد هذا التابع القيمة true‎ المنطقية إن كانت القيمة value‎ كائنًا من النوع Symbol‎ أُنشِيء عبر استدعاء Object()‎ مع الكائن Symbol‎ الأساسي.

const symbol = Symbol('foo');
util.types.isSymbolObject(symbol);  // false
util.types.isSymbolObject(Object(symbol));   // true

‎util.types.isTypedArray(value)‎

أضيف في الإصدار: v10.0.0.

• value‎:‏ <any>
• القيم المعادة: <boolean>

يعيد هذا التابع القيمة true‎ المنطقية إن كانت القيمة value‎ نسخةً مضمَّنةً من النوع TypedArray‎.

util.types.isTypedArray(new ArrayBuffer());  // false
util.types.isTypedArray(new Uint8Array());  // true
util.types.isTypedArray(new Float64Array());  // true

انظر أيضًا التابع ArrayBuffer.isView()‎.

util.types.isUint8Array(value)‎

أضيف في الإصدار: v10.0.0.

• value‎:‏ <any>
• القيم المعادة: <boolean>

يعيد هذا التابع القيمة true‎ المنطقية إن كانت القيمة value‎ نسخةً مضمَّنةً من النوع Uint8Array‎.

util.types.isUint8Array(new ArrayBuffer());  // false
util.types.isUint8Array(new Uint8Array());  // true
util.types.isUint8Array(new Float64Array());  // false

‎util.types.isUint8ClampedArray(value)‎

أضيف في الإصدار: v10.0.0.

• value‎:‏ <any>
• القيم المعادة: <boolean>

يعيد هذا التابع القيمة true‎ المنطقية إن كانت القيمة value‎ نسخةً مضمَّنةً من النوع Uint8ClampedArray.

util.types.isUint8ClampedArray(new ArrayBuffer());  // false
util.types.isUint8ClampedArray(new Uint8ClampedArray());  // true
util.types.isUint8ClampedArray(new Float64Array());  // false

util.types.isUint16Array(value)‎

أضيف في الإصدار: v10.0.0.

• value‎:‏ <any>
• القيم المعادة: <boolean>

يعيد هذا التابع القيمة true‎ المنطقية إن كانت القيمة value‎ نسخةً مضمَّنةً من النوع Uint16Array.

util.types.isUint16Array(new ArrayBuffer());  // false
util.types.isUint16Array(new Uint16Array());  // true
util.types.isUint16Array(new Float64Array());  // false

‎util.types.isUint32Array(value)‎

أضيف في الإصدار: v10.0.0.

• value‎:‏ <any>
• القيم المعادة: <boolean>

يعيد هذا التابع القيمة true‎ المنطقية إن كانت القيمة value‎ نسخةً مضمَّنةً من النوع Uint32Array.

util.types.isUint32Array(new ArrayBuffer());  // false
util.types.isUint32Array(new Uint32Array());  // true
util.types.isUint32Array(new Float64Array());  // false

‎util.types.isWeakMap(value)‎

أضيف في الإصدار: v10.0.0.

• value‎:‏ <any>
• القيم المعادة: <boolean>

يعيد هذا التابع القيمة true‎ المنطقية إن كانت القيمة value‎ نسخةً مضمَّنةً من النوع WeakMap.

util.types.isWeakMap(new WeakMap());  // true

util.types.isWeakSet(value)‎

أضيف في الإصدار: v10.0.0.

• value‎:‏ <any>
• القيم المعادة: <boolean>

يعيد هذا التابع القيمة true‎ المنطقية إن كانت القيمة value‎ نسخةً مضمَّنةً من النوع WeakSet.

util.types.isWeakSet(new WeakSet());  // true

util.types.isWebAssemblyCompiledModule(value)‎

أضيف في الإصدار: v10.0.0.

• value‎:‏ <any>
• القيم المعادة: <boolean>

يعيد هذا التابع القيمة true‎ المنطقية إن كانت القيمة value‎ نسخةً مضمَّنةً من النوع WebAssembly.Module‎.

const module = new WebAssembly.Module(wasmBuffer);
util.types.isWebAssemblyCompiledModule(module);  // Returns true

الواجهات البرمجية المهملة

أصبحت الواجهات البرمجية التالية مهملةً ولا يجب استخدامها مطلقًا بعد الآن. يجب على التطبيقات والوحدات التي تستعمل إحداها أن تستعيض عنها بالبديل المناسب.

util._extend(target, source)‎

أضيف في الإصدار: v0.7.5. أهمل منذ الإصدار: v6.0.0.

الاستقرار: 0-مهمل؛ استعمل التابع Object.assign()‎ عوضًا عنه.

• target:‏ <Object>
• source:‏ <Object>

لم يُقصَد أن يُستعمَل التابع util._extend()‎ خارج وحدات Node.js الداخلية على الإطلاق. على أي حال، المجتمع هو من أوجده واستعمله.

أصبح هذا التابع مهملًا ويجب ألا يُستعمَل بعد الآن في أي شيفرة. تأتي JavaScript مع وظائف مدمجة مشابهة عبر Object.assign()‎.

‎util.debug(string)‎

أضيف في الإصدار: v0.3.0. أهمل منذ الإصدار: v0.11.3.

الاستقرار: 0-مهمل؛ استعمل التابع console.error()‎ عوضًا عنه.

• string:‏ <string> الرسالة المراد طباعتها على مجرى الخطأ القياسي (stderr).

سلفٌ مهملٌ للتابع console.error‎.

util.error([...strings])‎

أضيف في الإصدار: v0.3.0. أهمل منذ الإصدار: 0.11.3.

الاستقرار: 0-مهمل؛ استعمل التابع console.error()‎ عوضًا عنه.

• ...strings:‏ <string> الرسالة المراد طباعتها على مجرى الخطأ القياسي (stderr).

سلفٌ مهملٌ للتابع console.error‎.

util.isArray(object)‎

أضيف في الإصدار: v0.6.0. أهمل منذ الإصدار: v4.0.0.

الاستقرار: 0-مهمل؛ استعمل التابع Array.isArray()‎ عوضًا عنه.

• object:‏ <any>
• القيم المعادة: <boolean>

يعدُّ هذا التابع اسمًا بديلًا للتابع Array.isArray()‎.

يعيد هذا التابع القيمة true‎ المنطقية إن كان الكائن object المعطى مصفوفةً. خلا ذلك، سيعيد القيمة false‎.

const util = require('util');

util.isArray([]);
// Returns: true
util.isArray(new Array());
// Returns: true
util.isArray({});
// Returns: false

util.isBoolean(object)‎

أضيف في الإصدار: v0.11.5. أهمل منذ الإصدار: v4.0.0.

الاستقرار: 0-مهمل؛ استعمل typeof value === 'boolean'‎ عوضًا عنه.

• object:‏ <any>
• القيم المعادة: <boolean>

يعيد هذا التابع القيمة true‎ المنطقية إن كان الكائن object المعطى قيمةً منطقيةً (boolean). خلا ذلك، سيعيد القيمة false‎.

const util = require('util');

util.isBoolean(1);      // false
util.isBoolean(0);      // false
util.isBoolean(false); // true

util.isBuffer(object)‎

أضيف في الإصدار: v0.11.5. أهمل منذ الإصدار: v4.4.0. الاستقرار: 0-مهمل؛ استعمل التابع Buffer.isBuffer()‎ عوضًا عنه.

• object:‏ <any>
• القيم المعادة: <boolean>

يعيد هذا التابع القيمة true‎ المنطقية إن كان الكائن object المعطى من النوع Buffer‎. خلا ذلك، سيعيد القيمة false‎.

const util = require('util');

util.isBuffer({ length: 0 }); // false
util.isBuffer([]); // false
util.isBuffer(Buffer.from('hello world')); // true

util.isDate(object)‎

أضيف في الإصدار: v0.6.0. أهمل منذ الإصدار: v4.0.0. الاستقرار: 0-مهمل؛ استعمل التابع util.types.isDate()‎ عوضًا عنه.

• object:‏ <any>
• القيم المعادة: <boolean>

يعيد هذا التابع القيمة true‎ المنطقية إن كان الكائن object المعطى من النوع Date‎.

const util = require('util');

util.isDate(new Date()); // true
util.isDate(Date()); // false (سلسلةً نصيةً 'new' تعيد دون)
util.isDate({}); // false

util.isError(object)‎

أضيف في الإصدار: v0.6.0. أهمل منذ الإصدار: v4.0.0. الاستقرار: 0-مهمل؛ استعمل التابع util.types.isNativeError()‎ عوضًا عنه.

• object:‏ <any>
• القيم المعادة: <boolean>

يعيد هذا التابع القيمة true‎ المنطقية إن كان الكائن object المعطى من النوع Error. خلا ذلك، سيعيد القيمة false‎.

const util = require('util');

util.isError(new Error()); // true
util.isError(new TypeError()); // true
util.isError({ name: 'Error', message: 'an error occurred' }); // false

انتبه إلى أنَّ هذا التابع يعتمد على السلوك Object.prototype.toString()‎. يحتمل الحصول على نتيجة خطأ عندما يتحكم الوسيط object‎ في ‎@@toStringTag‎.

const util = require('util');
const obj = { name: 'Error', message: 'an error occurred' };

util.isError(obj); // false
obj[Symbol.toStringTag] = 'Error';
util.isError(obj); // true

util.isFunction(object)‎

أضيف في الإصدار: v0.11.5. أهمل منذ الإصدار: v4.0.0. الاستقرار: 0-مهمل؛ استعمل typeof value === 'function'‎ عوضًا عنه.

• object:‏ <any>
• القيم المعادة: <boolean>

يعيد هذا التابع القيمة true‎ المنطقية إن كان الكائن object المعطى دالةً. خلا ذلك، سيعيد القيمة false‎.

const util = require('util');

function Foo() {}
const Bar = () => {};

util.isFunction({}); // false
util.isFunction(Foo); // true
util.isFunction(Bar); // true

util.isNull(object)‎

أضيف في الإصدار: v0.11.5. أهمل منذ الإصدار: v4.0.0. الاستقرار: 0-مهمل؛ استعمل value === null عوضًا عنه.

• object:‏ <any>
• القيم المعادة: <boolean>

يعيد هذا التابع القيمة true‎ المنطقية إن كان الكائن object المعطى يساوي القيمة null‎ بشكل صارم (strictly). خلا ذلك، سيعيد القيمة false‎.

const util = require('util');

util.isNull(0); // false
util.isNull(undefined); // false
util.isNull(null); // true

util.isNullOrUndefined(object)‎

أضيف في الإصدار: v0.11.5. أهمل منذ الإصدار: v4.0.0. الاستقرار: 0-مهمل؛ استعمل value === undefined || value === null‎ عوضًا عنه.

• object:‏ <any>
• القيم المعادة: <boolean>

يعيد هذا التابع القيمة true‎ المنطقية إن كان الكائن object المعطى هو null‎ أو undefined‎. خلا ذلك، سيعيد القيمة false‎.

const util = require('util');

util.isNullOrUndefined(0); // false
util.isNullOrUndefined(undefined); // true
util.isNullOrUndefined(null); // true

util.isNumber(object)‎

أضيف في الإصدار: v0.11.5. أهمل منذ الإصدار: v4.0.0.

الاستقرار: 0-مهمل؛ استعمل typeof value === 'number'‎ عوضًا عنه.

• object:‏ <any>
• القيم المعادة: <boolean>

يعيد هذا التابع القيمة true‎ المنطقية إن كان الكائن object المعطى عددًا (Number). خلا ذلك، سيعيد القيمة false‎.

const util = require('util');

util.isNumber(false); // false
util.isNumber(Infinity); // true
util.isNumber(0); // true
util.isNumber(NaN); // true

util.isObject(object)‎

أضيف في الإصدار: v0.11.5. أهمل منذ الإصدار: v4.0.0.

الاستقرار: 0-مهمل؛ استعمل value !== null && typeof value === 'object'‎ عوضًا عنه.

• object:‏ <any>
• القيم المعادة: <boolean>

يعيد هذا التابع القيمة true‎ المنطقية إن كان الكائن object المعطى هو من النوع Object‎ حتمًا وليس من دالةً (Function، رغم أنَّ الدوال هي كائنات في JavaScript). خلا ذلك، ستعيد القيمة false‎.

const util = require('util');

util.isObject(5); // false
util.isObject(null); // false
util.isObject({}); // true
util.isObject(() => {}); // false

util.isPrimitive(object)‎

أضيف في الإصدار: v0.11.5. أهمل منذ الإصدار: v4.0.0.

الاستقرار: 0-مهمل؛ استعمل ‎(typeof value !== 'object' && typeof value !== 'function') || value === null عوضًا عنه.

• object:‏ <any>
• القيم المعادة: <boolean>

يعيد هذا التابع القيمة true‎ المنطقية إن كان الكائن object المعطى أحدَ الأنواع الأساسية (primitive type). خلا ذلك، سيعيد القيمة false‎.

const util = require('util');

util.isPrimitive(5); // true
util.isPrimitive('foo'); // true
util.isPrimitive(false); // true
util.isPrimitive(null); // true
util.isPrimitive(undefined); // true
util.isPrimitive({}); // false
util.isPrimitive(() => {}); // false
util.isPrimitive(/^$/); // false
util.isPrimitive(new Date()); // false

util.isRegExp(object)‎

أضيف في الإصدار: v0.6.0. أهمل منذ الإصدار: v4.0.0. الاستقرار: 0-مهمل.

• object:‏ <any>
• القيم المعادة: <boolean>

يعيد هذا التابع القيمة true‎ المنطقية إن كان الكائن object المعطى من النوع RegExp‎. خلا ذلك، سيعيد القيمة false‎.

const util = require('util');

util.isRegExp(/some regexp/); // true
util.isRegExp(new RegExp('another regexp')); // true
util.isRegExp({}); // false

‎util.isString(object)‎

أضيف في الإصدار: v0.11.5. أهمل منذ الإصدار: v4.0.0.

الاستقرار: 0-مهمل؛ استعمل ‎typeof value === 'string'‎ عوضًا عنه.

• object:‏ <any>
• القيم المعادة: <boolean>

يعيد هذا التابع القيمة true‎ المنطقية إن كان الكائن object المعطى سلسلة نصية (String). خلا ذلك، سيعيد القيمة false‎.

const util = require('util');

util.isString(''); // true
util.isString('foo'); // true
util.isString(String('foo')); // true
util.isString(5); // false

util.isSymbol(object)‎

أضيف في الإصدار: v0.11.5. أهمل منذ الإصدار: v4.0.0.

الاستقرار: 0-مهمل؛ استعمل typeof value === 'symbol'‎ عوضًا عنه.

• object:‏ <any>
• القيم المعادة: <boolean>

يعيد هذا التابع القيمة true‎ المنطقية إن كان الكائن object المعطى من النوع Symbol‎. خلا ذلك، سيعيد القيمة false‎.

const util = require('util');

util.isSymbol(5); // false
util.isSymbol('foo'); // false
util.isSymbol(Symbol('foo')); // true

‎util.isUndefined(object)‎

أضيف في الإصدار: v0.11.5. أهمل منذ الإصدار: v4.0.0.

الاستقرار: 0-مهمل؛ استعمل value === undefined عوضًا عنه.

• object:‏ <any>
• القيم المعادة: <boolean>

يعيد هذا التابع القيمة true‎ المنطقية إن كان الكائن object المعطى هو undefined‎. خلا ذلك، سيعيد القيمة false‎.

const util = require('util');

const foo = undefined;
util.isUndefined(5); // false
util.isUndefined(foo); // true
util.isUndefined(null); // false

util.log(string)‎

أضيف في الإصدار: v0.3.0. أهمل منذ الإصدار: v6.0.0. الاستقرار: 0-مهمل؛ استعمل وحدة مُقدَّمة من طرف ثالث عوضًا عنه.

• string:‏ <string>

يطبع التابع util.log()‎ السلسلة النصية string‎ المعطاة على مجرى الخرج القياسي (stdout) مع إضافة بصمة وقت.

const util = require('util');

util.log('Timestamped message.');

util.print([...strings])‎

أضيف في الإصدار: v0.3.0. أهمل منذ الإصدار: v0.11.3.

الاستقرار: 0-مهمل؛ استعمل التابع console.log()‎ عوضًا عنه.

سلفٌ مهملٌ للتابع console.log‎.

util.puts([...strings])‎

أضيف في الإصدار: v0.11.3. أهمل منذ الإصدار: v0.11.3.

الاستقرار: 0-مهمل؛ استعمل التابع ‎console.log()‎ عوضًا عنه.

سلفٌ مهملٌ للتابع console.log‎.

مصادر

• صفحة util في توثيق Node.js الرسمي.