تحويل JSON إلى Sequelize (TypeScript) Schema!

أدخل JSON وحوله إلى Sequelize (TypeScript) Schema! يدعم sequelize-typescript @Table, @Column, Model, class-validator.
JSON
النتيجة
 

تحويل JSON إلى Sequelize (TypeScript) Schema!

يحوّل JSON إلى نموذج مبني على الـ decorators لمكتبة sequelize-typescript: صنف يرث Model مع @Table و@Column({ type: DataType.*, allowNull })، وأنواع TypeScript للخصائص، وdecorators من class-validator للتحقق.

يستهدف sequelize-typescript (المكتبة التي يقوم عليها @nestjs/sequelize في NestJS) لا sequelize المجردة، لذا يختلف مسار الاستيراد وتهجئة DataType (دون s في آخرها) عن نسخة JavaScript.

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

  1. الصق كائن JSON لصف واحد من الجدول، أو مصفوفة صفوف.
  2. أدخل اسم الصنف في اسم النموذج (الافتراضي MyModel)؛ ويصبح أيضًا tableName بصيغة upper snake case في @Table.
  3. احفظ النتيجة باسم invoice.model.ts وسجّلها بـ new Sequelize({ ..., models: [Invoice] }) أو بـ SequelizeModule.forFeature([Invoice]) في NestJS.

مثال

المدخلات (JSON)
{
  "invoice_no": "INV-2024-0042",
  "amount": 1250.75,
  "currency": "EUR",
  "paid": false,
  "due_date": "2024-07-31",
  "memo": ""
}
المخرجات (sequelize-typescript)
import { Table, Column, Model, DataType } from 'sequelize-typescript';
import { IsNotEmpty, IsOptional } from 'class-validator';

@Table({ tableName: 'INVOICE', timestamps: false })
export class Invoice extends Model<Invoice> {
  @Column({ type: DataType.INTEGER, primaryKey: true, autoIncrement: true })
  id: number;

  @Column({ type: DataType.STRING, allowNull: false, field: 'invoice_no' })
  @IsNotEmpty()
  invoiceNo: string;

  @Column({ type: DataType.DOUBLE, allowNull: false })
  @IsNotEmpty()
  amount: number;

  @Column({ type: DataType.STRING, allowNull: false })
  @IsNotEmpty()
  currency: string;

  @Column({ type: DataType.BOOLEAN, allowNull: false })
  @IsNotEmpty()
  paid: boolean;

  @Column({ type: DataType.DATEONLY, allowNull: false, field: 'due_date' })
  @IsNotEmpty()
  dueDate: string;

  @Column({ type: DataType.STRING, allowNull: false })
  @IsOptional()
  memo: string;
}

memo سلسلة فارغة: ليست NULL، لذا يُبقي العمود allowNull: false، لكنه يحصل على @IsOptional() لا @IsNotEmpty(). ويصبح amount من نوع DataType.DOUBLE، ويصبح due_date من نوع DataType.DATEONLY بنوع string، لأن Sequelize يُرجع القيم التي هي تاريخ فقط كنص.

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

  • يستورد { Table, Column, Model, DataType } من sequelize-typescript ويعرّف الصنف بالشكل extends Model<Invoice>.
  • @Table({ tableName: 'INVOICE', timestamps: false })، مطابقًا لمولّد JavaScript، فلا تُفترض أعمدة createdAt/updatedAt.
  • كل @Column يذكر type وallowNull؛ والأعمدة القابلة لـ null نوعها string | null وهكذا.
  • أزواج الأنواع: INTEGER/BIGINT/DOUBLE → number، وBOOLEAN → boolean، وDATE → Date، وDATEONLY → string، وJSON → Record<string, unknown> أو مصفوفة ذات نوع مثل string[].
  • الخصائص بصيغة camelCase مع field: 'invoice_no' يشير إلى العمود الأصلي؛ ومفتاح id في JSON يُستخدم مفتاحًا أساسيًا لا يُكرَّر.
  • الحقول التي لها قيمة غير فارغة في كل صف تحصل على @IsNotEmpty()؛ والبقية تحصل على @IsOptional().

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

نماذج NestJS مع `@nestjs/sequelize`

حين تحتاج إلى حفظ بيانات يرسلها نظام فوترة أو تسويات خارجي بصيغة JSON، ابنِ صنف النموذج من ذلك الـ payload واستخدمه عبر @InjectModel(Invoice).

تحويل نماذج Sequelize في JavaScript إلى كود ذي أنواع

صدّر بيانات الجدول الحالية كـ JSON والصقها لتحصل على مسودة نموذج ذي أنواع، بدلًا من إعادة كتابة كائن define() كصنف يدويًا.

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

  • للمبالغ المالية والأعداد العشرية الدقيقة الأخرى، DataType.DECIMAL(12, 2) أكثر أمانًا من DataType.DOUBLE.
  • يجب تفعيل experimentalDecorators وemitDecoratorMetadata في tsconfig لتعمل الـ decorators.
  • مع useDefineForClassFields (الافتراضي حين يكون target هو ES2022 أو أحدث)، تحجب تعريفات الخصائص العادية الـ getters الخاصة بـ Sequelize. عطّل ذلك الخيار أو أضف declare قبل الخصائص.

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

ألا يجب أن يكون Model<InvoiceAttributes, InvoiceCreationAttributes> بدلًا من Model<Invoice>؟

يقبل sequelize-typescript v2 معاملَي نوع عامّين؛ والكود المولَّد يمرّر الصنف نفسه ببساطة. إن أردت فحص أنواع Invoice.create({...}) دون الحقول المولَّدة تلقائيًا مثل id، فعرّف واجهة لسمات الإنشاء ومرّرها كمعامل النوع الثاني.

لماذا DataType لا DataTypes؟

DataType هو الاسم الذي تُصدِّره sequelize-typescript. استيراد DataTypes من sequelize يعمل بالطريقة نفسها، لكن الالتزام باسم واحد في كل ملف أوضح للقراءة.

هل تُفحص decorators من class-validator تلقائيًا على النموذج؟

لا. لا يحدث التحقق إلا حين تستدعي validate(invoice) بنفسك أو حين تكون الـ decorators على DTO يعالجه ValidationPipe في NestJS. للتحقق على مستوى Sequelize، استخدم @Column({ validate: { notEmpty: true } }) أو decorators من sequelize-typescript مثل @NotEmpty.