حوّل أنواع TypeScript إلى JSON!

أدخل واجهات TypeScript لإنشاء JSON تجريبي! يدعم TypeScript interface, type. مفيد لتوثيق واجهات API وأجسام الطلبات التجريبية (mock request body).
TypeScript
النتيجة
 

حوّل أنواع TypeScript إلى JSON!

الصق تعريفات interface أو أسماء type البديلة أو enum أو الأصناف في TypeScript لتحصل على مستند JSON نموذجي يحققها. تُتتبَّع الاتحادات الحرفية وRecord وأنواع الأدوات مثل Pick وOmit وPartial والـ interfaces المتسلسلة بـ extends وتُملأ كلها.

استخدمه قبل وجود الـ API لتجهيز بيانات وهمية لـ MSW أو json-server، أو لإنشاء props في Storybook، أو لتُري فريق الخلفية بالضبط الشكل الذي تريد أن يرسلوه.

طريقة الاستخدام

  1. الصق تعريفات الأنواع من ملف مثل types.ts. يمكن أن تختلط بها export وimport وتعريفات الدوال؛ فلا تُقرأ إلا تعريفات الأنواع.
  2. ضمّن الأنواع المشار إليها والـ enums حتى تُملأ. أسماء الأنواع الغائبة عن الإدخال تصبح null.
  3. لا توجد خيارات. أول نوع كائني لا يشير إليه أي تعريف آخر يصبح الجذر، فضع الذي تريده أولًا؛ والاسم البديل الذي يملأ نوعًا عامًّا (generic)، مثل type UserPage = Page<User>، يُفضَّل على تعريف النوع العام نفسه.
  4. انسخ النتيجة إلى HttpResponse.json(...) في handler لـ MSW أو إلى بيانات اختبار ثابتة أو إلى args في Storybook، ثم عدّل القيم.

مثال

المدخلات (TypeScript)
type Channel = "email" | "sms" | "push";

enum Priority { Low = "low", High = "high" }

interface Notification {
  id: string;
  channel: Channel;
  priority: Priority;
  recipient: { userId: number; locale?: string };
  payload: Record<string, string>;
  readAt: Date | null;
  meta: Pick<Audit, "createdBy">;
}

interface Audit { createdBy: string; createdAt: Date }
المخرجات (JSON)
{
  "id": "",
  "channel": "email",
  "priority": "low",
  "recipient": {
    "userId": 0,
    "locale": ""
  },
  "payload": {
    "key": ""
  },
  "readAt": "1970-01-01T00:00:00.000Z",
  "meta": {
    "createdBy": ""
  }
}

Channel اتحاد حرفي نصي، فيأخذ قيمته الأولى "email"؛ ويأخذ الـ enum النصي Priority قيمة عضوه الأول "low". يصبح Record<string, string> كائنًا بمفتاح واحد "key"، ويُحلّ Date | null إلى الجانب غير null كسلسلة ISO، ويُبقي Pick<Audit, "createdBy"> المفتاح المختار فقط. والحقل الاختياري locale? مضمَّن أيضًا.

الميزات المدعومة

  • الأنواع البدائية: string → ""، وnumber/bigint → 0، وboolean → false، وany/unknown → null، وDate → 1970-01-01T00:00:00.000Z (صيغة Date.toJSON()).
  • الأنواع الحرفية تستخدم قيمتها، والاتحادات تأخذ أول عضو ليس null/undefined، والتقاطعات (A & B) وinterface ... extends تدمج الخصائص.
  • يستخدم الـ enum قيمة عضوه الأول، أو 0 للـ enum الرقمي دون قيم ابتدائية.
  • المصفوفات وArray<T> وSet<T> تحصل على عنصر نموذجي واحد؛ والـ tuples تحصل على قيمة لكل موضع؛ وRecord<K, V> وMap وتوقيعات الفهرسة تصبح {"key": V}.
  • يدعم أنواع الأدوات Partial وRequired وReadonly وNonNullable وPick وOmit.
  • الدوال والخصائص ذات الأنواع الدالية لا وجود لها في JSON فتُحذف؛ وفي الأصناف تُستبعد الحقول static ودوال الوصول get/set وحقول @Exclude().
  • المصفوفات المرجعية ذاتيًا (children: TreeNode[]) تُقطع كمصفوفات فارغة.

حالات الاستخدام

استجابات وهمية لـ MSW أو json-server

قبل أن تجهز الخلفية، ولّد بيانات وهمية من أنواع استجابات الـ API. يمكن بناء الواجهة أولًا، والانتقال لاحقًا إلى الـ API الحقيقي يُبقي الأنواع نفسها.

props لـ Storybook والاختبارات

أنشئ كائنًا افتراضيًا من نوع props المكوّن لـ args في القصص أو لبيانات العرض في React Testing Library. كل خاصية مطلوبة موجودة، فلا أخطاء أنواع تطاردها.

الاتفاق على صيغ الطلبات مع الخلفية

حوّل نوع طلب من الواجهة الأمامية إلى JSON والصقه في وثيقة تصميم الـ API أو في issue، فيستطيع مطورو الخلفية الذين لا يستخدمون TypeScript قراءة البنية فورًا.

ملاحظات وقيود

  • الخصائص الاختيارية (?) مضمَّنة دائمًا؛ احذف المفاتيح بنفسك لاختبار الاستجابات التي تغيب فيها.
  • تُستبدل معاملات الأنواع العامة حيث يُستخدم النوع: مع type UserPage = Page<User> يُملأ items: T[] بـ User، وتُطبَّق القيم الافتراضية مثل <T = string> حين لا يُعطى معامل. أما الأنواع الشرطية داخل الأنواع العامة فما زالت لا تُقيَّم.
  • لا تُقيَّم أنواع الوصول المفهرس مثل T["key"] ولا الأنواع الشرطية ولا أنواع template literal.
  • حقل الصنف المهيأ بقيمة حرفية واحدة (name = "kim"، retries = 3) يستخدم تلك القيمة؛ أما القيم الابتدائية الأخرى مثل new Date() فلا تفيد إلا في تلميح النوع.
  • لا يُقرأ كود المخططات وقت التشغيل مثل Zod أو io-ts؛ اكتب النوع الذي يستنتجه z.infer كـ interface عادية.
  • يُعرض Map وSet ككائن ومصفوفة، لكن JSON.stringify يحوّل كليهما إلى {}، فالأفضل استخدام Record أو المصفوفات في أنواع الاستجابات.

الأسئلة الشائعة

هل صحيح أن Date يخرج كسلسلة نصية؟

نعم. يستبدل JSON.stringify الـ Date بنتيجة toJSON() الخاصة به، وهي سلسلة ISO 8601. والجانب المستقبِل يحصل على سلسلة نصية على أي حال، فإما أن تحدد نوعها بـ string أو أن تحلّلها.

أي قيمة يحصل عليها اتحاد مثل status: "active" | "inactive"؟

أول قيمة حرفية بترتيب التعريف، "active". أعد ترتيب الاتحاد إن كنت تفضّل إظهار قيمة أخرى.

هل يعمل مع أصناف DTO في NestJS؟

تُحلَّل تعريفات الأصناف والـ decorators، فتتحول كائنات DTO المعلَّمة بـ decorators من class-validator بلا مشكلة، وتُستبعد حقول @Exclude() من class-transformer.

كيف أنتقل من JSON إلى أنواع TypeScript؟

استخدم صفحة JSON → TypeScript للاتجاه المعاكس. وتولّد صفحات منفصلة أيضًا JSON من نماذج TypeORM وSequelize وMongoose.