Mongoose Schemas, Models, and Virtuals

What Is Mongoose?

// Install Mongoose
// npm install mongoose

const mongoose = require('mongoose');

// Connect to MongoDB
await mongoose.connect(process.env.MONGODB_URI);
console.log('Mongoose connected to MongoDB');

Defining a Schema

const { Schema } = mongoose;

const userSchema = new Schema({
  name: {
    type: String,
    required: [true, 'Name is required'],
    trim: true,
    maxlength: 100
  },
  email: {
    type: String,
    required: true,
    unique: true,
    lowercase: true  // automatically converts to lowercase before saving
  },
  age: {
    type: Number,
    min: [0, 'Age cannot be negative'],
    max: 150
  },
  role: {
    type: String,
    enum: ['admin', 'user', 'guest'],
    default: 'user'
  },
  createdAt: {
    type: Date,
    default: Date.now
  }
});

Schema Types: Supported Types

const { Schema } = mongoose;
const { ObjectId } = Schema.Types;

const orderSchema = new Schema({
  customerId: { type: ObjectId, ref: 'User', required: true }, // reference to User model
  items: [
    {
      productId: { type: ObjectId, ref: 'Product' },
      quantity: { type: Number, min: 1 },
      price: Number
    }
  ],
  total: Number,
  status: { type: String, default: 'pending' },
  metadata: Schema.Types.Mixed,  // accepts any shape
  tags: [String],                // array of strings
  shippedAt: Date
});

Timestamps Option

const productSchema = new Schema(
  {
    name: { type: String, required: true },
    price: { type: Number, required: true },
    category: String,
    stock: { type: Number, default: 0 }
  },
  { timestamps: true }  // adds createdAt and updatedAt automatically
);

// Documents will have:
// { name: 'Laptop', price: 999, createdAt: Date, updatedAt: Date }

Creating a Model

// Define schema
const userSchema = new mongoose.Schema({
  name: String,
  email: { type: String, unique: true },
  role: { type: String, default: 'user' }
}, { timestamps: true });

// Compile the model
const User = mongoose.model('User', userSchema);
// This creates/uses the 'users' collection

module.exports = User;

// Usage in another file:
// const User = require('./models/user');
// const user = await User.findOne({ email: 'alice@example.com' });

Creating Documents With new Model()

// Method 1: new + save (two-step)
const user = new User({
  name: 'Alice',
  email: 'alice@example.com',
  role: 'admin'
});
await user.save(); // validates then saves to 'users' collection

// Method 2: User.create() shorthand
const user2 = await User.create({
  name: 'Bob',
  email: 'bob@example.com'
});
console.log('Created user ID:', user2._id);

// Method 3: insertMany for bulk
await User.insertMany([
  { name: 'Carol', email: 'carol@example.com' },
  { name: 'Dave', email: 'dave@example.com' }
]);

Virtual Properties

const personSchema = new mongoose.Schema({
  firstName: String,
  lastName: String,
  birthDate: Date
});

// Virtual: combines firstName and lastName
personSchema.virtual('fullName').get(function () {
  return this.firstName + ' ' + this.lastName;
  // Use regular function (not arrow function) to access 'this'
});

// Virtual with a setter for convenience
personSchema.virtual('fullName').get(function () {
  return this.firstName + ' ' + this.lastName;
}).set(function (v) {
  this.firstName = v.split(' ')[0];
  this.lastName = v.split(' ')[1];
});

const Person = mongoose.model('Person', personSchema);
const p = new Person({ firstName: 'Alice', lastName: 'Smith' });
console.log(p.fullName); // 'Alice Smith'

Including Virtuals in JSON Output

const userSchema = new mongoose.Schema(
  {
    firstName: String,
    lastName: String
  },
  {
    toJSON: { virtuals: true },    // include virtuals in res.json()
    toObject: { virtuals: true }   // include virtuals in .toObject()
  }
);

userSchema.virtual('fullName').get(function () {
  return this.firstName + ' ' + this.lastName;
});

const user = new User({ firstName: 'Alice', lastName: 'Smith' });
console.log(JSON.stringify(user)); // includes 'fullName': 'Alice Smith'

Custom Validation in Schemas

const productSchema = new mongoose.Schema({
  name: String,
  price: {
    type: Number,
    required: true,
    validate: {
      validator: function (v) {
        return v > 0; // price must be positive
      },
      message: props => 'Price must be positive, got ' + props.value
    }
  },
  sku: {
    type: String,
    validate: {
      validator: function (v) {
        return /^[A-Z]{2}-\d{4}$/.test(v); // format: AB-1234
      },
      message: 'SKU must match format AB-1234'
    }
  }
});

Schema Methods and Statics

const userSchema = new mongoose.Schema({ email: String, passwordHash: String });

// Instance method: available on each user document
userSchema.methods.checkPassword = function (candidatePassword) {
  return bcrypt.compare(candidatePassword, this.passwordHash);
};

// Static method: called on the User model
userSchema.statics.findByEmail = function (email) {
  return this.findOne({ email: email.toLowerCase() });
};

const User = mongoose.model('User', userSchema);

// Usage:
const user = await User.findByEmail('alice@example.com');  // static
const valid = await user.checkPassword('secret');          // instance method

Subdocuments vs Nested Schema Objects

// Nested object — no array, no _id per entry
const userSchema = new Schema({
  address: {
    street: String,
    city: String,
    zip: String
  }
});

// Array subdocuments — each item gets its own _id
const orderSchema = new Schema({
  items: [
    {
      productId: Schema.Types.ObjectId,
      quantity: Number,
      price: Number
      // _id auto-added to each item
    }
  ]
});

// Access subdocument by ID:
const item = order.items.id(someItemId);

Quick Check

Lesson Recap