Consultas do Mongoose, encadeamento e documentos enxutos

Mongoose Query Objects

const User = require('./models/user');

// This does NOT execute immediately — returns a Query object
const query = User.find({ active: true });

// Now execute it with await
const users = await query;

// Or chain modifiers before executing:
const result = await User.find({ active: true })
  .sort({ createdAt: -1 })
  .limit(10)
  .select('name email -_id');
  // select() projects fields: '+field' includes, '-field' excludes

Chaining Query Modifiers

const orders = await Order
  .find({ status: 'completed', userId: currentUserId })
  .sort({ createdAt: -1 })              // newest first
  .skip(page * pageSize)                // pagination offset
  .limit(pageSize)                      // page size
  .select('_id total status createdAt') // projection
  .lean();                              // return plain objects (discussed next)

console.log('Orders on this page:', orders.length);

The .lean() Method: Raw POJO Performance

// Without .lean() — heavy Mongoose Document objects
const docsWithMethods = await User.find({ active: true });
// docsWithMethods[0].save() works, but incurs overhead

// With .lean() — plain JavaScript objects, much faster
const pureObjects = await User.find({ active: true }).lean();
// pureObjects[0].save() does NOT work — it's a plain object
// But JSON.stringify, spread operators, and array methods are all faster

console.log(typeof docsWithMethods[0].save); // 'function'
console.log(typeof pureObjects[0].save);     // 'undefined'

When to Use .lean() vs Full Documents

// API read endpoint — use .lean() for speed
router.get('/products', async (req, res) => {
  const products = await Product.find({}).lean(); // fastest, no doc wrapper
  res.json(products);
});

// Update endpoint — use full Mongoose document to access instance methods
router.post('/users/:id/deactivate', async (req, res) => {
  const user = await User.findById(req.params.id); // full document, NO .lean()
  await user.sendDeactivationEmail(); // instance method won't work with .lean()
  user.active = false;
  await user.save(); // document method won't work with .lean()
  res.json({ success: true });
});

findById and findOne Convenience Methods

// findById — automatic ObjectId conversion from string
const user = await User.findById('64a1b2c3d4e5f6789012345a').lean();

// findByIdAndUpdate — find, update, and return result atomically
const updatedProduct = await Product.findByIdAndUpdate(
  productId,
  { $set: { price: 199.99 }, $inc: { updateCount: 1 } },
  { new: true, runValidators: true }  // return new doc, run validators
);

// findByIdAndDelete — find and delete atomically
const deletedUser = await User.findByIdAndDelete(userId);
console.log('Deleted:', deletedUser ? deletedUser.email : 'not found');

Counting Documents

// Exact count with filter — uses an index if available
const activeUsers = await User.countDocuments({ active: true, role: 'user' });
console.log('Active users:', activeUsers);

// Fast approximate count — no filter, uses collection stats
const totalProducts = await Product.estimatedDocumentCount();
console.log('Approximate total products:', totalProducts);

// In Express pagination:
const [data, total] = await Promise.all([
  User.find({}).skip(offset).limit(pageSize).lean(),
  User.countDocuments({})
]);
res.json({ data, total, pages: Math.ceil(total / pageSize) });

Populate: Resolving References

const Order = mongoose.model('Order', new mongoose.Schema({
  userId: { type: mongoose.Schema.Types.ObjectId, ref: 'User' },
  productIds: [{ type: mongoose.Schema.Types.ObjectId, ref: 'Product' }]
}));

// Populate the userId reference with the full User document
const order = await Order
  .findById(orderId)
  .populate('userId', 'name email')    // only select name and email from User
  .populate('productIds', 'name price') // populate array of references
  .lean();

console.log(order.userId.email);      // 'alice@example.com'
console.log(order.productIds[0].name); // 'Laptop'

Mongoose vs Native Driver: When to Choose

// Mongoose: ergonomic, validates, populate works
const user = await User.findOne({ email }).select('-password').populate('profile');

// Native driver: faster, raw, no middleware
const user = await db.collection('users')
  .findOne({ email }, { projection: { password: 0 } });

exec() and Error Handling

// With .exec() — explicit Promise conversion
const user = await User.findOne({ email }).exec();

// Without .exec() — implicit execution via await
const user = await User.findOne({ email });

// Error handling with try/catch (both forms work the same)
try {
  const user = await User.findById(id);
  if (!user) throw new Error('User not found');
} catch (err) {
  if (err.name === 'CastError') {
    res.status(400).json({ error: 'Invalid ID format' });
  } else {
    res.status(500).json({ error: err.message });
  }
}

Query Builder Pattern

async function searchProducts(filters) {
  let query = Product.find();

  if (filters.category) {
    query = query.where('category').equals(filters.category);
  }
  if (filters.maxPrice) {
    query = query.where('price').lte(filters.maxPrice);
  }
  if (filters.inStock) {
    query = query.where('stock').gt(0);
  }

  const sortField = filters.sortBy || 'createdAt';
  query = query.sort({ [sortField]: -1 }).limit(50).lean();

  return query; // executes here via await in the caller
}

Aggregate Pipeline in Mongoose

// Aggregation in Mongoose — bypasses Mongoose middleware and casting
const salesByRegion = await Order.aggregate([
  { $match: { status: 'completed' } },
  {
    $group: {
      _id: '$region',
      totalRevenue: { $sum: '$total' },
      orderCount: { $sum: 1 },
      avgOrder: { $avg: '$total' }
    }
  },
  { $sort: { totalRevenue: -1 } }
]);

// salesByRegion is a plain array — no Mongoose Document wrapper

Quick Check

Lesson Recap