حوّل كيانات TypeORM إلى JSON!

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

حوّل كيانات TypeORM إلى JSON!

الصق أصناف entities في TypeORM لتحصل على شكل JSON الذي تُنتجه تلك الكيانات حين تُرجعها من API، مملوءًا بقيم بديلة. صُمّم لمشاريع NestJS أو Express التي ترسل الكيانات مباشرة في الاستجابات وتحتاج إلى أمثلة Swagger أو عيّنات طلبات واستجابات للاتفاق عليها مع الواجهة الأمامية.

تأتي القيم من نوع TypeScript على كل خاصية، لا من خيارات @Column. لذا فالعمود المعرَّف بـ @Column({ type: "decimal" }) مع price: number يخرج على شكل الرقم 0.

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

  1. الصق ملف الـ entity في خانة TypeORM. ضمّن الكيانات المرتبطة والـ enums حتى تُملأ الكائنات المتداخلة.
  2. تتحدث خانة النتيجة أثناء الكتابة. الـ entity الذي لا يشير إليه أي entity آخر يصبح كائن JSON على المستوى الأعلى؛ وإن وُجدت عدة كيانات غير مترابطة، يظهر كلٌّ منها تحت اسم صنفه.
  3. خذ JSON بزر النسخ في أعلى يمين النتيجة، أو اضغط Ctrl/⌘+Enter.

مثال

المدخلات (TypeORM)
enum Genre { Novel = "novel", Essay = "essay" }

@Entity()
export class Author {
  @PrimaryGeneratedColumn()
  id: number;

  @Column()
  name: string;
}

@Entity()
export class Book {
  @PrimaryGeneratedColumn("uuid")
  id: string;

  @Column({ type: "enum", enum: Genre })
  genre: Genre;

  @Column({ type: "decimal", nullable: true })
  price: number | null;

  @ManyToOne(() => Author)
  author: Author;

  @Exclude()
  @Column()
  internalCode: string;
}
المخرجات (JSON)
{
  "id": "",
  "genre": "novel",
  "price": 0,
  "author": {
    "id": 0,
    "name": ""
  }
}

يشير Book إلى Author، لذا فإن Book هو الجذر وauthor متداخل داخله. يُحذف internalCode بسبب @Exclude()، وprice ذو النوع number | null يتبع أول نوع غير null فيصبح 0. والمفتاح الأساسي من نوع uuid نوعه string، فيكون سلسلة فارغة.

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

  • تصبح علاقات @ManyToOne و@OneToOne كائنات متداخلة؛ ويصبح Post[] من @OneToMany أو @ManyToMany مصفوفة من عنصر واحد.
  • تُفك العلاقات الكسولة (Promise<Post[]>) وغلاف ESM Relation<User> إلى النوع الداخلي.
  • تستخدم enums في TypeScript قيمة العضو الأول: السلسلة النصية للـ enums النصية، والرقم للرقمية.
  • تُستبعد الحقول المعلَّمة بـ @Exclude() من class-transformer، والحقول static، والدوال، والـ getters.
  • تصبح خصائص Date (من @CreateDateColumn وما شابه) سلاسل ISO مثل 1970-01-01T00:00:00.000Z.
  • الأنواع الشائعة في أعمدة jsonb، مثل Record<string, number>، تُعرض على شكل {"key": 0}.
  • حين تشير الكيانات إلى بعضها، تُقطع الزيارة الثانية بـ null أو بمصفوفة فارغة فيبقى التداخل محدودًا.

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

أمثلة Swagger في controllers الخاصة بـ NestJS

الـ controllers التي تُرجع الكيانات مباشرة ما زالت تحتاج إلى payload مثال لـ @ApiResponse. الصق ملف الـ entity واستبدل القيم البديلة في النتيجة بقيم واقعية.

معاينة العلاقات المحمَّلة

حين تستعلم بـ relations: ["author"]، تريد الواجهة الأمامية معرفة عمق التداخل في الاستجابة. يوضّح الناتج أي حقول العلاقات كائنات وأيها مصفوفات.

بيانات ثابتة لاختبارات e2e

استخدم الناتج هيكلًا لجسم طلب في استدعاءات POST عبر supertest. احذف الحقول المولَّدة مثل id والطوابع الزمنية، ثم املأ البقية.

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

  • لا تُقرأ خيارات @Column مثل nullable أو default أو length؛ فالقيمة تأتي من نوع الخاصية أو من قيمة ابتدائية حرفية (status = "draft"). إن كان العمود قد يكون null، فغيّر تلك القيمة إلى null بنفسك.
  • أصناف @Entity المتعددة التي لا يشير بعضها إلى بعض تُحوَّل كلها، بمفاتيح هي أسماء الأصناف ({ "Book": {...}, "Author": {...} }). أما الكيانات التي يشير بعضها إلى بعض فتُنتج جذرًا واحدًا متداخلًا.
  • الأصناف المستوردة بدلًا من الملصوقة مجهولة للأداة وتظهر null.
  • لا تُطبَّق @Expose ومجموعات التسلسل و@Transform المستخدمة مع ClassSerializerInterceptor.

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

لماذا يكون @PrimaryGeneratedColumn("uuid") عندي سلسلة فارغة؟

نوع الخاصية وحده يحدد القيمة. id: string يعطي ""؛ ولا يُقرأ المعامل "uuid" في الـ decorator. للوثائق، ضع لاحقًا قيمة على شكل UUID.

هل هذا فعلًا ما يُرجعه الـ API حين يرسل entity؟

يطابق JSON.stringify لـ entity محمَّل بالكامل. العلاقات التي لم تحمّلها بـ relations تغيب ببساطة عن الاستجابة الحقيقية، فاعتبر حقول العلاقات في الناتج حالةَ التحميل.

عمود decimal يُظهر رقمًا، لكن الـ API عندي يُرجع سلسلة نصية. لماذا؟

تُرجع drivers PostgreSQL وMySQL قيم decimal كسلاسل نصية لتجنّب فقدان الدقة. عرّف الخاصية بالشكل price: string في الـ entity فيصبح الناتج، مثل بياناتك الحقيقية، سلسلة نصية.