Chapter 85 — Mongoose with TypeScript

// modules/users/user.model.ts
import { Schema, model, type Model, type HydratedDocument, type Types } from "mongoose";
import bcrypt from "bcrypt";

export type Role = "admin" | "user";

// 1. Raw document shape
export interface IUser {
  email: string;
  name: string;
  password: string;
  role: Role;
  isActive: boolean;
  orgId?: Types.ObjectId;
  createdAt: Date;
  updatedAt: Date;
}

// 2. Instance methods
export interface IUserMethods {
  comparePassword(candidate: string): Promise<boolean>;
}

// 3. Model type with statics
export interface UserModel extends Model<IUser, {}, IUserMethods> {
  findByEmail(email: string): Promise<UserDocument | null>;
}

export type UserDocument = HydratedDocument<IUser, IUserMethods>;

const userSchema = new Schema<IUser, UserModel, IUserMethods>(
  {
    email:    { type: String, required: true, unique: true, lowercase: true, trim: true },
    name:     { type: String, required: true, trim: true, maxlength: 80 },
    password: { type: String, required: true, select: false, minlength: 8 },
    role:     { type: String, enum: ["admin", "user"], default: "user" },
    isActive: { type: Boolean, default: true },
    orgId:    { type: Schema.Types.ObjectId, ref: "Org" },
  },
  { timestamps: true },
);

// Methods — `this` is typed as UserDocument
userSchema.method("comparePassword", function (candidate: string) {
  return bcrypt.compare(candidate, this.password);
});

// Statics — `this` is typed as UserModel
userSchema.static("findByEmail", function (email: string) {
  return this.findOne({ email: email.toLowerCase() }).select("+password");
});

// Hooks — Mongoose 8 supports async hooks without calling next()
userSchema.pre("save", async function () {
  if (!this.isModified("password")) return;
  this.password = await bcrypt.hash(this.password, 12);
});

// Remove secrets from every JSON response
userSchema.set("toJSON", {
  virtuals: true,
  versionKey: false,
  transform: (_doc, ret: Record<string, unknown>) => {
    delete ret.password;
    delete ret._id;          // `id` virtual (string) is kept instead
    return ret;
  },
});

export const User = model<IUser, UserModel>("User", userSchema);

const user = await User.findByEmail("a@b.com");   // UserDocument | null
if (user && (await user.comparePassword("secret"))) {
  user.role;                                      // "admin" | "user"
  // user.rol                                     ❌ compile error
}

import { Schema, model, type InferSchemaType, type HydratedDocument } from "mongoose";

const productSchema = new Schema(
  {
    name:  { type: String, required: true },
    price: { type: Number, required: true, min: 0 },
    tags:  { type: [String], default: [] },
    stock: { type: Number, default: 0 },
    category: { type: String, enum: ["book", "electronics", "toy"] as const, required: true },
  },
  { timestamps: true },
);

export type IProduct = InferSchemaType<typeof productSchema>;
// {
//   name: string; price: number; tags: string[]; stock: number;
//   category: "book" | "electronics" | "toy";
//   createdAt: NativeDate; updatedAt: NativeDate;
// }
export type ProductDocument = HydratedDocument<IProduct>;
export const Product = model("Product", productSchema);

import { Schema, model, type Types } from "mongoose";
import type { IUser } from "../users/user.model.js";

export interface IOrderItem { product: Types.ObjectId; qty: number; price: number }
export interface IOrder {
  user: Types.ObjectId;
  items: IOrderItem[];
  total: number;
  status: "pending" | "paid" | "shipped" | "cancelled";
}

const orderSchema = new Schema<IOrder>(
  {
    user:  { type: Schema.Types.ObjectId, ref: "User", required: true, index: true },
    items: [{
      product: { type: Schema.Types.ObjectId, ref: "Product", required: true },
      qty:     { type: Number, required: true, min: 1 },
      price:   { type: Number, required: true },
    }],
    total:  { type: Number, required: true },
    status: { type: String, enum: ["pending", "paid", "shipped", "cancelled"], default: "pending" },
  },
  { timestamps: true },
);
export const Order = model<IOrder>("Order", orderSchema);

// Without the generic, order.user stays Types.ObjectId after populate.
// Tell TS what populate replaced:
const order = await Order.findById(id)
  .populate<{ user: Pick<IUser, "name" | "email"> }>("user", "name email")
  .orFail();                     // throws DocumentNotFoundError instead of returning null

order.user.email;                // ✅ string

// Hydrated: full Document with getters, save(), virtuals — slower, more memory
const doc = await User.findById(id);           // UserDocument | null

// Lean: plain JS object — 3-5x faster for read-only endpoints
const plain = await User.findById(id).lean();  // (IUser & { _id: Types.ObjectId; __v: number }) | null
// plain.comparePassword  ❌ no methods on lean objects
// plain.save()           ❌

// modules/users/user.service.ts
import type { FilterQuery } from "mongoose";
import { User, type IUser } from "./user.model.js";
import { AppError } from "../../utils/AppError.js";
import type { Paginated } from "@app/shared";

export const userService = {
  async list(opts: { page: number; limit: number; search?: string }): Promise<Paginated<IUser>> {
    const filter: FilterQuery<IUser> = { isActive: true };
    if (opts.search) filter.name = { $regex: escapeRegex(opts.search), $options: "i" };

    const [items, total] = await Promise.all([
      User.find(filter)
        .sort({ createdAt: -1 })
        .skip((opts.page - 1) * opts.limit)
        .limit(opts.limit)
        .lean<IUser[]>(),
      User.countDocuments(filter),
    ]);
    return { items, total, page: opts.page, limit: opts.limit };
  },

  async findById(id: string) {
    const user = await User.findById(id);
    if (!user) throw AppError.notFound("User");
    return user.toJSON();
  },

  async update(id: string, patch: Partial<Pick<IUser, "name" | "role">>) {
    const user = await User.findByIdAndUpdate(id, patch, {
      new: true,             // return the updated doc
      runValidators: true,   // validators are OFF by default on updates!
    });
    if (!user) throw AppError.notFound("User");
    return user.toJSON();
  },
};

function escapeRegex(s: string) {
  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");   // prevents ReDoS/regex injection
}

import mongoose from "mongoose";

export async function placeOrder(userId: string, items: { productId: string; qty: number }[]) {
  const session = await mongoose.startSession();
  try {
    return await session.withTransaction(async () => {
      let total = 0;
      for (const { productId, qty } of items) {
        // Atomic decrement only if stock is sufficient
        const p = await Product.findOneAndUpdate(
          { _id: productId, stock: { $gte: qty } },
          { $inc: { stock: -qty } },
          { new: true, session },
        );
        if (!p) throw AppError.conflict(`Insufficient stock for ${productId}`);
        total += p.price * qty;
      }
      const [order] = await Order.create(
        [{ user: userId, items: items.map((i) => ({ product: i.productId, qty: i.qty, price: 0 })), total }],
        { session },
      );
      return order;
    });
  } finally {
    await session.endSession();
  }
}

import mongoose from "mongoose";

export async function connectDB(uri: string) {
  mongoose.set("strictQuery", true);       // unknown filter fields are dropped
  mongoose.connection.on("connected", () => console.log("Mongo connected"));
  mongoose.connection.on("error", (err: Error) => console.error("Mongo error", err));
  mongoose.connection.on("disconnected", () => console.warn("Mongo disconnected"));

  await mongoose.connect(uri, {
    maxPoolSize: 10,
    serverSelectionTimeoutMS: 5000,
    autoIndex: process.env.NODE_ENV !== "production",   // build indexes via migrations in prod
  });
}