Progress Tracking

Jobs can report their progress as a percentage (0–100) while they run. This is useful for long-running tasks like file processing, data imports, or image generation where you want to show a progress bar or percentage to the user.

Reporting Progress from a Handler

Use ctx.setProgress(percent) inside your job handler to report progress:

import { JobHandlers } from '@nicnocquee/dataqueue';

export const jobHandlers: JobHandlers<JobPayloadMap> = {
  generate_report: async (payload, signal, ctx) => {
    const chunks = await loadData(payload.reportId);

    for (let i = 0; i < chunks.length; i++) {
      if (signal.aborted) return;

      await processChunk(chunks[i]);

      // Report progress (0-100)
      await ctx.setProgress(Math.round(((i + 1) / chunks.length) * 100));
    }
  },
};

setProgress Rules

• Range: The value must be between 0 and 100 (inclusive). Values outside this range throw an error.
• Rounding: Fractional values are rounded to the nearest integer (33.7 becomes 34).
• Best-effort persistence: Progress is written to the database but errors during the write do not kill the handler — processing continues.

Reading Progress

Progress is stored in the progress field of the JobRecord:

const job = await jobQueue.getJob(jobId);
console.log(job?.progress); // null | 0–100

• Before the handler calls setProgress, the value is null.
• After the job completes, the last progress value is preserved (typically 100).

Tracking Progress in React

If you're using the React SDK, the useJob hook exposes progress directly:

import { useJob } from '@nicnocquee/dataqueue-react';

function JobProgress({ jobId }: { jobId: number }) {
  const { status, progress } = useJob(jobId, {
    fetcher: (id) =>
      fetch(`/api/jobs/${id}`)
        .then((r) => r.json())
        .then((d) => d.job),
  });

  return (
    <div>
      <p>Status: {status}</p>
      <progress value={progress ?? 0} max={100} />
      <span>{progress ?? 0}%</span>
    </div>
  );
}

Database Migration

The Redis backend requires no migration — the progress field is stored automatically as part of the job hash.