feat: add generic ProgressType parameter to Job and Worker

The progress type was hardcoded to JobProgress
(string | boolean | number | object), so there was no way to get
type-safe progress when calling updateProgress() or when listening to
the progress event.

Add an optional ProgressType generic parameter, constrained to
JobProgress and defaulting to JobProgress, to MinimalJob, Job,
Processor, Worker and WorkerListener. Existing code that passes fewer
generics keeps compiling unchanged.

Because ProgressType is constrained to JobProgress, Job<..., P> stays
assignable to the internal MinimalJob helpers, which never read or
write progress, so the generic does not need to be threaded through
them. This also keeps the persistence contract intact, since progress
is ultimately serialized before being stored in the backend.

On Worker the parameter is added after the backend generic B so that
the existing public signature is not broken.

Sandboxed processors keep JobProgress by design, as progress crosses a
process boundary where the static type is lost. Queue side getters such
as getJob and Job.fromId also keep the default.

Closes #3721

Co-authored-by: claygeo <claygeo6@gmail.com>

Author: skrukwa

docs/gitbook/guide/workers/README.md

@@ -133,6 +133,33 @@ It is also possible to specify the data types for the Job data and return value
 const worker = new Worker<MyData, MyReturn>(queueName, async (job: Job) => {});
 ```
 
+By default the job progress is typed as `string | boolean | number | object`. If you report progress with a specific shape, you can also specify a progress type so that `updateProgress` and the `progress` event are type-safe:
+
+```typescript
+import { Worker, RedisQueueBackend } from 'bullmq';
+
+type MyProgress = { percentage: number; message: string };
+
+const worker = new Worker<
+  MyData,
+  MyReturn,
+  string,
+  RedisQueueBackend,
+  MyProgress
+>(queueName, async job => {
+  // progress is checked against MyProgress
+  await job.updateProgress({ percentage: 42, message: 'halfway' });
+});
+
+worker.on('progress', (job, progress) => {
+  console.log(progress.percentage, progress.message);
+});
+```
+
+{% hint style="info" %}
+The progress type must be JSON-serializable, as progress is persisted in the queue's backend. Sandboxed processors always receive the default progress type, since the value crosses a process boundary.
+{% endhint %}
+
 ## Read more:
 
 - 💡 [Worker API Reference](https://docs.bullmq.io/api/classes/v6.Worker.html)

src/classes/job.ts

@@ -55,7 +55,8 @@ export class Job<
   DataType = any,
   ReturnType = any,
   NameType extends string = string,
-> implements MinimalJob<DataType, ReturnType, NameType> {
+  ProgressType extends JobProgress = JobProgress,
+> implements MinimalJob<DataType, ReturnType, NameType, ProgressType> {
   /**
    * It includes the prefix, the namespace separator :, and queue name.
    * @see {@link https://www.gnu.org/software/gawk/manual/html_node/Qualified-Names.html}
@@ -66,7 +67,7 @@ export class Job<
    * The progress a job has performed so far.
    * @defaultValue 0
    */
-  progress: JobProgress = 0;
+  progress: ProgressType = 0 as ProgressType;
 
   /**
    * The value returned by the processor when processing this job.
@@ -539,7 +540,7 @@ export class Job<
    *
    * @param progress - number or object to be saved as progress.
    */
-  async updateProgress(progress: JobProgress): Promise<void> {
+  async updateProgress(progress: ProgressType): Promise<void> {
     this.progress = progress;
     await this.backend.updateProgress(this.id, progress);
     this.queue.emit('progress', this, progress);