Named jobs in NestJS - Step-by-Step Execution

Concept Flow - Named jobs

Define Named Job

↓

Add Job to Queue with Name

↓

Worker Listens for Named Job

↓

Job Executes

↓

Job Completes or Fails

↓

Result or Retry Handling

This flow shows how a named job is defined, added to a queue, processed by a worker, and then completed or retried.

Execution Sample

NestJS

import { Processor, Process } from '@nestjs/bull';
import { Job } from 'bull';

@Processor('email')
export class EmailProcessor {
  @Process('send-welcome')
  async handleSendWelcome(job: Job) {
    console.log(`Sending welcome email to ${job.data.email}`);
  }
}

This code defines a named job 'send-welcome' inside an 'email' queue and processes it by logging the email address.

Execution Table

Step	Action	Job Name	Job Data	Worker Response	Output
1	Define processor and named job	send-welcome	N/A	Ready to process	No output
2	Add job to queue	send-welcome	{"email":"[e-mail]"}	Job queued	No output
3	Worker picks job	send-welcome	{"email":"[e-mail]"}	Job started	No output
4	Execute job handler	send-welcome	{"email":"[e-mail]"}	Processing	Logs: Sending welcome email to [e-mail]
5	Job completes	send-welcome	{"email":"[e-mail]"}	Job done	No output

💡 Job completes successfully after processing the named job 'send-welcome'.

Variable Tracker

Variable	Start	After Step 2	After Step 3	After Step 4	Final
job.name	undefined	send-welcome	send-welcome	send-welcome	send-welcome
job.data.email	undefined	[e-mail]	[e-mail]	[e-mail]	[e-mail]
worker.status	idle	idle	processing	processing	idle

Key Moments - 2 Insights

Why does the worker only process jobs with the specific name 'send-welcome'?

Because the @Process decorator specifies the job name 'send-welcome', the worker listens only for jobs with that name as shown in execution_table step 3.

What happens if a job with a different name is added to the queue?

The worker will ignore it since it only processes 'send-welcome' jobs, so no handler runs for other names, as implied by the variable_tracker showing worker.status stays idle for other names.

Visual Quiz - 3 Questions

Look at the execution table, what is the job name when the worker starts processing?

A send-welcome

B email

C handleSendWelcome

D undefined

💡 Hint

Check the 'Job Name' column at Step 3 in the execution_table.

At which step does the console log output appear?

A Step 2

B Step 4

C Step 3

D Step 5

💡 Hint

Look at the 'Output' column in the execution_table for the log message.

If the job data email changed to '[e-mail]', what would change in the variable_tracker?

A worker.status would stay 'idle' throughout

B job.name would change to '[e-mail]'

C job.data.email would show '[e-mail]' after Step 2

D No changes in variable_tracker

💡 Hint

Refer to the 'job.data.email' row in variable_tracker and imagine the new email value.

Concept Snapshot

Named jobs in NestJS Bull queues let you label jobs with a string name.
Use @Process('job-name') to handle specific jobs.
Add jobs with queue.add('job-name', data).
Workers listen only for their named jobs.
This helps organize and separate job logic clearly.

Full Transcript

In NestJS, named jobs allow you to assign a specific name to each job type in a queue. You define a processor class with @Processor('queue-name') and use @Process('job-name') to handle jobs with that name. When you add a job to the queue with queue.add('job-name', data), the worker listens for jobs matching that name and runs the handler. The execution flow starts with defining the job, adding it to the queue, the worker picking it up, executing the handler, and completing the job. Variables like job.name and job.data track the job's identity and data throughout. This approach helps keep job processing organized and clear.

Practice

1. What is the main benefit of using named jobs in NestJS queues?

easy

A. They automatically speed up job processing.

B. They help identify and manage specific background tasks easily.

C. They encrypt job data for security.

D. They allow jobs to run without a queue.

Solution

1. Step 1: Understand the purpose of named jobs

   Named jobs provide a clear label to background tasks, making them easier to find and manage.

2. Step 2: Compare options with the purpose

   Only They help identify and manage specific background tasks easily. matches this purpose. Options B, C, and D describe unrelated features.

3. Final Answer:

   They help identify and manage specific background tasks easily. -> Option B

4. Quick Check:

   Named jobs = easier management [OK]

Hint: Named jobs label tasks for easy tracking [OK]

Common Mistakes:

• Thinking named jobs improve speed
• Confusing named jobs with security features
• Assuming named jobs remove the need for queues

2. Which of the following is the correct way to add a named job to a queue in NestJS?

easy

A. queue.pushJob('emailJob', { to: '[e-mail]' });

B. queue.createJob('emailJob', { to: '[e-mail]' });

C. queue.runJob('emailJob', { to: '[e-mail]' });

D. queue.add('emailJob', { to: '[e-mail]' });

Solution

1. Step 1: Recall the NestJS queue method for adding jobs

   The correct method to add a job with a name is queue.add(name, data).

2. Step 2: Match the method with options

   Only queue.add('emailJob', { to: '[e-mail]' }); uses queue.add with a job name and data correctly.

3. Final Answer:

   queue.add('emailJob', { to: '[e-mail]' }); -> Option D

4. Quick Check:

   Use queue.add(name, data) [OK]

Hint: Use queue.add('jobName', data) to name jobs [OK]

Common Mistakes:

• Using non-existent methods like createJob or pushJob
• Forgetting to pass the job name as first argument
• Confusing job execution with job creation

3. Given this code snippet, what will be the output when checking the job name?

const job = await queue.add('reportGeneration', { userId: 42 });
console.log(job.name);

medium

A. 'reportGeneration'

B. 'default'

C. undefined

D. Throws an error

Solution

1. Step 1: Understand job creation with a name

   When adding a job with queue.add('reportGeneration', data), the job's name property is set to 'reportGeneration'.

2. Step 2: Check the console.log output

   Logging job.name will print 'reportGeneration'.

3. Final Answer:

   'reportGeneration' -> Option A

4. Quick Check:

   Job name property = 'reportGeneration' [OK]

Hint: Job.name matches the string passed to queue.add [OK]

Common Mistakes:

• Assuming default name is used if a name is given
• Expecting undefined if name is not accessed properly
• Thinking job creation throws error without processor

4. Identify the error in this NestJS queue job addition:

queue.add({ name: 'cleanupJob' }, { force: true });

medium

A. Job name should be a string, not inside an object.

B. The second argument must be a string, not an object.

C. The method add() does not exist on queue.

D. The job data cannot contain boolean values.

Solution

1. Step 1: Review the correct syntax for named jobs

   The queue.add method expects the first argument as a string name, not an object.

2. Step 2: Analyze the given code

   The code passes an object { name: 'cleanupJob' } instead of a string, causing a syntax error.

3. Final Answer:

   Job name should be a string, not inside an object. -> Option A

4. Quick Check:

   First argument to add() = string name [OK]

Hint: Pass job name as string, not object, to queue.add [OK]

Common Mistakes:

• Passing job name inside an object instead of string
• Confusing job data with job name argument
• Assuming add() method is missing or invalid

5. You want to cancel all jobs named 'emailNotification' in a queue. Which approach correctly uses named jobs to achieve this?

hard

A. Restart the queue to clear all jobs named 'emailNotification'.

B. Call queue.removeJobs('emailNotification') directly without fetching jobs.

C. Use queue.getJobs(['emailNotification']) and then call remove() on each job.

D. Filter jobs by data property { type: 'emailNotification' } and delete them.

Solution

1. Step 1: Understand how to retrieve named jobs

   Named jobs can be fetched using queue.getJobs(['jobName']) which returns jobs with that name.

2. Step 2: Remove each fetched job

   After fetching, calling remove() on each job deletes them from the queue.

3. Final Answer:

   Use queue.getJobs(['emailNotification']) and then call remove() on each job. -> Option C

4. Quick Check:

   Fetch named jobs then remove [OK]

Hint: Fetch named jobs first, then remove them one by one [OK]

Common Mistakes:

• Trying to remove jobs by name without fetching them
• Filtering jobs by data instead of name
• Restarting queue does not selectively remove jobs