util module

يستمع إلى حدث إحباط على signal المقدمة ويرجع وعدا يتم الوفاء به عند إجهاض signal. إذا كان resource الذي تم تمريره عبارة عن قمامة تم جمعها قبل إجهاض signal، يبقى الوعد الذي تم إرجاعه معلقا إلى أجل غير مسمى.

import { aborted } from 'node:util';

const dependent = obtainSomethingAbortable();

aborted(dependent.signal, dependent).then(() => {
  // Do something when dependent is aborted.
});

dependent.on('event', () => {
  dependent.abort();
});

function aborted(signal: AbortSignal, resource: any): Promise<void>

المعلمات

المرتجعات

إضافة معلمة إلى عنوان url المحدد

function addParamToUrl(url: string, paramName: string, value: string): string

المعلمات

المرتجعات

نسخ قيم كافة الخصائص القابلة للتعداد من كائن مصدر واحد أو أكثر إلى كائن هدف، وإرجاع الكائن الهدف.

function assign(args: any[]): any

المعلمات

المرتجعات

التحقق من احتواء عنوان url المضمن على autoAuth=true.

function autoAuthInEmbedUrl(embedUrl: string): boolean

المعلمات

المرتجعات

تأخذ دالة async (أو دالة ترجع Promise) وترجع دالة باتباع نمط رد الاتصال الأول للخطأ، أي أخذ رد اتصال (err, value) => ... كوسيطة أخيرة. في رد الاتصال، ستكون الوسيطة الأولى هي سبب الرفض (أو null إذا تم حل Promise)، وستكون الوسيطة الثانية هي القيمة التي تم حلها.

const util = require('node: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 له معنى خاص باعتباره الوسيطة الأولى لرد الاتصال، إذا رفضت دالة ملفوفة Promise بقيمة مزيفة لسبب ما، يتم التفاف القيمة في Error بالقيمة الأصلية المخزنة في حقل يسمى reason.

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

callbackFunction((err, ret) => {
  // When the Promise was rejected with `null` it is wrapped with an Error and
  // the original value is stored in `reason`.
  err && Object.hasOwn(err, 'reason') && err.reason === null;  // true
});

function callbackify(fn: () => Promise<void>): (callback: (err: NodeJS.ErrnoException) => void) => void

المعلمات

المرتجعات

دالة نمط رد الاتصال

function callbackify<T1, T2, T3, T4, T5, T6, TResult>(fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5, arg6: T6) => Promise<TResult>): (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5, arg6: T6, callback: (err: NodeJS.ErrnoException | null, result: TResult) => void) => void

المعلمات

المرتجعات

function callbackify<T1, T2, T3, T4, T5, T6>(fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5, arg6: T6) => Promise<void>): (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5, arg6: T6, callback: (err: NodeJS.ErrnoException) => void) => void

المعلمات

المرتجعات

function callbackify<T1, T2, T3, T4, T5, TResult>(fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5) => Promise<TResult>): (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5, callback: (err: NodeJS.ErrnoException | null, result: TResult) => void) => void

المعلمات

المرتجعات

function callbackify<T1, T2, T3, T4, T5>(fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5) => Promise<void>): (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5, callback: (err: NodeJS.ErrnoException) => void) => void

المعلمات

المرتجعات

function callbackify<T1, T2, T3, T4, TResult>(fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4) => Promise<TResult>): (arg1: T1, arg2: T2, arg3: T3, arg4: T4, callback: (err: NodeJS.ErrnoException | null, result: TResult) => void) => void

المعلمات

المرتجعات

function callbackify<T1, T2, T3, T4>(fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4) => Promise<void>): (arg1: T1, arg2: T2, arg3: T3, arg4: T4, callback: (err: NodeJS.ErrnoException) => void) => void

المعلمات

المرتجعات

function callbackify<T1, T2, T3, TResult>(fn: (arg1: T1, arg2: T2, arg3: T3) => Promise<TResult>): (arg1: T1, arg2: T2, arg3: T3, callback: (err: NodeJS.ErrnoException | null, result: TResult) => void) => void

المعلمات

المرتجعات

function callbackify<T1, T2, T3>(fn: (arg1: T1, arg2: T2, arg3: T3) => Promise<void>): (arg1: T1, arg2: T2, arg3: T3, callback: (err: NodeJS.ErrnoException) => void) => void

المعلمات

المرتجعات

function callbackify<T1, T2, TResult>(fn: (arg1: T1, arg2: T2) => Promise<TResult>): (arg1: T1, arg2: T2, callback: (err: NodeJS.ErrnoException | null, result: TResult) => void) => void

المعلمات

المرتجعات

function callbackify<T1, T2>(fn: (arg1: T1, arg2: T2) => Promise<void>): (arg1: T1, arg2: T2, callback: (err: NodeJS.ErrnoException) => void) => void

المعلمات

المرتجعات

function callbackify<T1, TResult>(fn: (arg1: T1) => Promise<TResult>): (arg1: T1, callback: (err: NodeJS.ErrnoException, result: TResult) => void) => void

المعلمات

المرتجعات

function callbackify<T1>(fn: (arg1: T1) => Promise<void>): (arg1: T1, callback: (err: NodeJS.ErrnoException) => void) => void

المعلمات

المرتجعات

function callbackify<TResult>(fn: () => Promise<TResult>): (callback: (err: NodeJS.ErrnoException, result: TResult) => void) => void

المعلمات

المرتجعات

إنشاء سلسلة أحرف عشوائية من 5 إلى 6 أحرف.

function createRandomString(): string

المرتجعات

يتم استخدام الأسلوب util.debuglog() لإنشاء دالة تكتب رسائل تتبع الأخطاء بشكل مشروط إلى stderr استنادا إلى وجود متغير البيئة NODE_DEBUG. إذا ظهر اسم section ضمن قيمة متغير البيئة هذا، فإن الدالة التي تم إرجاعها تعمل بشكل مشابه console.error(). إذا لم يكن الأمر كما هو، فإن الدالة التي تم إرجاعها هي no-op.

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

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

إذا تم تشغيل هذا البرنامج مع NODE_DEBUG=foo في البيئة، فسيخرج شيئا مثل:

FOO 3245: hello from foo [123]

حيث 3245 هو معرف العملية. إذا لم يتم تشغيله مع مجموعة متغيرات البيئة هذه، فلن يطبع أي شيء.

يدعم section أحرف البدل أيضا:

const util = require('node: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]

قد يتم تحديد أسماء section متعددة مفصولة بفواصل في متغير البيئة NODE_DEBUG: NODE_DEBUG=fs,net,tls.

يمكن استخدام الوسيطة الاختيارية callback لاستبدال دالة التسجيل بدالة مختلفة لا تحتوي على أي تهيئة أو التفاف غير ضروري.

const util = require('node:util');
let debuglog = util.debuglog('internals', (debug) => {
  // Replace with a logging function that optimizes out
  // testing if the section is enabled
  debuglog = debug;
});

function debug(section: string, callback?: (fn: DebugLoggerFunction) => void): DebugLogger

المعلمات

المرتجعات

دالة التسجيل

يتم استخدام الأسلوب util.debuglog() لإنشاء دالة تكتب رسائل تتبع الأخطاء بشكل مشروط إلى stderr استنادا إلى وجود متغير البيئة NODE_DEBUG. إذا ظهر اسم section ضمن قيمة متغير البيئة هذا، فإن الدالة التي تم إرجاعها تعمل بشكل مشابه console.error(). إذا لم يكن الأمر كما هو، فإن الدالة التي تم إرجاعها هي no-op.

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

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

إذا تم تشغيل هذا البرنامج مع NODE_DEBUG=foo في البيئة، فسيخرج شيئا مثل:

FOO 3245: hello from foo [123]

حيث 3245 هو معرف العملية. إذا لم يتم تشغيله مع مجموعة متغيرات البيئة هذه، فلن يطبع أي شيء.

يدعم section أحرف البدل أيضا:

const util = require('node: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]

قد يتم تحديد أسماء section متعددة مفصولة بفواصل في متغير البيئة NODE_DEBUG: NODE_DEBUG=fs,net,tls.

يمكن استخدام الوسيطة الاختيارية callback لاستبدال دالة التسجيل بدالة مختلفة لا تحتوي على أي تهيئة أو التفاف غير ضروري.

const util = require('node:util');
let debuglog = util.debuglog('internals', (debug) => {
  // Replace with a logging function that optimizes out
  // testing if the section is enabled
  debuglog = debug;
});

function debuglog(section: string, callback?: (fn: DebugLoggerFunction) => void): DebugLogger

المعلمات

المرتجعات

دالة التسجيل

يلتف أسلوب util.deprecate()fn (التي قد تكون دالة أو فئة) بطريقة يتم وضع علامة عليها على أنها مهملة.

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

exports.obsoleteFunction = util.deprecate(() => {
  // Do something here.
}, 'obsoleteFunction() is deprecated. Use newShinyFunction() instead.');

عند استدعاؤها، سيعيد util.deprecate() دالة ستبعث DeprecationWarning باستخدام الحدث 'warning'. سيتم إصدار التحذير وطباعته إلى stderr في المرة الأولى التي يتم فيها استدعاء الدالة التي تم إرجاعها. بعد إصدار التحذير، يتم استدعاء الدالة الملتفة دون إصدار تحذير.

إذا تم توفير نفس code الاختيارية في استدعاءات متعددة إلى util.deprecate()، إصدار التحذير مرة واحدة فقط لذلك code.

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

const fn1 = util.deprecate(someFunction, someMessage, 'DEP0001');
const fn2 = util.deprecate(someOtherFunction, someOtherMessage, 'DEP0001');
fn1(); // Emits a deprecation warning with code DEP0001
fn2(); // Does not emit a deprecation warning because it has the same code

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

إذا تم تعيين علامات سطر الأوامر --trace-deprecation أو --trace-warnings، أو تم تعيين الخاصية process.traceDeprecation إلى true، تتم طباعة تحذير وتتبع مكدس إلى stderr في المرة الأولى التي يتم فيها استدعاء الدالة المهملة.

إذا تم تعيين علامة سطر الأوامر --throw-deprecation، أو تم تعيين الخاصية process.throwDeprecation إلى true، طرح استثناء عند استدعاء الدالة المهملة.

علامة سطر الأوامر --throw-deprecation وخاصية process.throwDeprecation لها الأسبقية على --trace-deprecationprocess.traceDeprecation.

function deprecate<T>(fn: T, msg: string, code?: string): T

المعلمات

المرتجعات

الدالة المهملة الملتفة لإرسال تحذير.

البحث عن القيمة الأولى في صفيف يطابق دالة التقييم المحددة.

function find<T>(predicate: (x: T) => boolean, xs: T[]): T

المعلمات

المرتجعات

البحث عن فهرس القيمة الأولى في صفيف يطابق دالة التقييم المحددة.

function findIndex<T>(predicate: (x: T) => boolean, xs: T[]): number

المعلمات

المرتجعات

يقوم الأسلوب util.format() بإرجاع سلسلة منسقة باستخدام الوسيطة الأولى كسلسلة تنسيق printf-مثل التي يمكن أن تحتوي على صفر أو أكثر من محددات التنسيق. يتم استبدال كل محدد بالقيمة المحولة من الوسيطة المقابلة. المحددات المدعومة هي:

إذا لم يكن للمحدد وسيطة مقابلة، فلن يتم استبداله:

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

يتم تنسيق القيم التي ليست جزءا من سلسلة التنسيق باستخدام util.inspect() إذا لم يكن نوعها string.

إذا كان هناك المزيد من الوسيطات التي تم تمريرها إلى الأسلوب util.format() من عدد المحددات، يتم تسلسل الوسيطات الإضافية إلى السلسلة التي تم إرجاعها، مفصولة بمسافات:

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

إذا كانت الوسيطة الأولى لا تحتوي على محدد تنسيق صحيح، util.format() بإرجاع سلسلة عبارة عن سلسلة لكافة الوسيطات مفصولة بمسافات:

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

إذا تم تمرير وسيطة واحدة فقط إلى util.format()، يتم إرجاعها كما هي دون أي تنسيق:

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

util.format() هو أسلوب متزامن مخصص كأداة لتصحيح الأخطاء. يمكن أن يكون لبعض قيم الإدخال حمل أداء كبير يمكن أن يمنع حلقة الحدث. استخدم هذه الدالة بعناية ولا تستخدم أبدا في مسار التعليمات البرمجية الساخنة.

function format(format?: any, param: any[]): string

المعلمات

المرتجعات

هذه الدالة مطابقة لتنسيق ، باستثناء أنها تأخذ وسيطة inspectOptions تحدد الخيارات التي يتم تمريرها إلى فحص.

util.formatWithOptions({ colors: true }, 'See object %O', { foo: 42 });
// Returns 'See object { foo: 42 }', where `42` is colored as a number
// when printed to a terminal.

function formatWithOptions(inspectOptions: InspectOptions, format?: any, param: any[]): string

المعلمات

المرتجعات

إنشاء uuid مكون من 20 حرفا.

function generateUUID(): string

المرتجعات

إرجاع رقم عشوائي

function getRandomValue(): number

المرتجعات

إرجاع مخطط لكافة رموز أخطاء النظام المتوفرة من واجهة برمجة تطبيقات Node.js. يعتمد التعيين بين رموز الخطأ وأسماء الأخطاء على النظام الأساسي. راجع Common System Errors لأسماء الأخطاء الشائعة.

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

function getSystemErrorMap(): Map<number, [string, string]>

المرتجعات

إرجاع اسم السلسلة لرمز خطأ رقمي يأتي من واجهة برمجة تطبيقات Node.js. يعتمد التعيين بين رموز الخطأ وأسماء الأخطاء على النظام الأساسي. راجع Common System Errors لأسماء الأخطاء الشائعة.

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

function getSystemErrorName(err: number): string

المعلمات

المرتجعات

إرجاع الفاصل الزمني بين تاريخين بالمللي ثانية

function getTimeDiffInMilliseconds(start: Date, end: Date): number

المعلمات

المرتجعات

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

وراثة أساليب النموذج الأولي من منشئ إلى آخر. سيتم تعيين النموذج الأولي constructor إلى كائن جديد تم إنشاؤه من superConstructor.

يضيف هذا بشكل أساسي بعض التحقق من صحة الإدخال أعلىObject.setPrototypeOf(constructor.prototype, superConstructor.prototype). وكراحة إضافية، يمكن الوصول إلى superConstructor من خلال خاصية constructor.super_.

const util = require('node:util');
const EventEmitter = require('node: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!'); // Received data: "It works!"

مثال ES6 باستخدام classextends:

const EventEmitter = require('node: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');

function inherits(constructor: unknown, superConstructor: unknown)

المعلمات

يقوم الأسلوب util.inspect() بإرجاع تمثيل سلسلة object مخصص لتصحيح الأخطاء. قد يتغير ناتج util.inspect في أي وقت ولا ينبغي الاعتماد عليه برمجيا. قد يتم تمرير options إضافية تغير النتيجة. سيستخدم util.inspect() اسم الدالة الإنشائية و/أو @@toStringTag لإنشاء علامة قابلة للتعري لقيمة تم فحصها.

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] {}'

تشير المراجع الدائرية إلى ارتساءها باستخدام فهرس مرجعي:

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

const obj = {};
obj.a = [obj];
obj.b = {};
obj.b.inner = obj.b;
obj.b.obj = obj;

console.log(inspect(obj));
// <ref *1> {
//   a: [ [Circular *1] ],
//   b: <ref *2> { inner: [Circular *2], obj: [Circular *1] }
// }

يفحص المثال التالي كافة خصائص الكائن util:

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

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

يوضح المثال التالي تأثير خيار compact:

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

const o = {
  a: [1, 2, [[
    'Lorem ipsum dolor sit amet,\nconsectetur adipiscing elit, sed do ' +
      'eiusmod \ntempor 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,\nconsectetur [...]', // A long line
//           'test',
//           'foo' ] ],
//     4 ],
//   b: Map(2) { 'za' => 1, 'zb' => 'test' } }

// Setting `compact` to false or an integer creates more reader friendly output.
console.log(util.inspect(o, { compact: false, depth: 5, breakLength: 80 }));

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

// Setting `breakLength` to e.g. 150 will print the "Lorem ipsum" text in a
// single line.

يسمح خيار showHidden بفحص إدخالات WeakMapWeakSet. إذا كان هناك إدخالات أكثر من maxArrayLength، فلا يوجد أي ضمان لعرض الإدخالات. وهذا يعني أن استرداد نفس إدخالات WeakSet مرتين قد يؤدي إلى إخراج مختلف. علاوة على ذلك، قد يتم جمع الإدخالات التي لا تتضمن مراجع قوية متبقية في أي وقت.

const { inspect } = require('node: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 } }

يضمن خيار sorted أن ترتيب إدراج خاصية العنصر لا يؤثر على نتيجة util.inspect().

const { inspect } = require('node:util');
const assert = require('node:assert');

const o1 = {
  b: [2, 3, 1],
  a: '`a` comes before `b`',
  c: new Set([2, 3, 1]),
};
console.log(inspect(o1, { sorted: true }));
// { a: '`a` comes before `b`', b: [ 2, 3, 1 ], c: Set(3) { 1, 2, 3 } }
console.log(inspect(o1, { sorted: (a, b) => b.localeCompare(a) }));
// { c: Set(3) { 3, 2, 1 }, b: [ 2, 3, 1 ], a: '`a` comes before `b`' }

const o2 = {
  c: new Set([2, 1, 3]),
  a: '`a` comes before `b`',
  b: [2, 3, 1],
};
assert.strict.equal(
  inspect(o1, { sorted: true }),
  inspect(o2, { sorted: true }),
);

يضيف الخيار numericSeparator تسطيرا سفليا كل ثلاثة أرقام إلى جميع الأرقام.

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

const thousand = 1_000;
const million = 1_000_000;
const bigNumber = 123_456_789n;
const bigDecimal = 1_234.123_45;

console.log(inspect(thousand, { numericSeparator: true }));
// 1_000
console.log(inspect(million, { numericSeparator: true }));
// 1_000_000
console.log(inspect(bigNumber, { numericSeparator: true }));
// 123_456_789n
console.log(inspect(bigDecimal, { numericSeparator: true }));
// 1_234.123_45

util.inspect() هو أسلوب متزامن مخصص لتصحيح الأخطاء. يبلغ الحد الأقصى لطول الإخراج حوالي 128 ميجابايت. سيتم اقتطاع المدخلات التي تؤدي إلى إخراج أطول.

function inspect(object: any, showHidden?: boolean, depth?: null | number, color?: boolean): string

المعلمات

المرتجعات

تمثيل object.

function inspect(object: any, options?: InspectOptions): string

المعلمات

المرتجعات

الاسم المستعار Array.isArray().

إرجاع true إذا كان object المحدد هو Array. وإلا، يتم إرجاع false.

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

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

function isArray(object: unknown): object

المعلمات

المرتجعات

إرجاع true إذا كان object المحدد هو Boolean. وإلا، يتم إرجاع false.

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

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

function isBoolean(object: unknown): object

المعلمات

المرتجعات

إرجاع true إذا كان object المحدد هو Buffer. وإلا، يتم إرجاع false.

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

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

function isBuffer(object: unknown): object

المعلمات

المرتجعات

التحقق من أن نوع التضمين مخصص للإنشاء

function isCreate(embedType: string): boolean

المعلمات

المرتجعات

إرجاع true إذا كان object المحدد هو Date. وإلا، يتم إرجاع false.

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

util.isDate(new Date());
// Returns: true
util.isDate(Date());
// false (without 'new' returns a String)
util.isDate({});
// Returns: false

function isDate(object: unknown): object

المعلمات

المرتجعات

إرجاع true إذا كانت هناك مساواة صارمة عميقة بين val1val2. وإلا، يتم إرجاع false.

راجع assert.deepStrictEqual() لمزيد من المعلومات حول المساواة الصارمة العميقة.

function isDeepStrictEqual(val1: unknown, val2: unknown): boolean

المعلمات

المرتجعات

إرجاع true إذا كان object المحدد هو Error. وإلا، يتم إرجاع false.

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

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

يعتمد هذا الأسلوب على سلوك Object.prototype.toString(). من الممكن الحصول على نتيجة غير صحيحة عندما تعالج الوسيطة object@@toStringTag.

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

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

function isError(object: unknown): object

المعلمات

المرتجعات

إرجاع true إذا كان object المحدد هو Function. وإلا، يتم إرجاع false.

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

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

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

function isFunction(object: unknown): boolean

المعلمات

المرتجعات

إرجاع true إذا كان object المحدد nullبدقة . وإلا، فترجعfalse.

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

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

function isNull(object: unknown): object

المعلمات

المرتجعات

إرجاع true إذا كان object المحدد null أو undefined. وإلا، يتم إرجاع false.

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

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

function isNullOrUndefined(object: unknown): object

المعلمات

المرتجعات

إرجاع true إذا كان object المحدد هو Number. وإلا، يتم إرجاع false.

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

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

function isNumber(object: unknown): object

المعلمات

المرتجعات

إرجاع true إذا كان object المحدد هو Objectتماما ولاFunction (على الرغم من أن الدالات هي كائنات في JavaScript). وإلا، يتم إرجاع false.

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

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

function isObject(object: unknown): boolean

المعلمات

المرتجعات

إرجاع true إذا كان object المحدد نوعا بدائيا. وإلا، فترجعfalse.

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

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

function isPrimitive(object: unknown): boolean

المعلمات

المرتجعات

التحقق من أن عنوان url للتضمين هو لتقرير RDL.

function isRDLEmbed(embedUrl: string): boolean

المعلمات

المرتجعات

إرجاع true إذا كان object المحدد هو RegExp. وإلا، يتم إرجاع false.

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

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

function isRegExp(object: unknown): object

المعلمات

المرتجعات

التحقق من حفظ التقرير.

function isSavedInternal(hpm: HttpPostMessage, uid: string, contentWindow: Window): Promise<boolean>

المعلمات

المرتجعات

إرجاع true إذا كان object المحدد هو string. وإلا، يتم إرجاع false.

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

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

function isString(object: unknown): object

المعلمات

المرتجعات

إرجاع true إذا كان object المحدد هو Symbol. وإلا، يتم إرجاع false.

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

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

function isSymbol(object: unknown): object

المعلمات

المرتجعات

إرجاع true إذا كان object المحدد undefined. وإلا، يتم إرجاع false.

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

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

function isUndefined(object: unknown): object

المعلمات

المرتجعات

يقوم الأسلوب util.log() بطباعة string المعطاة stdout مع طابع زمني مضمن.

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

util.log('Timestamped message.');

function log(string: string)

المعلمات

يوفر واجهة برمجة تطبيقات أعلى مستوى لتحليل وسيطة سطر الأوامر من التفاعل مع process.argv مباشرة. يأخذ مواصفات للوسيطات المتوقعة ويعيد كائنا منظما بالخيارات والمواضع التي تم تحليلها.

import { parseArgs } from 'node:util';
const args = ['-f', '--bar', 'b'];
const options = {
  foo: {
    type: 'boolean',
    short: 'f',
  },
  bar: {
    type: 'string',
  },
};
const {
  values,
  positionals,
} = parseArgs({ args, options });
console.log(values, positionals);
// Prints: [Object: null prototype] { foo: true, bar: 'b' } []

function parseArgs<T>(config?: T): ParsedResults<T>

المعلمات

المرتجعات

وسيطات سطر الأوامر التي تم تحليلها:

الثبات: 1.1 - التطوير النشط نظرا لمثال .env الملف:

const { parseEnv } = require('node:util');

parseEnv('HELLO=world\nHELLO=oh my\n');
// Returns: { HELLO: 'oh my' }

function parseEnv(content: string): object

المعلمات

المرتجعات

function promisify(fn: (callback: (err?: any) => void) => void): () => Promise<void>

المعلمات

المرتجعات

function promisify(fn: Function): Function

المعلمات

المرتجعات

function promisify<T1, T2, T3, T4, T5, TResult>(fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5, callback: (err: any, result: TResult) => void) => void): (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5) => Promise<TResult>

المعلمات

المرتجعات

function promisify<T1, T2, T3, T4, T5>(fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5, callback: (err?: any) => void) => void): (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5) => Promise<void>

المعلمات

المرتجعات

function promisify<T1, T2, T3, T4, TResult>(fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4, callback: (err: any, result: TResult) => void) => void): (arg1: T1, arg2: T2, arg3: T3, arg4: T4) => Promise<TResult>

المعلمات

المرتجعات

function promisify<T1, T2, T3, T4>(fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4, callback: (err?: any) => void) => void): (arg1: T1, arg2: T2, arg3: T3, arg4: T4) => Promise<void>

المعلمات

المرتجعات

function promisify<T1, T2, T3, TResult>(fn: (arg1: T1, arg2: T2, arg3: T3, callback: (err: any, result: TResult) => void) => void): (arg1: T1, arg2: T2, arg3: T3) => Promise<TResult>

المعلمات

المرتجعات

function promisify<T1, T2, T3>(fn: (arg1: T1, arg2: T2, arg3: T3, callback: (err?: any) => void) => void): (arg1: T1, arg2: T2, arg3: T3) => Promise<void>

المعلمات

المرتجعات

function promisify<T1, T2, TResult>(fn: (arg1: T1, arg2: T2, callback: (err: any, result: TResult) => void) => void): (arg1: T1, arg2: T2) => Promise<TResult>

المعلمات

المرتجعات

function promisify<T1, T2>(fn: (arg1: T1, arg2: T2, callback: (err?: any) => void) => void): (arg1: T1, arg2: T2) => Promise<void>

المعلمات

المرتجعات

function promisify<T1, TResult>(fn: (arg1: T1, callback: (err: any, result: TResult) => void) => void): (arg1: T1) => Promise<TResult>

المعلمات

المرتجعات

function promisify<T1>(fn: (arg1: T1, callback: (err?: any) => void) => void): (arg1: T1) => Promise<void>

المعلمات

المرتجعات

يأخذ دالة تتبع نمط رد الاتصال الشائع للخطأ الأول، أي أخذ رد اتصال (err, value) => ... كوسيطة أخيرة، وإرجاع إصدار يرجع الوعود.

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

const stat = util.promisify(fs.stat);
stat('.').then((stats) => {
  // Do something with `stats`
}).catch((error) => {
  // Handle the error.
});

أو، ما يعادل استخدام async functions:

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

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

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

callStat();

إذا كانت هناك خاصية original[util.promisify.custom] موجودة، فسيرجع promisify قيمته، راجع Custom promisified functions.

يفترض promisify() أن original هي دالة تأخذ رد اتصال كوسيطة نهائية لها في جميع الحالات. إذا لم تكن original دالة، فسيطرح promisify() خطأ. إذا كانت original دالة ولكن وسيطتها الأخيرة ليست رد اتصال بالخطأ أولا، فسيستمر تمرير رد اتصال الخطأ الأول كوسيطة أخيرة له.

قد لا يعمل استخدام promisify() على أساليب الفئة أو الأساليب الأخرى التي تستخدم this كما هو متوقع ما لم تتم معالجتها بشكل خاص:

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

class Foo {
  constructor() {
    this.a = 42;
  }

  bar(callback) {
    callback(null, this.a);
  }
}

const foo = new Foo();

const naiveBar = util.promisify(foo.bar);
// TypeError: Cannot read property 'a' of undefined
// naiveBar().then(a => console.log(a));

naiveBar.call(foo).then((a) => console.log(a)); // '42'

const bindBar = naiveBar.bind(foo);
bindBar().then((a) => console.log(a)); // '42'

function promisify<TCustom>(fn: CustomPromisify<TCustom>): TCustom

المعلمات

المرتجعات

function promisify<TResult>(fn: (callback: (err: any, result: TResult) => void) => void): () => Promise<TResult>

المعلمات

المرتجعات

رفع حدث مخصص مع بيانات الحدث على عنصر HTML المحدد.

function raiseCustomEvent(element: HTMLElement, eventName: string, eventData: any)

المعلمات

function remove<T>(predicate: (x: T) => boolean, xs: T[])

المعلمات

إرجاع str مع إزالة أي رموز إلغاء ANSI.

console.log(util.stripVTControlCharacters('\u001B[4mvalue\u001B[0m'));
// Prints "value"

function stripVTControlCharacters(str: string): string

المعلمات

المرتجعات

الاستقرار: 1.1 - التطوير النشط

ترجع هذه الدالة نصا منسقا بالنظر إلى format تمريره.

const { styleText } = require('node:util');
const errorMessage = styleText('red', 'Error! Error!');
console.log(errorMessage);

يوفر util.inspect.colors أيضا تنسيقات نصية مثل italicunderline ويمكنك الجمع بين كليهما:

console.log(
  util.styleText(['underline', 'italic'], 'My italic underlined message'),
);

عند تمرير صفيف من التنسيقات، يكون ترتيب التنسيق المطبق من اليسار إلى اليمين بحيث قد يقوم النمط التالي بالكتابة فوق النمط السابق.

console.log(
  util.styleText(['red', 'green'], 'text'), // green
);

يمكن العثور على القائمة الكاملة للتنسيقات في المعدلات.

function styleText(format: ForegroundColors | BackgroundColors | Modifiers | (ForegroundColors | BackgroundColors | Modifiers)[], text: string): string

المعلمات

المرتجعات

إرجاع string بعد استبدال أي نقاط تعليمات برمجية بديلة (أو ما يعادلها، أي وحدات تعليمة برمجية بديلة غير مفصولة) ب "حرف استبدال" Unicode U+FFFD.

function toUSVString(string: string): string

المعلمات

المرتجعات

إنشاء وإرجاع مثيل AbortController تم وضع علامة على AbortSignal الخاص به على أنه قابل للنقل ويمكن استخدامه مع structuredClone() أو postMessage().

function transferableAbortController(): AbortController

المرتجعات

AbortController قابل للنقل

وضع علامة على AbortSignal المحددة على أنها قابلة للنقل بحيث يمكن استخدامها معstructuredClone()postMessage().

const signal = transferableAbortSignal(AbortSignal.timeout(100));
const channel = new MessageChannel();
channel.port2.postMessage(signal, [signal]);

function transferableAbortSignal(signal: AbortSignal): AbortSignal

المعلمات

المرتجعات

نفس AbortSignal