Populate

Populate starts with an explicit ref. Mongster does not infer relationships from naming conventions or separate relation metadata.

import { Post } from "./models";

const posts = await Post.find({}).populate("authorId", {
  select: ["name", "email"],
  excludeId: false,
});

console.log(posts[0].authorId);
                       
authorId: {
    name: string;
    email: string;
    _id: ObjectId;
} | null

Rules to remember

• The field must be declared as M.objectId().ref(() => Model).
• Populate currently works on top-level ref fields only.
• Array refs are not populatable yet.
• Nested populate paths are not supported.
• If the lookup does not match anything, Mongster normalizes the populated field back to null.
• Trying to populate a non-ref field raises a QueryError whose message names the offending field and points you at .ref(() => Model).

Select only what you need

Use select to limit fields from the populated document and excludeId when you want to omit _id from the populated payload.

ref() is terminal for now

At the moment, .ref() is the end of the chain. Do not add optional(), nullable(), default(), or defaultFn() after it.