API with NestJS #44. Implementing relationships with MongoDB

August 23, 2021

This entry is part 44 of 121 in the API with NestJS

An essential thing about MongoDB is that it is non-relational. Therefore, it might not be the best fit if relationships are a big part of our database design. That being said, we definitely can mimic SQL-style relations by using references of embedding documents directly.

You can get all of the code from this article in this repository.

Defining the initial schema

In this article, we base the code on many of the functionalities we’ve implemented in the previous parts of this series. If you want to know how we register and authenticate users, check out API with NestJS #3. Authenticating users with bcrypt, Passport, JWT, and cookies.

Let’s start by defining a schema for our users.

user.schema.ts

import { Prop, Schema, SchemaFactory } from '@nestjs/mongoose';

import { Document } from 'mongoose';

import { Exclude, Transform } from 'class-transformer';

export type UserDocument = User & Document;

@Schema()

export class User {

@Transform(({ value }) => value.toString())

_id: string;

@Prop({ unique: true })

email: string;

@Prop()

@Prop()

@Exclude()

password: string;

}

export const UserSchema = SchemaFactory.createForClass(User);

A few significant things are happening above. We use unique: true above to make sure that all users have unique emails. It sets up unique indexes under the hood and deserves a separate article.

The @Exclude and @Transform decorators come from the class-transformer library. We cover serialization in more detail in API with NestJS #5. Serializing the response with interceptors. There is a significant catch here with MongoDB and Mongoose, though.

The Mongoose library that we use for connecting to MongoDB and fetching entities does not return instances of our User class. Therefore, the ClassSerializerInterceptor won’t work out of the box. Let’s change it a bit using the mixin pattern.

mongooseClassSerializer.interceptor.ts

import {

ClassSerializerInterceptor,

PlainLiteralObject,

Type,

} from '@nestjs/common';

import { ClassTransformOptions, plainToClass } from 'class-transformer';

import { Document } from 'mongoose';

function MongooseClassSerializerInterceptor(

classToIntercept: Type,

): typeof ClassSerializerInterceptor {

return class Interceptor extends ClassSerializerInterceptor {

private changePlainObjectToClass(document: PlainLiteralObject) {

if (!(document instanceof Document)) {

return document;

}

return plainToClass(classToIntercept, document.toJSON());

}

private prepareResponse(

response: PlainLiteralObject | PlainLiteralObject[],

) {

if (Array.isArray(response)) {

return response.map(this.changePlainObjectToClass);

}

return this.changePlainObjectToClass(response);

}

serialize(

response: PlainLiteralObject | PlainLiteralObject[],

options: ClassTransformOptions,

) {

return super.serialize(this.prepareResponse(response), options);

}

};

}

export default MongooseClassSerializerInterceptor;

I wrote the above code with the help of Jay McDoniel. The official NestJS discord is a great place to ask for tips.

Above, we change MongoDB documents into instances of the provided class. Let’s use it with our controller:

authentication.controller.ts

import {

Body,

Controller,

Post,

UseInterceptors,

} from '@nestjs/common';

import { AuthenticationService } from './authentication.service';

import RegisterDto from './dto/register.dto';

import { User } from '../users/user.schema';

import MongooseClassSerializerInterceptor from '../utils/mongooseClassSerializer.interceptor';

@Controller('authentication')

@UseInterceptors(MongooseClassSerializerInterceptor(User))

export class AuthenticationController {

constructor(private readonly authenticationService: AuthenticationService) {}

@Post('register')

async register(@Body() registrationData: RegisterDto) {

return this.authenticationService.register(registrationData);

}

// ...

}

Thanks to doing the above, we exclude the password when returning the data of the user.

One-To-One

With the one-to-one relationship, the document in the first collection has just one matching document in the second collection and vice versa. Let’s create a schema for the address:

address.schema.ts

import { Prop, Schema, SchemaFactory } from '@nestjs/mongoose';

import { Document } from 'mongoose';

import { Transform } from 'class-transformer';

export type AddressDocument = Address & Document;

@Schema()

export class Address {

@Transform(({ value }) => value.toString())

_id: string;

@Prop()

city: string;

@Prop()

street: string;

}

export const AddressSchema = SchemaFactory.createForClass(Address);

There is a big chance that just one user is assigned to a particular address in our application. Therefore, it is a good example of a one-to-one relationship. Because of that, we can take advantage of embedding documents, which is an approach very good performance-wise.

For it to work properly, we need to explicitly pass AddressSchema to the @Prop decorator:

user.schema.ts

import { Prop, Schema, SchemaFactory } from '@nestjs/mongoose';

import { Document, ObjectId } from 'mongoose';

import { Exclude, Transform, Type } from 'class-transformer';

import { Address, AddressSchema } from './address.schema';

export type UserDocument = User & Document;

@Schema()

export class User {

@Transform(({ value }) => value.toString())

_id: ObjectId;

@Prop({ unique: true })

email: string;

@Prop()

@Prop()

@Exclude()

password: string;

@Prop({ type: AddressSchema })

@Type(() => Address)

address: Address;

}

export const UserSchema = SchemaFactory.createForClass(User);

We use @Type(() => Address) above to make sure that the class-transformer transforms the Address object too.

When we create the document for the user, MongoDB also creates the document for the address. It also gives it a distinct id.

In our one-to-one relationship example, the user has just one address. Also, one address belongs to only one user. Since that’s the case, it makes sense to embed the user straight into the user’s document. This way, MongoDB can return it fast. Let’s use MongoDB Compass to make sure that this is the case here.

One-To-Many

We implement the one-to-many and many-to-one relationships when a document from the first collection can be linked to multiple documents from the second collection. Documents from the second collection can be linked to just one document from the first collection.

Great examples are posts and authors where the user can be an author of multiple posts. In our implementation, the post can only have one author, though.

post.schema.ts

import { Prop, Schema, SchemaFactory } from '@nestjs/mongoose';

import { Document, ObjectId } from 'mongoose';

import * as mongoose from 'mongoose';

import { User } from '../users/user.schema';

import { Transform, Type } from 'class-transformer';

export type PostDocument = Post & Document;

@Schema()

export class Post {

@Transform(({ value }) => value.toString())

_id: ObjectId;

@Prop()

title: string;

@Prop()

content: string;

@Prop({ type: mongoose.Schema.Types.ObjectId, ref: User.name })

@Type(() => User)

author: User;

}

export const PostSchema = SchemaFactory.createForClass(Post);

Thanks to defining the above reference, we can now assign the user to the author property in the post.

posts.service.ts

import { Model } from 'mongoose';

import { Injectable } from '@nestjs/common';

import { InjectModel } from '@nestjs/mongoose';

import { Post, PostDocument } from './post.schema';

import PostDto from './dto/post.dto';

import { User } from '../users/user.schema';

@Injectable()

class PostsService {

constructor(@InjectModel(Post.name) private postModel: Model<PostDocument>) {}

create(postData: PostDto, author: User) {

const createdPost = new this.postModel({

...postData,

author,

});

return createdPost.save();

}

// ...

}

export default PostsService;

Populating the data with Mongoose

Saving the posts like that results in storing the id of the author in the database.

A great thing about it is that we can easily replace the id with the actual data using the populate function Mongoose provides.

posts.service.ts

import { Model } from 'mongoose';

import { Injectable } from '@nestjs/common';

import { InjectModel } from '@nestjs/mongoose';

import { Post, PostDocument } from './post.schema';

@Injectable()

class PostsService {

constructor(@InjectModel(Post.name) private postModel: Model<PostDocument>) {}

async findAll() {

return this.postModel.find().populate('author');

}

// ...

}

export default PostsService;

Doing the above results in Mongoose returning the data of the author along with the post.

The direction of the reference

In the code above, we store the id of the author in the document of the post. We could do that the other way around and store the posts’ id in the author’s document. When deciding that, we need to take a few factors into account.

First, we need to think of how many references we want to store. Imagine a situation where we want to store logs for different machines in our server room. We need to remember that the maximum size of a MongoDB document is 16MB. If we store an array of the ids of the Log document in the Machine document, in theory, we could run out of space at some point. We can store a single id of the machine in the Log document instead.

The other thing to think through is what queries we will run most often. For example, in our implementation of posts and authors, it is effortless to retrieve the author’s data if we have the post. This is thanks to the fact that we store the author’s id in the document of the post. On the other hand, it would be more time-consuming to retrieve a list of posts by a single user. To do that, we would need to query all of the posts and check the author’s id.

We could implement two-way referencing and store the reference on both sides to deal with the above issue. The above would speed up some of the queries but require us to put more effort into keeping our data consistent.

Embedding

We could also embed the document of the posts into the document of the user. The advantage of doing that would be not performing additional queries to the database to get the missing information. But, unfortunately, this would make getting a particular post more difficult.

Many-to-many

Another important relationship to consider is many-to-many. A document from the first collection can refer to multiple documents from the second collection and the other way around.

A good example would be posts that can belong to multiple categories. Also, a single category can belong to multiple posts. First, let’s define the schema of our category.

category.schema.ts

import { Prop, Schema, SchemaFactory } from '@nestjs/mongoose';

import { Document, ObjectId } from 'mongoose';

import { Transform } from 'class-transformer';

export type CategoryDocument = Category & Document;

@Schema()

export class Category {

@Transform(({ value }) => value.toString())

_id: ObjectId;

@Prop()

}

export const CategorySchema = SchemaFactory.createForClass(Category);

Now we can use it in the schema of the user.

user.schema.ts

import { Prop, Schema, SchemaFactory } from '@nestjs/mongoose';

import { Document, ObjectId } from 'mongoose';

import * as mongoose from 'mongoose';

import { User } from '../users/user.schema';

import { Transform, Type } from 'class-transformer';

import { Category } from '../categories/category.schema';

export type PostDocument = Post & Document;

@Schema()

export class Post {

@Transform(({ value }) => value.toString())

_id: ObjectId;

@Prop()

title: string;

@Prop()

content: string;

@Prop({ type: mongoose.Schema.Types.ObjectId, ref: User.name })

@Type(() => User)

author: User;

@Prop({

type: [{ type: mongoose.Schema.Types.ObjectId, ref: Category.name }],

})

@Type(() => Category)

categories: Category;

}

export const PostSchema = SchemaFactory.createForClass(Post);

A thing worth knowing is that we can also use the populate method right after saving our document.

import { Model } from 'mongoose';

import { Injectable } from '@nestjs/common';

import { InjectModel } from '@nestjs/mongoose';

import { Post, PostDocument } from './post.schema';

import PostDto from './dto/post.dto';

import { User } from '../users/user.schema';

@Injectable()

class PostsService {

constructor(@InjectModel(Post.name) private postModel: Model<PostDocument>) {}

async create(postData: PostDto, author: User) {

const createdPost = new this.postModel({

...postData,

author,

});

await createdPost.populate('categories').execPopulate();

return createdPost.save();

}

// ...

}

export default PostsService;

An important thing above is that we call the populate method on an instance of a MongoDB document. Since that’s the case, we also need to call execPopulate for it to run. This is not needed in the rest of our examples where we call populate on an instance of the MongoDB query.

Summary

In this article, we’ve covered defining relationships between documents in MongoDB using NestJS. We’ve learned various types of relationships and considered how to store the references to increase the performance. We’ve also touched on the subject of how to implement serialization with NestJS and MongoDB. There is still quite a lot to learn, so stay tuned!

Series Navigation<< API with NestJS #43. Introduction to MongoDBAPI with NestJS #45. Virtual properties with MongoDB and Mongoose >>

18 Comments

Oldest

Newest Most Voted

Inline Feedbacks

View all comments

ola

3 years ago

I love this series thanks dude, but how can i apply this to suit my code base i use postgres, sequelize, express and nodejs, is this possible to suit my code? i am reffering to the series that you use postgress, typeorm nestjs

Last edited 3 years ago by ola

Author

Marcin Wanago

3 years ago

Reply to ola

If you don’t use NestJS in your code but use Express, you might be interested in my TypeScript Express series.

Chris

3 years ago

Reply to Marcin Wanago

Hi! I’m too excited with this serie-course!!! Please! Keep it up! Will you add more topics?

Author

Marcin Wanago

3 years ago

Reply to Chris

Thank you. I’ve just published a new article in this series 🙂

Ryan Nguyen

3 years ago

Reply to Marcin Wanago

Your series are fantastic!

Juan González

3 years ago

Hello,

I have in my code Rol.schema

@Prop({
    type: { type: mongoose.Schema.Types.ObjectId, ref: Permission.name },
  })
  @Type(() => Permission)
  permissions: Permission;

Doing:
await createdRol.populate(‘permissions’).execPopulate();

Error:

Property ‘execPopulate’ does not exist on type ‘Promise<Rol & Document<any, any, any> & { _id: any; }>’.

Thanks for your answer.

John

2 years ago

Reply to Juan González

Hello, execPopulate is no longer available so you need just to use
await createdRol.populate(‘permissions’);

Seghosimhe David

2 years ago

Hello Marcin Wanago,
Please How can I get to see your DTO for the register user

Author

Marcin Wanago

2 years ago

Reply to Seghosimhe David

You can find all of the code from this article here:
https://github.com/mwanago/nestjs-mongodb

Gürkan

2 years ago

Love your posts so much. This series taught me many things about backend development!

Adrian Gonzalez

2 years ago

I have the following error:

@Prop({ type: mongoose.Schema.Types.ObjectId, ref: User.name })

TypeError: Cannot read properties of undefined (reading 'name')

My code here is:

@Schema()

export class News {

@Prop({ type: mongoose.Schema.Types.ObjectId, ref: User.name })

@Type(()=>User)

author: User;

}

And for user:

export type UserDocument = User & Document;

@Schema()

export class User {

@Transform(({ value }) => value.toString())

_id: string;

@Type(() => News)

news: News[];

}

export const UserSchema = SchemaFactory.createForClass(User);

Someone know what’s wrong? Any suggestion?
(imports are all correctly imported)

Author

Marcin Wanago

2 years ago

Reply to Adrian Gonzalez

Hi. Looks like you have a circular dependency in your imports. The “User” being undefined is what might happen in a case like that.
https://dev.wanago.io/2022/02/28/api-nestjs-circular-dependencies/

Illia

2 years ago

Hi, I have a problem with MongooseClassSerializerInterseptor. It works as intended for class-transformer but it also mutates _id on the output. I get different _id for the same entity every time on client.

My user.schema.ts

import { Prop, Schema, SchemaFactory } from '@nestjs/mongoose';

import { Exclude, Transform } from 'class-transformer';

import { Document } from 'mongoose';

export type UserDocument = User & Document;

@Schema()

export class User {

// TODO: create abstract generic class that will encapsulate common fields (like: _id, createAt, etc)

@Transform(({ value }) => value.toString())

_id: string;

@Prop({ required: true })

firstName: string;

@Prop({ required: true })

lastName: string;

@Prop({ required: true, unique: true })

email: string;

@Prop({ required: true })

@Exclude()

password: string;

@Prop()

@Exclude()

public refreshToken: string;

@Prop({ default: Date.now })

createdAt: Date;

}

export const UserSchema = SchemaFactory.createForClass(User);

Fapalz

2 years ago

Reply to Illia

I have the same problem! did you solve it?

Ben

2 years ago

Reply to Illia

I had the same issue. This worked for me:

On the schema, instead of this:

1 2	@Transform(({ value }) => value.toString()) _id: ObjectId;

Do this:

1 2	@Transform(value => value.obj._id.toString()) _id: ObjectId;

YEE

2 years ago

I love u!!!!

Ashish

1 year ago

Please share the solution for typeORM with mongoDB to implement many to many bidirectional relation in NEST
I am getting this error – TypeError: Cannot read properties of undefined (reading ‘_id’)I have used many-to-many bi-directional relation in employees and meetings entity, firstly I added meeting link and then added attendees as array , the meeting is getting saved but the above error is coming. (Without adding the attendees, no such error comes).I have been looking into this for so long

Ahmad

1 year ago

Reply to Ashish

Look here: https://github.com/typeorm/typeorm/issues/4190