Deleting Documents — deleteOne, deleteMany and Soft Deletes

Deleting data sounds simple — but in a production application it is one of the most consequential operations you can perform. A hard delete removes data permanently with no undo. For many MERN applications — particularly content platforms, e-commerce sites, and any system with audit requirements — a soft delete pattern is safer: you mark a document as deleted without actually removing it, which lets you recover accidentally deleted content, maintain audit trails, and satisfy data retention requirements. This lesson covers both approaches, when to use each, and how to implement them cleanly in Mongoose.

Delete Methods Overview #

Hard Delete — Permanent Removal #

// ── deleteOne — permanently delete by filter ──────────────────────────────────
const result = await Post.deleteOne({ _id: postId });
console.log(result.deletedCount); // 1 if found and deleted, 0 if not found

// ── findByIdAndDelete — delete by ID, return the deleted document ─────────────
const deleted = await Post.findByIdAndDelete(postId);
if (!deleted) throw new AppError('Post not found', 404);
// deleted is the document AS IT WAS before deletion

// ── doc.deleteOne() — delete a specific instance you already fetched ──────────
const post = await Post.findById(postId);
if (!post) throw new AppError('Post not found', 404);
// ... ownership check ...
await post.deleteOne(); // runs pre('deleteOne') hook if defined

// ── deleteMany — delete a group of documents ──────────────────────────────────
// Delete all draft posts older than 30 days
const thirtyDaysAgo = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000);
const result = await Post.deleteMany({
  published: false,
  createdAt: { $lt: thirtyDaysAgo },
});
console.log(`Deleted ${result.deletedCount} old drafts`);

Soft Delete Pattern #

// ── Step 1: Add deletedAt to the schema ───────────────────────────────────────
const postSchema = new mongoose.Schema({
  // ... other fields ...
  deletedAt: { type: Date, default: null }, // null = not deleted
}, { timestamps: true });

// ── Step 2: Add a query middleware to auto-filter deleted documents ────────────
// This pre-hook runs before EVERY find, findOne, findById, etc.
postSchema.pre(/^find/, function (next) {
  // 'this' is the Mongoose Query object
  // Only apply the filter if includeDeleted is not set
  if (!this.getOptions().includeDeleted) {
    this.where({ deletedAt: null });
  }
  next();
});

// ── Step 3: Soft delete method on the schema ──────────────────────────────────
postSchema.methods.softDelete = async function () {
  this.deletedAt = new Date();
  await this.save();
};

// ── Step 4: Usage in the controller ──────────────────────────────────────────
const deletePost = asyncHandler(async (req, res) => {
  const post = await Post.findById(req.params.id);
  if (!post) throw new AppError('Post not found', 404);
  if (post.author.toString() !== req.user.id && req.user.role !== 'admin') {
    throw new AppError('Not authorised', 403);
  }

  await post.softDelete(); // sets deletedAt — does NOT remove from database

  res.json({ success: true, message: 'Post deleted' });
});

// ── Step 5: Admin restore — clear deletedAt ──────────────────────────────────
const restorePost = asyncHandler(async (req, res) => {
  // Must use includeDeleted option to find soft-deleted documents
  const post = await Post.findById(req.params.id).setOptions({ includeDeleted: true });
  if (!post) throw new AppError('Post not found', 404);
  if (!post.deletedAt) throw new AppError('Post is not deleted', 400);

  post.deletedAt = null;
  await post.save();

  res.json({ success: true, message: 'Post restored', data: post });
});

Cascade Deletes — Cleaning Up Related Documents #

// When a post is permanently deleted, also delete its comments
postSchema.post('findOneAndDelete', async function (doc) {
  if (doc) {
    // doc is the deleted post document
    await Comment.deleteMany({ post: doc._id });
    console.log(`Deleted comments for post ${doc._id}`);
  }
});

// Or handle it explicitly in the controller
const deletePost = asyncHandler(async (req, res) => {
  const post = await Post.findByIdAndDelete(req.params.id);
  if (!post) throw new AppError('Post not found', 404);

  // Clean up related data
  await Comment.deleteMany({ post: post._id });
  // If you have uploaded files, delete them too:
  // if (post.coverImage) await deleteFileFromStorage(post.coverImage);

  res.json({ success: true, message: 'Post and its comments deleted' });
});

Hard Delete vs Soft Delete — Decision Guide #

Common Mistakes #

Mistake 1 — Hard-deleting without cleaning up references #

❌ Wrong — deleting a post without deleting its comments:

await Post.findByIdAndDelete(postId);
// Comments with postId still exist in the comments collection — orphaned data
// Any query to comments.find({ post: postId }) returns ghost comments

✅ Correct — always clean up related documents when hard deleting:

await Post.findByIdAndDelete(postId);
await Comment.deleteMany({ post: postId }); // ✓

Mistake 2 — Not checking deletedCount after deleteOne #

❌ Wrong — assuming the document existed and was deleted:

await Post.deleteOne({ _id: postId });
res.json({ success: true, message: 'Post deleted' }); // may have deleted nothing

✅ Correct — check whether anything was actually deleted:

const result = await Post.deleteOne({ _id: postId });
if (result.deletedCount === 0) throw new AppError('Post not found', 404);
res.json({ success: true, message: 'Post deleted' }); // ✓

Mistake 3 — Forgetting the pre-find hook for soft deletes #

❌ Wrong — implementing soft delete but forgetting to filter deleted documents from queries:

await Post.find({ published: true }); // also returns soft-deleted posts!

✅ Correct — the pre(/^find/) hook on the schema automatically adds { deletedAt: null } to all find queries, making soft-deleted documents invisible to normal queries.

Quick Reference #