Documentation about using populate() with TypeScript

[z164]

Do you want to request a feature or report a bug?
Bug

What is the current behavior?
Populating entity in any form (Model / Document) does not return actual type of populated doc in, instead it returns non-populated document type. It causes many type bindings like (as unknown as Actual type) and //@ts-ignores. Want to see a beam of light that it can be resolved in other way, than specified.

If the current behavior is a bug, please provide the steps to reproduce.
Literally any entity.populate()

What is the expected behavior?
Expected behavior is resolving "Not assignable types (Actual populated entity with nested object to Types.ObjectId)" TypeScript Error

What are the versions of Node.js, Mongoose and MongoDB you are using? Note that "latest" is not a version.
Node v16, MongoDB v4.4.5, Mongoose v5.12.7

[z164]

import * as mongoose from "mongoose";
import { Types } from "mongoose";

const SingleItemSchema = new mongoose.Schema({
  title: String,
  description: String,
});

const GroupOfItemsSchema = new mongoose.Schema({
  title: String,
  items: { type: [Types.ObjectId], ref: "SingleItem" },
});

type SingleDocument = {
  title: string;
  description: string;
} & mongoose.Document;

type GroupDocument = {
  title: string;
  items: [Types.ObjectId];
} & mongoose.Document;

interface IPopulatedGroup extends Omit<GroupDocument, "items"> {
  items: [
    {
      title: string;
      description: string;
    }
  ];
}

const singleModel = mongoose.model<SingleDocument>(
  "SingleItem",
  SingleItemSchema
);
const groupModel = mongoose.model<GroupDocument>(
  "GroupOfItems",
  GroupOfItemsSchema
);

async function main() {
  await mongoose.connect("mongodb://localhost:27017/issue");
  const single = await singleModel.create({
    title: "1",
    description: "First element",
  });
  const group = await groupModel.create({
    title: "Group of items",
    items: [single._id],
  });

  async function populateGroupDoc(
    group: GroupDocument
  ): Promise<IPopulatedGroup> {
    // need conversion to ANY on populated paths, like 'axios' does with his unknown fields
    /*{
	"resource": "/Projects/issue/index.ts",
	"owner": "typescript",
	"code": "2322",
	"severity": 8,
	"message": "Type 'GroupDocument' is not assignable to type 'IPopulatedGroup'.
    Types of property 'items' are incompatible.
    Type '[ObjectId]' is not assignable to type '[{ title: string; description: string; }]'.
    Type 'ObjectId' is missing the following properties from type '{ title: string; description: string; }': title, description",
	"source": "ts",
	"startLineNumber": 47,
	"startColumn": 7,
	"endLineNumber": 47,
	"endColumn": 52
}*/
    return group.populate("items").execPopulate();
  }

  async function populateGroupModel(
    groupModel: mongoose.Model<GroupDocument>,
    id: string
  ): Promise<IPopulatedGroup> {
    return groupModel.findById(id).populate("items");
  }

  async function populateGroupV2(group: GroupDocument): Promise<GroupDocument> {
    // has no ts-error
    return group.populate("items").execPopulate();
  }

  console.log(await populateGroupDoc(group));
  console.log(await populateGroupModel(groupModel, group._id));
  const populatedGroup = await populateGroupV2(group);
  console.log(populatedGroup);
  // Each populates Correctly

  populatedGroup.items.forEach((item) => {
    // Expects that item is stil Object.Id
    // Property 'title' does not exist on type 'ObjectId'.
    console.log(item.title);
  });

  mongoose.disconnect();
}

main();

[vkarpov15]

We recommend using Mongoose's PopulatedDoc type for this, it's a union type that says the given path can be an id or a populated doc. See below example:

import * as mongoose from "mongoose";
import { Types, PopulatedDoc } from "mongoose";

const SingleItemSchema = new mongoose.Schema({
  title: String,
  description: String,
});

const GroupOfItemsSchema = new mongoose.Schema({
  title: String,
  items: { type: [Types.ObjectId], ref: "SingleItem" },
});

type SingleDocument = {
  title: string;
  description: string;
} & mongoose.Document;

type GroupDocument = {
  title: string;
  items: PopulatedDoc<SingleDocument>[];
} & mongoose.Document;

const singleModel = mongoose.model<SingleDocument>(
  "SingleItem",
  SingleItemSchema
);
const groupModel = mongoose.model<GroupDocument>(
  "GroupOfItems",
  GroupOfItemsSchema
);

interface IPopulatedGroup extends Omit<GroupDocument, "items"> {
  items: SingleDocument[];
}

async function main() {
  await mongoose.connect("mongodb://localhost:27017/issue");
  const single = await singleModel.create({
    title: "1",
    description: "First element",
  });
  const group = await groupModel.create({
    title: "Group of items",
    items: [single._id],
  });

  async function populateGroupDoc(
    group: GroupDocument
  ): Promise<IPopulatedGroup> {
        return group.populate("items").execPopulate();
  }

  async function populateGroupModel(
    groupModel: mongoose.Model<GroupDocument>,
    id: string
  ): Promise<IPopulatedGroup> {
    return groupModel.findById(id).populate("items");
  }

  async function populateGroupV2(group: GroupDocument): Promise<GroupDocument> {
    // has no ts-error
    return group.populate("items").execPopulate();
  }

  console.log(await populateGroupDoc(group));
  console.log(await populateGroupModel(groupModel, group._id));
  const populatedGroup = await populateGroupV2(group);
  console.log(populatedGroup);
  // Each populates Correctly

  populatedGroup.items.forEach((item) => {
    console.log(item.title);
  });

  mongoose.disconnect();
}

main();

We should add a note to our docs about this.