‏Counterfact: سرور موک هوشمند با TypeScript و REPL زنده

Counterfact یه ابزار CLI‌ه که فقط با یه دستور، از روی یه فایل OpenAPI spec یه سرور API کاملاً زنده و قابل برنامه‌ریزی می‌سازه. نه فقط یه موک ساده که جواب‌های ثابت برمی‌گردونه — بلکه یه شبیه‌ساز واقعیه که state داره، تایپ‌سیف هست، و می‌شه حین اجرا باهاش تعامل داشت.

با اجرای این دستور کار شروع می‌شه:

npx counterfact@latest https://petstore3.swagger.io/api/v3/openapi.json api

Counterfact فایل OpenAPI رو می‌خونه، یه پوشه routes/ با یه فایل .ts برای هر endpoint می‌سازه، و یه پوشه types/ با تمام interface‌های تایپ‌شده. سرور بلافاصله بالا میاد و به صورت پیش‌فرض داده‌های تصادفی ولی معتبر از نظر schema برمی‌گردونه.

یکی از ویژگی‌های اصلیش shared state بین route‌هاست. با یه فایل _.context.ts در هر دایرکتوری می‌شه یه context تایپ‌شده تعریف کرد که همه route‌های اون سطح بهش دسترسی دارن. مثلاً POST یه pet اضافه می‌کنه، GET همون رو برمی‌گردونه، و DELETE حذفش می‌کنه — همه از یه Map مشترک:

export class Context {
  private pets = new Map<number, Pet>();
  private nextId = 1;

  add(pet: Omit<Pet, "id">): Pet {
    const id = this.nextId++;
    const rec = { ...pet, id };
    this.pets.set(id, rec);
    return rec;
  }

  get(id: number) { return this.pets.get(id); }
  list()         { return [...this.pets.values()]; }
  remove(id: number) { this.pets.delete(id); }
}

هات‌ریلود هم یه مزیت مهمه — وقتی یه فایل route رو ذخیره می‌کنی، سرور بدون ریستارت تغییر رو اعمال می‌کنه و state حافظه هم دست‌نخورده می‌مونه. یعنی می‌تونی رفتار API رو حین تست تغییر بدی بدون اینکه همه چیز ریست بشه.

REPL زنده شاید جالب‌ترین بخش ابزار باشه. یه prompt جاوااسکریپتیه که مستقیم به سرور در حال اجرا وصله. ازش می‌شه state رو بررسی کرد، داده اضافه کرد، درخواست HTTP فرستاد، یا حتی بخشی از route‌ها رو به یه بک‌اند واقعی proxy کرد — همه اینا بدون لمس کردن هیچ فایلی.

در مقایسه با ابزارهایی مثل Prism، WireMock یا MSW، Counterfact تنها گزینه‌ایه که همزمان TypeScript type safety، shared state، REPL زنده، و هات‌ریلود رو داره. مخاطبش فرانت‌اندرهاییه که بک‌اند آماده ندارن، تست‌نویس‌هایی که نیاز به state قابل تکرار دارن، و پایپ‌لاین‌های اتوماسیون که به API قابل اسکریپت نیاز دارن.

نکات کلیدی:

• با یه دستور npx و یه URL فایل OpenAPI، سرور کامل می‌سازه
• route‌های TypeScript تایپ‌شده تولید می‌کنه که drift با spec غیرممکنه
• state مشترک بین route‌ها از طریق فایل _.context.ts
• هات‌ریلود بدون از دست دادن state حافظه
• REPL زنده برای کنترل، تست، و شبیه‌سازی خطا حین اجرا
• حالت hybrid proxy: بخشی از route‌ها به بک‌اند واقعی فوروارد می‌شن