README.md

@rlanz/bull-queue is a queue system based on BullMQ for AdonisJS.

Note

You must have a Redis server running on your machine.

---

Getting Started

This package is available in the npm registry.

node ace add @rlanz/bull-queue

Usage

The queue service gives you access to the dispatch method. It will dispatch the linked job to the queue with the given payload.

import queue from '@rlanz/bull-queue/services/main';

queue.dispatch(RegisterStripeCustomer, {...});

// You can also specify options for a specific job
queue.dispatch(RegisterStripeCustomer, {...}, {
  queueName: 'stripe',
});

You can create a job by running node ace make:job {job}. This will create the job within your app/jobs directory.

The handle method is what gets called when the jobs is processed while the rescue method is called when the max attempts of the job has been reached.

You can remove the rescue method if you want.

Since the job instance is passed to the constructor, you can easily send notifications with the rescue method. See this page for full documentation on the job instance.

Example job file:

// app/jobs/register_stripe_customer.ts
import { Job } from '@rlanz/bull-queue'

interface RegisterStripeCustomerPayload {
  userId: string;
};

export default class RegisterStripeCustomer extends Job {
  static get $$filepath() {
    return import.meta.url
  }

  public async handle(payload: RegisterStripeCustomerPayload) {
    // ...
  }

  /**
   * This is an optional method that gets called if it exists when the retries has exceeded and is marked failed.
   */
  public async rescue(payload: RegisterStripeCustomerPayload, error: Error) {}
}

Job Attempts

By default, all jobs have a retry of 3 and this is set within your config/queue.ts under the jobs object.

You can also set the attempts on a call basis by passing the override as shown below:

queue.dispatch(SomeJob, {...}, { attempts: 3 })

Delayed retries

If you need to add delays between retries, you can either set it globally via by adding this to your config/queue.ts:

// config/queue.ts
import { defineConfig } from '@rlanz/bull-queue'

export default defineConfig({
  // ...

  jobs: {
    attempts: 3,
    backoff: {
      type: 'exponential',
      delay: 5000,
    }
  }
})

Or... you can also do it per job:

queue.dispatch(Somejob, {...}, {
  attempts: 3,
  backoff: { type: 'exponential', delay: 5000 }
})

With that configuration above, BullMQ will first add a 5s delay before the first retry, 20s before the 2nd, and 40s for the 3rd.

You can visit this page on further explanation / other retry options.

Running the queue

Run the queue worker with the following ace command:

node ace queue:listen

# or

node ace queue:listen --queue=stripe

# or

node ace queue:listen --queue=stripe,cloudflare

Once done, you will see the message Queue processing started.