koa-bullmq-admin-middleware

Collection of Koa 2 middlewares to interact with the BullMQ message queue. Every middleware exposes a factory function. Set the necessary parameter and customize the optional ones when calling the factory and you will get your custom middleware that can be inserted to any Koa 2 application.

Note: This module does not contain BullMQ as an inner dependency, only as peer dependency. This means it can be updated individually when a new version comes out but it also means you need to install it separately.

npm i bullmq
npm i koa-bullmq-admin-middleware

Middlewares:

• Get All Queue Details
• Get Queue Details
• Get Job Details
• Get Job Details For State

Get All Queue Details

Collects basic information about all the queues, like their name, if they're paused or not and the number of jobs for each state.

const result = [{
  name: String,           // queue's name
  isPaused: Boolean,      // queue is paused or not
  activeCount: Number,    // number of active jobs
  completedCount: Number, // number of completed jobs
  delayedCount: Number,   // number of delayed jobs
  failedCount: Number,    // number of failed jobs
  waitingCount: Number    // number of waiting jobs
}];

Throws ParameterError when:

• queues parameter is not set, not an array or members are not BullMQ Queues
• storeResult parameter not a function, when set

Example

//...
const { getAllQueueDetailsFactory } = require('koa-bullmq-admin-middleware');
///...
const getAllQueueDetailsMiddleware = getAllQueueDetailsFactory(queues, {
  storeResult = (ctx, result) => {...}
});
app.use(getAllQueueDetailsMiddleware);
///...

Parameters

Parameter | Required | Type | Description --- | --- | --- | --- queues | yes | Array | BullMQ queues config | no | Object | config parameters | - config.storeResult | no | Function(ctx, result) => undefined | By default result will be saved to ctx.state.bullMqAdmin.allQueueDetails

Back to top

Get Queue Details

Collects basic information about a queue, like it's name, if it's paused or not and the number of jobs for each state.

const result = {
  name: String,           // queue's name
  isPaused: Boolean,      // queue is paused or not
  activeCount: Number,    // number of active jobs
  completedCount: Number, // number of completed jobs
  delayedCount: Number,   // number of delayed jobs
  failedCount: Number,    // number of failed jobs
  waitingCount: Number    // number of waiting jobs
};

Throws ParameterError when:

• queues parameter is not set, not an array or members are not BullMQ Queues
• getQueue or storeResult parameter not a function, when set

Example

//...
const { getQueueDetailsFactory } = require('koa-bullmq-admin-middleware');
///...
const getQueueDetailsMiddleware = getQueueDetailsFactory(queues, {
  getQueue = (ctx, queues) => {...},
  storeResult = (ctx, result) => {...}
});
app.use(getQueueDetailsMiddleware);
///...

Parameters

Parameter | Required | Type | Description --- | --- | --- | --- queues | yes | Array | BullMQ queues config | no | Object | config parameters | - config.getQueue | no | Function(ctx, queues) => Queue | By default ctx.params.queueName will be used config.storeResult | no | Function(ctx, result) => undefined | By default result will be saved to ctx.state.bullMqAdmin.queueDetails

Back to top

Get Job Details

Collects information about a job by merging the results of it's asJSON and getState functions into one.

// Soma properties are only available on certain states
// check BullMQ's documentation for more details
const result = {
  name: String,             // job's name
  id: String,               // job's id
  attemptsMade: Number,     // job's attemps
  data: JSON,               // job's data
  opts: JSON,               // job's options
  progress: Number | JSON   // job's progress if updated
  returnvalue: JSON         // job's return value when completed
  stacktrace: JSON          // job's stacktrace when it failed
  failedReason: JSON,       // job's reason when it failed
  timestamp: Number,        // job's timestamp when created
  processedOn: Number,      // job's time when processedd
  finishedOn: Number,       // job's time when finished
  state: String,            // job's state
};

Throws ParameterError when:

• queues parameter is not set, not an array or members are not BullMQ Queues
• getQueue, getJob or storeResult parameter not a function, when set

Example

//...
const { getJobDetailsFactory } = require('koa-bullmq-admin-middleware');
///...
const getJobDetailsMiddleware = getJobDetailsFactory(queues, {
  getQueue = (ctx, queues) => {...},
  getJob = async (ctx, queues) => {...},
  storeResult = (ctx, result) => {...}
});
app.use(getJobDetailsMiddleware);
///...

Parameters

Parameter | Required | Type | Description --- | --- | --- | --- queues | yes | Array | BullMQ queues config | no | Object | config parameters | - config.getQueue | no | Function(ctx, queues) => Queue | By default ctx.params.queueName will be used config.getJob | no | async Function(ctx, queues) => Job | By default ctx.params.jobId will be used config.storeResult | no | Function(ctx, result) => undefined | By default result will be saved to ctx.state.bullMqAdmin.jobDetails

Back to top

Get Job Details For State

Collects information about selection of jobs by merging the results of their asJSON function and their state into one. Uses pagination to select only a portion of all jobs.

// Soma properties are only available on certain states
// check BullMQ's documentation for more details
const jobs = [{
  name: String,             // job's name
  id: String,               // job's id
  attemptsMade: Number,     // job's attemps
  data: JSON,               // job's data
  opts: JSON,               // job's options
  progress: Number | JSON   // job's progress if updated
  returnvalue: JSON         // job's return value when completed
  stacktrace: JSON          // job's stacktrace when it failed
  failedReason: JSON,       // job's reason when it failed
  timestamp: Number,        // job's timestamp when created
  processedOn: Number,      // job's time when processedd
  finishedOn: Number,       // job's time when finished
  state: String,            // job's state
}];
const pagination = {
  pageSize: Number,         // number of jobs to include
  start: Number,            // first job's sequantial number to include
  count: Number             // number of all jobs for the given state
};

Throws ParameterError when:

• queues parameter is not set, not an array or members are not BullMQ Queues
• getQueue, getState, getPagination or storeResult parameter not a function, when set

Example

//...
const { getJobDetailsForStateFactory } = require('koa-bullmq-admin-middleware');
///...
const getJobDetailsForStateMiddleware = getJobDetailsForStateFactory(queues, {
  getQueue = (ctx, queues) => {...},
  getState = ctx => {...},
  getPagination = ctx => {...},
  storeResult = (ctx, jobs, pagination) => {...}
});
app.use(getJobDetailsForStateMiddleware);
///...

Parameters

Parameter | Required | Type | Description --- | --- | --- | --- queues | yes | Array | BullMQ queues config | no | Object | config parameters | - config.getQueue | no | Function(ctx, queues) => Queue | By default ctx.params.queueName will be used config.getState | no | Function(ctx) => 'waiting' | 'active' | 'delayed' | 'completed' | 'failed' | By default ctx.params.state will be used config.getPagination | no | Function(ctx) => {pageSize: Number, start: Number} | Parameters for pagination. By default first 10 jobs will be listed config.storeResult | no | Function(ctx, jobs, pagination) => undefined | By default result will be saved to ctx.state.bullMqAdmin.jobsDetails and ctx.state.bullMqAdmin.pagination

Back to top