@tsed/bullmq 7.47.1 → 7.49.0

package/src/BullMQModule.ts

@@ -1,7 +1,8 @@
 import {BeforeInit, DIContext, runInContext} from "@tsed/common";
 import {Constant, InjectorService, Module} from "@tsed/di";
+import {deepMerge} from "@tsed/core";
 import {getComputedType} from "@tsed/schema";
-import {Job, Queue, Worker} from "bullmq";
+import {Job, Queue, type QueueOptions, Worker, type WorkerOptions} from "bullmq";
 import {v4} from "uuid";
 import {BullMQConfig} from "./config/config";
 import {JobMethods} from "./contracts";
@@ -19,7 +20,9 @@ export class BullMQModule implements BeforeInit {
       return;
     }
 
-    this.buildWorkers();
+    if (!this.bullmq.disableWorker) {
+      this.buildWorkers();
+    }
     this.buildQueues();
 
     this.injector.getMany<JobMethods>("bullmq:cron").map((job) => this.dispatcher.dispatch(getComputedType(job)));
@@ -27,13 +30,19 @@ export class BullMQModule implements BeforeInit {
 
   private buildQueues() {
     this.bullmq.queues.forEach((queue) => {
+      const ops = deepMerge<QueueOptions, QueueOptions>(
+        {
+          connection: this.bullmq.connection,
+          defaultJobOptions: this.bullmq.defaultJobOptions,
+          ...this.bullmq.defaultQueueOptions
+        },
+        this.bullmq.queueOptions?.[queue]
+      )!;
+
       this.injector
         .add(`bullmq.queue.${queue}`, {
           type: "bullmq:queue",
-          useValue: new Queue(queue, {
-            connection: this.bullmq.connection,
-            defaultJobOptions: this.bullmq.defaultJobOptions
-          }),
+          useValue: new Queue(queue, ops),
           hooks: {
             $onDestroy: (queue) => queue.close()
           }
@@ -44,12 +53,18 @@ export class BullMQModule implements BeforeInit {
 
   private buildWorkers() {
     (this.bullmq.workerQueues ?? this.bullmq.queues).forEach((queue) => {
+      const ops = deepMerge<WorkerOptions, WorkerOptions>(
+        {
+          connection: this.bullmq.connection,
+          ...this.bullmq.defaultWorkerOptions
+        },
+        this.bullmq.workerOptions?.[queue]
+      )!;
+
       this.injector
         .add(`bullmq.worker.${queue}`, {
           type: "bullmq:worker",
-          useValue: new Worker(queue, this.onProcess.bind(this), {
-            connection: this.bullmq.connection
-          }),
+          useValue: new Worker(queue, this.onProcess.bind(this), ops),
           hooks: {
             $onDestroy: (worker) => worker.close()
           }
@@ -59,7 +74,17 @@ export class BullMQModule implements BeforeInit {
   }
 
   private getJob(name: string, queueName: string) {
-    return this.injector.get(`bullmq.job.${queueName}.${name}`);
+    const job = this.injector.get<JobMethods>(`bullmq.job.${queueName}.${name}`);
+    if (job) {
+      return job;
+    }
+
+    const fallbackJobForQueue = this.injector.get(`bullmq.fallback-job.${queueName}`);
+    if (fallbackJobForQueue) {
+      return fallbackJobForQueue;
+    }
+
+    return this.injector.get("bullmq.fallback-job");
   }
 
   private async onProcess(job: Job) {

package/src/config/config.ts

@@ -1,13 +1,58 @@
-import {type ConnectionOptions, type DefaultJobOptions} from "bullmq";
+import type {ConnectionOptions, DefaultJobOptions, QueueOptions, WorkerOptions} from "bullmq";
 
 export type BullMQConfig = {
+  /**
+   * Specify queue name's to create
+   */
   queues: string[];
+
+  /**
+   * Default connection to use for queue's and worker's
+   */
   connection: ConnectionOptions;
+
+  /**
+   * @deprecated Use defaultQueueOptions instead. Will be removed in the next major release
+   */
   defaultJobOptions?: DefaultJobOptions;
+
+  /**
+   * Default queue options which are applied to every queue
+   *
+   * Can be extended/overridden by `queueOptions`
+   */
+  defaultQueueOptions?: QueueOptions;
+
+  /**
+   * Specify additional queue options by queue name
+   */
+  queueOptions?: Record<string, QueueOptions>;
+
+  /**
+   * Disable the creation of any worker.
+   *
+   * All other worker configuration will be ignored
+   */
   disableWorker?: boolean;
-  // optionally specify for which queues to start a worker for
-  // in case not all queues should be worked on
+
+  /**
+   * Specify for which queues to start a worker for.
+   *
+   * Defaultly for every queue added in the `queues` parameter
+   */
   workerQueues?: string[];
+
+  /**
+   * Default worker options which are applied to every worker
+   *
+   * Can be extended/overridden by `workerOptions`
+   */
+  defaultWorkerOptions?: WorkerOptions;
+
+  /**
+   * Specify additional worker options by queue name
+   */
+  workerOptions?: Record<string, WorkerOptions>;
 };
 
 declare global {

package/src/contracts/JobMethods.ts

@@ -1,3 +1,5 @@
-export interface JobMethods {
-  handle(payload: unknown): unknown;
+import {Job} from "bullmq";
+
+export interface JobMethods<DataType = unknown, ReturnType = unknown> {
+  handle(payload: DataType, job: Job<DataType, ReturnType>): ReturnType | Promise<ReturnType>;
 }

package/src/decorators/JobController.spec.ts

@@ -1,7 +1,10 @@
-import {JobController} from "./JobController";
+import {FallbackJobController, JobController} from "./JobController";
 import {Store} from "@tsed/core";
+import {GlobalProviders} from "@tsed/di";
 
 describe("JobController", () => {
+  afterEach(() => GlobalProviders.clear());
+
   it("should set the proper store data", () => {
     @JobController("testjob")
     class TestJob {}
@@ -48,3 +51,43 @@ describe("JobController", () => {
     expect(store);
   });
 });
+
+describe("FallbackJobController", () => {
+  afterEach(() => GlobalProviders.clear());
+
+  describe("with queue", () => {
+    it("should set the proper store data", () => {
+      @FallbackJobController("default")
+      class FallbackJob {}
+
+      const store = Store.from(FallbackJob).get("bullmq");
+      expect(store.queue).toBe("default");
+
+      const fallbackControllerForQueue = GlobalProviders.get("bullmq.fallback-job.default");
+      expect(fallbackControllerForQueue).not.toBeUndefined();
+      expect(fallbackControllerForQueue.type).toEqual("bullmq:fallback-job");
+      expect(fallbackControllerForQueue.useClass).toEqual(FallbackJob);
+
+      const fallbackController = GlobalProviders.get("bullmq.fallback-job");
+      expect(fallbackController).toBeUndefined();
+    });
+  });
+
+  describe("without queue", () => {
+    it("should set the proper store data", () => {
+      @FallbackJobController()
+      class FallbackJob {}
+
+      const store = Store.from(FallbackJob).get("bullmq");
+      expect(store.queue).toBeUndefined();
+
+      const fallbackController = GlobalProviders.get("bullmq.fallback-job");
+      expect(fallbackController).not.toBeUndefined();
+      expect(fallbackController.type).toEqual("bullmq:fallback-job");
+      expect(fallbackController.useClass).toEqual(FallbackJob);
+
+      const fallbackControllerForQueue = GlobalProviders.get("bullmq.fallback-job.default");
+      expect(fallbackControllerForQueue).toBeUndefined();
+    });
+  });
+});

package/src/decorators/JobController.ts

@@ -15,3 +15,15 @@ export function JobController(name: string, queue: string = "default", opts: Job
     })
   );
 }
+
+export function FallbackJobController(queue?: string) {
+  return useDecorators(
+    StoreMerge("bullmq", {
+      queue
+    }),
+    Injectable({
+      provide: "bullmq.fallback-job" + (queue ? `.${queue}` : ""),
+      type: "bullmq:fallback-job"
+    })
+  );
+}

package/src/dispatchers/JobDispatcher.spec.ts

@@ -9,7 +9,7 @@ import {instance, mock, verify, when, objectContaining} from "ts-mockito";
   backoff: 69
 })
 class ExampleTestJob implements JobMethods {
-  handle(payload: { msg: string }) {}
+  handle(payload: {msg: string}) {}
 }
 
 @JobController("queue-not-configured", "not-configured")
@@ -20,20 +20,20 @@ class NotConfiguredQueueTestJob implements JobMethods {
 describe("JobDispatcher", () => {
   it("should throw an exception when a queue is not configured", () => {
     const injector = mock(InjectorService);
-    when(injector.getMany("bullmq:queue")).thenReturn([]);
+    when(injector.get("bullmq.queue.not-configured")).thenReturn();
 
     const dispatcher = new JobDispatcher(instance(injector));
 
     expect(dispatcher.dispatch(NotConfiguredQueueTestJob)).rejects.toThrow(new Error("Queue(not-configured) not defined"));
-    verify(injector.getMany("bullmq:queue")).once();
+    verify(injector.get("bullmq.queue.not-configured")).once();
   });
 
-  it("should dispatch job", async () => {
+  it("should dispatch job as type", async () => {
     const injector = mock(InjectorService);
     const queue = mock(Queue);
     when(queue.name).thenReturn("default");
 
-    when(injector.getMany("bullmq:queue")).thenReturn([instance(queue)]);
+    when(injector.get("bullmq.queue.default")).thenReturn(instance(queue));
 
     const dispatcher = new JobDispatcher(instance(injector));
 
@@ -50,16 +50,50 @@ describe("JobDispatcher", () => {
     ).once();
   });
 
-  it('should overwrite job options defined by the job', async () => {
+  it("should dispatch job as options", async () => {
+    const injector = mock(InjectorService);
+    const queue = mock(Queue);
+    when(queue.name).thenReturn("special");
+
+    when(injector.get("bullmq.queue.special")).thenReturn(instance(queue));
+
+    const dispatcher = new JobDispatcher(instance(injector));
+
+    await dispatcher.dispatch(
+      {
+        queue: "special",
+        name: "some-name"
+      },
+      {msg: "hello test"}
+    );
+
+    verify(queue.add("some-name", objectContaining({msg: "hello test"}), objectContaining({}))).once();
+  });
+
+  it("should dispatch job as string", async () => {
+    const injector = mock(InjectorService);
+    const queue = mock(Queue);
+    when(queue.name).thenReturn("default");
+
+    when(injector.get("bullmq.queue.default")).thenReturn(instance(queue));
+
+    const dispatcher = new JobDispatcher(instance(injector));
+
+    await dispatcher.dispatch("some-name", {msg: "hello test"});
+
+    verify(queue.add("some-name", objectContaining({msg: "hello test"}), objectContaining({}))).once();
+  });
+
+  it("should overwrite job options defined by the job", async () => {
     const injector = mock(InjectorService);
     const queue = mock(Queue);
     when(queue.name).thenReturn("default");
 
-    when(injector.getMany("bullmq:queue")).thenReturn([instance(queue)]);
+    when(injector.get("bullmq.queue.default")).thenReturn(instance(queue));
 
     const dispatcher = new JobDispatcher(instance(injector));
 
-    await dispatcher.dispatch(ExampleTestJob, {msg: "hello test"}, {backoff: 42, jobId: 'ffeeaa'});
+    await dispatcher.dispatch(ExampleTestJob, {msg: "hello test"}, {backoff: 42, jobId: "ffeeaa"});
 
     verify(
       queue.add(
@@ -67,22 +101,22 @@ describe("JobDispatcher", () => {
         objectContaining({msg: "hello test"}),
         objectContaining({
           backoff: 42,
-          jobId: 'ffeeaa'
+          jobId: "ffeeaa"
         })
       )
     ).once();
-  })
+  });
 
-  it('should keep existing options and add new ones', async () => {
+  it("should keep existing options and add new ones", async () => {
     const injector = mock(InjectorService);
     const queue = mock(Queue);
     when(queue.name).thenReturn("default");
 
-    when(injector.getMany("bullmq:queue")).thenReturn([instance(queue)]);
+    when(injector.get("bullmq.queue.default")).thenReturn(instance(queue));
 
     const dispatcher = new JobDispatcher(instance(injector));
 
-    await dispatcher.dispatch(ExampleTestJob, {msg: "hello test"}, {jobId: 'ffeeaa'});
+    await dispatcher.dispatch(ExampleTestJob, {msg: "hello test"}, {jobId: "ffeeaa"});
 
     verify(
       queue.add(
@@ -90,7 +124,7 @@ describe("JobDispatcher", () => {
         objectContaining({msg: "hello test"}),
         objectContaining({
           backoff: 69,
-          jobId: 'ffeeaa'
+          jobId: "ffeeaa"
         })
       )
     ).once();

package/src/dispatchers/JobDispatcher.ts

@@ -1,25 +1,61 @@
+/* eslint-disable require-await */
 import {InjectorService, Service} from "@tsed/di";
 import {JobMethods, type JobStore} from "../contracts";
 import {Store, Type} from "@tsed/core";
 import {Job as BullMQJob, JobsOptions, Queue} from "bullmq";
+import type {JobDispatcherOptions} from "./JobDispatcherOptions";
 
 @Service()
 export class JobDispatcher {
   constructor(private readonly injector: InjectorService) {}
 
-  // eslint-disable-next-line require-await
-  public async dispatch<T extends JobMethods>(job: Type<T>, payload: Parameters<T["handle"]>[0] = {}, options: JobsOptions = {}): Promise<BullMQJob> {
-    const store = Store.from(job).get<JobStore>("bullmq");
+  public async dispatch<T extends JobMethods>(
+    job: Type<T>,
+    payload?: Parameters<T["handle"]>[0],
+    options?: JobsOptions
+  ): Promise<BullMQJob>;
+  public async dispatch<T = any>(job: JobDispatcherOptions, payload?: T, options?: JobsOptions): Promise<BullMQJob>;
+  public async dispatch<T = any>(job: string, payload?: T, options?: JobsOptions): Promise<BullMQJob>;
+  public async dispatch(job: Type | JobDispatcherOptions | string, payload: any, options: JobsOptions = {}): Promise<BullMQJob> {
+    const {queueName, jobName, defaultJobOptions} = this.resolveDispatchArgs(job);
 
-    const queue = this.injector.getMany<Queue>("bullmq:queue").find((queue) => queue.name === store.queue);
+    const queue = this.injector.get<Queue>(`bullmq.queue.${queueName}`);
 
     if (!queue) {
-      throw new Error(`Queue(${store.queue}) not defined`);
+      throw new Error(`Queue(${queueName}) not defined`);
     }
 
-    return queue.add(store.name, payload, {
-      ...store.opts,
-      ...options,
+    return queue.add(jobName, payload, {
+      ...defaultJobOptions,
+      ...options
     });
   }
+
+  private resolveDispatchArgs(job: Type | JobDispatcherOptions | string) {
+    let queueName: string;
+    let jobName: string;
+    let defaultJobOptions: JobsOptions | undefined;
+
+    if (typeof job === "function") {
+      // job is passed as a Type
+      const store = Store.from(job).get<JobStore>("bullmq");
+      queueName = store.queue;
+      jobName = store.name;
+      defaultJobOptions = store.opts;
+    } else if (typeof job === "object") {
+      // job is passed as JobDispatcherOptions
+      queueName = job.queue;
+      jobName = job.name;
+    } else {
+      // job is passed as a string
+      queueName = "default";
+      jobName = job;
+    }
+
+    return {
+      queueName,
+      jobName,
+      defaultJobOptions
+    };
+  }
 }

package/src/dispatchers/JobDispatcherOptions.ts

@@ -0,0 +1,4 @@
+export interface JobDispatcherOptions {
+  queue: string;
+  name: string;
+}

package/src/dispatchers/index.ts

@@ -3,3 +3,4 @@
  */
 
 export * from "./JobDispatcher";
+export * from "./JobDispatcherOptions";

package/src/index.ts

@@ -8,3 +8,4 @@ export * from "./contracts/JobMethods";
 export * from "./contracts/JobStore";
 export * from "./decorators/JobController";
 export * from "./dispatchers/JobDispatcher";
+export * from "./dispatchers/JobDispatcherOptions";