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

أدخل مخططات Mongoose (JS) لإنشاء JSON تجريبي! يدعم Mongoose new Schema, mongoose.model. مفيد لتوثيق واجهات API وأجسام الطلبات التجريبية (mock request body).
Mongoose (JS)
النتيجة
 

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

ابنِ JSON مستند نموذجي من مخطط Mongoose بلغة JavaScript معرَّف بـ new Schema({...}). بما أن كائن تعريف المخطط نفسه هو ما يُحلَّل، تُتتبَّع خيارات مثل { type: String, enum: [...] } أو { type: Map, of: Number } والإشارات إلى متغيرات مخططات أخرى.

يفيد عند توثيق المجموعات خلف API مبني بـ Express + Mongoose، أو عند شرح شكل المستند للواجهة الأمامية. وتنتقل القواعد الخاصة بـ Mongoose، مثل حصول المستندات الفرعية في المصفوفات على _id بينما لا تحصل عليه المسارات المتداخلة.

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

  1. الصق ملف المخطط في خانة Mongoose (JS). إن كانت المخططات الفرعية في متغيرات منفصلة، فضمّن تعريفاتها في الإدخال نفسه.
  2. المخطط الذي لا يستخدمه أي مخطط آخر يصبح المستند الجذري؛ وإن وُجد أكثر من واحد، يُرتَّب الناتج بمفاتيح هي أسماء المتغيرات.
  3. راجع النتيجة وانسخها بزر النسخ.

مثال

المدخلات (Mongoose · JavaScript)
const variantSchema = new Schema({
  sku: String,
  price: Schema.Types.Decimal128,
  stock: { type: Number, default: 0 },
});

const productSchema = new Schema(
  {
    title: { type: String, required: true },
    variants: [variantSchema],
    dimensions: { width: Number, height: Number },
    labels: { type: Map, of: String },
  },
  { timestamps: { createdAt: "created_at", updatedAt: false } }
);
المخرجات (JSON)
{
  "_id": "507f1f77bcf86cd799439011",
  "title": "",
  "variants": [
    {
      "_id": "507f1f77bcf86cd799439011",
      "sku": "",
      "price": {
        "$numberDecimal": "0"
      },
      "stock": 0
    }
  ],
  "dimensions": {
    "width": 0,
    "height": 0
  },
  "labels": {
    "key": ""
  },
  "created_at": "1970-01-01T00:00:00.000Z",
  "__v": 0
}

variants: [variantSchema] مصفوفة مستندات فرعية، فيحصل كل عنصر على _id، بينما لا يوجد __v إلا في المستوى الأعلى. وdimensions ليس له type، فهو مسار متداخل بلا _id، ويظهر Decimal128 بصيغة toJSON() الخاصة به، $numberDecimal. ويعيد خيار timestamps تسمية الحقل إلى created_at ويعطّل updatedAt، فيبقى حقل تاريخ واحد.

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

  • يحصل المستند الجذري على _id و__v، مع احترام إعادة التسمية بـ versionKey: "rev" أو القيمة false.
  • المستندات الفرعية في المصفوفات مثل [subSchema] أو [{ name: String }] تحصل على _id، ما لم يضبط المخطط { _id: false }.
  • الكائنات المتداخلة بلا type (address: { city: String }) تبقى كائنات عادية بلا _id.
  • مصفوفات enum تعطي قيمتها الأولى، و{ type: Map, of: String } يعطي {"key": ""}، وSchema.Types.Mixed يعطي null.
  • يصبح Schema.Types.ObjectId سلسلة ObjectId نموذجية، ويصبح Decimal128 على شكل {"$numberDecimal": "0"}.
  • إلى جانب timestamps: true، تُقرأ الإعدادات التفصيلية مثل { createdAt: "created_at", updatedAt: false }.
  • الإشارات الدائرية بين المخططات تُقطع بـ null.

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

وثائق مجموعات تبقى دقيقة

حين يُظهر README أو wiki مستندًا نموذجيًا لكل مجموعة، فإن توليده من ملف المخطط يمنع الوثائق من الابتعاد عن الكود.

ملاحظة `_id` في المستندات الفرعية

كثيرًا ما تقارن الواجهات الأمامية عناصر المصفوفات دون إدراك أن كل عنصر يحمل _id خاصًا به. يوضّح الناتج على أي مستوى يظهر _id.

شرح الاستجابات قبل populate

الحقول ذات ref تبقى سلاسل ObjectId عادية حتى تُملأ بـ populate. استخدم الناتج خطَّ أساس عند وصف كيف تتغير الاستجابة بعد populate().

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

  • يُستخدم default الحرفي ("active"، 0، true) قيمةً نموذجية. أما القيم الافتراضية الدالية مثل Date.now فلا تُشغَّل، فتحصل تلك الحقول على القيمة البديلة للنوع بدلًا من ذلك.
  • الحقول ذات ref تبقى سلاسل ObjectId لا كائنات مملوءة.
  • الـ new Schema({...}, { _id: false }) المضمَّن المكتوب كقيمة لحقل يُحوَّل في مكانه ويحترم خياراته الخاصة؛ ولا يظهر كمدخل جذري مستقل.
  • لا تُطبَّق الـ virtuals ولا تحويلات toJSON ولا الـ getters ولا select: false.

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

لماذا يخرج حقل Decimal128 ككائن؟

يُسلسَل Decimal128 في Mongoose عبر toJSON() على شكل {"$numberDecimal": "12.50"}. إن كنت ترسله كرقم أو سلسلة نصية، فأضف getter أو transform إلى المخطط وعدّل الناتج ليطابقه.

هل يمكنني لصق مخططات TypeScript أو NestJS هنا؟

حوّل أصناف @Schema() والـ interfaces في صفحة Mongoose (TS) إلى JSON. هذه الصفحة تحلّل كائن JavaScript الممرَّر إلى new Schema().

ماذا لو كان الملف لا يحوي إلا mongoose.model() والمخطط في مكان آخر؟

يجب أن يكون تعريف المخطط في الإدخال. الصق جزء new Schema(...) معه.