Queueing Jobs

Once a queue is defined and registered, jobs can be added to it via the global process.queues.<queue_name>.add() function from anywhere on your server.

Example Usage

Adding a Notification Job

import joystick from '@joystick.js/node';

const setters = {
  send_notification: {
    input: {
      user_id: {
        type: 'string',
        required: true,
      },
      message: {
        type: 'string',
        required: true,
      },
    },
    set: async (input = {}) => {
      const notification_id = joystick.id();

      await process.databases.mongodb.collection('notifications').insertOne({
        _id: notification_id,
        ...input,
      });

      await process.queues.notifications.add({
        job: 'send_notification_via_email',
        next_run_at: new Date().toISOString(),
        payload: {
          notification_id,
        },
      });
    },
  },
};

export default setters;

In the example above, process.queues.notifications.add() is called to add a job where notifications is the name of the queue we defined.

The add() function receives an options object containing:

• job: The name of the job in the queue definition's jobs object.
• next_run_at: An ISO-8601 timestamp specifying when the job should run.
• payload: Key/value pairs with additional metadata for the job at run time.

When called, the job is added to the queue and will run as soon as possible (ASAP), unless constrained by the queue’s concurrent_jobs setting or other rules.

API

Definition

process.queues.<queue_name>.add(options: object) => Promise

Parameters

options object required

Options defining the job to add to the queue.

job string required

The name of the job to run, as defined in the queue's jobs object.

next_run_at string

An ISO-8601 string specifying the date/time when the job should run. Relative to other jobs in the queue, the job will run as close to this timestamp as possible.

payload object

An object containing key/value pairs to pass to the job's run() method at run time. Should include any data necessary for performing the job.