Job Handlers

The first thing you need to do is define your job types and their corresponding payload types. A payload is the data passed to the job handler. A job handler is a function that runs when a job is processed.

Define Job Types and Payloads

Job types and their payloads are specific to your app. You can define them in any file. The important thing is that they are an object type, where the keys are the job types and the values are the payload types. In this example, send_email, generate_report, and generate_image are the job types, and their values are the payload types.

// Define the job payload map for this app.
// This ensures that the job payload is typed correctly when adding jobs.
// The keys are the job types, and the values are the payload types.
export type JobPayloadMap = {
  send_email: {
    to: string;
    subject: string;
    body: string;
  };
  generate_report: {
    reportId: string;
    userId: string;
  };
  generate_image: {
    prompt: string;
  };
};

Define Job Handlers

Next, define the job handlers by exporting a JobHandlers object that maps job types to handler functions. If you forget to add a handler for a job type, TypeScript will show an error.

import { sendEmail } from './services/email'; // Function to send the email
import { generateReport } from './services/generate-report'; // Function to generate the report
import { JobHandlers } from '@nicnocquee/dataqueue';

export const jobHandlers: JobHandlers<JobPayloadMap> = {
  send_email: async (payload) => {
    const { to, subject, body } = payload;
    await sendEmail(to, subject, body);
  },
  generate_report: async (payload) => {
    const { reportId, userId } = payload;
    await generateReport(reportId, userId);
  },
  generate_image: async (payload, signal) => {
    const { prompt } = payload;
    await generateImageAi(prompt, signal);
  },
};

In the example above, we define three job handlers: send_email, generate_report, and generate_image. Each handler is a function that takes a payload, an AbortSignal, and a JobContext as arguments. The AbortSignal is used to abort the job if it takes too long to complete. The JobContext provides methods to extend the job's timeout while it's running.

Job Handler Signature

A job handler receives three arguments: the job payload, an AbortSignal, and a JobContext.

(payload: Payload, signal: AbortSignal, ctx: JobContext) => Promise<void>;

You can omit arguments you don't need. For example, if you only need the payload:

const handler = async (payload) => {
  // ...
};

JobContext

The third argument provides methods for timeout management and progress reporting:

• ctx.prolong(ms?) — Proactively reset the timeout. If ms is provided, sets the deadline to ms milliseconds from now. If omitted, resets to the original timeoutMs.
• ctx.onTimeout(callback) — Register a callback that fires when the timeout is about to hit, before the AbortSignal is triggered. Return a number (ms) to extend, or return nothing to let the timeout proceed.
• ctx.setProgress(percent) — Report progress as a percentage (0–100). The value is persisted to the database and can be read by clients via getJob() or the React SDK's useJob() hook.

See Job Timeout for timeout examples and Progress Tracking for progress reporting.