@acidiney/bull-queue

@acidiney/bull-queue is a powerful queue system designed specifically for AdonisJS applications, leveraging the reliability and scalability of BullMQ, a Redis-based queue for Node.js. Derived from @rlanz/bull-queue, 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 @acidiney/bull-queue using npm:

npm install @acidiney/bull-queue

Configuration

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

node ace configure @acidiney/bull-queue

Usage

Job Dispatching

Utilize the dispatch 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 bull from '@acidiney/bull-queue/services/main'
import RegisterStripeCustomer, {
  RegisterStripeCustomerPayload,
} from '#app/jobs/register_stripe_customer'

await app.booted(async () => {
  bull.dispatch(RegisterStripeCustomer.name, { userId: '123456' } as RegisterStripeCustomerPayload)
})

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 '@acidiney/bull-queue/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
import RegisterStripeCustomer from '#app/jobs/register_stripe_customer'
const jobs: Record<string, Function> = {
  [RegisterStripeCustomer.name]: () => import('#app/jobs/register_stripe_customer'),
}

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.

Example:

node ace queue:listen:ui

By default, the UI will be accessible at localhost:9999/admin. You can specify a different port using the --port option:

node ace queue:listen:ui --port=3939

Additionally, you can specify the queues to listen to:

node ace queue:listen:ui --queue=stripe

In case you want to start a custom queue, do not forget to name it when you dispatching it

import app from '@adonisjs/core/services/app'
import bull from '@acidiney/bull-queue/services/main'
import RegisterStripeCustomer, {
  RegisterStripeCustomerPayload,
} from '#app/jobs/register_stripe_customer'

await app.booted(async () => {
  bull.dispatch(
    RegisterStripeCustomer.name,
    { userId: '123456' } as RegisterStripeCustomerPayload,
    {
      queueName: 'stripe',
    }
  )
})

This command starts the queue worker and launches the UI for convenient management and monitoring of your queues.

Dependencies

• @bull-board/api: Provides API endpoints for monitoring and managing queues.
• @bull-board/h3: UI components for Bull queue management.
• bullmq: The core library for handling queues.
• h3: A library for generating unique hash codes.

Author

Acidiney Dias