Migrate from Mongoose

Mondel is intentionally not a Mongoose-compatible layer. Plan for API and mental-model changes.

What maps cleanly

Mongoose	Mondel
Schema paths	defineSchema + s.*
required, enum, min, max	.required(), .enum(), .min(), .max()
unique: true	.unique() / index options
timestamps: true	timestamps: true
Model.find	findMany
Model.findOne	findOne
Model.create	create / createMany
findByIdAndUpdate	findOneAndUpdate / updateById
countDocuments	count
Transactions via sessions	db.startSession() + { session }

What does not map 1:1

Mongoose feature	Mondel approach
Middleware (pre/post)	Explicit functions in your app layer
Virtuals	Compute in application code
Populate	$lookup aggregation or manual second query
Discriminators	Separate schemas / collections
Plugins	Compose your own helpers
Lean vs hydrated docs	Always plain objects
save() on documents	updateById / updateOne
Cast + coerce everywhere	Zod validation on writes; strict types

Schema example

// Mongoose-ish idea
// email: { type: String, required: true, unique: true }
// role: { type: String, enum: ["ADMIN", "USER"], default: "USER" }

import { defineSchema, s } from "mondel";

export const userSchema = defineSchema("users", {
  timestamps: true,
  fields: {
    email: s.string().required().email().unique(),
    role: s.enum(["ADMIN", "USER"]).default("USER"),
  },
});

Connection

Replace mongoose.connect + models with createClient (Client guide).

Indexes

Replace syncIndexes() on startup with:

npx mondel push --uri "$MONGODB_URI" --schema ./dist/schemas.js

Validation

Mongoose casts aggressively. Mondel’s strict mode throws on invalid shapes — closer to “fail fast” than silent cast. Use loose while porting dirty data.

Populate → lookup

const usersWithPosts = await db.users.aggregate([
  {
    $lookup: {
      from: "posts",
      localField: "_id",
      foreignField: "authorId",
      as: "posts",
    },
  },
]);

Suggested migration order

1. Read-only paths → findMany / findOne
2. Simple writes → create / updateOne
3. Remove document instance methods (user.save())
4. Replace middleware with service functions
5. Move indexes to CLI
6. Enable validation: "strict"