@brighthustle/adonis-jobs

What's this

@brighthustle/adonis-jobs is a powerful queue system designed specifically for AdonisJS applications, leveraging the reliability and scalability of BullMQ, a Redis-based queue for Node.js. Inspired from @rocketseat/adonis-bull, it offers enhanced functionality tailored to AdonisJS's ecosystem.

Table of Contents

1. Installation
2. Configuration
3. Usage
   • Job Dispatching
   • Job Creation
   • Job Lifecycle
4. Advanced Features
   • Job Attempts and Retries
   • Running the Queue Worker
5. Dependencies

Installation

Begin by installing @brighthustle/adonis-jobs using npm:

npm install @brighthustle/adonis-jobs

Configuration

After installation, configure the package to adapt it to your AdonisJS project:

node ace configure @brighthustle/adonis-jobs

Usage

Job Dispatching

Utilize the addTask method provided by the bull provider to enqueue jobs. Example:

Please note that #app is an alia that was created by me, and isn't in adonis by default... So if you want to use it, you will need to add it in your tsconfig and package.json

import app from '@adonisjs/core/services/app'
import queue from '@brighthustle/adonis-jobs/services/main'

Job Creation

Generate new job classes using the node ace make:job {job} command.

Example:

// app/jobs/register_stripe_customer.ts
import { JobHandlerContract, Job } from '@brighthustle/adonis-jobs/types'

export type RegisterStripeCustomerPayload = {
  userId: string
}

export default class RegisterStripeCustomer
  implements JobHandlerContract<RegisterStripeCustomerPayload>
{
  public async handle(job: Job<RegisterStripeCustomerPayload>) {
    // Logic to register a Stripe customer
    const { userId } = job.data
    // Perform Stripe registration process
  }

  public async failed(job: Job<RegisterStripeCustomerPayload>) {
    // Logic to handle failed job attempts
    const { userId } = job.data
    // Send notification or log failure
  }
}

Register the new job into start/jobs.ts

// start/jobs.ts
const jobs: Record<string, Function> = {}

export { jobs }

Job Lifecycle

Define the handle method to execute job logic and the failed method to handle failed attempts.

Advanced Features

Job Attempts and Retries

• Customize the retry setting for jobs, configurable in the config/queue.ts file.
• Adjust attempts and delays per job or globally.

Running the Queue Worker

Initiate the queue worker using the node ace queue:listen command.

• Specify queues or run the UI for monitoring and managing queues.

Dependencies

• @queuedash/api: Provides API endpoints for monitoring and managing queues.
• @trpc/server: Starts QueueDash API server.
• bullmq: The core library for handling queues.

Author

Kumar Yash