adonis-queue

An addon/plugin package to provide driver-based job queueing services in AdonisJS 4.0+

Getting Started

    adonis install adonisjs-queue

Usage

Add a job file to the jobs folder using the command. The command below creates the file app/Jobs/SendEmail.js. The queue flag in the command is for setting the queue priority channel. The queue flag has only 2 possible values: high and low

	$ adonis make:job SendEmail

	$ adonis make:job SendEmail --queue=low

OR

	$ node ace make:job SendEmail

Installation Instructions

See the instructions.md file for the complete installation steps and follow as stated.

Writing A Job

/** @type {typeof import('adonisjs-queue/src/Job')} */
const Job = use('Job')

/** @type {typeof import('@adonisjs/mail/src/Mail')} */
const Mail = use('Mail')

class SendEmail extends Job {
	
	get queue(){
		return 'low'
	}
    
	constructor(emailAddress, emailFrom, emailSubject, emailBody) {
		super(arguments)

		this.timeOut = 100; // seconds
		this.retryCount = 0;
		this.retryUntil = 200; // seconds
		this.delayUntil = Date.parse('2038-01-19T03:14:08.000Z') // optional, omit this line if not required
	}

	async handle(link, done) {
		//....
		console.log(`Job [${this.constructor.name}] - handler called: status=running; id=${this.id} `)
    
		await link.reportProgress(10)

		let _data = link.data // arguments passed into the constructor
		let error = null
		let result = null

		try{
			result = await Mail.send(_data.emailBody, {gender:'F', fullname:"Aisha Salihu"}, (message) => {
				message.to(_data.emailAddress) 
				message.from(_data.emailFrom) 
				message.subject(_data.emailSubject)
			})
			await link.reportProgress(50)
		}catch(err){
			error = err
			result = undefined
			await link.reportProgress(50)
		}finally{
			await link.reportProgress(100)
		}
		
		return new Promise((resolve, reject) => {
			error === null ? resolve(result) : reject(error)
		});
	}

	progress(progress) {

		console.log(`Job [${this.constructor.name}] - progress:${progress}%: status=running; id=${this.id} `)
	}

	failed(error) {
    
		console.log(`Job [${this.constructor.name}] - status:failed; id=${this.id} `, error.message)
		
		this.detach() // remove the job from the queue (when the job fails after all retries)
	}
	
	retrying(error){
	
		console.log(`Job [${this.constructor.name}] - status:retrying; id=${this.id} `, error.message)
	}
	
	succeeded(result){
	
		console.log(`Job [${this.constructor.name}] - status:succeeded; id=${this.id} `, result)
	}
}

module.exports = SendEmail

Open the start/events.js file of an AdonisJS Framework installation and add the following code to it (This package encourages the use of the standard event bus for AdonisJS)

'use strict'

/** @type {typeof import('@adonisjs/framework/src/Event')} */
const Event = use('Event')

/** @type {typeof import('adonisjs-queue/src/Queue')} */
const Queue = use('Queue')

const SendEmail = use('App/Jobs/SendEmail')

Event.on('user_registered', async ( _email ) => {
	// dispatch to the "high" priority queue

    await Queue.select('high').andDispatch(new SendEmail(
		_email,
		'support@example.com',
		'YOU ARE WELCOME',
		'emails.template_1' // AdonisJS view template file: "resources/views/emails/template_1.edge"
    ));
    
    // implicitly calls select('high')
    await Queue.dispatch(new SendEmail(
    		_email,
		'support@example.com',
		'NEXT STEPS',
		'emails.template_2' // AdonisJS view template file: "resources/views/emails/template_2.edge"
    ));
})

Then, go to the start/routes.js file of an AdonisJS Framework installation and add the following code to it

/** @type {typeof import('@adonisjs/framework/src/Route/Manager')} */
const Route = use('Route')

Route.post('user/register/:type', ({ request, params: { type }, respopnse }) => {
	const body = request.post()

	Event.fire('user_registered', 'queensaisha04@gmail.com') // Invoke the 'SendEmail' Job (to send an email) via the Event Bus

	if (request.format() === 'json') {
  		return response.status(200).json({
		  	status:'success'
		})
	}else{
		return response.send('success')
	}
})

Possible Gocthas

If the select() method is explicitly called before a (chained) call andDispatch() OR dispatch() is made on the Queue object, the queue getter value on a job instance (job.queue) is automatically overridden by the value passed to the select method like so select('low'). So, be well aware of how calling select explicitly affects things.

You can also access the queue instance via the AdonisJS Http Context in a controller/middleware

'use strict'

const SendEmail = use('App/Jobs/SendEmail')

class WorksController {

	async sendEmail({ request, queue, session }){
	
		let tenant_id = session.get('tenant_id')
		
		let { email } = request.only([
			'email'
		])
		
		await queue.dispatch(new SendEmail( // dispatch to the "low" priority queue
			email,
			'support@example.com',
			'YOU ARE WELCOME',
			'emails.template' // AdonisJS view template file in "resources/views"
		))
	}
}

module.exports = WorksController

License

MIT

Running Tests

    npm i

    npm run lint
    
    npm run test

Credits

Contributing

See the CONTRIBUTING.md file for info

Support

Coolcodes is a non-profit software foundation (collective) created by Oparand - parent company of StitchNG, Synergixe based in Abuja, Nigeria. You'll find an overview of all our work and supported open source projects on our Facebook Page.

Follow us on facebook if you can to get the latest open source software/freeware news and infomation.

Does your business depend on our open projects? Reach out and support us on Patreon. All pledges will be dedicated to allocating workforce on maintenance and new awesome stuff.

stitchng/adonis-queue