LogoENEnglish

راهنمای جامع ماژول util در Node.js

ماژول node:util مجموعه‌ای از توابع کمکی قدرتمند برای استفاده در هستهٔ Node.js و همچنین توسعهٔ برنامه‌ها ارائه می‌دهد. این ماژول ابزارهایی برای دیباگ، بازرسی اشیا، تبدیل Callback ↔ Promise، قالب‌بندی رشته‌ها، بررسی انواع، مدیریت خطاها، رمزگذاری متن، پردازش MIME، پارس آرگومان‌های CLI، سیگنال‌های Abort، و ابزارهای متفرقه فراهم می‌کند. این ماژول یکی از جعبه‌ابزارهای اصلی و ضروری برای توسعه‌دهندگان Node.js است.

util.inspectutil.promisify / util.callbackifyutil.deprecateutil.formatutil.types

~3 دقیقه مطالعه • بروزرسانی ۹ دی ۱۴۰۴

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


ماژول node:util مجموعه‌ای از توابع کمکی برای کارهای رایج در Node.js ارائه می‌دهد. این توابع در دیباگ، مدیریت خطا، بررسی انواع، قالب‌بندی خروجی و تبدیل سبک‌های مختلف برنامه‌نویسی بسیار کاربردی هستند.


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


const util = require('node:util');
// یا
import util from 'node:util';

3. دیباگ و بازرسی (Debugging & Inspection)


3.1 util.inspect()


نمایش ساختار کامل یک شیء—ابزار اصلی دیباگ.

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

پشتیبانی از util.inspect.custom برای تعریف نمایش سفارشی.


3.2 util.debuglog()


لاگ‌گیری مشروط بر اساس متغیر محیطی NODE_DEBUG.

const log = util.debuglog('myapp');
log('Debug message');

4. تبدیل Callback ↔ Promise


4.1 util.promisify()


تبدیل توابع callback-style به Promise.

4.2 util.callbackify()


تبدیل Promise به callback-style.


5. مدیریت Deprecation


برای هشدار دادن دربارهٔ توابع قدیمی:

const fn = util.deprecate(originalFn, 'This function is deprecated');

6. قالب‌بندی رشته‌ها (Formatting)


6.1 util.format()


مشابه printf با %s، %d، %j، %o، %O و ...

6.2 util.formatWithOptions()


همان format اما با گزینه‌های inspect.


7. بررسی انواع (util.types)


مجموعه‌ای از چک‌های سریع و دقیق:

  • isArrayBuffer()
  • isAsyncFunction()
  • isBigInt64Array()
  • isDate()
  • isMap()
  • isPromise()
  • isProxy()
  • isRegExp()
  • isSet()
  • isTypedArray()
  • isUint8Array()
  • isWeakMap()

8. اطلاعات خطا و سیستم


  • util.getSystemErrorName(err)
  • util.getSystemErrorMap()
  • util.getSystemErrorMessage(err)

9. رمزگذاری و رمزگشایی متن


  • TextEncoder: فقط UTF‑8
  • TextDecoder: پشتیبانی از چندین encoding

10. پردازش MIME


  • util.MIMEType
  • util.MIMEParams

11. پارس آرگومان‌های CLI


ابزار مدرن برای ساخت CLI:

const args = util.parseArgs({
  options: { verbose: { type: 'boolean' } }
});

12. Abort و سیگنال‌های قابل انتقال


  • util.transferableAbortController()
  • util.transferableAbortSignal()
  • util.aborted(signal)

13. ابزارهای متفرقه


  • util.diff() — الگوریتم Myers Diff
  • util.stripVTControlCharacters() — حذف کدهای ANSI
  • util.styleText() — استایل‌دهی ANSI
  • util.toUSVString() — اصلاح surrogateهای نامعتبر
  • util.parseEnv() — پارس فایل‌های .env
  • util.getCallSites() — استک‌تریس با پشتیبانی Source Map

14. APIهای قدیمی و منسوخ


  • util.inherits() → استفاده از class extends
  • util.isArray() → استفاده از Array.isArray()
  • util._extend() → استفاده از Object.assign()

15. بهترین شیوه‌ها


  • برای لاگ‌گیری عمیق از util.inspect() استفاده کن.
  • برای APIهای callback قدیمی از promisify بهره ببر.
  • برای لاگ‌های شرطی از debuglog استفاده کن.
  • برای ساخت CLI تمیز از parseArgs استفاده کن.
  • در کدهای performance-critical از util.types استفاده کن.

نتیجه‌گیری


ماژول node:util یکی از قدرتمندترین جعبه‌ابزارهای Node.js است. این ماژول ابزارهایی برای دیباگ، قالب‌بندی، بررسی انواع، مدیریت خطا، کار با متن، پردازش MIME، ساخت CLI و بسیاری موارد دیگر ارائه می‌دهد. استفادهٔ درست از این ماژول می‌تواند کیفیت، خوانایی و پایداری کد را به‌طور چشمگیری افزایش دهد.


نوشته و پژوهش شده توسط دکتر شاهین صیامی

Next Article