- 1. API with NestJS #1. Controllers, routing and the module structure
- 2. API with NestJS #2. Setting up a PostgreSQL database with TypeORM
- 3. API with NestJS #3. Authenticating users with bcrypt, Passport, JWT, and cookies
- 4. API with NestJS #4. Error handling and data validation
- 5. API with NestJS #5. Serializing the response with interceptors
- 6. API with NestJS #6. Looking into dependency injection and modules
- 7. API with NestJS #7. Creating relationships with Postgres and TypeORM
- 8. API with NestJS #8. Writing unit tests
- 9. API with NestJS #9. Testing services and controllers with integration tests
- 10. API with NestJS #10. Uploading public files to Amazon S3
- 11. API with NestJS #11. Managing private files with Amazon S3
- 12. API with NestJS #12. Introduction to Elasticsearch
- 13. API with NestJS #13. Implementing refresh tokens using JWT
- 14. API with NestJS #14. Improving performance of our Postgres database with indexes
- 15. API with NestJS #15. Defining transactions with PostgreSQL and TypeORM
- 16. API with NestJS #16. Using the array data type with PostgreSQL and TypeORM
- 17. API with NestJS #17. Offset and keyset pagination with PostgreSQL and TypeORM
- 18. API with NestJS #18. Exploring the idea of microservices
- 19. API with NestJS #19. Using RabbitMQ to communicate with microservices
- 20. API with NestJS #20. Communicating with microservices using the gRPC framework
- 21. API with NestJS #21. An introduction to CQRS
- 22. API with NestJS #22. Storing JSON with PostgreSQL and TypeORM
- 23. API with NestJS #23. Implementing in-memory cache to increase the performance
- 24. API with NestJS #24. Cache with Redis. Running the app in a Node.js cluster
- 25. API with NestJS #25. Sending scheduled emails with cron and Nodemailer
- 26. API with NestJS #26. Real-time chat with WebSockets
- 27. API with NestJS #27. Introduction to GraphQL. Queries, mutations, and authentication
- 28. API with NestJS #28. Dealing in the N + 1 problem in GraphQL
- 29. API with NestJS #29. Real-time updates with GraphQL subscriptions
- 30. API with NestJS #30. Scalar types in GraphQL
So far, in this series, we’ve been creating an API that allows users to interact with our application. As soon as the client makes the request, we react to it and respond.
Sometimes though, we need to delay the execution of some logic or do so on a schedule. A common solution in the Unix world is cron. No wonder its syntax got adapted by various Node.js libraries.
In this article, we go through the cron syntax. We look into the @nestjs/schedule library that uses node-cron under the hood. We also use it together with the Nodemailer to schedule emails.
Setting up the Nodemailer
There are a few ways to set up the Nodemailer with NestJS. Although some libraries can integrate Nodemailer with NestJS, they don’t have a ton of downloads. Instead, we can use Nodemailer directly. First, let’s install it.
1 | npm install nodemailer @types/nodemailer |
To successfully send emails, we need a few environment variables:
.env
1 2 3 4 | EMAIL_SERVICE=gmail EMAIL_USER=nestjs.application@gmail.com EMAIL_PASSWORD=... # ... |
app.module.ts
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 | import { Module } from '@nestjs/common'; import { ConfigModule } from '@nestjs/config'; import * as Joi from '@hapi/joi'; @Module({ imports: [ ConfigModule.forRoot({ validationSchema: Joi.object({ EMAIL_SERVICE: Joi.string().required(), EMAIL_USER: Joi.string().required(), EMAIL_PASSWORD: Joi.string().required(), // ... }) }), // ... ], controllers: [], providers: [], }) export class AppModule {} |
In this simple example, we are using Gmail. If you want to use Gmail with Nodemailer, you need to turn on the less secure apps access as stated in the official Nodemailer documentation.
The last thing to do is to create a service that initializes the Nodemailer.
email.service.ts
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 | import { Injectable } from '@nestjs/common'; import { createTransport } from 'nodemailer'; import * as Mail from 'nodemailer/lib/mailer'; import { ConfigService } from '@nestjs/config'; @Injectable() export default class EmailService { private nodemailerTransport: Mail; constructor( private readonly configService: ConfigService ) { this.nodemailerTransport = createTransport({ service: configService.get('EMAIL_SERVICE'), auth: { user: configService.get('EMAIL_USER'), pass: configService.get('EMAIL_PASSWORD'), } }); } sendMail(options: Mail.Options) { return this.nodemailerTransport.sendMail(options); } } |
email.module.ts
1 2 3 4 5 6 7 8 9 10 11 | import { Module } from '@nestjs/common'; import EmailService from './email.service'; import { ConfigModule } from '@nestjs/config'; @Module({ imports: [ConfigModule], controllers: [], providers: [EmailService], exports: [EmailService] }) export class EmailModule {} |
With the above approach, we could switch the Nodemailer to any other solution we want without much impact on the rest of the application.
Using the schedule module built into NestJS
The most straightforward way to start using cron with NestJS is to install the @nestjs/schedule package.
1 | npm install @nestjs/schedule @types/cron |
There is a very good explanation of this library in the official documentation and I recommend looking into it
We also need to import it in our AppModule.
app.module.ts
1 2 3 4 5 6 7 8 9 10 11 12 | import { Module } from '@nestjs/common'; import { ScheduleModule } from '@nestjs/schedule'; @Module({ imports: [ ScheduleModule.forRoot(), // ... ], controllers: [], providers: [], }) export class AppModule {} |
The ScheduleModule.forRoot method initializes the scheduler. It also registers all the cron jobs we define declaratively across our application.
Defining cron jobs in a declarative way
When we look up the declarative programming on Wikipedia, we see that it expresses the logic of a computation without describing its control flow. In NestJS, we can use various decorators that allow us to set up cron jobs. Thanks to their declarative approach, we don’t need to worry about what happens under the hood.
Cron utilizes its own string format for scheduling, which can vary across implementations. The node-cron library allows us to specify six sections. Each one represents a unit of time.
1 2 3 4 5 6 7 8 9 | ┌────────────── second (optional) │ ┌──────────── minute │ │ ┌────────── hour │ │ │ ┌──────── day of the month │ │ │ │ ┌────── month │ │ │ │ │ ┌──── day of week (0 or 7 are Sunday) │ │ │ │ │ │ │ │ │ │ │ │ * * * * * * |
Not all systems allow us to specify the seconds. Even implementations in Node.js can vary because the cron package uses 0-6 for days of the week.
The asterisk (*) indicates that the event is scheduled to happen for any time unit value. Consider the following example:
emailScheduling.service.ts
1 2 3 4 5 6 7 8 9 10 | import { Injectable } from '@nestjs/common'; import { Cron } from '@nestjs/schedule'; @Injectable() export default class EmailSchedulingService { @Cron('* * * * * *') log() { console.log('Hello world!'); } } |
The Cron decorator also accepts a JavaScript Date object.
Above, the log method is called for any second, minute, hour, day of the month, month, and day of the week. This means that cron calls the log method every second.
We can change this behavior by replacing an asterisk with a number. If we do that, cron executes the method only if the current time matches our cron expression. For example, writing @Cron('0 0 8 * * 1') means scheduling the method to run only on Monday at 8:00:00 AM.
There are a lot of possibilities and characters that we can use in our expressions. Some of the examples are:
- 0 30 11 * * 6,7 – 11:30:00 on Saturday, and Sunday,
- 0 0 8 * 12 5-7 – 8:00:00 on Friday, Saturday, and Sunday (only in December),
- 0 */15 10-12 * * * – every 15 minutes between 10AM and 12AM.
NestJS has more decorators that we can use to set up cron jobs. One of them is the @Interval() that we can use to run a method at an interval specified as a number of milliseconds.
1 2 3 4 | @Interval(60000) log() { console.log('Called every minute'); } |
Aside from the above, we also have the @Timeout() decorator that allows us to run a method once while specifying the timeout with milliseconds.
1 2 3 4 | @Timeout(60000) log() { console.log('Called once after a minute'); } |
Using the dynamic schedule API to send emails
Aside from using various decorators to schedule cron jobs, we can also use the schedule module manually. Let’s create a simple endpoint that allows our users to schedule emails. First, let’s define the structure of the request body.
emailSchedule.dto.ts
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 | import { IsString, IsNotEmpty, IsDateString, IsEmail } from 'class-validator'; export class EmailScheduleDto { @IsEmail() recipient: string; @IsString() @IsNotEmpty() subject: string; @IsString() @IsNotEmpty() content: string; @IsDateString() date: string; } export default EmailScheduleDto; |
Once we define the Data Transfer Object, we can deal with the controller.
emailSchedule.controller.ts
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 | import { Body, Controller, UseGuards, Post, } from '@nestjs/common'; import JwtAuthenticationGuard from '../authentication/jwt-authentication.guard'; import EmailSchedulingService from './emailScheduling.service'; import EmailScheduleDto from './dto/emailSchedule.dto'; @Controller('email-scheduling') export default class EmailSchedulingController { constructor( private readonly emailSchedulingService: EmailSchedulingService ) {} @Post('schedule') @UseGuards(JwtAuthenticationGuard) async scheduleEmail(@Body() emailSchedule: EmailScheduleDto) { this.emailSchedulingService.scheduleEmail(emailSchedule); } } |
Above, we allow only logged in users to request this endpoint. If you want to know more, check out API with NestJS #3. Authenticating users with bcrypt, Passport, JWT, and cookies
The core logic of this scheduling resides in the EmailSchedulingService:
emailSchedule.service.ts
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 | import { Injectable } from '@nestjs/common'; import EmailService from '../email/email.service'; import EmailScheduleDto from './dto/emailSchedule.dto'; import { SchedulerRegistry } from '@nestjs/schedule'; import { CronJob } from 'cron'; @Injectable() export default class EmailSchedulingService { constructor( private readonly emailService: EmailService, private readonly schedulerRegistry: SchedulerRegistry ) {} scheduleEmail(emailSchedule: EmailScheduleDto) { const date = new Date(emailSchedule.date); const job = new CronJob(date, () => { this.emailService.sendMail({ to: emailSchedule.recipient, subject: emailSchedule.subject, text: emailSchedule.content }) }); this.schedulerRegistry.addCronJob(`${Date.now()}-${emailSchedule.subject}`, job); job.start(); } } |
Above, we use the CronJob constructor to define a crone job. As a first argument, it takes either a cron pattern or a date. The second argument is a function that is executed at a given time.
With the addCronJob method, we add the job to the scheduler built into NestJS. We need to give it a unique name as a first argument. Thanks to doing so, we could access the job and stop it, for example.
1 2 3 4 5 | cancelAllScheduledEmails() { this.schedulerRegistry.getCronJobs().forEach((job) => { job.stop(); }) } |
Aside from starting cron jobs, we could also use the schduler to define intervals, and create timeouts
Summary
In this article, we’ve gone through both the Nodemailer and the cron. We’ve learned what a cron pattern is and how to create one. We’ve also integrated both the Nodemailer and the cron to work together to create an email scheduler. With that knowledge, we can create a lot more functionalities related to scheduling.