‏tsnapi؛ اسنپ‌شات گرفتن از API عمومی کتابخونه

آنتونی فو (antfu) تو معرفی tsnapi می‌گه ایده‌اش ساده‌ست: همون کاری که Vitest با اسنپ‌شات تست برای خروجی توابع می‌کنه، برای «قرارداد عمومی» یه پکیج انجام بشه. tsnapi کل سطح API — هم export‌های ران‌تایم و هم تایپ‌ها — رو تو فایل‌های خوانا می‌ریزه که کنار کد کامیت می‌شن، و هر entry point دو فایل می‌سازه: .snapshot.js برای ران‌تایم و .snapshot.d.ts برای تایپ‌ها.

به گفتهٔ نویسنده دلیلش اینه که موقع نگهداری یه کتابخونه خیلی راحت می‌شه ناخواسته یه export رو حذف یا rename کرد، امضای یه تابع رو عوض کرد، تایپ‌ها رو شکوند، یا چیزی رو که نباید، عمومی کرد. وقتی اسنپ‌شات‌ها تو ریپو باشن، این تغییرها هم مثل هر تغییر کد دیگه‌ای تو دیف دیده و ریویو می‌شن.

روش پیشنهادی خودش استفاده به‌صورت پلاگین tsdown/Rolldown‌ه:

import { defineConfig } from 'tsdown'
import ApiSnapshot from 'tsnapi/rolldown'

export default defineConfig({
  entry: ['src/index.ts'],
  dts: true,
  plugins: [ApiSnapshot()],
})

بیلد اول اسنپ‌شات‌ها رو می‌نویسه و از بیلد بعدی، هر تغییری بیلد رو همراه با دیف فیل می‌کنه. یه CLI مستقل و یه یکپارچگی با Vitest هم داره که برای مونوریپو خودش پکیج‌های ورک‌اسپیس رو پیدا می‌کنه.

جالب‌ترین بخش، گارد تغییرات شکننده‌ست: وقتی با -u اسنپ‌شات رو آپدیت می‌کنی، tsnapi تغییر رو به «افزایشی» و «شکننده» دسته‌بندی می‌کنه و اگه شکننده باشه — مثل حذف یه export یا باریک‌تر شدن یه تایپ — آپدیت رو کلاً متوقف می‌کنه تا یه تغییر ناسازگار بی‌سروصدا منتشر نشه؛ برای عبور آگاهانه باید --allow-breaking یا متغیر محیطی TSNAPI_ALLOW_BREAKING=1 رو بدی. نویسنده تأکید می‌کنه این تشخیص عمداً محافظه‌کارانه‌ست و فقط «حذف شدن» رو مطمئن می‌گیره تا هشدار الکی کم باشه، ولی چون بیلد عادی با هر تغییری فیل می‌شه، هیچ تغییری از دید دیف پنهون نمی‌مونه.

نکات کلیدی:

• tsnapi سطح API عمومی پکیج — export‌های ران‌تایم و تایپ‌ها — رو به اسنپ‌شات تبدیل می‌کنه
• اسنپ‌شات‌ها کنار کد کامیت می‌شن، پس تغییر API تو گیت دیف دیده می‌شه
• به شکل پلاگین tsdown/Rolldown، CLI مستقل، یا افزونهٔ Vitest قابل استفاده‌ست
• گارد تغییرات شکننده جلوی آپدیت خودکار اسنپ‌شات موقع حذف یا باریک شدن یه export رو می‌گیره
• تشخیص شکنندگی عمداً محافظه‌کارانه‌ست، ولی بیلد عادی با هر تغییری فیل می‌شه