حوّل مخططات Mongoose (TS) إلى JSON!

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

حوّل مخططات Mongoose (TS) إلى JSON!

أعطه أصناف @Schema() مكتوبة بـ @nestjs/mongoose في NestJS، أو interfaces عادية في TypeScript، فيُنتج مثالًا للمستند كما سيُصدّره toJSON(). تُضاف _id و__v وحقول الطوابع الزمنية وفق قواعد Mongoose نفسها، حتى لو لم يعرّفها الصنف.

استخدمه لتثبيت كائنات DTO للاستجابات في خدمة NestJS، أو للاتفاق مع فريقك على شكل مستندات الاختبار في مجموعة ما. وعلى خلاف صفحة JS، تُؤخذ القيم من أنواع خصائص TypeScript لا من خيارات @Prop().

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

  1. الصق ملف صنف المخطط في خانة Mongoose (TS)، بما في ذلك الأصناف المستخدمة كمستندات فرعية حتى تُملأ المصفوفات والكائنات المتداخلة.
  2. الصنف الذي لا يشير إليه غيره يصبح الجذر؛ تأكد من أن صنف المستند الرئيسي هو الذي يظهر في الناتج.
  3. غيّر خيارات مثل @Schema({ timestamps: true, versionKey: false }) وراقب تحديث createdAt و__v في النتيجة.

مثال

المدخلات (NestJS · @nestjs/mongoose)
@Schema({ _id: false })
export class Attachment {
  @Prop() url: string;
  @Prop() size: number;
}

@Schema({ timestamps: true, versionKey: false })
export class Message {
  @Prop({ type: Types.ObjectId, ref: "Room", required: true })
  roomId: Types.ObjectId;

  @Prop({ required: true })
  text: string;

  @Prop({ type: [Attachment], default: [] })
  attachments: Attachment[];

  @Prop()
  readAt?: Date;
}

export const MessageSchema = SchemaFactory.createForClass(Message);
المخرجات (JSON)
{
  "_id": "507f1f77bcf86cd799439011",
  "roomId": "507f1f77bcf86cd799439011",
  "text": "",
  "attachments": [
    {
      "url": "",
      "size": 0
    }
  ],
  "readAt": "1970-01-01T00:00:00.000Z",
  "createdAt": "1970-01-01T00:00:00.000Z",
  "updatedAt": "1970-01-01T00:00:00.000Z"
}

يشير Message إلى Attachment، لذا فإن Message هو الجذر. يُضاف _id في البداية، ويضيف timestamps: true حقلي تاريخ، ويحذف versionKey: false الحقل __v. ويصبح roomId ذو النوع Types.ObjectId سلسلة ObjectId نموذجية.

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

  • يحصل المستند الجذري على _id (الـ ObjectId النموذجي 507f1f77bcf86cd799439011) وعلى __v: 0 ما لم يكن versionKey: false؛ وقيمة versionKey النصية تعيد تسميته.
  • @Schema({ timestamps: true }) يُلحق createdAt وupdatedAt كسلاسل ISO.
  • يصبح Types.ObjectId وMongooseSchema.Types.ObjectId سلاسل ObjectId؛ ويصبح Types.Decimal128 والأنواع الرقمية الأخرى 0.
  • مصفوفات صنف آخر، مثل Attachment[]، تصبح مصفوفة من عنصر واحد مملوء من ذلك الصنف.
  • الأسماء البديلة للأنواع مثل type UserDocument = HydratedDocument<User> تُتجاهل عند اختيار الجذر، فيفوز صنف المخطط الحقيقي.
  • تعمل تعريفات interface العادية بلا @Schema أيضًا، فيمكن لصق interface نموذج مثل IUser كما هي.

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

استجابات NestJS وSwagger

حين تُرجع خدمةٌ this.model.find().lean() مباشرة، يُظهر هذا المفاتيح التي يستلمها العملاء بالضبط، بما فيها _id و__v اللذان يتسربان إلى الاستجابة.

مستندات اختبار لـ mongosh

عدّل الناتج ومرّره إلى db.messages.insertOne() لملء قاعدة بيانات محلية بسرعة. وغلّف سلاسل ObjectId بـ ObjectId("...") حين تفعل ذلك.

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

  • الأصناف المتداخلة المزيّنة بـ @Schema() تُعامل كمستندات فرعية: تحصل على _id خاص بها (ما لم يكن @Schema({ _id: false })) وعلى الطوابع الزمنية، لكن ليس على __v أبدًا. أما الأصناف المتداخلة بلا @Schema فتبقى كائنات عادية.
  • يُستخدم @Prop({ default: ... }) الحرفي قيمةً نموذجية؛ ولا تُقرأ خيارات required وenum. لمجموعة ثابتة من القيم، عرّف اتحادًا حرفيًا في TypeScript فتُستخدم قيمته الأولى.
  • Record<string, any> المعرَّف بـ @Prop({ type: Object }) يظهر على شكل {"key": null}.
  • لا تُطبَّق الـ virtuals ولا تحويلات toJSON ولا select: false.

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

الـ API لدي يعيد تسمية _id إلى id، لكن الناتج يُظهر _id.

يتبع الناتج toJSON() الافتراضي في Mongoose. إن كان مخططك يضيف id عبر toJSON: { virtuals: true } أو عبر transform، فأعد تسمية المفتاح في النتيجة.

ماذا لو كان النوع موجودًا في الخيارات فقط، مثل @Prop({ type: [String] })؟

تأتي القيم من النوع المُعلن للخاصية. مع tags: string[] تحصل على [""]؛ وبلا أي نوع TypeScript تكون القيمة مجهولة فتصبح null.

هل يمكنني تحويل new Schema({...}) بلغة JavaScript هنا؟

استخدم صفحة Mongoose (JS) إلى JSON لكائنات المخططات في JavaScript. فهي تقرأ خيارات المخطط مثل { type: String, enum: [...] } مباشرة.