What is a cron job?
A cron job is some piece of code or action that you want to take at specific intervals or specific times. Some examples could be
- Checking your app once everyday for users whose birthday is that day and sending them emails.
- Taking statistics/metrics of your app on the 1st of every month and storing it to the database or sending the data to an admin.
Basically any action you want to take at various intervals is called a cron job
Cron jobs in node.js using typescript.
Multiple packages are available to create cron jobs in Node.js, but we'll work with node-cron.
import cron from 'node-cron'
const cronExpression = '* * * * * *';
function action(){
console.log('This cron job will run every second')
}
const job = cron.schedule(cronExpression, action, {scheduled:false})
job.start()//starts the job
//job.stop() //stops the job
The cronExpression describes how often the action should be called. Check here for a description of cronExpression.
The Problem
There might be times when we want to pause or restart a cron job. Then we need to find a way to manage it. Say in our express server we wanted a way to start or stop a cron-job. How would we do it?
import cron from 'node-cron'
import express, { Request, Response } from 'express'
const cronExpression = '* * * * * *';
function action(){
console.log('This cron job will run every second')
}
const job = cron.schedule(cronExpression, action, {scheduled:false})
const app = express()
app.use(express.json())
app.use(express.urlencoded({ extended: true }))
app.post('/start-job',(req:Request,res:Response)=>{
job.start();
res.status(200).json({message:'job started successfully'})
})
app.post('/stop-job',(req:Request,res:Response)=>{
job.stop();
res.status(200).json({message:'job stopped successfully'})
})
We could do it this way when working with just a few jobs.
But say we're working with many jobs, and we don't want to create an endpoint for every one of them.
An approach would be to associate each job with a unique key, and we could map the key to the job.
See the implementation below.
import cron from 'node-cron'
import express, { Request, Response } from 'express'
//hash map to map keys to jobs
const jobMap: Map<string, cron.ScheduledTask> = new Map();
//jobs
const metricsJob = cron.schedule('0 0 0 1 * *',()=>{
console.log('There are 5 users in the application')
}, {scheduled:false})
const birthdayJob = cron.schedule('0 0 0 * * *',()=>{
console.log('20 users have their birthday today')
}, {scheduled:false})
//set the key to map to the job
jobMap.set('metrics',metricsJob)
jobMap.set('birthday',birthdayJob)
//express api and simple routes
const app = express()
app.use(express.json())
app.use(express.urlencoded({ extended: true }))
app.post('/start-job',(req:Request,res:Response)=>{
const {jobName} = req.body
const job = jobMap.get(jobName)
if(!job) return res.status(400).json({message: 'invalid job name'})
else job.start()
res.status(200).json({message:`job ${jobName} started successfully`})
})
app.post('/stop-job',(req:Request,res:Response)=>{
const {jobName} = req.body
const job = jobMap.get(jobName)
if(!job) return res.status(400).json({message: 'invalid job name'})
else job.start()
res.status(200).json({message:`job ${jobName} stoppeed successfully`})
})
It works right. All well and good. Another use case would be wanting to start or stop related jobs.
Say you had two jobs related to authentication and another two jobs related to application metrics. You would want a way to start or stop all jobs under auth or metrics without having to start each job individually.
You could use another map to achieve this too.
See the implementation below.
import cron from 'node-cron'
import express, { Request, Response } from 'express'
//hash map to map keys to jobs
const jobMap: Map<string, cron.ScheduledTask> = new Map();
const jobGroupsMap: Map<string, cron.ScheduledTask[]> = new Map();
//jobs
//default jobs
const metricsJob = cron.schedule('0 0 0 1 * *',()=>{
console.log('There are 5 users in the application')
}, {scheduled:false})
const birthdayJob = cron.schedule('0 0 0 * * *',()=>{
console.log('20 users have their birthday today')
}, {scheduled:false})
// jobs related to auth
const countLoggedInUsersJob = cron.schedule('0 * * * * *',()=>{
console.log('There are 100 users currently logged in')
}, {scheduled:false})
const autoUnbanUsersJob = cron.schedule('0 0 * * * *',()=>{
console.log('unbanning users whose ban has expired')
},{scheduled:false})
//set the key to map to the job
jobMap.set('metrics',metricsJob)
jobMap.set('birthday',birthdayJob)
jobMap.set('countUsers',countLoggedInUsersJob)
jobMap.set('unbanUsers',autoUnbanUsersJob)
jobGroupsMap.set('default',[metricsJob, birthdayJob])
jobGroupsMap.set('auth',[countLoggedInUsersJob, autoUnbanUsersJob])
//express api and simple routes
const app = express()
app.use(express.json())
app.use(express.urlencoded({ extended: true }))
app.post('/start-job',(req:Request,res:Response)=>{
const {jobName} = req.body
const job = jobMap.get(jobName)
if(!job) return res.status(400).json({message: 'invalid job name'})
else job.start()
res.status(200).json({message:`job ${jobName} started successfully`})
})
app.post('/stop-job',(req:Request,res:Response)=>{
const {jobName} = req.body
const job = jobMap.get(jobName)
if(!job) return res.status(400).json({message: 'invalid job name'})
else job.start()
res.status(200).json({message:`job ${jobName} stoppeed successfully`})
})
app.post('/start-job-group',(req:Request,res:Response)=>{
const {groupName} = req.body
const jobs = jobGroupsMap.get(groupName)
if(!jobs) return res.status(400).json({message: 'invalid group name'})
else{
jobs.forEach(job=>{
job.start()
})
}
res.status(200).json({message:`jobs in group ${groupName} started successfully`})
})
app.post('/stop-job-group',(req:Request,res:Response)=>{
const {groupName} = req.body
const jobs = jobGroupsMap.get(groupName)
if(!jobs) return res.status(400).json({message: 'invalid group name'})
else{
jobs.forEach(job=>{
job.stop()
})
}
res.status(200).json({message:`jobs in group ${groupName} stopped successfully`})
})
The Proposed Solution
As you can see, handling multiple cron jobs in node.js could become a hassle as the user has to write code to cater for each new cron job they create.
To solve this problem, I created a package. @ose4g/cron-manager.
It covers all use cases specified above
- starting and stopping all jobs
- starting and stopping a specific job
- starting and stopping a group of related jobs.
To use first of all install the package using
npm i @ose4g/cron-manager
or if you're using yarn
yarn add @ose4g/cron-manager
See implementation below
import { cronGroup, cronJob, CronManager } from "@ose4g/cron-manager";
import express, { Request, Response } from 'express'
@cronGroup('default')
class DefaultJobs{
@cronJob('0 0 0 1 * *','metrics')
metricsCount(){
console.log('There are 5 users in the application')
}
@cronJob('0 0 0 * * *','birthday')
countBirthdays(){
console.log('20 users have their birthday today')
}
}
@cronGroup('auth')
class AuthJobs{
@cronJob('0 * * * * *','countUsers')
countLoggedInUsers(){
console.log('There are 100 users currently logged in')
}
@cronJob('0 0 * * * *','unbanUsers')
autoUnbanUsers(){
}
}
const cronManager = new CronManager()
//registers the jobs
cronManager.register(DefaultJobs, new DefaultJobs())
cronManager.register(AuthJobs, new AuthJobs())
//express api and simple routes
const app = express()
app.use(express.json())
app.use(express.urlencoded({ extended: true }))
app.post('/start-job',(req:Request,res:Response)=>{
const {jobName} = req.body
try {
cronManager.startHandler(jobName) //throw error for invalid jobName.
res.status(200).json({message:`job ${jobName} started successfully`})
} catch (error) {
return res.status(400).json({message: 'invalid job name'})
}
})
app.post('/stop-job',(req:Request,res:Response)=>{
const {jobName} = req.body
try {
cronManager.stopHandler(jobName) //throw error for invalid jobName.
res.status(200).json({message:`job ${jobName} stopped successfully`})
} catch (error) {
return res.status(400).json({message: 'invalid job name'})
}
})
app.post('/start-job-group',(req:Request,res:Response)=>{
const {groupName} = req.body
try {
cronManager.stopHandler(groupName) //throw error for invalid jobName.
res.status(200).json({message:`jobs in group ${groupName} started successfully`})
} catch (error) {
return res.status(400).json({message: 'invalid group name'})
}
})
app.post('/stop-job-group',(req:Request,res:Response)=>{
const {groupName} = req.body
try {
cronManager.stopHandler(groupName) //throw error for invalid jobName.
res.status(200).json({message:`jobs in group ${groupName} stopped successfully`})
} catch (error) {
return res.status(400).json({message: 'invalid group name'})
}
})
app.post('/start-all',(req:Request, res:Response)=>{
cronManager.startAll();
return res.status(200).json({message: 'successfully started all jobs'})
})
app.post('/stop-all', (req:Request, res:Response)=>{
cronManager.stopAll();
return res.status(200).json({message: 'successfully stopped all jobs'})
})
So to use the package, there are a few things you must do first.
- Add decorator support in your tsconfig.json file Ensure the following is in your tsconfig.json file
"experimentalDecorators": true,
"emitDecoratorMetadata": true,
- Create your job class and annotate it with the @cronGroup tag. It takes a single parameter which is the string for the job groupName.
- Create methods in the class and annotate the required methods with @cronJob(). It takes 2 parameters. The first is the cron expression while the second is the jobName (unique string to identify that job).
- Create an instance of cronManager and register an instance of each Job class to the cronManager.It would throw an error if classes are not registered and you try to run the jobs.
- start or stop jobs. The following functions are available
- startAll(): starts all jobs defined in the app.
- stopAll(): stops all jobs defined in the app.
- startHandler(jobName): starts a specific job with jobName.
- stopHandler(jobName): stops a specific job with jobName
- startGroup(groupName): starts all jobs under group with groupName
- startGroup(groupName): starts all jobs under group with groupName.
- getGroups(): Lists all groupNames in the application
- getHandlers(): Lists all handler names in the application
So using this package you can focus more on the logic of the cron jobs and write less code for managing your cron jobs.
Check out the source code for the package here. Kindly leave a star too 🙏🏾🙏🏾.
I hope you found this article insightful and helpful.
See you on the next one. Stay Awesome
Top comments (0)