حوّل نماذج Sequelize (TS) إلى JSON!

أدخل نماذج Sequelize (TS) لإنشاء JSON تجريبي! يدعم Sequelize, sequelize-typescript. مفيد لتوثيق واجهات API وأجسام الطلبات التجريبية (mock request body).
Sequelize (TS)
النتيجة
 

حوّل نماذج Sequelize (TS) إلى JSON!

أدخل أصناف نماذج @Table المكتوبة بـ sequelize-typescript فيبني JSON نموذجيًا على شكل ناتج toJSON() للنسخة. ويشمل ذلك سمات id وcreatedAt وupdatedAt وdeletedAt التي يضيفها Sequelize حتى لو لم تُعرَّف في الصنف.

على خلاف صفحة JS، تأتي القيم هنا من نوع TypeScript لكل خاصية لا من معامل DataType. فـ @Column(DataType.DECIMAL) المعرَّف بالشكل amount: string يُنتج سلسلة نصية.

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

  1. الصق ملفًا يحوي أصناف @Table في خانة Sequelize (TS). أضف النماذج المرتبطة (عبر @HasMany وما شابه) لتحصل على قيم متداخلة.
  2. تحقق من خانة النتيجة لترى JSON مع السمات المضافة تلقائيًا.
  3. بدّل خيارات @Table مثل timestamps أو paranoid لترى فورًا كيف تتغير حقول التاريخ.

مثال

المدخلات (sequelize-typescript)
@Table({ tableName: "invoices", paranoid: true })
export class Invoice extends Model {
  @Column(DataType.STRING(20))
  number: string;

  @Column(DataType.DECIMAL(10, 2))
  amount: string;

  @Column(DataType.ENUM("draft", "sent", "paid"))
  status: "draft" | "sent" | "paid";

  @ForeignKey(() => Customer)
  @Column
  customerId: number;
}
المخرجات (JSON)
{
  "id": 0,
  "number": "",
  "amount": "",
  "status": "draft",
  "customerId": 0,
  "createdAt": "1970-01-01T00:00:00.000Z",
  "updatedAt": "1970-01-01T00:00:00.000Z",
  "deletedAt": null
}

ليس للصنف مفتاح أساسي، لذا يُضاف id أولًا، ويضيف paranoid: true الحقل deletedAt: null. ويأخذ status أول قيمة حرفية من اتحاده، "draft"، ويكون amount سلسلة فارغة لأنه معرَّف كـ string.

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

  • في غياب @PrimaryKey أو @Column({ primaryKey: true }) أو خاصية id، يُدرج id: 0 في الأعلى، للجذر وللنماذج المرتبطة على حد سواء.
  • ما لم يضبط @Table الخيار timestamps: false، يُلحق createdAt وupdatedAt؛ وتُحترم إعادة التسمية مثل createdAt: "created_on" وupdatedAt: false وparanoid: true (deletedAt: null) لكل نموذج.
  • يصبح Post[] من @HasMany مصفوفة؛ ويصبح @BelongsTo و@HasOne كائنات متداخلة.
  • الاتحادات الحرفية مثل "draft" | "sent" تستخدم القيمة الأولى، وكل ما يُورث عبر extends Model يُتجاهل.
  • عمود DataType.JSON نوعه كائن، مثل { theme: string }، يُملأ بذلك الشكل.

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

توثيق handlers في Express

لنقاط النهاية التي تفعل res.json(await Invoice.findByPk(id))، يعطيك الناتج مثال استجابة تطابق مفاتيحه الواقع، بما فيها السمات المضافة تلقائيًا.

قبل تفعيل الحذف الناعم وبعده

تفعيل paranoid يضيف deletedAt إلى كل استجابة. قارن الناتج مع تفعيل الخيار وتعطيله لتخبر مستهلكي الـ API بالضبط بما سيتغير.

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

  • النماذج المرتبطة المتداخلة داخل الجذر تحصل على id وطوابع زمنية خاصة بها من خيارات @Table الخاصة بها، لكن المفاتيح الأجنبية التي يضيفها Sequelize ضمنيًا (مثل invoiceId على هدف @HasMany ليس فيه عمود @ForeignKey) لا تُختلق.
  • تُتجاهل allowNull وإعادة تسمية الأعمدة عبر @Column({ field: ... })، لأن مفاتيح JSON هي أسماء الخصائص. ويُستخدم @Default("x") وdefaultValue الحرفي في @Column({...}) قيمًا نموذجية.
  • لا يغيّر underscored: true إلا أسماء أعمدة قاعدة البيانات؛ ويظل toJSON() يستخدم أسماء السمات، فيكون createdAt في الناتج صحيحًا.
  • تأتي القيم من أنواع TypeScript، لذا فالخاصية التي لا يحدد نوعها إلا الـ decorator (@Column(DataType.INTEGER) count; دون تلميح) تصبح null.

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

هل أحدد نوع عمود DECIMAL بـ number أم string؟

مع MySQL وPostgreSQL يُرجع Sequelize قيم DECIMAL كسلاسل نصية افتراضيًا. تحديد النوع بالشكل amount: string يُبقي النوع صادقًا، وسيُظهر المثال هنا سلسلة نصية أيضًا.

هل يمكنني استخدام حقول declare أو CreationOptional؟

نعم. يُقرأ declare id: CreationOptional<number> على أنه number، ويُطبَّق فك التغليف نفسه على NonAttribute<...> وForeignKey<...>. أما الأنواع المساعدة الأخرى، مثل InferAttributes، فلا تُوسَّع.

هل تتعامل هذه الصفحة مع نماذج sequelize.define المكتوبة بـ JavaScript؟

لا. هذه الصفحة تقرأ الأصناف وأنواع TypeScript. استخدم صفحة Sequelize (JS) إلى JSON لنماذج define وModel.init، فهي تقرأ DataTypes بدلًا من ذلك.