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

أدخل JSON لتحويله إلى واجهات TypeScript! يدعم TypeScript interface. TypeORM · Sequelize · Mongoose في التبويبات أعلاه.
JSON
النتيجة
 

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

تقرأ هذه الأداة قيمة JSON وتكتب لها تعريفات interface في TypeScript. تبقى المفاتيح كما هي تمامًا؛ وتُدمج مصفوفات الكائنات في interface واحدة، وتحصل المفاتيح الموجودة في بعض العناصر فقط على ?، وتصبح القيم المختلطة أنواع اتحاد (union).

استخدمها لتحديد أنواع استجابات fetch أو axios في الواجهة الأمامية، أو لتعريف أنواع الإرجاع لمسارات API في Next.js أو handlers في Express، أو كلما كانت الخلفية لا توثّق إلا أمثلة استجابات دون تعريفات أنواع.

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

  1. الصق JSON استجابة، منسوخًا مثلًا من تبويب Network في DevTools.
  2. أدخل اسم الـ interface الجذرية في اسم النوع (مثل ChannelHistory)؛ ويُحفظ في الرابط على شكل ?name=.
  3. احفظ الناتج في ملف مثل types.ts واستخدمه عبر import type { ChannelHistory } from "./types".

مثال

المدخلات (JSON)
{
  "channel": "general",
  "messages": [
    { "id": "m1", "user": "kim", "text": "deploy done", "reactions": ["+1"] },
    { "id": "m2", "user": "lee", "text": null, "edited": true, "attachment": { "type": "image", "url": "https://cdn.example.com/a.png" } }
  ],
  "cursor": 42
}
المخرجات (TypeScript)
export interface ChannelHistory {
  channel: string;
  messages: Message[];
  cursor: number;
}

export interface Message {
  id: string;
  user: string;
  text: string | null;
  reactions?: string[];
  edited?: boolean;
  attachment?: Attachment;
}

export interface Attachment {
  type: string;
  url: string;
}

تُدمج الرسالتان في interface واحدة باسم Message؛ وreactions وedited وattachment تظهر في إحداهما فقط، فتحصل على ?. ويخلط text بين سلسلة نصية وnull، فيعطي string | null. وتأخذ واجهات العناصر صيغة المفرد من المفتاح (messages → Message).

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

  • كل تعريف هو export interface، جاهز للاستيراد في مكان آخر.
  • لا يُعاد تسمية مفاتيح JSON، فتطابق الأنواع كائن الاستجابة واحدًا لواحد؛ والمفاتيح التي ليست معرّفات صالحة ("a-b"، "2fa") تُقتبس.
  • تدمج مصفوفات الكائنات المفاتيح من كل العناصر؛ والمفاتيح الغائبة في بعض العناصر تصبح اختيارية (?:).
  • الأنواع المختلطة تُنتج اتحادات (string | number)؛ ويُلحق null في الآخر على شكل | null. والمصفوفات المختلطة تصبح (string | number)[].
  • المصفوفات الفارغة ليس فيها نوع عنصر يُستنتج فتصبح unknown[].
  • المصفوفة على المستوى الأعلى تُنتج أيضًا اسمًا بديلًا مثل export type Root = RootItem[];.

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

تحديد أنواع استجابات fetch وaxios

مرّر النوع كمعامل generic، مثل const res = await axios.get<ChannelHistory>(url)، فينبّهك المحرر إلى أن res.data.messages[0].text قد يكون null.

APIs خارجية بلا تعريفات أنواع

للـ APIs الداخلية أو الخارجية التي ليس لها SDK أو حزمة @types، تكفي استجابة نموذجية واحدة لإنتاج ملف تعريف أنواع تشاركه مع الفريق.

البيانات الوهمية وprops المكونات

ولّد interfaces من JSON وهمي في Storybook أو الاختبارات واستخدمها أنواعًا لـ props المكونات؛ وحين تنحرف البيانات الوهمية عن المكونات، يخبرك المترجم.

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

  • تُمحى الـ interfaces وقت الترجمة ولا تتحقق وقت التشغيل من أن الاستجابة لها ذلك الشكل فعلًا. اقرنها بمكتبة مخططات مثل zod إن احتجت إلى تحقق وقت التشغيل.
  • كل الأرقام number (دون تمييز بين صحيح وعشري)، وسلاسل التاريخ string.
  • الحقول ذات المجموعة الثابتة من القيم، مثل "status": "active"، تخرج string؛ ضيّقها بنفسك إلى اتحادات حرفية ("active" | "banned").
  • الأشكال المتطابقة تحت مفاتيح مختلفة يحصل كلٌّ منها على interface خاصة به، والأسماء المتعارضة تحصل على لاحقة رقمية مثل Profile2.

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

هل يمكنني الحصول على أسماء type بديلة بدلًا من interfaces؟

لا يُستخدم الاسم البديل type إلا للمصفوفة أو القيمة البدائية على المستوى الأعلى؛ والكائنات دائمًا interfaces. إعادة كتابة export interface X { ... } بالشكل export type X = { ... }; تتصرف بالطريقة نفسها لهذا الغرض.

لماذا يُبقى الاختياري (?) و| null منفصلين؟

معناهما مختلف: ? يقول إن المفتاح قد يغيب (undefined)، بينما | null يقول إن المفتاح موجود بقيمة null. ومع تفعيل strictNullChecks تعالج الحالتين بشكل مختلف.

لماذا لا تُحوَّل المفاتيح إلى camelCase؟

نوع TypeScript يصف الكائن الفعلي، والمفاتيح المعاد تسميتها لن تطابق الاستجابة بعد ذلك. إن أردت camelCase في كودك، فعرّف نوعًا منفصلًا لنتيجة دالة الربط الخاصة بك.

أحتاج إلى entities للـ ORM (TypeORM، Sequelize، Mongoose).

هذه الصفحة تُخرج تعريفات أنواع بسيطة فقط. تبويبات TypeORM وSequelize وMongoose في الأعلى تولّد كود الـ entities والنماذج من JSON نفسه.