‏unbarrelify: خداحافظی با فایل‌های barrel

فایل‌های barrel همون فایل‌های index هستن که فقط محتوای ماژول‌های دیگه رو دوباره export می‌کنن — مثلاً یه utils/index.ts که formatDate و capitalize رو از فایل‌های جدا جمع می‌کنه و یه‌جا بیرون می‌ده. تو این صفحه اومده که این الگو خیلی راحته ولی هزینه داره: گراف ماژول‌ها رو الکی بزرگ می‌کنه و startup، HMR و پایپ‌لاین CI رو کند می‌کنه.

مشکل دوم به گفتهٔ مخزن، خراب‌شدن tree-shaking هست؛ یعنی وقتی فقط یه تابع رو لازم داری ممکنه کل کتابخونه باندل بشه. مشکل سوم هم وابستگی‌های حلقوی (import cycle) هست که گاهی باندلر رو می‌ترکونه یا خطاهای گیج‌کننده می‌سازه.

کار اصلی unbarrelify اینه که به‌جای اینکه فقط barrel رو پاک کنه، اول فایل‌های مصرف‌کننده رو پیدا می‌کنه و ایمپورت‌هاشون رو مستقیم به فایل سرچشمه وصل می‌کنه، بعد فایل barrel رو حذف می‌کنه. نتیجه اینه که import { formatDate } from "./utils/index.ts" تبدیل می‌شه به ایمپورت مستقیم از خود date.ts.

روش کارش چهار مرحله‌ست: شناسایی فایل‌هایی که فقط re-export دارن، ساختن نقشهٔ import/export برای ردگیری وابستگی‌ها، سیم‌کشی دوبارهٔ ایمپورت‌ها به سمت فایل اصلی، و آخرش حذف barrel.

ابزار چندتا گارد امن داره. هر چیزی که نقطهٔ ورود باشه — مثل فیلد exports تو package.json یا index.* ریشهٔ هر workspace — حفظ می‌شه. ایمپورت‌های پویا (dynamic import) و فایل‌های غیر JS/TS هم دست‌نخورده می‌مونن. namespace importها به‌صورت پیش‌فرض تغییر نمی‌کنن و فقط با فلگ --unsafe-namespace بازنویسی می‌شن که خود سازنده هشدار می‌ده ساده‌انگارانه‌ست و ممکنه برخورد اسم بسازه.

استفاده‌ش هم بدون نصب با npx unbarrelify ممکنه و تا وقتی --write نزنی فقط dry-run می‌مونه. فلگ‌هایی مثل --skip، --only و --barrel کنترل دقیق می‌دن و --check برای CI هست که اگه فایل barrel پیدا بشه با خروجی غیرصفر شکست بخوره. یه API برنامه‌نویسی هم داره که همون تابع unbarrelify(options) رو می‌ده و خروجی فایل‌های modified و deleted رو برمی‌گردونه.

نکات کلیدی:

• فقط برای پروژه‌های ESM (جاوااسکریپت و تایپ‌اسکریپت) کار می‌کنه
• به‌جای پاک‌کردن ساده، ایمپورت مصرف‌کننده‌ها رو مستقیم به سرچشمه وصل می‌کنه
• پیش‌فرض dry-run هست؛ تغییر واقعی فقط با --write
• نقطه‌های ورود، dynamic importها و فایل‌های غیر JS/TS حفظ می‌شن
• --check برای CI و یه API برنامه‌نویسی هم داره