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

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

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

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 و بسیاری موارد دیگر ارائه می‌دهد. استفادهٔ درست از این ماژول می‌تواند کیفیت، خوانایی و پایداری کد را به‌طور چشمگیری افزایش دهد.